# Implementation Notes for CLISP

Last modified: 2000-04-03

This implementation is mostly conforming to the

> ANSI Common Lisp standard X3.226-1994
> "Information Technology - Programming Language - Common Lisp"

available on-line as the

> Common Lisp HyperSpec
> http://www.lisp.org/HyperSpec/
> ("CLHS" for short)

(but the printed ANSI document remains the authoritative source of information).

ANSI CL supersedes the earlier specifications

> Guy L. Steele Jr.: Common Lisp - The Language (2nd ed.).
> Digital Press 1990, 1032 pages.
> ("CLtL2" for short) available on-line

and

> Guy L. Steele Jr.: Common Lisp - The Language (1st ed.).
> Digital Press 1984, 465 pages.
> ("CLtL1" for short)

These notes document the differences between the CLISP implementation of Common Lisp and the ANSI CL standard, and some implementation details. This document is indexed in parallel to CLHS.

## Chapter Index

1. Introduction [CLHS-1]
2. Syntax [CLHS-2]
3. Evaluation and Compilation [CLHS-3]
4. Types and Classes [CLHS-4]
5. Data and Control Flow [CLHS-5]
6. Iteration [CLHS-6]
7. Objects [CLHS-7]
8. Structures [CLHS-8]
9. Conditions [CLHS-9]
10. Symbols [CLHS-10]
11. Packages [CLHS-11]
12. Numbers [CLHS-12]
13. Characters [CLHS-13]
14. Conses [CLHS-14]
15. Arrays [CLHS-15]
16. Strings [CLHS-16]
17. Sequences [CLHS-17]
18. Hash Tables [CLHS-18]
19. Filenames [CLHS-19]
20. Files [CLHS-20]
21. Streams [CLHS-21]
22. Printer [CLHS-22]
23. Reader [CLHS-23]
24. System Construction [CLHS-24]
25. Environment [CLHS-25]
26. Glossary [CLHS-26]

- Appendix [CLHS-a]
- X3J13 Issue Index [CLHS-ic]

# Extensions

1. Platform-independent Extensions
   1. Saving an Image
   2. Quitting Lisp
   3. The Language
   4. Encodings
   5. Defining new kinds of Streams
   6. Weak Pointers
   7. Finalization
   8. The Prompt
   9. Maximum ANSI CL compliance
   10. Additional Fancy Macros
2. Platform-specific Extensions
   1. Random Screen Access
   2. External Modules
   3. The Foreign Function Call Facility
   4. The Amiga Foreign Function Call Facility
   5. ARexx
   6. Socket Streams
   7. System Calls
   8. Quickstarting CLISP programs
   9. Application delivery with CLISP
   10. Shell Access
   11. Other

## Chapter 1: Introduction

### 1.4.1.3 Special Symbols

The final delimiter of an interactive stream: On Unix, the user has to type Ctrl-D at the beginning of a line. On DOS or Win32, the user has to type Ctrl-Z, followed by Return. This final delimiter is never actually seen by programs; no need to test for #\^D or #\^Z - use `read-char-no-hang` to check for end of stream. Calling `clear-input` on the stream removes the end-of-stream state, thus making it available for further input.

A newline character can be entered by the user by pressing the Newline key or, in the numeric keypad, the Enter key.

### 1.4.2 Error Terminology

Safety settings are ignored; therefore where the standard uses the phrase ``should signal an error'', an error is signaled.

### 1.4.4.5 Class Precedence Lists

The class precedence lists of the system classes `class`, `built-in-class`, `structure-class`, `standard-class`, `standard-method` contain the class `structure-object` instead of the class `standard-object`.

### 1.9 Symbols in the COMMON-LISP Package

Symbols missing from the `COMMON-LISP` package:

- `*print-lines*`
- `*print-miser-width*`
- `*print-pprint-dispatch*`
- `call-method`
- `change-class`
- `compiler-macro`
- `compiler-macro-function`
- `copy-pprint-dispatch`
- `define-compiler-macro`
- `define-method-combination`
- `ensure-generic-function`
- `invalid-method-error`
- `make-instances-obsolete`
- `make-load-form`
- `make-load-form-saving-slots`
- `make-method`
- `method-combination`
- `method-combination-error`
- `pprint-dispatch`
- `pprint-exit-if-list-exhausted`
- `pprint-fill`
- `pprint-indent`
- `pprint-linear`
- `pprint-logical-block`
- `pprint-newline`
- `pprint-pop`
- `pprint-tab`
- `pprint-tabular`
- `set-pprint-dispatch`
- `simple-condition-format-control`
- `style-warning`
- `unbound-slot`
- `unbound-slot-instance`
- `update-instance-for-different-class`
- `update-instance-for-redefined-class`
- `upgraded-complex-part-type`

## Chapter 2: Syntax

### 2.3.4 Symbols as Tokens

A "reserved token", i.e., a token that has potential number syntax but cannot be interpreted as a number, is interpreted as symbol when being read.

When creating a symbol from a token, no character attributes are removed.

### 2.3.5 Valid Patterns for Tokens

When a token with package markers is read, then no checking is done whether the package part and the symbol-name part do not have number syntax. (What's the purpose of this check?) So we consider tokens like `USER::` or `:1` or `LISP::4711` or `21:3` as symbols.

### 2.4.5 Double-Quote

When a string is read, no character attributes are removed.

### 2.4.6 Backquote

The backquote read macro also works when nested. Example:

       (eval ``(,#'(lambda () ',a) ,#'(lambda () ',b)))
     = (eval `(list #'(lambda () ',a) #'(lambda () ',b)))
     = (eval (list 'list (list 'function (list 'lambda nil (list 'quote a)))
                         (list 'function (list 'lambda nil (list 'quote b)))
       )     )

Multiple backquote combinations like `,,@` or `,@,@` are not implemented. Their use would be confusing anyway.

### 2.4.8 Sharpsign

Reader macros are also defined for the following:

`#,` | load-time evaluation
`#Y` | function objects and file encoding
`#"` | pathname

## Chapter 3: Evaluation and Compilation

All the functions built by `function`, `compile` and the like are atoms. There are built-in functions written in C, compiled functions (both of type `compiled-function`) and interpreted functions (of type `function`).

### 3.1.1 Introduction to Environments

#### lisp:the-environment

As in Scheme, the macro `(lisp:the-environment)` returns the current lexical environment. This works only in interpreted code and is not compilable!

#### lisp:eval-env

`(lisp:eval-env form &optional env)` evaluates a form in a given lexical environment, just if the form had been part of the program text that environment came from.

### 3.2.1 Compiler Terminology

CLISP compiles to platform-independent byte-code.

### 3.2.4.2.2 Definition of Similarity

Hash tables are externalizable objects.

### 3.3 Declarations

The declarations `(type type var ...)`, `(ftype type fun ...)`, `(function name arglist result-type)`, `(optimize (quality value) ...)` are ignored by the interpreter and the compiler.

The ANSI CL declaration `(optimize (debug ...))` is legal.

Additional declarations:

- The ANSI CL declaration `(ignorable var ...)` affects the variable binding for the variable var. The compiler will not warn about the variable, regardless whether it is used or not.
- The declaration `(compile)` has the effect that the current form is compiled prior to execution. Examples:

  `(locally (declare (compile)) form)` executes a compiled version of form.

      (let ((x 0))
        (flet ((inc () (declare (compile)) (incf x))
               (dec () (decf x)))
          (values #'inc #'dec)
      ) )

  returns two functions. The first is compiled and increments `x`, the second is interpreted (slower) and decrements the same `x`.

The type assertion `(the value-type form)` enforces a type check in interpreted code. No type check is done in compiled code.

See also the `lisp:ethe` macro.

### 3.4.6 Boa Lambda Lists

The initial value of an `&aux` variable in a boa lambda list is the value of the corresponding slot's initial form.

## Chapter 4: Types and Classes

### 4.2.3 Type Specifiers.

The general form of the `complex` type specifier is `(complex type-of-real-part type-of-imaginary-part)`. The type specifier `(complex type)` is equivalent to `(complex type type)`.

The ANSI CL type specifier `(real low high)` denotes the real numbers between low and high.

`deftype` lambda lists are subject to destructuring (nested lambda lists are allowed, as in `defmacro`) and may contain a `&whole` marker, but not an `&environment` marker.

`(lisp:type-expand-1 typespec)`: If typespec is a user-defined type, `type-expand-1` will expand it once and return two values: the expansion and `t`. If typespec is not a user-defined type, then the two values typespec and `nil` are returned.

`(lisp:type-expand typespec)`: This is similar to `(type-expand-1 typespec)`, but repeatedly expands typespec until it is no longer a user-defined type. A second value of `t` or `nil` is returned as for `type-expand-1`, indicating whether the original typespec was a user-defined type.

The possible results of `type-of` are:

- `cons`
- `symbol`, `null`, `boolean`
- `fixnum`, `bignum`, `ratio`, `short-float`, `single-float`, `double-float`, `long-float`, `complex`
- `character`, `base-char`
- `(array element-type dimensions)`, `(simple-array element-type dimensions)`
- `(vector t size)`, `(simple-vector size)`
- `(string size)`, `(simple-string size)`
- `(base-string size)`, `(simple-base-string size)`
- `(bit-vector size)`, `(simple-bit-vector size)`
- `function`, `compiled-function`
- `stream`, `file-stream`, `synonym-stream`, `broadcast-stream`, `concatenated-stream`, `two-way-stream`, `echo-stream`, `string-stream`,
- `package`, `hash-table`, `readtable`, `pathname`, `logical-pathname`, `random-state`, `byte`
- `special-operator`, `load-time-eval`, `symbol-macro`, `encoding`, `foreign-pointer`, `foreign-address`, `foreign-variable`, `foreign-function`
- `weak-pointer`, `read-label`, `frame-pointer`, `system-internal`
- `address` (should not occur)
- any other symbol (structure types or CLOS classes)
- a class (CLOS classes without proper name)

### 4.3 Classes

The CLOS symbols are exported from the package `"CLOS"` and thus normally visible in all user packages. If you do not want them (for example, if you want to use the PCL implementation of CLOS instead of the native one), do `(unuse-package "CLOS")`.

#### Deviations from ANSI CL:

`defclass`: It is required that the superclasses of a class be defined before the `defclass` form for the class is evaluated.

`defclass` supports the option `:metaclass structure-class`. This option is necessary in order to define a subclass of a `defstruct`-defined structure type using `defclass` instead of `defstruct`.

When `call-next-method` is called with arguments, the rule that the ordered set of applicable methods must be the same as for the original arguments is enforced by the implementation only in interpreted code.

`call-next-method` and `next-method-p` are local macros, not local functions. Use `#'(lambda () (call-next-method))` instead of `#'call-next-method` if you really need it as a function.

There is a generic function `clos:no-primary-method` (similar to `no-applicable-method`) which is called when a generic function of the class `standard-generic-function` is invoked and no primary method on that generic function is applicable.

`clos:generic-flet` and `clos:generic-labels` are implemented as macros, not as special operators. They are not imported into the packages `COMMON-LISP-USER` and `COMMON-LISP` because of the ANSI CL issue GENERIC-FLET-POORLY-DESIGNED:DELETE.

The function `ensure-generic-function` is not implemented.

`add-method` can put methods into other generic functions than the one the method came from.

`print-object` is only called on objects of type `standard-object` and `structure-object`. It is not called on other objects, like conses and numbers, due to the performance concerns.

`documentation` still has the CLtL1 implementation.

### 4.3.1.1 Standard Metaclasses

Among those classes listed in Figure 4-8, only the following are instances of `built-in-class`:

- `t`,
- `character`,
- `number`, `complex`, `real`, `float`, `rational`, `ratio`, `integer`,
- `sequence`,
- `array`, `vector`, `bit-vector`, `string`,
- `list`, `cons`,
- `symbol`, `null`,
- `function`, `generic-function`, `standard-generic-function`,
- `hash-table`,
- `package`,
- `pathname`, `logical-pathname`,
- `random-state`,
- `readtable`,
- `stream`, `synonym-stream`, `broadcast-stream`, `concatenated-stream`, `two-way-stream`, `echo-stream`, `string-stream`, `file-stream`.

### 4.3.2 Defining Classes

`defclass` supports the `:metaclass` option. Possible values are `standard-class` (the default) and `structure-class` (which creates structure classes, like `defstruct` does).

### 4.3.6 Redefining Classes

Redefining classes is not supported. The function `update-instance-for-redefined-class` is not implemented.

### 4.3.7 Integrating Types and Classes

The class `method-combination` is not implemented.

## Chapter 5: Data and Control Flow

### 5.3. The Data and Control Flow Dictionary

`prog1`, `prog2`, `and`, `or`, `psetq`, `when`, `unless`, `cond`, `case`, `multiple-value-list`, `multiple-value-bind`, `multiple-value-setq` are implemented as special operators and, as such, rather efficient.

#### destructuring-bind

The ANSI CL macro `destructuring-bind` does not perform full error checking.

#### compiled-function-p

`compiled-function-p` returns `t` on built-in functions written in C, compiled functions and special operator handlers. Therefore `compiled-function` is not a subtype of `function`.

#### eq

`eq` compares characters and fixnums as `eql` does. No unnecessary copies are made of characters and numbers. Nevertheless, one should use `eql` as it is more portable across CL implementations.

`(let ((x y)) (eq x x))` always returns `t`, regardless of `y`.

#### symbol-function

`(setf (symbol-function symbol) object)` requires object to be either a function, a `symbol-function` return value or a lambda expression. A lambda expression is thereby immediately converted to a function.

#### setf

Additional places:

`funcall`:
  `(setf (funcall #'symbol ...) object)` and `(setf (funcall 'symbol ...) object)` are equivalent to `(setf (symbol ...) object)`.
`get-dispatch-macro-character`:
  `(setf (get-dispatch-macro-character ...) ...)` performs a `set-dispatch-macro-character`.
`long-float-digits`:
  `(setf (long-float-digits) digits)` sets the default mantissa length of long floats to digits bits.
`values-list`:
  `(setf (values-list list) form)` is equivalent to `(values-list (setf list (multiple-value-list form)))`

`&key` markers in `defsetf` lambda lists are supported, but the corresponding keywords must appear literally in the program text.

`(get-setf-expansion form &optional env)`, `(lisp:get-setf-method form &optional env)`, and `(lisp:get-setf-method-multiple-value form &optional env)` receive as optional argument the environment necessary for macro expansions. In `define-setf-expander` and `lisp:define-setf-method` lambda lists, one can specify `&environment` and a variable, which will be bound to the environment. This environment should be passed to all calls of `get-setf-expansion`, `lisp:get-setf-method` and `lisp:get-setf-method-multiple-value`. If this is done, even local macros will be interpreted as places correctly.

Attempts to modify read-only data will signal an error. Program text and quoted constants loaded from files are considered read-only data. This check is only performed for strings, not for conses, other kinds of arrays, and user-defined data types.

See also the lisp:letf and lisp:letf* macros.

#### function

`(function symbol)` returns the local function definition established by `flet` or `labels`, if it exists, otherwise the global function definition.

`(special-operator-p symbol)` returns `nil` or `t`. If it returns `t`, then `(symbol-function symbol)` returns the (useless) special operator handler.

#### define-symbol-macro

The macro `define-symbol-macro` establishes symbol macros with global scope (as opposed to symbol macros defined with `symbol-macrolet`, which have local scope): `(define-symbol-macro symbol expansion)`.

The function `lisp:symbol-macro-expand` tests for a symbol macro: If symbol is defined as symbol macro, `(lisp:symbol-macro-expand symbol)` returns two values, `t` and the expansion, else it returns `nil`.

Calling `boundp` on a symbol defined as symbol macro returns `t`.

Calling `symbol-value` on a symbol defined as symbol macro returns the value of the expansion. Calling `set` on a symbol defined as symbol macro calls `setf` on the expansion.

Calling `makunbound` on a symbol defined as symbol macro removes the symbol macro definition.

#### lambda

`lambda-list-keywords` = `(&optional &rest &key &allow-other-keys &aux &body &whole &environment)`

Platform dependent: | 16-bit CPU | 32-bit CPU | 64-bit CPU
--- | --- | --- | ---
`call-arguments-limit` | 216=65536 | 232=4294967296
`multiple-values-limit` | 27=128
`lambda-parameters-limit` | 216=65536 | 232=4294967296

#### defun & defmacro

`defun` and `defmacro` are allowed in non-toplevel positions. As an example, consider the old (CLtL1) definition of `gensym`:

    (let ((gensym-prefix "G")
          (gensym-count 1))
      (defun gensym (&optional (x nil s))
        (when s
          (cond ((stringp x) (setq gensym-prefix x))
                ((integerp x)
                 (if (minusp x)
                   (error "~S: index ~S is negative" 'gensym x)
                   (setq gensym-count x)
                ))
                (t (error "~S: argument ~S of wrong type" 'gensym x))
        ) )
        (prog1
          (make-symbol
            (concatenate 'string
              gensym-prefix
              (write-to-string gensym-count :base 10 :radix nil)
          ) )
          (incf gensym-count)
    ) ) )

#### special

`(proclaim '(special var))` declarations may not be undone. The same holds for `defvar`, `defparameter` and `defconstant` declarations.

It is an error if a `defconstant` variable is bound at the moment the `defconstant` is executed, but `defconstant` does not check this.

Constants may not be bound dynamically or lexically.

#### eval-when

`eval-when` also accepts the situations `(not eval)` and `(not compile)`.

## Chapter 6: Iteration

No notes.

## Chapter 7: Objects

Changing the class of a given instance is not supported. The functions `change-class`, `update-instance-for-different-class`, `make-instances-obsolete` are not implemented.

Only the `standard` method combination is implemented.

User-defined method combination is not supported. The macros `define-method-combination`, `call-method` and the functions `invalid-method-error`, `method-combination-error`, `method-qualifiers` are not implemented.

## Chapter 8: Structures

The `:print-function` option should contain a lambda expression `(lambda (structure stream depth) (declare (ignore depth)) ...)` This lambda expression names a function whose task is to output the external representation of structure onto the stream. This may be done by outputting text onto the stream using `write-char`, `write-string`, `write`, `prin1`, `princ`, `print`, `pprint`, `format` and the like. The following rules must be obeyed:

- The value of `*print-escape*` must be respected.
- The value of `*print-pretty*` should not and cannot be respected, since the pretty-print mechanism is not accessible from outside.
- The value of `*print-circle*` need not to be respected. This is managed by the system. (But the print-circle mechanism handles only those objects that are (direct or indirect) components of structure.)
- The value of `*print-level*` is respected by `write`, `prin1`, `princ`, `print`, `pprint`, `format` instructions `~A`, `~S`, `~W`, and `format` instructions `~R`, `~D`, `~B`, `~O`, `~X`, `~F`, `~E`, `~G`, `~$` with not-numerical arguments. Therefore the print-level mechanism works automatically if only these functions are used for outputting objects and if they are not called on objects with nesting level > 1. (The print-level mechanism does not recognize how many parentheses you have output. It only counts how many times it was called recursively.)
- The value of `*print-length*` must be respected, especially if you are outputting an arbitrary number of components.
- The value of `*print-readably*` must be respected. Remember that the values of `*print-escape*`, `*print-level*`, `*print-length*` are ignored if `*print-readably*` is true. The value of `*print-readably*` is respected by `print-unreadable-object`, `write`, `prin1`, `princ`, `print`, `pprint`, `format` instructions `~A`, `~S`, `~W`, and `format` instructions `~R`, `~D`, `~B`, `~O`, `~X`, `~F`, `~E`, `~G`, `~$` with not-numerical arguments. Therefore `*print-readably*` will be respected automatically if only these functions are used for printing objects.
- You need not worry about the values of `*print-base*`, `*print-radix*`, `*print-case*`, `*print-gensym*`, `*print-array*`, `lisp:*print-closure*`, `lisp:*print-rpars*`, `lisp:*print-indent-lists*`.

The `:inherit` option is exactly like `:include` except that it does not create new accessors for the inherited slots.

## Chapter 9: Conditions

When an error occurred, you are in a break loop. You can evaluate forms as usual. The `help` command (or help key if there is one) lists the available debugging commands.

The macro `(lisp:muffle-cerrors {form}*)` executes the forms. When a continuable error occurs, no message is printed. Instead, the `continue` restart is invoked.

The macro `(lisp:appease-cerrors {form}*)` executes the forms. When a continuable error occurs, the error is printed as a warning and the `continue` restart is invoked.

The macro `(lisp:exit-on-error {form}*)` executes the forms. When a non-continuable error or a Ctrl-C interrupt occurs, the error is printed and CLISP terminates with error status.

The macro `lisp:with-restarts` is like `restart-case`, except that the forms are specified after the restart clauses instead of before them, and the restarts created are not implicitly associated to any condition. `(lisp:with-restarts (`{restart-clause}*`)` {form}*`)` is therefore equivalent to `(restart-case (progn` {form}*`)` {restart-clause}*`)`.

### 9.1.3.1.3 Embedded Newlines in Condition Reports

The error message prefix for the first line is "*** - ". There is no prefix for subsequent error lines. The aesthetics of condition reports containing an object, which requires newlines when pretty printing is enabled, is undefined.

### 9.2. The Conditions Dictionary

#### signal

The default condition type for conditions created by `signal` is `simple-condition`, not `simple-error`.

#### restart-case

In `restart-case` clauses the argument list can also be specified after the keyword/value pairs instead of before them. The syntax therefore is `(restart-case form {restart-clause}*)` with

restart-clause ::= | `(restart-name` arglist {keyword value}* {form}*`)`
| | `(restart-name` {keyword value}* arglist {form}*`)`

#### compute-restarts

`compute-restarts` and `find-restart` behave as specified in ANSI CL: If the optional condition argument is non-`nil`, only restarts associated with that condition and restarts associated to no condition at all are considered. Therefore the effect of associating a restart to a condition is not to activate it, but to hide it from other conditions. This makes the syntax dependent implicit association performed by `restart-case` nearly obsolete.

#### warn

The default condition type for conditions created by `warn` is `simple-warning`, not `simple-error`.

## Chapter 10: Symbols

No notes.

## Chapter 11: Packages

The standard ANSI CL packages

- `COMMON-LISP` with the nickname `CL`;
- `COMMON-LISP-USER` with the nickname `CL-USER` and
- `KEYWORD`

are implemented. The package `COMMON-LISP` exports only those symbols from the ANSI CL standard that are actually implemented.

### 11.1.2.2 The COMMON-LISP-USER Package

The `COMMON-LISP-USER` package uses only the `COMMON-LISP` package.

### 11.1.2.4 Implementation-Defined Packages

The following additional packages exist:

- `LISP` exports all symbols needed for a CLtL1/CltL2 environment, excluding CLOS.
- `CLOS` exports all CLOS specific symbols needed for a CLtL1/CltL2 environment.
- `USER` is the default user's package for a CLtL1/CltL2 environment.
- `SYSTEM`, with the nicknames `SYS` and `COMPILER`, has no exported symbols. It defines many system internals.
- `CHARSET` defines and exports some character sets, for use with `make-encoding` and as `:external-format` argument.
- `FFI` implements the foreign function interface. Some platforms only.
- `SCREEN` defines an API for random screen access. Some platforms only.

All pre-existing packages except `USER` and `COMMON-LISP-USER` belong to the implementation, in the sense that doing side-effects on them or on their symbols causes undefined behavior.

### 11.2. The Packages Dictionary

#### `make-package`

For `common-lisp:make-package`, the default value of the `:use` argument is `("COMMON-LISP")`. For `lisp:make-package`, the default value of the `:use` argument is `("LISP" "CLOS")`.

`make-package` and `lisp:in-package` accept a keyword argument `:case-sensitive`. Similarly, `defpackage` accepts an option `:case-sensitive`. When its value is non-`nil`, the package will be case sensitive, i.e., the reader will not case-convert symbol names before looking them up or creating them in this package. The package names are still subject to `(readtable-case *readtable*)`, though.

## Chapter 12: Numbers

The type `number` is the disjoint union of the types `real` and `complex`. ("exhaustive partition")

The type `real` is the disjoint union of the types `rational` and `float`.

The type `rational` is the disjoint union of the types `integer` and `ratio`.

The type `integer` is the disjoint union of the types `fixnum` and `bignum`.

The type `float` is the disjoint union of the types `short-float`, `single-float`, `double-float` and `long-float`.

### 12.1.1.3.2 Byte Operations on Integers

Byte specifiers are objects of type `byte`, not integers.

### 12.1.3.3 Rule of Float Substitutability

When a mathematical function may return an exact (rational) or inexact (floating-point) result, it always returns the exact result.

### 12.1.4 Floating-point Computations

There are four floating point types: short-float, single-float, double-float and long-float:

type | sign | mantissa | exponent | comment
--- | --- | --- | --- | ---
short-float | 1 bit | 16+1 bits | 8 bits
single-float | 1 bit | 23+1 bits | 8 bits | CLISP uses IEEE format
double-float | 1 bit | 52+1 bits | 11 bits | CLISP uses IEEE format
long-float | 1 bit | >=64 bits | 32 bits | variable length

The single and double float formats are those of the IEEE standard (1981), except that CLISP does not support features like +0, -0, +inf, -inf, gradual underflow, NaN, etc. (Common Lisp does not make use of these features.) This is why `*features*` does not contain the :IEEE-FLOATING-POINT keyword.

Long floats have variable mantissa length, which is a multiple of 16 (or 32, depending on the word size of the processor). The default length used when long floats are read is given by the place `(lisp:long-float-digits)`. It can be set by `(setf (lisp:long-float-digits) nnn)`, where nnn is a positive integer.

Example: `(setf (lisp:long-float-digits) 3322)` sets the default precision of long floats to 1000 decimal digits.

#### 12.1.4.4 Rule of Float Precision Contagion

The floating point contagion is controlled by the variable `lisp:*floating-point-contagion-ansi*`. When it is non-nil, contagion is done as per the ANSI CL standard: short->single->double->long.

Rationale:
  See it pragmatically: save what you can and let others worry about the rest.
Short:
  CL knows the number's precision, not accuracy, so preserving the precision can be accomplished reliably, while anything relating to the accuracy is just a speculation - only the user (programmer) knows what it is in each case.
Long:
  A float is an approximation of a real number. One can think of it as a random variable with the mean equal to itself and standard deviation equal to half the last significant digit. E.g., `1.5` is actually `1.5+-0.05`. Consider adding `1.5` and `1.75`. ANSI CL requires that `(+ 1.5 1.75)` return `3.25`, while traditional CLISP would return `3.3`. The implied random variables are: `3.25+-0.005` and `3.3+-0.05`. Note that the CLISP's way DOES lie about the mean: the mean IS `3.25` and nothing else, while the ANSI CL's way COULD be lying about the deviation (accuracy): if the implied accuracy of `1.5 (0.05)` is its actual accuracy, then the accuracy of the result cannot be smaller that that. Therefore, since CL has no way of knowing the actual accuracy, ANSI CL (and all the other standard engineering programming languages, like C, FORTRAN etc) decides that keeping the accuracy correct is the business of the programmer, while the language should preserve what it can - the precision.
Experience:
  Rounding errors accumulate, and if a computation is conducted with insufficient precision, an outright incorrect result can be returned. (E.g., `E(x^2)-E(x)^2` can be negative!) The user should not mix floats of different precision (that's what `lisp:*warn-on-floating-point-contagion*` is for), but one should not be penalized for this too harshly.

When `lisp:*floating-point-contagion-ansi*` is nil, the traditional CLISP method is used, namely:

The result of an arithmetic operation whose arguments are of different float types is rounded to the float format of the shortest (least precise) of the arguments: rational -> long float -> double float -> single float -> short float (in contrast to 12.1.4.4 Rule of Float Precision Contagion!)

Rationale:
  See it mathematically. Add intervals: {1.0 ± 1e-8} + {1.0 ± 1e-16} = {2.0 ± 1e-8} So, if we add `1.0s0` and `1.0d0`, we should get `2.0s0`.
Briefly:
  Do not suggest accuracy of a result by giving it a precision that is greater than its accuracy.
Example:
  `(- (+ 1.7 pi) pi)` should not return `1.700000726342836417234L0`, it should return `1.7f0` (or `1.700001f0` if there were rounding errors).
Experience:
  If in a computation using thousands of short floats, a long float (like pi) happens to be used, the long precision should not propagate throughout all the intermediate values. Otherwise, the long result would look precise, but its accuracy is only that of a short float; furthermore much computation time would be lost by calculating with long floats when only short floats would be needed.

If the variable `lisp:*warn-on-floating-point-contagion*` is true, a warning is emitted for every coercion involving different floating-point types.

When rational numbers are to be converted to floats (due to `float`, `coerce`, `sqrt` or a transcendental function), the result type is given by the variable `lisp:*default-float-format*`.

#### lisp:without-floating-point-underflow

The macro `lisp:without-floating-point-underflow`: `(without-floating-point-underflow {form}*)` executes the forms, with errors of type `floating-point-underflow` inhibited. Floating point operations will silently return zero instead of signalling an error of type `floating-point-underflow`.

### 12.1.5 Complex Computations

Complex numbers can have a real part and an imaginary part of different types. For example, `(sqrt -9.0)` evaluates to the number `#C(0 3.0)`, which has a real part of exactly 0, not only 0.0 (which would mean "approximately 0").

The type specifier for this is `(complex integer single-float)`, and `(complex type-of-real-part type-of-imaginary-part)` in general.

The type specifier `(complex type)` is equivalent to `(complex type type)`.

#### 12.1.5.3 Rule of Canonical Representation for Complex Rationals

Complex numbers can have a real part and an imaginary part of different types. If the imaginary part is `eql` to `0`, the number is automatically converted to a real number.

This has the advantage that `(let ((x (sqrt -9.0))) (* x x))` - instead of evaluating to `#C(-9.0 0.0)`, with `x` = `#C(0.0 3.0)` - evaluates to `#C(-9.0 0)` = `-9.0`, with `x` = `#C(0 3.0)`.

### 12.2 The Numbers Dictionary

#### Functions on integers

`(lisp:! n)` returns the factorial of n, n a nonnegative integer.

`(lisp:exquo x y)` returns the quotient x/y of two integers x,y, and checks that it is an integer. (This is more efficient than `/`.)

`(lisp:xgcd x1 ... xn)` returns the values g, c1, ..., cn, where g is the greatest common divisor of the integers x1,...,xn, and c1,...,cn are integer coefficients such that

`g` = `(gcd x1 ... xn)` = `(+ (* c1 x1) ... (* cn xn))`

#### expt

`(expt base exponent)` is not very precise if exponent has large absolute value.

#### log

`(log number base)` signals an error if `base = 1`.

#### pi

The value of `pi` is a long float with the precision given by `(lisp:long-float-digits)`. When this precision is changed, the value of `pi` is automatically recomputed. Therefore `pi` is a variable, not a constant.

#### float decoding

`float-radix` always returns `2`.

`(float-digits number digits)` coerces number (a real number) to a floating point number with at least digits mantissa digits. The following holds:

`(>= (float-digits (float-digits number digits)) digits)`

#### boolean operations

constant name | value
--- | ---
`boole-clr` | 0
`boole-set` | 15
`boole-1` | 10
`boole-2` | 12
`boole-c1` | 5
`boole-c2` | 3
`boole-and` | 8
`boole-ior` | 14
`boole-xor` | 6
`boole-eqv` | 9
`boole-nand` | 7
`boole-nor` | 1
`boole-andc1` | 4
`boole-andc2` | 2
`boole-orc1` | 13
`boole-orc2` | 11

#### fixnum limits

Platform dependent: | 16-bit CPU | 32-bit CPU | 64-bit CPU
--- | --- | --- | ---
`most-positive-fixnum` | 224-1 = 16777215 | 232-1 = 4294967295
`most-negative-fixnum` | -224 = -16777216 | -232 = -4294967296

#### float limits

Together with `pi`, the other long float constants `most-positive-long-float`, `least-positive-long-float`, `least-negative-long-float`, `most-negative-long-float`, `least-positive-normalized-long-float`, `least-negative-normalized-long-float`, `long-float-epsilon`, `long-float-negative-epsilon` are recomputed whenever `(lisp:long-float-digits)` is changed. They are variables, not constants.

#### floating-point-invalid-operation

This condition is never signaled by CLISP.

#### floating-point-inexact

This condition is never signaled by CLISP.

## Chapter 13: Characters

The characters are ordered according to a superset of the ASCII encoding.

Platform dependent: Only in CLISP built with the compile-time flag `UNICODE`.
  More precisely, CLISP uses the 16-bit Unicode character set (ISO 10646, also known as UCS-2).

Platform dependent: DOS, OS/2 platforms only, and only in CLISP built without compile-time flag `UNICODE`.
  More precisely, CLISP uses the IBM PC character set (code page 437):

  | #x0 | #x1 | #x2 | #x3 | #x4 | #x5 | #x6 | #x7 | #x8 | #x9 | #xA | #xB | #xC | #xD | #xE | #xF
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  #x00 | ** |  |  |  |  |  |  | ** | ** | ** | ** | ** | ** | ** | ¶ | §
  #x10 |  |  |  |  |  |  |  |  |  |  | ** | ** |  |  |  |
  #x20 |  | ! | " | # | $ | % | & | ' | ( | ) | * | + | , | - | . | /
  #x30 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | : | ; | < | = | > | ?
  #x40 | @ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O
  #x50 | P | Q | R | S | T | U | V | W | X | Y | Z | [ | \ | ] | ^ | _
  #x60 | ` | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o
  #x70 | p | q | r | s | t | u | v | w | x | y | z | { | | | } | ~ |
  #x80 | Ç | ü | é | â | ä | à | å | ç | ê | ë | è | ï | î | ì | Ä | Å
  #x90 | É | æ | Æ | ô | ö | ò | û | ù | ÿ | Ö | Ü | ¢ | £ | ¥ | ₧ | ƒ
  #xA0 | á | í | ó | ú | ñ | Ñ | ª | º | ¿ | ⌐ | ¬ | ½ | ¼ | ¡ | « | »
  #xB0 | ░ | ▒ | ▓ | │ | ┤ | ╡ | ╢ | ╖ | ╕ | ╣ | ║ | ╗ | ╝ | ╜ | ╛ | ┐
  #xC0 | └ | ┴ | ┬ | ├ | ─ | ┼ | ╞ | ╟ | ╚ | ╔ | ╩ | ╦ | ╠ | ═ | ╬ | ╧
  #xD0 | ╨ | ╤ | ╥ | ╙ | ╘ | ╒ | ╓ | ╛ | ╚ | ┘ | ┌ | █ | ▄ | ▌ | ▐ | ▀
  #xE0 | α | ß | Γ | π | Σ | σ | µ | τ | Φ | Θ | Ω | δ | ∞ | φ | ε | ∩
  #xF0 | ≡ | ± | ≥ | ≤ | ⌠ | ⌡ | ÷ | ≈ | ° | ∙ | · | √ | ⁿ | ² | ■ |

  Here ** are control characters, not graphic characters. (The characters left blank here cannot be represented in this character set).

Platform dependent: UNIX (except NeXTstep), Win32, Amiga, Acorn platforms only, and only in CLISP built without compile-time flag `UNICODE`.
  More precisely, CLISP uses the ISO Latin-1 (ISO 8859-1) character set:

  | #x0 | #x1 | #x2 | #x3 | #x4 | #x5 | #x6 | #x7 | #x8 | #x9 | #xA | #xB | #xC | #xD | #xE | #xF
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  #x00 | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | **
  #x10 | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | **
  #x20 |  | ! | " | # | $ | % | & | ' | ( | ) | * | + | , | - | . | /
  #x30 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | : | ; | < | = | > | ?
  #x40 | @ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O
  #x50 | P | Q | R | S | T | U | V | W | X | Y | Z | [ | \ | ] | ^ | _
  #x60 | ` | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o
  #x70 | p | q | r | s | t | u | v | w | x | y | z | { | | | } | ~ |
  #x80 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
  #x90 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
  #xA0 |  | ¡ | ¢ | £ | ¤ | ¥ | ¦ | § | ¨ | © | ª | « | ¬ |  | ® | ¯
  #xB0 | ° | ± | ² | ³ | ´ | µ | ¶ | · | ¸ | ¹ | º | » | ¼ | ½ | ¾ | ¿
  #xC0 | À | Á | Â | Ã | Ä | Å | Æ | Ç | È | É | Ê | Ë | Ì | Í | Î | Ï
  #xD0 | Ð | Ñ | Ò | Ó | Ô | Õ | Ö | × | Ø | Ù | Ú | Û | Ü | Ý | Þ | ß
  #xE0 | à | á | â | ã | ä | å | æ | ç | è | é | ê | ë | ì | í | î | ï
  #xF0 | ð | ñ | ò | ó | ô | õ | ö | ÷ | ø | ù | ú | û | ü | ý | þ | ÿ

  Here ** are control characters, not graphic characters. (The characters left blank here cannot be represented in this character set).

Platform dependent: NeXTstep platforms only, and only in CLISP built without compile-time flag `UNICODE`.
  More precisely, CLISP uses the NextStep character set:

  | #x0 | #x1 | #x2 | #x3 | #x4 | #x5 | #x6 | #x7 | #x8 | #x9 | #xA | #xB | #xC | #xD | #xE | #xF
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  #x00 | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | **
  #x10 | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | ** | **
  #x20 |  | ! | " | # | $ | % | & | ' | ( | ) | * | + | , | - | . | /
  #x30 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | : | ; | < | = | > | ?
  #x40 | @ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O
  #x50 | P | Q | R | S | T | U | V | W | X | Y | Z | [ | \ | ] | ^ | _
  #x60 | ` | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o
  #x70 | p | q | r | s | t | u | v | w | x | y | z | { | | | } | ~ |
  #x80 |  | À | Á | Â | Ã | Ä | Å | Ç | È | É | Ê | Ë | Ì | Í | Î | Ï
  #x90 | Ð | Ñ | Ò | Ó | Ô | Õ | Ö | Ù | Ú | Û | Ü | Ý | Þ | µ | × | ÷
  #xA0 | © | ¡ | ¢ | £ | ⁄ | ¥ | ƒ | § | ¤ | ’ | “ | « | ‹ | › | ﬁ | ﬂ
  #xB0 | ® | – | † | ‡ | · | ¦ | ¶ | • | ‚ | „ | ” | » | … | ‰ | ¬ | ¿
  #xC0 | ¹ | ˋ | ´ | ˆ | ˜ | ¯ | ˘ | ˙ | ¨ | ² | ˚ | ¸ | ³ | ˝ | ˛ | ˇ
  #xD0 | — | ± | ¼ | ½ | ¾ | à | á | â | ã | ä | å | ç | è | é | ê | ë
  #xE0 | ì | Æ | í | ª | î | ï | ð | ñ | Ł | Ø | Œ | º | ò | ó | ô | õ
  #xF0 | ö | æ | ù | ú | û | ı | ü | ý | ł | ø | œ | ß | þ | ÿ |  |

  Here ** are control characters, not graphic characters. (The characters left blank here cannot be represented in this character set).

The following are standard characters:

`#\Space` | #x20
`#\Newline` | #x0A

The following are semi-standard characters:

`#\Backspace` | #x08
`#\Tab` | #x09
`#\Linefeed` | #x0A
`#\Page` | #x0C
`#\Return` | #x0D

Platform dependent: DOS, OS/2, Win32 platforms only.

  `#\Rubout` | #x08

Platform dependent: UNIX, Amiga, Acorn platforms only.

  `#\Rubout` | #x7F

`#\Newline` is the delimiter between lines.

### Additional Named Characters

There are the following additional characters with names:

`#\Null` | #x00
`#\Bell` | #x07
`#\Escape` | #x1B

Additionally, the following syntax is defined for characters with code from #x00 to #x1F:

`#\^@` | #x00
`#\^A` .. `#\^Z` | #x01 .. #x1A
`#\^[` | #x1B
`#\^\` | #x1C
`#\^]` | #x1D
`#\^^` | #x1E
`#\^_` | #x1F

See also the section character i/o.

### Attributes

Characters do not have the CLtL1 font and bits attributes. For backward compatibility, there is a class `sys::input-character` representing either a character with font and bits, or a keystroke. The following functions work with objects of types `character` and `sys::input-character`. Note that `eql` or `equal` can not be used to compare objects of type `sys::input-character`.

`lisp:char-font-limit` = 16
  The system uses only font 0.
`lisp:char-bits-limit` = 16
  The following bits are defined:

  `:control` | `lisp:char-control-bit`
  `:meta` | `lisp:char-meta-bit`
  `:super` | `lisp:char-super-bit`
  `:hyper` | `lisp:char-hyper-bit`

`(lisp:char-font object)`
  returns the font of a character or `sys::input-character`.
`(lisp:char-bits object)`
  returns the bits of a character or `sys::input-character`.
`(lisp:make-char char [bits [font]])`
  returns a new `sys::input-character`, or `nil` if such a character cannot be created.
`(lisp:char-bit object name)`
  returns `t` if the named bit is set in object, else `nil`.
`(lisp:set-char-bit object name newvalue)`
  returns a new `sys::input-character` with the named bit set or unset, depending on the boolean newvalue.

Platform dependent: UNIX, DOS, OS/2, Win32, Acorn platforms only.
  The system itself uses this `sys::input-character` type only to mention special keys and Control/Alternate/Shift key status on return from `(read-char lisp:*keyboard-input*)`.

### 13.1.2.1 Character Scripts

The only defined character script is the type `character` itself.

### 13.1.3 Character Attributes

Characters have no implementation-defined attributes. All characters are simple characters.

### 13.1.4.1 Graphic Characters

The graphic characters are those Unicode characters which are defined by the Unicode standard, excluding the ranges `U0000..U001F` and `U007F..U009F`.

### 13.1.4.2 Alphabetic Characters

The alphabetic characters are those Unicode characters which are defined as letters by the Unicode standard.

### 13.1.4.3.4 Case of Implementation-Defined Characters

The characters with case are those Unicode characters c, for which the upper case mapping uc and the lower case mapping lc have the following properties:

- uc and lc are different,
- c is one of uc and lc,
- the upper case mapping of uc and of lc is uc,
- the lower case mapping of uc and of lc is lc.

The titlecase property of Unicode characters has no equivalent in Common Lisp.

### 13.1.4.4 Numeric Characters

The numeric characters are those Unicode characters which are defined as digits by the Unicode standard.

### 13.1.6 Ordering of Characters

The characters are ordered according to their Unicode code.

### 13.1.8 Treatment of Newline during Input and Output

Newlines are written according to the stream's encoding, see the function `stream-external-format` and the description of encodings, in particular, line terminators. The default behavior is as follows:

Platform dependent: DOS, OS/2, Win32 platforms only.
  When writing to a file, `#\Newline` is converted to CR/LF. (This is the usual convention on DOS.) For example, `#\Return #\Newline` is written as CR/CR/LF.

When reading from a file, CR/LF is converted to `#\Newline` (the usual convention on DOS), and CR not followed by LF is converted to `#\Newline` as well (the usual conversion on MacOS, also used by some programs on Win32).

### 13.1.9 Character Encodings

The integer returned by `char-int` is the same as the character's code.

### 13.1.10 Character Encodings

See the description of encodings.

### 13.2. The Characters Dictionary

`char-code` takes values from 0 (inclusive) to `char-code-limit` (exclusive), i.e., the implementation supports exactly `char-code-limit` characters.

binaries built ... | without UNICODE support | with UNICODE support
--- | --- | ---
`char-code-limit` | 256 | 65536

The types `lisp:string-char` and `base-char` are equivalent to `character`.

The graphic characters have been described above.

The standard characters are `#\Newline` and the graphic characters with a code between 32 and 126 (inclusive).

The alphabetic characters are these characters:

                 ABCDEFGHIJKLMNOPQRSTUVWXYZ
                 abcdefghijklmnopqrstuvwxyz

and the international alphabetic characters from the character set:

                 ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜßáíóúñÑªºãõØøÀÃÕ etc.

The functions `char-equal`, `char-not-equal`, `char-lessp`, `char-greaterp`, `char-not-greaterp`, `char-not-lessp` ignore bits and font attributes of their arguments.

#### Functions on characters

`(lisp:char-width character)` returns the number of screen columns occupied by character. This is 0 for non-spacing characters (such as control characters and many combining characters), 2 for double-width East Asian characters, and 1 for all other characters. See also function `string-width`.

### platform-dependent characters

The characters that are not graphic chars and the space character have names:

Platform dependent: Amiga platforms only.

  `(code-char #x00)` | = | `#\Null`
  `(code-char #x01)` | = | `#\Code1`
  `(code-char #x02)` | = | `#\Code2`
  `(code-char #x03)` | = | `#\Code3`
  `(code-char #x04)` | = | `#\Code4`
  `(code-char #x05)` | = | `#\Code5`
  `(code-char #x06)` | = | `#\Code6`
  `(code-char #x07)` | = | `#\Bell` | = | `#\Bel`
  `(code-char #x08)` | = | `#\Backspace` | = | `#\Bs`
  `(code-char #x09)` | = | `#\Tab` | = | `#\Ht`
  `(code-char #x0A)` | = | `#\Newline` | = | `#\Linefeed` | = | `#\Lf`
  `(code-char #x0B)` | = | `#\Vt`
  `(code-char #x0C)` | = | `#\Page` | = | `#\Ff`
  `(code-char #x0D)` | = | `#\Return` | = | `#\Cr`
  `(code-char #x0E)` | = | `#\So`
  `(code-char #x0F)` | = | `#\Si`
  `(code-char #x10)` | = | `#\Code16`
  `(code-char #x11)` | = | `#\Code17`
  `(code-char #x12)` | = | `#\Code18`
  `(code-char #x13)` | = | `#\Code19`
  `(code-char #x14)` | = | `#\Code20`
  `(code-char #x15)` | = | `#\Code21`
  `(code-char #x16)` | = | `#\Code22`
  `(code-char #x17)` | = | `#\Code23`
  `(code-char #x18)` | = | `#\Code24`
  `(code-char #x19)` | = | `#\Code25`
  `(code-char #x1A)` | = | `#\Code26`
  `(code-char #x1B)` | = | `#\Escape` | = | `#\Esc`
  `(code-char #x1C)` | = | `#\Code28`
  `(code-char #x1D)` | = | `#\Code29`
  `(code-char #x1E)` | = | `#\Code30`
  `(code-char #x1F)` | = | `#\Code31`
  `(code-char #x20)` | = | `#\Space`
  `(code-char #x7F)` | = | `#\Rubout`
  `(code-char #x9B)` | = | `#\Csi`

Platform dependent: DOS, OS/2, Win32 platforms only.

  `(code-char #x00)` | = | `#\Null`
  `(code-char #x07)` | = | `#\Bell`
  `(code-char #x08)` | = | `#\Backspace` | = | `#\Rubout`
  `(code-char #x09)` | = | `#\Tab`
  `(code-char #x0A)` | = | `#\Newline` | = | `#\Linefeed`
  `(code-char #x0B)` | = | `#\Code11`
  `(code-char #x0C)` | = | `#\Page`
  `(code-char #x0D)` | = | `#\Return`
  `(code-char #x1A)` | = | `#\Code26`
  `(code-char #x1B)` | = | `#\Escape`
  `(code-char #x20)` | = | `#\Space`

Platform dependent: UNIX, Acorn platforms only.

  `(code-char #x00)` | = | `#\Null` | = | `#\Nul`
  `(code-char #x01)` | = | `#\Soh`
  `(code-char #x02)` | = | `#\Stx`
  `(code-char #x03)` | = | `#\Etx`
  `(code-char #x04)` | = | `#\Eot`
  `(code-char #x05)` | = | `#\Enq`
  `(code-char #x06)` | = | `#\Ack`
  `(code-char #x07)` | = | `#\Bell` | = | `#\Bel`
  `(code-char #x08)` | = | `#\Backspace` | = | `#\Bs`
  `(code-char #x09)` | = | `#\Tab` | = | `#\Ht`
  `(code-char #x0A)` | = | `#\Newline` | = | `#\Nl` | = | `#\Linefeed`
  `(code-char #x0B)` | = | `#\Vt`
  `(code-char #x0C)` | = | `#\Page` | = | `#\Np`
  `(code-char #x0D)` | = | `#\Return` | = | `#\Cr`
  `(code-char #x0E)` | = | `#\So`
  `(code-char #x0F)` | = | `#\Si`
  `(code-char #x10)` | = | `#\Dle`
  `(code-char #x11)` | = | `#\Dc1`
  `(code-char #x12)` | = | `#\Dc2`
  `(code-char #x13)` | = | `#\Dc3`
  `(code-char #x14)` | = | `#\Dc4`
  `(code-char #x15)` | = | `#\Nak`
  `(code-char #x16)` | = | `#\Syn`
  `(code-char #x17)` | = | `#\Etb`
  `(code-char #x18)` | = | `#\Can`
  `(code-char #x19)` | = | `#\Em`
  `(code-char #x1A)` | = | `#\Sub`
  `(code-char #x1B)` | = | `#\Escape` | = | `#\Esc`
  `(code-char #x1C)` | = | `#\Fs`
  `(code-char #x1D)` | = | `#\Gs`
  `(code-char #x1E)` | = | `#\Rs`
  `(code-char #x1F)` | = | `#\Us`
  `(code-char #x20)` | = | `#\Space` | = | `#\Sp`
  `(code-char #x7F)` | = | `#\Rubout` | = | `#\Delete` | = | `#\Del`

### obsolete constants

`lisp:char-control-bit` | 1
`lisp:char-meta-bit` | 2
`lisp:char-super-bit` | 4
`lisp:char-hyper-bit` | 8

## Chapter 14: Conses

### 14.2 The Conses Dictionary

#### sublis, nsublis

`sublis` and `nsublis` apply the `:key` argument to the nodes of the cons tree and not to the keys of the alist.

#### mapcar, mapcan, maplist, mapcon, ...

The function `lisp:mapcap` is like `mapcan`, except that it concatenates the resulting lists with `append` instead of `nconc`:
`(mapcap fun x1 ... xn)` == `(apply #'append (mapcar fun x1 ... xn))`

(Actually a bit more efficient that this would be.)

The function `lisp:maplap` is like `mapcon`, except that it concatenates the resulting lists with `append` instead of `nconc`:
`(maplap fun x1 ... xn)` == `(apply #'append (maplist fun x1 ... xn))`

(Actually a bit more efficient that this would be.)

## Chapter 15: Arrays

`make-array` can return specialized arrays for the element types `(unsigned-byte 2)`, `(unsigned-byte 4)`, `(unsigned-byte 8)`, `(unsigned-byte 16)`, `(unsigned-byte 32)` and of course `bit` and `character`.

### 15.1.1 Array Elements

Platform dependent: | 16-bit CPU | 32-bit CPU | 64-bit CPU
--- | --- | --- | ---
`array-rank-limit` | 216=65536 | 232=4294967296
`array-dimension-limit` | 224=16777216 | 232=4294967296
`array-total-size-limit` | 224=16777216 | 232=4294967296

Note that these constants are not fixnums, contrary to the ANSI CL Issue ARRAY-DIMENSION-LIMIT-IMPLICATIONS:ALL-FIXNUM.

### adjust-array for displaced arrays

An array to which another array is displaced should not be shrunk (using `adjust-array`) in such a way that the other array points into void space. This is not checked at the time `adjust-array` is called!

## Chapter 16: Strings

String comparison is based on the function `char<=`. Therefore diphthongs do not obey the usual national rules. Example: `"o"` < `"oe"` < `"z"` < `"ö"`.

### 16.2 The Strings Dictionary

#### Functions on strings

`(lisp:string-width string)` returns the number of screen columns occupied by string. This is computed as the sum of all `char-width`s of all of the string's characters.

## Chapter 17: Sequences

### 17.3. The Sequences Dictionary

#### loop, map

For iteration through a sequence, a macro `lisp:doseq`, similar to `dolist`, may be used instead of `map` :

`(lisp:doseq (var seqform [resultform]) {declaration}* {tag|statement}* )`

`lisp:doseq` forms are iteration forms.

#### nreverse

The result of `nreverse` is always `eq` to the argument. `nreverse` on a vector swaps pairs of elements. `nreverse` on a list swaps the first and the last element and reverses the list chaining between them.

#### nreconc

The result of `nreconc` is `eq` to the first argument unless it is `nil`, in which case the result is `eq` to the second argument.

#### remove/delete

`remove`, `remove-if`, `remove-if-not`, `remove-duplicates` return their argument unchanged, if no element has to be removed.

`delete`, `delete-if`, `delete-if-not`, `delete-duplicates` destructively modify their argument: If the argument is a list, the `cdr` parts are modified. If the argument is a vector with fill pointer, the fill pointer is lowered and the remaining elements are compacted below the new fill pointer.

Contrary to the ANSI CL issue 283 RANGE-OF-COUNT-KEYWORD:NIL-OR-INTEGER, negative `:count` keyword arguments are not allowed unless you set `lisp:*sequence-count-ansi*` to a non-`nil` value, in which case "using a negative integer value is functionally equivalent to using a value of zero", as per the ANSI CL issue.

#### sort

`sort` and `stable-sort` have two additional keywords `:start` and `:end`:

      (sort sequence predicate &key :key :start :end)
      (stable-sort sequence predicate &key :key :start :end)

`sort` and `stable-sort` are identical. They implement the mergesort algorithm. Worst case complexity: O(n*log(n)) comparisons, where n is the length of the subsequence bounded by the `:start` and `:end` arguments.

## Chapter 18: Hash Tables

### 18.2. The Hash Tables Dictionary

#### make-hash-table

`make-hash-table` has an additional keyword `:initial-contents`:

    (make-hash-table &key :test :initial-contents :size
                     :rehash-size :rehash-threshold)

The `:initial-contents` argument is an alist that is used to initialize the new hash table. The `:rehash-threshold` argument is ignored.

#### loop, maphash

For iteration through a hash table, a macro `lisp:dohash`, similar to `dolist`, can be used instead of `maphash`:

    (lisp:dohash (key-var value-var hash-table-form [resultform])
      {declaration}* {tag|statement}*
    )

`lisp:dohash` forms are iteration forms.

## Chapter 19: Filenames

For most operations, pathnames denoting files and pathnames denoting directories can not be used interchangeably.

Platform dependent: UNIX, Amiga platforms only.
  For example, `#p"FOO/BAR"` denotes the file `BAR` in the directory `FOO`, while `#p"FOO/BAR/"` denotes the subdirectory `BAR` of the directory `FOO`.
Platform dependent: DOS, OS/2, Win32 platforms only.
  For example, `#p"FOO\\BAR"` denotes the file `BAR` in the directory `FOO`, while `#p"FOO\\BAR\\"` denotes the subdirectory `BAR` of the directory `FOO`.
Platform dependent: Acorn platforms only.
  For example, `#p"FOO.BAR"` denotes the file `FOO` in the directory `BAR`, while `#p"FOO.BAR."` denotes the subdirectory `BAR` of the directory `FOO`.

This is especially important for the functions `directory`, `lisp:dir`, `lisp:cd`, `lisp:make-dir`, `lisp:delete-dir`.

The minimum filename syntax that may be used portably is:

`"xxx"` | for a file with name xxx,
`"xxx.yy"` | for a file with name xxx and type yy,
`".yy"` | for a pathname with type yy and no name specified.

Hereby xxx denotes 1 to 8 characters, and yy denotes 1 to 3 characters, each of which being either an alphanumeric character or the underscore `#\_`. Other properties of pathname syntax vary between operating systems.

### 19.2.1 Pathname Components

Platform dependent: DOS platforms only.
  Pathname components:
  `host`
    always `nil`
  `device`
    `nil` or `:wild` or `"A"`|...|`"Z"`
  `directory`
    `(startpoint . subdirs)` where
    startpoint = `:relative` | `:absolute`
    subdirs = `()` | `(subdir . subdirs)`
    subdir = `:current` (means `"."`) or
    subdir = `:parent` (means `".."`) or
    subdir = `:wild-inferiors` (means `"..."`, all subdirectories) or
    subdir = `(name . type)`
    name = `:wild` or a `simple-string` of length at most 8
    type = `:wild` or a `simple-string` of length at most 3
  `name`
    `nil` or `:wild` or a `simple-string` of length at most 8
  `type`
    `nil` or `:wild` or a `simple-string` of length at most 3
  `version`
    always `nil` (may also be specified as `:wild` or `:newest`)

  When a pathname is to be fully specified (no wildcards), that means that no `:wild`, `:wild-inferiors` is allowed, and name = `nil` may not be allowed either.

  External notation: | `A:\sub1.typ\sub2.typ\name.typ`
  using defaults: | `\sub1.typ\sub2.typ\name.typ`
  or | `name.typ`
  or | `*:\sub1.typ\*.*\name.*`
  or similar.

  Instead of `'\'` one may use `'/'`, as usual for DOS calls.

Platform dependent: Amiga platforms only.
  Pathname components:
  `host`
    always `nil`
  `device`
    `nil` or a `simple-string`
  `directory`
    `(startpoint . subdirs)` where
    startpoint = `:relative` | `:absolute`
    subdirs = `()` | `(subdir . subdirs)`
    subdir = `:wild-inferiors` (means `"**"` or `"..."`, all subdirectories) or
    subdir = `:parent` (means `"/"` instead of `"subdir/"`) or
    subdir = `simple-string`, may contain wildcard characters `?` and `*`
  `name`
    `nil` or `simple-string`, may contain wildcard characters `?` and `*` (may also be specified as `:wild`)
  `type`
    `nil` or `simple-string`, may contain wildcard characters `?` and `*` (may also be specified as `:wild`)
  `version`
    always `nil` (may also be specified as `:wild` or `:newest`)

  Constraint: startpoint = `:relative` only if device is `nil`. If the device is specified, the pathname must be absolute!

  A filename from AMIGAOS is split into name and type according to the following rule:

  - if there is no `'.'` in the filename, then the name is everything, type is `nil`;
  - if there is a `'.'`, then name is the part before and type the part after the last dot.

  Case is ignored in the strings on comparison. No case conversions are performed.

  When a pathname is to be fully specified (no wildcards), that means that no `:wild`, `:wild-inferiors` is allowed, no wildcard characters are allowed in the strings, and name = `nil` may not be allowed either.

  External notation: | `dev:sub1.typ/sub2.typ/name.typ`
  using defaults: | `sub1.typ/sub2.typ/name.typ`
  or | `name.typ`
  or | `sub1.typ/**/sub3.typ/x*.lisp`
  or similar.

  Formal specification of the external notation:

  ch ::=
    any character except ':','/' and '*','?'
  name ::=
    {ch}+
  device ::=
    [ <empty> | ':' | name ':' ]
    ; empty = current device, relative to current directory
    ; ':' = current device, absolute (relative to root for disks)
    ; name ':' = specified device, absolute (relative to root for disks)
  subdir ::=
    [ <empty> | name ]
    ; empty means parent directory
  pathname ::=
    device { subdir '/' }* name

  Examples:

  String | Device | Directory | our pathname
  --- | --- | --- | ---
  `'c:foo'` | 'C' | device->`foo` | `"c" (:absolute "foo")`
  `'c:foo/'` | 'C' | device->`foo` | `"c" (:absolute "foo")`
  `'c:foo/bar'` | 'C' | device->`foo`->`bar` | `"c" (:absolute "foo" "bar")`
  `'c:/foo'` | 'C' | device->up->`foo` | `"c" (:absolute :parent "foo")`
  `'c:'` | 'C' | device | `"c" (:absolute)`
  `':foo'` | current | device->root->`foo` | `nil (:absolute "foo")`
  `'foo'` | current | device->`foo` | `nil (:relative "foo")`
  `'/foo'` | current | device->up->`foo` | `nil (:relative :parent "foo")`
  `'//foo/bar'` | current | device->up->up->`foo`->`bar` | `nil (:relative :parent :parent "foo" "bar")`
  `''` | current | device | `nil (:relative)`

  Appending a `'/'` to a path string that is non-empty and does not end with `':'` or `'/'` does not change its meaning. This `'/'` must be appended before another non-empty component can be appended. But appending a `'/'` to a path string that is empty or ends with `':'` or `'/'` means going up to the parent directory!
  We interpret any path string that is empty or ends with `':'` or `'/'` as pathname of a directory (with both name and type being `nil`).

Platform dependent: UNIX platforms only.
  Pathname components:
  `host`
    always `nil`
  `device`
    always `nil`
  `directory`
    `(startpoint . subdirs)` where
    startpoint = `:relative` | `:absolute`
    subdirs = `()` | `(subdir . subdirs)`
    subdir = `:wild-inferiors` (means `"**"` or `"..."`, all subdirectories) or
    subdir = `simple-string`, may contain wildcard characters `?` and `*`
  `name`
    `nil` or `simple-string`, may contain wildcard characters `?` and `*` (may also be specified as `:wild`)
  `type`
    `nil` or `simple-string`, may contain wildcard characters `?` and `*` (may also be specified as `:wild`)
  `version`
    always `nil` (may also be specified as `:wild` or `:newest`)

  A UNIX filename is split into name and type according to the following rule:

  - if there is no `'.'` in the filename, then the name is everything, type is `nil`;
  - if there is a `'.'`, then name is the part before and type the part after the last dot.

  When a pathname is to be fully specified (no wildcards), that means that no `:wild`, `:wild-inferiors` is allowed, no wildcard characters are allowed in the strings, and name = `nil` may not be allowed either.

  External notation: | `server:sub1.typ/sub2.typ/name.typ`
  using defaults: | `sub1.typ/sub2.typ/name.typ`
  or | `name.typ`
  or | `sub1.typ/**/sub3.typ/x*.lisp`
  or similar.

Platform dependent: OS/2, Win32 platforms only.
  Pathname components:
  `host`
    always `nil`
  `device`
    `nil` or `:wild` or `"A"`|...|`"Z"`
  `directory`
    `(startpoint . subdirs)` where
    startpoint = `:relative` | `:absolute`
    subdirs = `()` | `(subdir . subdirs)`
    subdir = `:wild-inferiors` ( means `"**"` or `"..."`, all subdirectories) or
    subdir = `simple-string`, may contain wildcard characters `?` and `*`
  `name`
    `nil` or `simple-string`, may contain wildcard characters `?` and `*` (may also be specified as `:wild`)
  `type`
    `nil` or `simple-string`, may contain wildcard characters `?` and `*` (may also be specified as `:wild`)
  `version`
    always `nil` (may also be specified as `:wild` or `:newest`)

  An OS/2 filename is split into name and type according to the following rule:

  - if there is no `'.'` in the filename, then the name is everything, type is `nil`;
  - if there is a `'.'`, then name is the part before and type the part after the last dot.

  When a pathname is to be fully specified (no wildcards), that means that no `:wild`, `:wild-inferiors` is allowed, no wildcard characters are allowed in the strings, and name `eq` `nil` may not be allowed either.

  External notation: | `A:\sub1.typ\sub2.typ\name.typ`
  using defaults: | `\sub1.typ\sub2.typ\name.typ`
  or | `name.typ`
  or | `*:\sub1.typ\**\sub3.typ\x*.lisp`
  or similar.

  Instead of '\' one may use '/', as usual for DOS calls.

Platform dependent: UNIX, OS/2, Win32, Amiga platforms only.
  The wildcard characters: `'*'` matches any sequence of characters, `'?'` matches any one character.

Platform dependent: UNIX, OS/2, Win32, Amiga platforms only.
  Due to the name/type splitting rule, there are pathnames that cannot result from `parse-namestring`. To get a pathname whose type contains a dot or whose name contains a dot and whose type is `nil`, `make-pathname` must be used. Example: `(make-pathname :name ".profile")`.

Platform dependent: Acorn platforms only.
  RISC OS provides several file systems as standard (ADFS, IDEFS, NetFS, RamFS, NetPrint) and support for extra file systems (DOSFS, ResourceFS and DeviceFS).

  A module called FileSwitch is at the center of all file system operation in RISC OS. FileSwitch provides a common core of functions used by all file systems. It only provides the parts of these services that are device independent. The device dependent services that control the hardware are provided by separate modules, which are the actual file systems. FileSwitch keeps track of active file systems and switches between them as necessary.

  One of the file system modules that RISC OS provides is FileCore. It takes the normal calls that FileSwitch sends to a file system module, and converts them to a simpler set of calls to modules that control the hardware. Unlike FileSwitch it creates a fresh instantiation of itself for each module that it supports. Using FileCore to build file system modules imposes a more rigid structure on it, as more of the file system is predefined.

  As well as standard file systems, FileSwitch supports image file systems. These provide facilities for RISC OS to handle media in foreign formats, and to support `image files' (or partitions) in those formats. Rather than accessing the hardware directly they rely on standard RISC OS file systems to do so. DOSFS is an example of an image file system used to handle DOS format discs.

  Terminology
    A pathname may include a file system name, a special field, a media name (e.g., a disc name), directory name(s), and the name of the object itself; each of these parts of a pathname is known as an `element' of the pathname.

  Filenames
    Filename `elements' may be up to ten characters in length on FileCore-based file systems and on NetFS. These characters may be digits or letters. FileSwitch makes no distinction between upper and lower case, although file systems can do so. As a general rule, you should not use top-bit-set characters in filenames, although some file systems (such as FileCore-based ones) support them. Other characters may be used provided they do not have a special significance. Those that do are listed below :
    .
      Separates directory specifications, e.g., $.fred
    :
      Introduces a drive or disc specification, e.g., :0, :bigdisc. It also marks the end of a file system name, e.g., adfs:
    *
      Acts as a `wildcard' to match zero or more characters.
    #
      Acts as a `wildcard' to match any single character.
    $
      is the name of the root directory of the disc.
    &
      is the user root directory (URD)
    @
      is the currently selected directory (CSD)
    ^
      is the `parent' directory
    %
      is the currently selected library (CSL)
    \
      is the previously selected directory (PSD)

  Directories
    The root directory, $, forms the top of the directory hierarchy of the media which contains the CSD. $ does not have a parent directory, trying to access its parent will just access $. Each directory name is separated by a '.' character. For example:

    $.Documents.Memos
    %.cc

  File Systems
    Files may also be accessed on file systems other than the current one by prefixing the filename with a file system specification. A file system name may appear between '-' characters, or suffixed by a ':', though the latter is advised since '-' can also be used to introduce a parameter on a command line, or as part of a file name. For example:

    -net-$.SystemMesg
    adfs:%.aasm

  Special Fields
    Special fields are used to supply more information to the file system than you can using standard path names; for example NetFS and NetPrint use them to specify server addresses or names. They are introduced by a '#' character; a variety of syntaxes are possible:

    net#MJHardy::disc1.mike
    #MJHardy::disc1.mike
    -net#MJHardy-:disc1.mike
    -#MJHardy-:disc1.mike

    The special fields here are all MJHardy, and give the name of the fileserver to use. Special fields may use any character except for control characters, double quote '"', solidus '|' and space. If a special field contains a hyphen you may only use the first two syntaxes given above.

  File$Path and Run$Path
    These two special variables control exactly where a file will be looked for, according to the operation being performed on it.

    File$Path | for read operations
    Run$Path | for execute operations

    The contents of each variable should expand to a list or prefixes, separated by commas. When a read operation is performed then the prefixes in File$Path are used in the order in which they are listed. The first object that matches is used, whether it be a file or directory. Similarly any execute operation uses the prefixes in Run$Path. These search paths are only used when the pathname does not contain an explicit file system reference, e.g., executing adfs:file will not use Run$Path.

  Other path variables
    You can set up other path variables and use them as pseudo file systems. For example if you typed:

    *Set Source$Path adfs:$.src.,adfs:$.public.src.

    you could then refer to the pseudo file system as Source: or (less preferable) as -Source-. These path variables work in the same was as File$Path and Run$Path.

    NOTE: Path variables are not implemented in this version of CLISP. A workaround for this is to use "<Foo$Path>" instead of "Foo:" until they are made available.

  from Lisp-string notation to internal representation
    No swapping. "foo.lisp" means file type "lisp" and file name "foo". This is pseudo-BNF:
    legal character ::=
      any ISO latin-1 graphic character >= ' ' except '.' ':' '*' '#' '$' '&' '@' '^' '%' '\' '?'
    extended legal character ::=
      any ISO latin-1 graphic character >= ' ' except ':' '"' '|'
    legal-wild char ::=
      legal char | '*' | '#' | '?'
    host ::=
      '-' { extended legal char except '-' }+ '-' | { extended legal char except '-' } { extended legal char }* ':' | empty
    device ::=
      ':' { legal char }+ '.' | empty
    directory ::=
      { '$' | '&' | '@' | '%' | '\' } '.' { subdirectory }* | { subdirectory }+ | empty

      '$' -> | `:absolute :root`
      '&' -> | `:absolute :home`
      '@' -> | `:absolute :current`
      '%' -> | `:absolute :library`
      '\' -> | `:absolute :previous`
      else | `:relative`

    subdirectory ::=
      { '^' | { legal-wild char }+ } '.'

      '^' -> | `:parent`

    filename ::=
      { { legal-wild char }+ | empty }
    filetype ::=
      { '.' { legal-wild char }+ | empty }
    pathname ::=
      host device directory filename filetype
    Examples:

    String | Hostname | Device | Directory | Name | Type
    --- | --- | --- | --- | --- | ---
    `-net-$.SystemMesg` | `"net"` | `nil` | `(:absolute :root)` | `"SystemMesg"` | `nil`
    `net#MJHardy::disc1.mike` | `"net#MJHardy"` | `"disc1"` | `(:absolute :root)` | `"mike"` | `nil`
    `#MJHardy::disc1.mike` | `"#MJHardy"` | `"disc1"` | `(:absolute :root)` | `"mike"` | `nil`
    `-net#MJHardy-:disc1.mike` | `"net#MJHardy"` | `"disc1"` | `(:absolute :root)` | `"mike"` | `nil`
    `-#MJHardy-:disc1.mike` | `"#MJHardy"` | `"disc1"` | `(:absolute :root)` | `"mike"` | `nil`
    `@.foo` | `nil` | `nil` | `(:absolute :current)` | `"foo"` | `nil`
    `foo` | `nil` | `nil` | `(:relative)` | `"foo"` | `nil`
    `^.` | `nil` | `nil` | `(:relative :parent)` | `nil` | `nil`
    `@.^.` | `nil` | `nil` | `(:absolute :current :parent)` | `nil` | `nil`
    `foo.bar` | `nil` | `nil` | `(:relative)` | `"foo"` | `"bar"`
    `foo.bar.baz` | `nil` | `nil` | `(:relative "foo")` | `"bar"` | `"baz"`
    `foo.bar.` | `nil` | `nil` | `(:relative "foo" "bar")` | `nil` | `nil`
    `foo.@.` | illegal

  From internal representation to RISCOS string
    with swapping only of name/type components.

    Hostname | Device | Directory | Name | Type | RISCOS String
    --- | --- | --- | --- | --- | ---
    `"net"` | `"disc1"` | `(:absolute :root)` | `"foo"` | `nil` | `"net::disc1.$.foo"`
    `"net#MJ"` | `"disc1"` | `(:absolute :root "foo")` | `"bar"` | `"baz"` | `"net#MJ::disc1.$.foo.baz.bar"`
    `"adfs"` | `"4"` | `(:absolute :root "foo" "bar")` | `nil` | `nil` | `"adfs::4.$.foo.bar"`
    `nil` | `"disc1"` | `(:absolute :root "foo")` | `"bar"` | `nil` | `":disc1.$.foo.bar"`
    `nil` | `"disc1"` | `(:absolute :current)` | `nil` | `nil` | illegal here
    `nil` | `"disc1"` | `(:relative)` | `nil` | `nil` | `":disc1."`
    `nil` | `"disc1"` | `nil` | `nil` | `nil` | `":disc1."`
    `nil` | `nil` | `(:absolute :root)` | `"foo"` | `nil` | `"$.foo"`
    `nil` | `nil` | `(:absolute :current)` | `"foo"` | `nil` | `"@.foo"`
    `nil` | `nil` | `(:relative)` | `"foo"` | `"bar"` | `"bar.foo"`
    `nil` | `nil` | `(:relative "foo")` | `"bar"` | `"baz"` | `"foo.baz.bar"`
    `nil` | `nil` | `(:absolute :library)` | `"bar"` | `nil` | `"%.bar"`
    `nil` | `nil` | `(:absolute :library "foo")` | `"bar"` | `nil` | `"%.foo.bar"`
    `nil` | `nil` | `(:relative)` | `"foo"` | `"bar"` | `"bar.foo"`
    `nil` | `nil` | `(:relative "foo")` | `"bar"` | `nil` | `"foo.bar"`
    `nil` | `nil` | `(:relative "foo")` | `nil` | `"bar"` | illegal here

    That is, the RISCOS string is the flattening-concatenation of

          (append
            (if (null hostname) "" (append hostname ":"))
            (if (null device) "" (append ":" device "."))
            (case (pop directory)
              (:absolute (case (pop directory)
                                 (:root "$.")
                                 (:home "&.")
                                 (:current "@.")
                                 (:library "%.")
                                 (:previous "\\.")
              )          )
              (:relative "")
            )
            (mapcar (lambda (subdir) (append subdir ".")) directory)
            (if (null name)
              (if (null type) "" (error "type with name illegal here"))
              (if (null type)
                name
                (append type "." name)
          ) ) )

  internal representation
    Pathname components:
    `host`
      `simple-string` or `nil`
    `device`
      `simple-string` or `nil`
    `directory`
      `(Startpoint . Subdirs)` where
      Startpoint = `:relative` | `:absolute` anchor
      anchor = `:root` | `:home` | `:current` | `:library` | `:previous`
      Subdirs = `()` | `(subdir . Subdirs)`
      subdir = `:parent` or
      subdir = `simple-string`, may contain wildcard characters `?`,`#` and `*`
    `name`
      `nil` or `simple-string`, may contain wildcard characters `?`,`#` and `*` (may also be specified as `:wild`)
    `type`
      `nil` or `simple-string`, may contain wildcard characters `?`,`#` and `*` (may also be specified as `:wild`)
    `version`
      always `nil` (may also be specified as `:wild` or `:newest`)

    Constraint: startpoint is not `:absolute :root` only if device is `nil`. If the device is specified, the pathname must be `:absolute :root`.

    The wildcard characters: `'*'` matches any sequence of characters, `'#'` or `'?'` matches any one character.

    Due to the name/type swapping rule, there are pathnames that cannot result from `parse-namestring`. To get a pathname whose type is `nil`, `make-pathname` must be used. Example: `(make-pathname :directory "!Clisp." :name "README")`.

### External notation.

External notation of pathnames (cf. `parse-namestring` and `namestring`), of course without spaces, [,],{,}:

Platform dependent: DOS platforms only.

  [ [drivespec] : ] | a letter `'*'`|`'a'`|...|`'z'`| `'a'`|...|`'z'`
  { name [. type] \ } | each one a subdirectory, `'\'` may be replaced by `'/'`
  [ name [. type] ] | filename with type (extension)

  Name and type may be character sequences of any length (consisting of alphanumeric characters and `'-'`, `'_'`). They are shortened to 8 resp. 3 characters and converted to upper case. A single `'*'` is allowed for `:wild`.

Platform dependent: Amiga platforms only.
  see above.
Platform dependent: UNIX platforms only.

  [ / ] | / denotes absolute pathnames
  { name / } | each one a subdirectory
  [ name [. type] ] | filename with type (extension)

  Name and type may be character sequences of any length (consisting of printing ASCII characters, except `'/'`).

Platform dependent: OS/2, Win32 platforms only.

  [ [drivespec] : ] | a letter '*'|'a'|...|'z'|'a'|...|'z'
  { name [. type] \ } | each one a subdirectory, '\' may be replaced by '/'
  [ name [. type] ] | filename with type (extension)

  Name and type may be character sequences of any length (consisting of printing ASCII characters, except `'/'`, `'\'`, `':'`).

Platform dependent: Acorn platforms only.
  see above.

`namestring` has an optional flag argument: `(namestring pathname t)` returns an external notation suitable for passing to the operating system or other programs.

Platform dependent: DOS, OS/2, Amiga platforms only.
  The function `user-homedir-pathname` is not implemented.
Platform dependent: DOS, OS/2 platforms only.
  If you really need that function, you might define it like this:

        (defun user-homedir-pathname (&optional host)
          (declare (ignore host))
          (or (system::getenv "HOME") "\\")
        )

### 19.3 Logical Pathnames.

When the argument of the function `translate-logical-pathname` is a string, it is interpreted as a logical pathname string.

### 19.4 The Filenames Dictionary.

`pathname-match-p` does not interpret missing components as wild.

`translate-pathname` has two additional keywords:
`(translate-pathname source from-wildname to-wildname &key :all :merge)`
If `:all` is specified and non-`nil`, a list of all resulting pathnames, corresponding to all matches of `(pathname-match-p source from-wildname)`, is returned. If `:merge` is specified and `nil`, unspecified pieces of to-pathname are not replaced by corresponding pieces of source.
This function seems to be buggy at this time. Sorry.

#### parse-namestring

`(parse-namestring string &optional host defaults)` returns a logical pathname only if host is a logical host or host is `nil` and defaults is a logical pathname. To construct a logical pathname from a string, the function `logical-pathname` can be used.

#### merge-pathnames

`(merge-pathnames pathname [default-pathname])` returns a logical pathname only if `default-pathname` is a logical pathname. To construct a logical pathname from a string, the function `logical-pathname` can be used.

When both `pathname` and `default-pathname` are relative pathnames, the behavior depends on `lisp:*merge-pathnames-ansi*`: when it is `nil`, then CLISP retains its traditional behavior:

    (merge-pathnames #p"x/" #p"y/")
                 ==> #p"x/"

Rationale: `merge-pathnames` is used to specify default components for pathnames, so there is some analogy between `(merge-pathnames a b)` and `(or a b)`. Obviously putting in the same default a second time should do the same as putting it in once: `(or a b b)` is the same as `(or a b)`, so `(merge-pathnames (merge-pathnames a b) b)` should be the same as `(merge-pathnames a b)`.

(This question actually matters because in Common Lisp there is no distinction between "pathnames with defaults merged-in" and "pathnames with defaults not yet applied".)

Now, `(merge-pathnames (merge-pathnames '#p"x/" '#p"y/") '#p"y/")` and `(merge-pathnames '#p"x/" '#p"y/")` are equal in CLISP (when `lisp:*merge-pathnames-ansi*` is `nil`), but not in implementations that strictly follow the Common Lisp spec. In fact, the above twice-default = once-default rule holds for all pathnames in CLISP.

When `lisp:*merge-pathnames-ansi*` is non-`nil`, the normal ANSI CL behavior is exhibited:

    (merge-pathnames #p"x/" #p"y/")
                 ==> #p"y/x/"

The rationale is that "merge" is "merge" and not "or".

## Chapter 20: Files

### 20.2 The Files Dictionary.

#### rename-file

`rename-file` always returns a non-logical pathname as its first value.

#### probe-file

`probe-file` can not be used to check whether a directory exists. Use the function `lisp:probe-directory` or the function `directory` for this purpose.

#### file-author

`file-author` always returns `nil`, because the operating systems CLISP is ported to do not store a file's author in the file system. Some operating systems, such as Unix, have the notion of a file's owner, and some other CL implementations return the user name of the file owner. CLISP does not do this, because owner and author are not the same; in particular, authorship is preserved by copying, while ownership is not.

#### probe-directory

`(lisp:probe-directory pathname)` tests whether pathname exists and is a directory. It will, unlike `probe-file` or `truename`, not signal an error if the parent directory of pathname does not exist.

#### directory

`(directory &optional pathname &key :full :circle)` can run in two modes:

- If pathname contains no name or type component, a list of all matching directories is produced.
- Otherwise a list of all matching files is returned. If the `:full` argument is non- `nil`, this contains additional information: for each matching file you get a list of at least four elements `(file-pathname file-truename file-write-date-as-decoded-time file-length)`.

Platform dependent: UNIX platforms only.
  If the `:circle` argument is non-`nil`, the function avoids endless loops that may result from symbolic links.

`(lisp:dir &optional pathname)` is like `directory`, but displays the pathnames instead of returning them. `(lisp:dir)` shows the contents of the current directory.

Platform dependent: UNIX, Amiga platforms only.
  `(lisp:cd [pathname])` manages the current directory.
Platform dependent: Acorn platforms only.
  `(lisp:cd [pathname])` manages the current host, current device and the current directory.
Platform dependent: DOS, OS/2, Win32 platforms only.
  `(lisp:cd [pathname])` manages the current device and the current directory.

`(lisp:cd pathname)` sets it, `(lisp:cd)` returns it.

`(lisp:default-directory)` is equivalent to `(cd)`. `(setf (lisp:default-directory) pathname)` is equivalent to `(cd pathname)`, except for the return value.

`(lisp:make-dir directory-pathname)` creates a new subdirectory.

`(lisp:delete-dir directory-pathname)` removes an (empty) subdirectory.

## Chapter 21: Streams

### 21.1.1.1.3 Interactive Streams

Interactive streams are those whose next input might depend on a prompt one might output.

### terminal interaction.

Platform dependent: UNIX, DOS, OS/2 platforms only, and only in CLISP built without compile-time flag `NO_READLINE`.
  Input through `*terminal-io*` uses the GNU readline library. Arrow keys can be used to move within the input history. The Tab key completes the symbol's name that is being typed. See clreadline.html or clreadline.dvi for a complete description of the key bindings. The GNU readline library is not used if standard input and standard output do not both refer to the same terminal.

Platform dependent: UNIX, DOS, OS/2, Win32, Amiga, Acorn platforms only.
  `*terminal-io*` is not the only stream that communicates directly with the user: During execution of the body of a `(lisp:with-keyboard . body)` form, `lisp:*keyboard-input*` is the stream that reads the keystrokes from the keyboard. It returns every keystroke in detail, as character or `sys::input-character` with the following bits:
  `:hyper`
    (Platform dependent: DOS, OS/2, Win32, Amiga platforms only.) if a non-standard key. These are: Function keys, cursor keypads, numeric keypad (Platform dependent: DOS, OS/2, Win32 platforms only). Function keys, cursor keypad (Platform dependent: Amiga platforms only).
  slot `key`
    the key name, for non-standard keys:
    Platform dependent: DOS, OS/2 platforms only.
      F1 -> `:F1`, ..., F10 -> `:F10`, F11 -> `:F11`, F12 -> `:F12`, Insert -> `:Insert`, Delete -> `:Delete`, Home -> `:Home`, End -> `:End`, PgUp -> `:PgUp`, PgDn -> `:PgDn`, Arrow keys -> `:Up`, `:Down`, `:Left`, `:Right`.
    Platform dependent: UNIX, Win32 platforms only.
      F1 -> `:F1`, ..., F10 -> `:F10`, F11 -> `:F11`, F12 -> `:F12`, Insert -> `:Insert`, Delete -> `:Delete`, Center -> `:Center`, Home -> `:Home`, End -> `:End`, PgUp -> `:PgUp`, PgDn -> `:PgDn`, Arrow keys -> `:Up`, `:Down`, `:Left`, `:Right`.
    Platform dependent: Amiga platforms only.
      F1 -> `:F1`, ..., F9 -> `:F9`, F10 -> `:F10`, Help -> `:Help`, Arrow keys -> `:Up`, `:Down`, `:Left`, `:Right`.
  slot `char`
    the ASCII code for standard keys
  `:super`
    (Platform dependent: DOS, OS/2, Win32, Amiga platforms only.) if pressed together with Shift key(s) and if the keystroke would have been an other without Shift.
  `:control`
    if pressed together with the Control key.
  `:meta`
    (Platform dependent: DOS, OS/2, Win32 platforms only.) if pressed together with the Alternate key.
  This keyboard input is not echoed on the screen. During execution of a `(lisp:with-keyboard . body)` form, no input from `*terminal-io*` or any synonymous stream should be requested.

### Printing and OS interface.

See also `(shell command)`.

The macro `lisp:with-output-to-printer`:
`(lisp:with-output-to-printer (var [:external-format]) {declaration}* {form}*)` binds the variable var to an output stream that sends its output to the printer.

Platform dependent: UNIX, OS/2, Win32 platforms only.
  `(lisp:make-pipe-input-stream command &key :element-type :external-format :buffered)`
    returns an input stream that will supply the output from the execution of the given operating system command.
  `(lisp:make-pipe-output-stream command &key :element-type :external-format :buffered)`
    returns an output stream that will pass its output as input to the execution of the given operating system command.
  `(lisp:make-pipe-io-stream command &key :element-type :external-format :buffered)`
    returns three values. The first value is a bidirectional stream that will simultaneously pass its output as input to the execution of the given operating system command and supply the output from this command as input. The second and third value will be the input stream and the output stream that make up the I/O stream, respectively. Note that they must be closed individually.
    Warning: Improper use of this function can lead to deadlocks. You use it at your own risk!
    A deadlock occurs if the command and your program either both try to read from each other at the same time or both try to write to each other at the same time. To avoid deadlocks, it is recommended that you fix a protocol between the command and your program and avoid any hidden buffering: use `read-char`, `read-char-no-hang`, `listen` instead of `read-line` and `read` on the input side, and complete every output operation by a `finish-output`. The same cautions must apply to the called command as well.

For all functions that accept these keywords, the acceptable values are:

`:element-type`
  types equivalent to `character` or `(unsigned-byte n)`, `(signed-byte n)`; if the stream is to be unbuffered, n must be a multiple of 8.
`:external-format`
  encodings, (constant) symbols in the `CHARSET` package, strings (denoting iconv() based encodings), the symbol `:default`, and the line terminator keywords `:unix`, `:mac`, `:dos`. The default encoding is `lisp:*default-file-encoding*`.
`:buffered`
  `nil`, `t`, or `:default`.
  - for functions that create sockets and pipes, `:default` is equivalent to `nil`;
  - for functions that open files, `:default` means that buffered file streams will be returned for regular files and (on Unix) block-devices, and unbuffered file streams for special files.

### 21.2. The Streams Dictionary

#### stream-element-type

`stream-element-type` is `setf`able. The element type of streams created by the functions `open`, `lisp:make-pipe-input-stream`, `lisp:make-pipe-output-stream`, `lisp:make-pipe-io-stream`, `lisp:socket-accept`, `lisp:socket-connect` can be modified, if the old and the new element type are either

- both equivalent to `character` or `(unsigned-byte 8)` or `(signed-byte 8)`, or
- both equivalent to `(unsigned-byte n)` or `(signed-byte n)`, with the same n.

#### Binary input, read-byte

The function `(lisp:read-integer stream element-type &optional endianness eof-error-p eof-value)` reads a multi-byte integer from stream. stream should be a stream with element-type `(unsigned-byte 8)`. element-type should be a type equivalent to `(unsigned-byte n)`, where n is a multiple of 8.

`(lisp:read-integer stream element-type)` is like `(read-byte stream)` if stream's element type were set to element-type, except that stream's file-position will increase by n/8 instead of 1.

endianness can be `:little` or `:big`. The default is `:little`, which corresponds to the `read-byte` behavior in CLISP.

Together with `(setf stream-element-type)`, this function permits mixed character/binary input from a stream.

The function `(lisp:read-float stream element-type &optional endianness eof-error-p eof-value)` reads a floating-point number in IEEE binary representation from stream. stream should be a stream with element-type `(unsigned-byte 8)`. element-type should be a type equivalent to `single-float` or `double-float`.

endianness can be `:little` or `:big`. The default is `:little`, which corresponds to the `read-byte` behavior in CLISP.

#### Binary output, write-byte

The function `(lisp:write-integer integer stream element-type &optional endianness)` writes a multi-byte integer to stream. stream should be a stream with element-type `(unsigned-byte 8)`. element-type should be a type equivalent to `(unsigned-byte n)`, where n is a multiple of 8.

`(lisp:write-integer integer stream element-type)` is like `(write-byte integer stream)` if stream's element type were set to element-type, except that stream's file-position will increase by n/8 instead of 1.

endianness can be `:little` or `:big`. The default is `:little`, which corresponds to the `write-byte` behaviour in CLISP.

Together with `(setf stream-element-type)`, this function permits mixed character/binary output to a stream.

The function `(lisp:write-float float stream element-type &optional endianness)` writes a floating-point number in IEEE binary representation to stream. stream should be a stream with element-type `(unsigned-byte 8)`. element-type should be a type equivalent to `single-float` or `double-float`.

endianness can be `:little` or `:big`. The default is `:little`, which corresponds to the `write-byte` behaviour in CLISP.

#### read-sequence

In addition to `read-sequence`, the following two functions are provided:

`lisp:read-byte-sequence` performs multiple `read-byte` operations:
  `(lisp:read-byte-sequence sequence stream &key :start :end)` fills the subsequence of sequence specified by `:start` and `:end` with integers consecutively read from stream. It returns the index of the first element of sequence that was not updated (= end or < end if the stream reached its end).

  This function is especially efficient if sequence is a `(vector (unsigned-byte 8))` and stream is a file/pipe/socket stream with element type `(unsigned-byte 8)`.

`lisp:read-char-sequence` performs multiple `read-char` operations:
  `(read-char-sequence sequence stream &key :start :end)` fills the subsequence of sequence specified by `:start` and `:end` with characters consecutively read from stream. It returns the index of the first element of sequence that was not updated (= end or < end if the stream reached its end).

  This function is especially efficient if sequence is a `string` and stream is a file/pipe/socket stream with element type `character` or an input string stream.

#### write-sequence

In addition to `write-sequence`, the following two functions are provided:

`lisp:write-byte-sequence` performs multiple `write-byte` operations:
  `(lisp:write-byte-sequence sequence stream &key :start :end)` outputs the integers of the subsequence of sequence specified by `:start` and `:end` to stream. It returns sequence.

  This function is especially efficient if sequence is a `(vector (unsigned-byte 8))` and stream is a file/pipe/socket stream with element type `(unsigned-byte 8)`.

`lisp:write-char-sequence` performs multiple `write-char` operations:
  `(lisp:write-char-sequence sequence stream &key :start :end)` outputs the characters of the subsequence of sequence specified by `:start` and `:end` to stream. It returns sequence.

  This function is especially efficient if sequence is a `string` and stream is a file/pipe/socket stream with element type `character`.

#### file-position

Platform dependent: DOS, OS/2, Win32 platforms only.
  `file-position` works on any buffered file stream. When a Newline is output to resp. input from a file stream, its file position is increased by 2 since Newline is encoded as CR/LF in the file.

#### open

`open` cannot handle files of size >= 4 GB.

`open` accepts three additional keywords: `:external-format`, `:element-type`, and `:buffered`.

#### close

`close` ignores its `:abort` argument.

#### broadcast-stream

`input-stream-p` and `interactive-stream-p` return false for broadcast streams.

## Chapter 22: Printer

### 22.1.1.1 Multiple Possible Textual Representations

An additional variable `lisp:*print-closure*` controls whether compiled and interpreted functions (closures) are output in detailed form. If `lisp:*print-closure*` is non-`nil`, compiled closures are output in `#Y` syntax which the reader understands. `lisp:*print-closure*` is initially set to `nil`.

An additional variable `lisp:*print-rpars*` controls the output of the right (closing) parentheses. If `lisp:*print-rpars*` is non-`nil`, closing parentheses which do not fit onto the same line as the the corresponding opening parenthesis are output just below their corresponding opening parenthesis, in the same column. `lisp:*print-rpars*` is initially set to `t`.

An additional variable `lisp:*print-indent-lists*` controls the indentation of lists that span more than one line. It specifies by how many characters items within the list will be indented relative to the beginning of the list. `lisp:*print-indent-lists*` is initially set to `2`.

### 22.1.3.7 Printing Other Vectors

When `*print-readably*` is true, other vectors are written as follows: If the element-type is `t`, the syntax `#(x0 ... xn-1)` is used. Otherwise, the syntax `#A(element-type dimensions contents)` is used.

### 22.1.3.8 Printing Other Arrays

When `*print-readably*` is true, other arrays are written as follows: If the element-type is `t`, the syntax `#rankA contents` is used. Otherwise, the syntax `#A(element-type dimensions contents)` is used.

### 22.2.1.3 Compiling Format Strings

The functions `write` and `write-to-string` have an additional keyword `:closure` that can be used to bind `lisp:*print-closure*`.

## 22.4 The Printer Dictionary

### format

The `format` instruction `~W` is similar to `~A` and `~S`, but avoids binding of `*print-escape*`. `(format stream "~W" object)` is equivalent to `(write object :stream stream)`.

The `format` instruction `~!` is similar to `~/`, but avoids putting a function name into a string. Thus, even if the function is not interned in the `COMMON-LISP-USER` package, you might not need to specify the package.

`(format stream "~args!" function object)` is equivalent to `(funcall function stream object colon-modifier-p atsign-modifier-p args)`.

`format` `~R` and `format` `~:R` can output only integers in the range `|n| < 1066`. The output is in English, according to the American conventions, and these conventions are identical to the British conventions only in the range `|n| < 109`.

`format` `~:@C` does not output the character itself, only the instruction how to type the character.

For `format` `~E` and `format` `~G`, the value of `*read-default-float-format*` does not matter if `*print-readably*` is true.

`format` `~T` can determine the current column of any built-in stream.

### pathnames

Pathnames are printed as follows: If `*print-escape*` is `nil`, only the namestring is printed; otherwise it is printed with `#P""` syntax, as per ANSI CL Issue PRINT-READABLY-BEHAVIOR:CLARIFY. But, if `*print-readably*` is true, we are in trouble as `#P""` is ambiguous (which is verboten when `*print-readably*` is true), while being mandated by the ANSI CL standard. Therefore, in this case, we print it like this

    #-CLISP #P"" #+CLISP #S(PATHNAME ...)

When the variable `lisp:*print-pathnames-ansi*` is not set, otherwise the `#P""` notation is used as per 1.5.1.4.1 Resolution of Apparent Conflicts in Exceptional Situations.

### misc

`*print-case*` controls the output not only of symbols, but also of characters and some `#<...>` objects.

In the absence of `sys::write-float-decimal`, floating point numbers are output in radix 2. This function is defined in `floatprint.lisp` and is not available if you run CLISP without a memory image.

If `*print-readably*` is true, `*read-default-float-format*` has no influence on the way floating point numbers are printed.

Platform dependent: UNIX, DOS, OS/2, Win32, Acorn platforms only.
  `*print-pretty*` is initially `nil` but set to `t` in `config.lisp`. This makes screen output prettier.
Platform dependent: Amiga platforms only.
  `*print-pretty*` is initially `nil` but set to `t` in `config.lisp`. This makes unbuffered screen output much faster.

`*print-array*` is initially set to `t`.

## Chapter 23: Reader

This is the list of objects whose external representation can not be meaningfully read in:

`#<type ...>` | all structures lacking a keyword constructor
`#<ARRAY type dimensions>` | all arrays except strings, if `*print-array*` is `nil`
`#<SYSTEM-FUNCTION name>` | built-in function written in C
`#<ADD-ON-SYSTEM-FUNCTION name>` | other function written in C
`#<SPECIAL-OPERATOR name>` | special operator handler
`#<COMPILED-CLOSURE name>` | compiled function, if `lisp:*print-closure*` is `nil`
`#<CLOSURE name ...>` | interpreted function
`#<FRAME-POINTER #x...>` | pointer to a stack frame
`#<DISABLED POINTER>` | frame pointer which has become invalid on exit from the corresponding `block` or `tagbody`
`#<...-STREAM ...>` | stream
`#<PACKAGE name>` | package
`#<HASH-TABLE #x...>` | hash table, if `*print-array*` is `nil`
`#<READTABLE #x...>` | readtable
`#<SYMBOL-MACRO form>` | symbol-macro handler
`#<FOREIGN-POINTER #x...>` | foreign pointer (Platform dependent: UNIX, Win32, Amiga platforms only.)
`#<FOREIGN-ADDRESS #x...>` | foreign address (Platform dependent: UNIX, Win32 platforms only.)
`#<FOREIGN-VARIABLE name #x...>` | foreign variable (Platform dependent: UNIX, Win32 platforms only.)
`#<FOREIGN-FUNCTION name #x...>` | foreign function (Platform dependent: UNIX, Win32 platforms only.)
`#<UNBOUND>` | "value" of a symbol without value, "value" of an unsupplied optional or keyword argument
`#<SPECIAL REFERENCE>` | environment marker for variables declared `special`
`#<DOT>` | internal `read` result for "."
`#<END OF FILE>` | internal `read` result, when the end of file is reached
`#<READ-LABEL ...>` | intermediate `read` result for #n#
`#<ADDRESS #x...>` | machine address, should not occur
`#<SYSTEM-POINTER #x...>` | should not occur

### characters

`#\` allows inputting characters of arbitrary code: `#\Code231` yields the character `(code-char 231.)`.

### Additional read dispatch macros

- `#Y` is used to read compiled functions and to set the current input stream's encoding.
- `#""` is used to read pathnames: `#"test.lisp"` is the value of `(pathname "test.lisp")`
  Platform dependent: DOS, OS/2, Win32 platforms only.
    As in all strings, backslashes must be written twice here: `#"A:\\programs\\test.lisp"`
  Platform dependent: Acorn platforms only.
    As in all strings, backslashes must be written twice here: `#"\\.test.lisp"`

### readtable-case

When the value of `(readtable-case readtable)` is `:invert`, it applies to the package name and the symbol name of a symbol separately (not to the entire token at once). An alternative to the use of `readtable-case` is the use of the `:case-sensitive` option to `make-package`, `in-package` and `defpackage`.

#### listen, read-char-no-hang

`(lisp:read-char-will-hang-p stream)`
  `lisp:read-char-will-hang-p` queries the stream's input status. It returns `nil` if `read-char` and `peek-char` with a peek-type of `nil` will return immediately. Otherwise it returns true.

  Note the difference with the standard `listen` function: When the end-of-stream is reached, `listen` returns `nil`, whereas `lisp:read-char-will-hang-p` returns true.

  Note also that `lisp:read-char-will-hang-p` is not a good mean to test for end-of-stream: If `lisp:read-char-will-hang-p` returns `t`, this does not mean that the stream will deliver more characters. It only means that it is not known at this moment whether the stream is already at end-of-stream, or will deliver more characters.

## Chapter 24: System Construction

### 24.2: The System Construction Dictionary

The compiler can be called not only by the functions `compile`, `compile-file` and `disassemble`, but also by the declaration `(compile)`.

#### compile-file

`(compile-file input-file &key :output-file :listing :warnings :verbose :print)` compiles a file to platform-independent bytecode.

input-file
  should be a pathname/string/symbol.
`:output-file`
  should be `nil` or `t` or a pathname/string/symbol or an output-stream. The default is `t`.
`:listing`
  should be `nil` or `t` or a pathname/string/symbol or an output-stream. The default is `nil`.
`:warnings`
  specifies whether warnings should also appear on the screen.
`:verbose`
  specifies whether error messages should also appear on the screen.
`:print`
  specifies whether an indication which forms are being compiled should appear on the screen.

The variables `lisp:*compile-warnings*`, `*compile-verbose*`, `*compile-print*` provide defaults for the `:warnings`, `:verbose`, `:print` keyword arguments, respectively. For each input file (default file type: `#p".lisp"`) the following files are generated:

File | When | Default file type | Contents
--- | --- | --- | ---
output file | only if `:output-file` is not `nil` | `#p".fas"` | can be loaded using the `load` function.
auxiliary output file | only if `:output-file` is not `nil` | `#p".lib"` | used by `compile-file` when compiling a `require` form referring to the input file.
listing file | only if `:listing` is not `nil` | `#p".lis"` | disassembly of the output file.
C output file | only if `:output-file` is not `nil` | `#p".c"` | foreign function interface; this file is deleted if it is empty.

#### compile-file-pathname

The default for the `:output-file` argument is `t`, which means `#p".fas"`.

#### require

The function `require` receives as optional argument either a pathname or a list of pathnames: files to be loaded if the required module is not already in memory.

#### load

`load` has two additional keywords `:echo` and `:compiling`.

`(load filename &key :verbose :print :echo :if-does-not-exist :compiling)`

`:verbose t`
  causes `load` to emit a short message that a file is being loaded. The default is `*load-verbose*`, which is initially `t`.
`:print t`
  causes `load` to print the value of each form. The default is `*load-print*`, which is initially `nil`.
`:echo t`
  causes the input from the file to be echoed to `*standard-output*` (normally to the screen). Should there be an error in the file, you can see at one glance where it is. The default is `lisp:*load-echo*`, which is initially `nil`.
`:compiling t`
  causes each form read to be compiled on the fly. The compiled code is executed at once and - in contrast to `compile-file` - not written to a file. The default is `lisp:*load-compiling*`, which is initially `nil`.

The variable `lisp:*load-paths*` contains a list of directories where program files are searched - additionally to the specified or current directory - by `load`, `require`, `compile-file`.

#### *features*

The variable `*features*` initially contains the symbols

`:CLISP` | the name of this implementation
`:ANSI-CL` | if invoked with `-a` command line option.
`:COMMON-LISP`
`:CLTL2`
`:INTERPRETER`
`:COMPILER`
`:LOGICAL-PATHNAMES`
`:FFI` | if a foreign function interface is supported (Platform dependent: many UNIX, Win32 platforms only)
`:GETTEXT` | if internationalization using the GNU gettext package is supported (Platform dependent: most UNIX platforms only)
`:UNICODE` | if Unicode (ISO 10646) characters are supported
`:LOOP`
`:CLOS`
`:AMIGA` | if hardware = Amiga and operating system = Exec/AmigaDOS
`:DOS` | if hardware = PC (clone) and operating system = DOS
`:OS/2` | if hardware = PC (clone) and operating system = OS/2
`:WIN32` | if hardware = PC (clone) and operating system = Win32 (Windows 95/98/NT)
`:PC386` | if hardware = PC (clone) with a 386/486/586/686 CPU
`:UNIX` | if operating system = Unix (yes, in this case the hardware is irrelevant!)

## Chapter 25: Environment

### 25.1.2 Debugging Utilities

The debugger may be invoked through the functions `invoke-debugger`, `break`, `signal`, `error`, `cerror`, `warn`. The stepper is invoked through the macro `step`. Debugger and stepper execute subordinate read-eval-print loops (called "break loops") which are similar to the main read-eval-print loop except for the prompt and the set of available commands. Commands must be typed literally, without surrounding quotes or white space. Each command has a keyword abbreviation, indicated in the second column.

Commands common to the main loop, the debugger and the stepper:

`Help` | :h | prints a list of available commands.

Commands common to the debugger and the stepper:

`Abort` | :a | abort to the next most recent read-eval-print loop.
`Unwind` | :uw | abort to the next most recent read-eval-print loop.

The stack is organized into frames and other stack elements. Usually every invocation of an interpreted function and every evaluation of an interpreted form corresponds to one stack frame. Special forms such as `let`, `let*`, `unwind-protect` and `catch` produce special kinds of stack frames.

In a break loop there is a current stack frame, which is initially the most recent stack frame but can be moved using the debugger commands `Up` and `Down`.

Evaluation of forms in a break loop occurs in the lexical environment of the current stack frame but in the dynamic environment of the debugger's caller. This means that to inspect or modify a lexical variable all you have to do is to move to the current stack frame just below the frame that corresponds to the form or the function call that binds that variable.

There is a current "stack mode" which defines in how much detail the stack is shown by the stack related debugger commands.

Commands common to the debugger and the stepper:

`Error` | :e | Print the recent Error Message.
`Mode-1` | :m1 | sets the current mode to 1: all the stack elements are considered. This mode is fine for debugging compiled functions.
`Mode-2` | :m2 | sets the current mode to 2: all the frames are considered.
`Mode-3` | :m3 | sets the current mode to 3: only lexical frames (frames that correspond to special forms that modify the lexical environment) are considered.
`Mode-4` | :m4 | sets the current mode to 4 (the default): only `eval` and `apply` frames are considered. Every evaluation of a form in the interpreter corresponds to an EVAL frame.
`Mode-5` | :m5 | sets the current mode to 5: only `apply` frames are considered. Every invocation of an interpreted function corresponds to one `apply` frame.
`Where` | :w | shows the current stack frame.
`Up` | :u | goes up one frame, i.e., to the caller if in mode-5
`Down` | :d | does down one frame, i.e., to the callee if in mode-5
`Top` | :t | goes to top frame, i.e., to the top-level form if in mode-4
`Bottom` | :b | goes to bottom (most recent) frame, i.e., most probably to the form or function that caused the debugger to be entered.
`Backtrace` | :bt | lists the stack in current mode, bottom frame first, top frame last.
`Backtrace-1` | :bt1 | lists the stack in mode 1.
`Backtrace-2` | :bt2 | lists the stack in mode 2.
`Backtrace-3` | :bt3 | lists the stack in mode 3.
`Backtrace-4` | :bt4 | lists the stack in mode 4.
`Backtrace-5` | :bt5 | lists the stack in mode 5.
`Frame-limit` | :fl | set the frame-limit. This many frames will be printed in a backtrace at most.
`Backtrace-l` | :bl | list stack in current mode. Limit of frames to print will be prompted for.

If the current stack frame is an `eval` or `apply` frame, the following commands are available as well:

`Break+` | :br+ | sets a breakpoint in the current frame. When the corresponding form or function will be left, the debugger will be entered again, with the variable `*trace-values*` containing a list of its values.
`Break-` | :br- | removes a breakpoint from the current frame.
`Redo` | :rd | re-evaluates the corresponding form or function call. This command can be used to restart parts of a computation without aborting it entirely.
`Return` | :rt | leaves the current frame. You will be prompted for the return values.

Commands specific to the debugger:

`Continue` | :c | continues evaluation of the program.

Commands specific to the stepper:

`Step` | :s | step into a form: evaluate this form in single step mode
`Next` | :n | step over a form: evaluate this form at once
`Over` | :o | step over this level: evaluate at once up to the next return
`Continue` | :c | switch off single step mode, continue evaluation

The stepper is usually used like this: If some form returns a strange value or results in an error, call `(step form)` and navigate using the commands `Step` and `Next` until you reach the form you regard as responsible. If you are too fast (execute `Next` once and get the error), there is no way back; you have to restart the entire stepper session. If you are too slow (stepped into a function or a form which certainly is OK), a couple of `Next` commands or one `Over` command will help.

### 25.2 The Environment Dictionary

#### disassemble

Platform dependent: UNIX platforms only.
  `disassemble` can disassemble to machine code, provided that GNU gdb is present. In that case the argument may be a `system-function`, a `foreign-function`, a special operator indicator, a symbol denoting one of these, a number, or a string.

#### uncompile

The function `uncompile` does the converse of `compile`: `(uncompile function-name)` reverts an interpreted function that has been entered or loaded in the same session and then compiled back to its interpreted form.

#### documentation

No on-line documentation is available for the system functions (yet).

#### trace

`(trace fun ...)` makes the functions fun, ... traced. Syntax of fun: Either a symbol: symbol or a list of a symbol and some keywords and arguments (which must come in pairs!): `(symbol`

`[:suppress-if form]` | no trace output as long as form is true
`[:step-if form]` | invokes the stepper as soon as form is true
`[:pre form]` | evaluates form before calling the function
`[:post form]` | evaluates form after return from the function
`[:pre-break-if form]` | goes into the break loop before calling the function if form is true
`[:post-break-if form]` | goes into the break loop after return from the function if form is true
`[:pre-print form]` | prints the values of form before calling the function
`[:post-print form]` | prints the values of form after return from the function
`[:print form]` | prints the values of form both before calling and after return from the function

`)`

In all these forms you can access

the function itself | as `lisp:*trace-function*`,
the arguments to the function | as `lisp:*trace-args*`,
the function/macro call as form | as `lisp:*trace-form*`,
after return from the function: the list of return values from the function call | as `lisp:*trace-values*`,

and you can leave the function call with specified values by using `return`.

`trace` and `untrace` are also applicable to functions `(setf symbol)` and to macros, but not to locally defined functions and macros.

#### inspect

The function `inspect` takes an additional keyword argument `:frontend`. Two frontends are available at this time:

`:tty`
  interact with the user via the terminal.
`:http`
  interact with the user using a Web browser, such as Emacs/W3 or netscape.

#### lisp:space

The macro `lisp:space` is like the macro `time`: `(lisp:space form)` evaluates the form, and, as a side effect, outputs information about the memory allocations caused by this evaluation. It also prints everything printed by `time`.

#### room

The function `room` returns two values: the number of bytes currently occupied by Lisp objects, and the number of bytes that can be allocated before the next regular garbage collection occurs.

The function `lisp:gc` starts global garbage collection and its return value has the same meaning as the second value of `room`.

#### time macro

The timing data printed by the macro `time` includes: The real time (elapsed time), the run time (processor time for this process), the number of bytes allocated (use the `lisp:space` macro for more detailed analysis), and the number of GCs performed, if any.

#### ed

The function `ed` calls the external editor specified by the variable `lisp:*editor*` (see `config.lisp`). If the argument is a function name which was defined in the current session (not loaded from a file), the program text to be edited is a pretty-printed version (without comments) of the text which was used to define the function.

#### clock time

Platform dependent: DOS, OS/2, Amiga, Acorn platforms only.
  The variable `lisp:*default-time-zone*` contains the default time zone used by `encode-universal-time` and `decode-universal-time`. It is initially set to -1 (which means 1 hour east of Greenwich, i.e., Mid European Time).

The timezone in a decoded time must not necessarily be an integer, but (as float or rational number) it should be a multiple of `1/3600`.

Platform dependent: | DOS, OS/2, Acorn | Amiga | UNIX | Win32
--- | --- | --- | --- | ---
`internal-time-units-per-second` | 100 | 50 | 1,000,000 | 10,000,000

`get-internal-run-time` returns the amount of run time consumed by the current CLISP process since its startup.

#### machine

Platform dependent: UNIX, Win32 platforms only.
  The functions `short-site-name`, `long-site-name` should be defined in a site-specific `config.lisp` file.
Platform dependent: DOS, OS/2, Amiga, Acorn platforms only.
  The functions `machine-type`, `machine-version`, `machine-instance` and `short-site-name`, `long-site-name` should be defined by every user in his site-specific `config.lisp` file.

#### apropos, apropos-list

The search performed by `apropos` and `apropos-list` is case-insensitive.

#### dribble

If `dribble` is called with an argument, and dribbling is already enabled, a warning is printed, and the new dribbling request is ignored.

## Chapter 26: Glossary

No notes.

## Appendix

No notes.

## X3J13 Issue Index

This is the list of ANSI CL issues and their current status in CLISP, i.e., whether CLISP supports code that makes use of the functionality specified by the vote.

&ENVIRONMENT-BINDING-ORDER:FIRST
  yes
ACCESS-ERROR-NAME
  yes
ADJUST-ARRAY-DISPLACEMENT
  yes
ADJUST-ARRAY-FILL-POINTER
  yes
ADJUST-ARRAY-NOT-ADJUSTABLE:IMPLICIT-COPY
  no
ALLOCATE-INSTANCE:ADD
  yes
ALLOW-LOCAL-INLINE:INLINE-NOTINLINE
  yes
ALLOW-OTHER-KEYS-NIL:PERMIT
  yes
AREF-1D
  yes
ARGUMENT-MISMATCH-ERROR-AGAIN:CONSISTENT
  yes
ARGUMENT-MISMATCH-ERROR-MOON:FIX
  yes
ARGUMENT-MISMATCH-ERROR:MORE-CLARIFICATIONS
  yes, except for argument list checking in `call-next-method` in compiled code (items 11,12)
ARGUMENTS-UNDERSPECIFIED:SPECIFY
  yes
ARRAY-DIMENSION-LIMIT-IMPLICATIONS:ALL-FIXNUM
  no
ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING
  yes for arrays, no for complex numbers
ASSERT-ERROR-TYPE:ERROR
  yes
ASSOC-RASSOC-IF-KEY
  yes
ASSOC-RASSOC-IF-KEY:YES
  yes
BOA-AUX-INITIALIZATION:ERROR-ON-READ
  yes
BREAK-ON-WARNINGS-OBSOLETE:REMOVE
  no
BROADCAST-STREAM-RETURN-VALUES:CLARIFY-MINIMALLY
  no
BUTLAST-NEGATIVE:SHOULD-SIGNAL
  yes
CHANGE-CLASS-INITARGS:PERMIT
  no
CHAR-NAME-CASE:X3J13-MAR-91
  yes
CHARACTER-LOOSE-ENDS:FIX
  yes
CHARACTER-PROPOSAL:2
  yes
CHARACTER-PROPOSAL:2-1-1
  yes
CHARACTER-PROPOSAL:2-1-2
  yes
CHARACTER-PROPOSAL:2-2-1
  yes
CHARACTER-PROPOSAL:2-3-1
  yes
CHARACTER-PROPOSAL:2-3-2
  yes
CHARACTER-PROPOSAL:2-3-3
  yes
CHARACTER-PROPOSAL:2-3-4
  yes
CHARACTER-PROPOSAL:2-3-5
  yes
CHARACTER-PROPOSAL:2-3-6
  yes
CHARACTER-PROPOSAL:2-4-1
  yes
CHARACTER-PROPOSAL:2-4-2
  yes
CHARACTER-PROPOSAL:2-4-3
  yes
CHARACTER-PROPOSAL:2-5-2
  yes
CHARACTER-PROPOSAL:2-5-6
  yes
CHARACTER-PROPOSAL:2-5-7
  yes
CHARACTER-PROPOSAL:2-6-1
  yes
CHARACTER-PROPOSAL:2-6-2
  yes
CHARACTER-PROPOSAL:2-6-3
  yes
CHARACTER-PROPOSAL:2-6-5
  yes
CHARACTER-VS-CHAR:LESS-INCONSISTENT-SHORT
  yes
CLASS-OBJECT-SPECIALIZER:AFFIRM
  yes
CLOS-CONDITIONS-AGAIN:ALLOW-SUBSET
  yes
CLOS-CONDITIONS:INTEGRATE
  yes
CLOS-ERROR-CHECKING-ORDER:NO-APPLICABLE-METHOD-FIRST
  yes
CLOS-MACRO-COMPILATION:MINIMAL
  yes
CLOSE-CONSTRUCTED-STREAM:ARGUMENT-STREAM-ONLY
  yes
CLOSED-STREAM-OPERATIONS:ALLOW-INQUIRY
  yes
COERCING-SETF-NAME-TO-FUNCTION:ALL-FUNCTION-NAMES
  yes
COLON-NUMBER
  yes
COMMON-FEATURES:SPECIFY
  yes
COMMON-TYPE:REMOVE
  yes, still present in package LISP
COMPILE-ARGUMENT-PROBLEMS-AGAIN:FIX
  yes
COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS:CLARIFY
  yes
COMPILE-FILE-OUTPUT-FILE-DEFAULTS:INPUT-FILE
  yes
COMPILE-FILE-PACKAGE
  yes
COMPILE-FILE-PATHNAME-ARGUMENTS:MAKE-CONSISTENT
  yes
COMPILE-FILE-SYMBOL-HANDLING:NEW-REQUIRE-CONSISTENCY
  yes
COMPILED-FUNCTION-REQUIREMENTS:TIGHTEN
  yes
COMPILER-DIAGNOSTICS:USE-HANDLER
  no
COMPILER-LET-CONFUSION:ELIMINATE
  yes
COMPILER-VERBOSITY:LIKE-LOAD
  yes
COMPILER-WARNING-STREAM
  yes
COMPLEX-ATAN-BRANCH-CUT:TWEAK
  yes
COMPLEX-ATANH-BOGUS-FORMULA:TWEAK-MORE
  yes
COMPLEX-RATIONAL-RESULT:EXTEND
  yes
COMPUTE-APPLICABLE-METHODS:GENERIC
  yes
CONCATENATE-SEQUENCE:SIGNAL-ERROR
  yes
CONDITION-ACCESSORS-SETFABLE:NO
  yes
CONDITION-RESTARTS:BUGGY
  yes
CONDITION-RESTARTS:PERMIT-ASSOCIATION
  yes, except for (6)
CONDITION-SLOTS:HIDDEN
  yes
CONS-TYPE-SPECIFIER:ADD
  yes
CONSTANT-CIRCULAR-COMPILATION:YES
  yes
CONSTANT-COLLAPSING:GENERALIZE
  yes
CONSTANT-COMPILABLE-TYPES:SPECIFY
  yes
CONSTANT-FUNCTION-COMPILATION:NO
  no
CONSTANT-MODIFICATION:DISALLOW
  yes
CONSTANTP-DEFINITION:INTENTIONAL
  yes
CONSTANTP-ENVIRONMENT:ADD-ARG
  no
CONTAGION-ON-NUMERICAL-COMPARISONS:TRANSITIVE
  yes
COPY-SYMBOL-COPY-PLIST:COPY-LIST
  yes
COPY-SYMBOL-PRINT-NAME:EQUAL
  yes
DATA-IO:ADD-SUPPORT
  yes for `*print-readably*`, `*read-eval*` and `with-standard-io-syntax`, no for everything else
DATA-TYPES-HIERARCHY-UNDERSPECIFIED
  yes
DEBUGGER-HOOK-VS-BREAK:CLARIFY
  no
DECLARATION-SCOPE:NO-HOISTING
  no
DECLARE-ARRAY-TYPE-ELEMENT-REFERENCES:RESTRICTIVE
  yes
DECLARE-FUNCTION-AMBIGUITY:DELETE-FTYPE-ABBREVIATION
  yes
DECLARE-MACROS:FLUSH
  no
DECLARE-TYPE-FREE:LEXICAL
  yes
DECLS-AND-DOC
  ??
DECODE-UNIVERSAL-TIME-DAYLIGHT:LIKE-ENCODE
  yes
DEFCONSTANT-SPECIAL:NO
  yes
DEFGENERIC-DECLARE:ALLOW-MULTIPLE
  yes
DEFINE-COMPILER-MACRO:X3J13-NOV89
  no
DEFINE-CONDITION-SYNTAX:INCOMPATIBLY-MORE-LIKE-DEFCLASS+EMPHASIZE-READ-ONLY
  yes
DEFINE-METHOD-COMBINATION-BEHAVIOR:CLARIFY
  no
DEFINING-MACROS-NON-TOP-LEVEL:ALLOW
  no
DEFMACRO-BLOCK-SCOPE:EXCLUDES-BINDINGS
  yes
DEFMACRO-LAMBDA-LIST:TIGHTEN-DESCRIPTION
  yes
DEFMETHOD-DECLARATION-SCOPE:CORRESPONDS-TO-BINDINGS
  yes
DEFPACKAGE:ADDITION
  yes
DEFSTRUCT-CONSTRUCTOR-KEY-MIXTURE:ALLOW-KEY
  yes
DEFSTRUCT-CONSTRUCTOR-OPTIONS:EXPLICIT
  yes
DEFSTRUCT-CONSTRUCTOR-SLOT-VARIABLES:NOT-BOUND
  no (furthermore it gets hairy when applied to BOA constructors)
DEFSTRUCT-COPIER-ARGUMENT-TYPE:RESTRICT
  yes
DEFSTRUCT-COPIER:ARGUMENT-TYPE
  yes
DEFSTRUCT-DEFAULT-VALUE-EVALUATION:IFF-NEEDED
  yes
DEFSTRUCT-INCLUDE-DEFTYPE:EXPLICITLY-UNDEFINED
  yes
DEFSTRUCT-PRINT-FUNCTION-AGAIN:X3J13-MAR-93
  yes
DEFSTRUCT-PRINT-FUNCTION-INHERITANCE:YES
  yes
DEFSTRUCT-REDEFINITION:ERROR
  yes
DEFSTRUCT-SLOTS-CONSTRAINTS-NAME:DUPLICATES-ERROR
  yes
DEFSTRUCT-SLOTS-CONSTRAINTS-NUMBER
  yes
DEFTYPE-DESTRUCTURING:YES
  yes
DEFTYPE-KEY:ALLOW
  yes
DEFVAR-DOCUMENTATION:UNEVALUATED
  yes
DEFVAR-INIT-TIME:NOT-DELAYED
  yes
DEFVAR-INITIALIZATION:CONSERVATIVE
  yes
DEPRECATION-POSITION:LIMITED
  yes
DESCRIBE-INTERACTIVE:NO
  yes
DESCRIBE-UNDERSPECIFIED:DESCRIBE-OBJECT
  yes
DESTRUCTIVE-OPERATIONS:SPECIFY
  yes
DESTRUCTURING-BIND:NEW-MACRO
  yes
DISASSEMBLE-SIDE-EFFECT:DO-NOT-INSTALL
  yes
DISPLACED-ARRAY-PREDICATE:ADD
  yes
DO-SYMBOLS-BLOCK-SCOPE:ENTIRE-FORM
  yes
DO-SYMBOLS-DUPLICATES
  yes
DOCUMENTATION-FUNCTION-BUGS:FIX
  no
DOCUMENTATION-FUNCTION-TANGLED:REQUIRE-ARGUMENT
  no
DOTIMES-IGNORE:X3J13-MAR91
  yes
DOTTED-LIST-ARGUMENTS:CLARIFY
  yes
DOTTED-MACRO-FORMS:ALLOW
  yes
DRIBBLE-TECHNIQUE
  yes
DYNAMIC-EXTENT-FUNCTION:EXTEND
  yes
DYNAMIC-EXTENT:NEW-DECLARATION
  yes
EQUAL-STRUCTURE:MAYBE-STATUS-QUO
  no for `equalp` on hash tables, yes for everything else
ERROR-TERMINOLOGY-WARNING:MIGHT
  yes
EVAL-OTHER:SELF-EVALUATE
  yes
EVAL-TOP-LEVEL:LOAD-LIKE-COMPILE-FILE
  yes, except maybe if `load` :compiling `t`
EVAL-WHEN-NON-TOP-LEVEL:GENERALIZE-EVAL-NEW-KEYWORDS
  no
EVAL-WHEN-OBSOLETE-KEYWORDS:X3J13-MAR-1993
  no
EVALHOOK-STEP-CONFUSION:FIX
  yes
EVALHOOK-STEP-CONFUSION:X3J13-NOV-89
  yes
EXIT-EXTENT-AND-CONDITION-SYSTEM:LIKE-DYNAMIC-BINDINGS
  yes
EXIT-EXTENT:MINIMAL
  yes, actually implement MEDIUM
EXPT-RATIO:P.211
  yes
EXTENSIONS-POSITION:DOCUMENTATION
  yes
EXTERNAL-FORMAT-FOR-EVERY-FILE-CONNECTION:MINIMUM
  no
EXTRA-RETURN-VALUES:NO
  yes
FILE-OPEN-ERROR:SIGNAL-FILE-ERROR
  no
FIXNUM-NON-PORTABLE:TIGHTEN-DEFINITION
  no
FLET-DECLARATIONS
  yes
FLET-DECLARATIONS:ALLOW
  yes
FLET-IMPLICIT-BLOCK:YES
  yes
FLOAT-UNDERFLOW:ADD-VARIABLES
  yes
FLOATING-POINT-CONDITION-NAMES:X3J13-NOV-89
  yes
FORMAT-ATSIGN-COLON
  yes
FORMAT-COLON-UPARROW-SCOPE
  yes
FORMAT-COMMA-INTERVAL
  yes
FORMAT-E-EXPONENT-SIGN:FORCE-SIGN
  yes
FORMAT-OP-C
  yes
FORMAT-PRETTY-PRINT:YES
  yes, except that `~F`, `~E`, `~G`, `~$` also bind `*print-base*` to 10 and `*print-radix*` to `nil`
FORMAT-STRING-ARGUMENTS:SPECIFY
  yes
FUNCTION-CALL-EVALUATION-ORDER:MORE-UNSPECIFIED
  yes
FUNCTION-COMPOSITION:JAN89-X3J13
  yes
FUNCTION-DEFINITION:JAN89-X3J13
  yes
FUNCTION-NAME:LARGE
  yes
FUNCTION-TYPE
  yes
FUNCTION-TYPE-ARGUMENT-TYPE-SEMANTICS:RESTRICTIVE
  yes
FUNCTION-TYPE-KEY-NAME:SPECIFY-KEYWORD
  yes
FUNCTION-TYPE-REST-LIST-ELEMENT:USE-ACTUAL-ARGUMENT-TYPE
  yes
FUNCTION-TYPE:X3J13-MARCH-88
  yes
GENERALIZE-PRETTY-PRINTER:UNIFY
  no
GENERIC-FLET-POORLY-DESIGNED:DELETE
  yes
GENSYM-NAME-STICKINESS:LIKE-TEFLON
  yes
GENTEMP-BAD-IDEA:DEPRECATE
  yes
GET-MACRO-CHARACTER-READTABLE:NIL-STANDARD
  yes
GET-SETF-METHOD-ENVIRONMENT:ADD-ARG
  yes
HASH-TABLE-ACCESS:X3J13-MAR-89
  yes
HASH-TABLE-KEY-MODIFICATION:SPECIFY
  yes
HASH-TABLE-PACKAGE-GENERATORS:ADD-WITH-WRAPPER
  no
HASH-TABLE-REHASH-SIZE-INTEGER
  yes
HASH-TABLE-SIZE:INTENDED-ENTRIES
  yes
HASH-TABLE-TESTS:ADD-EQUALP
  yes
IEEE-ATAN-BRANCH-CUT:SPLIT
  yes
IGNORE-USE-TERMINOLOGY:VALUE-ONLY
  yes
IMPORT-SETF-SYMBOL-PACKAGE
  no
IN-PACKAGE-FUNCTIONALITY:MAR89-X3J13
  yes
IN-SYNTAX:MINIMAL
  yes
INITIALIZATION-FUNCTION-KEYWORD-CHECKING
  ??
ISO-COMPATIBILITY:ADD-SUBSTRATE
  yes
JUN90-TRIVIAL-ISSUES:11
  yes
JUN90-TRIVIAL-ISSUES:14
  yes
JUN90-TRIVIAL-ISSUES:24
  yes
JUN90-TRIVIAL-ISSUES:25
  yes
JUN90-TRIVIAL-ISSUES:27
  yes for `the`, no for `apply` (spec not clear)
JUN90-TRIVIAL-ISSUES:3
  yes
JUN90-TRIVIAL-ISSUES:4
  yes
JUN90-TRIVIAL-ISSUES:5
  yes
JUN90-TRIVIAL-ISSUES:9
  yes
KEYWORD-ARGUMENT-NAME-PACKAGE:ANY
  yes
LAST-N
  yes
LCM-NO-ARGUMENTS:1
  yes
LEXICAL-CONSTRUCT-GLOBAL-DEFINITION:UNDEFINED
  yes
LISP-PACKAGE-NAME:COMMON-LISP
  yes
LISP-SYMBOL-REDEFINITION-AGAIN:MORE-FIXES
  yes
LISP-SYMBOL-REDEFINITION:MAR89-X3J13
  yes
LOAD-OBJECTS:MAKE-LOAD-FORM
  no
LOAD-TIME-EVAL:R**2-NEW-SPECIAL-FORM
  obsolete
LOAD-TIME-EVAL:R**3-NEW-SPECIAL-FORM
  yes, except for macro expansion at compile time
LOAD-TRUENAME:NEW-PATHNAME-VARIABLES
  yes
LOCALLY-TOP-LEVEL:SPECIAL-FORM
  yes
LOOP-AND-DISCREPANCY:NO-REITERATION
  yes
LOOP-FOR-AS-ON-TYPO:FIX-TYPO
  yes
LOOP-INITFORM-ENVIRONMENT:PARTIAL-INTERLEAVING-VAGUE
  no
LOOP-MISCELLANEOUS-REPAIRS:FIX
  yes
LOOP-NAMED-BLOCK-NIL:OVERRIDE
  yes
LOOP-PRESENT-SYMBOLS-TYPO:FLUSH-WRONG-WORDS
  yes
LOOP-SYNTAX-OVERHAUL:REPAIR
  yes
MACRO-AS-FUNCTION:DISALLOW
  yes
MACRO-DECLARATIONS:MAKE-EXPLICIT
  yes
MACRO-ENVIRONMENT-EXTENT:DYNAMIC
  yes
MACRO-FUNCTION-ENVIRONMENT
  obsolete
MACRO-FUNCTION-ENVIRONMENT:YES
  yes
MACRO-SUBFORMS-TOP-LEVEL-P:ADD-CONSTRAINTS
  no
MACROEXPAND-HOOK-DEFAULT:EXPLICITLY-VAGUE
  yes
MACROEXPAND-HOOK-INITIAL-VALUE:IMPLEMENTATION-DEPENDENT
  yes
MACROEXPAND-RETURN-VALUE:TRUE
  yes
MAKE-LOAD-FORM-CONFUSION:REWRITE
  no
MAKE-LOAD-FORM-SAVING-SLOTS:NO-INITFORMS
  no
MAKE-PACKAGE-USE-DEFAULT:IMPLEMENTATION-DEPENDENT
  yes
MAP-INTO:ADD-FUNCTION
  yes
MAPPING-DESTRUCTIVE-INTERACTION:EXPLICITLY-VAGUE
  yes
METACLASS-OF-SYSTEM-CLASS:UNSPECIFIED
  yes
METHOD-COMBINATION-ARGUMENTS:CLARIFY
  no
METHOD-INITFORM:FORBID-CALL-NEXT-METHOD
  no
MUFFLE-WARNING-CONDITION-ARGUMENT
  yes
MULTIPLE-VALUE-SETQ-ORDER:LIKE-SETF-OF-VALUES
  yes
MULTIPLE-VALUES-LIMIT-ON-VARIABLES:UNDEFINED
  yes
NINTERSECTION-DESTRUCTION
  yes
NINTERSECTION-DESTRUCTION:REVERT
  yes
NOT-AND-NULL-RETURN-VALUE:X3J13-MAR-93
  yes
NTH-VALUE:ADD
  yes
OPTIMIZE-DEBUG-INFO:NEW-QUALITY
  yes
PACKAGE-CLUTTER:REDUCE
  no
PACKAGE-DELETION:NEW-FUNCTION
  yes
PACKAGE-FUNCTION-CONSISTENCY:MORE-PERMISSIVE
  yes
PARSE-ERROR-STREAM:SPLIT-TYPES
  yes
PATHNAME-COMPONENT-CASE:KEYWORD-ARGUMENT
  yes
PATHNAME-COMPONENT-VALUE:SPECIFY
  no
PATHNAME-HOST-PARSING:RECOGNIZE-LOGICAL-HOST-NAMES
  no
PATHNAME-LOGICAL:ADD
  yes
PATHNAME-PRINT-READ:SHARPSIGN-P
  yes
PATHNAME-STREAM
  yes
PATHNAME-STREAM:FILES-OR-SYNONYM
  yes
PATHNAME-SUBDIRECTORY-LIST:NEW-REPRESENTATION
  no
PATHNAME-SYMBOL
  no
PATHNAME-SYNTAX-ERROR-TIME:EXPLICITLY-VAGUE
  yes
PATHNAME-UNSPECIFIC-COMPONENT:NEW-TOKEN
  no
PATHNAME-WILD:NEW-FUNCTIONS
  yes
PEEK-CHAR-READ-CHAR-ECHO:FIRST-READ-CHAR
  yes
PLIST-DUPLICATES:ALLOW
  yes
PRETTY-PRINT-INTERFACE
  no
PRINC-READABLY:X3J13-DEC-91
  yes
PRINT-CASE-BEHAVIOR:CLARIFY
  yes
PRINT-CASE-PRINT-ESCAPE-INTERACTION:VERTICAL-BAR-RULE-NO-UPCASE
  no
PRINT-CIRCLE-SHARED:RESPECT-PRINT-CIRCLE
  yes
PRINT-CIRCLE-STRUCTURE:USER-FUNCTIONS-WORK
  yes
PRINT-READABLY-BEHAVIOR:CLARIFY
  yes
PRINTER-WHITESPACE:JUST-ONE-SPACE
  yes
PROCLAIM-ETC-IN-COMPILE-FILE:NEW-MACRO
  yes
PUSH-EVALUATION-ORDER:FIRST-ITEM
  yes
PUSH-EVALUATION-ORDER:ITEM-FIRST
  yes
PUSHNEW-STORE-REQUIRED:UNSPECIFIED
  yes
QUOTE-SEMANTICS:NO-COPYING
  yes
RANGE-OF-COUNT-KEYWORD:NIL-OR-INTEGER
  yes, when `lisp:*sequence-count-ansi*` is non-`nil`; otherwise negative `:count` values are not allowed.
RANGE-OF-START-AND-END-PARAMETERS:INTEGER-AND-INTEGER-NIL
  yes
READ-AND-WRITE-BYTES:NEW-FUNCTIONS
  yes
READ-CASE-SENSITIVITY:READTABLE-KEYWORDS
  yes
READ-MODIFY-WRITE-EVALUATION-ORDER:DELAYED-ACCESS-STORES
  no
READ-SUPPRESS-CONFUSING:GENERALIZE
  yes, except that `read-delimited-list` still constructs a list
READER-ERROR:NEW-TYPE
  yes
REAL-NUMBER-TYPE:X3J13-MAR-89
  yes
RECURSIVE-DEFTYPE:EXPLICITLY-VAGUE
  yes
REDUCE-ARGUMENT-EXTRACTION
  yes
REMF-DESTRUCTION-UNSPECIFIED:X3J13-MAR-89
  yes
REQUIRE-PATHNAME-DEFAULTS-AGAIN:X3J13-DEC-91
  yes
REQUIRE-PATHNAME-DEFAULTS-YET-AGAIN:RESTORE-ARGUMENT
  yes, except that `require` wants a pathname, not a list of pathnames
REQUIRE-PATHNAME-DEFAULTS:ELIMINATE
  superseded by REQUIRE-PATHNAME-DEFAULTS-AGAIN:X3J13-DEC-91
REST-LIST-ALLOCATION:MAY-SHARE
  yes
RESULT-LISTS-SHARED:SPECIFY
  yes
RETURN-VALUES-UNSPECIFIED:SPECIFY
  yes
ROOM-DEFAULT-ARGUMENT:NEW-VALUE
  yes
SELF-MODIFYING-CODE:FORBID
  yes
SEQUENCE-TYPE-LENGTH:MUST-MATCH
  yes
SETF-APPLY-EXPANSION:IGNORE-EXPANDER
  no
SETF-FIND-CLASS:ALLOW-NIL
  no
SETF-FUNCTIONS-AGAIN:MINIMAL-CHANGES
  yes
SETF-GET-DEFAULT:EVALUATED-BUT-IGNORED
  yes
SETF-MACRO-EXPANSION:LAST
  yes
SETF-METHOD-VS-SETF-METHOD:RENAME-OLD-TERMS
  yes
SETF-MULTIPLE-STORE-VARIABLES:ALLOW
  yes
SETF-OF-APPLY:ONLY-AREF-AND-FRIENDS
  yes
SETF-OF-VALUES:ADD
  yes
SETF-SUB-METHODS:DELAYED-ACCESS-STORES
  yes
SHADOW-ALREADY-PRESENT
  yes
SHADOW-ALREADY-PRESENT:WORKS
  yes
SHARP-COMMA-CONFUSION:REMOVE
  no
SHARP-O-FOOBAR:CONSEQUENCES-UNDEFINED
  yes
SHARP-STAR-DELIMITER:NORMAL-DELIMITER
  yes
SHARPSIGN-PLUS-MINUS-PACKAGE:KEYWORD
  yes
SLOT-MISSING-VALUES:SPECIFY
  yes
SLOT-VALUE-METACLASSES:LESS-MINIMAL
  yes
SPECIAL-FORM-P-MISNOMER:RENAME
  yes
SPECIAL-TYPE-SHADOWING:CLARIFY
  yes
STANDARD-INPUT-INITIAL-BINDING:DEFINED-CONTRACTS
  yes
STANDARD-REPERTOIRE-GRATUITOUS:RENAME
  yes
STEP-ENVIRONMENT:CURRENT
  yes
STEP-MINIMAL:PERMIT-PROGN
  yes
STREAM-ACCESS:ADD-TYPES-ACCESSORS
  yes
STREAM-CAPABILITIES:INTERACTIVE-STREAM-P
  yes
STRING-COERCION:MAKE-CONSISTENT
  yes
STRING-OUTPUT-STREAM-BASHING:UNDEFINED
  yes
STRUCTURE-READ-PRINT-SYNTAX:KEYWORDS
  yes
SUBSEQ-OUT-OF-BOUNDS
  yes
SUBSEQ-OUT-OF-BOUNDS:IS-AN-ERROR
  yes
SUBSETTING-POSITION:NONE
  yes
SUBTYPEP-ENVIRONMENT:ADD-ARG
  no
SUBTYPEP-TOO-VAGUE:CLARIFY-MORE
  yes
SXHASH-DEFINITION:SIMILAR-FOR-SXHASH
  no
SYMBOL-MACROLET-DECLARE:ALLOW
  yes
SYMBOL-MACROLET-SEMANTICS:SPECIAL-FORM
  yes
SYMBOL-MACROLET-TYPE-DECLARATION:NO
  yes
SYMBOL-MACROS-AND-PROCLAIMED-SPECIALS:SIGNALS-AN-ERROR
  yes
SYMBOL-PRINT-ESCAPE-BEHAVIOR:CLARIFY
  yes
SYNTACTIC-ENVIRONMENT-ACCESS:RETRACTED-MAR91
  yes
TAGBODY-TAG-EXPANSION:NO
  yes
TAILP-NIL:T
  yes
TEST-NOT-IF-NOT:FLUSH-ALL
  yes, but no warning
THE-AMBIGUITY:FOR-DECLARATION
  yes
THE-VALUES:RETURN-NUMBER-RECEIVED
  no
TIME-ZONE-NON-INTEGER:ALLOW
  yes
TYPE-DECLARATION-ABBREVIATION:ALLOW-ALL
  no
TYPE-OF-AND-PREDEFINED-CLASSES:TYPE-OF-HANDLES-FLOATS
  yes
TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND
  yes, except for class `method-combination`
TYPE-OF-UNDERCONSTRAINED:ADD-CONSTRAINTS
  yes
TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS
  yes
UNDEFINED-VARIABLES-AND-FUNCTIONS:COMPROMISE
  yes
UNINITIALIZED-ELEMENTS:CONSEQUENCES-UNDEFINED
  yes, could add error checking
UNREAD-CHAR-AFTER-PEEK-CHAR:DONT-ALLOW
  yes
UNSOLICITED-MESSAGES:NOT-TO-SYSTEM-USER-STREAMS
  yes
VARIABLE-LIST-ASYMMETRY:SYMMETRIZE
  yes
WITH-ADDED-METHODS:DELETE
  yes
WITH-COMPILATION-UNIT:NEW-MACRO
  yes
WITH-OPEN-FILE-DOES-NOT-EXIST:STREAM-IS-NIL
  yes
WITH-OPEN-FILE-SETQ:EXPLICITLY-VAGUE
  yes
WITH-OPEN-FILE-STREAM-EXTENT:DYNAMIC-EXTENT
  yes
WITH-OUTPUT-TO-STRING-APPEND-STYLE:VECTOR-PUSH-EXTEND
  yes
WITH-STANDARD-IO-SYNTAX-READTABLE:X3J13-MAR-91
  yes

## Extensions-1: Platform independent Extensions

### Extensions-1.1. Saving an Image

The function `(lisp:saveinitmem &optional (filename "lispinit.mem") &key :quiet :init-function)` saves the running CLISP's memory to a file. If the `:quiet` argument is not `nil`, the startup banner and the good-bye message will be suppressed. The `:init-function` argument specifies a function that will be executed at startup of the saved image. The starting package of the new image is the one in which you were when you invoked `lisp:saveinitmem`.

### Extensions-1.2. Quitting Lisp

The functions `(lisp:exit [errorp])`, `(lisp:quit [errorp])` and `(lisp:bye [errorp])` - all synonymous - terminate CLISP. If errorp is not `nil`, CLISP aborts with error status, i.e., the environment is informed that the CLISP session did not succeed.

### Extensions-1.3. The Language

The language CLISP uses to communicate with the user can be either `ENGLISH` or `DEUTSCH` (i.e., German) or `FRANCAIS` (i.e., French) or `ESPAÑOL` (i.e. Spanish). More languages can be defined through the macro `lisp:deflanguage`: `(lisp:deflanguage lang)` For such an additional language to take effect, you must install the corresponding message catalog, or translate the messages yourself, using GNU gettext and Emacs po-mode.

The macros `ENGLISH`, `DEUTSCH`, `FRANCAIS` produce strings that depends on the language: `(ENGLISH english-string DEUTSCH deutsch-string FRANCAIS francais-string)` - and all permutations of this - evaluates all of english-string, deutsch-string, francais-string in no particular order and returns the evaluation result corresponding to the user language, be it among these three or not.

This works only for strings. For arbitrary language-dependent Lisp objects, you define one through the macro `lisp:definternational`:

    (lisp:definternational symbol &optional (t default-language))

and add language-dependent values through the macro `lisp:deflocalized`:

    (lisp:deflocalized symbol language value-form)

(One such form for each language. Languages without an assigned value will be treated like the default-language.) You can then access the localized value through the function call

    (lisp:localized symbol &optional language)

### Extensions-1.4. Encodings

An encoding describes the correspondence between characters and raw bytes during input/output via streams with element-type `character`.

An encoding is an object composed of the following facets:

- A character set. This denotes both the set of characters that can be represented and passed through the I/O channel, and the way these characters translate into raw bytes. In this context, for example, "UTF-8" and "UCS-4" are considered different, although they can represent the same set of characters.
- A line terminator mode. This denotes the way newline characters are represented.

#### Character Sets

Platform dependent: Only in CLISP built without compile-time flag `UNICODE`.
  Only one character set is understood: the platform's native (8-bit) character set. See chapter 13.
Platform dependent: Only in CLISP built with compile-time flag `UNICODE`.
  The following character sets are supported, as values of the corresponding (constant) symbol in the `CHARSET` package.
  - `UCS-2` = `UNICODE-16` = `UNICODE-16-BIG-ENDIAN`, the 16-bit Unicode character set. Every character is represented as two bytes.
  - `UNICODE-16-LITTLE-ENDIAN`
  - `UCS-4` = `UNICODE-32` = `UNICODE-32-BIG-ENDIAN`, the 32-bit Unicode character set. Every character is represented as four bytes. Note that CLISP understands only those characters which are already contained in the 16-bit Unicode character set.
  - `UNICODE-32-LITTLE-ENDIAN`
  - `UTF-8`, the 16-bit Unicode character set. Every character is represented as one to three bytes. ASCII characters represent themselves and need one byte per character. Most Latin/Greek/Cyrillic/Hebrew characters need two bytes per character, and the remaining characters need three bytes per character. This is therefore, in general, the most space-efficient encoding of all of Unicode-16.
  - `UTF-16`, the 16-bit Unicode character set. Every character is represented as two bytes.
  - `UTF-7`, the 16-bit Unicode character set. This is a stateful 7-bit encoding. Not all ASCII characters represent themselves.
  - `JAVA`, the 16-bit Unicode character set. ASCII characters represent themselves and need one byte per character. All other characters are represented by \unnnn sequences (nnnn a hexadecimal number) and need 6 bytes per character. While this encoding is very comfortable for editing Unicode files using only ASCII aware tools and editors, it cannot faithfully represent all Unicode text. Only text which does not contain \u (backslash followed by lowercase Latin u) can be faithfully represented by this encoding.
  - `ASCII`, the well-known US-centric 7-bit character set (American Standard Code for Information Interchange).
  - `ISO-8859-1`, an extension of the ASCII character set, suitable for the Afrikaans, Albanian, Basque, Breton, Catalan, Cornish, Danish, Dutch, English, Faeroese, Finnish, French, Frisian, Galician, German, Greenlandic, Icelandic, Irish, Italian, Latin, Luxemburgish, Norwegian, Portuguese, Raeto-Romanic, Scottish, Spanish, and Swedish languages.
  - `ISO-8859-2`, an extension of the ASCII character set, suitable for the Croatian, Czech, German, Hungarian, Polish, Slovak, Slovenian, and Sorbian languages.
  - `ISO-8859-3`, an extension of the ASCII character set, suitable for the Esperanto and Maltese languages.
  - `ISO-8859-4`, an extension of the ASCII character set, suitable for the Estonian, Latvian, Lithuanian and Sami (Lappish) languages.
  - `ISO-8859-5`, an extension of the ASCII character set, suitable for the Bulgarian, Byelorussian, Macedonian, Russian, Serbian, and Ukrainian languages.
  - `ISO-8859-6`, suitable for the Arabic language.
  - `ISO-8859-7`, an extension of the ASCII character set, suitable for the Greek language.
  - `ISO-8859-8`, an extension of the ASCII character set, suitable for the Hebrew language (without punctuation).
  - `ISO-8859-9`, an extension of the ASCII character set, suitable for the Turkish language.
  - `ISO-8859-10`, an extension of the ASCII character set, suitable for the Estonian, Icelandic, Inuit (Greenlandic), Latvian, Lithuanian, and Sami (Lappish) languages.
  - `ISO-8859-13`, an extension of the ASCII character set, suitable for the Estonian, Latvian, Lithuanian, Polish and Sami (Lappish) languages.
  - `ISO-8859-14`, an extension of the ASCII character set, suitable for Irish Gaelic, Manx Gaelic, Scottish Gaelic, and Welsh languages.
  - `ISO-8859-15`, an extension of the ASCII character set, suitable for the ISO-8859-1 languages, with improvements for French, Finnish and the Euro.
  - `ISO-8859-16` an extension of the ASCII character set, suitable for the Rumanian language.
  - `KOI8-R`, an extension of the ASCII character set, a popular character set for the Russian language.
  - `KOI8-U`, an extension of the ASCII character set, a popular character set for the Ukrainian language.
  - `KOI8-RU`, an extension of the ASCII character set, suitable for Russian and/or Ukrainian??
  - `JIS_X0201`, a character set for the Japanese language.
  - `MAC-ARABIC`, a platform specific extension of the ASCII character set.
  - `MAC-CENTRAL-EUROPE`, a platform specific extension of the ASCII character set.
  - `MAC-CROATIAN`, a platform specific extension of the ASCII character set.
  - `MAC-CYRILLIC`, a platform specific extension of the ASCII character set.
  - `MAC-DINGBAT`, a platform specific character set.
  - `MAC-GREEK`, a platform specific extension of the ASCII character set.
  - `MAC-HEBREW`, a platform specific extension of the ASCII character set.
  - `MAC-ICELAND`, a platform specific extension of the ASCII character set.
  - `MAC-ROMAN` = `MACINTOSH`, a platform specific extension of the ASCII character set.
  - `MAC-ROMANIA`, a platform specific extension of the ASCII character set.
  - `MAC-SYMBOL`, a platform specific character set.
  - `MAC-THAI`, a platform specific extension of the ASCII character set.
  - `MAC-TURKISH`, a platform specific extension of the ASCII character set.
  - `MAC-UKRAINE`, a platform specific extension of the ASCII character set.
  - `CP437`, a DOS oldie, a platform specific extension of the ASCII character set.
  - `CP437-IBM`, an IBM variant of `CP437`.
  - `CP737`, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Greek language.
  - `CP775`, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for some Baltic languages.
  - `CP850`, a DOS oldie, a platform specific extension of the ASCII character set.
  - `CP852`, a DOS oldie, a platform specific extension of the ASCII character set.
  - `CP852-IBM`, an IBM variant of `CP852`.
  - `CP855`, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Russian language.
  - `CP857`, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Turkish language.
  - `CP860`, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Portuguese language.
  - `CP860-IBM`, an IBM variant of `CP860`.
  - `CP861`, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Icelandic language.
  - `CP861-IBM`, an IBM variant of `CP861`.
  - `CP862`, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Hebrew language.
  - `CP862-IBM`, an IBM variant of `CP862`.
  - `CP863`, a DOS oldie, a platform specific extension of the ASCII character set.
  - `CP863-IBM`, an IBM variant of `CP863`.
  - `CP864`, a DOS oldie, meant to be suitable for the Arabic language.
  - `CP864-IBM`, an IBM variant of `CP864`.
  - `CP865`, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for some Nordic languages.
  - `CP865-IBM`, an IBM variant of `CP865`.
  - `CP866`, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Russian language.
  - `CP869`, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Greek language.
  - `CP869-IBM`, an IBM variant of `CP869`.
  - `CP874`, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Thai language.
  - `CP874-IBM`, an IBM variant of `CP874`.
  - `WINDOWS-1250` = `CP1250`, a platform specific extension of the ASCII character set, heavily incompatible with ISO-8859-2.
  - `WINDOWS-1251` = `CP1251`, a platform specific extension of the ASCII character set, heavily incompatible with ISO-8859-5, meant to be suitable for the Russian language.
  - `WINDOWS-1252` = `CP1252`, a platform specific extension of the ISO-8859-1 character set.
  - `WINDOWS-1253` = `CP1253`, a platform specific extension of the ASCII character set, gratuitously incompatible with ISO-8859-7, meant to be suitable for the Greek language.
  - `WINDOWS-1254` = `CP1254`, a platform specific extension of the ISO-8859-9 character set.
  - `WINDOWS-1255` = `CP1255`, a platform specific extension of the ASCII character set, gratuitously incompatible with ISO-8859-8, meant to be suitable for the Hebrew language.
  - `WINDOWS-1256` = `CP1256`, a platform specific extension of the ASCII character set, meant to be suitable for the Arabic language.
  - `WINDOWS-1257` = `CP1257`, a platform specific extension of the ASCII character set.
  - `WINDOWS-1258` = `CP1258`, a platform specific extension of the ASCII character set.
  - `HP-ROMAN8`, a platform specific extension of the ASCII character set.
  - `NEXTSTEP`, a platform specific extension of the ASCII character set.
  - `EUC-JP`, a multibyte character set for the Japanese language.
  - `SHIFT-JIS`, a multibyte character set for the Japanese language.
  - `CP932`, a Microsoft variant of `SHIFT-JIS`.
  - `ISO-2022-JP`, a stateful 7-bit multibyte character set for the Japanese language.
  - `ISO-2022-JP-2`, a stateful 7-bit multibyte character set for the Japanese language.
  - `ISO-2022-JP-1`, a stateful 7-bit multibyte character set for the Japanese language.
  - `EUC-CN`, a multibyte character set for simplified Chinese.
  - `HZ`, a stateful 7-bit multibyte character set for simplified Chinese.
  - `GBK`, a multibyte character set for Chinese,
  - `CP936`, a Microsoft variant of `GBK`.
  - `EUC-TW`, a multibyte character set for traditional Chinese.
  - `BIG5`, a multibyte character set for traditional Chinese.
  - `CP950`, a Microsoft variant of `BIG5`.
  - `ISO-2022-CN`, a stateful 7-bit multibyte character set for Chinese.
  - `ISO-2022-CN-EXT`, a stateful 7-bit multibyte character set for Chinese.
  - `EUC-KR`, a multibyte character set for Korean.
  - `CP949`, a Microsoft variant of `EUC-KR`.
  - `ISO-2022-KR`, a stateful 7-bit multibyte character set for Korean.
  - `JOHAB`, an old multibyte character set for Korean.
  - `ARMSCII-8`, an extension of the ASCII character set, suitable for Armenian.
  - `GEORGIAN-ACADEMY`, an extension of the ASCII character set, suitable for Georgian.
  - `GEORGIAN-PS`, an extension of the ASCII character set, suitable for Georgian.
  - `TIS-620`, an extension of the ASCII character set, suitable for Thai.
  - `MULELAO-1`, an extension of the ASCII character set, suitable for Laotian.
  - `CP1133`, an extension of the ASCII character set, suitable for Laotian.
  - `VISCII`, an extension of the ASCII character set, suitable for Vietnamese.
  - `TCVN`, an extension of the ASCII character set, suitable for Vietnamese.

#### Line Terminators

The line terminator mode can be one of the following three keywords:

`:unix` | Newline is represented by the ASCII LF character (U000A).
`:mac` | Newline is represented by the ASCII CR character (U000D).
`:dos` | Newline is represented by ASCII CR followed by ASCII LF.

Windows programs typically use the `:dos` line terminator, sometimes they also accept `:unix` line terminators or produce `:mac` line terminators.

The line terminator mode is relevant only for output (writing to a file, pipe or socket). During input, all three kinds of line terminators are recognized. If you do not want this, i.e., if you really want to distinguish LF, CR and CR/LF, you have to resort to binary input (function `read-byte`).

See also 13.1.8 Treatment of Newline during Input and Output.

#### lisp:make-encoding

The function `(lisp:make-encoding &key :charset :line-terminator :input-error-action :output-error-action)` returns an encoding. The `:charset` argument may be an encoding, a string, or `:default`. The possible values for the `:line-terminator` argument are the keywords `:unix`, `:mac`, `:dos`.

The `:input-error-action` specifies what happens when an invalid byte sequence is encountered while converting bytes to characters. Its value can be `:error`, `:ignore` or a character to be used instead. The Unicode character #\uFFFD is typically used to indicate an error in the input sequence.

The `:output-error-action` specifies what happens when an invalid character is encountered while converting characters to bytes. Its value can be `:error`, `:ignore`, a byte to be used instead, or a character to be used instead. The Unicode character #\uFFFD can be used here only if it is encodable in the character set.

Encodings are types. As such, they represent the set of characters encodable in the character set. In this context, the way characters are translated into raw bytes is ignored, and the line terminator mode is ignored as well. `typep` and `subtypep` can be used on encodings.

Besides every file/pipe/socket stream containing an encoding, the following symbol-macro places contain global encodings:

`lisp:*default-file-encoding*` is the encoding used for new file/pipe/socket streams, when no `:external-format` argument was specified.

Platform dependent: Only in CLISP built with compile-time flag `UNICODE`.
  `lisp:*pathname-encoding*`
    is the encoding used for pathnames in the file system. Normally, this is a 1:1 encoding. Its line terminator mode is ignored.
  `lisp:*terminal-encoding*`
    is the encoding used for communication with the terminal, in particular by `*terminal-io*`.
  `lisp:*misc-encoding*`
    is the encoding used for access to environment variables, command line options, and the like. Its line terminator mode is ignored.

### Extensions-1.5. Defining new kinds of Streams

Two mechanisms are supported for creating new streams with user-defined behavior:

- You can create a new subclass of `lisp:fundamental-stream` and define methods for the elementary stream operations on it. These generic functions all have a name starting with the prefix "stream-".
- You can create a new subclass of `lisp:generic-stream-controller` and define methods for the elementary stream operations on it. These generic functions all have a name starting with the prefix "generic-stream-". The stream itself is a different object, created using the function `lisp:make-generic-stream`.

The `fundamental-stream` API is based on a proposal by David N Gray and is supported by most Common Lisp implementations currently in use. The `generic-stream-controller` API is CLISP specific and is now obsolete.

#### Gray streams

This interface permits the definition of new classes of streams, and to program their behavior by defining methods for the elementary stream operations. It is based on a proposal of David N Gray to X3J13, available from ftp://parcftp.xerox.com/pub/cl/cleanup/mail/stream-definition-by-user.mail.

All symbols defined by this interface, starting with the prefix "fundamental-" or "stream-", are exported from the package "LISP".

The following classes are defined.

`fundamental-stream`
  This is a superclass of all user-defined streams. It is a subclass of `stream` and of `standard-object`. Its metaclass is `standard-class`.
`fundamental-input-stream`
  This is a superclass of all user-defined input streams. It is a subclass of `fundamental-stream`. The built-in function `input-stream-p` returns true on instances of this class. This means that when you define a new stream class capable of doing input, you have to make it a subclass of `fundamental-input-stream`.
`fundamental-output-stream`
  This is a superclass of all user-defined output streams. It is a subclass of `fundamental-stream`. The built-in function `output-stream-p` returns true on instances of this class. This means that when you define a new stream class capable of doing output, you have to make it a subclass of `fundamental-output-stream`.
`fundamental-character-stream`
  This is a superclass of all user-defined streams whose element-type is `character`. It is a subclass of `fundamental-stream`. It defines a method on `stream-element-type` that returns `character`.
`fundamental-binary-stream`
  This is a superclass of all user-defined streams whose element-type is a subtype of `integer`. It is a subclass of `fundamental-stream`. When you define a subclass of `fundamental-binary-stream`, you have to provide a method on `stream-element-type`.
`fundamental-character-input-stream`
  This is a convenience class inheriting from both `fundamental-character-stream` and `fundamental-input-stream`.
`fundamental-character-output-stream`
  This is a convenience class inheriting from both `fundamental-character-stream` and `fundamental-output-stream`.
`fundamental-binary-input-stream`
  This is a convenience class inheriting from both `fundamental-binary-stream` and `fundamental-input-stream`.
`fundamental-binary-output-stream`
  This is a convenience class inheriting from both `fundamental-binary-stream` and `fundamental-output-stream`.

The following are general generic functions defined on streams.

`(stream-element-type stream)`
  Returns the stream's element type, normally a subtype of `character` or `integer`.
  The method for `fundamental-character-stream` returns `character`.
`((setf stream-element-type) new-element-type stream)`
  Changes the stream's element type.
  The default method signals an error.
  This function is a CLISP extension.
`(close stream &key :abort)`
  Closes the stream and flushes any associated buffers.
  When you define a primary method on this function, don't forget to `(call-next-method)`.
`(open-stream-p stream)`
  Returns true before the stream has been closed, and `nil` after the stream has been closed.
  You don't need to add methods to this function.

The following are generic functions for character input.

`(stream-read-char stream)`
  If a character was pushed back using `stream-unread-char`, returns and consumes it. Otherwise returns and consumes the next character from the stream. Returns `:eof` if the end-of-stream is reached.
  You must define a method for this function.
`(stream-unread-char stream character)`
  Pushes character, which must be the last character read from the stream, back onto the front of the stream.
  You must define a method for this function.
`(stream-read-char-no-hang stream)`
  Returns a character or `:eof`, like `stream-read-char`, if that would return immediately. If `stream-read-char`'s value is not available immediately, returns `nil` instead of waiting.
  The default method simply calls `stream-read-char`; this is sufficient for streams whose `stream-read-char` method never blocks.
`(stream-peek-char stream)`
  If a character was pushed back using `stream-unread-char`, returns it. Otherwise returns the next character from the stream, avoiding any side effects `stream-read-char` would do. Returns `:eof` if the end-of-stream is reached.
  The default method calls `stream-read-char` and `stream-unread-char`; this is sufficient for streams whose `stream-read-char` method has no side-effects.
`(stream-listen stream)`
  If a character was pushed back using `stream-unread-char`, returns it. Otherwise returns the next character from the stream, if already available. If no character is available immediately, or if end-of-stream is reached, returns `nil`.
  The default method calls `stream-read-char-no-hang` and `stream-unread-char`; this is sufficient for streams whose `stream-read-char` method has no side-effects.
`(stream-read-char-will-hang-p stream)`
  Returns `nil` if `stream-read-char` will return immediately. Otherwise it returns true.
  The default method calls `stream-read-char-no-hang` and `stream-unread-char`; this is sufficient for streams whose `stream-read-char` method has no side-effects.
  This function is a CLISP extension.
`(stream-read-char-sequence stream sequence &optional [start [end]])`
  Fills the subsequence of sequence specified by `:start` and `:end` with characters consecutively read from stream. Returns the index of the first element of sequence that was not updated (= end or < end if the stream reached its end).
  sequence is an array of characters, i.e. a string. start is a nonnegative integer and default to 0. end is a nonnegative integer or `nil` and defaults to `nil`, which stands for `(length sequence)`.
  The default method repeatedly calls `stream-read-char`; this is always sufficient if speed does not matter.
  This function is a CLISP extension.
`(stream-read-line stream)`
  Reads a line of characters, and return two values: the line (a string, without the terminating `#\Newline` character), and a boolean value which is true if the line was terminated by end-of-stream instead of `#\Newline`.
  The default method repeatedly calls `stream-read-char`; this is always sufficient.
`(stream-clear-input stream)`
  Clears all pending interactive input from the stream, and returns true if some pending input was removed.
  The default method does nothing and returns `nil`; this is sufficient for non-interactive streams.

The following are generic functions for character output.

`(stream-write-char stream character)`
  Writes character.
  You must define a method for this function.
`(stream-line-column stream)`
  Returns the column number where the next character would be written (0 stands for the first column), or `nil` if that is not meaningful for this stream.
  You must define a method for this function.
`(stream-start-line-p stream)`
  Returns true if the next character would be written at the start of a new line.
  The default method calls `stream-line-column` and compares its result with 0; this is sufficient for streams whose `stream-line-column` never returns `nil`.
`(stream-write-char-sequence stream sequence &optional [start [end]])`
  Outputs the subsequence of sequence specified by `:start` and `:end` to stream.
  sequence is an array of characters, i.e. a string. start is a nonnegative integer and default to 0. end is a nonnegative integer or `nil` and defaults to `nil`, which stands for `(length sequence)`.
  The default method repeatedly calls `stream-write-char`; this is always sufficient if speed does not matter.
  This function is a CLISP extension.
`(stream-write-string stream string &optional [start [end]])`
  Outputs the subsequence of string specified by `:start` and `:end` to stream. Returns string.
  string is a string. start is a nonnegative integer and default to 0. end is a nonnegative integer or `nil` and defaults to `nil`, which stands for `(length string)`.
  The default method calls `stream-write-char-sequence`; this is always sufficient.
`(stream-terpri stream)`
  Outputs a `#\Newline` character.
  The default method calls `stream-write-char`; this is always sufficient.
`(stream-fresh-line stream)`
  Possibly outputs a `#\Newline` character, so as to ensure that the next character would be written at the start of a new line. Returns true if it did output a `#\Newline` character.
  The default method calls `stream-start-line-p` and then `stream-terpri` if necessary; this is always sufficient.
`(stream-finish-output stream)`
  Ensures that any buffered output has reached its destination, and then returns.
  The default method does nothing.
`(stream-force-output stream)`
  Brings any buffered output on its way towards its destination, and returns without waiting until it has reached its destination.
  The default method does nothing.
`(stream-clear-output stream)`
  Attempts to discard any buffered output which has not yet reached its destination.
  The default method does nothing.
`(stream-advance-to-column stream column)`
  Ensures that the next character will be written at column at least.
  The default method outputs an appropriate amount of space characters; this is sufficient for non-proportional output.

The following are generic functions for binary input.

`(stream-read-byte stream)`
  Returns and consumes the next integer from the stream. Returns `:eof` if the end-of-stream is reached.
  You must define a method for this function.
`(stream-read-byte-sequence stream sequence &optional [start [end]])`
  Fills the subsequence of sequence specified by `:start` and `:end` with integers consecutively read from stream. Returns the index of the first element of sequence that was not updated (= end or < end if the stream reached its end).
  sequence is an array of integers. start is a nonnegative integer and default to 0. end is a nonnegative integer or `nil` and defaults to `nil`, which stands for `(length sequence)`.
  The default method repeatedly calls `stream-read-byte`; this is always sufficient if speed does not matter.
  This function is a CLISP extension.

The following are generic functions for binary output.

`(stream-write-byte stream integer)`
  Writes integer.
  You must define a method for this function.
`(stream-write-byte-sequence stream sequence &optional [start [end]])`
  Outputs the subsequence of sequence specified by `:start` and `:end` to stream.
  sequence is an array of integers. start is a nonnegative integer and default to 0. end is a nonnegative integer or `nil` and defaults to `nil`, which stands for `(length sequence)`.
  The default method repeatedly calls `stream-write-byte`; this is always sufficient if speed does not matter.
  This function is a CLISP extension.

#### Generic streams

This interface is CLISP specific and now obsolete. Please use the Gray streams interface instead.

Generic streams are user programmable streams. The programmer interface:

`(lisp:make-generic-stream controller)`
  returns a generic stream.
`(lisp:generic-stream-controller stream)`
  returns a private object to which generic stream methods dispatch. The typical usage is to retrieve the object originally provided by the user in `lisp:make-generic-stream`.
`(lisp:generic-stream-p stream)`
  determines whether a stream is a generic stream, returning `t` if it is, `nil` otherwise.

In order to specify the behavior of a generic stream, the user must define CLOS methods on the following CLOS generic functions. The function `generic-stream-xyz` corresponds to the Common Lisp function `xyz`. They all take a controller and some number of arguments.

`(lisp:generic-stream-read-char controller)`
  Returns and consumes the next character, `nil` at end of file. Takes one argument, the controller object.
`(lisp:generic-stream-peek-char controller)`
  Returns the next character, `nil` at end of file. A second value indicates whether the side effects associated with consuming the character were executed: `t` means that a full `read-char` was done, `nil` means that no side effects were done. Takes one argument, the controller object.
`(lisp:generic-stream-read-byte controller)`
  Returns and consumes the next integer, `nil` at end of file. Takes one argument, the controller object.
`(lisp:generic-stream-read-char-will-hang-p controller)`
  This generic function is used to query the stream's input status. It returns `nil` if `lisp:generic-stream-read-char` and `lisp:generic-stream-peek-char` will certainly return immediately. Otherwise it returns true.
`(lisp:generic-stream-write-char controller ch)`
  First argument is the controller object. Second argument is the character to be written.
`(lisp:generic-stream-write-byte controller by)`
  First argument is the controller object. Second argument is the integer to be written.
`(lisp:generic-stream-write-string controller string start len)`
  Called with argument list `(controller string start len)`, this function shall write `(subseq (the string string) start (+ start len))` First argument is the controller object.
`(lisp:generic-stream-clear-input controller)`
`(lisp:generic-stream-clear-output controller)`
`(lisp:generic-stream-finish-output controller)`
`(lisp:generic-stream-force-output controller)`
`(lisp:generic-stream-close controller)`
  Take one argument, the controller object.

### Extensions-1.6. Weak Pointers

A weak pointer is an object holding a reference to a given object, without keeping the latter from being garbage-collected.

`(lisp:make-weak-pointer value)` returns a fresh weak pointer referring to value.

`(lisp:weak-pointer-p object)` returns true if the object is of type `weak-pointer`.

`(lisp:weak-pointer-value weak-pointer)` returns two values: The original value and `t`, if the value has not yet been garbage collected, else `nil` and `nil`.

### Extensions-1.7. Finalization

Calling `(lisp:finalize object function)` has the effect that when the specified object is being garbage collected, `(funcall function object)` will be executed.

Calling `(lisp:finalize object function guardian)` has a similar effect, but only as long as the "guardian" has not been garbage collected: When object is being garbage collected, `(funcall function object guardian)` will be executed. If the guardian is garbage collected before object is, nothing happens.

Note: The time when "the object is being garbage collected" is not defined deterministically. (Actually, it possibly never occurs.) It denotes a moment at which no references to object exist from other Lisp objects. When the function is called, object (and possibly guardian) enter the "arena of live Lisp objects" again.

No finalization request will be executed more than once.

### Extensions-1.8. The Prompt

The variable `sys::*prompt*` controls the appearance of the prompt. When its value is a function, it is called and its value is printed with `princ`. Otherwise, the value itself is printed with `princ`. The default value of `sys::*prompt*` prints "package[nn]> " where package is the shortest (nick)name of the current package `*package*` if it is the same as it was in the beginning or if it does not contain symbol `t` (it is assumed that in the latter case you would want to keep in mind that your current package is something weird); and nn is the ordinal number of the current prompt (hopefully, it will remain finite). To help you in constructing your own fancy prompts, two functions are provided: `sys::prompt-new-package`, returning `*package*` or `nil` if the current package is the same as it was initially; and `sys::package-short-name` taking one argument, a package, and returning its shortest name or nickname. Also, a variable `sys::*command-index*` contains the current prompt number, it is your responsibility to increment it (this variable is bound to 0 before saving the image).

### Extensions-1.9. Maximum ANSI CL compliance

A few ANSI CL features are turned off by default, because they would hurt in every-day use. They can be switched on, all at once by setting the symbol-macro `lisp:*ansi*` to `t`, or they can be switched on individually. Setting `lisp:*ansi*` to `t` implies the following:

- Setting `lisp:*print-pathnames-ansi*` to `t` for ANSI CL compliant `pathname` printing.
- Setting `lisp:*coerce-fixnum-char-ansi*` to `t` so that `fixnum`s cannot be `coerce`d to `character`s (because a `fixnum` is not a character designator in ANSI CL.)
- Setting `lisp:*sequence-count-ansi*` to `t` so that negative `:count` keyword parameter is equivalent to 0 as per the RANGE-OF-COUNT-KEYWORD:NIL-OR-INTEGER ANSI CL Issue 283.
- Setting `lisp:*merge-pathnames-ansi*` to `t`.
- Setting `lisp:*floating-point-contagion-ansi*` to `t`.
- Adding `:ansi-cl` to `*features*`.

Please note that if you run CLISP with the -a switch or set the symbol-macro `lisp:*ansi*` to `t` and save image, then all subsequent invocations of CLISP with this image will be as if with -a (regardless whether you actually supply the -a switch). You can always set the symbol-macro `lisp:*ansi*` to `nil`, reversing the above settings, i.e.,

- Setting `lisp:*print-pathnames-ansi*` to `nil` for readable `pathname` printing.
- Setting `lisp:*coerce-fixnum-char-ansi*` to `nil` so that `fixnum`s can be `coerce`d to `character`s (via `code-char`).
- Setting `lisp:*sequence-count-ansi*` to `nil` to signal an error on negative `:count` keyword parameter, contrary to the RANGE-OF-COUNT-KEYWORD:NIL-OR-INTEGER ANSI CL Issue 283.
- Setting `lisp:*merge-pathnames-ansi*` to `nil`.
- Setting `lisp:*floating-point-contagion-ansi*` to `nil`.
- Deleting `:ansi-cl` from `*features*`.

### Extensions-1.10. Additional Fancy Macros

If you uncomment the `(load "macros3")` line in the file `"init.lisp"` before doing `make`, or load the file `"macros3"`into a running CLISP, you get access to the following macros:

`lisp:ethe`
  `(lisp:ethe value-type form)` enforces a type check in both interpreted and compiled code.
`lisp:letf` and `lisp:letf*`
  These macros are similar to `let` and `let*`, respectively, except that they can bind places, even places with multiple values. Example:
  `(letf (((values a b) form)) ...)`
    is equivalent to `(multiple-value-bind (a b) form ...)`
  `(letf (((first l) 7)) ...)`
    is approximately equivalent to

            (let* ((#:g1 l) (#:g2 (first #:g1)))
              (unwind-protect (progn (setf (first #:g1) 7) ...)
                              (setf (first #:g1) #:g2)))

`lisp:with-collect`
  Similar to the `loop`'s `collect` instruction, except that it is more "Lispy" in appearance and can appear arbitrarily deep. It defines local macros (with `macrolet`) which collect objects given to it in lists, which are then returned as multiple values. E.g.,

          (lisp:with-collect (c0 c1)
            (dotimes (i 10) (if (oddp i) (c0 i) (c1 i))))

  returns two lists `(1 3 5 7 9)` and `(0 2 4 6 8)` as multiple values.

You might want to add a `(load "macros3")` statement to your `".clisprc"` file if you do not want to dump your own image.

## Extensions-2: Platform specific Extensions

### Extensions-2.1. Random Screen Access

Platform dependent: UNIX, DOS, OS/2, Amiga platforms only.

`(screen:make-window)`
  returns a "window stream". As long as this stream is open, the terminal is in cbreak/noecho mode. `*terminal-io*` should not be used for input or output during this time. (Use `lisp:with-keyboard` and `lisp:*keyboard-input*` instead.)
`(screen:with-window . body)`
  binds `screen:*window*` to a window stream and executes body. The stream is guaranteed to be closed when the body is left. During its execution, `*terminal-io*` should not be used, as above.
`(screen:window-size window-stream)`
  returns the window's size, as two values: height (= ymax+1) and width (= xmax+1).
`(screen:window-cursor-position window-stream)`
  returns the position of the cursor in the window, as two values: line (>=0, <=ymax, 0 means top), column (>=0, <=xmax, 0 means left margin).
`(screen:set-window-cursor-position window-stream line column)`
  sets the position of the cursor in the window.
`(screen:clear-window window-stream)`
  clears the window's contents and puts the cursor in the upper left corner.
`(screen:clear-window-to-eot window-stream)`
  clears the window's contents from the cursor position to the end of window.
`(screen:clear-window-to-eol window-stream)`
  clears the window's contents from the cursor position to the end of line.
`(screen:delete-window-line window-stream)`
  removes the cursor's line, moves the lines below it up by one line and clears the window's last line.
`(screen:insert-window-line window-stream)`
  inserts a line at the cursor's line, moving the lines below it down by one line.
`(screen:highlight-on window-stream)`
  switches highlighted output on.
`(screen:highlight-off window-stream)`
  switches highlighted output off.
`(screen:window-cursor-on window-stream)`
  makes the cursor visible, a cursor block in most implementations.
`(screen:window-cursor-off window-stream)`
  makes the cursor invisible, in implementations where this is possible.

### Extensions-2.2. External Modules

Platform dependent: UNIX platforms only.

CLISP has a facility for adding external modules (written in C, for example). It is invoked through `clisp-link`.

A module is a piece of external code which defines extra Lisp objects, symbols and functions. A module name must consist of the characters A-Z,a-z,_,0-9. The module name `"clisp"` is reserved. Normally a module name is derived from the corresponding file name.

`clisp-link` needs a directory containing:

`modules.d`
`modules.c`
`clisp.h`

`clisp-link` expects to find these files in a subdirectory `linkkit/` of the current directory. This can be overridden by the environment variable `CLISP_LINKKIT`.

`clisp-link` operates on CLISP linking sets and on module sets.

A linking set is a directory containing:

`makevars`
  some `/bin/sh` commands, setting the variables
  `CC`
    the C compiler
  `CFLAGS`
    flags for the C compiler, when compiling
  `CLFLAGS`
    flags for the C compiler, when linking
  `LIBS`
    libraries to use when linking
  `X_LIBS`
    additional X window system libraries to use
  `RANLIB`
    the ranlib command
  `FILES`
    the list of files needed when linking
`modules.h`
  the list of modules contained in this linking set
`modules.o`
  the compiled list of modules contained in this linking set
all the `FILES` listed in `makevars`
`lisp.run`
  the executable
`lispinit.mem`
  the memory image

To run a clisp contained in some linking set dir, call "`dir/lisp.run -M dir/lispinit.mem`".

A module set is a directory containing:

`link.sh`
  some `/bin/sh` commands, which prepare the directory before linking, and set the variables `NEW_FILES`, `NEW_LIBS`, `NEW_MODULES`, `TO_LOAD` and optionally `TO_PRELOAD`
and any other files needed by `link.sh`.

Note that in `link.sh` the module set directory is referred to as `"$modulename"/`.

The `NEW_FILES` variable
  shall contain a space-separated list of files that belong to the module set and will belong to every new linking set.
The `NEW_LIBS` variable
  shall contain a space-separated list of files or C compiler switches that need to be passed to the C compiler when linking the lisp.run belonging to a new linking set.
The `NEW_MODULES` variable
  shall contain a space-separated list of the module names belonging to the module set. Normally, every `.c` file in the module set defines a module of its own. The module name is derived from the file name.
The `TO_LOAD` variable
  shall contain a space-separated list of Lisp files to load before building the `lispinit.mem` belonging to a new linking set.
The `TO_PRELOAD` variable, if defined,
  shall contain a space-separated list of Lisp files to load into an intermediate `lispinit.mem` file, before building the `lispinit.mem` belonging to a new linking set. This variable is usually used for defining Lisp packages which must be present when the new `.c` files are initialized.

The command "`clisp-link create-module-set module-dir file1.c ...`" creates a module set in module-dir which refers (via symbolic links) to `file1.c` etc. The files are expected to be modules of their own.

The command "`clisp-link add-module-set module-dir source-dir destination-dir`" combines a linking set in source-dir and a module in module-dir to a new linking set, in a directory destination-dir which is newly created.

The command "clisp-link run source-dir module-dir ..." runs the linking set in source-dir, with the module in module-dir loaded. More than one module can be specified. If CLISP has been built with the configuration option `--with-dynamic-modules`, the loading will be performed through dynamic loading. Otherwise -- this is much slower -- a temporary linking set will be created and deleted afterwards. Note that dynamic loading does not work on all operating systems, and that `--with-dynamic-modules` precludes some efficiency optimizations which are on by default.

#### Example

To link in the FFI bindings for the Linux operating system, the following steps are needed. (Step 1 and step 2 need not be executed in this order.)

1. Create a new module set:

          $ clisp-link create-module-set linux /somewhere/bindings/linux.c

   Modify the newly created `linux/link.sh` to add "`-lm`" to the libraries:

          NEW_LIBS="$file_list"
          -->
          NEW_LIBS="$file_list -lm"

   Modify the newly created `linux/link.sh` to load `linux.fas` before saving the memory image:

          TO_LOAD=''
          -->
          TO_LOAD='/somewhere/bindings/linux.fas'

2. Compile `linux.lisp`, creating `linux.c`:

          $ clisp -c /somewhere/bindings/linux.lisp

3. Create a new linking set:

          $ clisp-link add-module-set linux base base+linux

4. Run and try it:

          $ base+linux/lisp.run -M base+linux/lispinit.mem
          > (linux::stat "/tmp")

#### Modules included in the distribution.

The following modules come with the distribution of `CLISP`:

bindings
  Call the operating system functions from `CLISP`. The following platforms are supported:
  - AmigaOS
  - Linux/libc5
  - Linux/libc6
CLX
  Call Xlib functions from `CLISP`. Two implementations are supplied:
  - mit-clx, from MIT
  - new-clx, by Gilbert Baumann unk6@rz.uni-karlsruhe.de.
postgresql632, postgresql642
  Access PostgreSQL from `CLISP`.
queens
  Compute the number of solutions to the n-queens problem on a n*n checkboard.
regexp
  The POSIX Regular Expressions matching, compiling, executing.

  The following code computes the number of people who use a particular shell:

      (use-package :regexp)
      (let ((h (make-hash-table :test #'equal :size 10)) (n 0))
        (with-open-file (f "/etc/passwd")
          (with-loop-split (s f ":")
            (let ((sh (seventh s)))
              (if (gethash sh h)
                  (incf (gethash sh h))
                  (setf (gethash sh h) 1)))))
        (with-hash-table-iterator (i h)
          (loop (multiple-value-bind (r k v) (i)
                  (unless r (return))
                  (format t "[~d] ~s~30t== ~5:d~%" (incf n) k v)))))

  The same is done by the following Perl:

      #!/usr/local/bin/perl -w

      use diagnostics;
      use strict;

      my $IN = $ARGV[0];
      open(INF,"< $IN") || die "$0: cannot read file [$IN]: $!\n;";
      my %hash;
      while (<INF>) {
        chop;
        my @all = split($ARGV[1]);
        my $shell = ($#all >= 6 ? $all[6] : "");
        if ($hash{$shell}) { $hash{$shell} ++; }
        else { $hash{$shell} = 1; }
      }
      my $ii = 0;
      for my $kk (keys(%hash)) {
        print "[",++$ii,"] \"",$kk,"\"  --  ",$hash{$kk},"\n";
      }

wildcard
  Shell globbing

### Extensions-2.3. The Foreign Function Call Facility

Platform dependent: many UNIX, Win32 platforms only.

A foreign function description is written as a Lisp file, and when compiled it produces a `.c` file which is then compiled by the C compiler and may be linked together with `lisp.a`.

All symbols relating to the foreign function interface are exported from the package FFI. To use them, `(use-package "FFI")`.

Special FFI forms may appear anywhere in the Lisp file.

#### Overview

These are the special FFI forms. We have taken a pragmatic approach: the only foreign languages we support for now are C and ANSI C.

`(def-c-type name c-type)`

`(def-c-var name {option}*)`

option ::=
| `(:name c-name)`
| | `(:type c-type)`
| | `(:read-only boolean)`
| | `(:alloc allocation)`

`(def-call-out name {option}*)`

option ::=
| `(:name c-name)`
| | `(:arguments {(arg-name c-type [param-mode [allocation]])}*)`
| | `(:return-type c-type [allocation])`
| | `(:language language)`

`(def-call-in name {option}*)`

option ::=
| `(:name c-name)`
| | `(:arguments {(arg-name c-type [param-mode [allocation]])}*)`
| | `(:return-type c-type [allocation])`
| | `(:language language)`

`(def-c-call-out name {option}*)`

option ::=
| `(:name c-name)`
| | `(:arguments {(arg-name c-type [param-mode [allocation]])}*)`
| | `(:return-type c-type [allocation])`

`(def-c-call-in name {option}*)`

option ::=
| `(:name c-name)`
| | `(:arguments {(arg-name c-type [param-mode [allocation]])}*)`
| | `(:return-type c-type [allocation])`

`(def-c-struct name (ident c-type)*)`

`(def-c-enum name {ident | (ident [value])}*)`

`(c-lines format-string {argument}*)`

`(element c-place {index}*)`
`(deref c-place)`
`(slot c-place slot-name)`
`(cast c-place c-type)`

`(typeof c-place)`
`(sizeof c-place)`, `(sizeof c-type)`
`(bitsizeof c-place)`, `(bitsizeof c-type)`

`(validp foreign-entity)`

name is any Lisp symbol.

c-name is a string.

#### (Foreign) C types

Foreign C types are used in the FFI. They are not regular Common Lisp types or CLOS classes.

A c-type is either a predefined C type or the name of a type defined by `def-c-type`.

The simple C types are these:

Lisp name | Lisp equiv | C equiv | ILU equiv | Comment
--- | --- | --- | --- | ---
`nil` | `nil` | `void` |  | as a result type only
`boolean` | `boolean` | `int` | `BOOLEAN`
`character` | `character` | `char` | `SHORT CHARACTER`
`char` | `integer` | `signed char`
`uchar` | `integer` | `unsigned char`
`short` | `integer` | `short`
`ushort` | `integer` | `unsigned short`
`int` | `integer` | `int`
`uint` | `integer` | `unsigned int`
`long` | `integer` | `long`
`ulong` | `integer` | `unsigned long`
`uint8` | `(unsigned-byte 8)` | `uint8` | `BYTE`
`sint8` | `(signed-byte 8)` | `sint8`
`uint16` | `(unsigned-byte 16)` | `uint16` | `SHORT CARDINAL`
`sint16` | `(signed-byte 16)` | `sint16` | `SHORT INTEGER`
`uint32` | `(unsigned-byte 32)` | `uint32` | `CARDINAL`
`sint32` | `(signed-byte 32)` | `sint32` | `INTEGER`
`uint64` | `(unsigned-byte 64)` | `uint64` | `LONG CARDINAL` | does not work on all platforms
`sint64` | `(signed-byte 64)` | `sint64` | `LONG INTEGER` | does not work on all platforms
`single-float` | `single-float` | `float`
`double-float` | `double-float` | `double`

The predefined C types are:

c-type ::=
| simple-c-type
| | `c-pointer`
| | `c-string`
| | `(c-struct class (ident c-type)*)`
| | `(c-union (ident c-type)*)`
| | `(c-array c-type dimensions)` dimensions ::= number | `({number}*)`
| | `(c-array-max c-type maxdimension)` maxdimension ::= number
| | `(c-function {option}*)` option ::= `(:arguments {(arg-name c-type [param-mode [allocation]])}*)` | `(:return-type c-type [allocation])` | `(:language language)`
| | `(c-ptr c-type)`
| | `(c-ptr-null c-type)`
| | `(c-array-ptr c-type)`

`(def-c-type name c-type)` makes name a shortcut for c-type. Note that c-type may already refer to name. Forward declarations of types are not possible, however.

The type `c-pointer` corresponds to what C calls "`void*`", an opaque pointer.

The type `c-string` corresponds to what C calls "`char*`", a zero-terminated string. Its Lisp equivalent is a string, without the trailing zero character.

The type `(c-struct class (ident1 type1) ... (identn typen))` is equivalent to what C calls "`struct { type1 ident1; ...; typen identn; }`". Its Lisp equivalent is: if class is `vector`, a simple-vector; if class is `list`, a list; if class is a symbol naming a structure or CLOS class: an instance of this class, with slots of names ident1,...,identn.

The type `(c-union (ident1 type1) ... (identn typen))` is equivalent to what C calls "`union { type1 ident1; ...; typen identn; }`". Conversion to and from Lisp assumes that a value is to be viewed as being of type1.

The type `(c-array type dim1 ... dimn)` is equivalent to what C calls "`type [dim1]...[dimn]`". Note that when an array is passed as an argument to a function in C, it is actually passed as a pointer; you therefore have to write `(c-ptr (c-array ...))` for this argument's type.

The type `(c-array-max type maxdim)` is equivalent to what C calls "`type [maxdim]`", an array containing up to maxdim elements. The array is zero-terminated if it contains less than maxdim elements. Conversion from Lisp of an array with more than maxdim elements silently ignores the superfluous elements.

The type `(c-ptr type)` is equivalent to what C calls "`type *`": a pointer to a single item of the given type.

The type `(c-ptr-null type)` is also equivalent to what C calls "`type *"`: a pointer to a single item of the given type, with the exception that C `NULL` corresponds to Lisp `nil`.

The type `(c-array-ptr type)` is equivalent to what C calls "`type (*)[]`": a pointer to a zero-terminated array of items of the given type.

The type `(c-function (:return-type rtype) (:arguments (arg1 type1 ...) ...))` designates a C function that can be called according to the given prototype `(rtype (*) (type1, ...))`. The language is either `:C` (denotes K&R C) or `:STDC` (denotes ANSI C) or `:STDC-STDCALL` (denotes ANSI C with stdcall calling convention). It specifies whether the C function has been compiled by a K&R C compiler or by an ANSI C compiler, and possibly the calling convention. Conversion between C functions and Lisp functions is transparent.

`(def-c-struct name (ident c-type)*)` defines name to be both a `defstruct` structure type and a foreign C type with the given slots.

`(def-c-enum name {ident | (ident [value])}*)` defines idents as constants, similarly to the C declaration `enum { ident [= value], ... };`

`(c-lines format-string {argument}*)` outputs the string `(format nil format-string {argument}*)` to the C output file. This is a rarely needed low-level facility.

The form `(sizeof c-type)` returns the size and alignment of a C type, measured in bytes.

The form `(bitsizeof c-type)` returns the size and alignment of a C type, measured in bits.

The predicate `(validp foreign-entity)` returns `nil` if the foreign-entity (e.g. the Lisp equivalent of a `c-pointer`) refers to a pointer which is invalid because it comes from a previous Lisp session. It returns `t` if foreign-entity can be used within the current Lisp process.

#### Foreign variables

Foreign variables are variables whose storage is allocated in the foreign language module. They can nevertheless be evaluated and modified through `setq`, just as normal variables can, except that the range of allowed values is limited according to the variable's foreign type. Note that for a foreign variable x the form `( eql x x)` is not necessarily true, since every time x is evaluated its foreign value is converted to a freshly created Lisp value.

`(def-c-var name {option}*)`

option ::=
| `(:name c-name)`
| | `(:type c-type)`
| | `(:read-only boolean)`
| | `(:alloc allocation)`

defines a foreign variable. name is the Lisp name, a regular Lisp symbol.

The `:name` option specifies the name, as seen from C, as a string. If not specified, it is derived from the print name of the Lisp name.

The `:type` option specifies the variable's foreign type.

If the `:read-only` option is specified and non-`nil`, it will be impossible to change the variable's value from within Lisp (using `setq` or similar).

The `:alloc` option can be either `:none` or `:malloc-free` and defaults to `:none`. If it is `:malloc-free`, any values of type `c-string`, `(c-ptr ...)`, `(c-ptr-null ...)`, `(c-array-ptr ...)` within the foreign value are assumed to be pointers to `malloc()`-allocated storage, and when `setq` replaces an old value by a new one, the old storage is freed using `free()` and the new storage allocated using `malloc()`. If it is `:none`, `setq` assumes that the pointers point to good storage (not `NULL`!) and overwrites the old values by the new ones. This is dangerous (just think of overwriting a string with a longer one or storing some data in a `NULL` pointer...) and deprecated.

#### Operations on foreign places

A foreign variable name defined by `def-c-var` defines a "place", i.e., a form which can also be used as argument to `setf`. (An "lvalue" in C terminology.) The following operations are available on foreign places:

`(element place index1 ... indexn)`
Array element: If place is of foreign type `(c-array c-type dim1 ... dimn)` and 0 <= index1 < dim1, ..., 0 <= indexn < dimn, this will be the place corresponding to `(aref place index1 ... indexn)` or `place[index1]...[indexn]`. It is a place of type c-type. If place is of foreign type `(c-array-max c-type dim)` and 0 <= index < dim, this will be the place corresponding to `(aref place index)` or `place[index]`. It is a place of type c-type.

`(deref place)`
Dereference pointer: If place is of foreign type `(c-ptr c-type)` or `(c-ptr-null c-type)`, this will be the place the pointer points to. It is a place of type c-type. For `(c-ptr-null c-type)`, the place may not be `NULL`.

`(slot place slot-name)`
Struct or union component: If place is of foreign type `(c-struct class ... (slot-name c-type) ...)` or of type `(c-union ... (slot-name c-type) ...)`, this will be of type c-type.

`(cast place c-type)`
Type change: A place denoting the same memory locations as the original place, but of type c-type.

`(typeof place)`
returns the c-type corresponding to the place.

`(sizeof place)`
returns the size and alignment of the C type of place, measured in bytes.

`(bitsizeof place)`
returns the size and alignment of the C type of place, measured in bits.

#### Foreign functions

Foreign functions are functions which are defined in the foreign language. There are named foreign functions (imported via `def-call-out` or created via `def-call-in`) and anonymous foreign functions; they arise through conversion of function pointers.

A "call-out" function is a foreign function called from Lisp: control flow temporarily leaves Lisp. A "call-in" function is a Lisp function called from the foreign language: control flow temporary enters Lisp.

`(def-call-out name {option}*)`

option ::=
| `(:name c-name)`
| | `(:arguments {(arg-name c-type [param-mode [allocation]])}*)`
| | `(:return-type c-type [allocation])`
| | `(:language language)`

defines a named call-out function. Any Lisp function call to `#'name` is redirected to call the C function c-name. The language is either `:C` (denotes K&R C) or `:STDC` (denotes ANSI C) or `:STDC-STDCALL` (denotes ANSI C with stdcall calling convention). It specifies whether the C function has been compiled by a K&R C compiler or by an ANSI C compiler, and possibly the calling convention.

`def-c-call-out` is equivalent to `def-call-out` with `:language :stdc`.

`(def-call-in name {option}*)`

option ::=
| `(:name c-name)`
| | `(:arguments {(arg-name c-type [param-mode [allocation]])}*)`
| | `(:return-type c-type [allocation])`
| | `(:language language)`

defines a named call-in function. Any C function call to the C function c-name is redirected to call the Lisp function `#'name`. The language is either `:C` (denotes K&R C) or `:STDC` (denotes ANSI C) or `:STDC-STDCALL` (denotes ANSI C with stdcall calling convention). It specifies whether the calling code has been compiled by a K&R C compiler or by an ANSI C compiler, and possibly the calling convention.

`def-c-call-in` is equivalent to `def-call-in` with `:language :stdc`.

#### Argument and result passing conventions

When passed to and from functions, allocation of arguments and results is handled as follows:

Values of simple-c-type, `c-pointer` are passed on the stack, with dynamic extent. The allocation is effectively ignored.

Values of type `c-string`, `(c-ptr` ...`)`, `(c-ptr-null` ...`)`, `(c-array-ptr` ...`)` need storage. The allocation specifies the allocation policy:

allocation | meaning
--- | ---
`:none` | no storage is allocated.
`:alloca` | allocation of storage on the stack, which has dynamic extent.
`:malloc-free` | storage will be allocated via `malloc()` and freed via `free()`.

If no allocation is specified, the default allocation is `:none` for most types, but `:alloca` for `c-string` and `(c-ptr` ...`)` and `(c-ptr-null` ...`)` and `(c-array-ptr` ...`)` and for `:out` arguments. [Subject to change!] The `:malloc-free` policy provides the ability to pass arbitrarily nested structs containing pointers pointing to structs ... within a single conversion.

For call-out functions:
  For arguments passed from Lisp to C:
    If allocation is `:malloc-free`,
      Lisp allocates the storage using malloc() and never deallocates it. The C function is supposed to call free() when done with it.
    If allocation is `:alloca`,
      Lisp allocates the storage on the stack, with dynamic extent. It is freed when the C function returns.
    If allocation is `:none`,
      Lisp assumes that the pointer already points to a valid area of the proper size and puts the result value there. This is dangerous! and deprecated.
  For results passed from C to Lisp:
    If allocation is `:malloc-free`,
      Lisp calls free() on it when done.
    If allocation is `:none`,
      Lisp does nothing.
For call-in functions:
  For arguments passed from C to Lisp:
    If allocation is `:malloc-free`,
      Lisp calls free() on it when done.
    If allocation is `:alloca` or `:none`,
      Lisp does nothing.
  For results passed from Lisp to C:
    If allocation is `:malloc-free`,
      Lisp allocates the storage using malloc() and never deallocates it. The C function is supposed to call free() when done with it.
    If allocation is `:none`,
      Lisp assumes that the pointer already points to a valid area of the proper size and puts the result value there. This is dangerous! and deprecated.

A function parameter's param-mode may be

either `:in` (means: read-only):
  The caller passes information to the callee.
or `:out` (means: write-only):
  The callee passes information back to the caller on return. When viewed as a Lisp function, there is no Lisp argument corresponding to this, instead it means an additional return value.
or `:in-out` (means: read-write):
  Information is passed from the caller to the callee and then back to the caller. When viewed as a Lisp function, the "`:out`" value is returned as an additional multiple value.

The default is `:in`.

[Currently, only `:in` is fully implemented. `:out` works only with allocation = `:alloca`.]

Platform dependent: Amiga platforms only.
  allocation may not be `:malloc-free` because there is no commonly used `malloc()/free()` library function.

  The allocation may be followed by a register specification, any of the symbols `:d0`, `:d1`, `:d2`, `:d3`, `:d4`, `:d5`, `:d6`, `:d7`, `:a0`, `:a1`, `:a2`, `:a3`, `:a4`, `:a5`, `:a6`, each representing one 680x0 register. This works only for integral types: integers, pointers, `c-string`, `c-function`.

Passing `c-struct`, `c-union`, `c-array`, `c-array-max` values as arguments (not via pointers) is only possible to the extent the C compiler supports it. Most C compilers do it right, but some C compilers (such as gcc on hppa) have problems with this.

Platform dependent: Only in CLISP built with compile-time flag `UNICODE`.
  A symbol-macro place `lisp:*foreign-encoding*` contains the encoding for characters and strings passed through the FFI. Its value must be a 1:1 encoding, i.e., an encoding in which every character is represented by one byte.

#### Examples

Ex. 1: The C declaration

           struct foo {
               int a;
               struct foo * b[100];
           };

corresponds to

           (def-c-struct foo
             (a int)
             (b (c-array (c-ptr foo) 100))
           )

The element access

           struct foo f;
           f.b[7].a

corresponds to

           (declare (type foo f))
           (foo-a (aref (foo-b f) 7)) or (slot-value (aref (slot-value f 'b) 7) 'a)

Ex. 2: Here is an example of an external C variable and some accesses:

           struct bar {
               short x, y;
               char a, b;
               int z;
               struct bar * n;
           };

           extern struct bar * my_struct;

           my_struct->x++;
           my_struct->a = 5;
           my_struct = my_struct->n;

corresponds to

           (def-c-struct bar
             (x short)
             (y short)
             (a char)
             (b char) ; or (b character) if it represents a character, not a number
             (z int)
             (n (c-ptr bar))
           )

           (def-c-var my_struct (:type (c-ptr bar)))

           (setq my_struct (let ((s my_struct)) (incf (slot-value s 'x)) s))
           or (incf (slot my_struct 'x))
           (setq my_struct (let ((s my_struct)) (setf (slot-value s 'a) 5) s))
           or (setf (slot my_struct 'a) 5)
           (setq my_struct (slot-value my_struct 'n))
           or (setq my_struct (deref (slot my_struct 'n)))

Ex. 3: An example for calling an external function: On ANSI C systems, <stdlib.h> contains the declarations

           typedef struct {
             int quot;   /* Quotient */
             int rem;    /* Remainder */
           } div_t;
           extern div_t div (int numer, int denom);

This translates to

           (def-c-struct div_t
             (quot int)
             (rem int)
           )
           (def-c-call-out div (:arguments (numer int) (denom int))
                               (:return-type div_t)
           )

Sample call from within Lisp:

           > (div 20 3)
           #S(DIV :QUOT 6 :REM 2)

Ex. 4: Another example for calling an external function:

Suppose the following is defined in a file `"cfun.c"`:

           struct cfunr { int x; char *s; };
           struct cfunr * cfun (i,s,r,a)
               int i;
               char *s;
               struct cfunr * r;
               int a[10];
           {
               int j;
               struct cfunr * r2;
               printf("i = %d\n", i);
               printf("s = %s\n", s);
               printf("r->x = %d\n", r->x);
               printf("r->s = %s\n", r->s);
               for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
               r2 = (struct cfunr *) malloc (sizeof (struct cfunr));
               r2->x = i+5;
               r2->s = "A C string";
               return r2;
           }

It is possible to call this function from Lisp using the file `"callcfun.lisp"` (do not call it `"cfun.lisp"` - `compile-file` would overwrite `"cfun.c"`) whose contents is:

           (in-package "TEST-C-CALL" :use '("LISP" "FFI"))
           (def-c-struct cfunr (x int) (s c-string))
           (def-c-call-out cfun (:arguments (i int)
                                            (s c-string)
                                            (r (c-ptr cfunr) :in :alloca)
                                            (a (c-ptr (c-array int 10)) :in :alloca)
                                )
                                (:return-type (c-ptr cfunr))
           )
           (defun call-cfun ()
             (cfun 5 "A Lisp string" (make-cfunr :x 10 :s "Another Lisp string")
                   '#(0 1 2 3 4 5 6 7 8 9)
           ) )

Use the module facility:

           $ clisp-link create-module-set cfun callcfun.c
           $ cc -O -c cfun.c
           $ cd cfun
           $ ln -s ../cfun.o cfun.o
           Add cfun.o to NEW_LIBS and NEW_FILES in link.sh.
           $ cd ..
           $ base/lisp.run -M base/lispinit.mem -c callcfun.lisp
           $ clisp-link add-module-set cfun base base+cfun
           $ base+cfun/lisp.run -M base+cfun/lispinit.mem -i callcfun
           > (test-c-call::call-cfun)
           i = 5
           s = A Lisp string
           r->x = 10
           r->s = Another Lisp string
           a[0] = 0.
           a[1] = 1.
           a[2] = 2.
           a[3] = 3.
           a[4] = 4.
           a[5] = 5.
           a[6] = 6.
           a[7] = 7.
           a[8] = 8.
           a[9] = 9.
           #S(TEST-C-CALL::CFUNR :X 10 :S "A C string")
           >
           $ rm -r base+cfun

Note that there is a memory leak here: The return value `r2` of `cfun()` is `malloc()`ed but never `free()`d. Specifying

           (:return-type (c-ptr cfunr) :malloc-free)

is not an alternative because this would also `free(r2->x)` but `r2->x` is a pointer to static data.

Ex. 5: To sort an array of double-floats using the Lisp function `sort` instead of the C library function `qsort()`, one can use the following interface code `"sort1.c"`. The main problem is to pass a variable-sized array.

           extern void lispsort_begin (int);
           void* lispsort_function;
           void lispsort_double (int n, double * array)
           {
               double * sorted_array;
               int i;
               lispsort_begin(n); /* store #'sort2 in lispsort_function */
               sorted_array = ((double * (*) (double *)) lispsort_function) (array);
               for (i = 0; i < n; i++) array[i] = sorted_array[i];
               free(sorted_array);
           }

This is accompanied by `"sort2.lisp"`:

           (use-package "FFI")
           (def-call-in lispsort_begin (:arguments (n int))
                                       (:return-type nil)
                                       (:language :stdc)
           )
           (def-c-var lispsort_function (:type c-pointer))
           (defun lispsort_begin (n)
             (setf (cast lispsort_function
                         `(c-function
                            (:arguments (v (c-ptr (c-array double-float ,n))))
                            (:return-type (c-ptr (c-array double-float ,n))
                                          :malloc-free
                          ) )
                   )
                   #'sort2
           ) )
           (defun sort2 (v)
             (declare (type vector v))
             (sort v #'<)
           )

To test this, use the following test file `"sorttest.lisp"`:

           (def-call-out sort10
                         (:name "lispsort_double")
                         (:language :stdc)
                         (:arguments (n int)
                                     (array (c-ptr (c-array double-float 10))
                                            :in-out
           )             )           )

Now try

           $ clisp-link create-module-set sort sort2.c sorttest.c
           $ cc -O -c sort1.c
           $ cd sort
           $ ln -s ../sort1.o sort1.o
           Add sort1.o to NEW_LIBS and NEW_FILES in link.sh.
           $ cd ..
           $ base/lisp.run -M base/lispinit.mem -c sort2.lisp sorttest.lisp
           $ clisp-link add-module-set sort base base+sort
           $ base+sort/lisp.run -M base+sort/lispinit.mem -i sort2 sorttest
           > (sort10 10 '#(0.501d0 0.528d0 0.615d0 0.550d0 0.711d0
                           0.523d0 0.585d0 0.670d0 0.271d0 0.063d0))
           #(0.063d0 0.271d0 0.501d0 0.523d0 0.528d0 0.55d0 0.585d0 0.615d0 0.67d0 0.711d0)
           $ rm -r base+sort

### Extensions-2.4. The Amiga Foreign Function Call Facility

Platform dependent: Amiga platforms only.

#### Another Foreign Function Interface

All symbols relating to the simple foreign function interface are exported from the package `AFFI`. To use them, `(use-package "AFFI")`.

#### Design issues

AFFI was designed to be small in size but powerful enough to use most library functions. Lisp files may be compiled to `.fas` files without the need to load function definition files at run-time and without external C or linker support. Memory images can be created, provided that the function libraries are opened at run-time.

Therefore, AFFI supports only primitive C types (integers 8, 16 and 32 bits wide, signed or unsigned, pointers) and defines no new types or classes. Foreign functions are not first-class objects (you can define a lambda yourself), name spaces are separate.

The AFFI does no tracking of resources. Use `finalize`.

#### Overview

These are the AFFI forms:

`(declare-library-base keyword-base library-name)`

`(require-library-functions library-name [(:import {string-name}*)])`

`(open-library base-symbol)`

`(clos-library base-symbol)`

`(with-open-library (base-symbol | library-name) {form}*)`

`(defflibfun function-name base-symbol offset mask result-type {argument-type}*)`

`(declare-library-function function-name library-name {option}*)`

`(flibcall function-name {argument}*)`

`(mlibcall function-name {argument}*)`

`(mem-read address result-type [offset])`

`(mem-write address type value [offset])`

`(mem-write-vector address vector [offset])`

`(nzero-pointer-p value)`

Except for `with-open-library`, `declare-library-function` and `mlibcall`, all of the above are functions.

A library contains a collection of functions. The library is referred to by a symbol referred as library-base at the AFFI level. This symbol is created in the package `AFFI`. The link between this symbol and the OS-level library name is established by `declare-library-base`. To avoid multiple package conflicts, this and only this function requires the symbol-name to be in the `KEYWORD` package. The function returns the library-base.

A library may be opened by `open-library` and closed by `close-library`. An opened library must be closed. `with-open-library` is provided to automatically close the library for you, thus it is much safer to use.

A function is contained in a library. Every function is referred to by a symbol. A function is defined through `defflibfun` or `declare-library-function` by giving the function name, the library-base, an offset into the library, a mask (or `nil`) for register-based library calls, the result type and all parameter-types. `require-library-functions` loads the complete set of functions defined in a library file. Symbols are created in the package `AFFI` and imported into the current package.

`flibcall` and `mlibcall` call library functions. `mlibcall` is a macro that does a few checks at macroexpansion time and allows the compiler to inline the call, not requiring the foreign function to be defined again at load or execution time. The use of this macro is advertised wherever possible.

`mem-read` reads an arbitrary address (with offset for structure references) and returns the given type.

`mem-write` writes an arbitrary address. `mem-write-vector` copies the content of a Lisp `string` or `unsigned-byte` `vector` into memory.

`nzero-pointer-p` tests for non-`NULL` pointers in all recognized representations ( `null`, `unsigned-byte` and `foreign-pointer`).

#### Foreign Libraries

`declare-library-base` ought to be wrapped in an `(eval-when (compile eval load) ...)` form and come before any function is referenced, because the library base symbol must be known.

`open-library` tries to open the library referenced by the base symbol. Therefore it must have been preceded with `declare-library-base`. The call returns `nil` on failure. `open-library` calls nest. Every successful call must be matched by `close-library`. `with-open-library` does this for you and also allows you to specify the library by name, provided that its base has been declared. It is recommended to use this macro and to reference the library by name.

CLISP will not close libraries for you at program exit. [A previous version did so but now AFFI is a module and there are no module exit functions.] Programmers, watch `affi::*libraries-alist*`.

#### (Foreign) C types

The following foreign C types are used in AFFI. They are not regular Common Lisp types or CLOS classes.

AFFI name | Lisp equiv | C equiv | Comment
--- | --- | --- | ---
`nil` | `nil` | `void` | as a result type for functions only
`4` | `(unsigned-byte 32)` | `unsigned long`
`2` | `(unsigned-byte 16)` | `unsigned short`
`1` | `(unsigned-byte 8)` | `unsigned char`
`-4` | `(signed-byte 32)` | `long`
`-2` | `(signed-byte 16)` | `short`
`-1` | `(signed-byte 8)` | `signed char`
`0` | `boolean` | `BOOL` | as a result type for functions only
`*` | opaque | `void*`
`:external` | opaque | `void*`
`string` | `string` or `vector` | `char*`
`:io` | `string` or `vector` | `char*`

Objects of type `string` are copied and passed NUL-terminated on the execution stack. On return, a Lisp string is allocated and filled from the address returned (unless NULL). Functions with `:io` parameters are passed the address of the Lisp string or unsigned byte vector. These are not NUL-terminated! This is useful for functions like like `read()` which do not need an array at a constant address longer than the dynamic extent of the call (it is dangerous to define callback functions with `:io` (or `string`) type parameters). Arguments of type `integer` and `foreign-pointer` are always acceptable where a `string` or `:io` type is specified.

Platform dependent: Only in CLISP built with compile-time flag `UNICODE`.
  A symbol-macro place `lisp:*foreign-encoding*` contains the encoding for characters and strings passed through the FFI. Its value must be a 1:1 encoding, i.e., an encoding in which every character is represented by one byte.

To meet the design goals, predefined types and objects were used. As such, pointers were represented as integers. Now that there is the `foreign-pointer` type, both representations may be used on input. The pointer type should be therefore considered as opaque. Use `nzero-pointer-p` for NULL tests.

#### Foreign functions

Foreign Functions are declared either through `defflibfun` or`declare-library-function`. The former is closer to the low-level implementation of the interface, the latter is closer to the other FFI.

`defflibfun` requires the library base symbol and register mask to be specified, `declare-library-function` requires the library name and computes the mask from the declaration of the arguments.

The value of mask is implementation-dependent. On the Amiga, it is an integer whose hexadecimal value is the reverse of the function argument register numbers, where d0 has number `1` and a6 number `#xF`. A `nil` mask is reserved for stack-based calls (unimplemented).

The AFFI type `0` is only acceptable as a function result type and yields either `t` or `nil`. The difference between `*` and `:external` is the following: `*` uses integers, `:external` uses `foreign-pointer` as function result-type (except from `nil` for a NULL pointer) and refuses objects of type `string` or unsigned byte vector as input. Thus `:external` provides some security on the input and the ability to use `lisp:finalize` for resource-tracking on the output side.

`(declare-library-function name library-name {option}*)`

option ::=
| `(:offset library-offset)`
| | `(:arguments {(arg-name AFFI-type register)}*)`
| | `(:return-type AFFI-type)`

register ::= | `:d0` | `:d1` | ... | `:d7` | `:a0` | ... | `:a6`

declares a named library function for further reference through `flibcall` and `mlibcall`.

`mlibcall` should be the preferred way of calling foreign functions (when they are known at compile-time) as macroexpansion-time checks may be performed and the call can be sort of inlined.

#### Memory access

`(mem-read address type offset)` can read 8, 16 and 32 bit signed or unsigned integers (AFFI types `-4`, `-2`, `-1`, `1`, `2`, `4`), a pointer (`*`), a NUL-terminated string (`string`) or, if the type argument is of type `string` or unsigned byte vector, it can fill this vector. `:external` is not an acceptable type as no object can be created by using `mem-read`.

`(mem-write address type value [offset])` writes integers (AFFI type `-4`, `-2`, `-1`, `1`, `2` and `4`) or pointer values (type `*`), but not vectors to the specified memory address.

`(mem-write-vector address vector [offset])` can write memory from the given vector (of type `string` or unsigned byte vector).

#### Function Definition Files

`require-library-functions` will `require` a file of name derived from thelibrary name and with type `"affi"`. It may be used to import all names into the current package or only a given subset identified by string names, using the `:import` keyword (recommended use). Some definition files for standard Amiga libraries are provided. See example 1 below.

As `require-library-functions` loads a global file which you, the programmer, may have not defined, you may consider declaring every function yourself to be certain what the return and argument types are. See example 4 below.

The file `read-fd.lisp` defines the function `make-partial-fd-file` with which the provided `".affi"` files have been prepared from the original Amiga FD files (located in the directory `FD:`). They must still be edited as the function cannot know whether a function accepts a `*`, `:io`, `string` or `:external` argument and because files in `FD:` only contain a register specification, not the width of integer arguments (`-4`, `-2`, `-1`, `1`, `2`, or `4`).

#### Hints

By using appropriate `eval-when` forms for `declare-library-base` and `require-library-functions` and not using `flibcall`, it is possible to write code that only loads library function definition files at compile-time. See example 1 below.

Do not rely on `finalize` to free resources for you, as CLISP does not call finalizers when it exits, use `unwind-protect`.

#### Caveats

You can consider the library bases being symbols in need of being imported from the package AFFI originating from a brain-damage, causing the usual symbol headaches when using foreign functions calls within macros. Luckily, even if the high-level interface (or its implementation in `affi1.lisp`) were to change, the low-level part (`affi.d`) should remain untouched as all it knows are integers and foreign-pointers, no symbols. The difficulty is just to get the library base value at run-time. Feel free to suggest enhancements to this facility!

#### Examples

NB: These examples are somewhat specific to the Amiga.

1. Using a predefined library function file

    (use-package "AFFI")

    ;; SysBase is the conventional name for exec.library
    ;; It is only enforced by the file loaded by REQUIRE-LIBRARY-FUNCTIONS
    (eval-when (compile eval load)
      (declare-library-base :SysBase "exec.library")) ;keyword avoids name conflicts

    ;; using only MLIBCALL allows not to load definitions at load-time
    (eval-when (compile eval)
      (require-library-functions "exec.library"
        :import '("FindTask")))

    (with-open-library ("exec.library")
      (print (mlibcall FindTask 0)))

This file can be used in interpreted and compiled mode. Compiled, it will have inlined the library function calls.

2. Using flibcall

    (use-package "AFFI")

    (eval-when (compile eval load)
      (declare-library-base :SysBase "exec.library")) ;keyword avoids name conflicts

    ;; The load situation permits the use of flibcall
    (eval-when (eval compile load)
      (require-library-functions "exec.library"))

    (unless (open-library 'SysBase) (error "No library for SysBase"))
    (flibcall (if t 'FindTask 'Debug) 0)
    (close-library 'SysBase)

3. Be fully dynamic, defining library bases ourselves

    (use-package "AFFI")

    (eval-when (compile eval load)
      (defvar mylib (declare-library-base :foobase "foo.library")))
    (eval-when (eval compile load)          ;eval allows mlibcall, load flibcall
      (defflibfun 'foo1 mylib -30 '#xA '* 'string)
      (defflibfun 'foo2 mylib -36 '#x21 0 * 4))

    (defun foo (name)
      (when (open-library mylib)
        (list (mlibcall foo1 name) (flibcall 'foo2 name 123213))
        (close-library mylib)))

4. Some sample function definitions

    (defflibfun 'FindTask 'SysBase -294 #xA '* 'string)
    (declare-library-function FindTask "exec.library"
      (:offset -294)
      (:return-type *)
      (:arguments
       (name   string   :A1)))
    (declare-library-function NameFromLock "dos.library"
      (:offset -402)
      (:return-type 0)
      (:arguments
       (lock   4   :D1)
       (buffer :io :D2)
       (len    4   :D3)))

    (eval-when (compile eval)
      (defconstant GVF_LOCAL_ONLY (ash 1 9))
      (defflibfun 'SetVar 'DosBase -900 #x5432 0 'string 'string -4 4))
    (defun setvar (name value)
      (with-open-library (DosBase)
        ;; length of -1 means find length of NUL-terminated-string
        (mlibcall SetVar name value -1 GVF_LOCAL_ONLY)))

### Extensions-2.5. ARexx

Platform dependent: Amiga platforms only.

CLISP comes with a small yet extensible and powerful ARexx interface.

`(rexx-do-command "return address()" :string t :result t)`
tells you the name of the CLISP ARexx port. The default extension for CLISP ARexx scripts is `"cl"`.

`(REXX-DO-COMMAND command &key :string :result :token :io :host)`
-> `(RC &optional result)`, or `nil` on failure

`(REXX-RUN-COMMAND command &KEY :string :token)`
-> `t`, or `nil` on failure

`(REXX-SEND-COMMAND command &KEY :string :result :token :io :host)`
-> arexx-msg-handle, or `nil` on failure

`(REXX-WAIT-SENT-COMMAND arexx-msg-handle)`
-> `(RC &optional result)`, or `nil` on failure

`(REXX-LOOP)`
-> no return, use the `exit-loop.cl` ARexx script to abort the loop

command may be a string denoting a command with optional arguments or a vector of strings thus denoting an ARexx function call. The first element in the vector is the function name, the others are the up to 15 arguments.

Messages may be sent to an arbitrary ARexx host, special cases are `nil` (meaning `"REXX"`, the default) and `t` (`"AREXX"` for asynchronous execution).

ARexx server mode: Like Ispell, Csh and SKsh, you can run it in server mode by calling `(rexx-loop)`. You can then only exit with the ARexx `exit-loop.cl` script.

Restrictions: Currently CLISP is not able to wait for input from several sources, e.g. both a console and ARexx, at the same time.

### Extensions-2.6. Socket Streams

Platform dependent: UNIX, Win32 platforms only.

`(lisp:socket-server &optional [port-or-socket])`
  This function creates a socket, binds a port to the socket, and then listens for connect attempts. The server exists to watch for client connect attempts. The optional argument is either a port (positive fixnum) or a socket-stream (from whose peer the connections will be made).
`(lisp:socket-server-close socket-server)`
  Closes down the server socket.
`(lisp:socket-server-port socket-server)`
  Returns the port which was bound using `lisp:socket-server`.
`(lisp:socket-wait socket-server &optional [seconds [microseconds]])`
  Given time argument(s), waits for (possibly zero) fixed duration for a connect on the socket-server. Without an argument, `socket-wait` blocks indefinitely.
`(lisp:socket-accept socket-server &key [:element-type] [:external-format] [:buffered])`
  Creates the server-side two-way stream for the connection.
`(lisp:socket-connect port &optional [host] &key [:element-type] [:external-format] [:buffered])`
  Attempts to create a client-side two-way stream. Blocks until the server accepts the connections.
`(lisp:socket-stream-host socket-stream)`
`(lisp:socket-stream-port socket-stream)`
  These two functions return information about the socket stream. For a server, `lisp:socket-stream-host` returns `nil`.
`(lisp:socket-service-port &optional "service-name" (protocol "tcp"))`
  A convenience function for looking up a port given the service name. It returns the servent struct as multiple values (name, list of aliases, port, protocol) for the given `service-name` and `protocol`, or all services as the list of vectors of length 4, if `service-name` is not given or is `:default` or `nil`.
`(lisp:socket-stream-peer socket-stream)`
  Given a stream, this function returns the name of the host on the opposite side of the connection and its port number; the server-side can use this to see who connected.
`(lisp:socket-stream-local socket-stream)`
  The dual to `lisp:socket-stream-peer` - same information, host name and port number, but for the local host.

### Extensions-2.7. System Calls

When CLISP is configured with an option `--with-export-syscalls`, some system calls are available from lisp, in package `POSIX`.

`(posix:resolve-host-ipaddr &optional host)`
  Returns the hostent struct (name, list of aliases, list of IP addresses as dotted quads (for IPv4) or coloned octets (for IPv6), address type - IPv4 or IPv6). When `host` is omitted or `:default`, return the data for the current host. When `host` is given and is `nil`, all the host database is returned as a list of vectors of length 4 (this would be the contents of the /etc/hosts file on a UNIX system or ${windir}/system32/etc/hosts on a Win32 system).
`(posix:file-stat file &optional link-p)`
  Return the stat struct. `file` can be a stream, a pathname, a string or a number (on a UNIX system, meaning file descriptor). The first slot of the struct returned is the string or the number on which `stat`(2)/`fstat`(2)/`lstat`(2) was called. The other 13 slots are numbers, members of the stat struct: device, inode, protection, number of hard links, owner's UID, owner's GID, device type, total size (bytes), blocksize for filesystem I/O, number of blocks allocated, atime, mtime, ctime (as number of seconds since 1900-01-01). If the system does not support a particular field (e.g., Win32 does not have hard links), `nil` (or the default, like 1 for the number of hard links for Win32 or DOS) is returned.
  [UNIX systems only at this time, patches are welcome.]
`(posix:user-data &optional user)`
  Return the passwd struct (name, encoded password, UID, GID, full name, home directory, shell). When `user` is `nil`, return all users. When `user` is `:default` or not supplied, return the information about the current user. If the system does not support a particular field (e.g., Win32 does not have a concept of a shell), `nil` (or the default, like c:\command.com for DOS) is returned.
  [UNIX systems only at this time, patches are welcome.]
  `(posix:sysinfo)`
  Return a struct describing the OS, derived from `uname(2)` and `sysconf(3)`.
  `(posix:resource-usage-limits)`
  Return 3 structs describing the resources usage and limits, derived from `getrlimit(2)` and `getrusage(3)`.
`(posix:erf real)`
`(posix:erfc real)`
`(posix:j0 real)`
`(posix:j1 real)`
`(posix:jn int real)`
`(posix:y0 real)`
`(posix:y1 real)`
`(posix:yn int real)`
`(posix:gamma real)`
`(posix:lgamma real)`
  Compute the error functions, Bessel functions and Gamma. These functions are required by the POSIX standard and should be available in libm.so. Please note that these functions do not provide lisp-style error handling and precision, and all the computations at the double float level.
  [UNIX systems only at this time, patches are welcome.]

### Extensions-2.8. Quickstarting delivery with CLISP

This section describes four ways to turn CLISP programs into executable programs, which can be started as quickly as executables written in other languages.

UNIX
  CLISP can act as a script interpreter.
Desktop environments such as KDE, GNOME, or Windows.
  Files created with CLISP can be associated with the CLISP executables so that clicking on them would make CLISP execute the appropriate code.
Linux with `CONFIG_BINFMT_MISC=y`
  Associate the extensions `fas` and `lisp` with CLISP; then you can make the files executable and run them from the command line.
Amiga
  Files created with CLISP can be associated with a Workbench project icon so that clicking on them would make CLISP execute the appropriate code. Note that several `fas` files can be concatenated (using `Join`) into one file.

These three techniques apply to a single `lisp` or `fas` file. If your application is made up of several `lisp` or `fas` files, you can simply concatenate them (using `cat`(1)) into one file; the techniques then apply to that concatenated file.

Platform dependent: UNIX platforms only.
  On Unix, a text file (`fas` or `lisp`) can be made executable by adding a first line of the form

      #!interpreter [interpreter-args]

  and using `chmod`(1) to make the script executable. CLISP can be used as a script interpreter under the following circumstances:

  1. The interpreter must be a full pathname of CLISP. I recommend using `/usr/local/bin/clisp`, and if CLISP is actually installed elsewhere, letting `/usr/local/bin/clisp` be a symbolic link to the real CLISP.

  2. The interpreter must be a real executable, not a script. Unfortunately, in the binary distributions of CLISP on Solaris, `clisp` is a shell script because a C compiler cannot be assumed to be installed on this platform. If you have a C compiler installed, build CLISP from source yourself; "`make install`" will install `clisp` as a real executable.

  3. On some platforms, the first line "`#!interpreter [interpreter-args]`" is limited in length:
     - max. 32 characters on SunOS 4,
     - max. 80 characters on HP-UX,
     - max. 127 characters on Linux.
     Characters exceeding this limit are simply cut off by the system. At least 128 characters are accepted on Solaris, IRIX, AIX, OSF/1. There is no workaround: You have to keep the interpreter pathname and arguments short.

  4. On Solaris and HP-UX, only the first interpreter-arg is passed to the interpreter. In order to pass more than one option (for example, "`-Msomewhere.mem`" and "`-C`") to `clisp`, separate them by hard spaces (ISO Latin-1 character 160) instead of normal spaces. (But the separator between interpreter and interpreter-args must still be a normal space!) CLISP will split the interpreter-args at hard spaces and at normal spaces.

  The script should contain Lisp forms, except in the #! line. The file is normally loaded, through the function `load`. Before it is loaded, the variable `lisp:*args*` is bound to a list of strings, representing the arguments given to the Lisp script. `*standard-input*` and `*standard-output*` are bound, as usual, to the Unix standard input and output. `*error-output*` is bound to the Unix error output. Continuable errors will be turned to warnings. Non-continuable errors and Ctrl-C interrupts will terminate the execution of the Lisp script with error status. If you wish the script's contents to be compiled during loading, add `-C` to the interpreter-args.

  Another, quite inferior, alternative is to put the following into a file:

      #!/bin/sh
      exec clisp <<EOF
      (lisp-form)
      (another-lisp-form)
      (yet-another-lisp-form)
      EOF

  The problem with this approach is that the return values of each form will be printed to the standard output. Another problem is that no user input will be available.

Platform dependent: Windows platforms only.
  There are two different ways to make CLISP "executables" for Windows platforms.
  - Associate the `mem` extension with `"c:\clisp\lisp.exe -m 10M -M %s -N c:\clisp\locale"`.
  - Associate the `fas` extension with `"c:\clisp\lisp.exe -m 10M -M c:\clisp\lispinit.mem -N c:\clisp\locale -i %s"`. Alternatively, you may want to have a function `main` in your files and associate the `fas` extension with `"c:\clisp\lisp.exe -m 10M -M c:\clisp\lispinit.mem -N c:\clisp\locale -i %s -x (main)"`.

  Then clicking on the compiled lisp file (with `fas` extension) will load the file (thus executing all the code in the file), while the clicking on a CLISP memory image (with `mem` extension) will start clisp with the given memory image.

Platform dependent: Linux platforms only.
  You have to build your kernel with `CONFIG_BINFMT_MISC=y` and `CONFIG_PROC_FS=y`. Then you will have a `/proc/sys/fs/binfmt_misc/` directory and you will be able to do (as `root`; you might want to put these lines into `/etc/rc.d/rc.local`):

      bash# echo ":CLISP:E::fas::/usr/bin/clisp:" >> /proc/sys/fs/binfmt_misc/register
      bash# echo ":CLISP:E::lisp::/usr/bin/clisp:" >> /proc/sys/fs/binfmt_misc/register

  Then you can do the following:

      bash$ cat << EOF > hello.lisp
      (print "hello, world!")
      EOF
      bash$ clisp -c hello.lisp

      Compiling file /home/sds/hello.lisp ...

      Compilation of file /home/sds/hello.lisp is finished.
      0 errors, 0 warnings
      bash$ chmod +x hello.fas
      bash$ hello.fas

      "hello, world!"
      bash$

  Please read `/usr/src/linux/Documentation/binfmt_misc.txt` for details.

Platform dependent: Amiga platforms only.
  Using a Workbench project file, the memory images, source and binary files can be made "executable".
  - Using IconEdit, create a project icon.
  - Set the tool to `lisp:lisp.run` (or wherever the binary is located).
  - Define a tooltype named `ARGS` set to `-M *` for a memory image project icon or to `-M lisp:lispinit.mem -i *` for a source or compiled lisp file. The startup code will replace an isolated `*` token with the file name.
  - Alternatively, you may want to have a function `main` in your files and set the `ARGS` tooltype to `-M lisp:lispinit.mem -i * -x (main)`.
  - You might want to add more command line options to the `ARGS` tooltype.

  Clicking on the compiled lisp file (with `fas` suffix) will load the image and the file (thus executing all the code in the file), while clicking on the CLISP's memory image (with `mem` suffix) with start clisp with the given memory image.

  You might want to add a tooltype named `WINDOW` which names the console window that `*terminal-io*` will be bound to, for example `CON:0/0/500/300/CLISP-Listener/AUTO/CLOSE`, or `TCP:20002`.

### Extensions-2.9. Application delivery with CLISP

Some ways of packaging CLISP programs are discussed in the section Quickstarting delivery with CLISP.

CLISP is Free Software, covered by the GNU GPL, with special terms governing the distribution of applications that run in CLISP. The precise terms can be found in the COPYRIGHT file contained in the source and binary distributions of CLISP. Here is an informal clarification what these terms mean in practice. Please refer to the said COPYRIGHT file when in doubt.

In many cases, CLISP does not force an application to be covered by the GNU GPL. Nevertheless, we encourage you to release your software under an open source copyright. The benefits of such a copyright for your users are numerous, in particular they are free to modify the application when their needs/requirements change, and they are free to recompile the application when they upgrade their machine or operating system.

CLISP extensions, i.e. programs which need to access non-portable CLISP internal symbols (in the packages SYSTEM, COMPILER, CLOS, FFI, ...), must be covered by GNU GPL as well.

Other programs running in CLISP have to or need not to be placed under GNU GPL, depending on their distribution form:

- Programs distributed as Lisp source of .fas files can be distributed without restrictions coming from CLISP.
- Programs distributed as CLISP memory images can be distributed only if accompanied with the non-CLISP .fas files which make up the memory image, and a Makefile for rebuilding the memory image.
- If you need to distribute a modified CLISP executable (for example, incorporating additional modules written in C), you must distribute its full source under GNU GPL. If you are not satisfied with this, you can instead put the additional modules into a separate (non-CLISP) program, with which your Lisp program will communicate via sockets.

### Extensions-2.10. Shell Access

Platform dependent: UNIX, DOS, OS/2, Acorn platforms only.
  `(lisp:execute programfile arg1 arg2 ...)` executes an external program. Its name is programfile. It is given the strings arg1, arg2, ... as arguments.
Platform dependent: Amiga platforms only.
  `(lisp:execute command)` executes a given command using the operating system's shell.

Platform dependent: UNIX, DOS, OS/2, Win32, Amiga, Acorn platforms only.
  `(lisp:shell [command])` calls the operating system's shell. `(lisp:shell)` calls the shell for interactive use. `(lisp:shell command)` calls the shell only for execution of the one given command.

Platform dependent: UNIX, OS/2, Win32 platforms only.
  The functions `lisp:run-shell-command` and `lisp:run-program` are a general interface to `lisp:shell` and the above:

  `(run-shell-command command [:input] [:output] [:if-output-exists])` runs a shell command.

  `(run-program program [:arguments] [:input] [:output] [:if-output-exists])` runs an external program.

  command
    the shell command.
    Platform dependent: UNIX platforms only.
      The shell the command is passed to is the value of the environment variable `SHELL`, which normally is `/bin/sh`. The command should be a ``simple command''; a ``command list'' should be enclosed in "{ ... ; }" (for `/bin/sh`) or "( ... )" (for `/bin/csh`).
  program
    the program. The directories listed in the `PATH` environment variable will be searched for it.
  `:arguments`
    a list of arguments (strings) that are given to the program.
  `:input`
    where the program's input is to come from: either `:terminal` (the standard input) or `:stream` (a Lisp stream to be created) or a pathname (an input file) or `nil` (no input at all).
  `:output`
    where the program's output is to be sent to: either `:terminal` (the standard output) or `:stream` (a Lisp stream to be created) or a pathname (an output file) or `nil` (ignore the output).
  `:if-output-exists`
    what to do if the `:output` file already exists. The possible values are `:overwrite`, `:append`, `:error`, with the same meaning as for `open`.

  If `:stream` was specified for `:input` or `:output`, a Lisp stream is returned. If `:stream` was specified for `:input` and `:output`, three Lisp streams are returned, as for the function `lisp:make-pipe-io-stream`. This use of `lisp:run-program` can cause deadlocks, see `lisp:make-pipe-io-stream`.

### Extensions-2.11. Other

Platform dependent: Amiga platforms only.
  To have `*debug-io*` and `*error-output*` point to separate console windows (thus keeping your standard console window clean from error messages) you can use

        (setq *error-output*
          (setq *debug-io*
            (open "CON:0/0/500/300/CLISP-Debugger/AUTO/CLOSE" :direction :io)
        ) )

  at startup.

## Authors

| Bruno Haible |  |  | Michael Stoll
| 17, rue Danton |  |  | Westerwaldweg 22
F - | 94270 Le Kremlin-Bicêtre |  | D - | 53424 Remagen-Oberwinter
| France |  |  | Germany

## Current Maintainers

- haible@clisp.cons.org
- sds@clisp.cons.org

### CLISP implementation notes

Bruno Haible
Sam Steingold

Bugs in both these notes and CLISP itself should be sent to:

Valid HTML 3.2!