[UP]


Manual Reference Pages  - commandline (3)

NAME

commandline(3f) - [ARGUMENTS:M_CLI] command line argument parsing (LICENSE:PD)

CONTENTS

Synopsis
Description
Options
Returns
Author
License

SYNOPSIS

function commandline(definition,name,noquote) result(string)

    character(len=*),intent(in),optional  :: definition
    character(len=*),optional :: name
    logical,optional :: noquote
    character(len=:),allocatable :: string

DESCRIPTION

To use the routine first define a NAMELIST group called ARGS.

This routine leverages NAMELIST groups to do the conversion from strings to numeric values required by other command line parsers.

The example program shows how simple it is to use. Add a variable to the NAMELIST and the prototype and it automatically is available as a value in the program.

There is no need to convert from strings to numeric values in the source code. Even arrays and user-defined types can be used, complex values can be input ... just define the variable in the prototype and add it to the NAMELIST definition.

Note that since all the arguments are defined in a NAMELIST group that
config files can easily be used for the same options.
  Just create a NAMELIST input file and read it.
NAMELIST syntax can vary between different programming environments. Currently, this routine has only been tested using gfortran 7.0.4; and requires at least Fortran 2003.

For example:

       program demo_commandline
          use M_CLI,  only : unnamed, commandline, check_commandline
          implicit none
          integer                      :: i
          character(len=255)           :: message ! for I/O error
          character(len=:),allocatable :: readme  ! updated namelist
          integer                      :: ios

! declare a namelist real :: x, y, z, point(3), p(3) character(len=80) :: title logical :: l, l_ equivalence (point,p) namelist /args/ x,y,z,point,p,title,l,l_

! Define the prototype ! o All parameters must be listed with a default value. ! o logicals should be specified with a value of F or T. ! o string values must be double-quoted. ! o lists must be comma-delimited. No spaces allowed in lists. ! o all long names must be lowercase. An uppercase short name ! -A maps to variable A_ ! o if variables are equivalenced only one should be used on ! the command line character(len=*),parameter :: cmd=’& & -x 1 -y 2 -z 3 & & --point -1,-2,-3 & & --title "my title" & & -l F -L F’ ! reading in a NAMELIST definition defining the entire NAMELIST ! now get the values from the command prototype and ! command line as NAMELIST input readme=commandline(cmd) read(readme,nml=args,iostat=ios,iomsg=message) call check_commandline(ios,message) ! all done cracking the command line

! use the values in your program. write(*,nml=args) ! the optional unnamed values on the command line are ! accumulated in the character array "UNNAMED" if(size(unnamed).gt.0)then write(*,’(a)’)’files:’ write(*,’(i6.6,3a)’)(i,’[’,unnamed(i),’]’,i=1,size(unnamed)) endif end program demo_commandline

OPTIONS

DESCRIPTION
  composed of all command arguments concatenated into a Unix-like command prototype string.
o all keywords get a value.
o logicals must be set to F or T.
o strings MUST be delimited with double-quotes and must be at least one space. Internal double-quotes are represented with two double-quotes
o lists of values should be comma-delimited. No spaces are allowed in lists of numbers.
o long names (--keyword) should be all lowercase
o short names (-letter) that are uppercase map to a NAMELIST variable called "letter_", but lowercase short names map to NAMELIST name "letter".
o the values follow the rules for NAMELIST values, so "-p 2*0" for example would define two values.
DESCRIPTION is pre-defined to act as if started with the reserved options ’--usage F --help F --version F’. The --usage option is processed when the check_commandline(3f) routine is called. The same is true for --help and --version if the optional help_text and version_text options are provided.

NOQUOTE
  If .TRUE., then a comma is implicitly assumed a value separator in unquoted strings on the command line, so that an array of strings not containing commas in the values can be specified as A,B,C instead of ’"A","B","C"’. Note that this means if a non-array string value is specified that contains a comma, the scalar value would now need quoted, as in ’"yesterday, today or tomorrow"’. So if you are not using string arrays this should be left off.

RETURNS

STRING The output is a NAMELIST string than can be read to update the NAMELIST "ARGS" with the keywords that were supplied on the command line.
When using one of the Unix-like command line forms note that (subject to change) the following variations from other common command-line parsers:
 
o long names do not take the --KEY=VALUE form, just --KEY VALUE; and long names should be all lowercase and always more than one character.
o duplicate keywords are replaced by the rightmost entry
o numeric keywords are not allowed; but this allows negative numbers to be used as values.
o mapping of short names to long names is via an EQUIVALENCE. specifying both names of an equivalenced keyword will have undefined results (currently, their alphabetical order will define what the Fortran variable values become).
o short keywords cannot be combined. -a -b -c is required, not -abc even for Boolean keys.
o shuffling is not supported. Values must follow their keywords.
o if a parameter value of just "-" is supplied it is converted to the string "stdin".
o if the keyword "--" is encountered the rest of the command arguments go into the character array "UNUSED".
o values not matching a keyword go into the character array "UNUSED".
o short-name parameters of the form -LETTER VALUE map to a NAMELIST name of LETTER_ if uppercase

AUTHOR

John S. Urban, 2019

LICENSE

Public Domain


commandline (3) March 11, 2021
Generated by manServer 1.08 from 70aa71d1-6a15-4bb8-a451-ac077f6e4e13 using man macros.