pilot(1) Manual Page

pilot [-dcmpk] [-v num[y]] [files…​]

This program is an interpreter/compiler for IEEE PILOT. Details of the language may be found in the written standard. This interpreter supports the core language plus certain proposed extensions, as detailed below. The purpose of this interpreter is to serve as a reference implementation of the IEEE PILOT language for users wishing to check standards conformance of PILOT programs and other implementations. The source distribution also provides portable model C code for standards-conforming implementations.

Four options control the behavior of pilot. The -v option controls the parser/lexer’s verbosity. Verbosity level 1 echoes each line to stderr just before it is processed (for better context on errors). Level 2 reports on each token found by the lexer. If your PILOT was generated with YACC supporting the -t option, suffixing a level with "y" causes the parser to report on the actions it is taking to parse each PILOT statement. The -d option causes all relevant system variables to be dumped after each statement. The -m option suppresses the normal exit on syntax error. The -p (pedantic) option forces strict IEEE conformance.

These options may also be set by a line beginning with # embedded in program text. Thus, for example, "-v2y" enables lexer reporting and parser reporting. You may switch off options by prefixing them with "+". Thus, "+y" would turn off grammar reporting. This # feature is disabled if the -p option is on.

The -c option causes PILOT to compile each argument file named to executable object code; this option cannot be given on a # line. PILOT source files must have a .p extension. This is actually accomplished by generating C code from the PILOT source and compiling the C; if you want to get a look at the translation, the -k option is available to prevent the .c file from being delated.

The IEEE standard for PILOT is underspecified in some important respects. Thus, an implementor has to make choices about how to resolve ambiguities. The choices made in this reference implementation are detailed here. Paragraph numbers reference the relevant section of the Standard.

2.3: The Standard does not specify whether or not ACCEPT strips the line terminator from input before copying it to %answer. This implementation performs the stripping.

2.3: In an ACCEPT statement with a numeric ID, the Standard does not specify how the contents of %answer is to be interpreted as a number. In this implementation, a leading string of decimal digits is interpreted as a number.

2.3: The Standard does not specify what a "valid" label is. Forward-referencing of labels is permitted. That is, a jump to a label may occur before the declaration of the label.

2.3: When looking for IDs embedded in <text>, this implementation considers them to be lexically bounded by any non-<limited-string> character, choosing the longest match. Thus, the text "foo$bar,baz" is parsed as "foo" $bar ",baz", rather than "foo" $ba "r ,baz" or any others of the alternatives permitted by the Standard.

2.3: Each <text> part is treated as a character stream and not tokenized; all whitespace after the colon or : introducing it is significant.

2.3: The text "abc$def" is resolved as the string identifier abc$ followed by the literal "def"; that is, postfix $ is considered the preferred marker for a string identifier where there is ambiguity.

2.3: The * wildcard in the MATCH statement prefers the shortest match. Thus, if "b*a" is matched against "foobaaaz", %matched will be "ba", not "baa".

Whitespace after alternation characters in match patterns is skipped. The Standard is silent on this, and the Standard’s lexical rules are not sufficiently precise to exclude it; it follows pre-existing practice.

2.3: The actions of the FILE and GRAPHICS core language statements are not defined. In this implementation, they produce a warning message.

The initial value of a numeric variable is 0. The initial value of a string variable is the empty string (some existing implementations make it the string form of the variable’s name, without $).

Section numbers below reference paragraphs in the official correction sheet for the Standard.

4.1: The PAUSE extended command is implemented. The syntax is:

PAUSE may be abbreviated PA, as in Nevada and Atari PILOT. The semantics is that if <condition>, which is a normal condition-part, is satisfied, the interpreter sleeps for <expression> seconds. Use of PAUSE will raise an error if the -p option is on.

4.1: The LINK extended command is implemented. The syntax is:

LINK may be abbreviated L, as in Apple PILOT. The semantics is that if <condition>, which is a normal condition-part, is satisfied, the interpreter interprets the text part as a filename, and executes that file as a PILOT program as though it had been inserted, replacing the LINK statement. However, you may not JUMP or USE from a LINKed file to the containing one, or vice-versa. Use of LINK will raise an error if the -p option is on.

In compiled programs, LINK looks first for a binary in the in current directory, then for an interpretable source in the current directory, then for a binary in the PILOT library directory, finally for an interpretable source in the PILOT library directory; the sys_status variable is set to -1 if it finds none of these, otherwise to the return status of the binary or the PILOT interpreter called on the source.

In interpreted PILOT, when you call another PILOT program with LINK, any variables set in the 'outer' PILOT program are also set for the 'inner' one; in effect, the text of the called program is inserted at the point of the LINK. A compiled program neither makes its variables available to a program it calls nor picks up variables from a calling program.

4.1: The TYPEHANG extended command is implemented. The syntax is:

TYPEHANG may be abbreviated TH, as in Nevada and Apple PILOT. The semantics is that if <condition>, which is a normal condition-part, is satisfied, the program writes the contents of %text to standard output with no terminating linefeed. Use of TYPEHANG will raise an error if the -p option is on.

4.1: A new command, SYSTEM, is supported. The syntax is:

SYSTEM may be abbreviated XS, as in Nevada PILOT. The semantics is that if <condition>, which is a normal condition-part, is satisfied, the program sends the text part to the underlying operating system shell as a command. A new system variable, %status, holds the integer status (if any) returned by the command; typically, a return of 0 means the command executed normally while other values indicate errors. Use of SYSTEM will raise an error if the -p option is on.

4.1: The CLEARHOME extended command is implemented. The syntax is:

CLEARHOME may be abbreviated CH, as in Nevada PILOT. The semantics is that if <condition>, which is a normal condition-part, is satisfied, the program attempts to clear the output terminal screen and home the cursor. Under UNIX this is done via the termcap(3) libraries; on non-UNIX systems it is implemented by sending a form feed to standard output. This feature is disabled when the -p option is on.

4.1: The CURSADDR extended command is implemented. The syntax is:

CURSADDR may be abbreviated CA, as in Nevada PILOT. The semantics is that if <condition>, which is a normal condition-part, is satisfied, the program attempts to position the screen cursor to the given row and column (both must by integer constants). Under UNIX this is done via the termcap(3) libraries; on non-UNIX systems it is implemented by sending an ANSI cursor-positioning sequence to stdout. This feature is disabled when the -p option is on.

4.7 Intraline comments with // are supported. Note that in order to use a // in a <text>, you must escape the first character thus: \\//. This feature is disabled when the -p option is on.

4.8 All system variables named in the Standard are defined as read-only variables in this implementation: that is, %expression, %term, %factor, %nextstmt, %uselevel, %maxuses, %answer, %matched, %left, %match, %right, %satified, %relation, %text. There are, as described, variables %return1, %return2 etc. This feature is disabled when the -p option is on.

The Standard does not specify the true/false values of %matched, %satisfied, and %relation; we use 0 for false, 1 for true on the latter two. The value of %matched is 0 if no match was found; otherwise, it is the number of the alternation matched counting from the left.

4.9: The special pseudo-labels @P, @A, and @M are supported. This feature is disabled when the -p option is on. The PROBLEM statement behaves like a REMARK.

4.10 The 'modulo' binary operator is supported, as a multiplicative operator written `%' (to conform with existing implementations). This feature is disabled when the -p option is on.

Unary minus is permitted in expressions to specify a negative numeric constant or negate a subexpression. This feature is disabled when the -p option is on.

If the 'pedantic' switch (-p) is off, the leading "*" may be omitted from the target label in JUMP and USE statements. This violates the Standard but is permitted in other PILOTs.

A new escape syntax for embedding nonprintable ASCII characters in text is supported. Escapes are as follows:

In addition, \\ preceding a carriage return neutralizes it as a line terminator, permitting a logical line to span multiple physical lines. This feature is disabled when the -p option is on.

The CLEARLINE extended command is implemented. The syntax is:

CLEARLINE may be abbreviated CL, as in Nevada PILOT. The semantics is that if <condition>, which is a normal condition-part, is satisfied, the program attempts to clear to end of line. Under UNIX this is done via the termcap(3) libraries; on non-UNIX systems it is by sending an ANSI escape sequence to standard output. This feature is disabled when the -p option is on.

The CLEAREND extended command is implemented. The syntax is:

CLEAREND may be abbreviated CE, as in Nevada PILOT. The semantics is that if <condition>, which is a normal condition-part, is satisfied, the program attempts to clear to end of screen. Under UNIX this is done via the termcap(3) libraries; on non-UNIX systems it is implemented by sending an ANSI escape sequence to standard output. This feature is disabled when the -p option is on.

The JUMPMATCH statement is implemented. The syntax isL

JUMPMATCH may be abbreviated JM, as in Nevada and Atari PILOT. The semantics is that if <condition>, which is a normal condition-part, is satisfied, the program looks at the %matched value from the last MATCH. If the value is zero (no match) the statement is ignored. If the value is k > 0, the kth label in the list is JUMPed to. If k is greater than the number of labels in the list, the statement is ignored.

The END statement allows a numeric expression argument, which is passed back as the interpreter’s return status. This feature is disabled when the -p option is on.

A "?" typed at the beginning of a line prints out a brief interactive help message. This feature is disabled when the -p option is on.

A "!" typed at the beginning of a line escapes the remainder of the line to the underlying shell. This feature is disabled when the -p option is on.

The command-continuation feature of some pre-IEEE PILOTs is supported. That is, an elided keyword-condition part repeats the last one. This feature is disabled when the -p option is on.

0 for successful execution, 1 for errors while compiling or executing. This may be overridden by the argument to an END.

PILOTDIR sets the location of the PILOT library directory.

The language design is appallingly ugly to begin with, and the 1991 IEEE standard has numerous syntactic and semantic holes. See the Implementor’s Comments on the IEEE PILOT Standard

Eric S. Raymond <esr@snark.thyrsus.com>, November 1991.

IEEE Standard 1154-1991: 'IEEE Standard for Programmed Inquiry, Learning Or Teaching (PILOT)' ISBN 1-55937-151-X, dated August 22 1991.

Correction Sheet, pages 13-15, dated September 23 1991.

'Implementor’s Comments on the IEEE PILOT Standard' by Eric S. Raymond (included with the source distribution).