SNOBOL4FUNC(1) CSNOBOL4 Manual SNOBOL4FUNC(1)NAMEsnobol4func - SNOBOL4 summary of built-in functions
DESCRIPTIONANY(charset)
Pattern: returns a pattern that matches one character in the STRING
charset. Standard.
APPLY(func,arg1,...)
Function: calls function func with the supplied arguments.
Standard.
ARBNO(pattern)
Pattern: returns a pattern that matches zero or more repeats of
pattern. I:<Standard>.
ARG(func,n)
Function: returns the name of the nth argument to function func.
Standard.
ARRAY(proto,value)
Data: Creates an ARRAY object. Standard.
ATAN(arg)
Math: Returns the principal value of the arc tangent of its
argument. Extension from SNOBOL4+?, added in CSNOBOL4 1.4.
BACKSPACE(unit)
I/O: Not implemented!! See SET() and SSET(). Standard.
BREAK(charset)
Pattern: Returns a pattern that matches the longest run of one or
more characters NOT in string charset. Standard.
BREAKX(charset)
Pattern: A pattern function used for fast scanning. BREAKX(str) is
equivalent to BREAK(str) ARBNO(LEN(1)BREAK(str)).
In other words BREAKX matches a sequence of ever larger strings
terminated by a break set. BREAKX can be used as a faster matching
replacement for ARB: BREAKX('S') 'STRING' always runs faster than
ARB 'STRING' since it only attempts matching 'STRING' at locations
where an 'S' has been detected. SPITBOL 360 Extension, added in
CSNOBOL4 version 0.98.
CHAR(n)
String: takes an integer from 0 to 255 and returns the nth
character in &ALPHABET. SPITBOL 360 Extension, added in CSNOBOL4
version 0.98. SNOBOL4+ has a CHR() function.
CHOP(real)
Math: truncates the fractional part of its argument (rounding
towards zero), and returns a REAL value. SPITBOL Extension, added
in CSNOBOL4 version 0.98.4.
CLEAR()
Interpreter: Clears ALL natural variable values (including
predefined pattern variables ABORT, ARB, BAL, FENCE, REM, and
SUCCEED). Standard.
CODE(str)
Interpreter: Compiles the argument as source code and returns a
CODE value, suitable for use with :<code>. If execution falls off
the end of the code, the program will exit. Standard.
COLLECT(n)
Interpreter: Triggers garbage collection. Returns failure if less
than n bytes are available after collection. Standard.
CONVERT(value,type)
Data: Convert value to data type type. Can convert TABLE to ARRAY
for iteration over members. Standard.
COPY(value)
Data: returns a copy of the supplied value. Copies of ARRAY, DATA
and TABLE objects are “shallow”: the returned object will point to
the same objects as the source container. Standard.
COS(argument)
Math: Return cosine of argument in radians. SNOBOL4+ Extension?,
added in CSNOBOL4 version 0.98.4.
DATA(prototype)
Data: Declares a DATA struct type. prototype is of the form
name(field,...). name is declared as a “constructor” function, and
each field is declared as an “accessor” function for the type. Any
number of types can use the same field names (regardless of
position). Standard.
DATATYPE(value)
Data: Returns a string with the data type of value, one of: ARRAY,
BLOCK, CODE, EXPRESSION, EXTERNAL, INTEGER, NAME, PATTERN, REAL,
STRING, TABLE, or a DATA() type name. Standard.
DATE()
String: returns MM/DD/YYYY HH:MM:SS. Standard. For compatibility
with Catspaw Macro SPITBOL, since CSNOBOL4 version 0.99.4 DATE(0)
returns strings of the form MM/DD/YY HH:MM:SS, and DATE(2) returns
strings of the form YYYY-MM-YY HH:MM:SS.
DEFINE(prototype[,label])
Functions: declares a function using prototype of the form
“name([argname,...])[localname,...]”. Optional label supplies the
function entry point. Standard.
DELETE(filename)
I/O: A predicate which tries to remove the named file, and fails if
it cannot. SITBOL Extension: added in CSNOBOL4 version 0.98.5.
DETACH(name)
I/O: Detach any I/O associations for named variable. Standard.
DIFFER(val1,val2)
Predicate: Succeeds if the supplied values refer to different
objects, strings, or numeric values. Standard.
DUMP(n)
Data: dumps natural variable values to stdout if argument n is non-
zero. Standard.
DUPL(string,n)
String: Returns a string with n copies of argument string.
Standard.
ENDFILE(unit)
I/O: Closes the file attached to I/O unit unit. Standard.
EQ(i1,i2)
Predicate: Succeeds if i1 is arithmetically equal to i2. Standard.
EVAL(v)
Interpreter: Evaluates v (an unevaluated expression, INTEGER, REAL,
or STRING), and returns the result; returns failure on syntax error
or the expression fails. Standard.
EXIT(arg)
System: Passes process control to a shell to execute arg as a
command. Returns failure if arg is not a STRING. SPITBOL
Extension, added in CSNOBOL. Does NOT implement “save file”
feature of SPITBOL.
EXP(x)
Math: returns the value e ** x. SPITBOL Extension, added in
CSNOBOL4 version 0.98.4.
FIELD(name,n)
Data: Returns a string with the name of the nth member of DATA()
type name. Standard.
FILE(string)
I/O: A predicate which tests if a file exists, and fails if it does
not. SITBOL Extension, added in CSNOBOL4 version 0.98.5.
FILE_ABSPATH(string)
I/O: A predicate which returns null if its argument is an absolute
file path, and failure if the path is relative. CSNOBOL4
Extension, added in CSNOBOL4 version 1.5.
FILE_ISDIR(string)
I/O: A predicate which returns the null string if its argument is
the pathname of a directory, and returns failure if not. CSNOBOL4
Extension, added in CSNOBOL4 version 1.5.
FREEZE(table)
Data: prohibits creation of new entries in the referenced table.
This is useful once a table has been initialized to avoid creating
empty entries on lookups that fail. This can greatly improve
program speed, since frozen tables will not become clogged with
empty entries. Lookups for uninitialized entries will return the
null string. Attempts to assign to a non-existent entry will cause
a “Variable not present where required” error. SNOBOL4+ Extension,
added in CSNOBOL4 version 0.98.2.
FUNCTION(name)
Function: A predicate which evaluates its argument as a string
(with case folding), and returns the null string if a function with
that name exists and fails if it does not. SITBOL Extension, added
in CSNOBOL4 version 0.99.44.
GE(i1,i2)
Predicate: Succeeds if i1 is arithmetically equal than or equal to
i2. Standard.
GT(i1,i2)
Predicate: Succeeds if i1 is arithmetically equal than i2.
Standard.
HOST(i,...)
System: This ought to be on it's own man page!! The host.sno
-INCLUDE contains symbolic defines for these (and many other)
functions:
With no parameters returns a string describing the system the
program is running on. The string contains three parts, separated
by colons. The first part describes the physical architecture, the
second describes the operating system, and the third describes the
language implementation name. NOTE! Architecture names come from
the uname(3) library call, and may be different for the same
hardware when running different operating systems. Example:
amd64:FreeBSD 10.0:CSNOBOL4B 2.0
HOST(0) returns a string containing the command line parameter
supplied to the -u option, if any. If no -u option was given,
HOST(0) returns the concatenation of all user parameters following
the input filename(s).
HOST(1,string) passes the string to the system(3) C library
function, and returns the subprocess exit status.
HOST(2,n) for integer n returns the n'th command line argument
(regardless of whether the argument was the command name, an
option, a filename or a user parameter) as a string, or failure if
n is out of range.
HOST(3) returns an integer for use with HOST(2) indicating the
first command line argument available as a user parameter.
HOST(4,string) returns the value of the environment variable named
string.
SPITBOL Extension, added in CSNOBOL4 version 0.98.4.
IDENT(v1,v2)
Predicate: Succeeds if the supplied values refer to the same
object, string, or numeric value. Standard.
INPUT(variable,unit,opt,name)
I/O: Associate variable for input, see snobol4io(1). Standard.*
INTEGER(value)
Predicate: Succeed if value is an INTEGER. Standard.
IO_FINDUNIT()
I/O: Returns an unused I/O unit number for use with the INPUT() or
OUTPUT() functions. IO_FINDUNIT() is meant for use in subroutines
which can be reused. IO_FINDUNIT() will never return a unit number
below 20. CSNOBOL4 Extension, added in version 0.99.4.
ITEM(a,i1,...)
Data: Reference an element of an ARRAY or TABLE which is the
result of an expression (ie; $variable). Standard.
LABEL(name)
Predicate: Evaluates argument as a string (with case folding), and
returns the null string if a label with that name has been defined,
and fails if it does not. Steve Duff's Macro SPITBOL Extension,
added in CSNOBOL4 version 1.5*. SITBOL has a LABEL function which
returns a CODE pointer. Added in CSNOBOL4 version 0.99.44, but
unreliable until version 1.5.
LE(i1,i2)
Predicate: tests if first argument is arithmetically less than or
equal to second argument. Standard.
LEN(n)
Pattern: Returns a PATTERN which matches exactly n characters.
Standard.
LEQ(s1,s2)
Predicate: tests if first argument is lexically equal to second
argument. SPITBOL Extension, added in CSNOBOL4 version 0.98.2.
LGE(S1,S2)
Predicate: tests if first argument is lexically greater than or
equal to second argument. SPITBOL Extension, added in CSNOBOL4
version 0.98.2.
LGT(s1,s2)
Predicate: tests if first argument is lexically greater than second
argument. SPITBOL Extension, added in CSNOBOL4 version 0.98.2.
LLE(s1,s2)
Predicate: tests if first argument is lexically less than or equal
to second argument. SPITBOL Extension, added in CSNOBOL4 version
0.98.2.
LLT(s1,s2)
Predicate: tests if first argument is lexically less than second
argument. SPITBOL Extension, added in CSNOBOL4 version 0.98.2.
LNE(s1,s2)
Predicate: tests if first argument is lexically different from
second argument. SPITBOL Extension, added in CSNOBOL4 version
0.98.2.
LN(value)
Math: an alias for LOG(), SPITBOL Extension, added in CSNOBOL4
version 1.4.
LOAD(prototype,file)
Function: Load an external function from dynamically loaded
library file. Standard.
LOCAL(name,n)
Interpreter: Returns a STRING with the nth argument to function
named name. Standard.
LOG(value)
Math: returns the natural logarithm of its argument. Extension
from SNOBOL4+, added in CSNOBOL4 version 0.98.4.
LPAD(str,n,char)
String: Takes the first argument (subject) string, and left pads it
out to the length specified in the second argument, using the first
character of the optional third argument. If the third argument is
missing, or is the null string, spaces will be used for padding.
The subject will be returned unmodified if already long enough.
SPITBOL 360 Extension, added in CSNOBOL4 version 0.98.
LT(i1,i2)
Predicate: Succeeds if i1 is arithmetically less than i2.
Standard.
NE(i1,i2)
Predicate: Succeeds if i1 is arithmetically not equal to i2.
Standard.
NOTANY(charset)
Pattern: Returns a pattern which matches on character NOT present
in STRING charset. Standard.
OPSYN(new,old,n)
Interpreter: If n omitted (or zero), new and old are treated as
function names, and new becomes a synonym for old: A call to a
synonym MUST have the correct number of arguments; trailing
arguments can NOT be omitted. If n is 1, new and old are treated
as unary operators, or function names. If n is 2, new and old are
treated as binary operators, or function names. Standard.
ORD(string)
String: returns the INTEGER ordinal value (zero to 255) of the
first character in its string argument (the inverse of CHAR()).
CSNOBOL4 Extension, added in version 0.99.44. SNOBOL4+ has an
ASC() function.
OUTPUT(variable,unit,options,name)
I/O: Associate variable for output, see snobol4io(1). Standard*.
POS(n)
Pattern: Returns a pattern which succeeds if the pattern matching
cursor is at (non-negative INTEGER) position n, or fails.
Standard.
PROTOTYPE(a)
Data: Returns the prototype of ARRAY a. Standard.
REMDR(n,m)
Math: Returns the remainder from dividing INTEGER n with INTEGER
m. Standard.
RENAME(new,old)
I/O: A predicate which attempts to rename the file named by old to
the name new. Extension from SITBOL: added in CSNOBOL4 version
0.98.5. Unlike the SITBOL version, if the target file exists, it
will be removed.
REPLACE(str,charset1,charset2)
String: Returns a string with each character str that appears in
charset1 replaced by the corresponding character in <charset2>.
Standard.
REVERSE(str)
String: returns its subject string in reverse order. SPITBOL
Extension, added in CSNOBOL4 version 0.98.2.
REWIND(unit)
I/O: Reset input pointer of file associated with unit to start of
file. Standard.
RPAD(str,n,char)
String: Takes the first argument (subject) string, and right pads
it out to the length specified in the second argument, using the
first character of the optional third argument. If the third
argument is missing, or is the null string, spaces will be used for
padding. The subject will be returned unmodified if already long
enough. SPITBOL 360 Extension, added in CSNOBOL4 version 0.98.
RPOS(n)
Pattern: Returns a pattern which succeeds if the pattern matching
cursor is at (non-negative INTEGER) position n, counting from the
end of the subject string, or fails. Standard.
RSORT(ta,c)
Data: see SORT(). Macro SPITBOL extension, added in CSNOBOL4
version 0.98.
RTAB(n)
Pattern: Returns a PATTERN which matches all characters up to (non-
negative INTEGER) position n, counting from the end of the subject
string; matching fails if cursor is past position n. REM is a
synonym for RTAB(0). Standard.
SERV_LISTEN(family,type,service)
I/O: takes three STRING arguments and makes snobol4(1) into a
network server process. family must be either "inet" for an
Internet Protocol v4 socket, "inet6" for an Internet Protocol v6
socket, or "unix" for a local (“unix domain”) socket. The second
argument, TYPE must be "stream", and the third argument, service
must be a port number or service name (for an internet socket), or
a pathname (for a "unix" socket). SERV_LISTEN() listens for
incoming requests, accepts them, then “forks” a child process and
returns an integer file descriptor which can be opened for
bidirectional I/O using a "/dev/fd/n" magic pathname. The original
(“parent”) process never returns from the SERV_LISTEN() call. This
function is only available on systems with the “fork” system call,
which makes a child process which is an identical copy of the
parent process. CSNOBOL4 Extension, added in version 0.99.44
SET(unit,offset,whence)
I/O: Seeks the file pointer of an open file. The first argument is
an I/O unit number, the second is an integer offset. The third
argument, an integer determines from “whence” the file pointer will
be adjusted. If whence is zero the starting point is the beginning
of the file, if whence is one, the starting point is the current
file pointer, and if whence is two, the starting point is the end
of the file. SET() returns the new file pointer value. On systems
with 64-bit file pointers and 32-bit integers the values will be
truncated to 32 bits, and only the first and last 4 gigabytes of a
file can be accessed directly: see SSET(). Catspaw Macro SPITBOL
Extension, added in CSNOBOL4 version 0.99.1.
SETEXIT(label)
Interpreter: The argument to SETEXIT() is the name of a label to
pass control to if a subsequent error occurs, when the keyword
&ERRLIMIT is non-zero. The value of &ERRLIMIT is positive, it is
decremented when the error trap occurs. A SETEXIT() call with a
null argument causes cancellation of the intercept. Subsequent
errors will terminate execution as usual with an error message.
The result returned by SETEXIT() is the previous intercept setting
(i.e., a label name or null if no intercept is set). This can be
used to save and restore the SETEXIT() conditions in a recursive
environment, or chain handlers.
The error intercept routine may inspect &ERRTYPE, &ERRTEXT,
&LASTNO, &LASTFILE, &LASTLINE, and take one of the following
actions:
1. Branching to the special label ABORT causes error processing to
resume as though no error intercept had been set.
2. Branching to the special label CONTINUE causes program
execution to resume by taking the failure exit of the statement in
error.
3. Branching to the special label SCONTINUE causes execution to
resume at the point of interruption.
4. If the error occurred inside a function (&FNCLEVEL is non-zero),
branch to labels RETURN, FRETURN, or NRETURN to return from the
function.
The error intercept routine must reissue the SETEXIT() in order to
catch further errors. Handlers cannot be nested: only one copy of
the saved execution state is kept.
Extension from SPITBOL 360, added in CSNOBOL4 version 1.4.
SIN(argument)
Math: Return sine of argument in radians. SNOBOL4+ Extension?,
added in CSNOBOL4 version 0.98.4.
SIZE(string)
String: returns the length of the STRING argument. Standard.
SORT(ta,c)
Data: takes two arguments. The first can be either an array or a
table. If the first argument is an array, it may be singly-
dimensioned in which case the second argument, if non-null should
indicate the name of a field of a programmer defined data type to
use to access the sort key. Otherwise the first argument should be
a table or a doubly-dimensioned array, in which case the second
argument may an integer indicating the array column on which to
sort. If the second argument is null, it is taken to be 1. The
array (or table) is not modified; a new array is allocated and
returned. SORT() sorts elements in ascending order, while RSORT()
sorts in descending order.
Example: for a table TAB of integers, indexed by strings being used
to tabulate word counts FREQ = RSORT(TAB,2) returns an array such
that FREQ<1,1> contains the most frequent word while FREQ<1,2>
contains the number of occurrences of that word. While WORDS =
SORT(TAB,1) returns an array with the rows by the lexicographical
ordering of the words; WORDS<1,1> contains the lexicographically
first word and WORDS<1,2> contains the number of occurrences of
that word. Macro SPITBOL extension?, added in CSNOBOL4 version
0.98.
SPAN(charset)
Pattern: Returns a pattern that matches the longest run of one or
more characters in string charset. Standard.
SQRT(argument)
Math: Return the square root. Fails if the argument is negative.
Extension from SPITBOL, added in CSNOBOL4 version 0.90.
SSET(unit,offset,whence,scale)
I/O: “scaled set” function, to handle files larger than 4GB on
systems with 32-bit INTEGER variables. The first three arguments
analogous to the same arguments for the SET() function. The last
parameter is used as a multiplicative scaling factor on the offset
parameter, and as a divisor on the return value. When used in
combination with relative SET() calls (whence of one), any file
offset can be achieved, even when system file offsets are larger
than can be represented in a SNOBOL4 INTEGER. Support for “Large
Files” is enabled when available, but not all file systems support
large files. CSNOBOL4 Extension, added in version 0.99.44.
STOPTR(name,type)
Interpreter: Disable type tracing for name. Standard.
SUBSTR(subject,pos,len)
String: Takes a subject string as its first argument, and returns
the substring starting at the position specified by the second
argument (one-based) with a length specified by the third argument.
If the third argument is missing or zero, the remainder of the
string is returned. SPITBOL 360 extension, added in CSNOBOL4
version 0.98.2.
TAB(n)
Pattern: Returns a PATTERN which matches all characters up to
(non-negative INTEGER) position n; matching fails if cursor is
past position n. Standard.
TABLE(n,m)
Data: Return a TABLE object, with (optional) initial size n and
additional extent size m. Standard.
TAN(argument)
Math: Return tangent of argument in radians. SNOBOL4+ extension?,
added in CSNOBOL4 version 0.98.4.
THAW(table)
Data: restores normal entry creation behavior after FREEZE().
SNOBOL4+ extension, added in CSNOBOL4 version 0.98.2.
TIME()
Interpreter: Returns program execution time in milliseconds.
Standard (returning INTEGER). Returns REAL since CSNOBOL4 0.99.44.
TRACE(name,type,id,func)
Intrepreter: Associates name for type (VALUE, CALL, RETURN,
FUNCTION, LABEL, KEYWORD) tracing; id is included in trace output;
func is optional name of function to call. See snobol4key(1) for
&TRACE and &FTRACE keywords. Standard. SPITBOL extension of first
letter of trace type accepted since CSNOBOL4 2.0.
TRIM(str)
String: Returns str with trailing blanks and tabs removed.
Standard.
UNLOAD(name)
Function: Removes the function definition for function name.
Standard.
VALUE(name)
Interpreter: An “accessor” function, defined for STRING and NAME,
so that user data types can declare a VALUE field, and allow
uniform treatment of variables and user types. Standard.
VDIFFER(v1,v2)
Misc: If the two arguments, DIFFER(), the first argument's value is
returned. This is intended to be used in contexts where DIFFER(X)
X would otherwise have been used. Extension from Steve Duff's
Macro SPITBOL, added in CSNOBOL4 version 0.99.44.
NOTES
A “predicate” is a function that either returns the null string or
failure.
An “accessor” is a function which returns it's value by NAME (and can
be used on the right hand side of an assignment).
BUGS
Descriptions are too brief!!
See http://www.snobol4.org/docs/books.html#green for Standard function
definitions.
Need to research origins of “SPITBOL” extensions!
SEE ALSOsnobol4(1), snobol4blocks(1).
CSNOBOL4B 2.0 January 1, 2015 SNOBOL4FUNC(1)
