flap_command_line_arguments_group_t

Command Line Arguments Group (CLAsG) class.

Source: src/lib/flap_command_line_arguments_group_t.f90

Dependencies

Contents

• exclusive_set
• command_line_arguments_group
• free
• check_maps
• check
• check_position_gaps
• is_required_passed
• add_exclusive_set
• check_exclusive_sets
• reset_parse
• resolve_values
• match_compact_count
• raise_error_m_exclude
• add
• parse
• errored
• check_m_exclusive
• sanitize_defaults
• finalize
• is_named
• has_alias
• completion_fish
• completion_powershell
• has_examples
• examples_text
• name_count
• name_of
• names
• is_passed
• positional_index
• config_key_index
• value_arity
• is_defined
• is_action_passed
• is_switch_token
• usage
• completion_skips
• signature
• exclusive_set_of
• exclusive_set_signature
• same

Variables

Name	Type	Attributes	Description
STATUS_PRINT_V	integer(kind=I4P)	parameter	Print version status.
STATUS_PRINT_H	integer(kind=I4P)	parameter	Print help status.
STATUS_PRINT_M	integer(kind=I4P)	parameter	Print help status to Markdown file.
STATUS_NO_ARGS	integer(kind=I4P)	parameter	No arguments passed, help printed (no_args_is_help).
STATUS_ALTERNATE	integer(kind=I4P)	parameter	An alternate action passed: value validation bypassed (F16).
STATUS_SHOW_COMPLETION	integer(kind=I4P)	parameter	--show-completion passed (F24).
STATUS_INSTALL_COMPLETION	integer(kind=I4P)	parameter	--install-completion passed (F24).
STATUS_PRINT_MAN	integer(kind=I4P)	parameter	--man passed: the man page saved (F29).
ERROR_CONSISTENCY	integer(kind=I4P)	parameter	CLAs group consistency error.
ERROR_M_EXCLUDE	integer(kind=I4P)	parameter	Two mutually exclusive CLAs group have been called.
ERROR_M_EXCLUDE_SET	integer(kind=I4P)	parameter	Two members of a mutually exclusive set have been passed.
ERROR_M_EXCLUDE_SET_REQUIRED	integer(kind=I4P)	parameter	No member of a required mutually exclusive set passed.
ERROR_M_EXCLUDE_SET_DEFINITION	integer(kind=I4P)	parameter	Invalid definition of a mutually exclusive set.
ERROR_POSITION_DUPLICATE	integer(kind=I4P)	parameter	Two positional CLAs declared at the same position.
ERROR_POSITION_GAP	integer(kind=I4P)	parameter	Declared positions are not 1..N: one is missing.

Derived Types

exclusive_set

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

Components

Name	Type	Attributes	Description
switches	character(len=:)	allocatable	Members, by their switch, as a stored list (LIST_SEP).
is_required	logical		Exactly one member must be passed.

command_line_arguments_group

Command Line Arguments Group (CLAsG) class.

CLAsG are useful for building nested commands.

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).
group	character(len=:)	allocatable	Group name (command).
Na	integer(kind=I4P)		Number of CLA.
Na_required	integer(kind=I4P)		Number of required command line arguments.
Na_optional	integer(kind=I4P)		Number of optional command line arguments.
cla	type(command_line_argument)	allocatable	CLA list [1:Na].
is_called	logical		Flag for checking if CLAs group has been passed to CLI.
no_args_is_help	logical		Print the help when invoked with no arguments.
m_sets	type(exclusive_set)	allocatable	Mutually exclusive sets of switches.
deprecated	character(len=:)	allocatable	Deprecation message of the command (F13).
aliases	type(flap_string)	allocatable	Aliases of the command (F19), aliases(i)%s.

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.
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.
is_named		Check if a name is the name of the group (command) or an alias.
has_alias		Check if a name is an alias of the group (command).
names		Name and aliases of the group (command), separated.
name_count		Number of names of the group (command): 1 + aliases.
has_examples		Check if the group (command) has examples.
completion_fish		Fish completion lines of the group (command) and its CLAs.
completion_powershell		PowerShell completion tables of the group (command).
examples_text		Examples of the group (command), for its help.
name_of		Name (1) or alias (2, ...) of the group (command).
check		Check data consistency.
check_position_gaps		Check that the declared positions have no gap.
is_required_passed		Check if required CLAs are passed.
add_exclusive_set		Add a mutually exclusive set of switches.
check_exclusive_sets		Check the mutually exclusive sets of switches.
check_maps		Check the KEY=VALUE pairs of the map CLAs.
is_passed		Check if a CLA has been passed.
is_defined		Check if a CLA has been defined.
is_switch_token		Check if a command line token names a CLA of the group.
is_action_passed		Check if a CLA with an action has been passed.
match_compact_count		Match the compact form -vvv of a count CLA.
positional_index		Index of the positional CLA declared at a position.
value_arity		Number of fixed value slots following a switch.
reset_parse		Forget the result of a parse, keeping the definitions.
resolve_values		Settle the source of the values not given on the command line.
config_key_index		Index of the CLA named by a configuration file key.
raise_error_m_exclude		Raise error mutually exclusive CLAs passed.
add		Add CLA to CLAsG.
parse		Parse CLAsG arguments.
usage		Get correct CLAsG usage.
signature		Get CLAsG signature.
completion_skips		Get the bash lines skipping the values of the switches (B37).
sanitize_defaults		Sanitize default values.
errored		Trig error occurrence and print meaningful message.
check_m_exclusive		Check if two mutually exclusive CLAs have been passed.
exclusive_set_of		Index of the mutually exclusive set of a CLA.
exclusive_set_signature		Usage signature of a mutually exclusive set.

Subroutines

free

Free dynamic memory.

Attributes: elemental

subroutine free(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	inout		CLAsG data.

Call graph

check_maps

Check the KEY=VALUE pairs of the map CLAs (F18 of #125), whatever their source; the first error stops.

subroutine check_maps(self, pref)

Arguments

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

Call graph

check

Check data consistency.

subroutine check(self, pref)

Arguments

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

Call graph

check_position_gaps

Check that the declared positions are 1..N without gaps (B29 of #125, D20).

Checked when parsing starts, not in add: positionals may be declared in any order.

subroutine check_position_gaps(self, pref)

Arguments

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

Call graph

is_required_passed

Check if required CLAs are passed; a missing one prints the group help after its message, unless print_usage is false (the CLI prints the usage line, or nothing: init(usage_on_error=), F27).

subroutine is_required_passed(self, pref, print_usage)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	inout		CLAsG data.
pref	character(len=*)	in	optional	Prefixing string.
print_usage	logical	in	optional	Print the group help after the error (default).

Call graph

add_exclusive_set

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

The members are comma separated and must be already defined, named switches (by switch or abbreviation, stored by their switch), not individually required, distinct and in no other set. An invalid set is not added: the error is ERROR_M_EXCLUDE_SET_DEFINITION.

subroutine add_exclusive_set(self, switches, required, pref)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	inout		CLAsG data.
switches	character(len=*)	in		Comma separated members.
required	logical	in	optional	Exactly one member must be passed (default .false.).
pref	character(len=*)	in	optional	Prefixing string.

Call graph

check_exclusive_sets

Check the mutually exclusive sets of a called group: at most one member given, exactly one for a required set.

Explicit sources count (command line, environment, configuration file; D2, E3 of #125), a default does not. When a member is on the command line, the environment and configuration values of the other members fall back to their defaults first, so that a value set for a batch job never makes a command line alternative a violation. Called after the statuses (help, version, markdown) and the value resolution, like the required check (E4 of #125).

subroutine check_exclusive_sets(self, pref, print_usage)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	inout		CLAsG data.
pref	character(len=*)	in	optional	Prefixing string.
print_usage	logical	in	optional	Print the group help after an error (default).

Call graph

reset_parse

Forget the result of a parse (called status, passed values, errors), keeping the definitions.

subroutine reset_parse(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	inout		CLAsG data.

Call graph

resolve_values

Settle the source of the values not given on the command line (the value-resolution chain R, F06 of #125).

Called after all groups are parsed, before the required check. The source of a parsed value (command line, or the environment for a bare switch with envvar) is recorded while parsing, so that it survives a parse stopped by an error. The others take, in order, the environment variable if set and not blank (F07), the configuration file (section = group name, key = switch without dashes; F08) if the value is not blank, the default, or nothing.

subroutine resolve_values(self, ignore_env, config, check_paths, lenient)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	inout		CLAsG data.
ignore_env	logical	in	optional	Turn every environment lookup off.
config	type(config_file)	in	optional	Configuration file.
check_paths	logical	in	optional	Check the path values (F09).
lenient	logical	in	optional	Ignore invalid environment lists (alternate, F16).

Call graph

match_compact_count

Match the compact form of a count, -vvv (D1 rule 3): a dash and one letter repeated, the letter forming the switch_ab -v of a count CLA. The caller uses it only when no switch matches the whole token (an exact switch wins).

Attributes: pure

subroutine match_compact_count(self, token, a, n)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
token	character(len=*)	in		Command line token.
a	integer(kind=I4P)	out		Index of the count CLA, 0 if no match.
n	integer(kind=I4P)	out		Occurrences (repetitions of the letter).

Call graph

raise_error_m_exclude

Raise error mutually exclusive CLAs passed.

subroutine raise_error_m_exclude(self, pref)

Arguments

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

Call graph

add

Add CLA to CLAs list.

@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.

subroutine add(self, pref, cla)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	inout		CLAsG data.
pref	character(len=*)	in	optional	Prefixing string.
cla	type(command_line_argument)	in		CLA data.

Call graph

parse

Parse CLAsG arguments.

subroutine parse(self, args, ignore_unknown_clas, pref, error_unknown_clas, ignore_env, commands)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	inout		CLAsG data.
args	character(len=*)	in		Command line arguments.
ignore_unknown_clas	logical	in		Disable errors-raising for passed unknown CLAs.
pref	character(len=*)	in	optional	Prefixing string.
error_unknown_clas	integer(kind=I4P)	out		Error flag for passed unknown CLAs.
ignore_env	logical	in	optional	Turn every environment lookup off.
commands	type(flap_string)	in	optional	Command names and aliases (top level), for the

Call graph

errored

Trig error occurrence and print meaningful message.

subroutine errored(self, error, pref, a1, a2, position, members, reason)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	inout		CLAsG data.
error	integer(kind=I4P)	in		Error occurred.
pref	character(len=*)	in	optional	Prefixing string.
a1	integer(kind=I4P)	in	optional	First index CLAs group inconsistent.
a2	integer(kind=I4P)	in	optional	Second index CLAs group inconsistent.
position	integer(kind=I4P)	in	optional	Position of positional CLAs.
members	character(len=*)	in	optional	Members of a mutually exclusive set.
reason	character(len=*)	in	optional	Why a mutually exclusive set is invalid.

Call graph

check_m_exclusive

Check if two mutually exclusive CLAs have been passed.

subroutine check_m_exclusive(self, pref)

Arguments

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

Call graph

sanitize_defaults

Sanitize defaults values.

It is necessary to sanitize the default values of non-passed, optional CLAs. Called or not: the getters read the defaults of a command not called too (#127), and the CLA sanitize is idempotent.

subroutine sanitize_defaults(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	inout		CLAsG data.

Call graph

finalize

Free dynamic memory when finalizing.

Attributes: elemental

subroutine finalize(self)

Arguments

Name	Type	Intent	Attributes	Description
self	type(command_line_arguments_group)	inout		CLAsG data.

Functions

is_named

Check if a name is the name of the group (command) or one of its aliases (F19 of #125). Trailing blanks are not significant; the case is, unless case_insensitive (F14).

Attributes: pure

Returns: logical

function is_named(self, name) result(named)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
name	character(len=*)	in		Name.

Call graph

has_alias

Check if a name is an alias of the group (command) (F19 of #125), with the case rule of is_named.

Attributes: pure

Returns: logical

function has_alias(self, name) result(alias)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
name	character(len=*)	in		Name.

Call graph

completion_fish

Get the fish completion lines of the group (F15 of #125): for a command, the line completing its names (while no command is typed) and its CLAs (once it is); for the top level, its CLAs (while no command is typed, if any).

Returns: character(len=:)

function completion_fish(self, prog, commands) result(lines)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
prog	character(len=*)	in		Program name.
commands	logical	in		The CLI has commands.

Call graph

completion_powershell

Get the PowerShell completion table rows of the group (F15 of #125): with commands, its names and aliases mapped to its name ('co' = 'compile'); otherwise its options, as the entry of the options table ('compile' = @(...)).

Returns: character(len=:)

function completion_powershell(self, commands) result(text)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
commands	logical	in		Return the command rows instead of the options.

Call graph

has_examples

Check if the group (command) has examples.

Attributes: pure

Returns: logical

function has_examples(self) result(has)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.

Call graph

examples_text

Return the examples of the group (command) for its help: a blank line, 'Examples:', one example per line.

Attributes: pure

Returns: character(len=:)

function examples_text(self, prefd) result(text)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
prefd	character(len=*)	in		Prefixing string.

Call graph

name_count

Return the number of names of the group (command): its name and its aliases (F19).

Attributes: pure

Returns: integer(kind=I4P)

function name_count(self) result(n)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.

Call graph

name_of

Return the i-th name of the group (command): 1 its name, 2... its aliases (F19).

Attributes: pure

Returns: character(len=:)

function name_of(self, i) result(name)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
i	integer(kind=I4P)	in		Index of the name.

Call graph

names

Return the name of the group (command) followed by its aliases, separated by sep (help listing, completion).

Attributes: pure

Returns: character(len=:)

function names(self, sep) result(list)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
sep	character(len=*)	in		Separator.

Call graph

is_passed

Check if a CLA has been passed.

Attributes: pure

Returns: logical

function is_passed(self, switch, position)

Arguments

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

Call graph

positional_index

Return the index of the positional CLA declared at a position, 0 if there is none.

Positionals are looked up by their declared position, never by their index in the CLA list.

Attributes: pure

Returns: integer(kind=I4P)

function positional_index(self, position) result(a)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
position	integer(kind=I4P)	in		Position of the positional CLA.

Call graph

config_key_index

Return the index of the CLA named by a configuration file key (its switch without dashes), 0 if none.

Returns: integer(kind=I4P)

function config_key_index(self, key) result(a)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
key	character(len=*)	in		Key.

Call graph

value_arity

Return the number of values that always follow a switch of this group, 0 if not fixed or not a switch.

Fixed: store with a required value (1) or with an integer nargs (N). Not fixed: flags, optional values, environment variables and variadic lists (nargs='+'/'*'), whose extent is decided while parsing.

Returns: integer(kind=I4P)

function value_arity(self, switch) result(n)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
switch	character(len=*)	in		Command line argument, maybe a switch.

Call graph

is_defined

Check if a CLA has been defined.

Returns: logical

function is_defined(self, switch, pos)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
switch	character(len=*)	in		Switch name.
pos	integer(kind=I4P)	out	optional	CLA position.

Call graph

is_action_passed

Check if a CLA with an action (e.g. print help) has been passed.

Attributes: pure

Returns: logical

function is_action_passed(self, act) result(passed)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
act	character(len=*)	in		Action.

Call graph

is_switch_token

Check if a command line token names a CLA of the group, also as NAME=VALUE: the look-ahead test of the parser.

Attributes: pure

Returns: logical

function is_switch_token(self, token)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
token	character(len=*)	in		Command line token.

Call graph

usage

Get correct CLAsG usage: the usage line, the description, then the positionals, the required and the optional switches.

One blank line between the parts; the positionals in their own part, in order of position (defects 2, 4, 8 of #126).

Returns: character(len=:)

function usage(self, pref, no_header, markdown)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
pref	character(len=*)	in	optional	Prefixing string.
no_header	logical	in	optional	Avoid insert header to usage.
markdown	logical	in	optional	Format things form markdown.

Call graph

completion_skips

Get the bash case lines skipping the fixed values of the switches of the group (value_arity, as the parser does), so that a value is never taken for a command name by the bash script (B37 of #125); '' if none.

Returns: character(len=:)

function completion_skips(self) result(lines)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.

Call graph

signature

Get CLAsG signature: the usage text, or the bash completion (a COMPREPLY line with the switches, then the value tests).

Returns: character(len=:)

function signature(self, bash_completion, plain)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
bash_completion	logical	in	optional	Return the signature for bash completion.
plain	logical	in	optional	Return the value tests as plain switches lists.

Call graph

exclusive_set_of

Return the index of the mutually exclusive set of a CLA, 0 if it is in none.

Attributes: pure

Returns: integer(kind=I4P)

function exclusive_set_of(self, a) result(s)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
a	integer(kind=I4P)	in		Index of the CLA.

Call graph

exclusive_set_signature

Return the usage signature of a mutually exclusive set, docopt style: (a | b) if required, [a | b] otherwise.

Returns: character(len=:)

function exclusive_set_signature(self, s) result(signature)

Arguments

Name	Type	Intent	Attributes	Description
self	class(command_line_arguments_group)	in		CLAsG data.
s	integer(kind=I4P)	in		Index of the set.

Call graph

same

Compare two names, trailing blanks not significant, in any case with case_insensitive (F14).

Attributes: pure

Returns: logical

function same(a, b, case_insensitive) result(equal)

Arguments

Name	Type	Intent	Attributes	Description
a	character(len=*)	in		First name.
b	character(len=*)	in		Second name.
case_insensitive	logical	in		Compare in any case.

Call graph