ACRi FREEFORM COMMAND LANGUAGE

NOTE: This section is an excerpt from Appendix B of ANSWER and PORFLOW Manuals.

ACRi FREEFORM™ command language, developed by Analytic & Computational Research, Inc., provides a simple user interface for complex software packages through a set of conversational, English-like commands.  These commands are free of any requirements of format or hierarchy except those naturally arising from the nature of the input. These provide for interactive input or emulate the interactive input in batch mode.

B.1    THE FREEFORM™ INPUT RECORDS

B.1.1  The Keyword Record

B.1.2  The Continuation Record

B.1.3  The Comment Record

B.2    ELEMENTS OF INPUT RECORD

B.2.1  The Keyword

B.2.2  The Modifier

B.2.3  The Numeric Field

B.2.4  The Separator Field

B.2.5  The Terminator

B.2.6  The Comment Field

B.2.7  The Prompt

B.1    THE FREEFORM™ INPUT RECORDS

The FREEFORM™ Input is specified through three types of records: KEYWORD, CONTINUATION and COMMENT records. These are described below.

B.1.1    The Keyword Record

Function

• To specify the numeric and character data.

Structure

• A keyword record must begin with a keyword.
• Only one keyword per record is allowed.
• Modifiers and numerical fields may follow the keyword.
• Comment, separator, or terminator fields must separate all the keyword, the modifiers and the numerical fields from each other.
• Any character or numeric data on a keyword record after the first occurrence of a terminator are ignored.

B.1.2    The Continuation Record

Function

• To continue numeric and character input started by a previous keyword record.

Structure

• A continuation record must begin with either a separator or a numeric character as the first character of the record.  It must not begin with an alphabetic ('A' through 'Z' or 'a' through 'z') character as the first character of a record.
• A continuation record may only occur after a keyword record for that group.
• A continuation record must consist only of a combination of modifiers and numerical fields separated from each other by separators.
• Any character or numeric data on a continuation record after the first occurrence of a ter­minator is ignored.
• Any number of continuation records may follow a keyword record.

B.1.3    The Comment Record

Function

• To enhance the clarity and readability of the input.

Structure

• A comment record must begin with a back-slash (/), asterisk (*), dollar ($) or exclamation (!) character in the first column of a record. Any combination of characters may follow the first character.
• A comment record is not processed.  No numerical or character data are extracted; the record is merely written to the output file.
• A comment record cannot be extended by a continuation record.
• A comment record can be inserted anywhere in the input.

B.2    ELEMENTS OF INPUT RECORD

One or more of the following seven basic components comprise an input record: KEYWORD, MODIFIER, NUMERIC, SEPARATOR, TERMINATOR, COMMENT and PROMPT fields. These are described below.

B.2.1    The Keyword

Function

• The keyword identifies the input group.

Structure

• The keyword may consist of any characters except separator (Section B.2.4) or terminator (Section B.2.5) characters.  However, the first character of a keyword must be alphabetic ('A' through 'Z' or 'a' through 'z').  To this extent, the concept of a keyword is similar to that of a variable name in FORTRAN.
• The keyword may be in upper or lower case.
• A keyword must begin in the first column of a record.
• The keyword is terminated with the first occurrence of a valid separator or terminator character.
• The keyword may consist of 1 to 256 characters.  However, if there are more than four characters, only the first four are machine-identifiable.

EXAMPLES:

ABCD, A123, A&B+, A&B. are all valid examples of a keyword. The keyword specifications of ABCD, abcd, ABCDEFGH, AbCd123, ABCDxxxxxxx (where x stands for any character) are all equivalent because only the first four characters are significant and the input is case-insensitive.

1ABC, 567, (abc, 'abc, .abc are all invalid keywords since the 1^st character in all of these is not alphabetic.

Note that a specification of ABC) or ABC', ABC$, although valid, is equivalent to that of ABC because the last character in all of these examples is either a separator (Section B.2.5) or a terminator (Section B.2.6).

B.2.2    The Modifier

Any character information on an input record following a keyword, except that embedded in a numeric or comment field (see Sections B.2.3 and B.2.6), is treated as modifier(s).

Function

• To specify character data that helps in interpretation of the rest of the input data.

Structure

• A modifier in any input group, if present, must follow the keyword.
• The modifier is identical to the keyword in its structure. It may consist of any characters, except separator and terminator characters, of which the first character must be alphabetic.
• A modifier must not start in the first column of a record. It can be from 1 to 79 characters in length; however, if it is longer than four characters, only the first four are significant.
• The modifier must be separated from the keyword, other modifiers and numeric data by a valid separator, terminator or comment field.

EXAMPLES:

The structure of a modifier is identical to that of a keyword except that it must not start in the first column of a record. Examples are given in Section B.2.1

B.2.3    The Numeric Field

Any numeric characters on a keyword or continuation record following a keyword, except those embedded in a keyword, modifier or comment field (see Sections B.2.1, B.2.2 and B.2.6), are treated as numeric data.

Function

• A numeric field contains numeric data for input variables.

Structure

• A numeric field is a continuous string of characters that must begin with the numeric character set. In this context, the numeric character set consists of the numerals (0-9), the decimal point (.), and the plus (+) and minus (-) operators.
• A numeric field must consist only of the numeric character set defined above, the asterisk (*), and the exponent in lower (e) or upper (E) case. It must not contain any other character.
• The plus (+) or minus (-) sign, if present, must immediately precede the numerical value without any intervening blank or other characters.
• The asterisk (*) or the exponent (E or e), if present, must be embedded; the numeric field must not begin or end with one of these characters.
• A numeric field must be separated from the keyword, modifiers and other numeric fields by a valid separator, terminator or comment field.
• Numeric field may be located anywhere on a keyword or continuation record.
• The numeric values may be specified in any of the following formats:
• Integer, (e.g., 999),
• Real (e.g., 999.0, 999.)
• Exponent (e.g., 9.99E2, 99.9E1)
• Successive, repetitive, identical numeric values may be specified by the asterisk (*) option. Thus, (30., 30., 30.) may be represented as (3*30. or 3*3.0E+1); embedded separators or non-numeric characters must not appear in such specification.

EXAMPLES:

The input character strings, 1, 0.1234, .567, +123., -1.0005, 1.2e00, 1.35E0, and 3*1.2 are all valid examples of a numerical field. Input specifications of 123, 123., 1.23e02, +0.123E+3, 1.23E2, 1*123, 1*1.23E02 are all equivalent.

The strings 1ABC, 11X11, 1+2, 11.., 1+1.E1 are all invalid numeric specifications. In the first three, non-numeric characters follow a leading numeric character, and in the last three, a valid numeric character occurs in an invalid, embedded location.

Note that a specification of 1.2)2. or 1.2=2, although valid, will be equivalent to a specification of two numeric fields, 1.2 and 2 because of the embedded separator (Section B.2.4) in both cases. A specification of 1.2$2 is equivalent to a specification of 1.2 because the 2 following the $ will be ignored (Section B.2.5).

B.2.4    The Separator Field

Function

• To separate the keyword, the modifiers and the numeric fields of an input record.

Structure

• Any continuous string of characters on an input record, which consists only of the characters from the separator character set, is treated as a separator field. The set of separator characters may vary from one installation to another. The preferred separator characters are the comma (,), the space ( ), the equal sign (=), the colon (:), the semi-colon (;), the pound sign (#), the apostrophe ('), the vertical line (|), the left parenthesis "(", and the right parenthesis ")" characters.

EXAMPLES:

The sequence of characters  ';:: )), ======, =', #, and ; are all valid separator fields. However, (a) or (1) are not valid separator fields. In the first case, the character "a" will be processed by FREEFORM™ as a modifier; in the second, the character "1" will be processed as a numeric field.

Function

• To provide a vehicle for the user to insert comments in input to enhance the clarity and readability of the input.

Structure

• A comment field may be in the form of an embedded comment or a comment record.

• An embedded comment field is one which occurs on a keyword or continuation record. It must begin with a terminator ($ or !) character; any combination of characters may follow the terminator. The comment field is terminated at the end of the 256-th character in that record (Section B.2.5).
• A comment field on a comment record may consist of any combina­tion of characters. In this case, the comment field begins with the back slash (/), asterisk (*), or a terminator ($ or !) charac­ter as the first character and terminates with the 256^th character.

EXAMPLES:

In the input record:

• ARRAY = 1., 2., 3., 4., 5.    $ EXAMPLE 1

the character string "$ EXAMPLE 1" is an example of the embedded comment on a keyword record. Input processing stops with the $ character; all characters on that record following, and including, the $ character are ignored.

As examples of comment records, the character strings:

• / ARRAY = 1., 2., 3., 4., 5.    $ EXAMPLE 1
• * ARRAY = 1., 2., 3., 4., 5.    - another EXAMPLE
• !****////// ARRAY = 1., 2., 3., 4., 5.    $ another exa­mple

will all be treated as comment records and no processing will be done because one of the comment record identifier characters appears as the first character of the input record.

B.2.7    The Prompt

Function

• To allow for interactive or runtime input of a partial or entire input record.

Structure

• The user may insert a '?' in place of either an entire input record or numerical or character string in the input itself. The command interpreter will pause and prompt the user for input at this stage.
• The input obtained by the prompt may be comprised of one or more of the elements of an input record described in Sections B.2.1 through B.2.6.
• Any input specified by the prompt is inserted in the input command string starting with the location of the question mark symbol.
• All input in the original command string following the prompt in that record will be disregarded.
• The input for the prompt may consist of 1 to 256 characters depending on where the question mark symbol is located. The prompt will pause and display a message telling the user the maximum number of characters allowed.
• It is possible to avoid the message, referred to above, from being displayed by placing two question mark symbols in succession (eg. '??'). The command interpreter will still pause and wait for input, however it will not display a message.

EXAMPLES:

In the input record:

• SOLVE ?    ! Prompt user for input

the character string '?' has the effect of pausing the command interpreter during run-time and displaying a message that asks the user for up to 74 characters of input, since the '?' appears in the 7th location of the input record. The comment '! Prompt user for input' will be overwritten by the input provided by the user at run-time or will be replaced by blank characters if the user input is less than 74 characters long.

Alternatively the user may choose to write:

• SOLVE ??    ! Prompt user for input without a message

This input record has the same effect as above except no message is displayed.

Related Links:

# FREEFORM Examples