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

VERSION
    our $VERSION = qw$Version: 0.5.8.124 $[1]

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
    fully implemented, 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 can be used to add 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"'              [would otherwise FAIL]

  `4NT/TCC/TCMD'
        alias type=call xx type
        type [a-c]*.pl
        .
        alias perl=call xx perl
        perl -e 'print "test"'              [would otherwise FAIL]

    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 (see NOTE); no globbing within quotes
      $"..."   literal (no escapes and no globbing within quotes) [same as "..."]
      $( ... ) subshell expansion [subshell commandline is _not_ automatically expanded]
      $("...") subshell expansion (quotes removed) [subshell commandline is _not_ automatically expanded]

    NOTE: ANSI C string escapes are (\a, \b, \e, \f, \n, \r, \t, \v, \\, \',
    \[0-9]{1,3}, \x[0-9a-fA-f]{1,2}, \c[@A-Z[\\\]\^_`]; all other escaped
    characters are left in place without transformation (\<x> => \<x>).

    URLref: [bash ANSI-C Quoting]
    http://www.gnu.org/software/bash/manual/html_node/ANSI_002dC-Quoting.htm
    l @@ http://www.webcitation.org/66M8skmP8

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

    The multiple pattern 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 it is
    deprecated):

        perl Makefile.PL
        make
        make test
        make install

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

    Note that the Makefile.PL script is just a pass-through, and
    Module::Build is still ultimately required for installation. Makefile.PL
    will throw an exception if Module::Build is missing from your current
    installation. `cpan' will notify the user of the build prerequisites
    (and install them for the build, if it is setup to do so [see the cpan
    configuration option `build_requires_install_policy']).

    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 that 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' was 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::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.

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 Perl Artistic License v2.0 (see
    http://opensource.org/licenses/artistic-license-2.0.php).

DISCLAIMER OF WARRANTY
      THIS PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS"
      AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF
      MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT
      ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED
      BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF
      THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

      [REFER TO THE FULL LICENSE FOR EXPLICIT DEFINITIONS OF ALL TERMS.]

ACKNOWLEDGEMENTS
    Thanks to BrowserUK and syphilis (aka SISYPHUS on CPAN) for some helpful
    ideas (including an initial XS starting point for the module) during a
    discussion on PerlMonks (see http://www.perlmonks.org/?node_id=625182).

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

