/*
 * $Id$
 */

/*  $DOC$
 *  $TEMPLATE$
 *     Document
 *  $NAME$
 *      Command line utility
 *  $CATEGORY$
 *      Document
 *  $SUBCATEGORY$
 *      Compiler
 *  $ONELINER$
 *      Compiler Options
 *  $DESCRIPTION$
 *      This spec goes for CLIPPERCMD, HARBOURCMD, Harbour compiler and
 *      #pragma directives in the source code.
 *
 *      The command line always overrides the envvar.
 *
 *      Note that some switches are not accepted in envvar, some others in
 *      #pragmas.
 *
 *      First the parser should start to step through all the tokens in the
 *      string separated by whitespace. (or just walk through all argv[])
 *
 *      1.) If the token begins with "-", it should be treated as a new style
 *      switch.
 *
 *      One or more switch characters can follow this. The "-" sign inside
 *      the token will turn off the switch.
 *
 *      If the switch has an argument all the following characters are
 *      treated as part of the argument.
 *
 *      The "/" sign has no special meaning here.
 *
 *        <table>
 *        Switch                  Result option
 *
 *        -wn                     ( W N )
 *        -w-n                    ( !W N )
 *        -wi/harbour/include/    ( W I=/harbour/include/ )
 *        -wi/harbour/include/n   ( W I=/harbour/include/n )
 *        -wes0n                  ( W ES=0 N )
 *        -wen                    ( W [invalid switch: e] N )
 *        -wesn                   ( W ES=default(0) N )
 *        -wses                   ( W S ES=default(0) )
 *        -wess                   ( W ES=default(0) S )
 *        -                       ( [invalid switch] )
 *        -w-n-p                  ( !W !N P )
 *        -w-n-p-                 ( !W !N !P )
 *        -w- -w -w-              ( finally: !W )
 *          </table>
 *
 *      2.) If the token begins with "/", it should be treated as a compatibility
 *      style switch.
 *
 *      The parser scans the token for the next "/" sign or EOS and treats
 *      the resulting string as one switch.
 *
 *      This means that a switch with an argument containing "/" sign has
 *      some limitations. This may be solved by allowing the usage of quote
 *      characters. This is mostly a problem on systems which use "/" as
 *      path separator.
 *
 *      The "-" sign has no special meaning here, it can't be used to
 *      disable a switch.
 *
 *         <table>
 *        Switch               Result option
 *
 *        /w/n                 ( W N )
 *        /wo/n                ( [invalid switch: wo] N )
 *        /ihello/world/       ( I=hello [invalid switch: world] [invalid switch: /] )
 *        /i"hello/world/"/w   ( I=hello/world/ W )
 *        /ihello\world\       ( I=hello\world\ )
 *      </table>
 *
 *      3.) If the token begins with anything else it should be skipped.
 *
 *      The Harbour switches are always case insensitive.
 *
 *      In the Harbour commandline the two style can be used together:  </par>
 *      harbour -wnes2 /gc0/q0 -iC:\hello
 *
 *      Exceptions:
 *
 *      - Handlig of the /CREDIT undocumented switch on Harbour command line
 *      is unusual, check the current code for this.
 *
 *      - The CLIPPER, HARBOUR and Harbour application command line parsing
 *      is a different beast, see cmdarg.c for a NOTE.
 *
 *      Notes:
 *
 *      - All occurences where a path is accepted, Harbour should handle the
 *        quote char to specify path containing space, negative sign, slash,
 *        or any other chars with special meaning.
 *
 *        /i"C:/hello/"   </par>
 *        -i"C:/hello-n"  </par>
 *        /i"C:/Program Files/" </par>
 *        -i"C:/Program Files/" </par>
 *
 *      <fixed>
 *        Just some examples for the various accepted forms:
 *        //F20 == /F20 == F20 == F:20 == F20X
 *        //TMPPATH:C:\hello
 *        F20//TMPPATH:/temp///F:30000000 NOIDLE
 *        F0NOIDLEX10
 *        SQUAWKNOIDLE
 *         </fixed>
 *        "//" should always be used on the command line.
 *  $SEEALSO$
 *      Compiler Options
 *  $END$
 */