C. Built-in Functions
Refal-5 includes a library of standard built-in functions.
These include I/O and arithmetic operations, various system jobs
which cannot be defined in Refal, and some simple procedures which
are built into the system for greater efficiency.
If need be, a function name used for a built-in function can be
reassigned to denote a function defined in Refal.
The built-in function will then be inaccessible.
1. I/O Functions
<Card>
returns (is replaced by) the next line from the input.
Normally it is from the terminal, but input can be redirected
as allowed by MS-DOS. The returned expression
is a sequence of character-symbols (possibly empty). The End-Of-Line byte
is not included. If the input is read from a file,
the macrodigit 0 is returned when the end of file is reached
(no more lines). This is used in programs as
the indicator of end, since a macrodigit cannot result from input otherwise.
When reading from the terminal, enter Control-Z to produce the same
effect.
<Print e.Expr>
prints the expression e.Expr
on the current output and returns (is replaced by) e.Expr
.
<Prout e.Expr>
prints the expression e.Expr
on the current output and returns the empty expression.
Functions that work with files require a file descriptor as
an argument. A file descriptor is a macrodigit
in the range 1-19; in some operations the descriptor 0
is allowed and refers to the terminal.
<Open s.Mode s.D e.File-name>
opens file e.File-name
and associates it with the file descriptor s.D
.
s.Mode
is one of: 'w','W'
(open for writing),
or 'r','R'
(open for reading). e.File-name
may be
empty; Open
will then try to open file REFALdescr.DAT
,
where descr is the decimal representation of s.D
.
If the mode is reading and this file does not exist,
an error occurs. If the mode is writing, this file is created.
<Get s.D>
where s.D
is a file descriptor or ,
is similar to <Card>
except that it gets its input from
the file associated with s.D
.
If no file has been opened for reading with that file descriptor,
Get
will try to open file REFALdescr.DAT
,
where descr is the decimal representation of s.D
.
If it fails, an error occurs and the program is terminated.
If s.D
is , Get
will read from the terminal.
<Put s.D e.Expr>
where s.D
is a file descriptor or ,
writes e.Expr
on the file associated with s.D
and
returns Expr
(similar to Print
). If
no file has been opened for writing with that file descriptor,
Put
will open file REFALdescr.DAT
,
where descr is the decimal representation of s.D
.
If s.D
is , Put
prints out on the terminal.
(Note that this output is not redirectable.)
<Putout s.D e.Expr>
returns empty (like Prout
).
In all other respects Putout
is identical to Put
.
2. Arithmetic Functions
Representation of numbers. Whole numbers
are represented as sequences of macrodigits using the base 232
. Negative whole numbers are preceded by the character
'-'
. Positive numbers may be preceded by '+'
.
Arithmetic functions
return whole numbers in the standard form: '-'
and a sequence of
macrodigits for a negative number;
no '+'
for 0 or a positive number.
Real numbers (of either sign) are represented as single symbols
and take a 32-bit word. (For the syntax of real numbers see
Reference Section B.)
The basic format of binary arithmetic operations is:
<ar-function (e.N1) e.N2>
However, the parentheses can be dropped. This is no problem with
real numbers, since each of those takes exactly one symbol.
When the first argument is a whole number, it will be assumed to take one
macrodigit possibly preceded by a sign, while the rest goes to
the second argument.
If both arguments of an arithmetic function are whole numbers,
the result is also a whole number; otherwise it is a real number.
The following functions ar-function are implemented:
Add
or +
returns the sum of the operands.
Sub
or -
subtracts e.N2
from e.N1
and returns
the difference.
Mul
or *
returns the product of the operands.
Div
or /
if at least one argument is real, returns the
real quotient. If both are whole, Div
returns the whole quotient of e.N1
and e.N2
;
the remainder is ignored. With this and the other two division
functions, if e.N2
is 0, an error occurs.
Divmod
expects whole arguments and returns
(e.Quotient) e.Remainder
The remainder is of the sign of e.N1
.
Mod
expects whole arguments and
returns the remainder of the division of e.N1
by e.N2
.
Compare
compares the two numbers and returns '-'
if e.N1
is less than e.N2
, '+'
if it is greater,
and '0'
if they are equal.
<Trunc eN>
where eN
is a real number,
returns the truncated whole number.
<Real eN>
where eN
is a whole number,
returns the equal real number.
<Realfun (e.Function) sN>
or
<Realfun (e.Function) s.N1 s.N2>
returns the value of the
function e.Function
of one or two arguments.
e.Function
must be a string of characters
naming a function available in the language C.
For instance, <Realfun ('log') sN>
returns the logarithm of
sN
. (For the list of available functions, see information
on the system diskette.)
3. Stack Operations
<Br e.Name'=' e.Expr>
buries (see Chapter 4) the
expression e.Name
under the name e.Name
.
The name must not contain '='
on the top level of structure.
<Dg e.Name>
digs the expression buried under the
name e.Name
, i.e., returns the last expression buried under
this name and removes it from the stack. If there is no expression
buried under e.Name
, Dg
returns the empty expression.
<Cp e.Name>
works as Dg
but does not remove the expression
from the stack.
<Rp e.Name'=' e.Expr>
replaces the expression buried under
the name e.Name
by e.Expr
.
<Dgall>
digs out the whole stack. The stack
is a string of terms of the form
(e.Name'=' e.Value)
Each time Br
is activated, such a term is added on the left
side. Dg
takes the leftmost term away, while Cp
copies it, and Rp
changes it.
4. Symbol and String Manipulation
<Type e.Expr>
returns s.Type e.Expr
, where e.Expr
is unchanged and s.Type
depends on the type of the first element
of e.Expr
.
s.Type e.Expr starts with
'L' letter
'D' digit
'F' identifier or function name
'N' macrodigit
'R' real number
'O' any other symbol
'B' left parenthesis
'*' e.Expr is empty
<Numb e.Digit-string>
returns the macrodigit
represented by e.Digit-string
.
<Symb s.Macrodigit>
is the inverse of Numb
.
It returns the string of decimal digits representing s.Macrodigit
.
<Implode e.Expr>
takes the initial alphanumeric characters
of e.Expr
and creates an identifier (symbolic name)
from them.
The initial string in e.Expr
must begin with a letter and terminate
with a non-alphanumeric character, parenthesis,
or the end of the expression. The string must not exceed
15 characters. Underscore and dash are also permitted.
Implode
returns the identifier followed by the unimploded portion
of e.Expr
. If the first character is not a letter, Implode
returns the macrodigit 0 followed by the argument.
<Explode s.Identifier>
returns the string of character-symbols
which make up s.Idenitifier
.
<Chr e.Expr>
replaces every macrodigit in e.Expr
by the character-symbol with the same ASCII code modulo 256.
<Ord e.Expr>
is the inverse of Char
.
It returns the expression in which all characters are replaced
by macrodigits equal to their ASCII codes.
<First s.N e.Expr>
where s.N
is a macrodigit,
breaks up e.Expr
into two parts -- e1
and e2
,
and returns (e1)e2
. If the original expression e.Expr
has at least s.N
terms (on the top level of structure),
then the first s.N
terms go to e1
, and the rest
to e2
. Otherwise, e1
is e.Expr
and e2
is empty.
<Last s.N e.Expr>
is similar to First
but it is e2
that has s.N
terms.
<Lenw e.Expr>
returns the length of e.Expr
in terms followed by e.Expr
.
<Lower e.Expr>
returns the original expression e.Expr
in which all capital letters are replaced by lower case letters.
<Upper e.Expr>
is similar to Lower
. All lower case letters
are capitalized.
5. System Functions
<Step>
returns the sequential number of the current step as a
macrodigit.
<Time>
returns a string containing the current system time.
<Arg s.N>
where s.N
is a macrodigit,
returns the command line argument which has the sequential
number s.N
. Command line arguments must not start with '-'
(in order not to be confused with flags).
<Mu s.F-name e.Expr>
, or
<Mu (e.String) e.Expr>
finds the function whose name is s.F-name
or
<Implode e.String>
(when given in the form
of a string of characters) and applies it
to the expression e.Expr
, i.e., is replaced by <s.F-name e.Expr>
.
If no such function is visible from the call of Mu
,
an error occurs.
<Up e.Expr>>
upgrades e.Expr
(demetacodes it). See Chapter 6
for restrictions on e.Expr
.
<Dn e.Expr>
downgrades e.Expr
(metacodes it).