## arg - Arguments parser

### Module Description

The arg parser module implements a command line arguments parser. Due to the fact that the ANS standard does not specify words for arguments this module has a environmental dependency.

      Supported option formats:
         -v            short switch option
         -f a.txt      short option with parameter
         -vq           multiple short switch options
         --file=a.txt  long option with parameter
         --verbose     long switch option
         --            stop parsing arguments

### Module Words

#### Global setting

arg.cols ( -- n )
  Value with the number of columns for parser output [def. 79]

#### Constants

arg.version-option ( -- n )
  Version option
arg.help-option ( -- n )
  Help option
arg.non-option ( -- n )
  Non option
arg.done ( -- n )
  Done parsing
arg.error ( -- n )
  Error in option

#### Argument parser structure

arg% ( -- n )
  Get the required space for an argument parser variable

#### Argument parser structure creation, initialisation and destruction

arg-init ( c-addr1 u1 c-addr2 u2 c-addr3 u3 c-addr4 u4 arg -- )
  Initialise the parser with the program name c-addr1 u1, the usage c-addr2 u2, the version c-addr3 u3 and general info c-addr4 u4
arg-(free) ( arg -- )
  Free the internal, private variables from the heap
arg-create ( c-addr1 u1 c-addr2 u2 c-addr3 u3 c-addr4 u4 "<spaces>name" -- ; -- arg )
  Create a named parser in the dictionary with the program name c-addr1 u1, the usage c-addr2 u2, the version c-addr3 u3 and general info c-addr4 u4
arg-new ( c-addr1 u1 c-addr2 u2 c-addr3 u3 c-addr4 u4 -- arg )
  Create a new parser on the heap with the program name c-addr1 u1, the usage c-addr2 u2, the version c-addr3 u3 and general info c-addr4 u4
arg-free ( arg -- )
  Free the parser from the heap

#### Default print words

arg-print-version ( arg -- )
  Print the version info
arg-print-help ( arg -- )
  Print the help info

#### Option words

arg-add-option ( char c-addr1 u1 c-addr2 u2 flag n arg -- )
  Add an option to the parser with the short option char, the long option c-addr1 u1, the description c-addr2 u2, the switch flag and the identifier n [id=4..]
arg-add-help-option ( arg -- )
  Add the default help option
arg-add-version-option ( arg -- )
  Add the default version option

#### Parser words

arg-parse ( arg -- c-addr u n | n )
  Parse the next command line argument, return the option identifier and optional the parameter

### Examples

    include ffl/arg.fs

    \ Test if the argument parser is implemented for the current forth Engine

    [DEFINED] a32.version [IF]

    \ Create an argument parser on the heap

    s" argparser"                       \ program name
    s" [OPTION] .. [FILES]"             \ program usage
    s" v1.0"                            \ program version
    s" Report bugs to bugs@bugs.com"    \ program extra info
    arg-new value arg1

    \ Add the default help and version options

    arg1 arg-add-help-option

    arg1 arg-add-version-option

    \ Variable for the verbose switch

    variable verbose  verbose off

    \ Add the -v/--verbose option switch

    char v                              \ Short option name
    s" verbose"                         \ Long option name
    s" activate verbose mode"           \ Description
    true                                \ Switch -> true
    4                                   \ Option id
    arg1 arg-add-option

    \ Add the -f/--file=FILE option

    char f                              \ Short option name
    s" file=FILE"                       \ Long option name
    s" set input file, any input file is allowed, as long as the description is multicolumn"  \ Description
    false                               \ Parameter -> false
    5                                   \ Option id
    arg1 arg-add-option

    : parse-options ( -- )
      BEGIN
        arg1 arg-parse                 \ parse the next argument
        dup arg.done <> over arg.error <> AND  \ stop parsing when ready or after an error
      WHILE

        CASE
          arg.help-option    OF arg1 arg-print-help             ENDOF  \ print default help info

          arg.version-option OF arg1 arg-print-version          ENDOF  \ print default version info

          arg.non-option     OF ." Non option found:" type cr   ENDOF  \ non option parameter, parameter on stack

          4                  OF verbose on ." Verbose is on" cr ENDOF  \ switch, no extra stack parameters

          5                  OF ." File parameter:" type cr     ENDOF  \ parameter switch, parameter on stack
        ENDCASE
      REPEAT

      arg.done = IF
        ." All options okee." cr
      ELSE
        ." Error in one of the options." cr
      THEN
    ;

    \ Parse the command line arguments

    parse-options

    \ Free the argument parser from the heap

    arg1 arg-free

    [THEN]

generated 03-Jun-2010 by ofcfrth-0.10.0