CLI Method add

add

Signature

call cli%add(self, pref, group, group_index, switch, switch_ab, help, required, &
             positional, position, hidden, act, def, nargs, choices, exclude, envvar, error)

Meaning

Add new CLA to your CLI. All dummy arguments are optionals.

Dummy arguments

character(*), optional, intent(in)  :: pref        !< Prefixing string.
character(*), optional, intent(in)  :: group       !< Name of the grouped CLAs.
integer(I4P), optional, intent(in)  :: group_index !< Index of the grouped CLAs.
character(*), optional, intent(in)  :: switch      !< Switch name.
character(*), optional, intent(in)  :: switch_ab   !< Abbreviated switch name.
character(*), optional, intent(in)  :: help        !< Help message describing the CLA.
logical,      optional, intent(in)  :: required    !< Flag for set required argument.
logical,      optional, intent(in)  :: positional  !< Flag for checking if CLA is a positional or a named CLA.
integer(I4P), optional, intent(in)  :: position    !< Position of positional CLA.
logical,      optional, intent(in)  :: hidden      !< Flag for hiding CLA, thus it does not compare into help.
character(*), optional, intent(in)  :: act         !< CLA value action.
character(*), optional, intent(in)  :: def         !< Default value.
character(*), optional, intent(in)  :: nargs       !< Number of arguments consumed by CLA.
character(*), optional, intent(in)  :: choices     !< List of allowable values for the argument.
character(*), optional, intent(in)  :: exclude     !< Switch name of the mutually exclusive CLA.
character(*), optional, intent(in)  :: envvar      !< Environment variable from which take value.
integer(I4P), optional, intent(out) :: error       !< Error trapping flag.

The default values of them are:

pref=''
help='Undocumented argument'
required=.false.
positional=.false.
position=0
act='STORE'
m_exclude=''

All other arguments that are not passed are left unset (or not allocated).

The following rules apply:

• pref string is used as prefixing string for any messages on standard out/err;
• if group (or group_index) is not passed, the CLA is added to default (not named) group (i.e. the group 0).
• if group is not currently defined, but it is passed, it is created on the fly before adding the CLA; this is an inderect method for creating a group;
• the switch or switch_ab must be always passed for non positional CLA. If one of them is omitted it is set equal to one passed.
• for a positional CLA the position argument must be passed.
• the possible actions of CLA are (all actions definitions are case insensitive):
  • act=store, the CLA stores value(s) that must be passed after the CLA switch for named CLA;
  • act=store*, the CLA stores value (only single value) that can be passed after the CLA switch name; the following rules hold:
    • it is not allowed for positional CLA;
    • it is not allowed for list valued CLA, i.e. passing nargs;
    • it is not allowed for environment variable CLA;
    • a default value is mandatory;
  • act=store_true, the CLA stores .true.;
  • act=store_false, the CLA stores .false.;
  • act=print_help, the CLA triggers the printing of the help message that is built with the help messages of all defined CLAs and the help message of CLI;
  • act=print_version, the CLA triggers the printing the program version; if the version is not defined when the CLI is initialized the message will contain version unknown.
• if required is set to .false. a default value must be defined, even if it is a null string;
• no matter the type of CLA value is (real, integer, etc...) the definition of default value for an optional CLA must be always a string, e.g. def='1' or def='1.0'; the actual type casting is performed when the CLA value is gotten by means of the get method: the type casting is performed by means of the actual type (and kind) of the variable used for storing CLA value;
• choices must be a comma-separated list of allowable values and if it has been specified the passed value is checked to be consistent with this list when the get method is invoked: an error code is returned and if the value is not into the specified range an error message is printed to stderr. However the value of CLA is not modified and it is equal to the passed value;
• nargs must be used for list-valued argument; the number of elements of the list can be:
  • compiletime determined if nargs is set equal to a positive integer, e.g. nargs='3'; in this case the get method must be used to retrieve the CLA value and it must be invoked with an allocated (or static/automatic) array;
  • runtime determined; in this case the get_varying method must be used to retrieve the CLA value and it must be invoked with an allocatable array; this case is selected if:
    • nargs='+' meaning that the list must have at least 1 element;
    • nargs='*' meaning that the list can have any size, it can be even empty.
• if envvar=name_of_your_environment_variable is passed the CLA will try to infer the CLA value by the following logic:
  • if a value is passed after the CLA name it overrides the default value and the eventual environment value;
  • if no value is passed after the CLA name the value is first retrieved from the eventual environment value and if it is not set it is obtained from an eventual default value;
  • an envvar CLA must be a named CLA;
  • an envvar CLA must has action=store;
  • an envvar CLA must not be a list valued CLA;
• if hidden=.true. is passed the CLA will not be printed into the help/usage messages;

When a CLA is added a self-consistency-check is performed, e.g. it is checked if an optional CLA has a default value or if one of position and switch has been passed. In case the self-consistency-check fails an error code is returned and an error message is printed to stderr.

Usage

Must be used for add new CLA to CLI

use flap

type(command_line_interface):: cli
integer::                      error

call cli%init(...)
call cli%add(switch='--integer',                   &
             switch_ab='-i',                       &
             help='Integer input with fixed range',&
             required=.false.,                     &
             act='store',                          &
             def='1',                              &
             choices='1,3,5',                      &
             exclude='-ie',                        &
             error=error)
call cli%add(switch='--dynamic-list',                   &
             switch_ab='-dl',                           &
             help='Runtime varying integer input list', &
             required=.false.,                          &
             act='store',                               &
             nargs='*',                                 &
             def='1 2 3',                               &
             error=error)
call cli%add(switch='--list',                    &
             switch_ab='-l',                     &
             help='Prefixed integer input list', &
             required=.false.,                   &
             act='store',                        &
             nargs='4',                          &
             def='1 2 3 4',                      &
             error=error)

For trapping errors the dummy argument error can be used. The complete errors values are listed in Errors-codes.