flap_command_line_interface_t

Command Line Interface (CLI) class.

Source: src/lib/flap_command_line_interface_t.F90

Dependencies

Contents

• command_line_interface
• free
• init
• add_group
• set_mutually_exclusive_groups
• set_config
• warn_deprecated
• load_config
• save_provenance
• set_mutually_exclusive_switches
• add
• check
• check_m_exclusive
• reset_parse
• parse
• parse_once
• report_check
• print_error_hint
• parse_core
• install_completion
• print_usage_line
• get_clasg_indexes
• hoist_top_builtins
• get_args_from_string
• get_args_from_invocation
• get_cla
• get_cla_list
• get_cla_list_varying_R16P
• get_cla_list_varying_R8P
• get_cla_list_varying_R4P
• get_cla_list_varying_I8P
• get_cla_list_varying_I4P
• get_cla_list_varying_I2P
• get_cla_list_varying_I1P
• get_cla_list_varying_logical
• copy_options
• get_map
• get_map_value
• get_cla_list_varying_char
• ensure_builtins
• save_bash_completion
• save_zsh_completion
• save_fish_completion
• save_powershell_completion
• save_skill
• save_json_schema
• save_man_page
• save_usage_to_markdown
• print_usage
• save_man_page_core
• save_usage_to_markdown_core
• errored
• finalize
• quiet_stop
• write_script
• get_source
• provenance
• provenance_text
• provenance_json
• provenance_arguments
• envvar_name
• is_passed
• is_defined_group
• group_index
• raise_error
• is_called_group
• is_defined
• is_dry_run
• dry_run_passed
• exit_status
• is_parsed
• check_requested
• no_args_help
• dispatch_status
• completion_shell
• usage_on_error_is
• is_fatal
• top_builtin
• map_cla
• builtins_missing
• usage
• signature
• completion_script
• completion_script_core
• fish_script
• powershell_script
• error_description
• json_schema
• skill
• exclusive_of
• usage_core
• signature_core
• bash_script
• provenance_name
• completion_function
• program_basename

Variables

Name	Type	Attributes	Description
ERROR_CODES	integer(kind=I4P)	parameter	Codes described by error_description.
ERROR_MISSING_CLA	integer(kind=I4P)	parameter	CLA not found in CLI.
ERROR_MISSING_GROUP	integer(kind=I4P)	parameter	Group not found in CLI.
ERROR_MISSING_SELECTION_CLA	integer(kind=I4P)	parameter	CLA selection in CLI failing.
ERROR_TOO_FEW_CLAS	integer(kind=I4P)	parameter	Insufficient arguments for CLI.
ERROR_UNKNOWN_CLAS_IGNORED	integer(kind=I4P)	parameter	Unknown CLAs passed, but ignored.
ERROR_USER	integer(kind=I4P)	parameter	Application error reported by raise_error.
ERROR_CONFIG_NOT_FOUND	integer(kind=I4P)	parameter	Required configuration file not found.
ERROR_CONFIG_UNKNOWN_KEY	integer(kind=I4P)	parameter	Configuration file: unknown key or malformed line.
ERROR_GROUP_ALIAS	integer(kind=I4P)	parameter	Alias of a command equal to a command or an alias.
ERROR_COPY_POSITIONAL	integer(kind=I4P)	parameter	copy_options asked to copy a positional CLA.
ERROR_COMPLETION_SHELL	integer(kind=I4P)	parameter	Unknown (or unset) shell of the completion builtins.
ERROR_COMPLETION_INSTALL	integer(kind=I4P)	parameter	The completion script cannot be installed.
ERROR_ARGUMENT_RETRIEVAL	integer(kind=I4P)	parameter	A command line argument cannot be retrieved.
ERROR_COMMAND_REPEATED	integer(kind=I4P)	parameter	A command passed more than once (B36).
ERROR_USAGE_ON_ERROR	integer(kind=I4P)	parameter	init(usage_on_error=) not full, usage or none (F27).
ERROR_FORMAT	integer(kind=I4P)	parameter	init(error_format=) not text or json (#128).

Derived Types

command_line_interface

Command Line Interface (CLI) class.

Inheritance

Extends: object

Components

Name	Type	Attributes	Description
progname	character(len=:)	allocatable	Program name.
version	character(len=:)	allocatable	Program version.
help	character(len=:)	allocatable	Help message.
help_color	character(len=:)	allocatable	ANSI color of help messages.
help_style	character(len=:)	allocatable	ANSI style of help messages.
help_markdown	character(len=:)	allocatable	Longer help message, markdown formatted.
description	character(len=:)	allocatable	Detailed description.
license	character(len=:)	allocatable	License description.
authors	character(len=:)	allocatable	Authors list.
epilog	character(len=:)	allocatable	Epilogue message.
m_exclude	character(len=:)	allocatable	Mutually exclude other CLA(s group).
error_message	character(len=:)	allocatable	Meaningful error message to standard-error.
error_color	character(len=:)	allocatable	ANSI color of error messages.
error_style	character(len=:)	allocatable	ANSI style of error messages.
examples	type(flap_string)	allocatable	Examples of correct usage (examples(i)%s).
error	integer(kind=I4P)		Error trapping flag.
usage_lun	integer(kind=I4P)		Output unit to print help/usage messages
version_lun	integer(kind=I4P)		Output unit to print version message
error_lun	integer(kind=I4P)		Error unit to print error messages
case_insensitive	logical		Match switches and command names in any case (F14).
error_format	character(len=:)	allocatable	Format of the error messages: text (default) or json (#128).
error_argument	character(len=:)	allocatable	Argument of the last error, when known (JSON format).
error_suggestions	type(flap_string)	allocatable	"Did you mean" candidates of the last error (JSON format).
clasg	type(command_line_arguments_group)	allocatable	CLA list [1:Na].
args	type(flap_string)	allocatable	Actually passed command line arguments.
disable_hv	logical		Disable automatic 'help' and 'version' CLAs.
is_parsed_	logical		Parse status.
parse_tried	logical		A parse has run without completing.
parse_result	integer(kind=I4P)		Error or status of that parse.
parse_message	character(len=:)	allocatable	Error message of that parse.
ignore_unknown_clas	logical		Disable errors-raising for passed unknown CLAs.
standalone	logical		Stop after help/version/markdown.
error_hint	logical		Print a hint after a failed parse.
no_args_is_help	logical		Print the help when no arguments are passed.
ignore_env	logical		Turn every environment lookup off.
completion_options	logical		--show/--install-completion (F24).
auto_envvar_prefix	character(len=:)	allocatable	Prefix of the generated envvar names.
usage_on_error	character(len=:)	allocatable	After an error: full, usage, none (F27).
man_option	logical		--man builtin (F29).
schema_option	logical		--schema builtin (#128).
dry_run_option	logical		--dry-run builtin (#129).
check_option	logical		--check builtin (#128).
error_format_env	character(len=:)	allocatable	Variable choosing the error format (#128).
man_file	character(len=:)	allocatable	File of --man ('': .1).
markdown_file	character(len=:)	allocatable	File of --markdown ('': .md).
config_path	character(len=:)	allocatable	Configuration file (F08).
config_required	logical		The configuration file must exist.
config_used	character(len=:)	allocatable	Configuration file read by parse.
error_unknown_clas	integer(kind=I4P)		Error trapping flag for unknown CLAs.
unknown_message	character(len=:)	allocatable	Message of an ignored unknown CLA.

Type-Bound Procedures

Name	Attributes	Description
error_prefix	pass(self)	Prefix of error messages.
free_object	pass(self)	Free dynamic memory.
print_version	pass(self)	Print version.
print_error_message	pass(self)	Print meaningful error message.
print_warning	pass(self)	Print a warning.
is_json_format	pass(self)	Check if the error messages are JSON lines.
inherit_error	pass(self)	Take the error of another object, with its message.
clear_error	pass(self)	Forget the error and its message.
set_examples	pass(self)	Set examples of correct usage.
assign_object	pass(lhs )	Assignment overloading.
free		Free dynamic memory.
init		Initialize CLI.
add_group		Add CLAs group CLI.
add		Add CLA to CLI.
is_passed		Check if a CLA has been passed.
is_defined_group		Check if a CLAs group has been defined.
raise_error		Report an application error in FLAP's style.
is_defined		Check if a CLA has been defined.
is_dry_run		Check if --dry-run has been passed.
exit_status		Exit status of the current error or status.
is_parsed		Check if CLI has been parsed.
set_mutually_exclusive_groups		Set two CLAs group as mutually exclusive.
set_mutually_exclusive_switches		Set a mutually exclusive set of switches.
set_config		Set the configuration file.
get_source		Source of the value of a CLA.
save_provenance		Save the JSON report of every value with its source (#128).
provenance		Report of every value with its source.
run_command		Check if a CLAs group has been run.
parse		Parse Command Line Interfaces.
reset_parse		Forget the result of a parse, keeping the definitions.
get_map		Get the keys and values of a map option (F18).
copy_options		Copy the named options of a group into another (F21).
get_map_value		Get the value of a key of a map option (F18).
get		Get CLA value(s) from CLAs list parsed.
get_varying		Get CLA value(s) from CLAs list parsed, varying size list.
usage		Get CLI usage.
signature		Get CLI signature.
print_usage		Print correct usage of CLI.
save_bash_completion		Save bash completion script (for named CLAs only).
save_zsh_completion		Save zsh completion script (bash script via bashcompinit).
save_fish_completion		Save fish completion script (native).
save_powershell_completion		Save PowerShell completion script (native completer).
json_schema		JSON description of the CLI (#128).
skill		Agent Skill describing the program.
save_skill		Save the Agent Skill.
save_json_schema		Save the JSON description of the CLI (#128).
save_man_page		Save CLI usage as man page.
save_usage_to_markdown		Save CLI usage as markdown.
ensure_builtins		Add the builtin CLAs (help, markdown, version, --) if missing.
builtins_missing		Check if the builtin CLAs still have to be added.
usage_core		Get CLI usage (builtins already present).
signature_core		Get CLI signature (builtins already present).
completion_script		Completion script of a shell.
completion_script_core		Completion script of a shell (builtins already present).
completion_shell		Shell of a completion builtin.
install_completion		Install the completion script of a shell.
bash_script		Bash (or zsh) completion script.
fish_script		Fish completion script.
powershell_script		PowerShell completion script.
save_man_page_core		Save CLI usage as man page (builtins already present).
save_usage_to_markdown_core		Save CLI usage as markdown (builtins already present).
check_requested		Check if --check is on the command line.
report_check		Report the verdict of --check.
provenance_text		Text report of provenance.
provenance_json		JSON report of provenance.
provenance_arguments		Command line in JSON, sensitive values masked.
parse_core		Parse the command line (body of parse).
hoist_top_builtins		Move --check and --dry-run to the top level.
top_builtin		Check a top-level builtin.
exclusive_of		Command excluded by a command.
dry_run_passed		Check the --dry-run builtin.
parse_once		Parse for a getter, once: a failed parse is not repeated.
group_index		Index of the group with a name, -1 if none.
is_fatal		Check if the current error stops parsing.
dispatch_status		Print help/version/markdown in the D3 order.
no_args_help		Print the help when no arguments are passed.
print_error_hint		Print the hint after a failed parse.
errored		Trig error occurence and print meaningful message.
check		Check data consistency.
check_m_exclusive		Check if two mutually exclusive CLAs group have been called.
load_config		Load and check the configuration file.
warn_deprecated		Warn about the deprecated options and commands used.
get_clasg_indexes		Get CLAs groups indexes.
print_usage_line		After an error: the usage line (F27).
usage_on_error_is		Check init(usage_on_error=) (F27).
get_args		Get CLAs.
get_args_from_string		Get CLAs from string.
get_args_from_invocation		Get CLAs from CLI invocation.
get_cla		Get CLA (single) value from CLAs list parsed.
get_cla_list		Get CLA multiple values from CLAs list parsed.
get_cla_list_varying_R16P		Get CLA multiple values from CLAs list parsed, varying size, R16P.
get_cla_list_varying_R8P		Get CLA multiple values from CLAs list parsed, varying size, R8P.
get_cla_list_varying_R4P		Get CLA multiple values from CLAs list parsed, varying size, R4P.
get_cla_list_varying_I8P		Get CLA multiple values from CLAs list parsed, varying size, I8P.
get_cla_list_varying_I4P		Get CLA multiple values from CLAs list parsed, varying size, I4P.
get_cla_list_varying_I2P		Get CLA multiple values from CLAs list parsed, varying size, I2P.
get_cla_list_varying_I1P		Get CLA multiple values from CLAs list parsed, varying size, I1P.
get_cla_list_varying_logical		Get CLA multiple values from CLAs list parsed, varying size, bool.
get_cla_list_varying_char		Get CLA multiple values from CLAs list parsed, varying size, char.
map_cla		Locate the CLA of a map getter.

Subroutines

free

Free dynamic memory.

Attributes: elemental

subroutine free(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.

Call graph

init

Initialize CLI.

subroutine init(self, progname, version, help, description, license, authors, examples, epilog, disable_hv, usage_lun, error_lun, version_lun, error_color, error_style, ignore_unknown_clas, standalone, error_hint, no_args_is_help, ignore_env, auto_envvar_prefix, case_insensitive, completion_options, usage_on_error, man_option, man_file, markdown_file, schema_option, error_format, error_format_env, check_option, dry_run_option)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
progname	character(len=*)	in	optional	Program name.
version	character(len=*)	in	optional	Program version.
help	character(len=*)	in	optional	Help message introducing the CLI usage.
description	character(len=*)	in	optional	Detailed description message introducing the program.
license	character(len=*)	in	optional	License description.
authors	character(len=*)	in	optional	Authors list.
examples	character(len=*)	in	optional	Examples of correct usage.
epilog	character(len=*)	in	optional	Epilog message.
disable_hv	logical	in	optional	Disable automatic insert of 'help' and 'version' CLAs.
usage_lun	integer(kind=I4P)	in	optional	Unit number to print usage/help.
error_lun	integer(kind=I4P)	in	optional	Unit number to print error info.
version_lun	integer(kind=I4P)	in	optional	Unit number to print version/license info.
error_color	character(len=*)	in	optional	ANSI color of error messages.
error_style	character(len=*)	in	optional	ANSI style of error messages.
ignore_unknown_clas	logical	in	optional	Disable errors-raising for passed unknown CLAs.
standalone	logical	in	optional	Stop after help/version/markdown (default); if
error_hint	logical	in	optional	Print "Try 'prog --help' for help." after a failed
no_args_is_help	logical	in	optional	Print the help (STATUS_NO_ARGS) when no arguments
ignore_env	logical	in	optional	Turn every environment lookup off (F20): envvar
auto_envvar_prefix	character(len=*)	in	optional	Generate the envvar of the options without one:
case_insensitive	logical	in	optional	Match switches and command names in any case (F14);
completion_options	logical	in	optional	Add --show-completion and --install-completion
usage_on_error	character(len=*)	in	optional	What an error prints after its message (F27):
man_option	logical	in	optional	Add --man to the top level (F29).
man_file	character(len=*)	in	optional	File of --man (default .1).
markdown_file	character(len=*)	in	optional	File of --markdown (default .md).
schema_option	logical	in	optional	Add --schema to the top level (#128).
error_format	character(len=*)	in	optional	Format of the error messages: text (default), json.
error_format_env	character(len=*)	in	optional	Variable choosing the format, per run: text, json;
check_option	logical	in	optional	Add --check to the top level (#128).
dry_run_option	logical	in	optional	Add --dry-run to the top level, read by is_dry_run (#129).

Call graph

add_group

Add CLAs group to CLI.

The aliases (F19 of #125) are comma separated: invoking an alias is invoking the command. An alias equal to a command name, to another alias, to the command itself, or blank, and a command name equal to an alias, are ERROR_GROUP_ALIAS: printed, returned, and kept on the command, so that parse fails too (as an invalid exclusive set).

subroutine add_group(self, help, description, exclude, examples, group, no_args_is_help, deprecated, aliases, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
help	character(len=*)	in	optional	Help message.
description	character(len=*)	in	optional	Detailed description.
exclude	character(len=*)	in	optional	Group name of the mutually exclusive group.
examples	character(len=*)	in	optional	Examples of correct usage of the group.
group	character(len=*)	in		Name of the grouped CLAs.
no_args_is_help	logical	in	optional	Print the help of the group when invoked alone.
deprecated	character(len=*)	in	optional	Deprecation message ('' for none): warn when called.
aliases	character(len=*)	in	optional	Aliases of the command, comma separated (F19).
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

set_mutually_exclusive_groups

Set two CLAs group ad mutually exclusive. An undefined command is ERROR_MISSING_GROUP, reported (#129: it was ignored).

subroutine set_mutually_exclusive_groups(self, group1, group2, pref, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
group1	character(len=*)	in		Name of the first grouped CLAs.
group2	character(len=*)	in		Name of the second grouped CLAs.
pref	character(len=*)	in	optional	Prefixing string.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

set_config

Set the configuration file (F08 of #125): an INI file whose values come below the environment and above the defaults.

Read by parse, after help/version: keys are long switches without the dashes, sections are groups (commands). A missing file is skipped, unless required (ERROR_CONFIG_NOT_FOUND); an unknown key or a malformed line is ERROR_CONFIG_UNKNOWN_KEY, unless ignore_unknown_clas.

subroutine set_config(self, file, required, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
file	character(len=*)	in		File name.
required	logical	in	optional	The file must exist (default .false.).
error	integer(kind=I4P)	out	optional	Error trapping flag.

warn_deprecated

Warn about the deprecated options and commands used (F13 of #125), on error_lun: a called command, an option whose value comes from the command line or the environment (not from a configuration file or the default, as in click).

subroutine warn_deprecated(self, pref)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
pref	character(len=*)	in	optional	Prefixing string.

Call graph

load_config

Load the configuration file, if any, and check it: every key must name an option taking a value (D18 of #125).

The file is named by the top-level act='config' option when given on the command line or in its environment variable (then it must exist), else by set_config (which says if it must exist), else by the default of that option (skipped when missing).

subroutine load_config(self, config, pref, check)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
config	type(config_file)	inout		Configuration file.
pref	character(len=*)	in	optional	Prefixing string.
check	logical	in	optional	Report a missing or invalid file (default .true.; off for an

Call graph

save_provenance

Save the JSON report of provenance, the run manifest (#128); like get, it parses first if parse has not been called.

subroutine save_provenance(self, file, pref, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
file	character(len=*)	in		Output file name.
pref	character(len=*)	in	optional	Prefixing string.
error	integer(kind=I4P)	out	optional	I/O status (not zero if the file cannot be written).

Call graph

set_mutually_exclusive_switches

Set a mutually exclusive set of switches (F03 of #125): at most one member may be passed, exactly one if required.

The members (comma separated, by switch or abbreviation) must be already added to the group, not required, and in no other set; otherwise the set is not added and the error is ERROR_M_EXCLUDE_SET_DEFINITION. Only passed members count: a default neither satisfies nor violates a set.

subroutine set_mutually_exclusive_switches(self, switches, required, group, pref, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
switches	character(len=*)	in		Comma separated members, e.g. '--mesh,--restart'.
required	logical	in	optional	Exactly one member must be passed (default .false.).
group	character(len=*)	in	optional	Group (command) of the members (default: the top level).
pref	character(len=*)	in	optional	Prefixing string.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

add

Add CLA to CLI.

@note If not otherwise declared the action on CLA value is set to "store" a value that must be passed after the switch name or directly passed in case of positional CLA.

@note If not otherwise speficied the CLA belongs to the default group "zero" that is the group of non-grouped CLAs.

@note If CLA belongs to a not yet present group it is created on the fly.

subroutine add(self, pref, group, group_index, switch, switch_ab, switch_neg, help, help_markdown, help_color, help_style, required, val_required, positional, position, hidden, act, def, nargs, choices, exclude, envvar, must_exist, readable, writable, allow_dash, deprecated, min, max, min_open, max_open, clamp, case_sensitive, map, map_keys, metavar, error, val_type, sensitive)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
pref	character(len=*)	in	optional	Prefixing string.
group	character(len=*)	in	optional	Name of the grouped CLAs.
group_index	integer(kind=I4P)	in	optional	Index of the grouped CLAs.
switch	character(len=*)	in	optional	Switch name.
switch_ab	character(len=*)	in	optional	Abbreviated switch name.
switch_neg	character(len=*)	in	optional	Negation of a flag, --no-x (F11): the opposite value.
help	character(len=*)	in	optional	Help message describing the CLA.
help_markdown	character(len=*)	in	optional	Longer help message, markdown formatted.
help_color	character(len=*)	in	optional	ANSI color of help messages.
help_style	character(len=*)	in	optional	ANSI style of help messages.
required	logical	in	optional	Flag for set required argument.
val_required	logical	in	optional	Flag for set value required for optional argument.
positional	logical	in	optional	Flag for checking if CLA is a positional or a named CLA.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
hidden	logical	in	optional	Flag for hiding CLA, thus it does not compare into help.
act	character(len=*)	in	optional	CLA value action.
def	character(len=*)	in	optional	Default value.
nargs	character(len=*)	in	optional	Number of arguments consumed by CLA.
choices	character(len=*)	in	optional	List of allowable values for the argument.
exclude	character(len=*)	in	optional	Switch name of the mutually exclusive CLA.
envvar	character(len=*)	in	optional	Environment variable from which take value.
must_exist	logical	in	optional	The value is a path that must exist (F09).
readable	logical	in	optional	The value is a path that must be readable (and exist).
writable	logical	in	optional	The value is a path writable if it exists.
allow_dash	logical	in	optional	'-' passes the path checks (standard input/output).
deprecated	character(len=*)	in	optional	Deprecation message ('' for none): warn when used (F13).
min	character(len=*)	in	optional	Minimum of the value (F05), checked by get.
max	character(len=*)	in	optional	Maximum of the value (F05), checked by get.
min_open	logical	in	optional	The minimum is excluded (default .false.).
max_open	logical	in	optional	The maximum is excluded (default .false.).
clamp	logical	in	optional	An out-of-range value becomes the bound (default .false.).
case_sensitive	logical	in	optional	Character choices match only in their case (default
map	logical	in	optional	The values are KEY=VALUE pairs (F18).
map_keys	character(len=*)	in	optional	Allowed keys of a map, comma separated (F18).
metavar	character(len=*)	in	optional	Placeholder of the value in the help (F12), default 'value'.
error	integer(kind=I4P)	out	optional	Error trapping flag.
val_type	character(len=*)	in	optional	Declared type of the value, validated by parse (#128): I1P,
sensitive	logical	in	optional	Never report the value: *** in provenance, no default in

Call graph

check

Check data consistency.

subroutine check(self, pref, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
pref	character(len=*)	in	optional	Prefixing string.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

check_m_exclusive

Check if two mutually exclusive CLAs group have been called.

subroutine check_m_exclusive(self, pref)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
pref	character(len=*)	in	optional	Prefixing string.

Call graph

reset_parse

Forget the result of a parse, keeping the definitions (options, commands, builtins): the next parse (or get) parses again. Without it, a second call of parse is ignored and the first result is kept.

subroutine reset_parse(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.

Call graph

parse

Parse Command Line Interfaces by means of a previously initialized CLAs groups list.

@note The leading and trailing white spaces are removed from CLA values.

@note If the args argument is passed the command line arguments are taken from it and not from the actual program CLI invocations.

subroutine parse(self, pref, args, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

parse_once

Parse for a getter. A parse that has not completed (an error, or a status such as the help with standalone=.false.) is not repeated: its result comes back without reading the real command line nor printing again. A getter passing args asks for a parse of that text, and gets it.

subroutine parse_once(self, pref, args, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

report_check

Report the verdict of --check (#128): the result, then, in standalone mode, the end of the program, 0 if valid, else the status of the error (exit_status).

The options of an unknown type are named: FLAP has not validated them, and says so instead of implying they are fine.

subroutine report_check(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.

Call graph

print_error_hint

Print the last line after a failed parse: "Try 'prog [command] --help' for help." (F26 of #125).

Only when enabled (error_hint) and when there is a help option to suggest (not disable_hv); the command is the first called one with an error.

subroutine print_error_hint(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.

Call graph

parse_core

Parse the command line (the body of parse, which returns early once parsed and hands the error back).

subroutine parse_core(self, pref, args)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.

Call graph

install_completion

Install the completion script of a shell (F24 of #125): write it to $\text{HOME/.<prog>-completion.<shell>, then append a line sourcing it, marked '\# FLAP completion: <prog>', to the shell's rc file (}$HOME/.bashrc, $HOME/.zshrc, $HOME/.config/fish/config.fish), only if the marker is absent: the rc file is never rewritten, no directory is created. Success is STATUS_INSTALL_COMPLETION (and a report on the version unit); a failure ERROR_COMPLETION_INSTALL (printed, with the I/O message); PowerShell is not installed (ERROR_COMPLETION_SHELL, with instructions).

subroutine install_completion(self, shell, pref)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
shell	character(len=*)	in		Shell: bash, zsh, fish or powershell.
pref	character(len=*)	in	optional	Prefixing string.

Call graph

print_usage_line

After an error of group g, with init(usage_on_error='usage') (F27): the usage line of its help, as --help shows it.

subroutine print_usage_line(self, pref, g)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
pref	character(len=*)	in	optional	Prefixing string.
g	integer(kind=I4P)	in		Group of the error.

Call graph

get_clasg_indexes

Get the argument indexes of each CLAs group (command): ai(g,1:2) is the slice of self%args belonging to group g.

Arguments before the first command name belong to group 0; the arguments after a command name belong to that command. The fixed value slots of a switch (value_arity) are skipped before testing for a command name, so a value equal to a command name stays a value (B04); a variadic list is ended by a command name. A command met again (by its name or an alias) is returned in repeated (its name and the spelling met), never restarted (B36: that dropped its values).

subroutine get_clasg_indexes(self, ai, repeated)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
ai	integer(kind=I4P)	out	allocatable	CLAs grouped indexes.
repeated	type(flap_string)	out	allocatable	The first command repeated, [name, spelling]; none if none.

Call graph

hoist_top_builtins

Move --check and --dry-run found after a command name to the front of the arguments (#129): they belong to the top level, and prog cmd --check must mean prog --check cmd. Only the builtins (a command, or the program, defining its own switch of that name keeps it), only before a --, never a value slot of a switch. The order of the other arguments is kept.

subroutine hoist_top_builtins(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.

Call graph

get_args_from_string

Get CLAs from string.

The string is split as a shell would split a command line: see split_command_line.

subroutine get_args_from_string(self, args, ai, repeated)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
args	character(len=*)	in		String containing command line arguments.
ai	integer(kind=I4P)	out	allocatable	CLAs grouped indexes.
repeated	type(flap_string)	out	allocatable	The first command repeated (see get_clasg_indexes).

Call graph

get_args_from_invocation

Get CLAs from CLI invocation.

Every argument is read whole: its length is queried first, and a failed retrieval raises ERROR_ARGUMENT_RETRIEVAL.

subroutine get_args_from_invocation(self, ai, repeated)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
ai	integer(kind=I4P)	out	allocatable	CLAs grouped indexes.
repeated	type(flap_string)	out	allocatable	The first command repeated (see get_clasg_indexes).

Call graph

get_cla

Get CLA (single) value from CLAs list parsed.

@note For logical type CLA the value is directly read without any robust error trapping.

subroutine get_cla(self, val, pref, args, group, switch, position, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
val	class(*)	inout		CLA value.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

get_cla_list

Get CLA multiple values from CLAs list parsed.

@note For logical type CLA the value is directly read without any robust error trapping.

subroutine get_cla_list(self, val, pref, args, group, switch, position, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
val	class(*)	inout		CLA values.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

get_cla_list_varying_R16P

Get CLA multiple values from CLAs list parsed with varying size list, real(R16P).

@note The CLA list is returned deallocated if values are not correctly gotten.

@note For logical type CLA the value is directly read without any robust error trapping.

subroutine get_cla_list_varying_R16P(self, val, pref, args, group, switch, position, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
val	real(kind=R16P)	out	allocatable	CLA values.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

get_cla_list_varying_R8P

Get CLA multiple values from CLAs list parsed with varying size list, real(R8P).

@note The CLA list is returned deallocated if values are not correctly gotten.

@note For logical type CLA the value is directly read without any robust error trapping.

subroutine get_cla_list_varying_R8P(self, val, pref, args, group, switch, position, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
val	real(kind=R8P)	out	allocatable	CLA values.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

get_cla_list_varying_R4P

Get CLA multiple values from CLAs list parsed with varying size list, real(R4P).

@note The CLA list is returned deallocated if values are not correctly gotten.

@note For logical type CLA the value is directly read without any robust error trapping.

subroutine get_cla_list_varying_R4P(self, val, pref, args, group, switch, position, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
val	real(kind=R4P)	out	allocatable	CLA values.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

get_cla_list_varying_I8P

Get CLA multiple values from CLAs list parsed with varying size list, integer(I8P).

@note The CLA list is returned deallocated if values are not correctly gotten.

@note For logical type CLA the value is directly read without any robust error trapping.

subroutine get_cla_list_varying_I8P(self, val, pref, args, group, switch, position, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
val	integer(kind=I8P)	out	allocatable	CLA values.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

get_cla_list_varying_I4P

Get CLA multiple values from CLAs list parsed with varying size list, integer(I4P).

@note The CLA list is returned deallocated if values are not correctly gotten.

@note For logical type CLA the value is directly read without any robust error trapping.

subroutine get_cla_list_varying_I4P(self, val, pref, args, group, switch, position, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
val	integer(kind=I4P)	out	allocatable	CLA values.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

get_cla_list_varying_I2P

Get CLA multiple values from CLAs list parsed with varying size list, integer(I2P).

@note The CLA list is returned deallocated if values are not correctly gotten.

@note For logical type CLA the value is directly read without any robust error trapping.

subroutine get_cla_list_varying_I2P(self, val, pref, args, group, switch, position, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
val	integer(kind=I2P)	out	allocatable	CLA values.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

get_cla_list_varying_I1P

Get CLA multiple values from CLAs list parsed with varying size list, integer(I1P).

@note The CLA list is returned deallocated if values are not correctly gotten.

@note For logical type CLA the value is directly read without any robust error trapping.

subroutine get_cla_list_varying_I1P(self, val, pref, args, group, switch, position, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
val	integer(kind=I1P)	out	allocatable	CLA values.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

get_cla_list_varying_logical

Get CLA multiple values from CLAs list parsed with varying size list, logical.

@note The CLA list is returned deallocated if values are not correctly gotten.

@note For logical type CLA the value is directly read without any robust error trapping.

subroutine get_cla_list_varying_logical(self, val, pref, args, group, switch, position, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
val	logical	out	allocatable	CLA values.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

copy_options

Copy named options of a group (default the top level) into another group (F21 of #125): by value, every definition and none of the runtime state, so each copy has its own value. Without switches, every named option but the builtins; with switches (comma separated), those, all checked before any copy. A generated envvar (auto_envvar_prefix) is generated again for the target group, an explicit one is copied verbatim. Errors: ERROR_MISSING_GROUP, ERROR_MISSING_CLA, ERROR_COPY_POSITIONAL, and the consistency error of the target group (a switch it defines).

subroutine copy_options(self, to_group, from_group, switches, pref, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
to_group	character(len=*)	in		Target group (command).
from_group	character(len=*)	in	optional	Source group (command), default the top level.
switches	character(len=*)	in	optional	Switches to copy, comma separated (default all).
pref	character(len=*)	in	optional	Prefixing string.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

get_map

Get the keys and values of a map option (F18 of #125), in the order given; passed pairs replace the default ones.

subroutine get_map(self, switch, keys, values, group, pref, args, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
switch	character(len=*)	in		Switch name.
keys	character(len=*)	out	allocatable	Keys.
values	character(len=*)	out	allocatable	Values.
group	character(len=*)	in	optional	Name of group (command) of CLA.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

get_map_value

Get the value of a key of a map option, converted to the type of val (F18 of #125). A missing key leaves val untouched: found=.false., or ERROR_MAP_KEY_MISSING when found is absent.

subroutine get_map_value(self, switch, key, val, found, group, pref, args, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
switch	character(len=*)	in		Switch name.
key	character(len=*)	in		Key.
val	class(*)	inout		Value.
found	logical	out	optional	The key is in the map.
group	character(len=*)	in	optional	Name of group (command) of CLA.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

get_cla_list_varying_char

Get CLA multiple values from CLAs list parsed with varying size list, character.

@note The CLA list is returned deallocated if values are not correctly gotten.

@note For logical type CLA the value is directly read without any robust error trapping.

subroutine get_cla_list_varying_char(self, val, pref, args, group, switch, position, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
val	character(len=*)	out	allocatable	CLA values.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

ensure_builtins

Add the builtin CLAs if not done by the user: --help, --markdown and --version (unless disabled) and the hidden "--" collecting trailing arguments, in every group. Idempotent.

Called by parse and, on a copy, by every output method (usage, signature, save_*), so that their output is the same before and after parse (#125, B09).

subroutine ensure_builtins(self, pref)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
pref	character(len=*)	in	optional	Prefixing string.

Call graph

save_bash_completion

Save bash completion script (for named CLAs only), builtins included whether or not parse has been called.

subroutine save_bash_completion(self, bash_file, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
bash_file	character(len=*)	in		Output file name of bash completion script.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

save_zsh_completion

Save zsh completion script (F15 of #125): the bash script behind zsh's bashcompinit, to be sourced (e.g. from .zshrc); builtins included whether or not parse has been called.

subroutine save_zsh_completion(self, zsh_file, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
zsh_file	character(len=*)	in		Output file name of zsh completion script.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

save_fish_completion

Save fish completion script (F15 of #125), native: switches, choices, file names for free values, commands and aliases; builtins included whether or not parse has been called. Install it as ~/.config/fish/completions/prog.fish.

subroutine save_fish_completion(self, fish_file, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
fish_file	character(len=*)	in		Output file name of fish completion script.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

save_powershell_completion

Save PowerShell completion script (F15 of #125): a native argument completer (see powershell_script); builtins included whether or not parse has been called. Dot-source it, e.g. from $PROFILE.

subroutine save_powershell_completion(self, powershell_file, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
powershell_file	character(len=*)	in		Output file name of PowerShell completion script.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

save_skill

Save the Agent Skill (#129) in a file, usually <skill name>/SKILL.md: the format wants the directory named as the skill.

subroutine save_skill(self, file, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
file	character(len=*)	in		Output file name.
error	integer(kind=I4P)	out	optional	I/O status (not zero if the file cannot be written).

Call graph

save_json_schema

Save the JSON description of the CLI (#128), or of one command (#129): error is ERROR_MISSING_GROUP if there is no such one.

subroutine save_json_schema(self, file, error, group)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
file	character(len=*)	in		Output file name.
error	integer(kind=I4P)	out	optional	I/O status (not zero if the file cannot be written).
group	character(len=*)	in	optional	Name of a command.

Call graph

save_man_page

Save CLI usage as man page, builtins included whether or not parse has been called.

subroutine save_man_page(self, man_file, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
man_file	character(len=*)	in		Output file name for saving man page.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

save_usage_to_markdown

Save CLI usage as markdown, builtins included whether or not parse has been called.

subroutine save_usage_to_markdown(self, markdown_file, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
markdown_file	character(len=*)	in		Output file name for saving markdown.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

print_usage

Print correct usage.

subroutine print_usage(self, pref)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
pref	character(len=*)	in	optional	Prefixing string.

Call graph

save_man_page_core

Save CLI usage as man page.

subroutine save_man_page_core(self, man_file, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
man_file	character(len=*)	in		Output file name for saving man page.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

save_usage_to_markdown_core

Save CLI usage as markdown.

subroutine save_usage_to_markdown_core(self, markdown_file, error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
markdown_file	character(len=*)	in		Output file name for saving man page.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

errored

Trig error occurrence and print meaningful message.

subroutine errored(self, error, pref, group, switch, position)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		Object data.
error	integer(kind=I4P)	in		Error occurred.
pref	character(len=*)	in	optional	Prefixing string.
group	character(len=*)	in	optional	Group name.
switch	character(len=*)	in	optional	CLA switch name.
position	integer(kind=I4P)	in	optional	Position of the command line argument.

Call graph

finalize

Free dynamic memory when finalizing.

Attributes: elemental

subroutine finalize(self)

Arguments

Name	Type	Intent	Attributes	Description
self	type(command_line_interface)	inout		CLI data.

quiet_stop

End the program with an exit status, printing nothing (help/version/markdown: 0; no arguments: 2).

F2018 stop code, quiet=.true.; nvfortran 26.5 rejects quiet= and prints "FORTRAN STOP" on a plain stop, so it uses its exit extension (B33 of #125).

subroutine quiet_stop(code)

Arguments

Name	Type	Intent	Attributes	Description
code	integer(kind=I4P)	in		Exit status.

Call graph

write_script

Write a script (or any text) to a file. With error, a failure is reported (and its message in iomsg); without, it stops the program as any unchecked Fortran I/O.

subroutine write_script(file, script, error, iomsg)

Arguments

Name	Type	Intent	Attributes	Description
file	character(len=*)	in		File name.
script	character(len=*)	in		Text.
error	integer(kind=I4P)	out	optional	Error trapping flag.
iomsg	character(len=:)	out	allocatable, optional	Message of a failure.

Call graph

Functions

get_source

Return the source of the value of a CLA (SOURCE_COMMANDLINE, _ENVIRONMENT, _CONFIG, _DEFAULT, _NONE; F06 of #125).

Like get, it parses first if parse has not been called; an undefined CLA or group returns SOURCE_NONE with the error.

Returns: integer(kind=I4P)

function get_source(self, group, switch, position, pref, error) result(source)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.
pref	character(len=*)	in	optional	Prefixing string.
error	integer(kind=I4P)	out	optional	Error trapping flag.

Call graph

provenance

Return a report of every value with its source, for a run log (F06 of #125): one line per visible option of the top level and of the called commands, name = value [source], the environment and configuration sources naming their variable and file. Builtins and hidden options are left out; like get, it parses first if parse has not been called.

With format='json' the report is a JSON document, the run manifest (#128): no date, host or directory, so that the same inputs give the same bytes. Any other format is the text report.

Returns: character(len=:)

function provenance(self, pref, format) result(report)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
pref	character(len=*)	in	optional	Prefixing string.
format	character(len=*)	in	optional	Format of the report: text (default) or json.

Call graph

provenance_text

Return the text report of provenance.

Returns: character(len=:)

function provenance_text(self) result(report)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.

Call graph

provenance_json

Return the JSON report of provenance, the run manifest (#128).

Returns: character(len=:)

function provenance_json(self) result(report)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.

Call graph

provenance_arguments

Return the command line in JSON, the values of the sensitive options masked; null when a sensitive positional exists, since a token cannot be told to be its value without parsing again.

Returns: character(len=:)

function provenance_arguments(self) result(json)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.

Call graph

envvar_name

Return the generated name of an environment variable: PREFIX[_GROUP]NAME, upper case, NAME being the switch without its leading dashes, '-' becoming '' (auto_envvar_prefix, F07 of #125; click's rule).

Attributes: pure

Returns: character(len=:)

function envvar_name(prefix, group, switch) result(name)

Arguments

Name	Type	Intent	Attributes	Description
prefix	character(len=*)	in		Prefix.
group	character(len=*)	in		Group (command), '' for the top level.
switch	character(len=*)	in		Switch.

Call graph

is_passed

Check if a CLA has been passed.

Returns: logical

function is_passed(self, group, switch, position)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
group	character(len=*)	in	optional	Name of group (command) of CLA.
switch	character(len=*)	in	optional	Switch name.
position	integer(kind=I4P)	in	optional	Position of positional CLA.

Call graph

is_defined_group

Check if a CLAs group has been defined.

Returns: logical

function is_defined_group(self, group, g) result(defined)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
group	character(len=*)	in		Name of group (command) of CLAs.
g	integer(kind=I4P)	out	optional	Index of group, -1 if not defined.

Call graph

group_index

Return the index of the group (command) with a name, -1 if there is none: the one resolver of group names.

The top level is the group 0, named ''. A command matches by its name or an alias (F19); trailing blanks are not significant; the match is case sensitive, in any case with case_insensitive (F14).

Attributes: pure

Returns: integer(kind=I4P)

function group_index(self, name) result(g)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
name	character(len=*)	in		Name of group (command).

Call graph

raise_error

Report an application error in FLAP's style (prefix, colours, error unit) and return ERROR_USER; never stop (F17 of #125).

For validation only the application can do (e.g. "--nx must be even"); by default the help (of group) follows the message, as init(usage_on_error=) chooses (the whole help, its usage line, nothing). An undefined group returns ERROR_MISSING_GROUP and prints nothing.

Returns: integer(kind=I4P)

function raise_error(self, message, switch, group, show_usage) result(error)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
message	character(len=*)	in		Error message.
switch	character(len=*)	in	optional	Offending switch, prefixing the message.
group	character(len=*)	in	optional	Group (command) whose usage is printed (default: top level).
show_usage	logical	in	optional	Print the usage after the message (default .true.).

Call graph

is_called_group

Check if a CLAs group has been run.

Returns: logical

function is_called_group(self, group) result(called)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
group	character(len=*)	in		Name of group (command) of CLAs.

Call graph

is_defined

Check if a CLA has been defined.

Returns: logical

function is_defined(self, switch, group)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
switch	character(len=*)	in		Switch name.
group	character(len=*)	in	optional	Name of group (command) of CLAs.

Call graph

is_dry_run

Check if --dry-run has been passed (#129), parsing first if parse has not been called. The program must then skip its side effects: FLAP cannot do that for it. False if init(dry_run_option=) is not set, or if the program defines its own --dry-run.

Returns: logical

function is_dry_run(self, pref) result(dry_run)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
pref	character(len=*)	in	optional	Prefixing string.

Call graph

dry_run_passed

Check if the --dry-run builtin is on the parsed command line.

Attributes: pure

Returns: logical

function dry_run_passed(self) result(passed)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.

Call graph

exit_status

Return the exit status for the current error or status (#129), for stop cli%exit_status(). FLAP ends the program on an error only with --check: otherwise the program does.

Attributes: elemental

Returns: integer(kind=I4P)

function exit_status(self) result(status)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.

Call graph

is_parsed

Check if CLI has been parsed.

Attributes: elemental

Returns: logical

function is_parsed(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.

check_requested

Check if --check is on the command line, before a -- and before the first command: by its token, since an earlier error may have stopped the parse before reaching it, and the exit status must not depend on that (#128). A status of a builtin leaves it to that builtin.

Returns: logical

function check_requested(self) result(requested)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.

Call graph

no_args_help

Print the help when no arguments are passed (no_args_is_help), or when a command with the flag is invoked alone.

The status is STATUS_NO_ARGS; in standalone mode (default) the program ends with exit status 2 (a usage error, as in click), silently (quiet_stop).

Returns: logical

function no_args_help(self, ai, pref) result(printed)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
ai	integer(kind=I4P)	in		CLAs grouped indexes.
pref	character(len=*)	in	optional	Prefixing string.

Call graph

dispatch_status

Print the help (of the first group that asked for it), the version or the markdown, in this order (D3 of #125).

In standalone mode (default) the program stops; otherwise the status is left in self%error for parse to return.

Returns: logical

function dispatch_status(self, pref) result(dispatched)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
pref	character(len=*)	in	optional	Prefixing string.

Call graph

completion_shell

Return the shell of a completion builtin (F24 of #125): its value, else the basename of $SHELL; pwsh is powershell. An unknown or unset shell is ERROR_COMPLETION_SHELL (printed), and '' is returned.

Returns: character(len=:)

function completion_shell(self, act, pref) result(shell)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
act	character(len=*)	in		Action of the builtin.
pref	character(len=*)	in	optional	Prefixing string.

Call graph

usage_on_error_is

Check init(usage_on_error=) (F27; any case, 'full' when unset).

Returns: logical

function usage_on_error_is(self, mode) result(is)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
mode	character(len=*)	in		'FULL', 'USAGE' or 'NONE'.

Call graph

is_fatal

Check if the current error stops parsing: any error but an unknown argument that is ignored (then recorded as such).

Returns: logical

function is_fatal(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.

Call graph

top_builtin

Check if the top level has a builtin of this switch and action (not an option of the program with the same name).

Returns: logical

function top_builtin(self, switch, act) result(is)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
switch	character(len=*)	in		Switch name.
act	character(len=*)	in		Action of the builtin.

Call graph

map_cla

Locate the CLA of a map getter, parsing first if needed: false (with the error set) if the parse failed or the group or the switch is not defined.

Returns: logical

function map_cla(self, switch, group, pref, args, g, a) result(ok)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	inout		CLI data.
switch	character(len=*)	in		Switch name.
group	character(len=*)	in	optional	Name of group (command) of CLA.
pref	character(len=*)	in	optional	Prefixing string.
args	character(len=*)	in	optional	String containing command line arguments.
g	integer(kind=I4P)	out		Index of the group.
a	integer(kind=I4P)	out		Index of the CLA.

Call graph

builtins_missing

Check if the builtin CLAs still have to be added (the hidden "--" is added last, in every group).

Returns: logical

function builtins_missing(self) result(missing)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.

Call graph

usage

Get CLI usage, builtins included whether or not parse has been called.

Returns: character(len=:)

function usage(self, g, pref, no_header, no_examples, no_epilog, markdown) result(usaged)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
g	integer(kind=I4P)	in		Group index.
pref	character(len=*)	in	optional	Prefixing string.
no_header	logical	in	optional	Avoid insert header to usage.
no_examples	logical	in	optional	Avoid insert examples to usage.
no_epilog	logical	in	optional	Avoid insert epilogue to usage.
markdown	logical	in	optional	Format things with markdown

Call graph

signature

Get CLI signature, builtins included whether or not parse has been called.

Returns: character(len=:)

function signature(self, bash_completion)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
bash_completion	logical	in	optional	Return the signature for bash completion.

Call graph

completion_script

Return the completion script of a shell (bash, zsh, fish, powershell; '' for another), builtins included whether or not parse has been called (F15, F24 of #125).

Returns: character(len=:)

function completion_script(self, shell) result(script)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
shell	character(len=*)	in		Shell.

Call graph

completion_script_core

Return the completion script of a shell (builtins already present).

Returns: character(len=:)

function completion_script_core(self, shell) result(script)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
shell	character(len=*)	in		Shell.

Call graph

fish_script

Return the fish completion script (F15 of #125): one complete line per option, commands and aliases first.

Returns: character(len=:)

function fish_script(self) result(script)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.

Call graph

powershell_script

Return the PowerShell completion script (F15 of #125): a native argument completer with the tables of the commands (names and aliases) and of the options of each group; it completes the choices after an option, nothing after another option taking a value (PowerShell then completes paths), otherwise the options and, at the top level, the commands.

Returns: character(len=:)

function powershell_script(self) result(script)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.

Call graph

error_description

Return the meaning of an error code, as in the table of docs/guide/errors.md (flap_test_json_schema compares them); '' for an unknown code. The JSON description of the CLI publishes it.

Attributes: pure

Returns: character(len=:)

function error_description(code) result(description)

Arguments

Name	Type	Intent	Attributes	Description
code	integer(kind=I4P)	in		Error code.

Call graph

json_schema

Return the JSON description of the CLI (#128). It needs no copy with the builtins, unlike the other outputs: it leaves them out, and it reads no state of a parse, so that it is the same before and after parse.

With group, a command by its name or alias, only that command (#129); '' if there is no such command.

Returns: character(len=:)

function json_schema(self, group) result(json)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
group	character(len=*)	in	optional	Name of a command.

Call graph

skill

Return a SKILL.md (Agent Skills format, #129) describing the program: name and description first, then the options of the top level, one line per command, the machine-readable options enabled and the exit statuses. The detail stays in the program, read on demand: a skill is loaded whole. Like json_schema, it needs no copy with the builtins and reads no parse state.

Returns: character(len=:)

function skill(self) result(text)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.

Call graph

exclusive_of

Return the command excluded by a command, '' for none. parse makes the relation symmetric: the same answer before it.

Returns: character(len=:)

function exclusive_of(self, g) result(excluded)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
g	integer(kind=I4P)	in		Group index.

Call graph

usage_core

Print correct usage of CLI.

Returns: character(len=:)

function usage_core(self, g, pref, no_header, no_examples, no_epilog, markdown) result(usaged)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
g	integer(kind=I4P)	in		Group index.
pref	character(len=*)	in	optional	Prefixing string.
no_header	logical	in	optional	Avoid insert header to usage.
no_examples	logical	in	optional	Avoid insert examples to usage.
no_epilog	logical	in	optional	Avoid insert epilogue to usage.
markdown	logical	in	optional	Format things with markdown

Call graph

signature_core

Get signature.

Returns: character(len=:)

function signature_core(self, bash_completion) result(signature)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
bash_completion	logical	in	optional	Return the signature for bash completion.

Call graph

bash_script

Return the bash completion script (for named CLAs only), registered with complete -o default (an empty completion falls back to file names, F15 of #125); with zsh, the same script behind zsh's bashcompinit.

Returns: character(len=:)

function bash_script(self, zsh) result(script)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_interface)	in		CLI data.
zsh	logical	in		The zsh script.

Call graph

provenance_name

Return the name of a CLA in the provenance reports.

Returns: character(len=:)

function provenance_name(cla) result(name)

Arguments

Name	Type	Intent	Attributes	Description
cla	type(command_line_argument)	in		CLA data.

Call graph

completion_function

Name of the bash (and zsh) completion function of a program, _<basename>_completion, the basename made an identifier (any character but a letter, a digit or _ becomes _): one function per program, so that two FLAP programs complete in the same shell (B41 of #126).

Attributes: pure

Returns: character(len=:)

function completion_function(progname) result(name)

Arguments

Name	Type	Intent	Attributes	Description
progname	character(len=*)	in		Program name.

Call graph

program_basename

Return the program name without its path (separated by '/' or a backslash).

Attributes: pure

Returns: character(len=:)

function program_basename(progname) result(basename)

Arguments

Name	Type	Intent	Attributes	Description
progname	character(len=*)	in		Program name.

Call graph