NAME

Filesys::CygwinPaths - Perl extension to get various conversions of path specifications in the Cygwin port of Perl.

VERSION

$VERSION = '0.02' ;

SYNOPSIS

    use Filesys::CygwinPaths;
    PATHS_protocol('cyg_win32');
        my $HOME = $ENV{'HOME'};

    my @pics_to_ogle = glob("$HOME/mypics/*.jpg");
        foreach my $pic (@pics_to_ogle) {
           system('C:/Applications/IrfanView/iview32',
                vetted_path($pic), '/bf /pos=(0,0) /one', "/title=$pic")
         or die "No fun today!";
    }
        system('C:/Applications/IrfanView/iview32', '/killmesoftly');
        
   OR

    use Filesys::CygwinPaths ':all';
        my $windows_groks_this = fullwin32path("$ENV{HOME}");
        my $posix_style = fullposixpath($ENV{'USERPROFILE'});
        if(posixpath($windows_groks_this) ne $posix_style) {
           print "You don't keep your bash HOME in your NT Profile dir, huh?\n";
    }

DESCRIPTION

Filesys::CygwinPaths is a Cygwin-specific module created to ease the author's occasional pique over the little quirks that come up with using Perl on Cygwin. The subroutines it exports allow various kinds of path conversions to be made in a fairly concise, simple, procedural manner. At the present time the module does not have an OO interface but one might be added in the future. The module can be used according to two diffent approaches, which are outlined below.

Note: Hopefully it is evident that the module can be neither built nor used on any platform besides Perl built for Cygwin, and there would be no reason to want to do so.

Usage Styles

Two slightly different ways of using Filesys::CygwinPaths are available. The first, and recommended, way is to tell Perl once and for all (for the duration of your script) what protocol you need to use in conversing with, say external non-Cygwin applications. To do this, say something like:

<use Filesys::CygwinPaths;> <PATHS_protocol( 'cyg_mixed' );> <my $own_name = vetted_path($0);> <print "I am $own_name, how are you today?\n";>

And that will set the protocol to cyg_mixed for the duration of the script. The 3 recognized settings for PATHS_protocol() are:

<cyg_mixed> ( like: <C:/foobar/sugarplum/fairy.txt> ) <cyg_win32> ( like: <C:\foobar\sugarplum\fairy.txt> ) <cyg_posix> ( like: </cygdrive/c/sugarplum/fairy.txt> )

Alternatively you might prefer the more specific and elaborate full set of subroutines to be made available to you (:all). These can be called by name to get the specific translation protocol you desire. Listed below.

vetted_path($path_in)

make any translations necessary to transform the path argument according to the setting of the global (Filesysy::CygwinPaths) variable PATHS_PROTOCOL. If this variable is not already set when vetted_path() is called, it will set to the default of cyg_mixed and complain a little at you. Set the script-wide protocol you desire for vetted_path() to use by

        (a) setting PATHS_PROTOCOL directly in your script

(not my, it is a variable in the Filesys::CygwinPaths namespace which is imported by default, it must therefore not be a lexical in your script or will have no effect).

    (b) calling the subroutine C<PATHS_protocol> with the desired value.

PATHS_protocol(<style>)

set or query the current protocol under which vetted_path will return a path spec.

posixpath($path_in)

return the POSIX-style path spec (filename) for the given argument. If the argument is a relative path, returns a relative path.

win32path($path_in)

return the Win32 (Microsoft Windows standard) style path spec for the given argument. If the argument is a relative path, returns a relative path.

fullposixpath($path_in)

return the fully-qualified (absolute) path spec (filename) for the given argument, in POSIX-style.

fullwin32path($path_in)

return the fully-qualified path spec in Windows style.

Notes on the XS programming (C interface)

TODO.

• Another way to do the call to the xs interface would have been, maybe:

   sub conv_to_win32_path {
     my $in= shift(@_);
     my $out= "\0" x PATH_MAX();
     cygwin_conv_to_win 32_path($in,$out);
     return $out;
   }

BUGS

Perl does not know how to interpret the ~/ shell abbreviation for the login user's HOME directory (it is bash or another POSIX-y shell that does this); therefore do not use ~/ in args to any of the functions. Use $ENV{HOME} instead.

SEE ALSO

File::Spec, File::Spec::Unix, File::Basename, File::PathConvert, Env.

CREDITS

Tye McQueen for his XSeedingly generous help with the C interface work for this module. ;-)

Kazuko Andersen for her patience and for bringing food so I could finish working on this module ;-).

AUTHOR

Soren (Michael) Andersen (CPAN id SOMIAN), <somian@pobox.com>.

COPYRIGHT AND DISCLAIMER

This program is Copyright 2002 by Soren Andersen. This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License or the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

If you do not have a copy of the GNU General Public License write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

cpanm Filesys::CygwinPaths

perl -MCPAN -e shell
install Filesys::CygwinPaths