API Reference#

This section provides comprehensive documentation for all public types, procedures, and constants in the fclap library.

Main Public Interface#

fclap Module#

The main entry point module that re-exports all public symbols.

use fclap, only: ArgumentParser, Namespace

This is the only module users need to import for most use cases. It re-exports all public types, constants, and procedures from the internal modules.

Core Types#

ArgumentParser#

The main parser type for defining and parsing command-line arguments.

The core class for parsing command line arguments. This class handles the registration of arguments, parsing of the command line, and generation of help messages. It supports positional arguments, optional flags, subcommands, argument groups, and mutually exclusive options.

Type Components:

Component

Description

prog

Program name displayed in help/usage (character, allocatable)

description

Description text shown before arguments (character, allocatable)

epilog

Text shown after arguments in help (character, allocatable)

version

Version string for --version flag (character, allocatable)

add_help

Whether to add -h/--help automatically (logical, default: .true.)

Type-Bound Procedures:

init(self, prog, description, epilog, add_help, version)

Initialize the parser with optional configuration.

  • self: The ArgumentParser instance

  • prog: Optional program name (defaults to argv(0))

  • description: Optional description for help output

  • epilog: Optional text after arguments in help

  • add_help: Whether to add -h/–help (default: .true.)

  • version: Optional version string for –version

init_with_parents(self, parents, prog, description, epilog, add_help, version)

Initialize parser inheriting from parent parsers.

  • self: The ArgumentParser instance

  • parents: Array of parent parsers to inherit arguments from

  • prog: Optional program name

  • description: Optional description text

  • epilog: Optional epilog text

  • add_help: Whether to add help argument

  • version: Optional version string

add_argument(self, name1, name2, name3, name4, action, nargs, type_name, default_val, choices, required, help, metavar, dest, status, visible)

Add a new argument to the parser.

  • self: The ArgumentParser instance

  • name1: First option string or positional name

  • name2-4: Optional additional option strings

  • action: Action type (store, store_true, store_false, count, append, help, version)

  • nargs: Number of arguments to consume (integer or ARG_* constant)

  • type_name: Value type (string, int, real, logical)

  • default_val: Default value if not provided

  • choices: Array of valid choices

  • required: Whether argument is required

  • help: Help text for the argument

  • metavar: Display name in usage

  • dest: Destination name for storage

  • status: Argument status (STATUS_ACTIVE, STATUS_DEPRECATED, STATUS_REMOVED)

  • visible: Whether to show in help output

add_argument_group(self, title, description)

Create a new argument group for organizing help output. Returns the index of the created group (integer).

add_mutually_exclusive_group(self, required)

Create a mutually exclusive group. Returns the index of the created mutex group (integer).

add_subparsers(self, title, description, dest)

Enable subparser (subcommand) support.

add_parser(self, name, help_text)

Add a subparser (subcommand).

parse_args(self)

Parse command line arguments from the system. Returns a Namespace containing parsed values.

parse_args_array(self, argv)

Parse arguments from an array of strings. Returns a Namespace containing parsed values.

print_help(self)

Print the help message to stdout.

print_usage(self)

Print the usage message to stdout.

format_usage(self)

Format and return the usage string.

format_help(self)

Format and return the full help text.

Namespace#

Container for parsed argument values. Provides dictionary-like access to results.

The Namespace type stores the results of parse_args(). It behaves similarly to a dictionary or Python’s argparse.Namespace object, providing type-safe getter methods for retrieving argument values.

Type-Bound Procedures:

get_string(self, key, default)

Retrieve a string value by key.

  • key: The argument destination name

  • default: Optional default if key not found

  • Returns: The string value (character, allocatable)

get_integer(self, key, default)

Retrieve an integer value by key.

  • key: The argument destination name

  • default: Optional default if key not found (integer)

  • Returns: The integer value

get_real(self, key, default)

Retrieve a real value by key.

  • key: The argument destination name

  • default: Optional default if key not found (real)

  • Returns: The real value

get_logical(self, key, default)

Retrieve a logical value by key.

  • key: The argument destination name

  • default: Optional default if key not found (logical)

  • Returns: The logical value

get_string_list(self, key, values, count)

Retrieve a string list by key.

  • key: The argument destination name

  • values: Output array for the values

  • count: Output number of values retrieved

get_integer_list(self, key, values, count)

Retrieve an integer list by key.

has_key(self, key)

Check if a key exists and has a value. Returns: .true. if the key exists and has a value

show(self, unit)

Print namespace contents for debugging.

  • unit: Optional output unit (default: stdout)

Action#

Represents a single argument definition with all its properties.

The Action type encapsulates everything about an argument: how it appears on the command line, what type of value it expects, how many values it consumes, and what happens when it’s encountered.

Type Components:

Component

Description

dest

Destination name for storage

option_strings

Array of option flags (e.g., “-v”, “–verbose”)

nargs

Number of arguments to consume

help_text

Help description

required

Whether argument is required

default_value

Default value container

metavar

Display name in usage

choices

Array of valid choices

value_type

Expected value type

is_positional

Whether positional argument

action_type

Type of action to perform

Supporting Types#

ValueContainer#

Generic container for storing argument values of different types.

ValueContainer provides polymorphic storage for string, integer, real, and logical values. It also supports list storage for arguments that accept multiple values.

Type Components:

  • value_type - Type indicator (TYPE_STRING, TYPE_INTEGER, etc.)

  • string_value - String storage

  • integer_value - Integer storage

  • real_value - Real storage

  • logical_value - Logical storage

  • string_list - String array storage (for append/nargs)

  • integer_list - Integer array storage

  • real_list - Real array storage

  • list_count - Number of items in list

  • is_set - Whether value has been set

ArgumentGroup#

Organizes related arguments in the help output.

ArgumentGroup allows you to organize arguments into logical groups that appear together in the help output with a custom title and description.

Type Components:

  • title - Group title

  • description - Group description

  • required - Whether group is required

MutuallyExclusiveGroup#

Ensures only one argument from the group can be used.

A MutuallyExclusiveGroup ensures that only one of its member arguments can be used at a time. If the user specifies more than one, a parsing error will occur.

Type Components:

  • title - Group title

  • required - Whether one option must be chosen

fclap_error#

Error handling type for parser errors.

Stores error information including a message, the related argument name, and a flag indicating whether an error has occurred.

Type Components:

  • message - Error message

  • argument - Related argument name

  • has_error - Error state flag

Type-Bound Procedures:

init(self, message, argument)

Initialize error with message and optional argument.

report(self, unit)

Report error to output unit.

clear(self)

Clear the error state.

Constants#

Nargs Specifiers#

Control how many command-line arguments are consumed:

integer, parameter :: ARG_OPTIONAL     = -1  ! '?' - zero or one argument
integer, parameter :: ARG_ZERO_OR_MORE = -2  ! '*' - zero or more arguments
integer, parameter :: ARG_ONE_OR_MORE  = -3  ! '+' - one or more arguments
integer, parameter :: ARG_PARSER       = -4  ! For subparser mode
integer, parameter :: ARG_REMAINDER    = -5  ! '...' - all remaining arguments
integer, parameter :: ARG_SINGLE       = 1   ! Single argument (default)

Type Specifiers#

Identify the expected value type:

integer, parameter :: TYPE_STRING  = 1  ! Character string values
integer, parameter :: TYPE_INTEGER = 2  ! Integer values
integer, parameter :: TYPE_REAL    = 3  ! Real/floating-point values
integer, parameter :: TYPE_LOGICAL = 4  ! Boolean values

Action Types#

Specify what action to perform when argument is encountered:

integer, parameter :: ACT_STORE       = 1  ! Store single value (default)
integer, parameter :: ACT_STORE_TRUE  = 2  ! Store .true. when flag present
integer, parameter :: ACT_STORE_FALSE = 3  ! Store .false. when flag present
integer, parameter :: ACT_COUNT       = 4  ! Count flag occurrences
integer, parameter :: ACT_APPEND      = 5  ! Append value to list
integer, parameter :: ACT_HELP        = 6  ! Print help and exit
integer, parameter :: ACT_VERSION     = 7  ! Print version and exit

Argument Status#

Control argument lifecycle:

integer, parameter :: STATUS_ACTIVE     = 0  ! Normal active argument
integer, parameter :: STATUS_DEPRECATED = 1  ! Deprecated with warning
integer, parameter :: STATUS_REMOVED    = 2  ! Removed, will error

Group Types#

Identify argument group types:

integer, parameter :: GROUP_STANDARD = 1  ! Standard group for organization
integer, parameter :: GROUP_MUTEX    = 2  ! Mutually exclusive group

Special Values#

character(len=*), parameter :: SUPPRESS = "==SUPPRESS=="  ! Suppress default/help display

Utility Functions#

get_prog_name(override)

Get program name from command line.

  • override: Optional custom program name to use

  • Returns: The program name string

get_fclap_version(major, minor, patch)

Get fclap version components.

  • major: Major version number (output)

  • minor: Minor version number (output)

  • patch: Patch version number (output)

fclap_version_compact()

Get compact version string (e.g., “1.2.3”).

fclap_version_string()

Get full version string (e.g., “fclap version 1.2.3”).