NT SYNTAX - proposed syntax for Thinkage Windows NT software.

Description:

This file describes the command line syntax for Windows NT commands written by Thinkage Ltd.

A command consists of a command name, possibly followed by one or more arguments separated by blanks. An argument is basically a string of text, taking one of the following forms:

Strings and redirection are handled by the command interpreter, so they require no further discussion.

Keyword Options:

A keyword is an unquoted string which is a mnemonic for an option to a command. There are several simple forms:

 keyword
/keyword
/keyword+
/keyword-

The first three forms have more or less the same function: they turn on a particular option or override defaults. The convention is that a "/keyword+" turns an option on, while "/keyword-" turns the same option off. An option of the form "/keyword" is equivalent to "/keyword+".

For example, suppose that the default for a particular command is to write output to the standard output.

kommand /output-

might "turn off" the output so that it is not produced. Similarly, if a command normally does not produce certain tables,

kommand /tables+

overrides the default and tells the command to produce the tables.

The syntax also allows for options that can have three possible levels of effect. For example, suppose that

kommand

outputs a certain amount of information. Then

kommand /verbose+

might print out more verbose information, while

kommand /verbose-

might print out less verbose information. In other words, you can have higher, lower, or default levels of information, depending on whether you specify /keyword+, /keyword-, or omit the option.

Keywords with Values:

Some options are set by specifying a single value. In this case, the form of the option is

/keyword:value

If an option accepts multiple values, the following forms are both accepted:

/keyword:value,value,value
/keyword:value value value /
/keyword: value value value /

Notice that the second form uses a "/" character to mark the end of the list. This can be omitted if the list extends to the end of the command line, or to another keyword option beginning with "/".

It is possible to specify a null string as a value for an option, as in

/keyword: /

Notice that the space followed by a closing "/" is necessary to show that there is no value.

Abbreviation of Keywords:

Keywords may be abbreviated to a certain degree. The amount of abbreviation is determined to a great extent by the other options for the command -- minimal abbreviations are chosen to be as short as they can be without risking confusion with other abbreviations.

Valid abbreviations for an option may be determined from the way the keyword is shown in the explain file. An option will be listed with a number of capitalized letters and possibly some lower case letters. The capital letters must be given in any abbreviation of an option; small letters may also be given, but in all cases the letters must appear in the order given as spelled out in full. The minimal abbreviation consists only of the capital letters; this minimal abbreviation should always be unambiguous.

Option           Some abbreviations
------           ------------------
/Hstar:           /h:, /hs:, /hstar:
/Forward          /f, /for, /forward
/ForwardRegister  /fr, /for, /foreg

The user is warned to be wary however, as the "/Forward" and "/ForwardRegister" examples above show; "/for" is a valid abbreviation for both options, but will be interpreted as "/ForwardRegister". Note that the abbreviation "/f" is always interpreted as "/forward".

Positional Arguments

A positional argument is one which must appear in a certain position relative to other options or the command name. Our general policy is to avoid positional arguments except in high-use commands. For example,

copy fromfile tofile

is a reasonable format because users quickly become accustomed to the required position order. However, in low-use commands it might be preferable to have

copy /From:fromfile /To:tofile

Uniform Keywords

When several commands all support options that have comparable functionality, all the commands should use similar formats and/or option keywords. For example, when several commands all support options to increase or decrease the amount of output, the options should all use the keyword "Verbose" (as in "/Verbose+" or "/Verbose-").

All Thinkage commands should support a "/HELP" option that tells the command to output a list of all acceptable arguments and options, plus a short description of their meanings. For example,

kommand /HELP

might print

Usage: kommand [options]
  options:
    /Verbose+     Display more information than default
    /Verbose-     Display terse information

Copyright © 1997, Thinkage Ltd.