Add an argument parser for a specific type.
Add an argument parser for a specific type.
Parsers for the these types are provided by default:
String
Int
Short
Long
Float
Double
Char
java.io.File
A parser is simply a function that takes a single String
argument and returns a value of
the desired type. If your parser detects an invalid argument it should throw
an org.sellmerfud.optparse.InvalidArgumentException. You can supply a message in the exception
that indicates why the argument was not valid.
If you add a parser for a type that already has a parser, the existing parser will be replaced.
Provide a function that will be called with each non-switch argument as it is encountered on the command line.
Set this to false
to avoid the automatically added help switch.
Set this to false
to avoid the automatically added help switch.
The action for the added help switch is to print the help text to stdout
and then
call java.lang.System.exit(0)
.
You can also override the default help switch by adding your own switch with a short name of "-h" or a long name of "--help".
Set the banner that is displayed as the first line of the help text.
Define a boolean switch.
Define a boolean switch. This switch takes no arguments. The long form of the switch may be prefixed with no- to negate the switch. For example a switch with long name --expert could be specified as --no-expert on the command line.
Define a switch that takes no arguments.
Returns the formatted help text as a String
Define a switch that takes a comma separated list of arguments.
Define a switch that takes an optional argument where the valid values are given by a Map.
Define a switch that takes an optional argument where the valid values are given by a Seq[].
Define a switch that takes an optional argument.
Parse the given command line.
Parse the given command line.
Each token from the command line should be in a separate entry in the given sequence such
as the array of strings passed to def main(args: Array[String]) {}
.
The option switches are processed using the previously defined switches. All non-switch
arguments are returned as a list of strings.
If any problems are encountered an org.sellmerfud.optparse.OptionParserException is thrown.
Define a switch that takes a required argument where the valid values are given by a Map.
Define a switch that takes a required argument where the valid values are given by a Seq[].
Define a switch that takes a required argument.
Add a message to the help text.
Add a message to the help text.
It will be displayed at the left margin after any previously defined switches/separators.
Same as calling help.
Same as calling help.
Overview
OptionParser is a class that handles the parsing of switches and arguments on the command line. It is based on the Ruby OptionParser class that is part of the standard Ruby library. It supports POSIX style short option switches as well as GNU style long option switches. By using closures when defining command line switches your code becomes much easier to write and maintain.
Features
Dependencies
This code requires Scala 2.10 as it relies on
scala.reflect.ClassTag
.Configuration Class
The OptionParser class has a single type parameter. This type parameter specifies the configuration class that your code will use to aggregate the command line switches and arguments. Each time a command line switch or argument is processed a function is called with your configuration class. The function should modify the configuration class or preferably construct a new immutable instance of the class and return it. The command line parser will return the configuration class upon successfully parsing the command line.
Defining Switches
You define a switch by supplying its name(s), description, and a function that will be called each time the switch is detected in the list of command line arguments. Your function has the type
{ (value: T, cfg: C) => C }
. You supply the type forT
and the framework will select the appropriate parser and call your function with the value converted to your expected type. The typeC
is your configuration class that was specified when the OptionParser was instantiated.The
reqd()
function defines a switch that takes a required argument. In this case we have specified that we expect the argument value to be anInt
. If the user enters a value that is not a valid integer then an org.sellmerfud.optparse.OptionParserException is thrown with an appropriate error message. If the value is valid then our supplied function is called with the integer value. Here we return a copy of our configuration class with therevision
field updated.Non-Switch Arguments
Anything encountered on the command line that is not a switch or an argument to a switch is passed to the function supplied to the
arg()
method. Like switch arguments, the non-switch arguments can be of any type for which you have a defined argument parser. In the example above we have specified that non-switch arguments are of typeString
.Switch Names
A switch may have a short name, a long name, or both.
Short names may be specified as a single character preceded by a single dash. You may optionally append an argument name separated by a space. The argument name is only for documentation purposes and is displayed with the help text.
Long names may be any number of characters and are preceded by two dashes. You may optionally append an argument name. The argument name may be separated by a space or by an equals sign. This will affect how the name is displayed in the help text.
Notice that in the case of an optional parameter you may put the equal sign inside or outside the bracket. Again this only affects how it is dispalyed in the help message. If you specify an argument name with both the short name and the long name, the one specified with the long name is used.
There is a boolean switch that does not accept a command line argument but may be negated when using the long name by preceding the name with
no-
. For example:Notice that you only specify the positive form of the name when defining the switch. The help text for this switch looks like this:
Special Tokens
--
is iterpreted as the end of switches. When encountered no following arguments on the command line will be treated as switches.-
is interpreted as a normal argument and not a switch. It is commonly used to indicatestdin
.Switch Types
You can define switches that take no arguments, an optional argument, or a required argument.
Limiting Values
For switches that take arguments, either required or optional, you can specify a list of acceptable values.
Here if the user enters
--color purple
on the command line an org.sellmerfud.optparse.OptionParserException is thrown. The exception message will display the accepable values. Also the user can enter partial values.coolapp --color r // <== Will be interpreted as red
If the value entered matches two or more of the acceptable values then an org.sellmerfud.optparse.OptionParserException is thrown with a message indicating that the value was ambiguous and displays the acceptable values. Also note that you can pass a
Map
instead of aList
if you need to map string values to some other type.Since we are defining a switch with an optional argument, the type of
v
isOption[Color]
.Banner, Separators and Help Text
You can specify a banner which will be the first line displayed in the help text. You can also define separators that display information between the switches in the help text.
Where did the
-h, --help
entry come from? By default the-h
switch is added automatically. The function associated with it will print the help text tostdout
and calljava.lang.System.exit(0)
. You can define your own help switch by simply defining a switch with either or both of the names-h
,--help
. You can also turn off the auto help altogether.How Short Switches Are Parsed
Short switches encountered on the command line are interpreted as follows:
How Long Switches Are Parsed
Long swithes encountered on the command line are interpreted as follows:
Full Example