These are primitive SNOBOL4 functions which are not predicates or
pattern functions.
Any of these functions can be redefined by the user using DEFINE().
When calling any SNOBOL4 function, if an argument is omitted,
the corresponding parameter value is set to null (null string).
Note that a null string converts into a zero when it is the
operand of an arithmetic operation.
APPLY(f,a1,a2...)
calls function f with arguments a1, a2 ... and returns the
value of the called function.
The name of the function f must be a character string.
APPLY is useful for situations requiring a variable function name.
ARG(f,i)
returns a string which is the name of the ith parameter of
the programmer defined function f.
The name of the function f must be a character string.
This function is useful for obtaining the parameters in generalized
trace procedures.
ARRAY(p,x)
returns an array described by the string p, whose elements are
are all initialized to the value x.
The syntax for p is as follows:
The lower bound is assumed to be one if not specified.
The upper bound must not be less than the lower bound.
ARRAY('3,-1:1') returns a 3 by 3 element, two dimension array.
BACKSPACE(unit)
This
function
backspaces a file open for read
to the start of the record prior to the current
position in the file. That is after the carriage
return character before the start of the record,
usually at the line feed character for ASCII files.
If there is no carriage return character, then it
positions it to the start of the file. This works
the same for /A and /B file modifiers. If a fixed
length backspace is desired, use the relative SEEK
function. An error is issued if the unit is not a
file or is not open for read. Note, backspacing
once after a read means that you will read the
record again if you do another read. If you need to
read the records in a file in reverse order, you
need to issue two backspaces between each read.
CENTER(S,L,C)
This function centers string S so that the
result string has length max(L,SIZE(S)) by equal
padding (equal within one character) on the left and
right using the first character of string C as the
pad character, or using a blank if C is null.
Padding occurs if SIZE(S)<.L. Note S is not trimmed
before padding so any leading or trailing blanks in
S may make it look like it was not centered. One
use for CENTER is centering titles on a printed
page. See the example under RPAD.
CLEAR()
resets all natural variables to null at this function level.
If a variable has been pushed as a result of some function invocation,
it will reappear with its old value when that function returns.
Note that all of the pattern primitives, which are variables, such
as ARB, BAL etc. are also reset to null strings.
To get their values back, you can use the corresponding keywords
&ARB, &BAL etc.
CODE(s)
"compiles" the SNOBOL4 statements given by the string s and returns
the compiled code (see CODE data type).
The newly compiled code can be executed by using the <code> form
of the goto. This starts execution at the first compiled statement.
Also, if labels are included in the statements in string s, then
they replace any existing labels currently in effect and may
be branched to using the parenthesis form of the goto.
The CODE function fails if there is a syntax error in the string s.
Note, that the first character of a statement must be blank or it will
be treated as a label. Also, more than one statement can be
compiled by separating them with the semicolon.
COLLECT(i)
forces garbage collection in the SNOBOL4 work space.
The function returns the number of unused bytes in the work space.
If there are fewer than i bytes in the work space after collection,
then the function fails.
CONVERT(x,t)
converts the object x to the data type specified by string t.
If the conversion is not possible, then the function fails.
Anything can be converted to type "STRING".
A useful conversion is that converting a table into an "ARRAY",
which gives an n by 2 array form of the table. This allows one
to serially access all of the elements of a table.
Likewise, an n by 2 array can be converted into a "TABLE".
The <n,1> slice is the set of indexes for the table elements
containing the corresponding values in slice <n,2>.
COPY(a)
returns a new array which is a copy of array a.
DATA(p)
defines a "programmer defined" data type and returns the null
string.
The prototype of the data type is defined by string p which has
the following syntax:
To create an instance of the new data type, use what looks like
a function reference, giving the data type name instead of
the function name. Each argument gets assigned to the corresponding
fields of the data type instance.
The fields may be accessed with what also looks like a function
reference with one argument, which is the instance of the data type.
For example, if you wanted to introduce complex numbers in your
program:
DATATYPE(x)
returns the name of the datatype of object x as a string.
This also works for programmer defined data types defined with the
DATA() function.
DATATYPE('ABC') returns 'STRING' for example.
DATE()
returns the current date and time as a character string in the
form 'YYYY-MM-DD HH:MM:SS.SS'.
Both time and date are returned at once to handle midnight properly.
Note that prior (non-Y2K) versions of SNOBOL4 returned 'MM-DD-YY HH:MM:SS.SS'.
DEFINE(p,e)
defines a programmer defined function.
The prototype p of the function is specified by string p which has
the following syntax:
where the parameters and local variables are specified.
The local variable values are saved and set to null upon entry into
the function, and their old values are restored when the function
returns. This also applies to the parameters, except instead of
being set to null, they are set to the values of the corresponding
arguments.
The function is assumed to start at the statement with label fncname,
when e is null. If a different label is to be used, the string e
can be used to indicate this when calling DEFINE.
Use the special return label RETURN to return from the function
successfully and FRETURN to return with failure.
NRETURN can be used to return the name of a variable instead of
its value.
The value to be returned by the defined function can be set by
assigning a value to the variable fncname.
DEFINE() returns the null string.
The following is an example of the definition and use of a function
to compute numbers in Pascal's triangle (binomial coefficients):
The following is an example of the definition and use of a function
to compute factorials of numbers:
DETACH(s)
removes the I/O association to the variable with the name specified
by string s. See INPUT() and OUTPUT() functions.
DUMP(n)
prints a dump of all natural variables which have a non-null
value, if the argument n is a non-zero integer. If n is zero,
the dump is not performed.
DUPL(s,n)
returns a string consisting of string s repeated n times.
ENDFILE(n)
closes the file attached to I/O unit number n.
EVAL(s)
causes the SNOBOL4 expression given in string s to be compiled
and evaluated. "s" may also be an integer,
or an unevaluated expression.
If the argument is not syntactically correct, then EVAL fails.
For example,
EVAL('N + 4') returns the current value of N increased by four.
FIELD(dt,n)
returns a string giving the name of the nth field of a
programmer defined data type dt.
The function fails if there is no nth field in that data type.
The following example illustrates its use:
The above prints the string 'NEXT'.
INPUT(vname,unitn,buflen,fname)
is used to
associate a SNOBOL4 input variable name with an
external input/output unit and optionally specify
the file name (or path name) along with the file
modifiers. This function is usually used in one of
two ways. First, using just the first three
operands, and second with all four operands. The
fourth operand is an extension over the definition
contained in the green book. It permits the
specification of the file name along with optional
file modifiers.
In the spirit of mainframe SNOBOL4, 32 numbered I/O
ports are provided through which all I/O operations
are performed. On one side, the port is connected
to a DOS file or device and inside the program it is
connected to one or more I/O variables. For
example:
If the fourth operand is omitted, the record length
can be changed or additional I/O variable names can
be associated with the unit number. Also, if the
fourth operand is omitted, the file name can be
specified on the DOS command line used to invoke
SNOBOL4.2:
A file is not opened until its first use.
Input from the console (CON:) is limited to lines of length 128 characters or
less.
The output function is the counterpart for writing
to files.
ITEM(x,i1,i2,...)
is used to reference an element of an array or table without
using the bracket form of reference (XXX<N>).
ITEM returns the <i1,i2,...> element of the array or table x.
The following illustrates the use of ITEM.
LOAD(x,y)
The LOAD function is not available in this implementation of SNOBOL4.
LOCAL(f,n)
returns the name of the nth local variable for the function
with the name given by the string f.
For example:
prints the string 'Y'.
LPAD(S,L,C)
pads string S on left so that the
result string has length MAX(L,SIZE(S)) by padding
on the left with the first character of string C, or
with a blank if C is null. Padding occurs if
SIZE(S)<.L. Note S is not trimmed before padding so
any leading or trailing blanks in S may make it look
like it was not properly padded. A use for LPAD is
to right align numbers within a field so that when
several lines are printed, the numbers appear to
line up properly. See the example with RPAD.
OPSYN(newfn,oldfn,n)
makes the operator or function defined by newfn a synonym for
the operator or function defined by oldfn.
If newfn and oldfn are not operators, the third parameter must
be omitted.
If newfn or
oldfn is an operator, n specifies whether it is unary or binary
by giving an integer 1 or 2.
The concatenation operator is specified using a string of one blank.
If the newfn name is not a SNOBOL4 operator and not a syntactically
correct SNOBOL4 function name, it can still be accessed using the
APPLY function.
The following:
makes the function ADD perform the same function as the binary '+'
operator.
If you look back at the DATA() function where the COMPLEX
data type was illustrated, the snobol '+' operator can be
redefined to also handle complex addition using the following:
OUTPUT(vname,unitn,format,fname)
is used to
associate a SNOBOL4 output variable name with an
external unit number and optionally specify the file
name (or path name) along with the file modifiers.
This function is usually used in one of two ways.
First, using just the first three operands, and
second with all four operands. The fourth operand
is an extension over the definition contained in the
green book. It permits the specification of the
file name along with optional file modifiers.
In the spirit of mainframe SNOBOL4, 32 numbered I/O
ports are provided through which all I/O operations
are performed. On one side, the port is connected
to a DOS file or device and inside the program it is
connected to one or more I/O variables. For
example:
If the fourth operand is omitted, the format can be
changed or additional output variable names can be
associated with the unit number. Also, if the
fourth operand is omitted, the file name can be
specified on the DOS command line used to invoke
SNOBOL4.2:
PEEK(A,L,O)
returns a string of L number of
bytes of the memory contents at address A with O
bytes skipped between each source byte. O must be
0-4096 and the entire source string must be within
64K of storage. The third operand makes it
convenient to retrieve the character bytes from the
screen buffer while skipping the attribute bytes.
For example, the characters on a monochrome screen
can be retrieved by using PEEK(720896,2000,1). Note
that 720896 is the decimal equivalent of the
hexadecimal number B0000. Only the 20 low order
bits of address A should be used (keep A less than
1048576).
POKE(A,S,O)
stores bytes of string S in memory
locations starting at address A skipping O bytes in
storage between bytes stored. This function returns
the null string. O must be in the range 0-4096 and
the entire target must be within a 64K of storage.
Only the 20 low order bits of address A should be
used (keep A less than 1048576). For example, the
characters on a monochrome display can be set
without disturbing the attribute bytes by using
POKE(720896,S,1). Note that 720896 is the decimal
equivalent of the hexadecimal number B0000. POKE
can easily crash the system if data is stored in the
wrong place, so use it with caution, or better yet,
don't use it at all.
PROTOTYPE(a)
returns the prototype used to create array a. See the
the p parameter on the ARRAY function.
The following:
sets Y to the value '3,-1:1'.
REMDR(x,y)
returns the integer remainder from the division of the integer x
by the integer y.
The sign of the remainder is the same as that of x.
REMDR(14,12) gives 2.
REPLACE(x,y,z)
returns the string x with any character in x which appears in
the string y, replaced by the corresponding character in string z.
The strings y and z must be of equal, non-zero length or the
function will fail.
The following will change all lower case letters in string Q to
upper case:
REVERSE(S)
returns the string S with the order
of the characters reversed.
REWIND(n)
closes the file associated with I/O unit number n and
resets it so that the next operation will start at the
beginning of the file.
This is useful for situations where you want to read a
file twice or more.
The file is reopened on the first input or output operation
after the rewind.
RPAD(S,L,C)
pads string S on right so that the
result string has length MAX(L,SIZE(S)) by padding
on the right with the first character of string C,
or with a blank if C is null. Padding occurs if
SIZE(S)<.L. Note S is not trimmed before padding so
any leading or trailing blanks in S may make it look
like it was not properly padded. RPAD is useful for
left aligning fields in a listing. The following
example shows the usage of CENTER, LPAD and RPAD in
listing a file with line numbers on a printer:
SAVE(FILENAME)
saves (checkpoints) the current
SNOBOL4 workspace into a file with the name
FILENAME. A null string is returned by SAVE when
the save operation is performed. On resumption, a 1
is returned and all files are closed and assigned to
standard input or output. SNOBOL4R.EXE is used to
resume execution of a checkpointed workspace.
Simply give the workspace name first, and then the
usual SNOBOL4 command file assignments:
A garbage collection is performed as the result of
SAVE to minimize the size of the file written. If
the save operation encounters some write errors
(such as a full disk) the SAVE function will fail.
One use of checkpointing a workspace is to save a
data structure or data base built using SNOBOL4.2
constructs. On resumption the program can continue
operating on the data base without spending the time
to read and convert it from some file format. There
is some danger in this if one wishes to upgrade to a
new version of SNOBOL4.2. In general, workspaces
checkpointed on one version level of SNOBOL4.2 will
not work with a different version level of
SNOBOL4.2. Therefore, if you anticipate the need to
upgrade, you will need some provisions in your
program to write the data base to a file such that
it can be read back into your program when upgrading
SNOBOL4.2 versions.
SEEK(U,POS,TYPE)
is used to change the position
in a file at which the next read or write occurs. U
is an integer I/O unit number. POS is an integer
absolute or relative position. If TYPE is 0, the
positioning is absolute (relative to the beginning
of the file). If TYPE is 1, positioning is relative
to the current position in the file. If TYPE is 2,
positioning is relative the the end of the file.
The function returns the resulting position in the
file with respect to the beginning. Note that if
SEEK is used on a file you are writing, when the
files is closed, the record most recently written
becomes the last record in the file (because the 1Ah
end-of-file-character is written after that record)
unless you use the /B modifier indicating it is a
binary file. For ASCII files (/A modifier), you can
SEEK(unit,0,2) to the end of the file to avoid this
problem (and then close the file). When SEEKing
relative to the current position with ASCII mode
read/writes (/A modifier) it is useful to know the
following. When a record has been read, the file is
positioned to the character after the carriage
return character, usually a line feed character.
When a record has been written, the file is
positioned to the character after the line feed
character (after the carriage return character if
/NLF modifier specified) at the end of the record.
SEEK is not allowed on an unassigned unit. Results
are unpredictable if the I/O unit is not open when
SEEK is first used. You should read any record
first.
SIZE(s)
returns the length of the character string s.
The following can be used to create a fixed length string of 12
characters with the number N right aligned in the string:
SORT(ARRAY,STYPE)
returns the array ARRAY
sorted on the STYPEth column in ascending order, or
descending order for negative values of STYPE.
ARRAY must be a one or two dimensional array. The
absolute value of the second argument is the column
number (the row is the first and the column is the
second subscript of an array reference). Zero or
null is considered the same as positive one. Note
that the column number is not the index value of the
column (if the array is defined as
ARRAY('100,-1:1'), it has 100 rows and 3 columns,
and the first column number is 1, not -1). The
function sorts the array in place, so the first
argument is returned by the function. Sorting in
place permits sorting arrays which are larger than
one half of the workspace. Otherwise there would
not be room for the sorted copy. Tables must be
converted to arrays using CONVERT(table,'ARRAY')
before sorting. SORT fails if the array is not a
one or two dimensional array, or if the second
argument STYPE gives a number larger than the number
of columns. With an ascending sort, types are are
sorted in the following order: STRING, PATTERN,
ARRAY, TABLE, numeric(INTEGER, REAL), CODE, NAME,
EXPRESSION, and programmer defined data types.
Within the types, only strings and numeric items are
sorted. All strings sort before numbers. The
numerics (INTEGER and REAL) are sorted by their
value on the number line. Floating point NAN's will
collate unpredictably when compared with numerics.
The sort is stable so that consecutive sorts on
different columns preserve prior order when sort
keys are equal.
STOPTR(n,t)
stops tracing n of type t.
See the TRACE function for more information on tracing.
SUBSTR(S,O,L)
this function
returns the substring of S starting at offset O for
length L. O must be zero or greater. If O and L
are such that it would run beyond the end of S, then
the L is reduced. A null string is returned if O is
SIZE(S) or greater. Note that the offset O starts
with zero rather than one. This makes it more
consistent with the positioning parameters used in
pattern functions such as POS, TAB, etc.
SYSTEM(S,G)
lets you issue DOS commands from
within a SNOBOL program and lets you enter DOS
command mode and specify the required amount of
storage for DOS. If S is not null, then S is
executed as a DOS command. If S is null then DOS
command mode is entered. You must issue an EXIT
command to get back to SNOBOL4.2. G is the minimum
number of bytes you want DOS to have available.
This may require SNOBOL4.2 garbage collection, which
can take up to several seconds. If G is less than
32768, an attempt is made to give at least 32K to
DOS. If less than G bytes are available, an error
message is given indicating insufficient storage is
available. The command string S should not be
longer than 124 characters.
TABLE(init,inc)
creates and returns a table.
A table is an associative array with one dimension, where the index
into that dimension can be a value of any SNOBOL4 data type.
The initial amount of space allocated for the table is init elements.
When more space is needed, the table size is increased by inc elements.
If either init or inc is zero, then 10 is used.
Note that the character string "1" is different from the integer 1
when used as an index into the table.
The following program prints the number of occurrences of each
character appearing in string Q.
TIME()
returns the number of milliseconds of real time elapsed since the
beginning of the execution of the SNOBOL4 program.
It does not include the compilation time.
TRACE(n,t,g,f)
establishes that n with type of action t is to be traced,
(printed on I/O unit 6).
The third parameter g is used only if n is not a natural variable,
and is printed along with the trace information for identification
purposes.
The second parameter t can be one of the following string values:
'VALUE' indicates that a trace item should be printed whenever
the value of n is set.
'CALL' indicates that each call of function n is to be traced.
'RETURN' indicates that each return from function n is to be
traced.
'FUNCTION' indicates that both calls and returns for function n
are to be traced.
'LABEL' indicates that goto's to the label n are to be traced.
Note that simple sequential flow into a statement with that label
is not traced.
'KEYWORD' indicates that a trace item should be printed
whenever the value of the SNOBOL4 keyword with name n is set.
The STOPTR function is used to stop any particular trace.
The keyword &TRACE must be set to a positive number in order
to activate tracing.
Each trace item decrements &TRACE by one until it is becomes zero.
This keyword can be used to enable and disable tracing in the
program.
If the fourth parameter f is not omitted, it specifies a
function to be called with the first argument being n and
the second, the tag g.
This action occurs in place of printing a trace record.
Also, the values of &TRACE and &FTRACE are automatically saved
on entry to the function f and set to zero. They are restored
when the function returns.
This allows the programmer to design his own trace actions.
The keyword &FTRACE can be used to trace all calls and returns
for user-defined functions. &FTRACE must be set to the number
of trace entries desired. Each trace entry decrements &FTRACE
by one. &FTRACE acts independently of &TRACE.
TRIM(S,C,L)
this function has been enhanced to handle
trimming of specific character sets and to limit
trimming to a particular length. String S is
trimmed on the right. That is, any characters in C
which appear on the right end of S are removed.
However, no characters are trimmed in the first L
characters of the string. If C is null, blank and
tab characters are trimmed.
UNLOAD(FUNCNAME)
this function is used to remove
a subroutine loaded by the LOAD function. FUNCNAME
is the name by which the subroutine is known within
SNOBOL4.2, as given in the prototype parameter of
the LOAD function. See the LOAD function for more
details.
VALUE(x)
returns the value of the variable specified by string or name x.
It is used to provide uniform treatment of accessing variables and
fields, of name VALUE, in programmer defined data types.
Prior Page, Next Page, First Page of the Minnesota SNOBOL4 Reference