Previous chapter
· 
Next chapter
· 
Table of Contents
In this chapter, the following items are used to indicate the required argument type. Other types may be used, and will be automatically converted to the required type, if possible. Integer suffixes will be used to distinguish multiple arguments of the same type.
arg A generic argument of any SNOBOL4 data type.
array An array.
i An integer number.
name The name of a variable, function or label,
such as .VAR or 'VAR'. When case-folding,
'VAR' and 'var' are equivalent as names.
s Any SNOBOL4 string.
table A table.
unit I/O unit; an integer between 1 and 16.
If an argument is omitted in a function call, SNOBOL4 supplies
the null string instead.
Call function name with the specified arguments. Since name may be a variable containing a function name, it allows an indirect call to a function, similar to the :($VAR) construct in the GOTO field.
Returns a string which is the Ith argument from the formal definition of program-defined function name. ARG fails if i is greater than the number of arguments in name's definition. ARG is useful when one function is used to trace another. The trace function can access the actual argument used with the function being traced with an indirect reference: $ARG(name, i).
S is a prototype which specifies the dimensions of the array created, and the optional arg is the value used to initialize all array elements. The form of the prototype string is:
"L1:H1,L2:H2,...,Ln:Hn"
where L and H are integers giving the lower and upper bounds of
each dimension. Blanks are not permitted. If the lower bound
and colon are omitted from any dimension, '1:' is assumed. ARRAY
returns a pointer to the new array, which should be assigned to a
variable. The variable can then be subscripted to access the
array elements.
A common error when defining a multidimensional array is to use integers instead of a string for the prototype:
ARRAY(3,4) instead of ARRAY("3,4")
The first example defines a 3-element, one-dimensional array,
with elements initialized to integer 4. The second defines a
rectangular array, 3 rows by 4 columns.
Converts an integer ASCII code to a one-character string. The argument must be in the range 0 to 255, otherwise the function fails.
The null string is assigned to all variables in the system (including primitive patterns, such as ARB. These patterns and names may be restored from the protected keywords with the same names (e.g., ARB = &ARB).
CLEAR does not modify variables which are currently saved on the function call stack.
Returns a pointer to the object code compiled from the SNOBOL4 statements in string s. This pointer can be assigned to a variable, and the code executed with the direct GOTO :<variable>.
CODE fails if it finds a syntax error, and places an error message string in keyword &ERRTEXT. Individual statements in s are separated by a semicolon (;). The first character following a semicolon must be a blank, tab, the start of a label, or a comment. Control and continuation statements are not allowed in s. Statements may be any length; the 120 character limit when compiling from a file does not apply. Case-folding of names is controlled by keyword &CASE.
This function calls SNOBOL4's garbage collection routine, which reclaims all unused storage. It returns an integer result that is the number of free descriptors remaining in the work space (a descriptor contains 5 bytes of storage). If there are less than i free descriptors after regeneration, the function fails. SNOBOL4 automatically calls COLLECT whenever memory becomes full.
The argument is converted to the specified data type and returned as the value of the function. If conversion is not possible, the function fails. S is a data type name string, such as 'STRING', 'TABLE', etc. Data type names may be lower case if case-folding is active. Chapter 7, "Data Types and Conversion," lists allowable conversions.
Returns a distinct copy of arg. The argument may be an array, code block, pattern, or program-defined data type. If A is an array, the statement
B = COPY(A)
creates a new array B, whose initial contents are the same as
array A. Their elements are independent; altering element A<I>
does not affect element B<I>. In contrast, the assignment B = A
makes A and B alternate names for the same array.
Defines a new data type according to the prototype in string s. The prototype assumes a form similar to a function call, with the data type taking the place of the function name, and the field names replacing the arguments. The form of the prototype string is
"NEWTYPE(FIELD1,FIELD2,...,FIELDn)"
The DATA function implicitly defines a new function and n new
field variables:
NEWTYPE(ARG1,ARG2,...,ARGn) Object creation function.
FIELD1(x) Reference to field variable 1.
. . .
FIELDn(x) Reference to field variable n.
where x is an object created with the NEWTYPE function.
The fields may be of any data type, including pointers to other program-defined data items.
Returns a string specifying the data type of the argument. Some typical arguments and their data types are:
12 INTEGER
'ABCD' STRING
POS(2) 'C' LEN(3) PATTERN
.Q<3> NAME
*PAT EXPRESSION
If the argument is a program-defined data type, the name from
the creating DATA() function is returned.
Returns a 20-character string of the form:
'MM-DD-YY HH:MM:SS.CC'
representing month, day, year, hour, minute, second, and centisecond
respectively. The centisecond field can only be approximated,
since many personal computer clocks are only updated
every 55 milliseconds.
This function creates a new, program-defined function. S is a prototype string specifying the function's name, arguments, and local variables, if any. Name is optional, and specifies a label as the first statement of the function body. If absent, a label with the same name as the function is the assumed entry point. The form of the prototype string is
"FNAME(ARG1,ARG2,...,ARGn)LOCAL1,LOCAL2,...,LOCALn"
where FNAME is the name of the function, and ARGi are names of
formal arguments to the function. Blanks are not permitted in
the prototype. The values of variables specified in the list of
locals are saved prior to function entry, and restored upon function
return.
Functions may return a value or variable name by assigning the result to a variable with the same name as the function. Functions return by transferring to one of the reserved labels RETURN, NRETURN, or FRETURN to return by value, by name, or to fail respectively.
Removes any input or output unit associated with the variable name. The underlying file is not affected in any way. Remember that name is the address of the variable (e.g. .X or 'X'), not the variable itself.
Succeeds and returns the null string if and only if arg1 and arg2 are different. Strings and integers are different if they have unequal values. Other data types contain pointers to the actual data object, and differ only if the pointers are different. If arg2 is omitted, DIFFER succeeds if arg1 is not null.
This function causes all natural variables with nonnull values to be listed on the file associated with I/O unit 6 (normally OUTPUT). If i is zero, the dump does not occur.
Returns the argument string s repeated i times. The function returns the null string if i is zero, and fails if i is negative.
The file attached to the specified I/O unit is closed, and the file buffer is flushed and released. All variables which have been associated with this unit have their association removed. Upon program termination, SNOBOL4 will automatically perform an ENDFILE function on all open units.
This function succeeds and returns the null string if the two integer arguments are equal. I1 and i2 must evaluate to integer values. The function fails if i1 is not equal to i2.
If the argument is a string, it should contain a valid SNOBOL4 expression to be compiled and evaluated. The evaluation result is returned as the value of the function. EVAL fails and sets &ERRTEXT to an error message string if s contains a syntactic error. If the argument is a number, i, it is returned unchanged. If the argument is an unevaluated expression, it is evaluated, and the result returned.
Returns a string which is the Ith field name from the formal definition of the program-defined data type whose name is in string s. FIELD fails if i is greater than the number of fields in the data type's definition.
This function succeeds and returns the null string if the two integer arguments satisfy the relationship i1 >= i2. I1 and i2 must evaluate to integer values. The function fails if i1 is less than i2.
This function succeeds and returns the null string if the two integer arguments satisfy the relationship i1 > i2. I1 and i2 must evaluate to integer values. The function fails if i1 is less than or equal to i2.
Succeeds and returns the null string if and only if arg1 and arg2 are identical. Strings and integers re identical if they have the same values. Other data types contain pointers to the actual data object, and are identical only if they point to the same object. If arg2 is omitted, IDENT succeeds if arg1 is the null string.
This function opens a file for input, and associates it with a variable. Data may then be read from the file by using the variable in an expression or an assignment statement.
The file designated by string S is opened for input and given the specified unit number. I is an optional record length. The variable specified by Name is associated with this unit.
The first argument, Name, specifies a SNOBOL4 variable, typically as a quoted string or with the unary period operator:
INPUT('IN', ...
INPUT(.IN, ...
X = 'IN'
INPUT(X, ...
The second argument, Unit, must evaluate to an integer value in
the range 0 to 16 inclusive. Unit 0 (or omitting the unit argument)
will select the default input unit, 5.
The third argument, I, contains the record length in characters. 0 < I <= &MAXLNGTH. If omitted, the default is 80.
The fourth argument, S, is a string containing the name of the file to be opened. If the file is a disk file, S may contain an optional drive letter and pathname in addition to the filename. Besides disk files, MS-DOS device names such as NUL:, CON:, COM2:, etc., are permitted.
If S is absent or null, and this unit is not currently open, the SNOBOL4 command line is searched for a file to use with this unit (/n:file). If S is absent, but the unit is already open, the INPUT call serves only to establish another association between a variable and the unit. If S is not null, any file previously associated with this unit number is first closed by SNOBOL4 with an implicit ENDFILE(unit).
An error message is generated for an illegal unit number. The INPUT function fails (with no printed error message) if the file cannot be opened.
The record length I (or its default value, 80), determines the number of characters returned in a string when the associated variable is referenced. ASCII files will return I characters or less if an end-of-line condition is encountered. End-of-line is defined as either a carriage return, or a carriage return followed by a line feed. If I characters are read from an ASCII file without encountering an end-of-line, additional characters are read from the file and discarded until the end-of-line character(s) are found. That is, long lines are truncated. If less than I characters are read from an ASCII file, and keyword &TRIM is zero, the line will be padded with blank characters until length i is obtained.
A read operation will terminate on the last character of a disk file, returning a short record. Reading past the End-of-File will cause statement failure. If the file is ASCII, reading a control-Z character will be treated as an End-of-File.
Note: When program begins execution, the variable INPUT is associated with unit 5. Unit 5 is normally device CON:, the keyboard, unless redirected elsewhere by the /I=file command line option, or the MS-DOS redirection operation (<file).
Succeeds and returns the null string if arg is an integer, or a string which can be converted to an integer. If the argument is not an integer, the function fails.
ITEM(table, arg) Get table element
Returns the specified array or table element. I1, i2, ..., in are array subscripts, and arg is a table subscript. Since the first argument may be a function which returns an array or table name, it allows an indirect reference in situations that would not be syntactically valid. ITEM is an analog of the APPLY function. For example, if F(X) is a program-defined function which returns an array name,
ITEM(F(X), 20)
references the 20th element of that array, whereas F(X)<20> is
not acceptable.
This function succeeds and returns the null string if the two integer arguments satisfy the relationship i1 <= i2. I1 and i2 must evaluate to integer values. The function fails if i1 is greater than i2.
This function succeeds and returns the null string if s1 is lexically greater than s2 (according to their alphabetic ordering). The two strings are compared left to right, character by character. If one string is exhausted before the other---with all characters equal---the longer string is lexically greater than the shorter string. The null string is lexically less than any other non-null string. If there is a character mismatch at the same position in both strings, the relationship between the characters determines the relationship of the strings. Strings are equal only if they are the same length, and are identical character by character.
Returns a string which is the Ith local variable from the formal definition of program-defined function name. LOCAL fails if i is greater than the number of local variables in name's definition. LOCAL is useful when one function is used to trace another. The trace function can access the local variables used with the funcion being traced with an indirect reference: $LOCAL(name, i).
This function is useful for right-justifying columnar output. It returns s1 padded on its left end until its total size is i characters. The pad character used is the first character of s2 if present, otherwise a blank is used if s2 is absent or null. If i is less than or equal to the length of s1, s1 is returned unchanged.
This function succeeds and returns the null string if the two integer arguments satisfy the relationship i1 < i2. I1 and i2 must evaluate to integer values. The function fails if i1 is greater than or equal to i2.
This function succeeds and returns the null string if the two integer arguments are not equal. I1 and i2 must evaluate to integer values. The function fails if i1 is equal to i2.
The function or operator name s1 becomes a synonym for s2. If i is absent or 0, both strings are assumed to be function names. If i is 1 or 2, then the strings are assumed to be unary or binary operators, respectively. Other values for i are illegal. Operators are specified by using their graphic symbol in a quoted literal, such as:
OPSYN('#', '/', 2)
The concatenation operator is specified as a one-character
string containing a blank: ' '. The implicit pattern match operator
between subject and pattern cannot be OPSYNed.
This function opens a file for output, and associates it with a variable. Data may then be written to the file by assigning values to the variable.
The description of the OUTPUT function parallels that of the INPUT function, and will not be duplicated here. The following differences are noted below.
If the output file already exists, it is deleted and recreated anew. Facilities for updating existing files (direct-access files) are not present in Vanilla SNOBOL4; they are contained in SNOBOL4+, Catspaw's enhanced implementation of the SNOBOL4 language.
When an output variable is assigned a string value, the string is written to the associated file. A carriage return and line feed appended to the string. If the string is longer than the record length (i, or the default, 80), a carriage return and line feed will be inserted every i characters. That is, long strings will create multiple output lines.
Note: When a program begins execution, the variable OUTPUT is associated with unit 6. Unit 6 is normally device CON:, the display, unless redirected elsewhere by the /O: command line option or the MS-DOS redirection operation (>file). The variable SCREEN is associated with unit 7, which is also attached to device CON:.
Returns the prototype string of dimensions used to create the specified array. If the array was created by the ARRAY function, then the string returned is identical to the first argument of the original ARRAY function call. If the array was produced from a table by the CONVERT function, the string has the form 'N,2', where N is the integer number of rows in the array.
REMDR returns the integer remainder resulting from i1 divided by i2, that is, i1 modulus i2. The result has the same sign as i1.
This function returns s1 transformed according to a translation specified by s2 and s3. Each character of s1 found in s2 is replaced by the corresponding character in s3. S2 and s3 must be the same length. If duplicate characters appear in s2, the rightmost one is used to obtain the mapping character from s3. Normally, s2 and s3 are thought of as parameters, and REPLACE performs character substitutions on the variable s1. For instance:
REPLACE(S, 'aeiouAEIOU', '1234512345')
replaces all upper- and lower-case vowels in S with the digits 1
through 5. It is possible to use REPLACE as a "transposition"
function if s1 and s2 are considered parameters, and s3 allowed
to vary. If s1 and s2 are the same length, a simple positional
transformation results. For example,
REPLACE('123456', '214365', S)
returns the six character string S with adjacent pairs of characters
interchanged ('ABCDEF' becomes 'BADCFE'). S1 and s2 can be
different lengths---only s2 and s3 must be the same size. If s2
contains characters not in s1, the corresponding characters in s3
are dropped from the result. If s1 contains characters not in
s2, they will appear in the result. The function call
REPLACE('Yy/Mm/Dd', 'Mm-Dd-Yy xx:xx:xx.xx', DATE())
returns the date in the form YY/MM/DD (e.g., 87/07/28). Duplicate
characters in s1 are permitted, so:
REPLACE('aaabbbccc', 'abc' '(1)')
produces '(((111)))'.
This function is useful for left-justifying columnar output. It returns s1 padded on its right end until its total size is i characters. The pad character used is the first character of s2 if present, otherwise a blank (ASCII character 32) is used if s2 is absent or null. If i is less than or equal to the length of s1, s1 is returned unchanged.
The function SIZE returns an integer value which is the number of characters in its argument string. A null string argument returns 0.
Discontinues the type of trace of the named item. Consult the TRACE() function for a list of tracing types available.
A table is similar to a one-dimensional array, but the subscripts may be any SNOBOL4 data type. The TABLE function creates a table and returns a pointer to it. The integer i1 specifies the initial number of entries in the table. Integer i2 specifies the size by which the table is increased whenever it becomes full, and additional table space is required. If either is omitted, 10 is used as a default value.
Returns the number of tenths of a second elapsed since the start of program execution, including all I/O wait time.
The item name1 is traced according to the action specified by type. Trace output is written to the file associated with I/O unit 6.
Name1 is a the name of a variable, function, statement label, or keyword. It may appear as a string, or specified with the unary name operator (.).
Type is a string that determines the type of trace desired. It must be one of these values:
'VALUE' When value of name1 is changed (default if
type omitted).
'CALL' When function name1 is called.
'RETURN' When function name1 returns.
'FUNCTION' When function name1 is called, or returns.
'LABEL' When control is transferred to label name1.
'KEYWORD' When the value of keyword &name1 is changed.
Note that the ampersand character (&) is not
included in the first argument, name1.
S is an optional identifying tag that is added to the trace
output line when name1 is a created object, such as an array or
table element.
Name2 is an optional name of a program-defined function.
Instead of producing a trace output line, this function is called when the trace action occurs. The function is called with name1 as the first argument, and string s as the second argument.
Tracing will only occur when the keyword &TRACE is nonzero. Each trace will decrement &TRACE by one. Tracing ends when it becomes zero.
Returns the argument string with trailing blanks removed. Trailing tab characters are not affected. If the argument string was read from an input file, it is more efficient to set keyword &TRIM nonzero than to use TRIM(INPUT).
By combining function TRIM with REPLACE, any trailing character can be removed. The desired character is temporarily exchanged with blank, trimmed, then exchanged back. For example, this expression returns string S with trailing zeros removed:
REPLACE(TRIM(REPLACE(S,'0 ',' 0')),'0 ',' 0')
The function name becomes undefined.
The VALUE function returns the value of the variable name, behaving like the unary indirect operator ($).
Previous chapter
· Next chapter
· Table of Contents