cli_t Derived Type

type, public :: cli_t

A command line interface: what is accepted, and what was given.

Declare with set_program, add_option, add_flag and add_positional; fill with parse or parse_args; read with get, is_set and occurrences.


Inherits

type~~cli_t~~InheritsGraph type~cli_t cli_t type~entry_t entry_t type~cli_t->type~entry_t entries type~string_type string_type type~cli_t->type~string_type program_name, summary type~entry_t->type~string_type name, short, help, value, default

Components

Type Visibility Attributes Name Initial
integer(kind=default_int), private :: count = 0_default_int

Entries in use; entries may be longer.
type(entry_t), private, allocatable :: entries(:)

Declared entries, in registration order, so help_text is stable.
logical, private :: parsed = .false.

Set once a parse has completed, successfully or not.
type(string_type), private :: program_name

Name used in the usage line.
type(string_type), private :: summary

One-line description of the program.
logical, private :: wants_help = .false.

Set when -h or --help was seen.

Type-Bound Procedures

procedure, public :: add_flag => cli_add_flag

  • private subroutine cli_add_flag(this, name, help, short)

    Declare a flag, which takes no value.

    Read more…

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(inout) :: this
    character(len=*), intent(in) :: name

    Long name, given on the command line as --name.
    character(len=*), intent(in) :: help

    One-line description.
    character(len=*), intent(in), optional :: short

    Single-character short name.

procedure, public :: add_option => cli_add_option

  • private subroutine cli_add_option(this, name, help, short, default)

    Declare an option that takes a value.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(inout) :: this
    character(len=*), intent(in) :: name

    Long name, given on the command line as --name.
    character(len=*), intent(in) :: help

    One-line description.
    character(len=*), intent(in), optional :: short

    Single-character short name, given as -s.
    character(len=*), intent(in), optional :: default

    Value get returns when the option is absent; empty if omitted.

procedure, public :: add_positional => cli_add_positional

  • private subroutine cli_add_positional(this, name, help, required, default)

    Declare a positional argument, filled in registration order.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(inout) :: this
    character(len=*), intent(in) :: name

    Name used to read the value back, and in the usage line.
    character(len=*), intent(in) :: help

    One-line description.
    logical, intent(in), optional :: required

    Whether a parse without it is ERROR_VALIDATION; default false.
    character(len=*), intent(in), optional :: default

    Value get returns when the argument is absent.

generic, public :: get => get_string, get_char, get_int32, get_int64, get_real_sp, get_real_dp, get_logical

  • private subroutine cli_get_string(this, name, value, err)

    Read a value as a string_type.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    type(string_type), intent(out) :: value

    The last value given, or the declared default.
    type(error_t), intent(inout), optional :: err

    Set to ERROR_VALIDATION when name was never declared.

  • private subroutine cli_get_char(this, name, value, err)

    Read a value into a deferred-length character.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    character(len=:), intent(out), allocatable :: value

    The last value given, or the declared default.
    type(error_t), intent(inout), optional :: err

    Set to ERROR_VALIDATION when name was never declared.

  • private subroutine cli_get_int32(this, name, value, err)

    Read a value as integer(int32), strictly.

    Read more…

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    integer(kind=int32), intent(out) :: value

    Parsed value; zero when the conversion failed.
    type(error_t), intent(inout), optional :: err

    Set on an undeclared name or an unparsable value.

  • private subroutine cli_get_int64(this, name, value, err)

    Read a value as integer(int64), strictly.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    integer(kind=int64), intent(out) :: value

    Parsed value; zero when the conversion failed.
    type(error_t), intent(inout), optional :: err

    Set on an undeclared name or an unparsable value.

  • private subroutine cli_get_real_sp(this, name, value, err)

    Read a value as real(sp), strictly.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    real(kind=sp), intent(out) :: value

    Parsed value; zero when the conversion failed.
    type(error_t), intent(inout), optional :: err

    Set on an undeclared name or an unparsable value.

  • private subroutine cli_get_real_dp(this, name, value, err)

    Read a value as real(dp), strictly.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    real(kind=dp), intent(out) :: value

    Parsed value; zero when the conversion failed.
    type(error_t), intent(inout), optional :: err

    Set on an undeclared name or an unparsable value.

  • private subroutine cli_get_logical(this, name, value, err)

    Read a value as logical.

    Read more…

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    logical, intent(out) :: value

    Parsed value; false when the conversion failed.
    type(error_t), intent(inout), optional :: err

    Set on an undeclared name or an unrecognised spelling.

procedure, public :: has => cli_has

  • private pure function cli_has(this, name) result(r)

    Whether name was declared at all.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name to look for.

    Return Value logical

procedure, public :: help_requested => cli_help_requested

  • private pure function cli_help_requested(this) result(r)

    Whether -h or --help was given.

    Read more…

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this

    Return Value logical

procedure, public :: help_text => cli_help_text

  • private function cli_help_text(this) result(text)

    The help text, as a string. Nothing is printed; see the module note.

    Read more…

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this

    Return Value character(len=:), allocatable

procedure, public :: is_set => cli_is_set

  • private pure function cli_is_set(this, name) result(r)

    Whether name appeared on the command line.

    Read more…

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name to look for.

    Return Value logical

procedure, public :: occurrences => cli_occurrences

  • private pure function cli_occurrences(this, name) result(n)

    How many times name appeared on the command line.

    Read more…

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name to look for.

    Return Value integer(kind=default_int)

procedure, public :: parse => cli_parse

  • private subroutine cli_parse(this, err)

    Parse the real command line.

    Read more…

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(inout) :: this
    type(error_t), intent(inout), optional :: err

    Set on a parse or validation failure.

procedure, public :: parse_args => cli_parse_args

  • private subroutine cli_parse_args(this, args, err)

    Parse an explicit argument list.

    Read more…

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(inout) :: this
    type(string_type), intent(in) :: args(:)

    Arguments, excluding the program name.
    type(error_t), intent(inout), optional :: err

    Set on a parse or validation failure.

procedure, public :: set_program => cli_set_program

  • private subroutine cli_set_program(this, name, summary)

    Name and one-line description, used by help_text.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(inout) :: this
    character(len=*), intent(in) :: name

    Program name as it should appear in the usage line.
    character(len=*), intent(in) :: summary

    One-line description of what the program does.

procedure, private :: find => cli_find

  • private pure function cli_find(this, name) result(idx)

    Index of the entry with this long name, or 0.

    Read more…

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name to look for, without dashes.

    Return Value integer(kind=default_int)

procedure, private :: get_char => cli_get_char

  • private subroutine cli_get_char(this, name, value, err)

    Read a value into a deferred-length character.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    character(len=:), intent(out), allocatable :: value

    The last value given, or the declared default.
    type(error_t), intent(inout), optional :: err

    Set to ERROR_VALIDATION when name was never declared.

procedure, private :: get_int32 => cli_get_int32

  • private subroutine cli_get_int32(this, name, value, err)

    Read a value as integer(int32), strictly.

    Read more…

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    integer(kind=int32), intent(out) :: value

    Parsed value; zero when the conversion failed.
    type(error_t), intent(inout), optional :: err

    Set on an undeclared name or an unparsable value.

procedure, private :: get_int64 => cli_get_int64

  • private subroutine cli_get_int64(this, name, value, err)

    Read a value as integer(int64), strictly.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    integer(kind=int64), intent(out) :: value

    Parsed value; zero when the conversion failed.
    type(error_t), intent(inout), optional :: err

    Set on an undeclared name or an unparsable value.

procedure, private :: get_logical => cli_get_logical

  • private subroutine cli_get_logical(this, name, value, err)

    Read a value as logical.

    Read more…

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    logical, intent(out) :: value

    Parsed value; false when the conversion failed.
    type(error_t), intent(inout), optional :: err

    Set on an undeclared name or an unrecognised spelling.

procedure, private :: get_real_dp => cli_get_real_dp

  • private subroutine cli_get_real_dp(this, name, value, err)

    Read a value as real(dp), strictly.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    real(kind=dp), intent(out) :: value

    Parsed value; zero when the conversion failed.
    type(error_t), intent(inout), optional :: err

    Set on an undeclared name or an unparsable value.

procedure, private :: get_real_sp => cli_get_real_sp

  • private subroutine cli_get_real_sp(this, name, value, err)

    Read a value as real(sp), strictly.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    real(kind=sp), intent(out) :: value

    Parsed value; zero when the conversion failed.
    type(error_t), intent(inout), optional :: err

    Set on an undeclared name or an unparsable value.

procedure, private :: get_string => cli_get_string

  • private subroutine cli_get_string(this, name, value, err)

    Read a value as a string_type.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(in) :: this
    character(len=*), intent(in) :: name

    Long name of a declared entry.
    type(string_type), intent(out) :: value

    The last value given, or the declared default.
    type(error_t), intent(inout), optional :: err

    Set to ERROR_VALIDATION when name was never declared.

procedure, private :: reserve => cli_reserve

  • private subroutine cli_reserve(this)

    Make room for one more entry, doubling the store when it is full.

    Arguments

    Type IntentOptional Attributes Name
    class(cli_t), intent(inout) :: this

Source Code

   type :: cli_t
      !! A command line interface: what is accepted, and what was given.
      !!
      !! Declare with `set_program`, `add_option`, `add_flag` and
      !! `add_positional`; fill with `parse` or `parse_args`; read with `get`,
      !! `is_set` and `occurrences`.
      private
      type(string_type) :: program_name
         !! Name used in the usage line.
      type(string_type) :: summary
         !! One-line description of the program.
      type(entry_t), allocatable :: entries(:)
         !! Declared entries, in registration order, so `help_text` is stable.
      integer(default_int) :: count = 0_default_int
         !! Entries in use; `entries` may be longer.
      logical :: wants_help = .false.
         !! Set when `-h` or `--help` was seen.
      logical :: parsed = .false.
         !! Set once a parse has completed, successfully or not.
   contains
      procedure :: set_program => cli_set_program
      procedure :: add_option => cli_add_option
      procedure :: add_flag => cli_add_flag
      procedure :: add_positional => cli_add_positional
      procedure :: parse => cli_parse
      procedure :: parse_args => cli_parse_args
      procedure :: help_requested => cli_help_requested
      procedure :: help_text => cli_help_text
      procedure :: is_set => cli_is_set
      procedure :: occurrences => cli_occurrences
      procedure :: has => cli_has
      generic :: get => get_string, get_char, get_int32, get_int64, &
         get_real_sp, get_real_dp, get_logical

      procedure, private :: get_string => cli_get_string
      procedure, private :: get_char => cli_get_char
      procedure, private :: get_int32 => cli_get_int32
      procedure, private :: get_int64 => cli_get_int64
      procedure, private :: get_real_sp => cli_get_real_sp
      procedure, private :: get_real_dp => cli_get_real_dp
      procedure, private :: get_logical => cli_get_logical
      procedure, private :: find => cli_find
      procedure, private :: reserve => cli_reserve
   end type cli_t