Module to parse command line arguments. More...

Data Types
module	cli_parser
	This is a parser for command line arguments. More...

module	option
	This is a container for a single command line option. More...

Functions/Subroutines
type(cli_parser) function	new_cli_parser (prog, description, add_help_option, add_version_option, version, add_logger_options)
	Create a new cli_parser.

type(option) function	new_option (name, s_name, help, has_value, value_name, default, required, blank, repeated)
	Create a new option.

subroutine	add_option (self, name, s_name, help, has_value, value_name, default, required, blank, repeated)
	Add a new option to the cli_parser.

integer(i4) function	cnt_options (self)
	Get option count from the cli_parser.

logical function	is_given_arg (self, arg)
	check if this option is the given argument.

integer(i4) function	get_option_index (self, name, long, short, raise_error)
	Get the option index from cli_parser by name.

type(option) function	get_option (self, name)
	Get an option from cli_parser by name.

logical function	option_was_read (self, name)
	Whether the option was read by the cli_parser given by name.

integer(i4) function	option_read_count (self, name)
	Read count for the option in the cli_parser given by name.

logical function	has_option (self, name)
	Whether the option is defined in cli_parser given by name.

integer(i4) function	get_blank_option_index (self)
	Get the index of the blank option.

character(:) function, allocatable	option_value (self, name)
	Get the parsed value from an option by name from the cli_parser.

subroutine	print_info (self)
	Print info for an option.

subroutine	print_help (self)
	Print help message for the cli_parser.

subroutine	parse (self)
	Parse the given command line arguments with the cli_parser.

subroutine	parse_arg (arg, names, counts)
	Parse given argument.

integer(i4) function	findchar (array, chr)

Detailed Description

Module to parse command line arguments.

Version: 0.1

Authors: Sebastian Mueller

Date: May 2021

A simple parser for command line arguments. You can define options and then parse the given command. Option can be with or without passed values and they can be set as required.

The following example demonstrates the functionality:

program main
  use mo_cli, only: cli_parser
  implicit none
  type(cli_parser) :: parser
 
  parser = cli_parser( &
    description="This program has a CLI.", &
    add_version_option=.true., version="1.3")
  call parser%add_option( &
    "cwd", &
    blank=.true., &
    required=.true., &
    help="The working directory.")
  call parser%add_option( &
    name="file", &
    s_name="f", &
    has_value=.true., &
    value_name="path", &
    default="none", &
    help="Your file path.")
  call parser%add_option("opt", help="A switch")
 
  call parser%parse()
 
  print*, "file: ", parser%option_value("file")
  print*, "dir: ", parser%option_value("cwd")
  print*, "opt: ", parser%option_was_read("opt")
 
end program main

You can call the program with:

$ ./prog --opt -f file.txt /dir/
 file: file.txt
 dir: /dir/
 opt:  T

As you see, you can automatically create help and version options:

$ ./prog -h

$ ./prog -V

Copyright: Copyright 2005-2024, the CHS Developers, Sabine Attinger: All rights reserved. FORCES is released under the LGPLv3+ license

The UFZ (CHS) FORCES code is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the free Software Foundation either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You received a copy of the GNU Lesser General Public License along with the UFZ CHS FORCES code. It can be found in the files COPYING and COPYING.LESSER provided with this software. The complete GNU license text can also be found at http://www.gnu.org/licenses/.

Function/Subroutine Documentation

◆ add_option()

subroutine mo_cli::add_option	(	class(cli_parser), intent(inout)	self,
		character(*), intent(in)	name,
		character(1), intent(in), optional	s_name,
		character(*), intent(in), optional	help,
		logical, intent(in), optional	has_value,
		character(*), intent(in), optional	value_name,
		character(*), intent(in), optional	default,
		logical, intent(in), optional	required,
		logical, intent(in), optional	blank,
		logical, intent(in), optional	repeated
	)

private

Add a new option to the cli_parser.

Parameters

[in]	name	long name (will be double hyphenated: –opt)
[in]	s_name	short name (will be hyphenated: -o)
[in]	help	description of the option
[in]	has_value	whether the option has a value
[in]	value_name	name of the value for the help text (default "value")
[in]	default	default value for this option
[in]	required	whether the option is required
[in]	blank	whether the option is passed blank without hyphenated name (only latter one possible)
[in]	repeated	whether the option can be read repeatedly

Definition at line 263 of file mo_cli.f90.

◆ cnt_options()

integer(i4) function mo_cli::cnt_options ( class(cli_parser), intent(inout) self )

private

Get option count from the cli_parser.

Returns: Option count.

Definition at line 305 of file mo_cli.f90.

References cnt_options().

Referenced by cnt_options().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ findchar()

integer(i4) function mo_cli::findchar	(	character, dimension(:), intent(in)	array,
		character, intent(in)	chr
	)

private

Definition at line 653 of file mo_cli.f90.

◆ get_blank_option_index()

integer(i4) function mo_cli::get_blank_option_index ( class(cli_parser), intent(inout) self )

private

Get the index of the blank option.

Returns: The desired option index.

Definition at line 412 of file mo_cli.f90.

References get_blank_option_index().

Referenced by get_blank_option_index().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_option()

type(option) function mo_cli::get_option	(	class(cli_parser), intent(inout)	self,
		character(*), intent(in)	name
	)

private

Get an option from cli_parser by name.

Returns: The desired option.

Parameters

[in] name name (long or short) of the desired option

Definition at line 359 of file mo_cli.f90.

References get_option().

Referenced by get_option().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_option_index()

integer(i4) function mo_cli::get_option_index	(	class(cli_parser), intent(inout)	self,
		character(*), intent(in)	name,
		logical, intent(in), optional	long,
		logical, intent(in), optional	short,
		logical, intent(in), optional	raise_error
	)

private

Get the option index from cli_parser by name.

Returns: The desired option index.

Parameters

[in]	name	name of the desired option
[in]	long	whether to check long name (default: .true.)
[in]	short	whether to check short name (default: .true.)
[in]	raise_error	whether to raise an error if option is not found (default: .true.)

Definition at line 326 of file mo_cli.f90.

References get_option_index().

Referenced by get_option_index().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ has_option()

logical function mo_cli::has_option	(	class(cli_parser), intent(inout)	self,
		character(*), intent(in)	name
	)

private

Whether the option is defined in cli_parser given by name.

Returns: Truth value if the given option was defined.

Parameters

[in] name name of the desired option

Definition at line 401 of file mo_cli.f90.

References has_option().

Referenced by has_option().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ is_given_arg()

logical function mo_cli::is_given_arg	(	class(option), intent(inout)	self,
		character(*), intent(in)	arg
	)

private

check if this option is the given argument.

Returns: Truth value if the given argument is this option.

Definition at line 315 of file mo_cli.f90.

References is_given_arg().

Referenced by is_given_arg().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ new_cli_parser()

type(cli_parser) function mo_cli::new_cli_parser	(	character(*), intent(in), optional	prog,
		character(*), intent(in), optional	description,
		logical, intent(in), optional	add_help_option,
		logical, intent(in), optional	add_version_option,
		character(*), intent(in), optional	version,
		logical, intent(in), optional	add_logger_options
	)

private

Create a new cli_parser.

Returns: The new cli_parser.

Parameters

[in]	prog	Program name (default will be arg(0))
[in]	description	help text for the cli
[in]	add_help_option	whether to add a help option (–help, -h)
[in]	add_version_option	whether to add a version option (–version, -V)
[in]	version	Program version
[in]	add_logger_options	whether to add a logger options (–verbose, –quite, ...)

Definition at line 142 of file mo_cli.f90.

References mo_message::error_message(), new_cli_parser(), and mo_os::path_split().

Referenced by new_cli_parser().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ new_option()

type(option) function mo_cli::new_option	(	character(*), intent(in)	name,
		character(1), intent(in), optional	s_name,
		character(*), intent(in), optional	help,
		logical, intent(in), optional	has_value,
		character(*), intent(in), optional	value_name,
		character(*), intent(in), optional	default,
		logical, intent(in), optional	required,
		logical, intent(in), optional	blank,
		logical, intent(in), optional	repeated
	)

private

Create a new option.

Returns: The new option.

Parameters

[in]	name	long name (will be double hyphenated: –opt)
[in]	s_name	short name (will be hyphenated: -o)
[in]	help	description of the option
[in]	has_value	whether the option has a value
[in]	value_name	name of the value for the help text (default "value")
[in]	default	default value for this option
[in]	required	whether the option is required
[in]	blank	whether the option is passed blank without hyphenated name (only latter one possible)
[in]	repeated	whether the option can be read repeatedly

Definition at line 205 of file mo_cli.f90.

References new_option().

Referenced by new_option().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ option_read_count()

integer(i4) function mo_cli::option_read_count	(	class(cli_parser), intent(inout)	self,
		character(*), intent(in)	name
	)

private

Read count for the option in the cli_parser given by name.

Returns: Number of reads for the option.

Parameters

[in] name name of the desired option

Definition at line 387 of file mo_cli.f90.

References option_read_count().

Referenced by option_read_count().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ option_value()

character(:) function, allocatable mo_cli::option_value	(	class(cli_parser), intent(inout)	self,
		character(*), intent(in)	name
	)

private

Get the parsed value from an option by name from the cli_parser.

Returns: Value of the given option.

Parameters

[in] name name of the desired option

Definition at line 433 of file mo_cli.f90.

References option_value().

Referenced by option_value().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ option_was_read()

logical function mo_cli::option_was_read	(	class(cli_parser), intent(inout)	self,
		character(*), intent(in)	name
	)

private

Whether the option was read by the cli_parser given by name.

Returns: Truth value if the given option was read.

Parameters

[in] name name of the desired option

Definition at line 373 of file mo_cli.f90.

References option_was_read().

Referenced by option_was_read().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ parse()

subroutine mo_cli::parse ( class(cli_parser), intent(inout) self )

private

Parse the given command line arguments with the cli_parser.

Definition at line 510 of file mo_cli.f90.

References mo_logging::log_set_config(), and parse_arg().

Here is the call graph for this function:

◆ parse_arg()

subroutine mo_cli::parse_arg	(	character(*), intent(in)	arg,
		character(:), dimension(:), intent(out), allocatable	names,
		integer(i4), dimension(:), intent(out), allocatable	counts
	)

private

Parse given argument.

Parse a given argument, that starts with an "-", to determine the involved options in case of a multi arg (-xyz).

Parameters

[out]	names	names of involved options (can be multiple by using combined short names)
[out]	counts	counts of occurrences of each option

Definition at line 615 of file mo_cli.f90.

Referenced by parse().

Here is the caller graph for this function:

◆ print_help()

subroutine mo_cli::print_help ( class(cli_parser), intent(inout) self )

private

Print help message for the cli_parser.

Definition at line 474 of file mo_cli.f90.

◆ print_info()

subroutine mo_cli::print_info ( class(option), intent(inout) self )

private

Print info for an option.

Definition at line 449 of file mo_cli.f90.

Data Types

Functions/Subroutines

Detailed Description

Function/Subroutine Documentation

◆ add_option()

◆ cnt_options()

◆ findchar()

◆ get_blank_option_index()

◆ get_option()

◆ get_option_index()

◆ has_option()

◆ is_given_arg()

◆ new_cli_parser()

◆ new_option()

◆ option_read_count()

◆ option_value()

◆ option_was_read()

◆ parse()

◆ parse_arg()

◆ print_help()

◆ print_info()