GNU SETL Library Reference

sharp (#)  -  size of set; length of string or tuple

op # (set) : integer
op # (string) : integer
op # (tuple) : integer

The size (cardinality) of a set is the number of elements. The length of a tuple is the index of its last non-om element.

star (*)  -  multiplication; set intersection; string or tuple replication

op * (integer, integer) : integer
op * (real, real) : real
op * (real, integer) : real
op * (integer, real) : real
op * (set, set) : set
op * (string, integer) : string
op * (integer, string) : string
op * (tuple, integer) : tuple
op * (integer, tuple) : tuple

When one operand is real and the other integer, the integer value is converted as if by float before the numbers are multiplied.

In a bounded floating-point implementation such as 64-bit IEEE 754, multiplication can overflow to a floating-point infinity, or underflow to a subnormal number or a zero. Multiplying an infinity by 0 can produce a NaN (Not a Number). Multiplying a NaN by anything gives another NaN.

For a pair of set operands, this operator gives the set intersection, i.e., for sets a and b, a*b = {x in a | x in b}. (The first in iterates over a, the vertical bar means such that, and the second in tests for membership in b.)

For the cases involving a string or tuple, the result is the concatenation of however many copies of that string or tuple are indicated by the integer operand.

power (**)  -  exponentiation

op ** (integer, integer) : integer
op ** (integer, integer) : real
op ** (real, real) : real
op ** (real, integer) : real
op ** (integer, real) : real

The first operand is the base, and the second is the power to raise it to.

When both operands are of type integer, the return type is integer unless the power is negative, in which case the operands are first converted as if by float, as is the integer operand in the mixed cases.

When the power is 0, the result is 1 regardless of the base, in the type appropriate for the operands.

In a bounded floating-point implementation such as 64-bit IEEE 754, this operator works like POSIX pow() for all cases that return a real.

It is right-associative, which is an incompatible change from CIMS SETL but agrees with SETL2 and with the Fortran operator it resembles. It has higher precedence than all other binary operators, just below all non-predicate unary operators. See Operator Precedence.

plus (+)  -  addition; set union; concatenation

op + (integer) : integer
op + (real) : real
op + (integer, integer) : integer
op + (real, real) : real
op + (real, integer) : real
op + (integer, real) : real
op + (set, set) : set
op + (string, string) : string
op + (tuple, tuple) : tuple
op + (string, var) : string
op + (var, string) : string

The unary forms simply check that the operand is a number and return that number.

When one operand is real and the other integer, the integer value is converted as if by float before the numbers are added.

In a bounded floating-point implementation such as 64-bit IEEE 754, addition can overflow to a floating-point infinity, or underflow to a subnormal number. Addition of opposite infinities can produce a NaN (Not a Number). Adding a NaN to anything gives another NaN.

For a pair of set operands, this operator gives the set union, i.e., all elements from both sets. See also with.

The cases in which just one operand is a string are treated as if str is first applied to the non-string operand (shown here as var), for string concatenation.

The assigning +:= operator, when its left-hand operand is initially om, substitutes the additive identity (if any) of the type of its right-hand operand. So for example

sum +:= num

does not require sum to be pre-initialized before num is added to it. Here are the additive identities:

It is an error for the left-hand side of +:= to be om if the type of the right-hand side has no additive identity.

Note that when x is om,

x +:= "some string"

is slightly different from

x := x + "some string"

as the latter is then equivalent to

x := str om + "some string"

or in other words

x := "*some string"

Also,

n +:= 1

gives n the value 1 if it is initially om, but

n := n + 1

is an error (trying to add om and a number).

Similarly, trying to accumulate a set or tuple into an uninitialized variable using plain + rather than the assigning form +:= is an error.

minus (-)  -  negation or subtraction; set difference

op - (integer) : integer
op - (real) : real
op - (integer, integer) : integer
op - (real, real) : real
op - (real, integer) : real
op - (integer, real) : real
op - (set, set) : set

When one operand is real and the other integer, the integer value is converted as if by float before the numbers are subtracted.

In a bounded floating-point implementation such as 64-bit IEEE 754, subtraction can overflow to a floating-point infinity, or underflow to a subnormal number. Subtraction of equal infinities can produce a NaN (Not a Number), and a NaN operand gives a NaN result.

For a pair of set operands, this operator gives the set difference, i.e., for sets a and b, a - b = {x in a | x notin b}.

See also less, and the symmetric set difference operator mod.

slash (/)  -  division

op / (integer, integer) : real     -- when intslash is false
op / (integer, integer) : integer  -- when intslash is true
op / (real, real) : real
op / (real, integer) : real
op / (integer, real) : real

By default, all integer operands are converted as if by float, and the result is real. You would normally use div to get integer quotients.

But you can force this slash operator to work like div for the integer / integer case by setting intslash := true, or equivalently by calling set_intslash (true). This makes the slash operator mimic SETL2, which entails some peril. Consider a program that reads pairs of numbers and computes their quotients. Unless it takes care to ensure that at least one operand is real, say by applying float, such a program will sometimes truncate quotients and sometimes not, depending on which input numbers happen to have decimal points (or exponents) in them.

Division of reals, if the floating-point implementation is 64-bit IEEE 754, can produce an infinity by means of overflow or a divisor of 0, or can underflow to a subnormal number or a zero. Division of infinities gives a NaN (Not a Number), and a NaN operand gives a NaN result.

equalities (=, /=)  -  equal, not equal

op = (var, var) : boolean
op /= (var, var) : boolean

In most cases, two values of different types are considered unequal. But in the special case where an integer and real are numerically equal, they are considered equal despite their differing types.

A floating-point NaN (Not a Number) never equals anything, not even another bit-identical NaN.

comparatives (<, >, <=, >=)  -  order-based comparisons

op < (integer, integer) : boolean
op < (real, real) : boolean
op < (real, integer) : boolean
op < (integer, real) : boolean
op < (string, string) : boolean
op < (tuple, tuple) : boolean

op > (integer, integer) : boolean
op > (real, real) : boolean
op > (real, integer) : boolean
op > (integer, real) : boolean
op > (string, string) : boolean
op > (tuple, tuple) : boolean

op <= (integer, integer) : boolean
op <= (real, real) : boolean
op <= (real, integer) : boolean
op <= (integer, real) : boolean
op <= (string, string) : boolean
op <= (tuple, tuple) : boolean

op >= (integer, integer) : boolean
op >= (real, real) : boolean
op >= (real, integer) : boolean
op >= (integer, real) : boolean
op >= (string, string) : boolean
op >= (tuple, tuple) : boolean

Strings are compared character by character, as if using the codes arising from ichar. Tuple comparisons are recursive. If one string or tuple is a prefix of the other, the shorter one is considered smaller.

Where one operand is integer and the other is real, the integer is converted as if by float before comparison.

Comparison of a floating-point NaN (Not a Number) with anything yields false.

See also max and min.

query (?)  -  short-circuiting om test

op ? (var, var) : var

The expression

x ? y

is equivalent to the expression

if (temp := x) /= om then temp else y end

(or simply

if x /= om then x else y end

if x has no side-effects).

Thus the query operator is short-circuited like and and or.

abs  -  absolute value; integer value of character; Euclidean norm

op abs (integer) : integer
op abs (real) : real
op abs (string) : integer
op abs (tuple) : real

For a number, abs returns the magnitude.

For a string, abs is equivalent to ichar.

For a tuple t of numbers,

abs t = sqrt (0 +/ [x**2 : x in t])

Thus for a complex number represented by [x, y], its magnitude is abs [x, y]. Its phase is y atan2 x.

accept  -  accept connection on server socket

proc accept (stream) : integer

The argument must be a TCP or Unix-domain server socket opened by open, or denote a host and TCP port to auto-open in "tcp-server" mode (see Automatic opening).

The accept function waits for a client to connect, and then returns a new stream (over a new socket fd) for that peer connection.

The select function can be used on a server socket to test whether an accept would block on it.

It is possible for accept to fail due to conditions arising between the time of a successful select and the issuing of the accept call. In this case accept sets last_error and returns om.

See also peer_address, peer_name, peer_port, peer_sockaddr, sockaddr, and the "unix-server" mode of open.

acos  -  arc cosine

op acos (real) : real
op acos (integer) : real

The operand must be in the range -1 to +1, and the result is in radians. See also cos.

and  -  logical conjunction

op and (boolean, boolean) : boolean

The expression

x and y

is equivalent to the expression

if x then y else false end

which is to say that the and operator is short-circuited: it only evaluates y if x is true. This makes it suitable for use as a guard against erroneous evaluations such as subscripting a tuple with a nonpositive integer. For example,

if i > 0 then
  if t(i) = "/" then
    ...
  end if;
end if;

can be replaced by

if i > 0 and t(i) = "/" then
  ...
end if;

See also or and the query operator (?), which are likewise short-circuited, and the bitwise operators such as bit_and, which aren’t.

The and operator has a rather low precedence, above or but below not.

any  -  extract leading character using character set

proc any (rw string s, string p) : string

If the first character of s appears anywhere in p (treating p as a set of characters), that first character is removed from s and returned. Otherwise, nothing happens to s, and the empty string ("") is returned.

See also the other SNOBOL-inspired intrinsics, namely break, len, match, notany, span, rany, rbreak, rlen, rmatch, rnotany, and rspan. The inspiration is pretty much confined to the reuse of these names, as they are rather clumsy in their present form. But SETL currently has neither the syntactic nor semantic support for SNOBOL-like chained pattern matching with backtracking and easy extraction of intermediate substrings and positions into variables.

arb  -  arbitrary element of set

op arb (set) : var

An arbitrary (not random, but dealer’s choice) element of the set is returned. If the set is empty, om is returned.

See also from and random.

asin  -  arc sine

op asin (real) : real
op asin (integer) : real

The operand must be in the range -1 to +1, and the result is in radians. See also sin.

atan  -  arc tangent

op atan (real) : real
op atan (integer) : real

The result is in radians. See also atan2 and tan.

atan2  -  arc tangent of quotient

op atan2 (real, real) : real
op atan2 (real, integer) : real
op atan2 (integer, real) : real
op atan2 (integer, integer) : real

For non-zero x, the expression

y atan2 x

is similar to the expression

atan (y/x)

but when x is 0, only the atan2 form can be used, and returns a floating-point approximation of π/2 or -π/2 depending on the sign of y (or 0 if y is 0).

SETL does not currently have first class support for complex numbers, but for such a number with real part x and imaginary part y, its phase is y atan2 x and its magnitude is abs [x, y].

bit_and, bit_not, bit_or, bit_xor  -  bitwise logical ops

op bit_and (integer, integer) : integer
op bit_not (integer) : integer
op bit_or (integer, integer) : integer
op bit_xor (integer, integer) : integer

These operators treat integers as if they were expressed in 2’s complement with an infinite sequence of leading 0 or 1 digits. For example, bit_not 1 = -2.

See also and, or, and not.

break  -  extract leading substring using character set

proc break (rw string s, string p) : string

An initial substring of s up to but not including the first character that is found in p (treating p as a set of characters) is removed (broken off) from s and returned. If no character from p appears in s, the return value is the initial value of s, and s is reduced to the empty string ("").

See also the other SNOBOL-inspired intrinsics, namely any, len, match, notany, span, rany, rbreak, rlen, rmatch, rnotany, and rspan.

call  -  indirect call

proc call (proc_ref, var args(*)) : var

All of the 0 or more args to call are read-only, so the procedure referenced through the proc_ref value must not have any rw or wr arguments. It may, however, return a result of any type, including tuple, so multiple values can easily be returned, e.g.:

f_ref := routine f;
  ...
[x, y, z] := call (f_ref, a, b);
  ...
proc f (v, w);
  ...
  return [p, q, r];
end proc f;

callout  -  call C function

proc callout (integer service, om, tuple arglist) : string

This is a SETL2 compatibility feature. It calls a C function having the signature

char *setl2_callout (int service, int argc, char *const *argv)

by first converting service to a C int and arglist (which must contain only strings) to the pair of callout arguments argc (the number of strings) and argv (an array of pointers to C character strings).

The result of the call, a C character string, is then converted to a SETL string and returned by callout.

GNU SETL comes with a “stub” version of setl2_callout that simply reports details of the call on stderr and then returns a NULL pointer, causing callout to return om.

ceil  -  ceiling (least integer upper bound)

op ceil (real) : integer
op ceil (integer) : integer

This operator returns the smallest integer that is greater than or equal to the given operand.

For example, ceil -5.9 = -5.

Floating-point infinities and NaN (Not a Number) values give om.

See also floor, round, fix, and float.

char  -  character encoding of small integer

op char (integer) : string

This operator makes a one-byte string rather directly from the operand, which must be an integer in the range 0 to 255. For example, char 32 = "\x20".

In SETL, NUL characters may occur within strings, so char 0, or equivalently "\x00", is valid.

See also ichar.

chdir  -  change directory

proc chdir
proc chdir (string s)

The current working directory (“folder”) is changed to s if given and valid. Otherwise, if the HOME environment variable is defined and names a valid directory, the working directory becomes that.

It is an error for chdir to be called with no arg if HOME is not defined.

If s is given but not valid, or if s is not given and HOME is defined but not valid, then the current working directory is not changed, and last_error tells why. For example, the reason might be a nonexistent directory, a file that is not a directory, or insufficient permission to open the directory, as ruled by POSIX chdir().

See also getwd.

clear_error  -  clear system error indicator

proc clear_error

Sets last_error to no_error.

For example, a doubtful chdir call could be guarded thus:

clear_error;
chdir ("somewhere");
if last_error = no_error then
  -- success ...
else  -- the string last_error explains
  -- failure ...
end if;

clock  -  elapsed time in milliseconds

proc clock : integer

This is the total amount of wall-clock (“real”) time, in milliseconds, that has elapsed since the current process began. It is a monotonic clock, and does not depend on changes to the time within the epoch.

See also time and tod.

close  -  close stream

proc close (stream f)
proc close (stream f, integer how)

If f is a stream, i.e., if is_open f is true, then it is flushed as if by flush and destroyed. Any stream associated with f by tie is also flushed, and the association is dissolved. Output failures in the flushing are not reflected in last_error.

The underlying file descriptor (f itself or the associated fd) is passed to POSIX close() if it is in the range of valid file descriptors at the POSIX (system) level. That range is 0 to some maximum. Most Unix shells have a built-in ulimit or limit command to report or set the limit. For example, in Bourne-compatible shells, ‘ulimit -n’ gives the current maximum fd plus 1.

It is permitted to call close on stdin, stdout, and stderr.

You can also call close on a fd f that is not open at the SETL level but is open at the POSIX level, e.g. as inherited by the process, or as arising from a call to one of the low-level functions dup, dup2, socketpair, pipe, or recv_fd. This just calls POSIX close() on the fd.

Closing a stream of type "signal", "ignore", "default" (see Signal streams), or "real-ms" (see Timer streams) can change the disposition of a signal. The fd is a pseudo-fd for these stream cases, outside the range of valid POSIX file descriptors.

As a trivial and dubious convenience, close(om) is a no-op.

The how argument to close, if present, must be one of the constants close_await (default), close_autoreap, or close_zombie. This second argument is meaningful for pipe, pump, and tty-pump streams (when the stream is the original one created by the caller, not one obtained from a duplicated fd), as follows:

• If how is close_await, then close effectively does a waitpid on the child process ID, passing a waitflag of true. This causes close to block until the child process terminates. The termination status is then available in status, except in the unusual case that the status has already been reaped, e.g. by an explicit and probably misdirected waitpid before the close. In that case, close sets status to om.
• If how is close_autoreap, then close does not block the program in a wait for the child process to terminate, but reaps and discards the status in the background if it does so.
• If how is close_zombie, then close does not block the program in a wait, nor does it reap the termination status in the background. If the child process terminates before the parent, it will become a zombie (as defined by POSIX) until a waitpid (or equivalent) successfully reaps its status. You can open a SIGCHLD signal stream to get notified of child terminations.

Failure of the POSIX-level close() causes last_error to be set. In the case of how = close_await on a pipe, pump, or tty-pump stream, the POSIX waitpid() call after that can also set last_error, in the circumstances that set status to om described above.

When a Unix-domain server socket (open mode "unix-server" or "unix-datagram-server") is closed, its associated pathname is removed if it still exists.

Streams that were automatically opened are automatically closed when appropriate. See Automatic opening.

All streams are automatically flushed and drained, and then all closed, before the program exits. See Buffering.

See shutdown about shutting down one or both directions of a bidirectional communications stream without closing the stream itself.

close_await, close_autoreap, close_zombie  -  constants for use with close

close_await : integer
close_autoreap : integer
close_zombie : integer

See close.

command_line  -  command-line arguments

command_line : tuple

This is a tuple of strings giving the command-line arguments that were passed to the SETL program when it was launched.

See also command_name.

command_name  -  command name

command_name : string

This is an implementation-defined name for the SETL program.

For GNU SETL, if the SETL program comes from an file or command, command_name is the name of that file, or the command string, including the leading vertical bar in the case of a command. Otherwise (i.e., when the program is read from a file descriptor, from standard input, or from the command-line argument itself), command_name is the name of the language processor command, normally setl.

For example, in POSIX, if this script is stored in the text file /tmp/help and made executable, it should print ‘I'm /tmp/help’ and a newline when invoked:

#! /usr/bin/env setl
print ("I'm", command_name);  -- like shell’s $0 or C’s argv[0]

Note the use of the ‘#!’ escape (see #! invocation in the GNU SETL User Guide).

See also command_line.

cos  -  cosine

op cos (real) : real
op cos (integer) : real

The operand is in radians. See also acos.

cosh  -  hyperbolic cosine

op cosh (real) : real
op cosh (integer) : real

Hyperbolic cosine. Popular with catenarians.

date  -  date and time of day

proc date : string

Equivalent to fdate (tod, "%c").

See also clock and time.

denotype  -  type of denotation in string

op denotype (string s) : string

If s contains a denotation that would be acceptable to unstr, then denotype s = type unstr s, but if s is some other string, then the advantage of checking it with denotype first is that denotype returns om instead of taking exception to it as unstr would.

See also val and str.

div  -  integer division

op div (integer, integer) : integer

SETL’s div operator truncates fractional results towards zero.

It is an error for the second operand (denominator) to be zero.

See also slash (/), and for remainders see mod and rem.

domain  -  domain of map

op domain (set) : set

The operand must be a set of ordered pairs, that is, a set of 2-tuples in which no element is om. The result is the set of all first members of those pairs.

See also range and lessf.

dup, dup2  -  duplicate a file descriptor

op dup (integer fd) : integer
op dup2 (integer fd1, integer fd2) : integer

These are direct interfaces to POSIX dup() and dup2(), useful when you want low-level control over system-level file descriptors, e.g. to play games with socketpair (or pipe) and fork and exec.

The new fd produced by dup or dup2 is not automatically open at the SETL level, though you can use open or one of the auto-opening intrinsics on it subsequently (see Automatic opening).

In dup2, there is an implicit POSIX close() of fd2 before the duplication of fd1 occurs. If fd2 is already open at the SETL level, any buffer structure it has remains intact (see Buffering). Thus if fd2 has an output buffer, it is usually best to flush it if necessary before the dup2 call, so that the redirection to a new sink (fd1) only applies to new output. This is similar to the case of a buffered fd across a fork.

Example:

dup2 (stdout, stderr)

redirects stderr to wherever stdout points, like the shell notation ‘2>&1’.

On failure, dup and dup2 set last_error and return om.

eof  -  end-of-file indicators

proc eof : boolean
proc eof (stream) : boolean

When a stream input operation fails to get any input, two eof indicators are set: a global one and a stream-specific one, accessed respectively by the nullary and unary forms of this intrinsic.

The eof indicators are cleared by sequential input intrinsics (and by recv_fd and gets) before they attempt input, and are only set when no input at all is received. Thus a getb that asks for 3 values but only gets 2 does not set the eof indicators, even though an end of file on the underlying medium has been reached. The stream’s eof indicator is pending in that case, meaning that a subsequent input attempt on that stream will get nothing and will set the eof indicators. The setting will happen even if the attempt is for no input, such as for 0 values in the case of getb, 0 characters in the case of getn or gets, or 0 lines in the case of geta.

A vacuous input attempt like that is thus a way to convert a pending eof to a true result from the eof intrinsic, making it no longer pending. I haven’t worked out whether that use case is plausible or more likely symptomatic. I have not wanted it yet.

A vacuous input attempt on a stream for which eof is not pending is an unconditional way of clearing the eof indicators. Again, this is not something I have felt moved to do in practice.

Besides ordinary end-of-file conditions such as reaching the end of a medium, the eof indicators may also be set by input errors. These can be distinguished from normal end of file using last_error. A stream may have a pending setting of last_error when it has a pending eof; the actual setting occurs when the eof indicators are set.

Setting the eof indicators also triggers auto-closing when appropriate (see Automatic opening). Note that closing a stream invalidates the unary form of eof for that stream, as it has been destroyed by then, while the nullary form remains valid.

For some input sources, an eof indication of true does not necessarily mean that further attempts to read from that source will fail. For example, when the stream is connected to a terminal with the normal cooked line discipline settings, a ctrl-D instead of an input line typically makes getline yield om and eof yield true, but another getline after that will yield another string if another line is then entered at the terminal.

See get, geta, getb, getc, getchar, getfile, getline, getn, gets, peekc, peekchar, read, reada, and recv_fd; but do not see recv, recvfrom, seek, sys_read, nor ungetc, as they never set eof.

even  -  test for integer divisible by 2

op even (integer) : boolean

Divisible by 2. Not odd. See also mod.

Note that the precedence of this operator is quite low, like that of other unary predicates, and well below that of unary non-predicates (see Operator Precedence). Its relative precedence was higher in the original CIMS SETL.

exec  -  execute another program in place of current one

proc exec (string file)
proc exec (string file, tuple argv)
proc exec (string file, tuple argv, tuple envp)

This is a low-level interface to POSIX execvp() or execve() depending on whether the envp argument is supplied.

If envp is present, execve() is used, which requires that file be a full pathname identifying a command.

If the envp argument is not given, then execvp() is used, so the PATH environment variable is searched for a directory containing an executable named file unless file contains a slash (/) character. The POSIX implementation defines what happens if PATH isn’t defined, but a default search of /bin and /usr/bin is common.

If the second argument (argv) appears, it must be a tuple of strings giving the arguments that will be supplied to the command, beginning with the 0^th  which conventionally is the name by which the command identifies itself. A missing argv defaults to the one-element tuple [file].

If envp is present, it must be a tuple of strings defining the environment variables to be seen by the command. Each string is of the form "name=value". Otherwise, the existing environment is inherited.

If exec is successful, it does not return; the current process is replaced in that its image in memory is replaced by that of the new command. The process ID does not change.

Signals that are being caught because of an open "signal" stream are set to their POSIX defaults in the new execution context. If any "real-ms" timer streams are open (which is not the case in a new child of fork), SIGALRM is also set to the POSIX default (SIG_DFL). Other signal dispositions are inherited as POSIX SIG_DFL or SIG_IGN as appropriate. See Signal streams.

Compare filter, system, and the open modes "pipe-from", "pipe-to", "pump", and "tty-pump", all of which use /bin/sh to invoke a shell command. One of those may be able to achieve what you want more cleanly and directly than exec does.

If you want your SETL program to set up an environment and then replace itself with a shell command, this would do the latter:

exec ("/bin/sh", ["sh", "-c", "command and args"]);

See also pipe_from_child, pipe_to_child, pump, and tty_pump for some ways beyond fork to create a child process suitable for calling exec in.

exp  -  natural exponential (e raised to a power)

op exp (real) : real
op exp (integer) : real

See also log and the general exponentiation operator (**).

false  -  predefined boolean value

false : boolean

A starting point from which all conclusions are possible.

See also true.

fdate  -  format date and time

proc fdate (integer ms, string fmt) : string
proc fdate (integer ms) : string

The ms argument represents some number of milliseconds since 1 January 1970 UTC, to be formatted as a date and time according to fmt, which defaults to "%a %b %e %H:%M:%S.%s %Z %Y". For example, fdate (936433255888) might be ‘Sat Sep  4 04:20:55.888 EDT 1999’ if invoked in the POSIX locale in the US Eastern time zone, and fdate (tod) renders the current calendar time.

The %-sign patterns in fmt are those defined for POSIX strftime() when applied to the result of applying POSIX localtime() to ms div 1000, together with one extension: "%s" expands to the low-order 3 decimal digits of ms. (Note: this meaning of "%s" differs from a GNU extension to strftime(), where it means the number of seconds since the beginning of 1970, a number that can be obtained in SETL as tod div 1000.)

See also date, which is equivalent to fdate (tod, "%c").

fexists  -  test for existence of file

op fexists (string) : boolean

Returns true iff POSIX stat() returns 0 on the given pathname.

Note that stat() does follow symbolic links, so fexists will only return true if an existing file is found after following all links (and provided the caller has sufficient access to all pathname components in reaching it).

Thus fexists is stricter than lexists, which uses POSIX lstat(). Both provide mere snapshots, not automatically synchronized with actions by other processes. See link and symlink for some ways to use files as mutual exclusion (mutex) locks.

See also fsize, readlink, and unlink.

Note the low precedence of this operator relative to unary non-predicates (see Operator Precedence). This differs from its precedence rank in SETL2.

filename  -  name of stream

op filename (stream) : integer
op filename (stream) : string
op filename (stream) : [integer, integer]
op filename (stream) : [string, string]

This is some form of the “name” under which the given stream was opened, as follows.

For an ordinary file, it is the string name passed to open or used to auto-open the file (see Automatic opening), or the name assigned by mkstemp.

For a Unix-domain socket, it is the pathname used at open time. See Unix-domain sockets.

Similarly, for a subprocess started by open mode "pipe-from", "pipe-to", "pump", or "tty-pump", it is the command string that launched that subprocess. See Connected subprocesses.

For a signal-catching, -ignoring, or -defaulting stream, the name is returned in the same case and spelling (i.e., with or without the SIG prefix) as was originally used to open the stream. See Signal streams.

For a "real-ms" stream, filename returns a pair of numbers [initial, interval], each representing milliseconds. See Timer streams.

For a TCP or UDP socket stream, it returns a pair [node, service], where node is a string host name or Internet address (IPv4 dotted or IPv6 colon-rich), or is om to signify an unspecified address (as is common for servers); and service is a string service name or port number, converted as if by str if the original spec was an integer. See TCP and UDP sockets.

Finally, for a stream created by accept, pipe_from_child, pipe_to_child, pump, or tty_pump, or a stream over a fd that was already open at the system (POSIX) level, the “name” is simply the integer fd.

It is an error to call filename on a fd that is not open at the SETL level, even though it may be open at the system level.

See also is_open, fileno, port, sockaddr, peer_sockaddr, peer_name, ip_names, and ip_addresses.

fileno  -  file descriptor of stream

op fileno (stream f) : integer

If f exists as a stream according to is_open, fileno returns its underlying POSIX file descriptor (fd) or, for a signal-related stream (see Signal streams) or timer stream (see Timer streams), its pseudo-fd.

It is an error to apply fileno to anything else. The fact that GNU SETL kindly stops everything and issues a diagnostic leads to the following non-portable idiom in programs that would rather crash immediately than continue with a bad result from open:

fd := fileno open (f, ...);

See also filename.

filepos  -  current file position or #bytes transferred

op filepos (stream f) : integer

Similar to seek (f, 0, seek_cur), but does not flush or drain the stream before giving its result. Thus while the result of seek always matches the OS-level file position, filepos takes into account any buffered output bytes that have not been written out yet at the system level and any buffered input that has not yet been consumed by the SETL program; it gives the offset that would obtain as if the flushing or draining had occurred.

Also, filepos is allowed even on non-seekable streams, where it returns the number of bytes that have been read and/or written since the stream was opened.

Finally (again in contrast to seek), filepos does not attempt to auto-open f, but requires that f already be open (see open).

filter  -  filter string through external command

proc filter (string cmd, string input) : string
proc filter (string cmd) : string

This feeds the string input into an external command and returns its output.

The cmd argument specifies a shell command, which is performed as if by exec ("/bin/sh", ["sh", "-c", cmd]) in a child process spawned as if by pump.

The command may read from its standard input and/or write to its standard output. The input arg (default "") is fed to the child’s standard input while the content of its standard output is being captured.

When all of input has been fed to the child, the end of the pipe that does the feeding is closed, causing an end of file condition to be presented to the child’s standard input.

Meanwhile, when an end of file condition is seen by the SETL program on the capturing end of the pipe, signifying that the child’s standard output has been closed, POSIX waitpid() is called in an attempt to get the child’s exit status, and the captured output is returned by filter.

Just as with system, the signals SIGINT and SIGQUIT are temporarily ignored in the parent while it waits for the child to complete. Thus a terminal-generated signal (typically ctrl-C for SIGINT and ctrl-\ for SIGQUIT) that goes to the process group will be seen by the child but not the parent, which remains to handle the child termination. Also as with system, SIGCHLD is not blocked during the filter call.

The termination status of the /bin/sh invocation is placed in status. By convention, 0 means a successful command execution. In the event that the final POSIX waitpid() call to get that status fails, status is set to om and the reason for the failure appears in last_error, just as in the similar scenario of close with the close_await parameter.

See also fork, pipe_from_child, pipe_to_child, tty_pump, socketpair, pipe, dup, and dup2; and the open modes "pipe-from", "pipe-to", "pump", and "tty-pump".

fix  -  truncate real number to integer

op fix (real) : integer
op fix (integer) : integer

Truncation of real operands is towards zero; integer operands are simply returned.

Example: fix -5.6 = -5.

Floating-point infinities and NaN (Not a Number) values give om.

See also ceil, floor, round, and float.

fixed  -  format number with optional decimal point

proc fixed (real x, integer wid, integer aft) : string
proc fixed (integer x, integer wid, integer aft) : string

The number float x is converted to a string of length abs wid or more, with aft digits after the decimal point.

If aft is zero, there is no decimal point, and you might as well use whole instead of fixed. Negative aft is an error.

If abs wid is larger than necessary, the string is padded with blanks on the left (for positive wid) or on the right (for negative wid).

If abs wid is too small, a longer string is produced as necessary to accommodate the number.

It is possible for the conversion to result in the string "nan", "inf", or "infinity", with or without a minus sign in front.

See also floating, str, and strad.

float  -  convert number to real

op float (integer) : real
op float (real) : real

If integers are unbounded, and reals are not, it is possible for this conversion to produce a floating-point infinity. On a 64-bit IEEE 754 implementation, this will happen for any integer of magnitude 2**1024 or more, a 309-digit integer in decimal.

Also, loss of precision can occur for integers too big to fit in the mantissa (significand) of a bounded floating-point representation. In the 64-bit IEEE 754 case, this means that integers of magnitude at most 2**53 will be reproduced with absolute fidelity by float. Beyond that, the gaps in coverage begin, starting with the odd numbers.

Applied to a real, float simply returns it.

See also fix, ceil, floor, and round.

floating  -  format number in scientific notation

proc floating (real x, integer wid, integer aft) : string
proc floating (integer x, integer wid, integer aft) : string

The number float x is converted to a string of length abs wid or more in scientific notation, with one digit before the decimal point, aft digits after it, and the string "e+dd" or "e-dd" after that, where the latter stands for “times 10 to the power of dd (or -dd)”, and dd has at least 2 digits.

If aft is zero, there is no decimal point; aft must not be negative.

If abs wid is larger than necessary, the string is padded with blanks on the left (for positive wid) or on the right (for negative wid).

If abs wid is too small, a longer string is produced as necessary to accommodate the number.

It is possible for the conversion to result in the string "nan", "inf", or "infinity", with or without a minus sign in front.

See also fixed, whole, str, and strad.

floor  -  floor (greatest integer lower bound)

op floor (real) : integer
op floor (integer) : integer

This operator returns the largest integer that is less than or equal to the given operand.

For example, floor -5.1 = -6.

Floating-point infinities and NaN (Not a Number) values give om.

See also ceil, round, fix, and float.

flush  -  flush output buffer

proc flush (stream)

All buffered output for the given stream is written out using POSIX write(), blocking the program if necessary until the entire buffer has been written.

If POSIX write() fails, last_error is set, and the number of bytes written is then indeterminate.

Applying flush to a stream with no pending output (which is always the case for a read-only or datagram stream) has no effect, not even on last_error.

For most use cases, flushing is done automatically when it needs to be. Some auto-flushing can also be arranged using tie. See Buffering.

See also open, close, and is_open.

fork  -  fork into parent and child process

proc fork : integer

This is an interface to POSIX fork() with accommodations for SETL.

In the parent process, fork returns an integer representing the process ID of the child.

In the child, fork returns 0.

All output buffers are flushed as if by flush before the spawning attempt, possibly causing some blocking. Output errors in the flushing are suppressed, and not reflected in last_error.

In the child, before fork returns, all unread input on signal streams is drained (discarded), all timer streams (open mode "real-ms") are closed (see Signal streams), and the time base for elapsed time (see clock) is reset to 0.

If the system cannot spawn a new process, fork sets last_error and returns om, in contrast to all other intrinsics, which consider spawning failures errors.

In many cases, simply using system, filter, pipe_from_child, pipe_to_child, pump, tty_pump, or one of the open modes "pipe-from", "pipe-to", "pump", or "tty-pump" will be easier than dancing with fork, exec, socketpair (or pipe), dup2, close, and waitpid.

See also getpid, pexists, and kill.

from  -  take arbitrary element from set

op from (wr var x, rw set s)

An element of the set s is chosen arbitrarily (but probably not randomly), removed from s, and assigned to x.

If s is empty, x := om instead.

Currently, from is a statement form, not actually an operator.

See also arb, fromb, frome, less, lessf, and the minus operator (-) as applied to sets.

fromb  -  take from beginning of string or tuple

op fromb (wr string x, rw string s)
op fromb (wr var x, rw tuple s)

The string or tuple s is stripped of its first element (a one-character string if s is a string), and that element is assigned to x.

If s is of length 0, x := om instead.

Currently, fromb is a statement form, not actually an operator.

See also from and frome.

frome  -  take from end of string or tuple

op frome (wr string x, rw string s)
op frome (wr var x, rw tuple s)

The string or tuple s is stripped of its last element (a one-character string if s is a string), and that element is assigned to x.

If s is of length 0, x := om instead.

Currently, frome is a statement form, not actually an operator.

See also from and fromb.

fsize  -  size of file in bytes

op fsize (stream f) : integer
op fsize (string pathname) : integer

If the operand is a stream, fsize returns the size of the thing that is open (see is_open). More precisely, it returns the value of the st_size field in the POSIX struct stat, which is only required to be meaningful for files, though particular implementations of POSIX fstat() may extend its meaning to other things.

If the operand is not a stream, POSIX stat() is tried on it to get a size, again from the st_size field.

Errors in fstat() or stat() cause fsize to set last_error and return om.

Like fexists, fsize gives just a snapshot, not automatically synchronized with updates by other processes.

See also open and ftrunc.

ftrunc  -  set size of file in bytes

op ftrunc (stream f, integer length)
op ftrunc (string pathname, integer length)

The file associated with the writable stream f or, if f is not a stream, the writable file named by pathname, is resized to the given length, truncating the file or extending it as necessary. When extended, it is padded with NUL characters (\0), possibly in a way that is optimized by the underlying file system.

For the stream case, f is first flushed as if by flush (but ignoring output errors) and drained. See Buffering.

The underlying POSIX call is then ftruncate() for f and truncate() for pathname. Errors are reflected in last_error.

See also open and fsize.

get  -  read lines from stdin

proc get (wr string args(*))

Equivalent to geta (stdin, args(*)).

This signature for get follows that of SETL2, while geta is patterned after the old CIMS SETL get. This makes the signatures of get and geta consistent with those of read and reada.

geta  -  read lines from stream

proc geta (stream f, wr string args(*))

Zero or more lines are read from the stream f and assigned to the succeeding args in order, as strings. If an end of input (end of file or error) is reached before all those arguments have been assigned to, trailing arguments are set to om. If it is reached before any have been assigned to, the eof indicators are set.

If f is not already open, an attempt is made to auto-open it, for reading or for bidirectional I/O depending on the form of f. See Automatic opening.

Lines are terminated by newline (\n), and there is no restriction on line length. The newline character is not delivered as part of each assigned string, and the final line before the end of input need not be terminated by a newline.

There is no distinction between “text” and “binary” files, nor any special processing of carriage return (\r).

The rules on auto-flushing f’s output associations, on setting last_error, and on auto-closing are as for getc.

The operator-form getline in place of geta may often be stylistically preferable.

See also open, get, getb, getn, gets, peekc, reada, puta, and printa.

getb  -  read values from stream

proc getb (stream f, wr var args(*))

Zero or more values are read from the stream f and assigned to the succeeding args in order. If an end of input (end of file or error) is reached before all those arguments have been assigned to, trailing arguments are set to om. If it is reached before any have been assigned to, the eof indicators are set.

If f is not already open, an attempt is made to auto-open it. See Automatic opening.

Values written by putb or writea, except for atoms (see newat) and procedure references (see routine), are readable by getb. Tokens denoting values are separated by whitespace (ERE "[ \f\n\r\t\v]+") and converted as if by unstr.

There is a difference between getb and reada in that after reading the requested number of values, reada continues reading characters until it either absorbs a newline (\n) or encounters an end of input, whereas getb stops right after the end of the last value read.

The rules on auto-flushing f’s output associations, on setting last_error, and on auto-closing are as for getc.

See also geta, getline, getfile, getn, and val.

getc  -  read character from stream

op getc (stream f) : string

One character is read from the stream f and returned as a string of length 1. If an end of input (end of file or error) is reached instead, getc sets the eof indicators and possibly last_error, and returns om.

If f is not already open, an attempt is made to auto-open it. See Automatic opening.

If eof is set by getc for an auto-opened sequential stream, the stream is auto-closed, leaving the nullary eof true and the unary eof(f) invalid.

The getc intrinsic, like all input intrinsics, automatically flushes any output buffered for f and for any stream associated with f by tie before attempting input. It does not set last_error on output failures in the flushing, but you can flush explicitly before the input operation if details on such failures are of interest.

See also getchar, getfile, getline, getn, gets, geta, getb, peekc, reada, ungetc, and putc.

getchar  -  read character from stdin

proc getchar : string

Equivalent to getc (stdin).

getegid  -  get effective group ID

proc getegid : integer

Returns the result of calling the POSIX getegid() function.

See also getgid, setegid, setgid, geteuid, getuid, seteuid, and setuid (details and example).

getenv  -  get value of environment variable

op getenv (string) : string

If the environment variable named by the operand exists, its value is returned; otherwise you get om.

See also setenv and unsetenv.

geteuid  -  get effective user ID

proc geteuid : integer

Returns the result of calling the POSIX geteuid() function.

See also getuid, seteuid, setuid (details and example), getegid, getgid, setegid, and setgid.

getfile  -  read stream up to the end

op getfile (stream f) : string

Zero or more characters are read from the stream f until an end of input (end of file or error) is reached, and returned as a string.

If f is not already open, an attempt is made to auto-open it. See Automatic opening. As usual, if the file was automatically opened, it is automatically closed on end of input.

The getfile intrinsic is unique in that if it fails on the auto-open attempt, it returns om rather than considering the failure erroneous. This helps to discourage racy code like

x := if fexists f then getfile f else "some default" end;

when

x := getfile f ? "some default";

is race-free and serves a common use case. The latter is more or less equivalent to

fd := open (f, "r");
if fd /= om then
  x := getfile fd;
  close (fd);
  fd := om;
else
  x := "some default";
end if;

The eof indicators are always set by getfile. This does not matter to users, but allows auto-closing to be defined as something that only happens upon the setting of the eof indicators, as is the case for all other input intrinsics. On the other hand, this makes getfile the only intrinsic that sets eof even when it succeeds in getting more than 0 input items.

The rules on auto-flushing f’s output associations, on setting last_error, and on auto-closing are as for getc.

See also getline, getn, gets, getb, and putfile.

getgid  -  get real group ID

proc getgid : integer

Returns the result of calling the POSIX getgid() function.

Note that group IDs have no relation to process group IDs (see getpgrp).

See also getegid, setgid, setegid, getuid, geteuid, setuid (details and example), and seteuid.

getline  -  read line from stream

op getline (stream f) : string

This is an operator-form alternative to geta for reading a single line.

Characters through the next newline (\n) if any are read from f and returned as a string, without the newline. Thus the trailing newline is optional on the last line of a file except when needed to signify an empty line there.

If no characters can be read, getline sets the eof indicators and returns om.

If the stream is not already open, an attempt is made to auto-open it. See Automatic opening.

The rules on auto-flushing f’s output associations, on setting last_error, and on auto-closing are as for getc.

If respectability isn’t your thing, the expression

[getline f : until eof]

is a convenient way to read all the lines of a file into a tuple. If f is the name of a file that was not previously open, this leaves the file closed after the tuple is accumulated, by the usual rules of auto-opening and auto-closing.

The above expression only works because the om coming from the final getline call in the loop is trimmed from the tuple.

See also open, close, putline, getfile, getb, getn, gets, reada, and printa.

getn  -  read fixed number of characters from stream

proc getn (stream f, integer n) : string

Up to n characters are read from the stream f and returned as a string. If an end of input (end of file or error) is reached before n characters have been read, a shorter string is returned. If it is reached before any characters have been read, the eof indicators are set and the empty string ("") is returned.

If f is not already open, an attempt is made to auto-open it. See Automatic opening.

The rules on auto-flushing f’s output associations, on setting last_error, and on auto-closing are as for getc.

See also getfile, getline, gets, and putc.

getpgrp  -  get process group ID

proc getpgrp : integer

Gets the process group ID of the calling process, or in other words the process ID of the process group leader.

See also setpgid, getpid, getppid, getsid, pexists, kill, and waitpid.

getpid  -  get process ID

proc getpid : integer

Gets the process ID, in the POSIX sense, of the calling process.

See also pid, getppid, getpgrp, getsid, pexists, kill, and waitpid.

getppid  -  get parent process ID

proc getppid : integer

Gets the process ID of the parent of the calling process.

See also getpid.

gets  -  direct-access read

proc gets (stream f, integer start, integer n, wr string x)

The file under the readable, seekable stream f (open mode "r", "r+", "w+", "n+", or "a+") is viewed as a string, where start specifies the index (1 or higher) of the first character to read.

The gets intrinsic reads up to n characters and returns them as a string through the x arg. If an end of input (end of file or error) is reached before n characters have been read, a shorter string is returned. If it is reached before any characters have been read, the eof indicators are set and the empty string ("") is returned.

If f is not already open, an attempt is made to auto-open it in "r+" mode, which allows seeking, reading, and writing. See Automatic opening.

If f was auto-opened in "r" (not "r+") mode, it will be auto-closed when gets sets eof.

As with seek, f is flushed of output (ignoring errors) and drained of input before the file is repositioned. See Buffering.

See also getfile, getn, puts, seek, and mkstemp.

getsid  -  get session ID

proc getsid : integer
proc getsid (integer p) : integer

Gets the POSIX session ID for process ID p, which is to say the process group ID of p’s session leader. If p is 0 or omitted, the session ID of the calling process is returned.

On error, getsid sets last_error and returns om.

Sessions are used in job control—see setsid.

getuid  -  get real user ID

proc getuid : integer

Returns the result of calling the POSIX getuid() function.

See also geteuid, setuid (details and example), seteuid, getgid, getegid, setgid, and setegid.

getwd  -  current working directory

proc getwd : string

Current working directory of the process.

See also chdir.

glob  -  pathname wildcard expansion

op glob (string) : [string, ...]

Using the POSIX glob() function with no flags and no error callback, glob expands the pathname pattern given in the string operand to produce a tuple of strings. The empty tuple is produced if there is no match to an accessible filename.

For example, if the current directory contains 3 .h files, then

glob "*.h"

might equal the tuple

["bar.h", "foo.h", "mumble.h"]

See also getwd and chdir.

gmark  -  find all occurrences of pattern in string

proc gmark (string s, pattern p) : [[integer, integer], ...]

The locations of all non-overlapping occurrences of the pattern p in the string s are returned in left-to-right order as a tuple of pairs of integers [i, j], where each matched substring can be addressed as s(i..j). If p does not occur in s, the empty tuple is returned.

For example:

• gmark ("banana", "an") is [[2,3], [4,5]]
• gmark ("banana", "ana") is [[2,4]], not [[2,4], [4,6]]

The pattern p is subject to the setting of magic, and can be a string or a 2-tuple, as detailed under mark.

See also sub, gsub, and split.

gsub  -  replace patterns in string

proc gsub (rw string s, pattern p) : [string, ...]
proc gsub (rw string s, pattern p, string r) : [string, ...]

All non-overlapping occurrences in s of the pattern p are replaced by r, which defaults to the empty string (""). The substrings of s that were matched by p are returned as a tuple of strings in left-to-right order.

The pattern p is subject to the setting of magic, and can be a string or a 2-tuple, as detailed under mark.

When magic is true, ampersands and backslash-digit sequences in the replacement pattern r are expanded as in sub.

Example:

s := "abcd aabbccdd";
print (gsub (s, "a([bc]*)d", "&/<\\1>"));  -- prints [abcd abbccd]
print (s);  -- prints abcd/<bc> aabbccd/<bbcc>d

See also gmark and split.

hex  -  convert string to hexadecimal

op hex (string s) : string

Hexadecimal string representation of s. For example, hex "\011\xCf" = "09CF", and hex char 16#dB = "DB".

In general, #hex s = 2 * #s.

See also unhex.

hostaddr  -  current host address

proc hostaddr : string

This is some plausible Internet address for the current host system, defined as the first AF_INET or AF_INET6 address on the list returned by POSIX getaddrinfo() for the host name obtained by POSIX gethostname(), in dotted IPv4 or colon-delimited IPv6 notation.

If gethostname() or getaddrinfo() fails, hostaddr sets last_error and returns om.

If getaddrinfo() succeeds but yields no addresses in the family AF_INET or AF_INET6, the value of hostaddr is om but last_error is not set.

Uses for this function seem limited.

See also hostname, ip_addresses, and ip_names.

hostname  -  current host name

proc hostname : string

This is the “standard” name for the current host system as given by POSIX gethostname().

In the unlikely case that gethostname() fails, hostname sets last_error and returns om.

See also hostaddr, peer_name, ip_names, and ip_addresses.

ichar  -  integer code for character

op ichar (string) : integer

This operator interprets the one byte in the operand as an integer in the range 0 to 255. For example, ichar "\x20" = 32, the code for an ASCII blank.

See also char.

impl  -  implication

op impl (boolean, boolean) : boolean

Here is the truth table defining this operator:

true  impl true   =  true
true  impl false  =  false
false impl true   =  true
false impl false  =  true

This seldom-used operator could have been short-circuited like and, or, and the query operator (?), but isn’t. That is to say, both sides of impl are always evaluated.

This is no great loss, however, because it is usually more natural to write the short-circuiting expression

q or not p

or

(not p) or q

than the propositional

p impl q

especially in the context of if or while tests.

The impl operator has the lowest precedence of any operator (see Operator Precedence).

in  -  membership test; iterator form

op in (var x, set s) : boolean
op in (var x, tuple s) : boolean
op in (string x, string s) : boolean

The keyword in plays a dual role in SETL. Depending on context, it is either the boolean-valued membership test operator whose signature is given above, or the basis of a common iterator form that occurs in loop headers, quantifiers, and set and tuple formers.

Here are two examples of its use in iterators, where x acts like a bound variable in each iteration in that it is assigned successive members of a set or tuple s, or characters of a string s:

for x in s loop
  ...
end loop;

squares := {x*x : x in s};  -- set former

In its other role, as a binary operator,

x in s

it is a type-dependent membership test:

• For a set s, it tells whether x occurs in s; om is never considered to be a set member.
• For a tuple s, it likewise seeks an occurrence of x in s, perhaps searching linearly; om is considered present if the tuple has at least one hole, i.e., non-trailing om member.
• For a string s, it indicates whether x is a substring of s.

See also arb, from, and notin.

incs  -  subset test

op incs (set s, set ss) : boolean

Returns true when every member of ss is also in s. Thus

s incs ss

has the same truth value as

ss subset s

Its precedence is quite low, like that of other binary predicates. See Operator Precedence.

intslash  -  integer quotient type switch

intslash : boolean

By default, the result of dividing two integer values in SETL is real, as in Pascal and the Algol family. This default corresponds to intslash = false. See the discussion of the slash operator (/) for why it is best to leave it this way if possible.

See also set_intslash.

ip_addresses  -  internet host addresses

proc ip_addresses (string host) : {string, ...}

Returns a set of Internet addresses as strings in IPv4 dotted or IPv6 colon-separated notation, for the host name or Internet address host.

POSIX getaddrinfo() is used to obtain the addresses.

For example,

ip_addresses ("uccs.edu")

might produce the set

{"128.198.1.50", "128.198.1.71", "128.198.4.52"}

If getaddrinfo() fails, last_error is set and the empty set is returned. The empty set can be returned with no setting of last_error if getaddrinfo() succeeds but doesn’t find any addresses in the AF_INET or AF_INET6 family for the given host.

See also ip_names, hostaddr, hostname, peer_name, and peer_address.

ip_names  -  internet host names

proc ip_names (string host) : {string, ...}

Returns a set of Internet host names for the host name or IPv4/IPv6 address host.

It is like ip_addresses but with each address translated to a name using POSIX getnameinfo() if possible or omitted if not. For example,

ip_names ("uccs.edu")

might give the set

{"federation.uccs.edu", "klingon.uccs.edu", "warp.uccs.edu"}

and

ip_names ("::1")

might be

{"ip6-localhost"}

Failure of POSIX getaddrinfo() is treated the same as by ip_addresses, including the setting of last_error. Failure of getnameinfo() on an address found by getaddrinfo() is not reflected in last_error, but leaves a name out of the return set.

See also hostname and peer_name.

is_type  -  type testers

op is_atom (var) : boolean
op is_boolean (var) : boolean
op is_integer (var) : boolean
op is_map (var) : boolean
op is_mmap (var) : boolean
op is_numeric (var) : boolean
op is_om (var) : boolean
op is_real (var) : boolean
op is_routine (var) : boolean
op is_set (var) : boolean
op is_smap (var) : boolean
op is_string (var) : boolean
op is_tuple (var) : boolean

The operator is_map (or equivalently is_mmap, for multi-valued map) returns true if its operand is a set consisting entirely of ordered pairs (tuples of length 2), none of which has om as its first member.

The operator is_smap (single-valued map) adds the further condition that for a map f, #domain f = #f; that is, that f takes each domain element to one range element.

The operator is_atom tests for a value created by newat, and is_routine tests for a value created by routine.

See also type and denotype.

The type-testing operators have rather low precedence, like other unary predicates (see Operator Precedence).

is_open  -  test for being a stream

op is_open (stream f) : boolean

Tests whether f is one of the pre-opened streams stdin, stdout, or stderr; a stream returned by open, accept, pipe_from_child, pipe_to_child, pump, tty_pump, or mkstemp; or an automatically opened stream (see Automatic opening).

Being a stream is the same as being open at the SETL level; a stream ceases to exist when it is closed.

Although SETL provides no intrinsic specifically for testing whether a given plausible file descriptor fd is open at the underlying POSIX level (an uncommon use case), dup2(fd,fd) returns fd if it is, or sets last_error and returns om otherwise.

See also close.

Being a predicate, is_open has rather low precedence (see Operator Precedence).

join  -  concatenate tuple of strings, with delimiter

proc join (tuple t, string glue) : string

All elements of the tuple t must be strings, and they are concatenated together, separated by the delimiter string glue.

In general,

join (t, glue) = ("" +/ [glue+s : s in t])(#glue+1..)

Thus if t is the empty tuple ([]), the result is the empty string (""). Note that glue is not used when the number of elements #t is 0 or 1, but must still be a string.

See also split.

kill  -  send signal to process

proc kill (integer p)
proc kill (integer p, integer signal)
proc kill (integer p, string signal)

Calls POSIX kill(). Among processes that the caller of kill has permission to send a signal to, p is interpreted as follows.

If p is greater than 0, the signal is sent to the process with a process ID equal to p.

If p is 0, the signal is sent to every process whose process group ID is equal to that of the caller.

If p is negative and not equal to -1, then -p is a process group ID, and the signal is sent to every process in that group.

If p is -1, the signal is sent to every allowed process except for an unspecified set of system processes. The signal may or may not be sent to the calling process. POSIX doesn’t address this, but Linux excludes the caller in the -1 case.

If p indicates a nonexistent process or process group, the call has no effect except upon last_error.

If signal is omitted, it defaults to "TERM", or equivalently "SIGTERM". Signals may be given as integers or more portably as strings. Case is not significant. The signal names HUP, INT, QUIT, ILL, ABRT, FPE, KILL, SEGV, PIPE, ALRM, TERM, USR1, USR2, CHLD, CONT, STOP, TSTP, TTIN, and TTOU are defined by POSIX. A few other common signals such as PWR and WINCH may also be defined.

As a special case, if signal is 0, no signal is sent, but the validity of p is checked and the result is reflected in last_error.

See also pid, pexists, getpgrp, fork, pipe_from_child, pipe_to_child, pump, tty_pump, system, filter, and the open modes "pipe-from", "pipe-to", "pump" and "tty-pump".

last_error  -  last error message from system function

last_error : string

After a clear_error call, last_error has the value no_error, and is referred to as not set. Otherwise, it has the most recent setting by an intrinsic documented as being able to set last_error.

More precisely, if an intrinsic does set it, it is to

• the error message returned by POSIX strerror() for the most recent setting of POSIX errno, or
• the error message returned by POSIX gai_strerror() for the most recent failed POSIX getaddrinfo() or getnameinfo() call.

len  -  extract leading substring by length

proc len (rw string s, integer n) : string

An initial substring of length n min #s is removed from s and returned. It is an error for n to be less than 0.

See also the other SNOBOL-inspired intrinsics, namely any, break, match, notany, span, rany, rbreak, rlen, rmatch, rnotany, and rspan.

less  -  set less given element

op less (set s, var x) : set

Definition: s less x = s - {x}.

See the set difference (minus) operator (-), and also from, lessf, and with.

lessf  -  map less given domain element

op lessf (set s, var x) : set

The set s must be a map. The lessf operator returns a copy of the map in which all pairs having x as a first (i.e., domain) element are removed.

See also less and from.

lexists  -  test for existence of file or symlink

op lexists (string) : boolean

Returns true iff POSIX lstat() returns 0 on the given pathname.

Note that lstat() does not follow symbolic links, so lexists returns true for any existing pathname (provided the caller has sufficient access to all pathname components in reaching it), even a dangling symlink (one that refers to a file that doesn’t exist).

Thus lexists is less strict than fexists, which uses POSIX stat(). Both provide mere snapshots, not automatically synchronized with actions by other processes. See link and symlink for some ways to use files as mutual exclusion (mutex) locks.

See also readlink and unlink.

Like fexists, this predicate has rather low precedence (see Operator Precedence).

link  -  create hard link

proc link (string f, string new)

Creates a link (hard link) new to the existing file f using POSIX link(), if new does not exist before the call.

If link succeeds, new and f then refer to the same file. Otherwise, such as when new already exists, last_error is set.

Given stable directory structures above f and new, link behaves atomically, and can be used as a test-and-set mechanism for inter-process synchronization: the mutex (lock file) new is acquired if and when link succeeds, and releasing it is done atomically by unlink.

See also fexists, symlink, and rename, and the open modes "n" and "n+".

log  -  natural logarithm

op log (real) : real
op log (integer) : real

The operand must be greater than 0.

See also exp.

lpad  -  pad string on left with blanks

proc lpad (string s, integer n) : string

If n > #s, the returned string is s padded on the left with blanks to length n. Otherwise, s is returned.

It is an error for n to be less than 0.

See also rpad, which left-justifies by padding on the right.

magic  -  regular expression recognition switch

magic : boolean

This is a global modal switch.

By default, magic is true, meaning that subscripting and slicing of subject strings like say s by pattern strings p, p1, and p2 in expressions like s(p) and s(p1..p2) interprets the pattern strings as POSIX extended regular expressions (EREs). This also affects sub, gsub, mark, gmark, and split.

You can assign magic := false, or call set_magic (false), to cause pattern strings to be interpreted literally, i.e., as strings to be matched exactly somewhere in s.

mark  -  find first occurrence of pattern in string

proc mark (string s, pattern p) : [integer, integer]

The location of the first (leftmost) occurrence of the pattern p in the string s is returned as a pair of integers [i, j] which index the first and last characters in the substring matched by p, i.e., s(i..j).

If there is no such occurrence, om is returned.

With magic left at its default setting of true, a string-valued p is interpreted as a POSIX extended regular expression (ERE).

If magic is false, a string-valued p is interpreted literally as the substring of s to match.

If p is a pair [p1, p2] of strings, it represents a pattern that begins with p1 and ends with the first subsequent occurrence of p2. The setting of magic applies to each of p1 and p2. There can be any characters between p1 and p2, regardless of magic—sort of like the ERE ".*", but not so greedy.

As with the SETL expression s(p1..p2), the substring of s matched by a pattern pair begins with the first character of the first substring matching p1 and ends with the last character of the first substring matching p2 after that.

Also in line with SETL s(p1..p2) expressions, either or both of p1 and p2 may be an integer index rather than a pattern-bearing string, again irrespective of magic. If p1 is an integer, it simply becomes the i in the returned [i, j]. If p2 is an integer, j is the greater of p2 and i-1.

Like in string subscripting expressions, p can be an integer, in which case mark returns [p, p] if p <= #s, or [p, p-1] otherwise.

See also gmark, sub, and gsub.

match  -  extract leading substring by exact match

proc match (rw string s, string p) : string

If p is an initial substring of s, i.e., if s(1..#p) = p, it is removed from s and returned. Otherwise, nothing happens to s and the empty string ("") is returned.

See also the other SNOBOL-inspired intrinsics, namely any, break, len, notany, span, rany, rbreak, rlen, rmatch, rnotany, and rspan.

max  -  maximum

op max (integer, integer) : integer
op max (real, real) : real
op max (integer, real) : integer
op max (integer, real) : real
op max (real, integer) : integer
op max (real, integer) : real
op max (string, string) : string
op max (tuple, tuple) : tuple

Strings are compared character by character, as if using the codes arising from ichar. Tuple comparisons are element by element, and recursive. If one string or tuple is a prefix of the other, the longer one is considered larger.

For mixed numeric modes, the integer is converted to real before comparison, but the result has the type of the larger, or of the first operand in case of a tie.

If either operand is a floating-point NaN (Not a Number), the result is a NaN. Contrast POSIX fmax(), which returns the non-NaN arg when there is just one.

Examples:

1 max 2 = 2  -- max is a binary operator
max/ [1, 2, 3] = 3  -- max/ t gives max over set or tuple t
x max/ [] = x  -- but unary max/ [] is erroneous

See also the order-based comparatives, and min.

min  -  minimum

op min (integer, integer) : integer
op min (real, real) : real
op min (integer, real) : integer
op min (integer, real) : real
op min (real, integer) : integer
op min (real, integer) : real
op min (string, string) : string
op min (tuple, tuple) : tuple

Strings are compared character by character, as if using the codes arising from ichar. Tuple comparisons are element by element, and recursive. If one string or tuple is a prefix of the other, the shorter one is considered smaller.

For mixed numeric modes, the integer is converted to real before comparison, but the result has the type of the smaller, or of the first operand in case of a tie.

If either operand is a floating-point NaN (Not a Number), the result is a NaN. Contrast POSIX fmin(), which returns the non-NaN arg when there is just one.

This operator is commonly used in the combining form, min/, over a set or tuple. See max examples.

mkstemp  -  create and open temporary file

proc mkstemp (rw string template) : integer

The template must end in the characters "XXXXXX", which will be overwritten by characters that make the resulting string contain the name of a file that does not currently exist.

Then a file with that name is created with read/write permissions for the owner and none for others, using POSIX mkstemp(). A SETL open in "w+" mode is effectively performed over that, and the resulting file descriptor is returned.

On failure, last_error is set and om is returned. The template is not modified in that case.

The funky signature, with its read/write template arg, resembles that of the underlying POSIX function.

See also seek, rewind, puts, gets, and filename.

mod  -  integer modulus; symmetric set difference

op mod (integer, integer) : integer
op mod (set, set) : set

SETL yields a non-negative remainder as the result of mod, following the usual mathematical clock arithmetic definition. The sign of the denominator is immaterial, so:

 5 mod  3 = 2
-5 mod  3 = 1
 5 mod -3 = 2
-5 mod -3 = 1

See also rem and div.

The set-theoretic symmetric difference operator mod is analogous to the logical exclusive or, and is likewise associative and commutative (unlike mod over integers, which is neither). Two sets s and t can be swapped without an intermediate temporary variable thus:

s mod:= t;  -- add the info in t to s
t mod:= s;  -- take out the t, leaving old s
s mod:= t;  -- take out the old s, leaving old t

See also the regular set difference (minus) operator (-).

nargs  -  number of arguments given by caller

nargs : integer

For procedures that take a variable number of arguments (i.e., have the token sequence (*) after the final formal parameter, which the procedure sees as a tuple), nargs is the total number of arguments supplied by the caller to the currently active procedure.

newat  -  create new atom

proc newat : atom

This creates a unique atom, whose salient property is merely that it is different from all other atoms created by the current process. Atoms are like opaque pointers, and cannot be meaningfully exchanged between programs. They are sometimes used to highlight the domain independence of an abstract algorithm, but are otherwise rather useless. Real applications tend to be expressed over concrete domains with fitting rules and conventions.

See also is_atom.

no_error  -  non-error message

no_error : string

This is the value of last_error immediately after a call to clear_error. It is typically some locale-dependent version of "No error" or "Success".

not  -  logical negation

op not (boolean) : boolean

The unary predicate not has a precedence above and, or, and impl, but below that of all the other binary operators and non-predicates. See Operator Precedence. Still, generous use of parentheses is recommended for readability and for ease of transliteration to other languages.

See also the bitwise operators such as bit_not.

notany  -  extract leading character using character set

proc notany (rw string s, string p) : string

If the first character of s does not occur in p (treating p as a set of characters), that first character is removed from s and returned. Otherwise, nothing happens to s, and the empty string ("") is returned.

See also the other SNOBOL-inspired intrinsics, namely any, break, len, match, span, rany, rbreak, rlen, rmatch, rnotany, and rspan.

notin  -  membership test

op notin (var x, set s) : boolean
op notin (var x, tuple s) : boolean
op notin (string x, string s) : boolean

Definition: (x notin s) = not (x in s).

npow  -  all subsets of a given size

op npow (integer n, set s) : set
op npow (set s, integer n) : set

Definition: s npow n = n npow s = {ss in pow s | #ss = n}.

This is the set of all subsets of s that have n members, or the empty set if n exceeds #s. It is an error for n to be negative.

nprint  -  print to stdout with no trailing newline

proc nprint (var args(*))

Equivalent to nprinta (stdout, args(*)).

See also print and write.

nprinta  -  print to stream with no trailing newline

proc nprinta (stream f, var args(*))

The 0 or more args are written in sequence to the stream f, separated by single spaces. String arguments are written directly; all others are converted as if by str first.

If f is not already open, an attempt is made to auto-open it. See Automatic opening.

Note that the output of the program

nprinta (stderr, 1, 2);

is ‘1 2’, which is not the same as the output of the program

nprinta (stderr, 1);
nprinta (stderr, 2);

which is ‘12’.

On output error, output may be incomplete and last_error may be set.

See also nprint, printa, and writea.

odd  -  test for integer not divisible by 2

op odd (integer) : boolean

Not even, though it shares the rather low precedence of that predicate.

om  -  the undefined value

om

This is the default value of all uninitialized SETL variables, undefined set, range, or tuple elements, the implicit return value of all routines that do not return anything else, and the default result of many operations when they fail in ways that are not held to be errors.

Ideal if nothing is what you want. Sounds nice when said slowly. Depicted as a capital omega in the ancient texts. Could stand for omitted in some places.

See also is_om, type, denotype, str, and unstr.

open  -  open a stream

proc open (stream f, string how) : integer

Tries to create a stream for f, where f may be

• a string such as a filename, other pathname, command, or signal name,
• a tuple representing an interval timer or Internet service location, or
• an integer fd that is already open at the POSIX (operating system) level but not at the SETL level (see below).

How f is interpreted depends on the mode argument, how. See Arguments to open.

On success, the returned fd (or pseudo-fd, for a signal or timer stream) serves as a stream handle for use in SETL I/O. The fd is then “open at the SETL level”. The stream incorporates relevant state and buffer structure. See Buffering.

On failure due to external factors such as a missing file, open sets last_error and returns om.

The open described here is almost upwardly compatible with the old CIMS SETL open. It is completely compatible for programs which ignored the return value, because all I/O intrinsics in the present SETL accept as a stream specifier either the argument that was originally passed to a successful open call (if the arg is unique) or the file descriptor (fd) that was returned by it. This open is also compatible with SETL2 in that the fd serves as a unique handle.

fd := open ([om, 0], "tcp-server")