Minilib.App.Clap
Defined in minilib-app@0.9.0
Command line argument parser.
Inspired by clap crate of Rust.
How to use
- Create a command definition.
- A command definition (
Command) might have a name, a version, the author, as well as argument definitions. - An argument definition (
Arg) might have an ID, a short option, a long option, a help message, default value etc. - Parse a command line using
command.get_matches. - Get the values of the arguments from the argument matchings (
ArgMatches).
Example:
typical_command: Command;
typical_command = (
Command::new("typical_tool")
.bin_name("typical")
.display_name("TypicalTool")
.version("1.0.0")
.author("somebody <somebody@example.com>")
.arg(Arg::new("TARGET").help("Target").takes_value.required)
.arg(Arg::new("FILE").help("Input files").takes_multiple_values)
.arg(Arg::new("count").short('n').long("count").help("How many times to iterate")
.takes_value.value_name("NUMBER").default_value("100"))
.arg(Arg::new("output").short('o').long("output").help("An output file")
.takes_value.value_name("OUTFILE"))
);
main: IO ();
main = do {
// Parse a command line.
let matches: ArgMatches = *command.get_matches;
// Get the values of the arguments from `ArgMatches`.
let target: String = *matches.get_one("TARGET").as_some;
let files: Option (Array String) = *matches.get_many("FILE");
let count: I64 = *matches.get_one("count").as_some.from_string.from_result;
let output: Option String = *matches.get_one("output");
...
}.try(eprintln);
Changes in 0.6.0
- The effect of a boolean arg, which has a
set_true()or aset_false()action, will be negated if--no-{long-option}is specified in the command line.
Values
namespace Minilib.App.Clap::Arg
default_value
Type: Std::String -> Minilib.App.Clap::Arg -> Minilib.App.Clap::Arg
Sets @default_value.
help
Type: Std::String -> Minilib.App.Clap::Arg -> Minilib.App.Clap::Arg
Sets @help.
long
Type: Std::String -> Minilib.App.Clap::Arg -> Minilib.App.Clap::Arg
Sets @long.
new
Type: Std::String -> Minilib.App.Clap::Arg
Creates new argument.
required
Type: Minilib.App.Clap::Arg -> Minilib.App.Clap::Arg
Sets @required to true.
short
Type: Std::U8 -> Minilib.App.Clap::Arg -> Minilib.App.Clap::Arg
Sets @short.
takes_multiple_values
Type: Minilib.App.Clap::Arg -> Minilib.App.Clap::Arg
Sets @takes_value to true, @multiple_values to true, and @action to append().
takes_value
Type: Minilib.App.Clap::Arg -> Minilib.App.Clap::Arg
Sets @takes_value to true, and @action to set().
value_name
Type: Std::String -> Minilib.App.Clap::Arg -> Minilib.App.Clap::Arg
Sets @value_name.
namespace Minilib.App.Clap::ArgMatches
dispatch_subcommands
Type: [m : Minilib.Monad.Error::MonadError] Std::Array (Minilib.App.Clap::Command, Minilib.App.Clap::ArgMatches -> m a) -> Minilib.App.Clap::ArgMatches -> m a
Dispatches subcommands.
Parameters
subcommand_handlers: An array of pairs of subcommands and their handlersmatches: Argument matchings of the main command
empty
Type: Minilib.App.Clap::ArgMatches
An empty ArgMatches structure.
get_flag
Type: Std::String -> Minilib.App.Clap::ArgMatches -> Std::Bool
Gets the boolean value of the argument specified by ID.
Parameters
id: An argument IDmatches: Argument matchings
get_many
Type: Std::String -> Minilib.App.Clap::ArgMatches -> Std::Option (Std::Array Std::String)
Gets the plural values of the argument specified by ID.
Parameters
id: An argument IDmatches: Argument matchings
get_one
Type: Std::String -> Minilib.App.Clap::ArgMatches -> Std::Option Std::String
Gets the single value of the argument specified by ID.
Parameters
id: An argument IDmatches: Argument matchings
subcommand
Type: Minilib.App.Clap::ArgMatches -> Std::Option (Std::String, Minilib.App.Clap::ArgMatches)
Gets the matched subcommand name and matchings for the subcommand.
Parameters
matches: Argument matchings
namespace Minilib.App.Clap::ArgParser
advance
Type: Minilib.App.Clap::ArgParser::ArgParser -> Std::Result Std::ErrMsg (Std::String, Minilib.App.Clap::ArgParser::ArgParser)
Proceed to next input.
append_value
Type: Minilib.App.Clap::Arg -> Std::String -> Minilib.App.Clap::ArgParser::ArgParser -> Minilib.App.Clap::ArgParser::ArgParser
Adds a value to the array of values in arg.
check_required_args_present
Type: Minilib.App.Clap::ArgParser::ArgParser -> Std::Result Std::ErrMsg Minilib.App.Clap::ArgParser::ArgParser
Check whether the required argument values are set. Reports an error if the value is not set.
get_input
Type: Minilib.App.Clap::ArgParser::ArgParser -> Std::Result Std::ErrMsg Std::String
Get the current input.
make
Type: Std::Array Std::String -> Minilib.App.Clap::Command -> Minilib.App.Clap::ArgParser::ArgParser
Creates an ArgParser based on the input array and command.
no_inputs
Type: Minilib.App.Clap::ArgParser::ArgParser -> Std::Bool
Returns True if there are no more inputs. Returns False if there is more input.
parse_args
Type: Minilib.App.Clap::ArgParser::ArgParser -> Std::Result Std::ErrMsg Minilib.App.Clap::ArgParser::ArgParser
Parse the actual command line argument array and set the value of Arg.
set_default_if_not_present
Type: Minilib.App.Clap::ArgParser::ArgParser -> Std::Result Std::ErrMsg Minilib.App.Clap::ArgParser::ArgParser
If no value is set for the argument, set the default value.
set_value
Type: Minilib.App.Clap::Arg -> Std::String -> Minilib.App.Clap::ArgParser::ArgParser -> Minilib.App.Clap::ArgParser::ArgParser
Set the value to arg.
namespace Minilib.App.Clap::Command
about
Type: Std::String -> Minilib.App.Clap::Command -> Minilib.App.Clap::Command
Sets the description about the command.
Parameters
about: The description about the commandcommand: A command definition
arg
Type: Minilib.App.Clap::Arg -> Minilib.App.Clap::Command -> Minilib.App.Clap::Command
Adds an argument definition to the command.
Parameters
arg: An argument definition to the commandcommand: A command definition
author
Type: Std::String -> Minilib.App.Clap::Command -> Minilib.App.Clap::Command
Sets the author of the command.
Parameters
author: The author of the commandcommand: A command definition
bin_name
Type: Std::String -> Minilib.App.Clap::Command -> Minilib.App.Clap::Command
Sets the name of the executable binary of the command.
Parameters
bin_name: The name of the executable binary of the commandcommand: A command definition
display_name
Type: Std::String -> Minilib.App.Clap::Command -> Minilib.App.Clap::Command
Sets the display name of the command.
Parameters
display_name: The display name of the commandcommand: A command definition
empty
Type: Minilib.App.Clap::Command
A command definition with empty name.
find_subcommand
Type: Std::String -> Minilib.App.Clap::Command -> Std::Option Minilib.App.Clap::Command
Finds a subcommand with the specified name.
Parameters
name: A subcommand namecommand: A command definition
get_matches
Type: Minilib.App.Clap::Command -> Std::IO::IOFail Minilib.App.Clap::ArgMatches
Parse command line arguments based on IO::get_args.
If --help or --version is specified, the help string or version string will be returned as throw.
Parameters
command: A command definition
get_matches_from
Type: Std::Array Std::String -> Minilib.App.Clap::Command -> Std::Result Std::ErrMsg Minilib.App.Clap::ArgMatches
Parses command line arguments based on the specified input array.
If --help or --version is specified, the help string or version string will be returned as the error message.
Parameters
inputs: An input arraycommand: A command definition
name
Type: Std::String -> Minilib.App.Clap::Command -> Minilib.App.Clap::Command
Sets the name of the command.
Parameters
name: The name of the commandcommand: A command definition
new
Type: Std::String -> Minilib.App.Clap::Command
Creates a new command definition.
Parameters
name: The name of the command
subcommand
Type: Minilib.App.Clap::Command -> Minilib.App.Clap::Command -> Minilib.App.Clap::Command
Adds a subcommand definition to the command.
Parameters
subcommand: A subcommandcommand: A command definition
version
Type: Std::String -> Minilib.App.Clap::Command -> Minilib.App.Clap::Command
Sets the version of the command.
Parameters
version: The version of the commandcommand: A command definition
namespace Minilib.App.Clap::HelpTemplate
format
Type: Minilib.App.Clap::Command -> Minilib.App.Clap::HelpTemplate -> Std::String
new
Type: Std::String -> Minilib.App.Clap::HelpTemplate
Types and aliases
namespace Minilib.App.Clap
Arg
Defined as: type Arg = unbox struct { ...fields... }
An argument definition.
Arguments can be either optional or positional arguments.
If either short or long is set, it becomes an optional argument.
Otherwise, it is a positional argument.
field id
Type: Std::String
A unique ID that identifies the argument.
field short
Type: Std::U8
A one-hypen option, eg. -n
field long
Type: Std::String
A two-hypen option, eg. --count
field required
Type: Std::Bool
Whether the argument is required or not.
field takes_value
Type: Std::Bool
Whether the argument takes some value.
field multiple_values
Type: Std::Bool
Whether the argument value(s) is singule or multiple.
field default_value
Type: Std::Option Std::String
A default value of the argument.
field value_name
Type: Std::String
The name of the argument value which is displayed in help message.
field help
Type: Std::String
The help message of the argument.
field action
Type: Minilib.App.Clap::ArgAction::ArgAction
The action taken when the argument is parsed.
ArgMatches
Defined as: type ArgMatches = box struct { ...fields... }
The argument matchings of the command line.
field subcommand
Type: Std::Option (Std::String, Minilib.App.Clap::ArgMatches)
Subcommand name and submatches
field map
Type: HashMap::HashMap Std::String (Std::Array Std::String)
A hashmap from the argument ID to the argument values
Command
Defined as: type Command = box struct { ...fields... }
A command definition.
field name
Type: Std::String
The name of the command.
field bin_name
Type: Std::String
The name of the executable binary of the command.
field display_name
Type: Std::String
The display name of the command.
field subcommand_path
Type: Std::String
The subcommands that invokes this command.
field version
Type: Std::String
The version of the command.
field author
Type: Std::String
The author of the command.
field about
Type: Std::String
The description about the command.
field subcommands
Type: Std::Array Minilib.App.Clap::Command
Array of subcommands.
field args
Type: Std::Array Minilib.App.Clap::Arg
Argument definitions of the command.
field help_template
Type: Minilib.App.Clap::HelpTemplate
A help template of the command.
field version_template
Type: Minilib.App.Clap::HelpTemplate
A version template of the command.
HelpTemplate
Defined as: type HelpTemplate = unbox struct { ...fields... }
A help template. (used internally)
field data
Type: Std::String
namespace Minilib.App.Clap::ArgAction
ArgAction
Defined as: type ArgAction = unbox union { ...variants... }
The action taken when the argument is parsed.
variant set
Type: ()
Sets next input to the single argument value.
variant append
Type: ()
Appends next input to the array of argument values.
variant set_true
Type: ()
Sets "true" as the single argument value.
variant set_false
Type: ()
Sets "false" as the single argument value.
variant increment
Type: ()
Increment the argument value as an integer.
variant help
Type: ()
Displays help for the command.
variant version
Type: ()
Displays the version of the command.
namespace Minilib.App.Clap::ArgParser
ArgParser
Defined as: type ArgParser = unbox struct { ...fields... }
Command line argument parser. (used internally)
field command
Type: Minilib.App.Clap::Command
field remaining_args
Type: Std::Iterator::DynIterator Minilib.App.Clap::Arg
field matches
Type: Minilib.App.Clap::ArgMatches
field inputs
Type: Std::Iterator::DynIterator Std::String
field positional_only
Type: Std::Bool