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.Expron the current output and returns (is replaced by) e.Expr .


<Prout e.Expr>
prints the expression e.Expron 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-nameand 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

Representationofnumbers. 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, Divreturns 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 Cpcopies it, and Rp changes it.

4. Symbol and String Manipulation

<Type e.Expr>

returns s.Type e.Expr , where e.Expris 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, Implodereturns 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.Exprhas 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 Firstbut it is e2 that has s.N terms.
<Lenw e.Expr>

returns the length of e.Exprin terms followed by e.Expr .
<Lower e.Expr>

returns the original expression e.Exprin 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).