Types

This is a required part of the argument definition. It determines the type of data the user will be able to enter as a value for the argument. Other parts of the definition will allow for fine-tuning of the type, like constraints and formats. Each of the examples will also assign the --key parameter so that they make sense; --key is a required part of specifying an argument.

The examples are made up of the Java set up for the parser and then a command-line example of using a program (MyProgram) with that argument.

boolean

Booleans have no value associated with them. If the user indicates a boolean argument then the value is true. Otherwise, if not specified at all, the boolean will be false. (This can be changed with the "default" parameter.)

CmdLine.create("--type boolean --key d");

> MyProgram -d

string

A String lets the user enter anything as the value. It will be interpreted as an formless list of characters. If spaces or special, reserved characters are needed for the value then the value must be enclosed in quotes.

CmdLine.create("--type string --key d");

> MyProgram -d "Hello World"


MyProgram -d NothingSpecialHere

integer

An integer argument expects the user to enter a whole number. It can be negative, but the negative sign (a dash) is a special character. So negative numbers must be quoted.

CmdLine.create("--type integer --key d");

> MyProgram -d 123


MyProgram -d "-456"

long

A long argument expects the user to enter a whole number. It can be negative, but the negative sign (a dash) is a special character. So negative numbers must be quoted. Notice that the sign of the number can be at the beginning or at the end of the number. This is very much like an integer but allows for much larger numbers to be entered. long and integer have more significance when dealing with the --var parameter.

CmdLine.create("--type long --key d");

> MyProgram -d 123456


MyProgram -d "123456-"

MyProgram -d "-123456"

byte

A byte argument expects the user to enter a small whole number; something between 0 and 255. It can not be negative. There are three ways to enter the value; as a single, printable character, an integer between 0 and 255, or as a special symbol representing a special control character like a line feed (LF).

CmdLine.create("--type byte --key d");

> MyProgram -d z


MyProgram -d 87

MyProgram -d LF

This is a list of all of the special symbols and their decimal equivalents.

NULL(0) SOH(1) STX(2) ETX(3) EOT(4) ENQ(5) ACK(6) BEL(7) BS(8)

HT(9) LF(10) VT(11) FF(12) CR(13) SO(14) SI(15) DLE(16)

DC1(17) DC2(18) DC3(19) DC4(20) NAK(21) SYN(22) ETB(23) CAN(24)

EM(25) SUB(26) ESC(27) FS(28) GS(29) RS(30) US(31) SP(32)

float

A float argument expects the user to enter a floating point number. It can be negative, but the negative sign (a dash) is a special character. So negative numbers must be quoted.

CmdLine.create("--type float --key d");

> MyProgram -d 123.005


MyProgram -d "-0.123"

double

A double argument expects the user to enter a potentially very large floating point number. It can be negative, but the negative sign (a dash) is a special character. So negative numbers must be quoted. This is very much like a float but allows for much larger numbers to be entered. float and double have more significance when dealing with the --var parameter.

CmdLine.create("--type double --key d");

> MyProgram -d 1.23456


MyProgram -d "12345.6-"

MyProgram -d "-123.456"

date

A date argument expects the user to enter a date that may include a timestamp as well. If any special characters, including a space, are to be used in the date / time then the value must be quoted. See the discussion on --format for details on controlling the date / time format the user can use to type in a date. The assumption in this example is that the format will be month, day, and year only.

CmdLine.create("--type date --key d --format MMddyy");

> MyProgram -d 040960

That example would set the date to be April, 9th 1960. Dates roll forward. So if you enter 45 as the day part of the date then it will add one to the month and set the day to be around 15 days into that month.

enum

An enum lets the user enter a value that must be a member of a specific enum class. There can be no spaces or special characters in an enum so quotes are not necessarily needed for any value, but they could be used if so desired. An enum requires a Java enum class to be associated with the argument. Please see the documentation on variable assignments for more specifics. In this example it is assumed that a variable in your class (logLevel) is of a type of LogLevel, an implementation of enum. logLevel will be set to the corresponding enum value according to what the user enters as the value. An incorrect value will produce an error for the user.

CmdLine.create("--type enum --key d --var logLevel");

> MyProgram -d WARN

file

A file argument expects the name of a file, perhaps even a path (or only a path), to be entered as a value. Argument will create a File instance with the name set up to be the provided value.
It is almost always a good idea to quote the file names just be make sure any spaces or special characters do not cause problems.

CmdLine.create("--type file --key d");

> MyProgram -d c:/tmp/myFile.txt


MyProgram -d "c:/program files/myFile.txt"

pattern

A pattern argument allows the user to enter a Pattern as a value. It is a good idea to always quote the value coming in since patterns most often contain special characters and spaces. Argument will create a compiled instance of a Java Pattern. It can then be used to match other Strings.

This can be used for something like a database query where MyProgram takes the supplied pattern and uses it to select records that in this case have "Joe" as the beginning part of a column in the database.

CmdLine.create("--type pattern --key d");

> MyProgram -d "Joe.*"