Module description

arg -- Arguments parser
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                                  

Global setting

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


arg.version-option ( -- n )
Version 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


\ ==============================================================================
\          arg_expl - the argument parser example in the ffl
\               Copyright (C) 2007  Dick van Oudheusden
\ This library is free software; you can redistribute it and/or
\ modify it under the terms of the GNU General Public
\ License as published by the Free Software Foundation; either
\ version 2 of the License, or (at your option) any later version.
\ This library is distributed in the hope that it will be useful,
\ but WITHOUT ANY WARRANTY; without even the implied warranty of
\ General Public License for more details.
\ You should have received a copy of the GNU General Public
\ License along with this library; if not, write to the Free
\ Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
\ ==============================================================================
\  $Date: 2007-12-09 07:23:14 $ $Revision: 1.5 $
\ ==============================================================================

include ffl/arg.fs

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

[DEFINED] arg.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"    \ 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 ( -- )
    arg1 arg-parse                 \ parse the next argument
    dup arg.done <> over arg.error <> AND  \ stop parsing when ready or after an error
    CASE    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
  arg.done = IF
    ." All options okee." cr
    ." Error in one of the options." cr

\ Parse the command line arguments


\ Free the argument parser from the heap

arg1 arg-free


Generated by fsdocgen 0.1.0