Error Codes

Every FLAP method that can fail accepts an optional error integer argument, and prints its message on the error unit (standard error unless init(error_lun=...)). FLAP never stops the program on an error: the program decides.

call cli%parse(error=error)
if (error /= 0) stop 1, quiet=.true.   ! the message is already printed; nvfortran: call exit(1)

Code table

Every code is available as a named constant from the flap module, so programs can test for a specific condition without hard-coding numbers:

use flap, only : command_line_interface, ERROR_UNKNOWN, STATUS_PRINT_H

Negative values are statuses (FLAP did what was asked and the program should usually exit cleanly); positive values are errors. Existing values never change.

Code	Constant	Meaning	Typical cause	Class
-10	STATUS_CHECK	Command line valid	--check was passed (init(check_option=.true.)) and the command line is valid; in standalone mode the program ends with exit status 0
-9	STATUS_SCHEMA	JSON description printed	--schema was passed (init(schema_option=.true.)); in standalone mode the program ends with exit status 0
-8	STATUS_PRINT_MAN	Man page saved	--man was passed (init(man_option=.true.)); in standalone mode the program ends with exit status 0
-7	STATUS_INSTALL_COMPLETION	Completion script installed	--install-completion was passed (init(completion_options=.true.)); in standalone mode the program ends with exit status 0
-6	STATUS_SHOW_COMPLETION	Completion script printed	--show-completion was passed; in standalone mode the program ends with exit status 0
-5	STATUS_NO_ARGS	Help printed, no arguments	init(no_args_is_help=.true.) and no argument passed (or a command with no_args_is_help invoked alone); in standalone mode the program ends with exit status 2
-4	STATUS_ALTERNATE	An alternate action was passed	An option with act='alternate' (e.g. --list-models): value validation skipped, dispatch on is_passed; returned also in standalone mode
-3	STATUS_PRINT_M	Help written as Markdown	--markdown was passed; not a real error
-2	STATUS_PRINT_H	Help printed	--help / -h was passed; not a real error
-1	STATUS_PRINT_V	Version printed	--version / -v was passed; not a real error
0		Success	No error
1	ERROR_OPTIONAL_NO_DEF	Missing default for optional argument	Added required=.false. but omitted def=	definition
2	ERROR_REQUIRED_M_EXCLUDE	Required argument cannot use exclude	required=.true. combined with exclude=	definition
3	ERROR_POSITIONAL_M_EXCLUDE	Positional argument cannot use exclude	positional=.true. combined with exclude=	definition
4	ERROR_NAMED_NO_NAME	Named argument has no switch	Non-positional add called without switch=	definition
5	ERROR_POSITIONAL_NO_POSITION	Positional argument has no position	positional=.true. without position=	definition
6	ERROR_POSITIONAL_NO_STORE	Positional argument must use act='store'	Incompatible action for a positional CLA	definition
7	ERROR_NOT_IN_CHOICES	Value not in choices list	User supplied a value outside the allowed set	usage
8	ERROR_MISSING_REQUIRED	Required argument missing	A required=.true. argument was not passed	usage
9	ERROR_M_EXCLUDE	Two mutually exclusive arguments both passed	Both sides of an exclude= pair were given	usage
10	ERROR_CASTING_LOGICAL	Cast to logical failed	CLA value string cannot be parsed as logical	usage
11	ERROR_CHOICES_LOGICAL	choices not allowed for logical type	choices= used with a boolean argument	definition
12	ERROR_NO_LIST	Argument is not list-valued	get used with an array on a scalar argument	definition
13	ERROR_NARGS_INSUFFICIENT	Insufficient list arguments	nargs='N' but fewer than N values were passed	usage
14	ERROR_VALUE_MISSING	Missing value	A named argument was passed but no value followed	usage
15	ERROR_UNKNOWN	Unknown switch	An unrecognised switch (or argument) was passed on the command line; the message suggests the closest names (see Did you mean)	usage
16	ERROR_ENVVAR_POSITIONAL	envvar not allowed for positional	envvar= combined with positional=.true.	definition
17	ERROR_ENVVAR_NOT_STORE	envvar requires act='store', store_true or store_false	Environment variable used with an incompatible action (store*, count, append, ...)	definition
18	ERROR_ENVVAR_NARGS	envvar not allowed for list-valued	No longer raised: lists accept an envvar (comma-separated values)	definition
19	ERROR_STORE_STAR_POSITIONAL	act='store*' not allowed for positional	Incompatible combination	definition
20	ERROR_STORE_STAR_NARGS	act='store*' not allowed for list-valued	Incompatible combination	definition
21	ERROR_STORE_STAR_ENVVAR	act='store*' not allowed with envvar	Incompatible combination	definition
22	ERROR_ACTION_UNKNOWN	Unknown action	act= set to an unrecognised string	definition
23	ERROR_DUPLICATED_CLAS	Argument passed more than once	The same switch appears twice on the command line	usage
24	ERROR_MISSING_REQUIRED_VAL	Required value not passed	A switch that needs a value got none	usage
25	ERROR_INLINE_VALUE_NOT_ALLOWED	Inline value for a flag	--flag=yes on an option that takes no value	usage
26	ERROR_INLINE_VALUE_NARGS	Inline value for a list	--list=1 on an option with nargs: pass the values after the switch	usage
27	ERROR_COUNT_INCONSISTENT	Invalid count	A count option that is positional or has nargs, envvar or choices	definition
28	ERROR_APPEND_INCONSISTENT	Invalid append	An append option that is positional or has nargs or envvar	definition
29	ERROR_APPEND_SCALAR_GET	Scalar get of an append	An append option holds a list: read it with get_varying or into an array	definition
30	ERROR_RANGE_DEFINITION	Invalid range	A non-numeric bound, min > max, an empty open interval, a range on a flag; or get of a real that would clamp to an open bound	definition
31	ERROR_OUT_OF_RANGE	Value out of range	get of a value outside min/max (without clamp)	usage
32	ERROR_RANGE_TYPE	Range on a non-numeric get	get into a character or logical of an option with a range	definition
33	ERROR_PATH_NOT_FOUND	Path does not exist	must_exist=/readable= and the file is missing	environment
34	ERROR_PATH_NOT_READABLE	Path not readable	readable= and the file cannot be opened for reading (the message gives the reason)	environment
35	ERROR_PATH_NOT_WRITABLE	Path not writable	writable= and the existing file cannot be opened for writing	environment
36	ERROR_SWITCH_NEG_INCONSISTENT	Invalid flag negation	switch_neg= on an argument that is not a named store_true/store_false flag without nargs, blank, or equal to its own switch names	definition
37	ERROR_ALTERNATE_INCONSISTENT	Invalid alternate action	act='alternate' with nargs, envvar, choices, exclude, required=.true. or positional	definition
38	ERROR_MAP_FORMAT	Map item not KEY=VALUE	A map pair without = or with an empty key (command line, environment, configuration or default)	usage
39	ERROR_MAP_DUPLICATE_KEY	Map key repeated	The same key twice in a map	usage
40	ERROR_MAP_UNKNOWN_KEY	Map key not allowed	A key outside map_keys; the message lists the allowed keys and suggests the closest	usage
41	ERROR_MAP_KEY_MISSING	Map key not given	get_map_value of a missing key without found=	usage
42	ERROR_MAP_INCONSISTENT	Invalid map	map=.true. on a positional, a flag, a scalar store or with choices; map_keys without map; get_map of an option that is not a map	definition
43	ERROR_ENVVAR_CSV	Unterminated quote in a list from the environment	WORKERS='1,"99' for an option with nargs and envvar='WORKERS'	environment
44	ERROR_DEPRECATED_REQUIRED	A required option cannot be deprecated	deprecated= combined with required=.true.	definition
45	ERROR_POSITIONAL_NARGS	nargs on a positional argument	Positionals take one value each: use a named list option	definition
46	ERROR_UNSUPPORTED_TYPE	Unsupported variable type	get into a type FLAP cannot fill (e.g. complex, or a non-logical for a flag)	definition
47	ERROR_LIST_SIZE	List size differs from the array size	get into a fixed-size array with more or fewer elements than the values: use an array of the right size, or get_varying	usage
48	ERROR_DEF_NARGS	Default count differs from nargs	nargs='N' with a default of another number of values: give the default N values	definition
49	ERROR_PATH_INCONSISTENT	Path checks on an option without value	must_exist/readable/writable/allow_dash on a flag, count, ...	definition
50	ERROR_CASTING_NUMBER	Value is not a number	get into an integer or a real of a value that is not exactly one number (--nx many, --nx /, --nx 2*5), from any source, or parse of an option with val_type; the message names the value, the option and the type	usage
51	ERROR_TYPE_DEFINITION	Invalid val_type	An unknown name; a map, a configuration file option or an action without value; a flag not logical, a count not an integer, a path not character; a range on a non-number; a default or a choice that does not fit the type	definition
52	ERROR_TYPE_MISMATCH	get against val_type	get into another family or a narrower kind than declared, whatever the value (character is always allowed)	definition
100	ERROR_GROUP_CONSISTENCY	Group (command) consistency broken	Two arguments of a group share a switch	definition
101	ERROR_GROUP_M_EXCLUDE	Two mutually exclusive groups both passed	Both sides of set_mutually_exclusive_groups given	usage
102	ERROR_M_EXCLUDE_SET	Two members of a mutually exclusive set passed	--mesh m --restart r with set_mutually_exclusive_switches(switches='--mesh,--restart')	usage
103	ERROR_M_EXCLUDE_SET_REQUIRED	No member of a required set passed	None of the switches of a set with required=.true. given	usage
104	ERROR_M_EXCLUDE_SET_DEFINITION	Invalid mutually exclusive set	Fewer than two switches, an undefined, repeated or required member, or a switch already in a set (returned by set_mutually_exclusive_switches, then by parse)	definition
105	ERROR_POSITION_DUPLICATE	Position declared twice	Two positionals of a group (command) with the same position (raised by add)	definition
106	ERROR_POSITION_GAP	Missing position	Positions are not 1..N, e.g. 1 and 3 without 2 (raised when parsing starts)	definition
1000	ERROR_MISSING_CLA	Argument not found in CLI	get or get_source called for an undefined switch (is_passed returns .false., with no error)	definition
1001	ERROR_MISSING_GROUP	Group not found in CLI	get, get_source or set_mutually_exclusive_groups called for an undefined group (run_command returns .false., with no error)	definition
1002	ERROR_MISSING_SELECTION_CLA	No argument selected	get called with neither switch= nor position=	definition
1003	ERROR_TOO_FEW_CLAS	Insufficient arguments for CLI	Reserved: not raised by the current version	usage
1004	ERROR_UNKNOWN_CLAS_IGNORED	Unknown arguments ignored	init(ignore_unknown_clas=.true.) and an unknown switch was passed: not printed, the message of one of them is in cli%error_message	usage
1005	ERROR_USER	Application error	Returned by cli%raise_error (see below)	application
1006	ERROR_CONFIG_NOT_FOUND	Configuration file not found	set_config(file=..., required=.true.) and the file is missing (or cannot be read)	environment
1007	ERROR_CONFIG_UNKNOWN_KEY	Configuration file: unknown key	An unknown key or section, a key of an option taking no value, or a malformed line (the message names the line)	environment
1008	ERROR_GROUP_ALIAS	Invalid command alias	add_group(aliases=...) with an alias equal to a command name or another alias, repeated, blank or equal to its command, or a command name equal to an alias; parse then fails too	definition
1009	ERROR_COPY_POSITIONAL	Positional in copy_options	copy_options(switches=...) names a positional argument: only named options are copied	definition
1010	ERROR_COMPLETION_SHELL	Unknown completion shell	--show-completion/--install-completion with a shell other than bash, zsh, fish, powershell, or none given and $SHELL unset; --install-completion powershell (install it by hand)	usage
1011	ERROR_COMPLETION_INSTALL	Completion not installed	$HOME unset, or the script or the rc file cannot be written (the message carries the I/O error; for fish, ~/.config/fish must exist)	environment
1012	ERROR_ARGUMENT_RETRIEVAL	A command line argument cannot be read	get_command_argument failed (processor error; not expected in practice)	environment
1013	ERROR_COMMAND_REPEATED	A command passed more than once	prog commit -m x commit, or a command and one of its aliases; reported before --help	usage
1014	ERROR_USAGE_ON_ERROR	Invalid usage_on_error	init(usage_on_error=...) other than full, usage, none (any case); reported by parse	definition
1015	ERROR_FORMAT	Invalid error_format	init(error_format=) is not text or json	definition
2001	ERROR_MENU_INVALID	Invalid menu answer	Not one of the numbers shown, an empty field, or unreadable (see Interactive Menus)	usage
2002	ERROR_MENU_TOO_MANY	Too many menu answers	Several answers to a single-choice menu	usage
2003	ERROR_MENU_DUPLICATE	Duplicate menu answer	The same option chosen twice with multiple selection	usage
2004	ERROR_MENU_NO_RESPONSE	Empty menu answer	The user just pressed Enter, and the menu has no default option	usage
2005	ERROR_MENU_EOF	End of input in a menu	Standard input at its end (/dev/null, a batch job): no answer can come	environment
2006	ERROR_MENU_DEFINITION	Invalid menu	run on a menu without options, add_option with an empty text or a second default (single choice), init(tries=) below 1 or init(separator=''), the scalar run(choice) on a menu with multiple selection, yes_no(default=) other than y or n	definition

The first two group codes are named ERROR_GROUP_* in the flap module; inside the group module they are ERROR_CONSISTENCY and ERROR_M_EXCLUDE, which would clash with the argument-level ERROR_M_EXCLUDE (9).

Exit statuses

The class of an error says what must change before trying again, and cli%exit_status() turns it into an exit status. FLAP does not end the program on an error, except with --check: the program writes stop cli%exit_status().

Exit status	Class	What to change	Constant
0		Nothing: success, a status, or an unknown argument the program asked to ignore
1	application	Left to the program: raise_error, and its own failures	EXIT_APPLICATION
2	usage	The command line; also STATUS_NO_ARGS	EXIT_USAGE
3	environment	A file or a variable: the command line may be right	EXIT_ENVIRONMENT
4	definition	The program: retrying cannot help	EXIT_DEFINITION

error_class(code) (a string, '' for a status or an unknown code) and error_exit_status(code) (an integer) give the same answers for any code, error_description(code) the meaning of the table above, and JSON errors carry "class". The class belongs to the code, not to where the value came from: a bad number from a configuration file is still usage.

Handling status codes

Negative codes mean that FLAP did what the user asked (printed the help, saved the man page, ...). By default parse ends the program itself right after, with exit status 0 (2 for STATUS_NO_ARGS), so these statuses are not returned to your code; STATUS_ALTERNATE is always returned. With init(standalone=.false.) parse returns every status instead: the program can clean up first (close files, call MPI_Finalize), and the help can be tested in-process.

call cli%init(progname='statuses', version='v2.4.0', standalone=.false., no_args_is_help=.true.)

call cli%parse(error=error)
select case(error)
case(0)
  print '(A)', 'running'
case(STATUS_PRINT_H, STATUS_PRINT_V, STATUS_PRINT_M)
  print '(A)', 'help, version or Markdown printed: cleaning up, then exit status 0'
case(STATUS_NO_ARGS)
  stop 2, quiet=.true.
case default
  stop 1, quiet=.true.
endselect

$ statuses --help
usage: statuses [--mesh value] [--help] [--markdown] [--version]

Optional switches:
  --mesh value
      default value m.grd
      Mesh file
  --help, -h
      Print this help message
  --markdown, -md
      Save this help message in a Markdown file
  --version, -v
      Print version
help, version or Markdown printed: cleaning up, then exit status 0

When several of them are passed, one wins, in this order (--schema comes between the man page and completion): a syntax error anywhere on the command line (an unknown or duplicated switch, a missing value, a repeated command) is returned first, then help, version, Markdown, man page and completion. --version --help prints the help; --help compile --bogus reports the unknown switch.

Reporting application errors

Checks that only your program can do (--nx must be even, --t-end must exceed --t-start) can be reported in FLAP's own style (program name, error colour, error unit) with raise_error:

call cli%get(switch='--nx', val=nx, error=error)
if (mod(nx, 2) /= 0) error = cli%raise_error('must be even', switch='--nx')
if (error /= 0) stop 1

call cli%get(switch='--nx', val=nx, error=error)
if (mod(nx, 2) /= 0) error = cli%raise_error('must be even', switch='--nx')
if (error /= 0) stop 1, quiet=.true.

$ raise_error --nx 33
raise_error: error: switch "--nx": must be even

usage: raise_error [--nx value] [--help] [--markdown] [--version]
[exit status 1]

It returns ERROR_USER (1005, and sets cli%error) and never stops: the program decides what to do. The help follows the message unless show_usage=.false., as init(usage_on_error=...) chooses (the whole help, the usage line as here, or nothing); with group='post' it is the help of that command (an undefined group returns ERROR_MISSING_GROUP and prints nothing). It works before or after parse.

Error hint

After a failed parse FLAP prints one more line to the error unit, pointing to the help (the command is named when the error is inside one):

$ actions --verbse
actions: error: switch "--verbse" is unknown! Did you mean "--verbose"?

Try 'actions --help' for help.
[exit status 1]

It is printed once, as the last line, only when there is a --help to suggest (not with disable_hv=.true.), and never for statuses, ignored unknown arguments or errors raised later by get (a value out of its choices or range). Disable it with init(error_hint=.false.).

Output after an error

A missing required option (and a required mutually exclusive set with no member given) prints the whole help of its group (command) after the error message. init(usage_on_error=...) chooses what is printed instead:

Value	Printed after the error message
'full' (default)	the whole help of the group, as before
'usage'	the usage line only, the first line of --help
'none'	nothing

call cli%init(progname='usage_on_error', usage_on_error='usage')

$ usage_on_error
usage_on_error: error: named option "--mesh" is required!

usage: usage_on_error --mesh value [--cfl value] [--help] [--markdown] [--version]
Try 'usage_on_error --help' for help.
[exit status 1]

With the default 'full' (the minimal program of the Installation page):

$ minimal
minimal: error: named option "--string" is required!

usage: minimal --string value [--help] [--markdown] [--version]

minimal FLAP example

Required switches:
  --string value, -s value
      a string

Optional switches:
  --help, -h
      Print this help message
  --markdown, -md
      Save this help message in a Markdown file
  --version, -v
      Print version
Try 'minimal --help' for help.
[exit status 1]

The error message and the hint line are always printed, and --help always prints the whole help. Any other value is ERROR_USAGE_ON_ERROR (1014), returned by parse.

Did you mean

An unknown argument gets up to three suggestions, most similar first, with click's wording:

$ actions --verbse
actions: error: switch "--verbse" is unknown! Did you mean "--verbose"?

Try 'actions --help' for help.
[exit status 1]

$ fake_git comit
fake_git: error: argument "comit" is unknown! Did you mean "commit"?

Try 'fake_git --help' for help.
[exit status 1]

With several candidates the message is (Did you mean one of: "--mass", "--mach"?).

The candidates are the visible switches, abbreviations and negations of the command being parsed (hidden switches never), and, at the top level, for an argument that is not a switch, the command names and aliases. A name is suggested when its similarity 1 - d/max(len) is at least 0.6, d being the Levenshtein (edit) distance; in any case with init(case_insensitive=.true.). The name of --name=value is the part before =.

Accessing the error message

command_line_interface has a public error_message attribute that contains a human-readable description of the last error, the text FLAP prints on the error unit, whichever part of the CLI raised it (parse, get, add, ...). It is allocated only when cli%error is an error: not after a call that succeeds, nor after a status (the help printed, ...). Check the error before reading it:

call cli%parse(error=error)
if (error /= 0) then
  write(*,'(A)') trim(cli%error_message)
  stop 1
end if