class ArgumentParser extends SettingsParser
A simple command line argument parser.
Usage:
1. Define parameters with param, requiredParam, repeatedParam and command. Each of these methods gives back a handle to a future argument value.
2. Call parse()
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. (This behaviour may be changed by subclassing and redefining the
check()
method).
Example
val parser = argparse.ArgumentParser("0.1.0")
val p1 = parser.param[String]("--this-is-a-named-param", default = "default value") val p2 = parser.param[Int]("positional-param", default = 2)
parser.parse(Seq("--this-is-a-named-param=other", 5)) println(p1())
println(p2())
- Self Type
- ArgumentParser
- Alphabetic
- By Inheritance
- ArgumentParser
- SettingsParser
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Instance Constructors
- new ArgumentParser(description: String, enableHelpFlag: Boolean, enableBashCompletionFlag: Boolean, stdout: PrintStream, stderr: PrintStream)
- description
a short description of this command. Used in help messages.
- enableHelpFlag
include a
--help
flag which will print a generated help message
Value Members
- final def !=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def ##: Int
- Definition Classes
- AnyRef → Any
- final def ==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- def addParamDef(pdef: ParamDef): Unit
Low-level escape hatch for manually adding parameter definitions.
Low-level escape hatch for manually adding parameter definitions.
See also param, requiredParam and repeatedParam for the high-level API.
- def addParamInfo(pinfo: ParamInfo): Unit
Low-level escape hatch for manually adding parameter information.
Low-level escape hatch for manually adding parameter information.
See also param, requiredParam and repeatedParam for the high-level API.
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @native()
- def command(name: String, action: (Seq[String]) => Unit, description: String = ""): Unit
Utility to define a sub command.
Utility to define a sub command.
Many modern command line apps actually consist of multiple nested commands, each corresponding to the verb of an action, such as 'run' or 'clone'. Typically, each sub command also has its own dedicated parameters list.
In argparse, subcommands can easily be modelled by a positional parameter that represents the command, followed by a repeated, all-absorbing parameter which represents the command's arguments. However, since this pattern is fairly common, this method is provided as a shortcut.
- name
the name of the command
- action
a function called with the remaining arguments after this command. Note that you may reference an Arg's value in the action.
- var commandInfos: ListBuffer[CommandInfo]
- val description: String
- val enableBashCompletionFlag: Boolean
- val enableHelpFlag: Boolean
- final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef → Any
- def finalize(): Unit
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.Throwable])
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- def hasErrors: Boolean
- Attributes
- protected
- def hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- def help(): String
A default help message, generated from parameter help strings.
- final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- def param[A](name: String, default: => A, env: String = null, aliases: Seq[String] = Seq.empty, help: String = "", flag: Boolean = false, absorbRemaining: Boolean = false, completer: (String) => Seq[String] = null, bashCompleter: BashCompleter = null)(implicit reader: Reader[A]): () => 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 of type A where A may be a primitive type, it cannot be assigned null. The usual solution would be to wrap it in an Option type, but that leads to an ugly API. Hence the method is split into two. See addParam() for the common denominator.
- A
The type to which an argument shall be converted.
- 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".- default
The default value to use in case no matching argument is provided.
- 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.
- 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.
- help
A help message to display when the user types
--help
- 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.
- absorbRemaining
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 dedicatedcommand
method for such use cases)- completer
A bash snippet that is inserted in bash-completions, responsible for setting completion options for this param. If omitted, the parameter type's (A) default completer will be used. If present, this must be valid bash and should set COMPREPLY. The bash variable "$cur" may be used in the snippet, and will contain the current word being completed for this parameter.
- returns
A handle to the parameter's future value, available once
parse(args)
has been called.
- val paramInfos: ListBuffer[ParamInfo]
- def parseOrExit(args: Iterable[String]): 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 classes of errors are:
1. An unknown argument is encountered. This can either be an unspecified named argument or an extranous positional argument.
2. A required argument is missing.
3. An argument cannot be parsed from its string value to its desired type.
- See also
parseResult for a version of this function which does not exit
- def parseResult(args: Iterable[String], env: Map[String, String] = sys.env): Result
Parse the given arguments with respect to the parameters defined by param, requiredParam, repeatedParam and command.
- def printBashCompletion(programName: String): Unit
- def repeatedParam[A](name: String, aliases: Seq[String] = Seq.empty, help: String = "", flag: Boolean = false, completer: (String) => Seq[String] = null, bashCompleter: BashCompleter = null)(implicit reader: Reader[A]): () => 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 aSeq[A]
, while other params takeA
and give backA
).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 beSeq(1,2,3)
.Repeated positional parameters consume all remaining positional command line arguments.
- def reportMissing(name: String): Unit
- Attributes
- protected
- def reportParseError(name: String, message: String): Unit
- Attributes
- protected[argparse]
- def reportUnknown(name: String): Unit
- Attributes
- protected
- def reportUnknownCommand(actual: String, available: Seq[String]): Unit
- Attributes
- protected
- def requiredParam[A](name: String, env: String = null, aliases: Seq[String] = Seq.empty, help: String = "", flag: Boolean = false, absorbRemaining: Boolean = false, completer: (String) => Seq[String] = null, bashCompleter: BashCompleter = null)(implicit reader: Reader[A]): () => 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, absorbRemaining: Boolean, completer: Option[(String) => Seq[String]], bashCompleter: Option[BashCompleter])(implicit reader: Reader[A]): () => A
- val stderr: PrintStream
- val stdout: PrintStream
- final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toString(): String
- Definition Classes
- AnyRef → Any
- final def wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException]) @native()