snobol4func - Man Page

SNOBOL4 summary of built-in functions

Description

ANY(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. 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. Catspaw Macro SPITBOL extension, added in CSNOBOL4 1.4.

BACKSPACE(unit)

I/O: Not implemented!! See SET() and SSET(). Standard.

BREAK(charset)

Pattern: Returns a pattern that matches successively longer runs (zero 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. Catspaw SNOBOL4+ 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. Supports conversion to NUMERIC, SPITBOL 360 extension, added in CSNOBOL4 version 0.99.4.

COPY(value)

Data: returns a copy of the supplied value. Must be an ARRAY or a DATA object. Copy is `shallow'': the returned object will point to the same objects as the source container. Standard.

COS(argument)

Math: Return cosine of argument in radians. Catspaw Macro SPITBOL 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. Macro SPITBOL extension(?), added in CSNOBOL. Does NOT implement “save file” feature of SPITBOL.

EXP(x)

Math: Returns the value e ** x. Catspaw SNOBOL4+ extension, added in CSNOBOL4 version 0.98.4.

EXTERNAL_DATATYPE(x)

Functions: Returns a string for the datatype name for an EXTERNAL type returned by an external function created by LOAD(). Inspired by the DATACODE() function in Fred Weigel's SNOBOL4X extensions. CSNOBOL4 extension, added in CSNOBOL4 version 2.2.

EXTERNAL_MODULE_NAME(x)

Functions: Returns a string for (internal) module name for an EXTERNAL type returned by an external function created by LOAD(). CSNOBOL4 extension, added in CSNOBOL4 version 2.2.

EXTERNAL_MODULE_PATH(x)

Functions: returns a string for the path to an object file for the module for an EXTERNAL type returned by an external function created by LOAD(). CSNOBOL4 extension, added in CSNOBOL4 version 2.2.

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. Catspaw 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,...)

Host O/S functions. See snobol4host(3). Macro 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 name (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 (Added in CSNOBOL4 version 0.99.44, but unreliable until version 1.5).

LABELCODE(name)

Interpreter: Evaluates argument as a name (with case folding), and returns the CODE (if any) associated with the label of that name, or fails. SITBOL extension, added in CSNOBOL4 2.1.

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 360 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 360 extension, added in CSNOBOL4 version 0.98.2.

LGT(s1,s2)

Predicate: tests if first argument is lexically greater than second argument. SPITBOL 360 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 360 extension, added in CSNOBOL4 version 0.98.2.

LLT(s1,s2)

Predicate: tests if first argument is lexically less than second argument. SPITBOL 360 extension, added in CSNOBOL4 version 0.98.2.

LNE(s1,s2)

Predicate: tests if first argument is lexically different from second argument. SPITBOL 360 extension, added in CSNOBOL4 version 0.98.2.

LN(value)

Math: an alias for LOG(), Catspaw SNOBOL4+ 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. Catspaw SNOBOL4+ extension, 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. SITBOL extension: 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 360 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.

SPITBOL 360 extension, added in CSNOBOL4 version 1.4.

SIN(argument)

Math: Return sine of argument in radians. Catspaw Macro SPITBOL 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. Catspaw Macro SPITBOL extension, 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. SPITBOL 360 extension of first letter of trace type accepted since CSNOBOL4 2.0.

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. Catspaw SNOBOL4+ extension?, added in CSNOBOL4 version 0.98.4.

THAW(table)

Data: restores normal entry creation behavior after FREEZE(). Catspaw 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[,tag[,func]]])

Intrepreter: Associates name for type ('VALUE' (default), 'CALL', 'RETURN', 'FUNCTION', 'LABEL', 'KEYWORD') tracing. tag is included in trace output if name is not a natural variable; func is optional name of function to call with name and tag arguments. See snobol4key(1) &TRACE (must be non-zero to enable TRACE. Standard. SPITBOL 360 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.