cmdgraph Module

Library version. major and minor are synchronised across all implementations; patch may differ per implementation. Compile-time library version constant. Declarative argument specification attached to a command. Preferred over direct initialisation — use the arg_is_int / arg_is_real / arg_is_char / arg_is_rest constructor functions. When a command has an args= spec the engine validates count and types before invoking the action; failure short-circuits with RC_ERROR. Read-only description of one command in the current state, returned by engine_t%available_commands. The result depends only on the state name; safe to cache keyed by state name after finalize. State-graph driven command interpreter.

Typical usage:

 type(engine_t) :: eng
 call eng%add_state("root", prompt="> ")
 call eng%add_command("root", "q(uit)", EDGE_QUIT, help="exit")
 call eng%finalize("root")
 call eng%run()

Construct, populate, finalize, then run — in that order. Calling dispatch or run before finalize is undefined behaviour.


Uses

Used by


Variables

Type Visibility Attributes Name Initial
type(version_t), public, parameter :: CMDGRAPH_VERSION = version_t(1, 0, 0)
integer, public, parameter :: ARG_INT = 1

Integer token
integer, public, parameter :: ARG_REAL = 2

Floating-point token (accepts d/D Fortran-style exponent)
integer, public, parameter :: ARG_CHAR = 3

Word or double-quoted string (quotes stripped) Verbatim remainder of the line — no tokenising or unquoting. Must be the last spec slot.
integer, public, parameter :: ARG_REST = 4
integer, public, parameter :: QUIET_UNIT = -1
integer, public, parameter :: EDGE_ACTION = 1

Invoke proc; stay in current state
integer, public, parameter :: EDGE_GOTO = 2

Push target state with empty context (no proc)
integer, public, parameter :: EDGE_DO_GOTO = 3

Invoke proc; non-empty return value pushes target with that value as context
integer, public, parameter :: EDGE_POP = 4

Pop the stack — the canonical back/esc path (no proc)
integer, public, parameter :: EDGE_DO_POP = 5

Invoke proc, then pop on success (commit-and-return)
integer, public, parameter :: EDGE_QUIT = 6

Exit the engine
integer, public, parameter :: RC_OK = 0

Action ran, DoGoto stayed, help shown, or blank line
integer, public, parameter :: RC_UNKNOWN = 1

No command matched the input
integer, public, parameter :: RC_AMBIGUOUS = 2

Multiple commands matched — input was a common prefix
integer, public, parameter :: RC_TRANSITIONED = 3

State changed: Goto pushed, DoGoto succeeded, or Pop returned
integer, public, parameter :: RC_EXITED = 4

Engine stopped: Quit, stack exhausted, or already dead
integer, public, parameter :: RC_ERROR = 5

Action returned an error, or arg validation failed

Return value from an action proc. Use action_ok / action_error rather than direct initialisation.

Interfaces

interface

Add a concrete state (has a prompt) or abstract state (mix-in, no prompt). Add a command edge to state. Build an integer arg_spec_t. Build a real arg_spec_t. Build a character arg_spec_t. Build a rest arg_spec_t (verbatim remainder of the line; must be last). Return n copies of an integer spec (fixed-size tuple, e.g. a 2D point). Return n copies of a real spec. Successful result, optionally carrying a DoGoto context string. Error result, optionally with a message written to the error channel. Merge all commands from abstract state included into state. The state's own commands override included ones with the same spec. Register a hook called after every successful transition into state. Validate the graph and set the initial state. Sets stat non-zero if a cycle is detected in goto/do_goto edges or if any state reference is unresolved. Run an interactive loop reading from the configured input stream. Execute commands from path, stopping at the first error. Returns .true. if the file ran to completion (or ended with quit). Rewind to the initial state without rebuilding the graph. Clears the stack, contexts, last_message, and last_error. Redirect I/O channels. Pass QUIET_UNIT to suppress a channel. Default: stdin / stdout / stderr. Dispatch one line of input. Performs prefix matching, arg validation, and edge traversal. Name of the active state. Context of the active state. Returns .false. after Quit or stack exhausted. Commands visible in the current state (own + included, help/? excluded). Result depends only on the state name; safe to cache keyed by state name. State names on the stack, bottom-first.

  • public module function arg_is_int(name, optional) result(s)

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: name
    logical, intent(in), optional :: optional

    Return Value type(arg_spec_t)

interface

Add a concrete state (has a prompt) or abstract state (mix-in, no prompt). Add a command edge to state. Build an integer arg_spec_t. Build a real arg_spec_t. Build a character arg_spec_t. Build a rest arg_spec_t (verbatim remainder of the line; must be last). Return n copies of an integer spec (fixed-size tuple, e.g. a 2D point). Return n copies of a real spec. Successful result, optionally carrying a DoGoto context string. Error result, optionally with a message written to the error channel. Merge all commands from abstract state included into state. The state's own commands override included ones with the same spec. Register a hook called after every successful transition into state. Validate the graph and set the initial state. Sets stat non-zero if a cycle is detected in goto/do_goto edges or if any state reference is unresolved. Run an interactive loop reading from the configured input stream. Execute commands from path, stopping at the first error. Returns .true. if the file ran to completion (or ended with quit). Rewind to the initial state without rebuilding the graph. Clears the stack, contexts, last_message, and last_error. Redirect I/O channels. Pass QUIET_UNIT to suppress a channel. Default: stdin / stdout / stderr. Dispatch one line of input. Performs prefix matching, arg validation, and edge traversal. Name of the active state. Context of the active state. Returns .false. after Quit or stack exhausted. Commands visible in the current state (own + included, help/? excluded). Result depends only on the state name; safe to cache keyed by state name. State names on the stack, bottom-first.

  • public module function arg_is_real(name, optional) result(s)

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: name
    logical, intent(in), optional :: optional

    Return Value type(arg_spec_t)

interface

Add a concrete state (has a prompt) or abstract state (mix-in, no prompt). Add a command edge to state. Build an integer arg_spec_t. Build a real arg_spec_t. Build a character arg_spec_t. Build a rest arg_spec_t (verbatim remainder of the line; must be last). Return n copies of an integer spec (fixed-size tuple, e.g. a 2D point). Return n copies of a real spec. Successful result, optionally carrying a DoGoto context string. Error result, optionally with a message written to the error channel. Merge all commands from abstract state included into state. The state's own commands override included ones with the same spec. Register a hook called after every successful transition into state. Validate the graph and set the initial state. Sets stat non-zero if a cycle is detected in goto/do_goto edges or if any state reference is unresolved. Run an interactive loop reading from the configured input stream. Execute commands from path, stopping at the first error. Returns .true. if the file ran to completion (or ended with quit). Rewind to the initial state without rebuilding the graph. Clears the stack, contexts, last_message, and last_error. Redirect I/O channels. Pass QUIET_UNIT to suppress a channel. Default: stdin / stdout / stderr. Dispatch one line of input. Performs prefix matching, arg validation, and edge traversal. Name of the active state. Context of the active state. Returns .false. after Quit or stack exhausted. Commands visible in the current state (own + included, help/? excluded). Result depends only on the state name; safe to cache keyed by state name. State names on the stack, bottom-first.

  • public module function arg_is_char(name, optional) result(s)

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: name
    logical, intent(in), optional :: optional

    Return Value type(arg_spec_t)

interface

Add a concrete state (has a prompt) or abstract state (mix-in, no prompt). Add a command edge to state. Build an integer arg_spec_t. Build a real arg_spec_t. Build a character arg_spec_t. Build a rest arg_spec_t (verbatim remainder of the line; must be last). Return n copies of an integer spec (fixed-size tuple, e.g. a 2D point). Return n copies of a real spec. Successful result, optionally carrying a DoGoto context string. Error result, optionally with a message written to the error channel. Merge all commands from abstract state included into state. The state's own commands override included ones with the same spec. Register a hook called after every successful transition into state. Validate the graph and set the initial state. Sets stat non-zero if a cycle is detected in goto/do_goto edges or if any state reference is unresolved. Run an interactive loop reading from the configured input stream. Execute commands from path, stopping at the first error. Returns .true. if the file ran to completion (or ended with quit). Rewind to the initial state without rebuilding the graph. Clears the stack, contexts, last_message, and last_error. Redirect I/O channels. Pass QUIET_UNIT to suppress a channel. Default: stdin / stdout / stderr. Dispatch one line of input. Performs prefix matching, arg validation, and edge traversal. Name of the active state. Context of the active state. Returns .false. after Quit or stack exhausted. Commands visible in the current state (own + included, help/? excluded). Result depends only on the state name; safe to cache keyed by state name. State names on the stack, bottom-first.

  • public module function arg_is_rest(name, optional) result(s)

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: name
    logical, intent(in), optional :: optional

    Return Value type(arg_spec_t)

interface

Add a concrete state (has a prompt) or abstract state (mix-in, no prompt). Add a command edge to state. Build an integer arg_spec_t. Build a real arg_spec_t. Build a character arg_spec_t. Build a rest arg_spec_t (verbatim remainder of the line; must be last). Return n copies of an integer spec (fixed-size tuple, e.g. a 2D point). Return n copies of a real spec. Successful result, optionally carrying a DoGoto context string. Error result, optionally with a message written to the error channel. Merge all commands from abstract state included into state. The state's own commands override included ones with the same spec. Register a hook called after every successful transition into state. Validate the graph and set the initial state. Sets stat non-zero if a cycle is detected in goto/do_goto edges or if any state reference is unresolved. Run an interactive loop reading from the configured input stream. Execute commands from path, stopping at the first error. Returns .true. if the file ran to completion (or ended with quit). Rewind to the initial state without rebuilding the graph. Clears the stack, contexts, last_message, and last_error. Redirect I/O channels. Pass QUIET_UNIT to suppress a channel. Default: stdin / stdout / stderr. Dispatch one line of input. Performs prefix matching, arg validation, and edge traversal. Name of the active state. Context of the active state. Returns .false. after Quit or stack exhausted. Commands visible in the current state (own + included, help/? excluded). Result depends only on the state name; safe to cache keyed by state name. State names on the stack, bottom-first.

  • public module function arg_int_n(name, n) result(s)

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: name
    integer, intent(in) :: n

    Return Value type(arg_spec_t), allocatable, (:)

interface

Add a concrete state (has a prompt) or abstract state (mix-in, no prompt). Add a command edge to state. Build an integer arg_spec_t. Build a real arg_spec_t. Build a character arg_spec_t. Build a rest arg_spec_t (verbatim remainder of the line; must be last). Return n copies of an integer spec (fixed-size tuple, e.g. a 2D point). Return n copies of a real spec. Successful result, optionally carrying a DoGoto context string. Error result, optionally with a message written to the error channel. Merge all commands from abstract state included into state. The state's own commands override included ones with the same spec. Register a hook called after every successful transition into state. Validate the graph and set the initial state. Sets stat non-zero if a cycle is detected in goto/do_goto edges or if any state reference is unresolved. Run an interactive loop reading from the configured input stream. Execute commands from path, stopping at the first error. Returns .true. if the file ran to completion (or ended with quit). Rewind to the initial state without rebuilding the graph. Clears the stack, contexts, last_message, and last_error. Redirect I/O channels. Pass QUIET_UNIT to suppress a channel. Default: stdin / stdout / stderr. Dispatch one line of input. Performs prefix matching, arg validation, and edge traversal. Name of the active state. Context of the active state. Returns .false. after Quit or stack exhausted. Commands visible in the current state (own + included, help/? excluded). Result depends only on the state name; safe to cache keyed by state name. State names on the stack, bottom-first.

  • public module function arg_real_n(name, n) result(s)

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: name
    integer, intent(in) :: n

    Return Value type(arg_spec_t), allocatable, (:)

interface

Add a concrete state (has a prompt) or abstract state (mix-in, no prompt). Add a command edge to state. Build an integer arg_spec_t. Build a real arg_spec_t. Build a character arg_spec_t. Build a rest arg_spec_t (verbatim remainder of the line; must be last). Return n copies of an integer spec (fixed-size tuple, e.g. a 2D point). Return n copies of a real spec. Successful result, optionally carrying a DoGoto context string. Error result, optionally with a message written to the error channel. Merge all commands from abstract state included into state. The state's own commands override included ones with the same spec. Register a hook called after every successful transition into state. Validate the graph and set the initial state. Sets stat non-zero if a cycle is detected in goto/do_goto edges or if any state reference is unresolved. Run an interactive loop reading from the configured input stream. Execute commands from path, stopping at the first error. Returns .true. if the file ran to completion (or ended with quit). Rewind to the initial state without rebuilding the graph. Clears the stack, contexts, last_message, and last_error. Redirect I/O channels. Pass QUIET_UNIT to suppress a channel. Default: stdin / stdout / stderr. Dispatch one line of input. Performs prefix matching, arg validation, and edge traversal. Name of the active state. Context of the active state. Returns .false. after Quit or stack exhausted. Commands visible in the current state (own + included, help/? excluded). Result depends only on the state name; safe to cache keyed by state name. State names on the stack, bottom-first.

  • public module function action_ok(ctx) result(rv)

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in), optional :: ctx

    Return Value type(action_result_t)

interface

Add a concrete state (has a prompt) or abstract state (mix-in, no prompt). Add a command edge to state. Build an integer arg_spec_t. Build a real arg_spec_t. Build a character arg_spec_t. Build a rest arg_spec_t (verbatim remainder of the line; must be last). Return n copies of an integer spec (fixed-size tuple, e.g. a 2D point). Return n copies of a real spec. Successful result, optionally carrying a DoGoto context string. Error result, optionally with a message written to the error channel. Merge all commands from abstract state included into state. The state's own commands override included ones with the same spec. Register a hook called after every successful transition into state. Validate the graph and set the initial state. Sets stat non-zero if a cycle is detected in goto/do_goto edges or if any state reference is unresolved. Run an interactive loop reading from the configured input stream. Execute commands from path, stopping at the first error. Returns .true. if the file ran to completion (or ended with quit). Rewind to the initial state without rebuilding the graph. Clears the stack, contexts, last_message, and last_error. Redirect I/O channels. Pass QUIET_UNIT to suppress a channel. Default: stdin / stdout / stderr. Dispatch one line of input. Performs prefix matching, arg validation, and edge traversal. Name of the active state. Context of the active state. Returns .false. after Quit or stack exhausted. Commands visible in the current state (own + included, help/? excluded). Result depends only on the state name; safe to cache keyed by state name. State names on the stack, bottom-first.

  • public module function action_error(msg) result(rv)

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in), optional :: msg

    Return Value type(action_result_t)


Abstract Interfaces

abstract interface

Signature of an action or gate procedure. Signature of an on_enter hook. Called after every successful state transition.

  • public function action_fun(args, ctx) result(rv)

    Arguments

    Type IntentOptional Attributes Name
    type(dlist_t), intent(in) :: args

    Parsed, validated argument list
    character(len=*), intent(in) :: ctx

    Context string of the current state (set by the preceding DoGoto)

    Return Value type(action_result_t)

abstract interface

Signature of an action or gate procedure. Signature of an on_enter hook. Called after every successful state transition.

  • public subroutine on_enter_fun(ctx)

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: ctx

    Context string of the newly entered state

Derived Types

type, public ::  version_t

Components

Type Visibility Attributes Name Initial
integer, public :: major = 0

Breaking API change
integer, public :: minor = 0

Backwards-compatible feature addition
integer, public :: patch = 0

Bug fix

Type-Bound Procedures

procedure, public :: string => version_t_string

type, public ::  action_result_t

Components

Type Visibility Attributes Name Initial
logical, public :: errored = .false.

Set .true. to report an error
character(len=:), public, allocatable :: value

DoGoto context; unallocated or "" means no transition
character(len=:), public, allocatable :: errmsg

Written to error channel when errored; omit to leave last_error unchanged

type, public ::  arg_spec_t

Components

Type Visibility Attributes Name Initial
character(len=:), public, allocatable :: name

Displayed in help: <name:kind> or [name:kind]
integer, public :: kind = 0

ARG_INT, ARG_REAL, ARG_CHAR, or ARG_REST
logical, public :: optional = .false.

Trailing optionals may be omitted; positional only

type, public ::  command_info_t

Components

Type Visibility Attributes Name Initial
character(len=:), public, allocatable :: spec

Full spec string, e.g. p(airs)
character(len=:), public, allocatable :: req

Required prefix, e.g. p
character(len=:), public, allocatable :: opt

Optional suffix, e.g. airs
integer, public :: kind = EDGE_ACTION

EDGE_* constant
character(len=:), public, allocatable :: target

Destination state for Goto / DoGoto
type(arg_spec_t), public, allocatable :: args(:)
character(len=:), public, allocatable :: help

type, public ::  engine_t

Components

Type Visibility Attributes Name Initial
type(state_t), public, allocatable :: states(:)
integer, public :: build_error_stat = 0
character(len=:), public, allocatable :: build_error_msg
character(len=:), public, allocatable :: last_message

Last info/prompt string written to the output channel
character(len=:), public, allocatable :: last_error

Last error string written to the error channel

Type-Bound Procedures

procedure, public :: add_state => add_state_engine

Add a concrete or abstract state
procedure, public :: add_command => add_command_engine

Add a command edge to a state
procedure, public :: add_include => add_include_engine

Merge commands from an abstract state
procedure, public :: set_on_enter => set_on_enter_engine

Register a post-transition hook
procedure, public :: finalize => finalize_engine

Validate the graph and set initial state
procedure, public :: run => run_engine

Run an interactive loop on the configured input stream
procedure, public :: run_file => run_file_engine

Execute commands from a file, stopping at first error
procedure, public :: reset => reset_engine

Rewind to initial state without rebuilding the graph
procedure, public :: dispatch => dispatch_engine

Dispatch one line of input
procedure, public :: set_io_units => set_io_units_engine

Redirect I/O channels; pass QUIET_UNIT to suppress
procedure, public :: current_state => current_state_engine

Name of the active state
procedure, public :: current_context => current_context_engine

Context of the active state
procedure, public :: is_running => is_running_engine

False after Quit or stack exhausted
procedure, public :: available_commands => available_commands_engine

Commands visible in the current state
procedure, public :: state_path => state_path_engine

State names on the stack, bottom-first