NAME
   Win32::CommandLine - Retrieve and reparse the Win32 command line

VERSION
   This document describes `Win32::CommandLine' ($Version: 0.4.4.269 $).

SYNOPSIS
           @ARGV = Win32::CommandLine::argv() if eval { require Win32::CommandLine; };

           _or_

           use Win32::CommandLine qw( command_line );
           my $commandline = command_line();
           ...

DESCRIPTION
   This module is used to reparse the Win32 command line, automating better
   quoting and globbing of the command line. Globbing is full bash POSIX
   compatible globbing, including subshell expansions. With the use of the
   companion script (`xx.bat') and `doskey' for macro aliasing, you can add
   full-fledged bash compatible string quoting/expansion and file globbing
   to *any* Win32 executable.

   This module is compatible with both `cmd.exe' and `4nt/tcc/tcmd' shells,
   and adds better parsing and bash glob expansion to *any* external
   command (by using the included `xx.bat' batch script).

 `CMD.EXE'

           doskey type=call xx type $*
           type [a-c]*.pl
           doskey perl=call xx perl $*
           perl -e 'print "test"'  [o/w FAILS without commandline reinterpretation]

 `4NT/TCC/TCMD'

           alias type=call xx type
           type [a-c]*.pl
           alias perl=call xx perl
           perl -e 'print "test"'  [o/w FAILS without commandline reinterpretation]

   Note that bash compatible character expansion and globbing is available,
   including glob meta-notations such as "`a[bc]*'" or
   "`foo.{bat,pl,exe,o}'".

 Command line string/character expansion

    '...'    literal (no escapes and no globbing within quotes)
    "..."    literal (no escapes and no globbing within quotes)
    $'...'   string including all ANSI C string escapes (\a, \b, \e, \f, \n, \r, \t, \v, \\, \', \n{1,3}, \xh{1,2}, \cx; all other escaped characters: \<x> =>\<x>); no globbing within quotes
    $"..."   literal (no escapes and no globbing within quotes) [same as "..."]
    $( ... ) subshell expansion [subshell commandline is _not_ expanded]
    $("...") subshell expansion (quotes removed) [subshell commandline is _not_ expanded]

 GLOB META CHARACTERS

     \       Quote the next metacharacter
     []      Character class
     {}      Multiple pattern
     *       Match any string of characters
     ?       Match any single character
     ~       Current user home directory
     ~USER   User NAME home directory
     ~TEXT   Environment variable named ~TEXT ( $ENV{~TEXT} ) [overrides ~USER expansion]

   The metanotation `a{b,c,d}e' is a shorthand for `abe ace ade'. Left to
   right order is preserved, with results of matches being sorted
   separately at a low level to preserve this order.

INSTALLATION
   To install this module, run the following commands:

           perl Build.PL
           ./Build
           ./Build test
           ./Build install

   Or, if you're on a platform (like DOS or Windows) that doesn't require
   the "./" notation, you can do this:

           perl Build.PL
           Build
           Build test
           Build install

   Alternatively, the standard make idiom is also available (though
   deprecated):

           perl Makefile.PL
           make
           make test
           make install

   (On Windows platforms you should use `nmake' instead.)

   The Makefile.PL script is just a pass-through, and Module::Build is
   still ultimately required for installation. Makefile.PL will offer to
   download and install Module::Build if it is missing from your current
   installation.

   PPM installation bundles should also be available in the standard PPM
   repositories (i.e. ActiveState, trouchelle.com
   [http://trouchelle.com/ppm/package.xml]).

   Note: On ActivePerl installations, "`./Build install'" will do a full
   installation using `ppm' (see ppm). During the installation, a PPM
   package is constructed locally and then subsequently used for the final
   module install. This allows for uninstalls (using "`ppm uninstall
   '*`MODULE'*" and also keeps local HTML documentation current.

RATIONALE
   This began as a simple need to work-around the less-than-stellar
   `COMMAND.COM'/`CMD.EXE' command line parser, just to accomplish more
   `correct` quotation interpretation. It then grew into a small odyssey:
   learning XS and how to create a perl module, learning the perl build
   process and creating a customized build script/environment, researching
   tools and developing methods for revision control and versioning,
   learning and creating perl testing processes, and finally learning about
   PAUSE and perl publishing practices. And, somewhere in the middle,
   adding some of the `bash' shell magic to the CMD shell (and,
   additionally, making it compatible with the excellent [and free] TCC-LE
   shell from JPSoft [find it at http://jpsoft.com/]).

   Some initial attempts were made using `Win32::API' and `Inline::C'. For
   example (`Win32::API' attempt [caused GPFs]):

       @rem = '--*-Perl-*--
       @echo off
       if "%OS%" == "Windows_NT" goto WinNT
       perl -x -S "%0" %1 %2 %3 %4 %5 %6 %7 %8 %9
       goto endofperl
       :WinNT
       perl -x -S %0 %*
       if NOT "%COMSPEC%" == "%SystemRoot%\system32\cmd.exe" goto endofperl
       if %errorlevel% == 9009 echo You do not have Perl in your PATH.
       if errorlevel 1 goto script_failed_so_exit_with_non_zero_val 2>nul
       goto endofperl
       @rem ';
       #!/usr/bin/perl -w
       #line 15
       #
       use Win32::API;
       #
       Win32::API->Import("kernel32", "LPTSTR GetCommandLine()");
       my $string = pack("Z*", GetCommandLine());
       #
       print "string[".length($string)."] = '$string'\n";
       # ------ padding --------------------------------------------------------------------------------------
       __END__
       :endofperl

   Unfortunately, `Win32::API' and `Inline::C' were shown to be too fragile
   at the time (in 2007). `Win32::API' caused occasional (but reproducible)
   GPFs, and `Inline::C' is very brittle on Win32 systems (not compensating
   for paths with embedded strings). [ See
   http://www.perlmonks.org/?node_id=625182 for a more full explanation of
   the problem and initial attempts at a solution. ]

   So, an initial XS solution was implemented. And from that point, the
   lure of `bash'-like command line parsing led inexorably to the full
   implementation. The parsing logic is unfortunately still complex, but
   seems to be holding up under testing.

DEPENDENCIES
   `Win32::CommandLine' requires `Carp::Assert' for internal error checking
   and warnings.

   The optional modules `Win32', `Win32::API', `Win32::Security::SID', and
   `Win32::TieRegistry' are recommended to allow full glob tilde expansions
   for user home directories (eg, `~administrator' expands to
   `C:\Users\Administrator'). Expansion of the single tilde (`~') has a
   backup implementation based on %ENV variables, and therefore will still
   work even without the optional modules.

AUTHOR
   Roy Ivy III <rivy[at]cpan[dot]org>

LICENSE AND COPYRIGHT
   Copyright (c) 2007-2009, Roy Ivy III <rivy[at]cpan[dot]org>. All rights
   reserved. This module is free software; you can redistribute it and/or
   modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY
   BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
   FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
   OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
   PROVIDE THE SOFTWARE ''AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER
   EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
   ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
   YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
   NECESSARY SERVICING, REPAIR, OR CORRECTION.

   IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
   REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
   TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
   CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
   SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
   RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
   FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
   SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
   DAMAGES.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.