Generic UNIX Command Line Interface Design

This document discusses the requirements for a generic UNIX command line interface, in this case anvil as well as outlining the User Interface of the solution designed to fulfill these requirements.

Requirement:

The anvil command must be invocable as both a one-shot UNIX command line and as continuous command line interface. (test name: invoke)

To satisfy this requirement there needs to be two ways of invoking anvil, one with a command to execute, in which case the command will be executed and control returned the the UNIX prompt. The other, invoking anvil without a command to execute will put it into "command line" mode which will continue until either quit is entered or CTRL-D pressed at the command line's prompt. Thus the two ways to invoke anvil are as follows

[jboss@sps-expcont]$ anvil <cmd>
[jboss@sps-expcont]$

[jboss@sps-expcont]$ anvil
anvil** quit
[jboss@sps-expcont]$

Requirement:

When executing in command line mode the prompt must identify the environment in which it is executing. (test name: prompt)

The above example already demonstrates this with the command line prompt stating that anvil it the program that is running.

Requirement:

The value returned to the shell when anvil completes must be '0' if it succeeds; negative if there is an error in the invocation and a different negative value if the invoke comman executes but fails. (test name: failure)

A return value of -1 (255) will be used to signal an error with invocation, will any other negative value will be used to signal an error in the executing of command.

Requirement:

The anvil command must provide a command summary if it is not invoked correctly. (test name: usage)

If the UNIX command line can not be correctly parsed the anvil command will display a one line summary of how it can be invoked. In the following example the -1 option is used as an example of an illegal option.

[jboss@sps-expcont]$ anvil -1
Usage: anvil [-hqv?] [cmd]
[jboss@sps-expcont]$

Requirement:

The anvil command must provide help on how to invoke anvil correctly. (test name: help)

To satisfy this requirement the anvil command will support both the -h and -? options to get a summary of the commands usage plus a short write-up explaining how to get started using it.

Both -h and -? are clasified as 'prompt' options, which means that if anvil is invoked with no command and only "" options on the command line, then instead of executing in command line mode, control will immediately return to the the UNIX prompt.

[jboss@sps-expcont]$ anvil -h
 ...
[jboss@sps-expcont]$ anvil -?
 ...
[jboss@sps-expcont]$

Requirement:

Each anvil command must be supported by a help description. (test name: cmd.help)

To satisfy this requirement anvil will provide an help command that take another command as its argument and then displays that acmonds help.

[jboss@sps-expcont]$ anvil help quit

Requirement:

The anvil command must provide access to its version number. (test name: version)

To satisfy this requirement the anvil command will support a version command that displays the version number.

[jboss@sps-expcont]$ anvil version
anvil version: 1.0-SNAPSHOT
[jboss@sps-expcont]$

Requirement:

The anvil command must support the ability to execute quietly, i.e. not produce any output. (The prompt is not considered output for this requirement.) (test name: quiet)

To satisfy this requirement the anvil command will support a general -q option which will switch off all output.

[jboss@sps-expcont]$ anvil -q