Packages

class ArgumentParser extends AnyRef

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:

scala 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)

Self Type
(ParsersApi.this)#ArgumentParser
Linear Supertypes
AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. ArgumentParser
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Instance Constructors

  1. new ArgumentParser(description: String, helpFlags: Seq[String], bashCompletionFlags: Seq[String])

    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.

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##: Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. def action(fn: => Unit): ArgumentParser.this.type

    Set an action to be run after successful parsing.

  5. 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.

  6. 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.

  7. def addSubparser(name: String, parser: ArgumentParser, aliases: Seq[String] = Seq()): ArgumentParser.this.type

    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.

  8. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  9. val bashCompletionFlags: Seq[String]
  10. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native()
  11. val description: String
  12. def env: Map[String, String]
  13. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  14. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  15. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable])
  16. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  17. def hasErrors: Boolean
    Attributes
    protected
  18. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  19. def help(message: String): ArgumentParser.this.type
  20. def help(): String

    The help message.

  21. val helpFlags: Seq[String]
  22. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  23. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  24. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  25. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  26. def param[A](name: String, default: => A, env: String = null, aliases: Seq[String] = Seq.empty, help: String = "", flag: Boolean = false, endOfNamed: Boolean = false, interactiveCompleter: (String) => Seq[String] = null, standaloneCompleter: BashCompleter = null, argName: String = null)(implicit reader: (ParsersApi.this)#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.*

    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.

    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)

    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.

    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.

    returns

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

  27. def paramDefs: List[ParamDef]

    The actual parameters.

    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.

  28. def paramInfos: List[ParamInfo]

    Human-readable information about parameters.

    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.

  29. def parseOrExit(args: Iterable[String], env: Map[String, String] = sys.env, stdout: PrintStream = System.out, stderr: PrintStream = System.err): 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. 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

  30. def parseResult(args: Iterable[String], env: Map[String, String] = sys.env, stdout: PrintStream = System.out, stderr: PrintStream = System.err): ParseResult

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

  31. def postCheck(check: (Iterable[String], Map[String, String]) => Option[String]): ArgumentParser.this.type

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

  32. def printBashCompletion(out: PrintStream, commandChain: String*): Unit

    Generate and print a standalone bash completion script.

    Generate and print a standalone bash completion script.

    out

    the stream to which to print the script to

    commandChain

    the name of the program

  33. def repeatedParam[A](name: String, aliases: Seq[String] = Seq.empty, help: String = "", flag: Boolean = false, endOfNamed: Boolean = false, interactiveCompleter: (String) => Seq[String] = null, standaloneCompleter: BashCompleter = null, argName: String = null)(implicit reader: (ParsersApi.this)#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.

  34. def reportMissing(name: String): Unit
    Attributes
    protected
  35. def reportParseError(name: String, message: String): Unit
    Attributes
    protected
  36. def reportPostCheck(message: String): Unit
    Attributes
    protected
  37. def reportUnknown(name: String): Unit
    Attributes
    protected
  38. def reportUnknownCommand(actual: String): Unit
    Attributes
    protected
  39. def requiredParam[A](name: String, env: String = null, aliases: Seq[String] = Seq.empty, help: String = "", flag: Boolean = false, endOfNamed: Boolean = false, interactiveCompleter: (String) => Seq[String] = null, standaloneCompleter: BashCompleter = null, argName: String = null)(implicit reader: (ParsersApi.this)#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

  40. 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: (ParsersApi.this)#Reader[A]): Argument[A]
  41. def stderr: PrintStream
  42. def stdout: PrintStream
  43. def subparser(name: String, description: String = "", aliases: Seq[String] = Seq()): (ParsersApi.this)#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.

    name

    The name of the subcommand.

    description

    Information about what the nested command does.

    aliases

    Other names of the subcommand.

    returns

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

  44. def subparserUnknown(action: (String, Iterable[String]) => Unit): ArgumentParser.this.type

    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) }

  45. 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.

  46. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  47. def toString(): String
    Definition Classes
    AnyRef → Any
  48. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  49. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  50. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException]) @native()

Inherited from AnyRef

Inherited from Any

Ungrouped