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. 
<Close s.ID> ::
s.ID is the identifying number of the file. The function closes the file. If such a file does not exist, no action is taken. The value of Close is always empty. 
<ExistFile e.name> :: s.Boolean
e.name is a file name (a string of characters). The function checks whether the file exists and returnes the corresponding identifier "True" or "False". 
<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), 'r','R' (open for reading) or 'a','A' (open for adding). 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 . 
<RemoveFile e.file_name> :: s.Boolean (e.Errors)
If the function e.file_name can be successfully deleted, it is deleted, and s.Boolean is "True"; otherwise s.Boolean is "False", and the value of e.Errors is a description of the error.

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.

The basic format of binary arithmetic operations is: 

  <ar-function (e.N1) e.N2>
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.

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 /

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.

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 s.Subtype e.Expr , where e.Expr is unchanged and s.Type and s.Subtype depend on the type of the first element of e.Expr . 
  s.Type  s.subtype  e.Expr starts with 
  'L'     s.subtype  Latin letter 
                     'Lu'   capital Latin letter
                     'Ll'    lower Latin letter 
  'D'     0          decimal digit  
  'W'     s.subtype   word ( compound symbol ) 
                     'Wi'  identifier 
                     'Wq'  other word 
  'N'     0          macrodigit 
  'P'     s.subtype printable character
                     'Pu'      upper register printable character
                     'Pl'      lower register printable character
  'O'     s.subtype any other symbol 
                     'Ou'      upper register symbol 
                     'Ol'      lower register symbol 
  'B'     0          left parenthesis 
  '*'     0          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. 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.Compound_Symbol>

returns the string of character-symbols which make up s.Compound_Symbol .
<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 -- e.1 and e.2 , and returns (e.1)e.2 . 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 e.1 , and the rest to e.2 . Otherwise, e.1 is e.Expr and e.2 is empty.
<Last s.N e.Expr>

is similar to First but it is e.2 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

<GetCurrentDirectory> :: e.characters

This function returns the name of the current directory where the Refal-5 interpreter is running.
<GetEnv e.characters>

takes characters and interprets them as a name of the environment variable of the current operating system. The string must not exceed 120 characters. If the variable is undefined, then the function returns the empty expression, otherwise it returns a value of the variable as a sequence of characters. If the argument is not a sequence of characters, then "Recognition impossible" occures.
<Exit e.return-code>

takes a macrodigit or two terms ( '-' s.macrodigit ) and interrupts the current Refal-process. The process returns the argument to the current operating system as a return-code. If the argument is something else, then "Recognition impossible" occurs.
<Step>

returns the sequential number of the current step as a macrodigit.
<System e.characters>

takes e.characters and tries to interpret them as a shell's command of a current operating system. The string must not exceed 255 characters. If the value is a negative integer, then the function returns the string '--' followed by macrodigit, otherwise it returns a macrodigit. If the argument is not a sequence of characters, then "Recognition impossible" occurs.
<Time>

returns a string containing the current system time.
<TimeElapsed e.init> :: e.char-digits '.' e.char-digits

takes empty expression or macrodigit zero. It returns elapsead system time. The time is elapsed time from a last call to the same function with zero as its argument. If there was no such call then the time is elapsed time from start of loading of RSL-modules. The time is given in seconds. If the argument is something else, then "Recognition impossible" occurs.
<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).