Parsing commands

You should use the command template method for parsing the command line:

Standard Form

In general, Shell commands take the form:

COMMAND [redirection-argument] [<argument1>, <argument2>, ...]

where COMMAND is the name of an executable file, [redirection-argument] is a "<", ">", and/or ">>" symbol followed by an AmigaDOS device name, and [<argument1>, <argument2>, ...] is a list of arguments that will be passed to the executable file.

Here's a sample Shell command:

play myanim loops 20

The command is play (an executable program), there is no direction and three arguments are passed to the play program: myanim (the name of the data file), loops (a command option) and 20 (another command option).

Built-in Parsing

The Amiga, like UNIX and many other systems, passes command line arguments to your application. The system automatically provides the list of arguments and counts them for the application.

The system also needs to parse these arguments.

Parsing refers to the job of examining the arguments to find out what they mean so the appropriate operation can be performed.

Using AmigaDOS routines to handle command line parsing can shorten both your code and your development time.

Prior to Release 2 of the Amiga operating system, each application designer had to manage his own parsing. This resulted in a variety of command styles and a more complicated Shell environment for the user. So the designers of Release 2 built a standard way of processing Shell arguments into the system.

When your application is started from the Shell, any arguments should be parsed using the command template method - the same method used to parse all the system-supplied Shell commands. This argument parsing method should also be used by your ARexx or scripting commands for more information).

By far, the greatest benefit of this method is that it allows you to use AmigaDOS routines to handle the chore of parsing the command line. The DOS routines will handle errors and give help messages so both your code and your development time can be shorter. Using standard argument parsing also makes the Shell interface more consistent and more comfortable for the user.

The Command Template

In order for your application to use standard argument parsing, a command template must be constructed to describe the arguments that the command understands.

In the command template, each argument is specified by a keyword (a preset argument that the program understands) followed by a modifier that describes the properties of that argument. Modifiers take the form "/X" where X is one of the characters from the table below. Each keyword can have none or many of the modifiers.

Neither the keywords nor the modifiers are case-dependent. The format shown here corresponds to the way the system displays command templates in the Shell.

Use the standard command template described here in your Shell and ARexx commands.

,(comma) - No arguments
The comma indicates a null argument. It also separates arguments in the command template.

= - Equivalents
The equal sign indicates equivalent abbreviations for keywords, eg. PS=PUBSCREEN/K.

/A - Always required
The argument must be supplied in order for the command to be accepted.

/F - Final argument
If this is specified, the entire rest of the line is taken together as a single argument, even if other keywords appear in it.

/K - Keyword required
This means [that] the actual keyword must be typed on the command line along with its argument in order for the argument to be processed (often the keyword is optional). The argument will not be interpreted unless the keyword appears.

For example, if the template is NAME/K, then unless Name=<string> or Name <string> appears in the command line, the command will be interpreted as having no Name argument at all.

/M - Multiple argument
There can be a number of instances of this argument. For example, the AmigDOS Join command lets your merge together any number of files into a single file. The template is:

FILE/M,AS=TO/K/A
This allows commands such as:

Join file1 file2 file3 as bigfile

When the /M modifier is the first argument in a template, any number of filenames may be specified by the user.

If a command line has any leftover arguments, they will be interpreted as belonging to the /M argument. So only specify one /M per template. For example, in the command Join one two as bigfile three, the word three is an extra argument. In this case, one, two and three will be merged together to form bigfile; the extra argument is tacked onto the /M arguments.

The /M argument also interacts with the /A argument. If there aren't enough arguments given to fill all the /As, then part of the previous /M argument will be used to fill in the /As.

N - Number
This argument is a decimal number. If an invalid number is specified, an error message will be returned to the user. Unless the /N modifier is specified, all arguments are assumed to be strings.

S - Switch keyword
This modifier indicates a switch keyword argument. If the keyword is given, the switch is "on". If the keyword isn't given, the switch is "off".

T - Toggle keyword
This is similar to /S but, when specified, it causes the switch value to toggle from "on" to "off" or vice-versa.

Displaying the Command Template

When a user types a command name in the Shell followed by a space and a question mark, the command template should be shown to him. This acts as a sort of help message that gives the syntax of the command. For instance, in the above example of play myanim loops 20 the command is play. When the user types play ? in the Shell he should see this:

ANIM/A,LOOPS/K/N

This means [that] the command has two arguments: the Anim argument and the Loops argument. The Anim argument consists of the optional keyword ANIM followed by an animation filename. The /A modifier means this argument must always be given.

In the Loops part of the argument, the /K means that the keyword LOOPS is required for the argument to be processed correctly, and the /N means that the LOOPS keyword should be followed by a decimal number. Notice that since the Loops argument does not have a /A modifier, it could be left out altogether.

Other possible commands a user could come up with include:

play myanimfile loops 20
play myanimfile
play anim myanimfile

These commands, however, would be illegal:

play myanimfile 20          (the required keyword LOOPS is missing)
play anim                   (no filename is given)
play anim myanimfile loops  (the numeric value for LOOPS is missing)