Using Argument on the Command-line
How to interact with the command-line is probably the most important thing to know about Argument. You will need to know this to set up your own parser and to use your application once it incorporates Argument into it.
Argument as the Command-Line Interface
When you see “$ ” in an example that indicates a command-line prompt. It is when the operating system is waiting for your input.
$ MyProgram [Argument Input]
MyProgram is your application that has been coded to use Argument. Argument then intercepts everything after the name of your program. Argument interprets it and then allows your program to access the input after it has been processed.
Argument Command-Line Input
Everything that is processed by Argument is in the form of
[command] [value]
with one exception; positional arguments. A positional argument is only the value with an assumed command.
The Anatomy of [command].
All commands start with a command prefix followed by a command word. A command prefix can be overridden to be whatever you want – but the default is a dash, or hyphen (-). A typical integer based command would look like this…
-p 25
“p” is the command word and “25″ is the value. In this case, to MyProgram, “p” was meant to mean “port”. And we could have used the more verbose specification of
--port 25
Notice the two dashes as the command prefix. And the full word “port” after it. It is easy to set this up so that MyProgram will understand either input. (--) is always used to specify a more verbose command word. Whereas (-) always has a single character command word that follows it.
Returning an argument to its default value. (-!)
Multiple Values for a Command
In this example MyProgram wants a list of ticker symbols to process. So we use Argument to have a command ticker that will allow as many ticker symbols that the user wants to type.
$ MyProgram --ticker IBM GOOG AAPL
This list of ticker symbols will continue until the end of the input or until the next command prefix is found. Argument will let you separate the values with commas if you want, it is optional but sometimes it is easier to read.
$ MyProgram --ticker IBM,GOOG,AAPL
Concatenating Multiple Single Character Command Words
Let’s take this example one step further and tell MyProgram that we want to display the ask, bid, and possibly the last sale. To do this we set up MyProgram to allow three boolean commands; -a, -b, and -l. Now the user can use any combination of these on the command-line.
$ MyProgram --ticker IBM,GOOG,AAPL -a
would show only the ask price for these 3 tickers. And
$ MyProgram --ticker IBM,GOOG,AAPL -a -b -l
would show the ask, bid, and last sale values for all three tickers. These boolean commands can be strung together with only one prefix (-).
$ MyProgram --ticker IBM,GOOG,AAPL -abl
This is just shorthand that is normally expected.
Order is not Usually Important
The previous command could have been entered in a different order without any problems. MyProgram would not know the difference after Argument was done processing it.
$ MyProgram -a --ticker IBM,GOOG,AAPL -lb
Order is important when positional commands are used.
Positional Commands on the Command-line
A typical use for a positional command is a file name. Let’s use Funnel as the program and it wants to sort a file. So Funnel needs a command that lets the user enter the file name. We could do it with a normal command like –inputFile myFile.txt. But for this example we don’t want to use a command prefix or command word, so we instead use the positional command.
$ funnel myFile.txt
The concept of positional commands becomes more clear when there are at least two different positional commands for the same program. So lets also have Funnel allow for the output file to be a positional command.
$ funnel myFile.txt myOutputFile.txt
Positional implies order. So when Funnel’s Argument processor is defined we specified the order of these two positional arguments; the input file is always first and the output file is always second.
Important Consideration when Using Positional Commands
The positional commands are processed last by Argument. All keyword commands are first parsed and removed from the command line. Whatever is left is considered positional.
It is possible to define a multiple value positional command. That might be useful if MyProgram wanted to make –ticker be positional rather than the keyword version as we have previously used. Then it might look like this…
$ MyProgram IBM, GOOG, AAPL
Because of the multi-value nature of the ticker symbol command it is not possible to have more than the ticker command be positional. Argument would not know when the ticker command ended and the subsequent positional command started. In these cases, when a multi-value positional command is needed, then all other commands must be named.