argparse/argparse.core/ParsersApi/ArgumentParser

ArgumentParser

class ArgumentParser(val description: String, val helpFlags: Seq[String], val bashCompletionFlags: Seq[String])

A simple command line argument parser.

Usage:

  1. Define parameters with param, requiredParam and repeatedParam. Each of these methods gives back a handle to a future argument value.

  2. Call parseOrExit() with actual arguments.

  3. If parsing succeeds, the arguments will be available in the handles defined in step 1.

If parsing fails, error descriptions are printed and the program exits with 2.

Example:

val parser = argparse.default.ArgumentParser()

val p1 = parser.param[String]("--this-is-a-named-param", default = "default value")
val p2 = parser.param[Int]("positional-param", default = 2)

parser.parseOrExit(Seq("--this-is-a-named-param=other", 5))
println(p1.value)
println(p2.value)



Value Params
bashCompletionFlag
Use these flags to print a sourceable
bash-completion script. Set to empty to disable.


description
A short description of this command. Used in help
messages.


helpFlags
Use these flags to print the help message. Set to empty
to disable.


Companion
object
class Object
trait Matchable
class Any
Value members
Concrete methods
 def action(fn: => Unit): ArgumentParser
Set an action to be run after successful parsing.


Set an action to be run after successful parsing.


 def addParamDef(pdef: ParamDef): Unit
Low-level escape hatch for manually adding parameter definitions.


Low-level escape hatch for manually adding parameter definitions.


You should prefer declaring parameters via the param(),
requiredParam() and repeatedParam() methods.


 def addParamInfo(pinfo: ParamInfo): Unit
Low-level escape hatch for manually adding parameter information.


Low-level escape hatch for manually adding parameter information.


You should prefer declaring parameters via the param(),
requiredParam() and repeatedParam() methods.


 def addSubparser(name: String, parser: ArgumentParser, aliases: Seq[String]): ArgumentParser
Low-level escape hatch for manually adding a nested parser.


Low-level escape hatch for manually adding a nested parser.


You should use the subparser method if you want to construct an
argument parser of the same API package. This method allows you to nest
ArgumentParsers of different API styles.


 def env: Map[String, String]
 def help(): String
The help message.


The help message.


 def help(message: String): ArgumentParser
 def param[A](name: String, default: => A, env: String, aliases: Seq[String], help: String, flag: Boolean, endOfNamed: Boolean, interactiveCompleter: String => Seq[String], standaloneCompleter: BashCompleter, argName: String)(implicit reader: Reader[A]): Argument[A]
Define an optional parameter, using the given default value if it is not
supplied on the command line or by an environment variable.


Define an optional parameter, using the given default value if it is not
supplied on the command line or by an environment variable.


ErgoTip: always give named parameters a default value.


Internal design note: param and requiredParam differ only in
the presence of the 'default' parameter. Ideally, they would be merged
into one single method, giving the 'default' parameter a default null
value (as is done for the other optional parameters, such as 'env' and
'help'). Unfortunately, since 'default' is call-by-name, there is no way
to check if it has been set to null without evaluating it. See
singleParam for the common denominator.


Type Params
A
The type to which an argument shall be converted.


Value Params
aliases
Other names that may be used for this parameter. This is
a good place to define single-character aliases for frequently used
named parameters. Note that this has no effect for positional
parameters.


argName
The name to use in help messages for this parameter's
argument. This only has an effect on named parameters which take an
argument. By default, the name of the type of the argument will be used.


default
The default value to use in case no matching argument is
provided.


endOfNamed
Indicates that any arguments encountered after this
parameter must be treated as positionals, even if they start with -.
In other words, a parameter marked with this has the same effect as the
-- separator. It can be useful for implementing sub-commands. (Note
however that this ArgumentParser has a dedicated command method for
such use cases)


env
The name of an environment variable from which to read the
argument in case it is not supplied on the command line. Set to 'null'
to ignore.


flag
Set to true if the parameter should be treated as a flag.
Flags are named parameters that are treated specially by the parser:


    

  • they never take arguments, unless the argument is embedded in the flag
itself
    • 

  • they are always assigned the string value "true" if found on the
command line.
Note that flags are intended to make it easy to pass boolean parameters;
it is quite rare that they are useful for non-boolean params. The flag
field has no effect on positional parameters.
    • 



help
A help message to display when the user types --help.


interactiveCompleter
Compute available shell completions starting
with a given string. This is used by interactive bash completion, where
the user program is responsible for generating completions.


name
The name of the parameter. A name starting with -
indicates a named parameter, whereas any other name indicates a
positional parameter. Prefer double-dash named params. I.e. prefer
"--foo" over "-foo".


standaloneBashComplete
A completer for bash. This is used by
standalone bash completion, where a bash script generates completion,
without the involvement of the the user program.
If your program is implemented with Scala on the JVM, the startup time
is considerable and hence standalone completion should be preferred for
a snappy user experience.


Returns
A handle to the parameter's future value, available once
parse(args) has been called.


 def paramDefs: List[ParamDef]
The actual parameters. These objects contains callbacks that are invoked
by the parser.


The actual parameters. These objects contains callbacks that are invoked
by the parser.


This is a low-level escape hatch. You should prefer declaring parameters
via the param(), requiredParam() and repeatedParam() methods.


 def paramInfos: List[ParamInfo]
Human-readable information about parameters. These objects do not
influence parsing, but contain additional information that is useful to
generate help messages and bash completion.


Human-readable information about parameters. These objects do not
influence parsing, but contain additional information that is useful to
generate help messages and bash completion.


This is a low-level escape hatch. You should prefer declaring parameters
via the param(), requiredParam() and repeatedParam() methods.


 def parseOrExit(args: Iterable[String], env: Map[String, String], stdout: PrintStream, stderr: PrintStream): Unit
Parse the given arguments with respect to the parameters defined by
param, requiredParam, repeatedParam and command.


Parse the given arguments with respect to the parameters defined by
param, requiredParam, repeatedParam and command.


In case no errors are encountered, the arguments will be populated in
the functions returned by the parameter definitions.


In case errors are encountered, the default behaviour is to exit the
program.


The types of errors are:


    

  1. 

    An unknown argument is encountered. This can either be an unspecified
named argument or an extranous positional argument.
    

    2. 

  2. 

    A required argument is missing.
    

    3. 

  3. 

    An argument cannot be parsed from its string value to its desired
type.
    

    4. 



See also
parseResult for a version of this function which does not exit


 def parseResult(args: Iterable[String], env: Map[String, String], stdout: PrintStream, stderr: PrintStream): ParseResult
Parse the given arguments with respect to the parameters defined by
param, requiredParam, repeatedParam.


Parse the given arguments with respect to the parameters defined by
param, requiredParam, repeatedParam.


 def postCheck(check: (Iterable[String], Map[String, String]) => Option[String]): ArgumentParser
Add a function which is run after parsing command line args, optionally
reporting an error.


Add a function which is run after parsing command line args, optionally
reporting an error.


 def printBashCompletion(out: PrintStream, commandChain: String*): Unit
Generate and print a standalone bash completion script.


Generate and print a standalone bash completion script.


Value Params
commandChain
the name of the program


out
the stream to which to print the script to


 def repeatedParam[A](name: String, aliases: Seq[String], help: String, flag: Boolean, endOfNamed: Boolean, interactiveCompleter: String => Seq[String], standaloneCompleter: BashCompleter, argName: String)(implicit reader: Reader[A]): Argument[Seq[A]]
Define a parameter that may be repeated.


Define a parameter that may be repeated.


Note that all named parameters may always be repeated, regardless if
they are defined as repeated or not. The difference is that for
non-repeat-defined parameters the last value is used, whereas
repeat-defined parameters accumulate values. This is why
repeatedParam takes an A but gives back a Seq[A], while other
params take A and give back A.


E.g. consider the command line --foo=1 --foo=2 --foo=3. In case foo is
a regular named parameter, then, after parsing, the value will be 3.
In case it is defined as a repeating parameter, its value will be
Seq(1,2,3).


Repeated positional parameters consume all remaining positional command
line arguments. They should thus only ever be defined as the last
positional parameter.


 def requiredParam[A](name: String, env: String, aliases: Seq[String], help: String, flag: Boolean, endOfNamed: Boolean, interactiveCompleter: String => Seq[String], standaloneCompleter: BashCompleter, argName: String)(implicit reader: Reader[A]): Argument[A]
Define a required parameter.


Define a required parameter.


This method is similar to param, except that it does not accept a
default value. Instead, missing arguments for this parameter will cause
the parser to fail.


ErgoTip: avoid named parameters that are required. Only require
positional parameters.


See also
param


 def singleParam[A](name: String, default: Option[() => A], env: Option[String], aliases: Seq[String], help: String, flag: Boolean, endOfNamed: Boolean, interactiveCompleter: Option[String => Seq[String]], standaloneCompleter: Option[BashCompleter], argName: Option[String])(implicit reader: Reader[A]): Argument[A]
 def stderr: PrintStream
 def stdout: PrintStream
 def subparser(name: String, description: String, aliases: Seq[String]): ArgumentParser
Utility to define a nested argument parser.


Utility to define a nested argument parser.


Many applications actually consist of multiple nested commands, each
corresponding to the verb of an action (such as 'docker run' or 'git
clone'). Typically, each nested command also has its own dedicated
parameter list.


Value Params
aliases
Other names of the subcommand.


description
Information about what the nested command does.


name
The name of the subcommand.


Returns
a new ArgumentParser which will receive any remaining
arguments. Note that you should defined an action on the new
ArgumentParser.


 def subparserUnknown(action: (String, Iterable[String]) => Unit): ArgumentParser
Action to run on an unknown subcommand (if subparsers have been
defined).


Action to run on an unknown subcommand (if subparsers have been
defined).


You can use it to support dynamic subcommands. E.g.


    

  • match on the exact command:
    • 



parser.subparserUnknown {
  case ("foo", args) => foo(args)
}



    

  • run an external command:
    • 



parser.subparserUnknown {
 case (name, args) => os.proc("app-$name", args)
}



 def subparsers: Map[String, ArgumentParser]
Nested parsers that have been declared in this parser.


Nested parsers that have been declared in this parser.


This is a low-level escape hatch. You should prefer declaring
subcommands via the command() method.


Concrete fields
 val bashCompletionFlags: Seq[String]
 val description: String
 val helpFlags: Seq[String]