1SNOBOL4FUNC(1) CSNOBOL4 Manual SNOBOL4FUNC(1)
2
6 snobol4func - SNOBOL4 summary of built-in functions
7
9 ANY(charset)
10 Pattern: returns a pattern that matches one character in the STRING
11 charset. Standard.
12 APPLY(func,arg1,...)
14 Function: calls function func with the supplied arguments.
15 Standard.
16 ARBNO(pattern)
18 Pattern: returns a pattern that matches zero or more repeats of
19 pattern. Standard.
20 ARG(func,n)
22 Function: returns the name of the nth argument to function func.
23 Standard.
24 ARRAY(proto,value)
26 Data: Creates an ARRAY object. Standard.
27 ATAN(arg)
29 Math: Returns the principal value of the arc tangent of its
30 argument. Catspaw Macro SPITBOL extension, added in CSNOBOL4 1.4.
31 BACKSPACE(unit)
33 I/O: Not implemented!! See SET() and SSET(). Standard.
34 BREAK(charset)
36 Pattern: Returns a pattern that matches successively longer runs
37 (zero or more) characters NOT in string charset. Standard.
38 BREAKX(charset)
40 Pattern: A pattern function used for fast scanning. BREAKX(str) is
41 equivalent to BREAK(str) ARBNO(LEN(1) BREAK(str)).
42 In other words BREAKX matches a sequence of ever larger strings
44 terminated by a break set. BREAKX can be used as a faster matching
45 replacement for ARB: BREAKX('S') 'STRING' always runs faster than
46 ARB 'STRING' since it only attempts matching 'STRING' at locations
47 where an 'S' has been detected. SPITBOL 360 extension, added in
48 CSNOBOL4 version 0.98.
49 CHAR(n)
51 String: takes an integer from 0 to 255 and returns the nth
52 character in &ALPHABET. SPITBOL 360 extension, added in CSNOBOL4
53 version 0.98. SNOBOL4+ has a CHR() function.
54 CHOP(real)
56 Math: truncates the fractional part of its argument (rounding
57 towards zero), and returns a REAL value. Catspaw SNOBOL4+
58 extension(?), added in CSNOBOL4 version 0.98.4.
59 CLEAR()
61 Interpreter: Clears ALL natural variable values (including
62 predefined pattern variables ABORT, ARB, BAL, FENCE, REM, and
63 SUCCEED). Standard.
64 CODE(str)
66 Interpreter: Compiles the argument as source code and returns a
67 CODE value, suitable for use with :<code>. If execution falls off
68 the end of the code, the program will exit. Standard.
69 COLLECT(n)
71 Interpreter: Triggers garbage collection. Returns failure if less
72 than n bytes are available after collection. Standard.
73 CONVERT(value,type)
75 Data: Convert value to data type type. Can convert TABLE to ARRAY
76 for iteration over members. Standard. Supports conversion to
77 NUMERIC, SPITBOL 360 extension, added in CSNOBOL4 version 0.99.4.
78 COPY(value)
80 Data: returns a copy of the supplied value. Must be an ARRAY or a
81 DATA object. Copy is `shallow”: the returned object will point to
82 the same objects as the source container. Standard.
83 COS(argument)
85 Math: Return cosine of argument in radians. Catspaw Macro SPITBOL
86 extension, added in CSNOBOL4 version 0.98.4.
87 DATA(prototype)
89 Data: Declares a DATA struct type. prototype is of the form
90 name(field,...). name is declared as a “constructor” function, and
91 each field is declared as an “accessor” function for the type. Any
92 number of types can use the same field names (regardless of
93 position). Standard.
94 DATATYPE(value)
96 Data: Returns a string with the data type of value, one of: ARRAY,
97 BLOCK, CODE, EXPRESSION, EXTERNAL, INTEGER, NAME, PATTERN, REAL,
98 STRING, TABLE, or a DATA() type name. Standard.
99 DATE()
101 String: returns MM/DD/YYYY HH:MM:SS. Standard. For compatibility
102 with Catspaw Macro SPITBOL, since CSNOBOL4 version 0.99.4 DATE(0)
103 returns strings of the form MM/DD/YY HH:MM:SS, and DATE(2) returns
104 strings of the form YYYY-MM-YY HH:MM:SS.
105 DEFINE(prototype[,label])
107 Functions: declares a function using prototype of the form
108 “name([argname,...])[localname,...]”. Optional label supplies the
109 function entry point. Standard.
110 DELETE(filename)
112 I/O: A predicate which tries to remove the named file, and fails if
113 it cannot. SITBOL extension: added in CSNOBOL4 version 0.98.5.
114 DETACH(name)
116 I/O: Detach any I/O associations for named variable. Standard.
117 DIFFER(val1,val2)
119 Predicate: Succeeds if the supplied values refer to different
120 objects, strings, or numeric values. Standard.
121 DUMP(n)
123 Data: dumps natural variable values to stdout if argument n is non-
124 zero. Standard.
125 DUPL(string,n)
127 String: Returns a string with n copies of argument string.
128 Standard.
129 ENDFILE(unit)
131 I/O: Closes the file attached to I/O unit unit. Standard.
132 EQ(i1,i2)
134 Predicate: Succeeds if i1 is arithmetically equal to i2. Standard.
135 EVAL(v)
137 Interpreter: Evaluates v (an unevaluated expression, INTEGER, REAL,
138 or STRING), and returns the result; returns failure on syntax error
139 or the expression fails. Standard.
140 EXIT(arg)
142 System: Passes process control to a shell to execute arg as a
143 command. Returns failure if arg is not a STRING. Macro SPITBOL
144 extension(?), added in CSNOBOL. Does NOT implement “save file”
145 feature of SPITBOL.
146 EXP(x)
148 Math: Returns the value e ** x. Catspaw SNOBOL4+ extension, added
149 in CSNOBOL4 version 0.98.4.
150 EXTERNAL_DATATYPE(x)
152 Functions: Returns a string for the datatype name for an EXTERNAL
153 type returned by an external function created by LOAD(). Inspired
154 by the DATACODE() function in Fred Weigel's SNOBOL4X extensions.
155 CSNOBOL4 extension, added in CSNOBOL4 version 2.2.
156 EXTERNAL_MODULE_NAME(x)
158 Functions: Returns a string for (internal) module name for an
159 EXTERNAL type returned by an external function created by LOAD().
160 CSNOBOL4 extension, added in CSNOBOL4 version 2.2.
161 EXTERNAL_MODULE_PATH(x)
163 Functions: returns a string for the path to an object file for the
164 module for an EXTERNAL type returned by an external function
165 created by LOAD(). CSNOBOL4 extension, added in CSNOBOL4 version
166 2.2.
167 FIELD(name,n)
169 Data: Returns a string with the name of the nth member of DATA()
170 type name. Standard.
171 FILE(string)
173 I/O: A predicate which tests if a file exists, and fails if it does
174 not. SITBOL extension, added in CSNOBOL4 version 0.98.5.
175 FILE_ABSPATH(string)
177 I/O: A predicate which returns null if its argument is an absolute
178 file path, and failure if the path is relative. CSNOBOL4
179 extension, added in CSNOBOL4 version 1.5.
180 FILE_ISDIR(string)
182 I/O: A predicate which returns the null string if its argument is
183 the pathname of a directory, and returns failure if not. CSNOBOL4
184 extension, added in CSNOBOL4 version 1.5.
185 FREEZE(table)
187 Data: prohibits creation of new entries in the referenced table.
188 This is useful once a table has been initialized to avoid creating
189 empty entries on lookups that fail. This can greatly improve
190 program speed, since frozen tables will not become clogged with
191 empty entries. Lookups for uninitialized entries will return the
192 null string. Attempts to assign to a non-existent entry will cause
193 a “Variable not present where required” error. Catspaw SNOBOL4+
194 extension, added in CSNOBOL4 version 0.98.2.
195 FUNCTION(name)
197 Function: A predicate which evaluates its argument as a string
198 (with case folding), and returns the null string if a function with
199 that name exists and fails if it does not. SITBOL extension, added
200 in CSNOBOL4 version 0.99.44.
201 GE(i1,i2)
203 Predicate: Succeeds if i1 is arithmetically equal than or equal to
204 i2. Standard.
205 GT(i1,i2)
207 Predicate: Succeeds if i1 is arithmetically equal than i2.
208 Standard.
209 HOST(i,...)
211 Host O/S functions. See snobol4host(3). Macro SPITBOL extension,
212 added in CSNOBOL4 version 0.98.4.
213 IDENT(v1,v2)
215 Predicate: Succeeds if the supplied values refer to the same
216 object, string, or numeric value. Standard.
217 INPUT(variable,unit,opt,name)
219 I/O: Associate variable for input, see snobol4io(1). Standard.*
220 INTEGER(value)
222 Predicate: Succeed if value is an INTEGER. Standard.
223 IO_FINDUNIT()
225 I/O: Returns an unused I/O unit number for use with the INPUT() or
226 OUTPUT() functions. IO_FINDUNIT() is meant for use in subroutines
227 which can be reused. IO_FINDUNIT() will never return a unit number
228 below 20. CSNOBOL4 extension, added in version 0.99.4.
229 ITEM(a,i1,...)
231 Data: Reference an element of an ARRAY or TABLE which is the
232 result of an expression (ie; $variable). Standard.
233 LABEL(name)
235 Predicate: Evaluates argument as a name (with case folding), and
236 returns the null string if a label with that name has been defined,
237 and fails if it does not. Steve Duff's Macro SPITBOL extension,
238 added in CSNOBOL4 version 1.5 (Added in CSNOBOL4 version 0.99.44,
239 but unreliable until version 1.5).
240 LABELCODE(name)
242 Interpreter: Evaluates argument as a name (with case folding), and
243 returns the CODE (if any) associated with the label of that name,
244 or fails. SITBOL extension, added in CSNOBOL4 2.1.
245 LE(i1,i2)
247 Predicate: tests if first argument is arithmetically less than or
248 equal to second argument. Standard.
249 LEN(n)
251 Pattern: Returns a PATTERN which matches exactly n characters.
252 Standard.
253 LEQ(s1,s2)
255 Predicate: tests if first argument is lexically equal to second
256 argument. SPITBOL 360 extension, added in CSNOBOL4 version 0.98.2.
257 LGE(S1,S2)
259 Predicate: tests if first argument is lexically greater than or
260 equal to second argument. SPITBOL 360 extension, added in CSNOBOL4
261 version 0.98.2.
262 LGT(s1,s2)
264 Predicate: tests if first argument is lexically greater than second
265 argument. SPITBOL 360 extension, added in CSNOBOL4 version 0.98.2.
266 LLE(s1,s2)
268 Predicate: tests if first argument is lexically less than or equal
269 to second argument. SPITBOL 360 extension, added in CSNOBOL4
270 version 0.98.2.
271 LLT(s1,s2)
273 Predicate: tests if first argument is lexically less than second
274 argument. SPITBOL 360 extension, added in CSNOBOL4 version 0.98.2.
275 LNE(s1,s2)
277 Predicate: tests if first argument is lexically different from
278 second argument. SPITBOL 360 extension, added in CSNOBOL4 version
279 0.98.2.
280 LN(value)
282 Math: an alias for LOG(), Catspaw SNOBOL4+ extension, added in
283 CSNOBOL4 version 1.4.
284 LOAD(prototype,file)
286 Function: Load an external function from dynamically loaded
287 library file. Standard.
288 LOCAL(name,n)
290 Interpreter: Returns a STRING with the nth argument to function
291 named name. Standard.
292 LOG(value)
294 Math: returns the natural logarithm of its argument. Catspaw
295 SNOBOL4+ extension, added in CSNOBOL4 version 0.98.4.
296 LPAD(str,n,char)
298 String: Takes the first argument (subject) string, and left pads it
299 out to the length specified in the second argument, using the first
300 character of the optional third argument. If the third argument is
301 missing, or is the null string, spaces will be used for padding.
302 The subject will be returned unmodified if already long enough.
303 SPITBOL 360 extension, added in CSNOBOL4 version 0.98.
304 LT(i1,i2)
306 Predicate: Succeeds if i1 is arithmetically less than i2.
307 Standard.
308 NE(i1,i2)
310 Predicate: Succeeds if i1 is arithmetically not equal to i2.
311 Standard.
312 NOTANY(charset)
314 Pattern: Returns a pattern which matches on character NOT present
315 in STRING charset. Standard.
316 OPSYN(new,old,n)
318 Interpreter: If n omitted (or zero), new and old are treated as
319 function names, and new becomes a synonym for old: A call to a
320 synonym MUST have the correct number of arguments; trailing
321 arguments can NOT be omitted. If n is 1, new and old are treated
322 as unary operators, or function names. If n is 2, new and old are
323 treated as binary operators, or function names. Standard.
324 ORD(string)
326 String: returns the INTEGER ordinal value (zero to 255) of the
327 first character in its string argument (the inverse of CHAR()).
328 CSNOBOL4 extension, added in version 0.99.44. SNOBOL4+ has an
329 ASC() function.
330 OUTPUT(variable,unit,options,name)
332 I/O: Associate variable for output, see snobol4io(1). Standard*.
333 POS(n)
335 Pattern: Returns a pattern which succeeds if the pattern matching
336 cursor is at (non-negative INTEGER) position n, or fails.
337 Standard.
338 PROTOTYPE(a)
340 Data: Returns the prototype of ARRAY a. Standard.
341 REMDR(n,m)
343 Math: Returns the remainder from dividing INTEGER n with INTEGER
344 m. Standard.
345 RENAME(new,old)
347 I/O: A predicate which attempts to rename the file named by old to
348 the name new. SITBOL extension: added in CSNOBOL4 version 0.98.5.
349 Unlike the SITBOL version, if the target file exists, it will be
350 removed.
351 REPLACE(str,charset1,charset2)
353 String: Returns a string with each character str that appears in
354 charset1 replaced by the corresponding character in <charset2>.
355 Standard.
356 REVERSE(str)
358 String: returns its subject string in reverse order. SPITBOL 360
359 extension, added in CSNOBOL4 version 0.98.2.
360 REWIND(unit)
362 I/O: Reset input pointer of file associated with unit to start of
363 file. Standard.
364 RPAD(str,n,char)
366 String: Takes the first argument (subject) string, and right pads
367 it out to the length specified in the second argument, using the
368 first character of the optional third argument. If the third
369 argument is missing, or is the null string, spaces will be used for
370 padding. The subject will be returned unmodified if already long
371 enough. SPITBOL 360 extension, added in CSNOBOL4 version 0.98.
372 RPOS(n)
374 Pattern: Returns a pattern which succeeds if the pattern matching
375 cursor is at (non-negative INTEGER) position n, counting from the
376 end of the subject string, or fails. Standard.
377 RSORT(ta,c)
379 Data: see SORT(). Macro SPITBOL extension(?), added in CSNOBOL4
380 version 0.98.
381 RTAB(n)
383 Pattern: Returns a PATTERN which matches all characters up to (non-
384 negative INTEGER) position n, counting from the end of the subject
385 string; matching fails if cursor is past position n. REM is a
386 synonym for RTAB(0). Standard.
387 SERV_LISTEN(family,type,service)
389 I/O: takes three STRING arguments and makes snobol4(1) into a
390 network server process. family must be either "inet" for an
391 Internet Protocol v4 socket, "inet6" for an Internet Protocol v6
392 socket, or "unix" for a local (“unix domain”) socket. The second
393 argument, TYPE must be "stream", and the third argument, service
394 must be a port number or service name (for an internet socket), or
395 a pathname (for a "unix" socket). SERV_LISTEN() listens for
396 incoming requests, accepts them, then “forks” a child process and
397 returns an integer file descriptor which can be opened for
398 bidirectional I/O using a "/dev/fd/n" magic pathname. The original
399 (“parent”) process never returns from the SERV_LISTEN() call. This
400 function is only available on systems with the “fork” system call,
401 which makes a child process which is an identical copy of the
402 parent process. CSNOBOL4 extension, added in version 0.99.44
403 SET(unit,offset,whence)
405 I/O: Seeks the file pointer of an open file. The first argument is
406 an I/O unit number, the second is an integer offset. The third
407 argument, an integer determines from “whence” the file pointer will
408 be adjusted. If whence is zero the starting point is the beginning
409 of the file, if whence is one, the starting point is the current
410 file pointer, and if whence is two, the starting point is the end
411 of the file. SET() returns the new file pointer value. On systems
412 with 64-bit file pointers and 32-bit integers the values will be
413 truncated to 32 bits, and only the first and last 4 gigabytes of a
414 file can be accessed directly: see SSET(). Catspaw Macro SPITBOL
415 extension, added in CSNOBOL4 version 0.99.1.
416 SETEXIT(label)
418 Interpreter: The argument to SETEXIT() is the name of a label to
419 pass control to if a subsequent error occurs, when the keyword
420 &ERRLIMIT is non-zero. The value of &ERRLIMIT is positive, it is
421 decremented when the error trap occurs. A SETEXIT() call with a
422 null argument causes cancellation of the intercept. Subsequent
423 errors will terminate execution as usual with an error message.
424 The result returned by SETEXIT() is the previous intercept setting
425 (i.e., a label name or null if no intercept is set). This can be
426 used to save and restore the SETEXIT() conditions in a recursive
427 environment, or chain handlers.
428 The error intercept routine may inspect &ERRTYPE, &ERRTEXT,
430 &LASTNO, &LASTFILE, &LASTLINE, and take one of the following
431 actions:
432 1. Branching to the special label ABORT causes error processing to
434 resume as though no error intercept had been set.
435 2. Branching to the special label CONTINUE causes program
437 execution to resume by taking the failure exit of the statement in
438 error.
439 3. Branching to the special label SCONTINUE causes execution to
441 resume at the point of interruption.
442 4. If the error occurred inside a function (&FNCLEVEL is non-zero),
444 branch to labels RETURN, FRETURN, or NRETURN to return from the
445 function.
446 The error intercept routine must reissue the SETEXIT() in order to
448 catch further errors. Handlers cannot be nested: only one copy of
449 the saved execution state is kept.
450 SPITBOL 360 extension, added in CSNOBOL4 version 1.4.
452 SIN(argument)
454 Math: Return sine of argument in radians. Catspaw Macro SPITBOL
455 extension, added in CSNOBOL4 version 0.98.4.
456 SIZE(string)
458 String: returns the length of the STRING argument. Standard.
459 SORT(ta,c)
461 Data: takes two arguments. The first can be either an array or a
462 table. If the first argument is an array, it may be singly-
463 dimensioned in which case the second argument, if non-null should
464 indicate the name of a field of a programmer defined data type to
465 use to access the sort key. Otherwise the first argument should be
466 a table or a doubly-dimensioned array, in which case the second
467 argument may an integer indicating the array column on which to
468 sort. If the second argument is null, it is taken to be 1. The
469 array (or table) is not modified; a new array is allocated and
470 returned. SORT() sorts elements in ascending order, while RSORT()
471 sorts in descending order.
472 Example: for a table TAB of integers, indexed by strings being used
474 to tabulate word counts FREQ = RSORT(TAB,2) returns an array such
475 that FREQ<1,1> contains the most frequent word while FREQ<1,2>
476 contains the number of occurrences of that word. While WORDS =
477 SORT(TAB,1) returns an array with the rows by the lexicographical
478 ordering of the words; WORDS<1,1> contains the lexicographically
479 first word and WORDS<1,2> contains the number of occurrences of
480 that word. Macro SPITBOL extension(?), added in CSNOBOL4 version
481 0.98.
482 SPAN(charset)
484 Pattern: Returns a pattern that matches the longest run of one or
485 more characters in string charset. Standard.
486 SQRT(argument)
488 Math: Return the square root. Fails if the argument is negative.
489 Catspaw Macro SPITBOL extension, added in CSNOBOL4 version 0.90.
490 SSET(unit,offset,whence,scale)
492 I/O: “scaled set” function, to handle files larger than 4GB on
493 systems with 32-bit INTEGER variables. The first three arguments
494 analogous to the same arguments for the SET() function. The last
495 parameter is used as a multiplicative scaling factor on the offset
496 parameter, and as a divisor on the return value. When used in
497 combination with relative SET() calls (whence of one), any file
498 offset can be achieved, even when system file offsets are larger
499 than can be represented in a SNOBOL4 INTEGER. Support for “Large
500 Files” is enabled when available, but not all file systems support
501 large files. CSNOBOL4 extension, added in version 0.99.44.
502 STOPTR(name,type)
504 Interpreter: Disable type tracing for name. Standard. SPITBOL
505 360 extension of first letter of trace type accepted since CSNOBOL4
506 2.0.
507 SUBSTR(subject,pos,len)
509 String: Takes a subject string as its first argument, and returns
510 the substring starting at the position specified by the second
511 argument (one-based) with a length specified by the third argument.
512 If the third argument is missing or zero, the remainder of the
513 string is returned. SPITBOL 360 extension, added in CSNOBOL4
514 version 0.98.2.
515 TAB(n)
517 Pattern: Returns a PATTERN which matches all characters up to
518 (non-negative INTEGER) position n; matching fails if cursor is
519 past position n. Standard.
520 TABLE(n,m)
522 Data: Return a TABLE object, with (optional) initial size n and
523 additional extent size m. Standard.
524 TAN(argument)
526 Math: Return tangent of argument in radians. Catspaw SNOBOL4+
527 extension?, added in CSNOBOL4 version 0.98.4.
528 THAW(table)
530 Data: restores normal entry creation behavior after FREEZE().
531 Catspaw SNOBOL4+ extension, added in CSNOBOL4 version 0.98.2.
532 TIME()
534 Interpreter: Returns program execution time in milliseconds.
535 Standard (returning INTEGER). Returns REAL since CSNOBOL4 0.99.44.
536 TRACE(name[,type[,tag[,func]]])
538 Intrepreter: Associates name for type ('VALUE' (default),
539 'CALL', 'RETURN', 'FUNCTION', 'LABEL', 'KEYWORD') tracing.
540 tag is included in trace output if name is not a natural variable;
541 func is optional name of function to call with name and tag
542 arguments. See snobol4key(1) &TRACE (must be non-zero to enable
543 TRACE. Standard. SPITBOL 360 extension of first letter of trace
544 type accepted since CSNOBOL4 2.0.
545 TRIM(str)
547 String: Returns str with trailing blanks and tabs removed.
548 Standard.
549 UNLOAD(name)
551 Function: Removes the function definition for function name.
552 Standard.
553 VALUE(name)
555 Interpreter: An “accessor” function, defined for STRING and NAME,
556 so that user data types can declare a VALUE field, and allow
557 uniform treatment of variables and user types. Standard.
558 VDIFFER(v1,v2)
560 Misc: If the two arguments, DIFFER(), the first argument's value is
561 returned. This is intended to be used in contexts where DIFFER(X)
562 X would otherwise have been used. Extension from Steve Duff's
563 Macro SPITBOL, added in CSNOBOL4 version 0.99.44.
564
566 A “predicate” is a function that either returns the null string or
567 failure.
568 An “accessor” is a function which returns it's value by NAME (and can
570 be used on the right hand side of an assignment).
571
573 Descriptions are too brief!!
574 See http://www.regressive.org/snobol4/docs/books.html#green for
576 Standard function definitions.
577 Need to research origins of Macro SPITBOL extensions.
579
581 snobol4(1), snobol4blocks(1).
582CSNOBOL4B 2.3.1 March 31, 2022 SNOBOL4FUNC(1)