An option definition.
An exception thrown by OptParser.
An option parser defined with a sequence of option definitions.
The result of parsing an argument sequence.
Constructs Opt values.
Constructs OptParser values.
Constructs OptResult values.
Returns a processor that transforms a single argument.
Returns a processor that transforms a single argument.
Example
val parser = ("level", 'L') ~> as { (arg, opts) => arg.toInt } ~~ 0
the option type
a function that transforms an argument to an instance of A
Return a processor that converts an argument to a Boolean
.
Return a processor that converts an argument to a Boolean
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Byte
.
Return a processor that converts an argument to a Byte
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Charset
.
Return a processor that converts an argument to a Charset
.
Example
val parser = ("encoding", 'E') ~> asCharset ~~ Charset.forName("UTF-8")
The resulting processor throws an OptException if the argument refers to an unknown character set.
Return a processor that converts an argument to a Double
.
Return a processor that converts an argument to a Double
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Float
.
Return a processor that converts an argument to a Float
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Int
.
Return a processor that converts an argument to a Int
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Long
.
Return a processor that converts an argument to a Long
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Short
.
Return a processor that converts an argument to a Short
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Some[Boolean]
.
Return a processor that converts an argument to a Some[Boolean]
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Some[Byte]
.
Return a processor that converts an argument to a Some[Byte]
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Some[Charset]
.
Return a processor that converts an argument to a Some[Charset]
.
Example
val parser = ("encoding", 'E') ~> asSomeCharset ~~ None
The resulting processor throws an OptException if the argument refers to an unknown character set.
Return a processor that converts an argument to a Some[Double]
.
Return a processor that converts an argument to a Some[Double]
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Some[Float]
.
Return a processor that converts an argument to a Some[Float]
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Some[Int]
.
Return a processor that converts an argument to a Some[Int]
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Some[Long]
.
Return a processor that converts an argument to a Some[Long]
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that converts an argument to a Some[Short]
.
Return a processor that converts an argument to a Some[Short]
.
The resulting processor throws an OptException if the argument cannot be converted.
Return a processor that simply returns an argument as a Some[String]
.
Return a processor that simply returns an argument as a String
.
Return a processor whose value is false
.
Return a processor whose value is false
.
This is shorthand for set(false)
.
Return a processor whose value is true
.
Return a processor whose value is true
.
This is shorthand for set(true)
.
Returns a processor whose value does not depend on additional arguments.
Returns a processor whose value does not depend on additional arguments.
Example
val parser = ("verbose", 'v') ~> set(true) ~~ false
the option type
a function that returns an instance of A
A convenience method that throws OptException.
A convenience method that throws OptException.
A simple option parser.
Overview
An option parser is an ordered collection of option name and option processor pairs that matches on a sequence of arguments, yielding a map of option names to option values. As the parser recognizes option names in the argument sequence, it applies the corresponding processor function to obtain the option value. This process is repeated until the argument sequence is exhausted or the parser encounters an error.
An option name can be expressed in both long form (a string with at least two characters) and short form (a single character). For any given sequence of arguments, long options are detected by the presence of a
--
prefix and short options with a-
prefix. Examples include--verbose
and-v
, respectively.An option processor is an arbitrary function whose purpose is to return a value that gets assigned to the option name. A processor may consider and absorb subsequent arguments in computing the value, such as
--timeout
that might expect the next argument to be an integer.Parser Construction
The construction of a parser is best done using the DSL, which is available using the following import statement.
import com.loopfor.scalop._
The following is a simple parser that demonstrates how the DSL is used to pair an option name with a corresponding processor.
The
~>
method implicitly converts the tuple("verbose", 'v')
into an option, recognizing both long and short forms, and associates the processor functionset(true)
with that option.Invoking
parser
with an empty sequence yields the following map of option names to option values. The@
option is a special name containing all non-option values trailing the last option in the argument sequence. This is discussed in more detail below.Invoking
parser
with the sequence("--verbose")
or("-v")
produces the following map. Notice that the value is associated with both long and short forms of the option name regardless of which form is specified in the argument sequence.The following is a more advanced parser that demonstrates additional features of the DSL.
The
~~
operator following a processor function associates a default value, which is assigned to the option in the absence of being specified in the argument sequence.The
++
operator concatenates options, producing a sequence whose order of traversal also defines the order of evaluation.Note that, in addition to being defined in both long and short form, an option may also be specified using only one form. For example, the expression
"timeout" ~> {...}
creates an option with the long name"timeout"
, and similarly, the expression't' ~> {...}
creates an option with the short name"t"
.Parser Behavior
Given a sequence of arguments, such as those provided by a shell when supplying arguments to a command line program, an option parser behaves in the following manner.
First, default values for each option, if specified, are assigned to the option value map. The parser then recursively applies the following algorithm as it traverses the argument sequence.
If the next argument is equal to
"--"
, the sequence of all subsequent arguments is assigned to the special option name"@"
and the parser terminates, returning the option value map. By convention, the--
option is used to explicitly terminate options so that remaining arguments, which might be prefixed with--
or-
, are not treated as options.If the next argument is either a long or short option name recognized by the parser, the corresponding processor function is applied to the remaining arguments, yielding a value, which is then associated with the option name, both long and short, in the option value map. However, if the argument happens to be an option that is not recognized by the parser, then an exception is thrown. Otherwise, the parser is recursively applied to the remaining sequence of arguments.
If the next argument is not an option, implying that it contains neither a
--
nor a-
prefix, then the remaining argument sequence is assigned to the"@"
option and the parser terminates.Option Processors
An option processor is a function accepting as input:
and returning as output a tuple containing:
The argument sequence provided as input are those that follow the recognized option. For example, given the following argument sequence:
If
-F
was recognized by the parser, then the sequence provided to the associated processor function would be:Since a processor may expect additional arguments following the option, as is the case with
-F
, the resulting sequence should be the arguments that follow those absorbed by the processor, which in this case, would be:In cases where a processor requires additional arguments, it is often necessary to perform some degree of validation or transformation, both of which may fail. Exceptions that propagate beyond the processor function are caught by the parser and converted to OptException. Additionally, the
yell()
methods are provided as a convenience for processor implementations to throw instances of OptException.Predefined Processors
A handful of predefined processors are made available to simplify the construction of options.
For standalone options with no additional arguments, such as
--verbose
, set can be used to explicitly assign a value.Since many standalone options need only convey a boolean value, enable and disable are shorthand for
set(true)
andset(false)
, respectively.The as method constructs a processor in cases where an option requires only a single additional argument, thereby allowing the signature of the function to be simplified. The simplification comes from removing explicit handling of the argument sequence.
In addition, most of the primitive types have a prebuilt processor that performs the necessary conversion: