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

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

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 command.

    This module is compatible with both cmd.exe and 4nt/tcc shells.

            [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]

            [TCC/TCMD/4NT]
            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 the bash compatible character expansion and globbing available,
    including meta-notations a{b,c}*.

    String/character expansion:

      '...' => literal (no escapes and no globbing within quotes)

      $'...' => ANSI C string escapes (\a, \b, \e, \f, \n, \r, \t, \v, \\,
      \', \n{1,3}, \xh{1,2}, \cx; all other \<x> =>\<x>), no globbing within
      quotes

      "..." => literal (no escapes and no globbing within quotes)

      $"..." => same as "..."

      $( ... ) => subshell expansion

      $("...") => subshell expansion

    Globbing:

      \ Quote the next metacharacter

      [] Character class

      {} Multiple pattern

      * Match any string of characters

      ? Match any single character

      ~ Expand to current user home directory

      ~<name> Expands to user <name> home directory for any defined user [
      ONLY if {Win32, Win32::Security::SID, Win32::TieRegistry} are
      installed; o/w no expansion => pull off any leading non-quoted ~[name]
      (~ followed by word characters) => replace with home dir of [name] if
      exists, otherwise replace the characters)

      ~<text> Expands to value of environment variable "~<text>" (if
      defined) [OVERRIDES ~<name> expansion] #?? verify and document which
      has priority

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

    The standard make idiom ( "perl Makefile.PL" -> "make" -> "make test" ->
    "make install") is also available (though deprecated) via a Makefile.PL
    passthrough script. Module::Build is still ultimately required for
    installation, and 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).

RATIONALE
    Attempts were made using Win32::API and Inline::C.

    Win32::API attempt (causes 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 causes a GPF and Inline::C is very brittle on
    Win32 systems (not compensating for paths with embedded strings).

    See URLref: http://www.perlmonks.org/?node_id=625182 for a more full
    explanation of the problem and initial attempts at a solution.

DEPENDENCIES
    None.

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.

