SettingsParser

EXPERIMENTAL

Add parameter definitions for all vars in a class and nested objects.

Variables will be set when a corresponding argument is encountered on the commandline. The rules are as follows:

• Every variable will be assigned a named parameter (starting with '--')

• The named parameter is optional. If it is not encountered on the command line, the variable's default value will be used (since this method requires a class instance, variables cannot be abstract).

• For every variable of type A, an implicit Reader[A] must be available.

• Boolean variables are parsed as flags.

Example:

class Settings {
 var opt1: String = "default1"
 var opt2: Int = 42
 var enableSystemA: Boolean = false

 object http {
   var host: String = "localhost"
   var port: Int = 2020
 }

 object monitoring {
   var host: String = "localhost"
   var port: Int = 3030
 }
}

def main(args: Array[String]): Unit = {
 val parser = argparse.ArgumentParser()

 val settings = parser.mutableSettings(Settings())

 println("before")
 println(settings) // all default values

 parser.parse(Array(
   "--opt1", "value1", "--enable-system-a", "--monitoring.port", "3031"
 ))

 println("after")
 println(settings) // opt1, enableSystemA and monitoring.port have been changed
}

EXPERIMENTAL

Add arguments for case-class fields (recursively).

Low-level escape hatch for manually adding parameter definitions.

See also param, requiredParam and repeatedParam for the high-level API.

Low-level escape hatch for manually adding parameter information.

See also param, requiredParam and repeatedParam for the high-level API.

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.

A default help message, generated from parameter help strings.

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

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.

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

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.

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.