Options and Flags

All command input — flagged or positional — resolves to an option. The library does not distinguish between traditional “flags” (boolean switches) and “options” (value-bearing parameters) — all are options.

Terse flags — single dash, single letter:

-f  -o  -v

Verbose flags — double dash, more than one character:

--from  --overwrite  --verbose

An option definition requires a verbose flag. The terse flag is optional. Either form is accepted at the command line when both are defined.

Flags and option keys are case-sensitive. --Verbose and --verbose are distinct flags.

Positional Arguments

Arguments can be passed without flags, matched to options by their definition order. Positional passing is valid until a position is skipped — at that point the remaining arguments must be flagged.

Given a copy command with options defined in order from, to, silent, recursive:

copy d:\tmp\doc.txt d:\tmp2\doc.txt                               # fully positional
copy --from d:\tmp\doc.txt --to d:\tmp2\doc.txt                   # equivalent

copy d:\tmp\doc.txt d:\tmp2\doc.txt --recursive true              # positional until skip, then flagged
copy --from d:\tmp\doc.txt --to d:\tmp2\doc.txt --recursive true  # equivalent ('silent' uses default in both)

Boolean Options

A boolean option does not require an explicit argument. The presence of the flag implies true:

myapp.copy --overwrite
# equivalent to:
myapp.copy --overwrite true

When an explicit argument is provided, the following literals are accepted (case-insensitive):

Terse Flag Chaining

Terse flags can be chained Unix-style. The last flag in the chain may take an argument; all preceding flags must be boolean options and are resolved as true.

Given a copy command with options overwrite, silent, from, and to mapped to terse flags -o, -s, -f, and -t, the following three forms are equivalent:

myapp.copy -osf c:\tmp\hello.txt -t c:\tmp2\hello.txt
myapp.copy -o -s -f c:\tmp\hello.txt -t c:\tmp2\hello.txt
myapp.copy --overwrite --silent --from c:\tmp\hello.txt --to c:\tmp2\hello.txt

Explicit Assignment

The = operator binds a flag to its argument without ambiguity. Use it when the argument value could otherwise be tokenized as a flag — because it starts with a dash or is a negative number:

myapp --input=--verbose           # argument is the string "--verbose"
myapp --loss=-1000                # argument is the negative number -1000
myapp -f=--verbose
myapp -f=-1000

Spaces around = are permitted:

myapp --loss = -1000
myapp -f = --verbose

Quoting is the alternative for the same cases:

myapp --input "--verbose"
myapp --loss "-1000"

Explicit assignment does not extend across spaces — a spaced value still requires quotes:

myapp --label="some spaced value"     # correct
myapp --label = "some spaced value"   # correct
myapp --label = some spaced value     # throws CommandParseException