CMDGEN Commandline Interface Generator

Contents

    0.0: Invocation
    A.0: Syntax
      A.1: Grammar
      A.2: Lexical Syntax

0.0: Invocation

    cmdgen [options] [filename]
           -q           Print this message
           -o filename  Write output to this file
           -v           General verbosity flag
           -V           Include verbose information
           -d filename  Write data structures to this file
           -k           keep output file on error
           -w           treat warnings as errors

A.0: Syntax

• Items typed in TYPEWRITER font (uppercase) represent keywords which would be entered explicitly in a CMDGEN program.
• An item typed in lowercase is a non-terminal. The grammar recursively defines how non-terminals can be expanded. For example, the non-terminal rules can be expanded by zero or more rule non-terminals, and so on. Each line beginning with an indented colon (:) marks a possible expansion of the non-terminal being defined. Within an one of these expansions, each reference to a non-terminal is a link to that non-terminal's definition.
• Items bracketed by angle brackets (e.g. <INTEGER>) are lexical tokens. Their syntax should be implicit in their names.
• I have used brackets ([]) to signify optional items. I use the notation [ item ... ] to indicate that an optional item may be repreated indefinitely. The colon (:) at the beginning of a line identifies a non-terminal expansion (right-hand-side). Literal punctuation is enclosed in single quotes ('*').

A.1: CMDGEN Input Grammar

  rules
    : [ rule ... ]

  rule
    : '%INTERFACE' <INTERFACE-SPEC>
    : nt-spec [ ':' sub-items ... ] ';'

  nt-spec
    : <NON-TERMINAL> [ <TYPE-SPEC> ]

  sub-items
    : [ sub-item ... ]

  sub-item
    : <WORD>
    : '*'
    : <NON-TERMINAL>
    : <VAR-SPEC> [ <PROMPT> ]
    : <C-CODE>

A.2: CMDGEN Lexical Syntax

C-CODE

C code is enclosed in curly braces ({}). The input routine is not terribly clever, so don't try to embed unbalanced braces inside strings or comments! Within the C code, an assignment to $0 defines the value assigned to the "left-hand-side" non-terminal. $1 is the value returned by the variable or non-terminal in the first word position of the right-hand-side expression. $2 is the value returned for the second word position, etc.

NON-TERMINAL

a non-terminal begins with one or two ampersands ($amp;) followed by a letter and any number of letters, numbers or underscore characters. Examples are "&commands", "&oh_cmd" and "&&local". In client/server architectures, non-terminals beginning with two ampersands define commands which are to be processed locally rather than being sent to the server for execution.

INTERFACE-SPEC

An interface specification consists of an interface name enclosed in angle brackets. The interface name may have a qualifying string appended after a colon. Accepted syntaxes include:

<name>

The server will create a readable interface at /dev/huarp/$Experiment/cmd/name. Clients can open this interface and read commands. Within the cmdgen source, commands can be issued using the syntax: name_if.Turf(fmt, args ...) where fmt and args are standard printf-style arguments.

<name:DG/data>

This syntax is used to send data to telemetry via the Col_send() mechanisms. name must be the name of a variable (usually a structure) defined in the server and also referenced in a TM “Receive” statement. The data is sent via the syntax: name_if.Turf();

<subbus> or <subbusd>

Simply ensures that the subbusd daemon receives a quit command on shutdown. This is useful if subbusd is started as part of the instrument startup script, but not if it is started as part of the system boot scripts.

<name:path>

This syntax is used when the client has its own writable command interface. As with the first syntax above, commands are issued via the syntax: name_if.Turf(fmt, args ...) and the resulting command is written to the specified path. If path does not start with a '/', it is prefixed with /dev/huarp/$Experiment/.

TYPE-SPEC

A type specification is a C data type enclosed in angle brackets which defines the type represented by the non-terminal. Examples are "<unsigned short>" and "<struct foo *>".

PROMPT

A prompt is a string enclosed in parentheses which is displayed by interactive clients when the previously specified variable is being input.

WORD

A word is simply any non-whitespace text which doesn't begin with a left-brace ({) or a percent sign (%). Words are treated as literal command text which must match the input.

VAR-SPEC

Variables are specified using the following % escapes:

      escape  type                Default Prompt
      ---------------------------------------------------------------------
        %d    short  Enter Integer (Decimal: 123, Hex: 0x123F, Octal: 0123)
        %ld   long   Enter Integer (Decimal: 123, Hex: 0x123F, Octal: 0123)
        %x    short  Enter Hexadecimal Number
        %lx   long   Enter Hexadecimal Number
        %o    short  Enter Octal Number
        %lo   long   Enter Octal Number
        %f    float  Enter Floating Point Number
        %lf   double Enter Floating Point Number
        %w    char * Enter Word Terminated by <space>
        %s    char * Enter Word Terminated by <CR>

Arbitrary C Code

A line beginning with "%{" marks the beginning of a segment of arbitrary C code which is to be passed through to the output file. The segment is terminated by a line beginning with "%}"

Return to Manuals Guide