UI Style Guide Shell

The Shell

One of the best things about the Amiga is its versatility. While the rest of the personal computing community continues to argue about the best type of interface, Amiga users have both - a graphic interface with Workbench and a text-based interface with the Shell.

The Shell (also known as the Command Line Interface or CLI) preserves the best features of operating computers the "old-fashioned way", that is, by typing commands at a console. Although that is in some ways more difficult than clicking on graphics with a mouse, it provides a finer level of control, less overhead and greater power than is possible through a GUI.

Virtually anything that can be done through Workbench can also be done through the Shell. On Workbench, for instance, a user can move into a subdirectory by double-clicking on its drawer icon. The equivalent of this in the Shell is to type

 cd <subdirectory name>

The command dir will then list the contents of the directory.

The same example can be used to illustrate the greater power of the Shell. In addition to dir, which gives a brief listing of files and subdirectories, the user can also use list which gives a more in-depth listing including the size of each file, information about the file and when it was last updated. Or you could list only a subset of files by using wildcards in the command. For example,

 list #?.info

would list only those files ending with ".info".

The Shell

In addition to being able to do things with finer control than Workbench, the Shell can also do some things that Workbench cannot do at all. For instance, from the Shell you can create a script - a pre-recorded set of commands that helps to automate repetitive tasks.

Note
Your application should support all three interfaces built into the Amiga: the GUI, the Shell and ARexx.

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.

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.

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.

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

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.

Modifier	Description
,(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, e.g. 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 file names 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.

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

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 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 file name. 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 file name is given)
 play anim myanimfile loops (the numeric value for LOOPS is missing)

Standard Arguments

The following Shell arguments are standard within the system. Don't use these names for application-specific arguments with purposes different than those given below:

 FILES/M      List of files to work with as projects
 PUBSCREEN/K  Name of the public screen to open on
 PORTNAME/K   Name to assign to the ARexx port
 STARTUP/K    ARexx script to run at startup time
 NOGUI/S      Indicates that no GUI is desired
 SETTINGS/K   Name of preferences file to load at startup

If you need a keyword for your application, try to find an applicable one that is already in use - and use it the same way. If you need to make a new keyword, don't make it the same as a common command name; e.g. "list".

Pattern Matching

When most people think of pattern matching, they think of using wilcards, but pattern matching is actually much more. It's a powerful feature that enables more efficient operations, especially on systems like the Amiga that have a hierarchical file system with few size limits.

Pattern matching is part of the appeal of the Shell. It would be difficult to use icons to perform an operation on 50 files at once - not to mention the problem of fitting all the icons on a 12-inch monitor. Some complex operations are just easier to do with a text interface.

Standard Available Tokens

Token	Description
?	Matches a single character. For instance a? matches any string with two characters that starts with the letter a.
#	Matches a subsequent expression 0 or more times. For instance, the pattern #? will match any string.
(ab|cd)	Matches any one of the items separated by |.
~	Negates the following expression. For instance the pattern ~x? will match any two letter string except those starting with x. Another corollary of this is the pattern ~(x?) which will match anything except two-letter strings beginning with x; ie. xaa or ab but not xa.
[abc]	Character class; matches any one of the characters in the brackets.
[a-z]	Character range (must be within character classes). You can also use [a-e,x-z] style.
%	Matches 0 characters always. For example, the pattern (foo|whiskey|%)bar matches foobar, whiskeybar and bar.
*	Synonym for #?. Not available by default but it is an option that can be turned on.

Expression in this table means either a single token or character token (such as ? or x), or an alternation (such as (ab|cd|ef)), or a character class (such as [a-z,A-Z]).

The Amiga's Wildcard

On the Amiga, the wilcard is #? - as opposed to * on other platforms. For example, the command

 delete #?.info

would delete all the files in the current directory that end in .info.

Within Applications

In addition to its usefulness on the filing system, pattern matching is also useful within applications. For example, the Find function within a text editor should be able to find strings according to a pattern.

Your application should support pattern matching from the Shell and from functions within the application itself, through AmigaDOS system routines.

Embedded Version IDs

Follow the standard method for indicating the version of your software.

The Shell command VERSION provides support for version identification, but you have to follow a standard template.

A text sequence that indicates the current version of your application should be embedded within your code. (It should also be put in your ARexx scripts and your configuration files.) The format of this text sequence is:

 $VER: <name> <version>.<revision> (<d>.<m>.<y>)

 <name>         The name of your application
 <version>      Major version number
 <revision>     Minor revision number
 <d>            Day created
 <m>            Numeric month created
 <y>            Year created

If you follow this template, the user can find out what version of your software he is using with the Shell command VERSION.