/*
 * $Id: cmdline.txt 9312 2008-09-05 00:08:34Z vszakats $
 */

Harbour switch handling spec
============================

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.

  -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 )

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.

  /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\ )

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

  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

  "//" should always be used on the command line.

Viktor Szakats <viktor.szakats@syenar.hu>
