diff --git a/doc/further_reading.md b/doc/further_reading.md index 9d97f5a..3dfd32c 100644 --- a/doc/further_reading.md +++ b/doc/further_reading.md @@ -1,7 +1,16 @@ # Further Reading 1. [CODING for the MIT-IBM 704 COMPUTER, October 1957](http://bitsavers.org/pdf/mit/computer_center/Coding_for_the_MIT-IBM_704_Computer_Oct57.pdf) + This paper is not about Lisp. But it is about the particular individual computer on which Lisp was first implemented, and it is written in part by members of the Lisp team. I have found it useful in understanding the software environment in which, and the constraints under which, Lisp was written. 2. [MIT AI Memo 1, John McCarthy, September 1958](https://www.softwarepreservation.org/projects/LISP/MIT/AIM-001.pdf) + This is, as far as I can find, the earliest specification document of the Lisp project. 3. [Lisp 1 Programmer's Manual, Phyllis Fox, March 1960](https://bitsavers.org/pdf/mit/rle_lisp/LISP_I_Programmers_Manual_Mar60.pdf) 4. [Lisp 1.5 Programmer's Manual, Michael I. Levin, August 1962](https://www.softwarepreservation.org/projects/LISP/book/LISP%201.5%20Programmers%20Manual.pdf#page=81) + This book is essential reading: it documents in some detail the first fully realised Lisp language system. 5. [Early LISP History (1956 - 1959), Herbert Stoyan, August 1984](https://dl.acm.org/doi/pdf/10.1145/800055.802047#page=3) + + +6. [The Roots of Lisp, Paul Graham, 2001](http://www.paulgraham.com/rootsoflisp.html) +6. [The Revenge of the Nerds, Paul Graham, 2002](http://www.paulgraham.com/icad.html) + This is mainly about why to use Lisp as a language for modern commercial software, but has useful insights into where it comes from. + > So the short explanation of why this 1950s language is not obsolete is that it was not technology but math, and math doesn't get stale. \ No newline at end of file diff --git a/doc/lisp1.5.md b/doc/lisp1.5.md index 116cf53..972389f 100644 --- a/doc/lisp1.5.md +++ b/doc/lisp1.5.md @@ -5,10 +5,10 @@ **Massachusetts Institute of Technology** -> John McCarthy -> Paul W. Abrahams -> Daniel J. Edwards -> Timothy P. Hart +> [John McCarthy](https://en.wikipedia.org/wiki/John_McCarthy_(computer_scientist)) +> [Paul W. Abrahams](https://mitpress.mit.edu/author/paul-w-abrahams-31449/) +> [Daniel J. Edwards](https://www.chessprogramming.org/Daniel_Edwards) +> [Timothy P. Hart](https://www.chessprogramming.org/Timothy_Hart) > The M. I.T. Press > Massachusetts Institute of Technology @@ -43,11 +43,11 @@ The over-all design of the LISP Programming System is the work of John McCarthy This manual was written by Michael I. Levin. -The interpreter was programmed by Stephen B. Russell and Daniel J. Edwards. The print and read programs were written by John McCarthy, Klim Maling, Daniel J. Edwards, and Paul W, Abrahams. +The interpreter was programmed by [Stephen B. Russell](https://en.wikipedia.org/wiki/Steve_Russell_(computer_scientist)) and Daniel J. Edwards. The print and read programs were written by John McCarthy, Klim Maling, Daniel J. Edwards, and Paul W. Abrahams. The garbage collector and arithmetic features Were written by Daniel J. Edwards. The compiler and assembler were written by Timothy P. Hart and Michael I. Levin. An earlier compiler was written by Robert Brayton. -The "LISP 1 Programmer's Manual" March 1, 1960, was written by Phyllis A. Fox. Additional programs and suggestions were contributed by the following members of the Artificial Intelligence Group of the Research Laboratory of Electronics: Marvin L. Minsky, Bertram Raphael, Louis Hodes, David M. R. Park, David C. Luckham, Daniel G. Bobrow, James R. Slagle, and Nathaniel Rochester. +The "LISP 1 Programmer's Manual" March 1, 1960, was written by [Phyllis A. Fox](https://en.wikipedia.org/wiki/Phyllis_Fox). Additional programs and suggestions were contributed by the following members of the Artificial Intelligence Group of the Research Laboratory of Electronics: Marvin L. Minsky, Bertram Raphael, Louis Hodes, David M. R. Park, David C. Luckham, Daniel G. Bobrow, James R. Slagle, and Nathaniel Rochester. August 17, 1962 @@ -3347,7 +3347,7 @@ eval[form; a]= [ eq[car[form]; QUOTE] -> cadr[form]; eq[car[form]; FUNCTION] -> list[FUNARG; cadr[form]; a]; eq[car [form]; COND] -> evcon[cdr[form]; a]; - eq[car [form]; PROG] -> prog[cdr [form]; a]; + eq[car [form]; PROG] -> prog[cdr[form]; a]; atom[car[form]] -> [get[car [form]; EXPR] -> apply[expr; evlis[cdr[form]; a]; a]; get[car[form]; FEXPR] -> @@ -3375,27 +3375,18 @@ The PROG feature is an FSUBR coded into the system. It can best be explained in English, although it is possible to define it by using M-expressions. 1. As soon as the PROG feature is entered, the list of program variables is used -to make a new list in which each one is paired with NIL. This is then appended to the -current a-list. Thus each program variable is set to NIL at the entrance to the program. +to make a new list in which each one is paired with NIL. This is then appended to the current a-list. Thus each program variable is set to NIL at the entrance to the program. 2. The remainder of the program is searched for atomic symbols that are under- -stood to be location symbols. A go-list is formed in which each location symbol is -paired with a pointer into the remainder of the program. -3. When a set or a setq - is encountered, the name of the variable is located on the -a-list. The value of the variable (or cs of the pair) is actually replaced with the new -value. +stood to be location symbols. A go-list is formed in which each location symbol is paired with a pointer into the remainder of the program. +3. When a set or a setq - is encountered, the name of the variable is located on the a-list. The value of the variable (or cdr of the pair) is actually replaced with the new value. ----- -1. The value of get is set aside. This is the meaning of the apparent free or unde- -fined variable- -2. In the actual system this is handled by an FSUBR rather than as the separate special -case as shown here. +1. The value of get is set aside. This is the meaning of the apparent free or undefined variable. +2. In the actual system this is handled by an FSUBR rather than as the separate special case as shown here. page 72 -If the variable is bound several times on the a-list, only the first or most recent -occurrence is changed. If the current binding of the variable is at a higher level than -the entrance to the prog, then the change will remain in effect throughout the scope -of that binding, and the old value will be lost. +If the variable is bound several times on the a-list, only the first or most recent occurrence is changed. If the current binding of the variable is at a higher level than the entrance to the prog, then the change will remain in effect throughout the scope of that binding, and the old value will be lost. If the variable does not occur on the a-list, then error diagnostic `A4` or `A5` will occur. diff --git a/docs/codox/beowulf.bootstrap.html b/docs/codox/beowulf.bootstrap.html index 068508a..e43c121 100644 --- a/docs/codox/beowulf.bootstrap.html +++ b/docs/codox/beowulf.bootstrap.html @@ -1,13 +1,17 @@ -beowulf.bootstrap documentation

beowulf.bootstrap

Lisp as defined in Chapter 1 (pages 1-14) of the Lisp 1.5 Programmer's Manual; that is to say, a very simple Lisp language, which should, I believe, be sufficient in conjunction with the functions provided by beowulf.host, be sufficient to bootstrap the full Lisp 1.5 interpreter..

+beowulf.bootstrap documentation

beowulf.bootstrap

Lisp as defined in Chapter 1 (pages 1-14) of the Lisp 1.5 Programmer's Manual; that is to say, a very simple Lisp language, which should, I believe, be sufficient in conjunction with the functions provided by beowulf.host, be sufficient to bootstrap the full Lisp 1.5 interpreter..

The convention is adopted that functions in this file with names in ALLUPPERCASE are Lisp 1.5 functions (although written in Clojure) and that therefore all arguments must be numbers, symbols or beowulf.cons_cell.ConsCell objects.

APPLY

(APPLY function args environment depth)

Apply this function to these arguments in this environment and return the result.

-

For bootstrapping, at least, a version of APPLY written in Clojure. All args are assumed to be symbols or beowulf.cons-cell/ConsCell objects. See page 13 of the Lisp 1.5 Programmers Manual.

CAAAAR

macro

(CAAAAR x)

TODO: write docs

CAAADR

macro

(CAAADR x)

TODO: write docs

CAAAR

macro

(CAAAR x)

TODO: write docs

CAADAR

macro

(CAADAR x)

TODO: write docs

CAADDR

macro

(CAADDR x)

TODO: write docs

CAADR

macro

(CAADR x)

TODO: write docs

CAAR

macro

(CAAR x)

TODO: write docs

CADAAR

macro

(CADAAR x)

TODO: write docs

CADADR

macro

(CADADR x)

TODO: write docs

CADAR

macro

(CADAR x)

TODO: write docs

CADDAR

macro

(CADDAR x)

TODO: write docs

CADDDR

macro

(CADDDR x)

TODO: write docs

CADDR

macro

(CADDR x)

TODO: write docs

CADR

macro

(CADR x)

TODO: write docs

CDAAAR

macro

(CDAAAR x)

TODO: write docs

CDAADR

macro

(CDAADR x)

TODO: write docs

CDAAR

macro

(CDAAR x)

TODO: write docs

CDADAR

macro

(CDADAR x)

TODO: write docs

CDADDR

macro

(CDADDR x)

TODO: write docs

CDADR

macro

(CDADR x)

TODO: write docs

CDAR

macro

(CDAR x)

TODO: write docs

CDDAAR

macro

(CDDAAR x)

TODO: write docs

CDDADR

macro

(CDDADR x)

TODO: write docs

CDDAR

macro

(CDDAR x)

TODO: write docs

CDDDAR

macro

(CDDDAR x)

TODO: write docs

CDDDDR

macro

(CDDDDR x)

TODO: write docs

CDDDR

macro

(CDDDR x)

TODO: write docs

CDDR

macro

(CDDR x)

TODO: write docs

EVAL

(EVAL expr)(EVAL expr env depth)

Evaluate this expr and return the result. If environment is not passed, it defaults to the current value of the global object list. The depth argument is part of the tracing system and should not be set by user code.

-

All args are assumed to be numbers, symbols or beowulf.cons-cell/ConsCell objects.

INTEROP

(INTEROP fn-symbol args)

Clojure (or other host environment) interoperation API. fn-symbol is expected to be either

-
    -
  1. a symbol bound in the host environment to a function; or
  2. -
  3. a sequence (list) of symbols forming a qualified path name bound to a function.
  4. -
-

Lower case characters cannot normally be represented in Lisp 1.5, so both the upper case and lower case variants of fn-symbol will be tried. If the function you’re looking for has a mixed case name, that is not currently accessible.

-

args is expected to be a Lisp 1.5 list of arguments to be passed to that function. Return value must be something acceptable to Lisp 1.5, so either a symbol, a number, or a Lisp 1.5 list.

-

If fn-symbol is not found (even when cast to lower case), or is not a function, or the value returned cannot be represented in Lisp 1.5, an exception is thrown with :cause bound to :interop and :detail set to a value representing the actual problem.

interop-interpret-q-name

(interop-interpret-q-name l)

For interoperation with Clojure, it will often be necessary to pass qualified names that are not representable in Lisp 1.5. This function takes a sequence in the form (PART PART PART... NAME) and returns a symbol in the form PART.PART.PART/NAME. This symbol will then be tried in both that form and lower-cased. Names with hyphens or underscores cannot be represented with this scheme.

QUOTE

macro

(QUOTE f)

Quote, but in upper case for LISP 1.5

to-beowulf

(to-beowulf o)

Return a beowulf-native representation of the Clojure object o. Numbers and symbols are unaffected. Collections have to be converted; strings must be converted to symbols.

to-clojure

(to-clojure l)

If l is a beowulf.cons_cell.ConsCell, return a Clojure list having the same members in the same order.

uaf

(uaf l path)

Universal access function; l is expected to be an arbitrary LISP list, path a (clojure) list of the characters a and d. Intended to make declaring all those fiddly #'c[ad]+r' functions a bit easier

\ No newline at end of file +

For bootstrapping, at least, a version of APPLY written in Clojure. All args are assumed to be symbols or beowulf.cons-cell/ConsCell objects. See page 13 of the Lisp 1.5 Programmers Manual.

EVAL

(EVAL expr)(EVAL expr env depth)

Evaluate this expr and return the result. If environment is not passed, it defaults to the current value of the global object list. The depth argument is part of the tracing system and should not be set by user code.

+

All args are assumed to be numbers, symbols or beowulf.cons-cell/ConsCell objects. However, if called with just a single arg, expr, I’ll assume it’s being called from the Clojure REPL and will coerce the expr to ConsCell.

find-target

TODO: write docs

PROG

(PROG program env depth)

The accursed PROG feature. See page 71 of the manual.

+

Lisp 1.5 introduced PROG, and most Lisps have been stuck with it ever since. It introduces imperative programming into what should be a pure functional language, and consequently it’s going to be a pig to implement.

+

Broadly, PROG is a variadic pseudo function called as a FEXPR (or possibly an FSUBR, although I’m not presently sure that would even work.)

+

The arguments, which are unevaluated, are a list of forms, the first of which is expected tp be a list of symbols which will be treated as names of variables within the program, and the rest of which (the ‘program body’) are either lists or symbols. Lists are treated as Lisp expressions which may be evaulated in turn. Symbols are treated as targets for the GO statement.

+

GO: A GO statement takes the form of (GO target), where target should be one of the symbols which occur at top level among that particular invocation of PROGs arguments. A GO statement may occur at top level in a PROG, or in a clause of a COND statement in a PROG, but not in a function called from the PROG statement. When a GO statement is evaluated, execution should transfer immediately to the expression which is the argument list immediately following the symbol which is its target.

+

If the target is not found, an error with the code A6 should be thrown.

+

RETURN: A RETURN statement takes the form (RETURN value), where value is any value. Following the evaluation of a RETURN statement, the PROG should immediately exit without executing any further expressions, returning the value.

+

SET and SETQ: In addition to the above, if a SET or SETQ expression is encountered in any expression within the PROG body, it should affect not the global object list but instead only the local variables of the program.

+

COND: In strict mode, when in normal execution, a COND statement none of whose clauses match should not return NIL but should throw an error with the code A3except that inside a PROG body, it should not do so. sigh.

+

Flow of control: Apart from the exceptions specified above, expressions in the program body are evaluated sequentially. If execution reaches the end of the program body, NIL is returned.

+

Got all that?

+

Good.

prog-eval

(prog-eval expr vars env depth)

Like EVAL, q.v., except handling symbols, and expressions starting GO, RETURN, SET and SETQ specially.

try-resolve-subroutine

(try-resolve-subroutine subr args)

Attempt to resolve this subr with these arg.

\ No newline at end of file diff --git a/docs/codox/beowulf.cons-cell.html b/docs/codox/beowulf.cons-cell.html index 26fa55a..6db1822 100644 --- a/docs/codox/beowulf.cons-cell.html +++ b/docs/codox/beowulf.cons-cell.html @@ -1,3 +1,3 @@ -beowulf.cons-cell documentation

beowulf.cons-cell

The fundamental cons cell on which all Lisp structures are built. Lisp 1.5 lists do not necessarily have a sequence as their CDR, and must have both CAR and CDR mutable, so cannot be implemented on top of Clojure lists.

cons-cell?

(cons-cell? o)

Is this object o a beowulf cons-cell?

F

The canonical false value - different from NIL, which is not canonically false in Lisp 1.5.

make-beowulf-list

(make-beowulf-list x)

Construct a linked list of cons cells with the same content as the sequence x.

make-cons-cell

(make-cons-cell car cdr)

Construct a new instance of cons cell with this car and cdr.

MutableSequence

protocol

Like a sequence, but mutable.

members

getCar

(getCar this)

Return the first element of this sequence.

getCdr

(getCdr this)

like more, q.v., but returns List NIL not Clojure nil when empty.

getUid

(getUid this)

Returns a unique identifier for this object

rplaca

(rplaca this value)

replace the first element of this sequence with this value

rplacd

(rplacd this value)

replace the rest (but-first; cdr) of this sequence with this value

pretty-print

(pretty-print cell)(pretty-print cell width level)

This isn’t the world’s best pretty printer but it sort of works.

T

The canonical true value.

\ No newline at end of file +beowulf.cons-cell documentation

beowulf.cons-cell

The fundamental cons cell on which all Lisp structures are built. Lisp 1.5 lists do not necessarily have a sequence as their CDR, and must have both CAR and CDR mutable, so cannot be implemented on top of Clojure lists.

cons-cell?

(cons-cell? o)

Is this object o a beowulf cons-cell?

F

The canonical false value - different from NIL, which is not canonically false in Lisp 1.5.

make-beowulf-list

(make-beowulf-list x)

Construct a linked list of cons cells with the same content as the sequence x.

make-cons-cell

(make-cons-cell car cdr)

Construct a new instance of cons cell with this car and cdr.

MutableSequence

protocol

Like a sequence, but mutable.

members

getCar

(getCar this)

Return the first element of this sequence.

getCdr

(getCdr this)

like more, q.v., but returns List NIL not Clojure nil when empty.

getUid

(getUid this)

Returns a unique identifier for this object

rplaca

(rplaca this value)

replace the first element of this sequence with this value

rplacd

(rplacd this value)

replace the rest (but-first; cdr) of this sequence with this value

pretty-print

(pretty-print cell)(pretty-print cell width level)

This isn’t the world’s best pretty printer but it sort of works.

T

The canonical true value.

\ No newline at end of file diff --git a/docs/codox/beowulf.core.html b/docs/codox/beowulf.core.html index 660d5f5..efc5d77 100644 --- a/docs/codox/beowulf.core.html +++ b/docs/codox/beowulf.core.html @@ -1,3 +1,3 @@ -beowulf.core documentation

beowulf.core

Essentially, the -main function and the bootstrap read-eval-print loop.

-main

(-main & opts)

Parse options, print the banner, read the init file if any, and enter the read/eval/print loop.

cli-options

TODO: write docs

repl

(repl prompt)

Read/eval/print loop.

stop-word

TODO: write docs

\ No newline at end of file +beowulf.core documentation

beowulf.core

Essentially, the -main function and the bootstrap read-eval-print loop.

-main

(-main & opts)

Parse options, print the banner, read the init file if any, and enter the read/eval/print loop.

cli-options

TODO: write docs

repl

(repl prompt)

Read/eval/print loop.

stop-word

TODO: write docs

\ No newline at end of file diff --git a/docs/codox/beowulf.gendoc.html b/docs/codox/beowulf.gendoc.html index 208efe6..67327f5 100644 --- a/docs/codox/beowulf.gendoc.html +++ b/docs/codox/beowulf.gendoc.html @@ -1,4 +1,4 @@ -beowulf.gendoc documentation

beowulf.gendoc

Generate table of documentation of Lisp symbols and functions.

+beowulf.gendoc documentation

beowulf.gendoc

Generate table of documentation of Lisp symbols and functions.

NOTE: this is very hacky. You almost certainly do not want to use this!

find-documentation

(find-documentation entry)

Find appropriate documentation for this entry from the oblist.

gen-doc-table

(gen-doc-table)

TODO: write docs

gen-index

(gen-index)(gen-index url destination)

TODO: write docs

host-functions

Functions which we can infer are written in Clojure. We need to collect these at run-time, not compile time, hence memoised function, not variable.

infer-implementation

(infer-implementation entry)

TODO: write docs

infer-signature

(infer-signature entry)

Infer the signature of the function value of this oblist entry, if any.

infer-type

(infer-type entry)

Try to work out what this entry from the oblist actually represents.

open-doc

(open-doc symbol)

Open the documentation page for this symbol, if known, in the default web browser.

\ No newline at end of file diff --git a/docs/codox/beowulf.host.html b/docs/codox/beowulf.host.html index c22765d..3628eb6 100644 --- a/docs/codox/beowulf.host.html +++ b/docs/codox/beowulf.host.html @@ -1,14 +1,19 @@ -beowulf.host documentation

beowulf.host

provides Lisp 1.5 functions which can’t be (or can’t efficiently be) implemented in Lisp 1.5, which therefore need to be implemented in the host language, in this case Clojure.

ADD1

(ADD1 x)

TODO: write docs

AND

(AND & args)

T if and only if none of my args evaluate to either F or NIL, else F.

-

In beowulf.host principally because I don’t yet feel confident to define varargs functions in Lisp.

ASSOC

(ASSOC x a)

If a is an association list such as the one formed by PAIRLIS in the above example, then assoc will produce the first pair whose first term is x. Thus it is a table searching function.

+beowulf.host documentation

beowulf.host

provides Lisp 1.5 functions which can’t be (or can’t efficiently be) implemented in Lisp 1.5, which therefore need to be implemented in the host language, in this case Clojure.

ADD1

(ADD1 x)

TODO: write docs

AND

(AND & args)

T if and only if none of my args evaluate to either F or NIL, else F.

+

In beowulf.host principally because I don’t yet feel confident to define varargs functions in Lisp.

ASSOC

(ASSOC x a)

If a is an association list such as the one formed by PAIRLIS in the above example, then assoc will produce the first pair whose first term is x. Thus it is a table searching function.

All args are assumed to be beowulf.cons-cell/ConsCell objects. See page 12 of the Lisp 1.5 Programmers Manual.

-

NOTE THAT this function is overridden by an implementation in Lisp, but is currently still present for bootstrapping.

ATOM

(ATOM x)

Returns T if and only if the argument x is bound to an atom; else F. It is not clear to me from the documentation whether (ATOM 7) should return T or F. I’m going to assume T.

ATOM?

macro

(ATOM? x)

The convention of returning F from predicates, rather than NIL, is going to tie me in knots. This is a variant of ATOM which returns NIL on failure.

CAAAAR

macro

(CAAAAR x)

TODO: write docs

CAAADR

macro

(CAAADR x)

TODO: write docs

CAAAR

macro

(CAAAR x)

TODO: write docs

CAADAR

macro

(CAADAR x)

TODO: write docs

CAADDR

macro

(CAADDR x)

TODO: write docs

CAADR

macro

(CAADR x)

TODO: write docs

CAAR

macro

(CAAR x)

TODO: write docs

CADAAR

macro

(CADAAR x)

TODO: write docs

CADADR

macro

(CADADR x)

TODO: write docs

CADAR

macro

(CADAR x)

TODO: write docs

CADDAR

macro

(CADDAR x)

TODO: write docs

CADDDR

macro

(CADDDR x)

TODO: write docs

CADDR

macro

(CADDR x)

TODO: write docs

CADR

macro

(CADR x)

TODO: write docs

CAR

(CAR x)

Return the item indicated by the first pointer of a pair. NIL is treated specially: the CAR of NIL is NIL.

CDAAAR

macro

(CDAAAR x)

TODO: write docs

CDAADR

macro

(CDAADR x)

TODO: write docs

CDAAR

macro

(CDAAR x)

TODO: write docs

CDADAR

macro

(CDADAR x)

TODO: write docs

CDADDR

macro

(CDADDR x)

TODO: write docs

CDADR

macro

(CDADR x)

TODO: write docs

CDAR

macro

(CDAR x)

TODO: write docs

CDDAAR

macro

(CDDAAR x)

TODO: write docs

CDDADR

macro

(CDDADR x)

TODO: write docs

CDDAR

macro

(CDDAR x)

TODO: write docs

CDDDAR

macro

(CDDDAR x)

TODO: write docs

CDDDDR

macro

(CDDDDR x)

TODO: write docs

CDDDR

macro

(CDDDR x)

TODO: write docs

CDDR

macro

(CDDR x)

TODO: write docs

CDR

(CDR x)

Return the item indicated by the second pointer of a pair. NIL is treated specially: the CDR of NIL is NIL.

CONS

(CONS car cdr)

Construct a new instance of cons cell with this car and cdr.

CONSP

(CONSP o)

Return T if object o is a cons cell, else F.

-

NOTE THAT this is an extension function, not available in strct mode. I believe that Lisp 1.5 did not have any mechanism for testing whether an argument was, or was not, a cons cell.

DEFINE

(DEFINE args)

Bootstrap-only version of DEFINE which, post boostrap, can be overwritten in LISP.

-

The single argument to DEFINE should be an assoc list which should be nconc’ed onto the front of the oblist. Broadly, (SETQ OBLIST (NCONC ARG1 OBLIST))

DIFFERENCE

(DIFFERENCE x y)

TODO: write docs

DOC

(DOC symbol)

Open the page for this symbol in the Lisp 1.5 manual, if known, in the default web browser.

-

NOTE THAT this is an extension function, not available in strct mode.

EQ

(EQ x y)

Returns T if and only if both x and y are bound to the same atom, else NIL.

EQUAL

(EQUAL x y)

This is a predicate that is true if its two arguments are identical S-expressions, and false if they are different. (The elementary predicate EQ is defined only for atomic arguments.) The definition of EQUAL is an example of a conditional expression inside a conditional expression.

-

NOTE: returns F on failure, not NIL

ERROR

(ERROR & args)

Throw an error

FIXP

(FIXP x)

TODO: write docs

GENSYM

(GENSYM)

Generate a unique symbol.

GREATERP

(GREATERP x y)

TODO: write docs

lax?

(lax? symbol)

Are we in lax mode? If so. return true; is not, throw an exception with this symbol.

LESSP

(LESSP x y)

TODO: write docs

LIST

(LIST & args)

TODO: write docs

NILP

macro

(NILP x)

Not part of LISP 1.5: T if o is NIL, else NIL.

NULL

macro

(NULL x)

Returns T if and only if the argument x is bound to NIL; else F.

NUMBERP

(NUMBERP x)

TODO: write docs

OBLIST

(OBLIST)

Return a list of the symbols currently bound on the object list.

-

NOTE THAT in the Lisp 1.5 manual, footnote at the bottom of page 69, it implies that an argument can be passed but I’m not sure of the semantics of this.

PAIRLIS

(PAIRLIS x y a)

This function gives the list of pairs of corresponding elements of the lists x and y, and APPENDs this to the list a. The resultant list of pairs, which is like a table with two columns, is called an association list.

+

NOTE THAT this function is overridden by an implementation in Lisp, but is currently still present for bootstrapping.

ATOM

(ATOM x)

Returns T if and only if the argument x is bound to an atom; else F. It is not clear to me from the documentation whether (ATOM 7) should return T or F. I’m going to assume T.

ATOM?

macro

(ATOM? x)

The convention of returning F from predicates, rather than NIL, is going to tie me in knots. This is a variant of ATOM which returns NIL on failure.

CAAAAR

macro

(CAAAAR x)

TODO: write docs

CAAADR

macro

(CAAADR x)

TODO: write docs

CAAAR

macro

(CAAAR x)

TODO: write docs

CAADAR

macro

(CAADAR x)

TODO: write docs

CAADDR

macro

(CAADDR x)

TODO: write docs

CAADR

macro

(CAADR x)

TODO: write docs

CAAR

macro

(CAAR x)

TODO: write docs

CADAAR

macro

(CADAAR x)

TODO: write docs

CADADR

macro

(CADADR x)

TODO: write docs

CADAR

macro

(CADAR x)

TODO: write docs

CADDAR

macro

(CADDAR x)

TODO: write docs

CADDDR

macro

(CADDDR x)

TODO: write docs

CADDR

macro

(CADDR x)

TODO: write docs

CADR

macro

(CADR x)

TODO: write docs

CAR

(CAR x)

Return the item indicated by the first pointer of a pair. NIL is treated specially: the CAR of NIL is NIL.

CDAAAR

macro

(CDAAAR x)

TODO: write docs

CDAADR

macro

(CDAADR x)

TODO: write docs

CDAAR

macro

(CDAAR x)

TODO: write docs

CDADAR

macro

(CDADAR x)

TODO: write docs

CDADDR

macro

(CDADDR x)

TODO: write docs

CDADR

macro

(CDADR x)

TODO: write docs

CDAR

macro

(CDAR x)

TODO: write docs

CDDAAR

macro

(CDDAAR x)

TODO: write docs

CDDADR

macro

(CDDADR x)

TODO: write docs

CDDAR

macro

(CDDAR x)

TODO: write docs

CDDDAR

macro

(CDDDAR x)

TODO: write docs

CDDDDR

macro

(CDDDDR x)

TODO: write docs

CDDDR

macro

(CDDDR x)

TODO: write docs

CDDR

macro

(CDDR x)

TODO: write docs

CDR

(CDR x)

Return the item indicated by the second pointer of a pair. NIL is treated specially: the CDR of NIL is NIL.

CONS

(CONS car cdr)

Construct a new instance of cons cell with this car and cdr.

CONSP

(CONSP o)

Return T if object o is a cons cell, else F.

+

NOTE THAT this is an extension function, not available in strct mode. I believe that Lisp 1.5 did not have any mechanism for testing whether an argument was, or was not, a cons cell.

DEFINE

(DEFINE a-list)

Bootstrap-only version of DEFINE which, post boostrap, can be overwritten in LISP.

+

The single argument to DEFINE should be an association list of symbols to lambda functions. See page 58 of the manual.

DEFLIST

(DEFLIST a-list indicator)

For each pair in this association list a-list, set the property with this indicator of the symbol which is the first element of the pair to the value which is the second element of the pair. See page 58 of the manual.

DIFFERENCE

(DIFFERENCE x y)

TODO: write docs

DOC

(DOC symbol)

Open the page for this symbol in the Lisp 1.5 manual, if known, in the default web browser.

+

NOTE THAT this is an extension function, not available in strct mode.

EQ

(EQ x y)

Returns T if and only if both x and y are bound to the same atom, else NIL.

EQUAL

(EQUAL x y)

This is a predicate that is true if its two arguments are identical S-expressions, and false if they are different. (The elementary predicate EQ is defined only for atomic arguments.) The definition of EQUAL is an example of a conditional expression inside a conditional expression.

+

NOTE: returns F on failure, not NIL

ERROR

(ERROR & args)

Throw an error

FIXP

(FIXP x)

TODO: write docs

GENSYM

(GENSYM)

Generate a unique symbol.

GET

(GET symbol indicator)

From the manual:

+

get is somewhat like prop; however its value is car of the rest of the list if the indicator is found, and NIL otherwise.’

+

It’s clear that GET is expected to be defined in terms of PROP, but we can’t implement PROP here because we lack EVAL; and we can’t have EVAL here because both it and APPLY depends on GET.

+

OK, It’s worse than that: the statement of the definition of GET (and of) PROP on page 59 says that the first argument to each must be a list; But the in the definition of ASSOC on page 70, when GET is called its first argument is always an atom. Since it’s ASSOC and EVAL which I need to make work, I’m going to assume that page 59 is wrong.

GREATERP

(GREATERP x y)

TODO: write docs

lax?

(lax? symbol)

Are we in lax mode? If so. return true; is not, throw an exception with this symbol.

LESSP

(LESSP x y)

TODO: write docs

LIST

(LIST & args)

TODO: write docs

magic-marker

The unexplained magic number which marks the start of a property list.

NILP

macro

(NILP x)

Not part of LISP 1.5: T if o is NIL, else NIL.

NULL

macro

(NULL x)

Returns T if and only if the argument x is bound to NIL; else F.

NUMBERP

(NUMBERP x)

TODO: write docs

OBLIST

(OBLIST)

Return a list of the symbols currently bound on the object list.

+

NOTE THAT in the Lisp 1.5 manual, footnote at the bottom of page 69, it implies that an argument can be passed but I’m not sure of the semantics of this.

OR

(OR & args)

T if and only if at least one of my args evaluates to something other than either F or NIL, else F.

+

In beowulf.host principally because I don’t yet feel confident to define varargs functions in Lisp.

PAIRLIS

(PAIRLIS x y a)

This function gives the list of pairs of corresponding elements of the lists x and y, and APPENDs this to the list a. The resultant list of pairs, which is like a table with two columns, is called an association list.

Eessentially, it builds the environment on the stack, implementing shallow binding.

All args are assumed to be beowulf.cons-cell/ConsCell objects. See page 12 of the Lisp 1.5 Programmers Manual.

-

NOTE THAT this function is overridden by an implementation in Lisp, but is currently still present for bootstrapping.

PLUS

(PLUS & args)

TODO: write docs

QUOTIENT

(QUOTIENT x y)

I’m not certain from the documentation whether Lisp 1.5 QUOTIENT returned the integer part of the quotient, or a realnum representing the whole quotient. I am for now implementing the latter.

REMAINDER

(REMAINDER x y)

TODO: write docs

RPLACA

(RPLACA cell value)

Replace the CAR pointer of this cell with this value. Dangerous, should really not exist, but does in Lisp 1.5 (and was important for some performance hacks in early Lisps)

RPLACD

(RPLACD cell value)

Replace the CDR pointer of this cell with this value. Dangerous, should really not exist, but does in Lisp 1.5 (and was important for some performance hacks in early Lisps)

SET

(SET symbol val)

Implementation of SET in Clojure. Add to the oblist a binding of the value of var to the value of val. NOTE WELL: this is not SETQ!

SUB1

(SUB1 x)

TODO: write docs

TIMES

(TIMES & args)

TODO: write docs

TRACE

(TRACE s)

Add this symbol s to the set of symbols currently being traced. If s is not a symbol, does nothing.

traced-symbols

Symbols currently being traced.

traced?

(traced? s)

Return true iff s is a symbol currently being traced, else nil.

uaf

(uaf l path)

Universal access function; l is expected to be an arbitrary LISP list, path a (clojure) list of the characters a and d. Intended to make declaring all those fiddly #'c[ad]+r' functions a bit easier

UNTRACE

(UNTRACE s)

TODO: write docs

\ No newline at end of file +

NOTE THAT this function is overridden by an implementation in Lisp, but is currently still present for bootstrapping.

PLUS

(PLUS & args)

TODO: write docs

PUT

(PUT symbol indicator value)

Put this value as the value of the property indicated by this indicator of this symbol. Return value on success.

+

NOTE THAT there is no PUT defined in the manual, but it would have been easy to have defined it so I don’t think this fully counts as an extension.

QUOTIENT

(QUOTIENT x y)

I’m not certain from the documentation whether Lisp 1.5 QUOTIENT returned the integer part of the quotient, or a realnum representing the whole quotient. I am for now implementing the latter.

REMAINDER

(REMAINDER x y)

TODO: write docs

RPLACA

(RPLACA cell value)

Replace the CAR pointer of this cell with this value. Dangerous, should really not exist, but does in Lisp 1.5 (and was important for some performance hacks in early Lisps)

RPLACD

(RPLACD cell value)

Replace the CDR pointer of this cell with this value. Dangerous, should really not exist, but does in Lisp 1.5 (and was important for some performance hacks in early Lisps)

SET

(SET symbol val)

Implementation of SET in Clojure. Add to the oblist a binding of the value of var to the value of val. NOTE WELL: this is not SETQ!

SUB1

(SUB1 x)

TODO: write docs

TIMES

(TIMES & args)

TODO: write docs

TRACE

(TRACE s)

Add this s to the set of symbols currently being traced. If s is not a symbol or sequence of symbols, does nothing.

traced-symbols

Symbols currently being traced.

traced?

(traced? s)

Return true iff s is a symbol currently being traced, else nil.

uaf

(uaf l path)

Universal access function; l is expected to be an arbitrary LISP list, path a (clojure) list of the characters a and d. Intended to make declaring all those fiddly #'c[ad]+r' functions a bit easier

UNTRACE

(UNTRACE s)

Remove this s from the set of symbols currently being traced. If s is not a symbol or sequence of symbols, does nothing.

\ No newline at end of file diff --git a/docs/codox/beowulf.interop.html b/docs/codox/beowulf.interop.html new file mode 100644 index 0000000..4c2b46d --- /dev/null +++ b/docs/codox/beowulf.interop.html @@ -0,0 +1,11 @@ + +beowulf.interop documentation

beowulf.interop

TODO: write docs

INTEROP

(INTEROP fn-symbol args)

Clojure (or other host environment) interoperation API. fn-symbol is expected to be either

+
    +
  1. a symbol bound in the host environment to a function; or
  2. +
  3. a sequence (list) of symbols forming a qualified path name bound to a function.
  4. +
+

Lower case characters cannot normally be represented in Lisp 1.5, so both the upper case and lower case variants of fn-symbol will be tried. If the function you’re looking for has a mixed case name, that is not currently accessible.

+

args is expected to be a Lisp 1.5 list of arguments to be passed to that function. Return value must be something acceptable to Lisp 1.5, so either a symbol, a number, or a Lisp 1.5 list.

+

If fn-symbol is not found (even when cast to lower case), or is not a function, or the value returned cannot be represented in Lisp 1.5, an exception is thrown with :cause bound to :interop and :detail set to a value representing the actual problem.

interpret-qualified-name

(interpret-qualified-name l)

For interoperation with Clojure, it will often be necessary to pass qualified names that are not representable in Lisp 1.5. This function takes a sequence in the form (PART PART PART... NAME) and returns a symbol in the form part.part.part/NAME. This symbol will then be tried in both that form and lower-cased. Names with hyphens or underscores cannot be represented with this scheme.

listify-qualified-name

(listify-qualified-name subr)

We need to be able to print something we can link to the particular Clojure function subr in a form in which Lisp 1.5 is able to read it back in and relink it.

+

This assumes subr is either 1. a string in the format #'beowulf.io/SYSIN or beowulf.io/SYSIN; or 2. something which, when coerced to a string with str, will have such a format.

to-beowulf

(to-beowulf o)

Return a beowulf-native representation of the Clojure object o. Numbers and symbols are unaffected. Collections have to be converted; strings must be converted to symbols.

to-clojure

(to-clojure l)

If l is a beowulf.cons_cell.ConsCell, return a Clojure list having the same members in the same order.

\ No newline at end of file diff --git a/docs/codox/beowulf.io.html b/docs/codox/beowulf.io.html index 2d19239..7c4b31b 100644 --- a/docs/codox/beowulf.io.html +++ b/docs/codox/beowulf.io.html @@ -1,13 +1,13 @@ -beowulf.io documentation

beowulf.io

Non-standard extensions to Lisp 1.5 to read and write to the filesystem.

+beowulf.io documentation

beowulf.io

Non-standard extensions to Lisp 1.5 to read and write to the filesystem.

Lisp 1.5 had only READ, which read one S-Expression at a time, and various forms of PRIN* functions, which printed to the line printer. There was also PUNCH, which wrote to a card punch. It does not seem that there was any concept of an interactive terminal.

See Appendix E, OVERLORD - THE MONITOR, and Appendix F, LISP INPUT AND OUTPUT.

For our purposes, to save the current state of the Lisp system it should be sufficient to print the current contents of the oblist to file; and to restore a previous state from file, to overwrite the contents of the oblist with data from that file.

-

Hence functions SYSOUT and SYSIN, which do just that.

default-sysout

TODO: write docs

SYSIN

(SYSIN)(SYSIN filename)

Read the contents of the file at this filename into the object list.

+

Hence functions SYSOUT and SYSIN, which do just that.

default-sysout

TODO: write docs

safely-wrap-subr

(safely-wrap-subr entry)

TODO: write docs

safely-wrap-subrs

(safely-wrap-subrs objects)

TODO: write docs

SYSIN

(SYSIN)(SYSIN filename)

Read the contents of the file at this filename into the object list.

If the file is not a valid Beowulf sysout file, this will probably corrupt the system, you have been warned. File paths will be considered relative to the filepath set when starting Lisp.

It is intended that sysout files can be read both from resources within the jar file, and from the file system. If a named file exists in both the file system and the resources, the file system will be preferred.

NOTE THAT if the provided filename does not end with .lsp (which, if you’re writing it from the Lisp REPL, it won’t), the extension .lsp will be appended.

-

NOTE THAT this is an extension function, not available in strct mode.

SYSOUT

(SYSOUT)(SYSOUT filepath)

Dump the current content of the object list to file. If no filepath is specified, a file name will be constructed of the symbol Sysout and the current date. File paths will be considered relative to the filepath set when starting Lisp.

-

NOTE THAT this is an extension function, not available in strct mode.

\ No newline at end of file +

NOTE THAT this is an extension function, not available in strct mode.

SYSOUT

(SYSOUT)(SYSOUT filepath)

Dump the current content of the object list to file. If no filepath is specified, a file name will be constructed of the symbol Sysout and the current date. File paths will be considered relative to the filepath set when starting Lisp.

+

NOTE THAT this is an extension function, not available in strct mode.

\ No newline at end of file diff --git a/docs/codox/beowulf.manual.html b/docs/codox/beowulf.manual.html index bf60737..a448a5e 100644 --- a/docs/codox/beowulf.manual.html +++ b/docs/codox/beowulf.manual.html @@ -1,3 +1,3 @@ -beowulf.manual documentation

beowulf.manual

Experimental code for accessing the manual online.

*manual-url*

dynamic

TODO: write docs

format-page-references

(format-page-references fn-symbol)

Format page references from the manual index for the function whose name is fn-symbol.

index

This is data extracted from the index pages of Lisp 1.5 Programmer's Manual. It’s here in the hope that we can automatically link to an online PDF link to the manual when the user invokes a function probably called DOC or HELP.

page-url

(page-url page-no)

Format the URL for the page in the manual with this page-no.

\ No newline at end of file +beowulf.manual documentation

beowulf.manual

Experimental code for accessing the manual online.

*manual-url*

dynamic

TODO: write docs

format-page-references

(format-page-references fn-symbol)

Format page references from the manual index for the function whose name is fn-symbol.

index

This is data extracted from the index pages of Lisp 1.5 Programmer's Manual. It’s here in the hope that we can automatically link to an online PDF link to the manual when the user invokes a function probably called DOC or HELP.

page-url

(page-url page-no)

Format the URL for the page in the manual with this page-no.

\ No newline at end of file diff --git a/docs/codox/beowulf.oblist.html b/docs/codox/beowulf.oblist.html index 241acff..52a1a93 100644 --- a/docs/codox/beowulf.oblist.html +++ b/docs/codox/beowulf.oblist.html @@ -1,5 +1,5 @@ -beowulf.oblist documentation

beowulf.oblist

A namespace mainly devoted to the object list and other top level global variables.

+beowulf.oblist documentation

beowulf.oblist

A namespace mainly devoted to the object list and other top level global variables.

Yes, this makes little sense, but if you put them anywhere else you end up in cyclic dependency hell.

*options*

dynamic

Command line options from invocation.

NIL

The canonical empty list symbol.

TODO: this doesn’t really work, because (from Clojure) (empty? NIL) throws an exception. It might be better to subclass beowulf.cons_cell.ConsCell to create a new singleton class Nil which overrides the empty method of IPersistentCollection?

oblist

The default environment.

\ No newline at end of file diff --git a/docs/codox/beowulf.read.html b/docs/codox/beowulf.read.html index 115d614..31bb373 100644 --- a/docs/codox/beowulf.read.html +++ b/docs/codox/beowulf.read.html @@ -1,6 +1,6 @@ -beowulf.read documentation

beowulf.read

This provides the reader required for boostrapping. It’s not a bad reader - it provides feedback on errors found in the input - but it isn’t the real Lisp reader.

+beowulf.read documentation

beowulf.read

This provides the reader required for boostrapping. It’s not a bad reader - it provides feedback on errors found in the input - but it isn’t the real Lisp reader.

Intended deviations from the behaviour of the real Lisp reader are as follows:

  1. It reads the meta-expression language MEXPR in addition to the symbolic expression language SEXPR, which I do not believe the Lisp 1.5 reader ever did;
  2. diff --git a/docs/codox/beowulf.reader.char-reader.html b/docs/codox/beowulf.reader.char-reader.html index 8699ea3..414801c 100644 --- a/docs/codox/beowulf.reader.char-reader.html +++ b/docs/codox/beowulf.reader.char-reader.html @@ -1,6 +1,6 @@ -beowulf.reader.char-reader documentation

    beowulf.reader.char-reader

    Provide sensible line editing, auto completion, and history recall.

    +beowulf.reader.char-reader documentation

    beowulf.reader.char-reader

    Provide sensible line editing, auto completion, and history recall.

    None of what’s needed here is really working yet, and a pull request with a working implementation would be greatly welcomed.

    What’s needed (rough specification)

      diff --git a/docs/codox/beowulf.reader.generate.html b/docs/codox/beowulf.reader.generate.html index 574e61e..16f25fa 100644 --- a/docs/codox/beowulf.reader.generate.html +++ b/docs/codox/beowulf.reader.generate.html @@ -1,6 +1,6 @@ -beowulf.reader.generate documentation

      beowulf.reader.generate

      Generating S-Expressions from parse trees.

      +beowulf.reader.generate documentation

      beowulf.reader.generate

      Generating S-Expressions from parse trees.

      From Lisp 1.5 Programmers Manual, page 10

      Note that I’ve retyped much of this, since copy/pasting out of PDF is less than reliable. Any typos are mine.

      Quote starts:

      diff --git a/docs/codox/beowulf.reader.macros.html b/docs/codox/beowulf.reader.macros.html index 510db75..e5e5e4f 100644 --- a/docs/codox/beowulf.reader.macros.html +++ b/docs/codox/beowulf.reader.macros.html @@ -1,5 +1,5 @@ -beowulf.reader.macros documentation

      beowulf.reader.macros

      Can I implement reader macros? let’s see!

      +beowulf.reader.macros documentation

      beowulf.reader.macros

      Can I implement reader macros? let’s see!

      We don’t need (at least, in the Clojure reader) to rewrite forms like 'FOO, because that’s handled by the parser. But we do need to rewrite things which don’t evaluate their arguments, like SETQ, because (unless LABEL does it, which I’m not yet sure of) we’re not yet able to implement things which don’t evaluate arguments.

      TODO: at this stage, the following should probably also be read macros: DEFINE

      *readmacros*

      dynamic

      TODO: write docs

      expand-macros

      (expand-macros form)

      TODO: write docs

      \ No newline at end of file diff --git a/docs/codox/beowulf.reader.parser.html b/docs/codox/beowulf.reader.parser.html index 92309e8..c8a00f9 100644 --- a/docs/codox/beowulf.reader.parser.html +++ b/docs/codox/beowulf.reader.parser.html @@ -1,3 +1,3 @@ -beowulf.reader.parser documentation

      beowulf.reader.parser

      The actual parser, supporting both S-expression and M-expression syntax.

      parse

      Parse a string presented as argument into a parse tree which can then be operated upon further.

      \ No newline at end of file +beowulf.reader.parser documentation

      beowulf.reader.parser

      The actual parser, supporting both S-expression and M-expression syntax.

      parse

      Parse a string presented as argument into a parse tree which can then be operated upon further.

      \ No newline at end of file diff --git a/docs/codox/beowulf.reader.simplify.html b/docs/codox/beowulf.reader.simplify.html index f2adfb6..ad3ea31 100644 --- a/docs/codox/beowulf.reader.simplify.html +++ b/docs/codox/beowulf.reader.simplify.html @@ -1,4 +1,4 @@ -beowulf.reader.simplify documentation

      beowulf.reader.simplify

      Simplify parse trees. Be aware that this is very tightly coupled with the parser.

      remove-nesting

      (remove-nesting tree context)

      TODO: write docs

      remove-optional-space

      (remove-optional-space tree)

      TODO: write docs

      simplify

      (simplify p)

      Simplify this parse tree p. If p is an instaparse failure object, throw an ex-info, with p as the value of its :failure key. Calls remove-optional-space before processing.

      simplify-tree

      (simplify-tree p)(simplify-tree p context)

      Simplify this parse tree p. If p is an instaparse failure object, throw an ex-info, with p as the value of its :failure key.

      +beowulf.reader.simplify documentation

      beowulf.reader.simplify

      Simplify parse trees. Be aware that this is very tightly coupled with the parser.

      remove-nesting

      (remove-nesting tree context)

      TODO: write docs

      remove-optional-space

      (remove-optional-space tree)

      TODO: write docs

      simplify

      (simplify p)

      Simplify this parse tree p. If p is an instaparse failure object, throw an ex-info, with p as the value of its :failure key. Calls remove-optional-space before processing.

      simplify-tree

      (simplify-tree p)(simplify-tree p context)

      Simplify this parse tree p. If p is an instaparse failure object, throw an ex-info, with p as the value of its :failure key.

      NOTE THAT it is assumed that remove-optional-space has been run on the parse tree BEFORE it is passed to simplify-tree.

      \ No newline at end of file diff --git a/docs/codox/further_reading.html b/docs/codox/further_reading.html new file mode 100644 index 0000000..e536440 --- /dev/null +++ b/docs/codox/further_reading.html @@ -0,0 +1,17 @@ + +Further Reading

      Further Reading

      +
        +
      1. CODING for the MIT-IBM 704 COMPUTER, October 1957 This paper is not about Lisp. But it is about the particular individual computer on which Lisp was first implemented, and it is written in part by members of the Lisp team. I have found it useful in understanding the software environment in which, and the constraints under which, Lisp was written.
      2. +
      3. MIT AI Memo 1, John McCarthy, September 1958 This is, as far as I can find, the earliest specification document of the Lisp project.
      4. +
      5. Lisp 1 Programmer’s Manual, Phyllis Fox, March 1960
      6. +
      7. Lisp 1.5 Programmer’s Manual, Michael I. Levin, August 1962 This book is essential reading: it documents in some detail the first fully realised Lisp language system.
      8. +
      9. Early LISP History (1956 - 1959), Herbert Stoyan, August 1984
      10. +
      11. +

        The Roots of Lisp, Paul Graham, 2001

      12. +
      13. +

        The Revenge of the Nerds, Paul Graham, 2002 This is mainly about why to use Lisp as a language for modern commercial software, but has useful insights into where it comes from.

        +
        +

        So the short explanation of why this 1950s language is not obsolete is that it was not technology but math, and math doesn’t get stale.

        +
      14. +
      \ No newline at end of file diff --git a/docs/codox/index.html b/docs/codox/index.html index 54a0ed5..9b2f58b 100644 --- a/docs/codox/index.html +++ b/docs/codox/index.html @@ -1,3 +1,3 @@ -Beowulf 0.3.0-SNAPSHOT

      Beowulf 0.3.0-SNAPSHOT

      Released under the GPL-2.0-or-later

      An implementation of LISP 1.5 in Clojure.

      Installation

      To install, add the following dependency to your project or build file:

      [beowulf "0.3.0-SNAPSHOT"]

      Topics

      Namespaces

      beowulf.bootstrap

      Lisp as defined in Chapter 1 (pages 1-14) of the Lisp 1.5 Programmer's Manual; that is to say, a very simple Lisp language, which should, I believe, be sufficient in conjunction with the functions provided by beowulf.host, be sufficient to bootstrap the full Lisp 1.5 interpreter..

      beowulf.cons-cell

      The fundamental cons cell on which all Lisp structures are built. Lisp 1.5 lists do not necessarily have a sequence as their CDR, and must have both CAR and CDR mutable, so cannot be implemented on top of Clojure lists.

      beowulf.core

      Essentially, the -main function and the bootstrap read-eval-print loop.

      Public variables and functions:

      beowulf.gendoc

      Generate table of documentation of Lisp symbols and functions.

      beowulf.host

      provides Lisp 1.5 functions which can’t be (or can’t efficiently be) implemented in Lisp 1.5, which therefore need to be implemented in the host language, in this case Clojure.

      beowulf.io

      Non-standard extensions to Lisp 1.5 to read and write to the filesystem.

      Public variables and functions:

      beowulf.manual

      Experimental code for accessing the manual online.

      Public variables and functions:

      beowulf.oblist

      A namespace mainly devoted to the object list and other top level global variables.

      Public variables and functions:

      beowulf.read

      This provides the reader required for boostrapping. It’s not a bad reader - it provides feedback on errors found in the input - but it isn’t the real Lisp reader.

      Public variables and functions:

      beowulf.reader.char-reader

      Provide sensible line editing, auto completion, and history recall.

      Public variables and functions:

      beowulf.reader.macros

      Can I implement reader macros? let’s see!

      Public variables and functions:

      beowulf.reader.parser

      The actual parser, supporting both S-expression and M-expression syntax.

      Public variables and functions:

      beowulf.reader.simplify

      Simplify parse trees. Be aware that this is very tightly coupled with the parser.

      \ No newline at end of file +Beowulf 0.3.0-SNAPSHOT

      Beowulf 0.3.0-SNAPSHOT

      Released under the GPL-2.0-or-later

      An implementation of LISP 1.5 in Clojure.

      Installation

      To install, add the following dependency to your project or build file:

      [beowulf "0.3.0-SNAPSHOT"]

      Topics

      Namespaces

      beowulf.bootstrap

      Lisp as defined in Chapter 1 (pages 1-14) of the Lisp 1.5 Programmer's Manual; that is to say, a very simple Lisp language, which should, I believe, be sufficient in conjunction with the functions provided by beowulf.host, be sufficient to bootstrap the full Lisp 1.5 interpreter..

      Public variables and functions:

      beowulf.cons-cell

      The fundamental cons cell on which all Lisp structures are built. Lisp 1.5 lists do not necessarily have a sequence as their CDR, and must have both CAR and CDR mutable, so cannot be implemented on top of Clojure lists.

      beowulf.core

      Essentially, the -main function and the bootstrap read-eval-print loop.

      Public variables and functions:

      beowulf.gendoc

      Generate table of documentation of Lisp symbols and functions.

      beowulf.host

      provides Lisp 1.5 functions which can’t be (or can’t efficiently be) implemented in Lisp 1.5, which therefore need to be implemented in the host language, in this case Clojure.

      beowulf.io

      Non-standard extensions to Lisp 1.5 to read and write to the filesystem.

      beowulf.manual

      Experimental code for accessing the manual online.

      Public variables and functions:

      beowulf.oblist

      A namespace mainly devoted to the object list and other top level global variables.

      Public variables and functions:

      beowulf.read

      This provides the reader required for boostrapping. It’s not a bad reader - it provides feedback on errors found in the input - but it isn’t the real Lisp reader.

      Public variables and functions:

      beowulf.reader.char-reader

      Provide sensible line editing, auto completion, and history recall.

      Public variables and functions:

      beowulf.reader.macros

      Can I implement reader macros? let’s see!

      Public variables and functions:

      beowulf.reader.parser

      The actual parser, supporting both S-expression and M-expression syntax.

      Public variables and functions:

      beowulf.reader.simplify

      Simplify parse trees. Be aware that this is very tightly coupled with the parser.

      \ No newline at end of file diff --git a/docs/codox/intro.html b/docs/codox/intro.html index 9854ad9..55db19f 100644 --- a/docs/codox/intro.html +++ b/docs/codox/intro.html @@ -1,11 +1,11 @@ -beowulf

      beowulf

      +beowulf

      beowulf

      LISP 1.5 is to all Lisp dialects as Beowulf is to English literature.

      What this is

      A work-in-progress towards an implementation of Lisp 1.5 in Clojure. The objective is to build a complete and accurate implementation of Lisp 1.5 as described in the manual, with, in so far as is possible, exactly the same bahaviour - except as documented below.

      Status

      -

      Boots to REPL, but few functions yet available.

      +

      Working Lisp interpreter, but some key features not yet implemented.

      • Project website.
      • Source code documentation.
      • @@ -15,7 +15,7 @@
        lein uberjar
         

        Invoke with

        -
        java -jar target/uberjar/beowulf-0.2.1-SNAPSHOT-standalone.jar --help
        +
        java -jar target/uberjar/beowulf-0.3.0-SNAPSHOT-standalone.jar --help
         

        (Obviously, check your version number)

        Command line arguments as follows:

        diff --git a/docs/codox/mexpr.html b/docs/codox/mexpr.html index c8d104f..cea7607 100644 --- a/docs/codox/mexpr.html +++ b/docs/codox/mexpr.html @@ -1,6 +1,6 @@ -Interpreting M-Expressions

        Interpreting M-Expressions

        +Interpreting M-Expressions

        Interpreting M-Expressions

        M-Expressions (‘mexprs’) are the grammar which John McCarthy origininally used to write Lisp, and the grammar in which many of the function definitions in the Lisp 1.5 Programmer’s Manual are stated. However, I have not seen anywhere a claim that Lisp 1.5 could read M-Expressions, and it is not clear to me whether it was even planned that it should do so, although the discussion on page 10 suggests that it was.

        Rather, it seems to me possible that M-Expressions were only ever a grammar intended to be written on paper, like Backus Naur Form, to describe and to reason about algorithms. I think at the point at which the M-Expression grammar was written, the idea of the universal Lisp function

        I set out to make Beowulf read M-Expressions essentially out of curiousity, to see whether it could be done. I had this idea that if it could be done, I could implement most of Lisp 1.5 simply by copying in the M-Expression definitions out of the manual.

        diff --git a/docs/codox/values.html b/docs/codox/values.html index 2dd0ca3..e4d5640 100644 --- a/docs/codox/values.html +++ b/docs/codox/values.html @@ -1,9 +1,9 @@ -Understanding values and properties

        Understanding values and properties

        -

        Lisp is the list processing language; that is what it name means. It processes data structures built of lists - which may be lists of lists, or lists of numbers, or lists of any other sort of data item provided for by the designers of the system.

        +The properties of the system, and their values: here be dragons

        The properties of the system, and their values: here be dragons

        +

        Lisp is the list processing language; that is what its name means. It processes data structures built of lists - which may be lists of lists, or lists of numbers, or lists of any other sort of data item provided for by the designers of the system.

        But how is a list, in a computer, actually implemented?

        -

        They’re implemented as pairs, or, as the manual sometimes rather delightfully called them, ‘doublets’. Pairs of what? Pairs of pointers. Of the two pointers of a pair, the first points to the current entry of the list, and the second, by default, points to the remainder of the list, or, if the end of the list has been reached, to a special datum known as NIL which among other things indicates that the end of the list has been reached. The pair itself is normally referred to as a ‘cons cell’ for reasons which are nerdy and not important just now (all right, because they are constructed using a function called cons, which is in itself simply and abbreviation of ‘construct’).

        +

        They’re implemented as pairs, or, as the manual sometimes rather delightfully called them, ‘doublets’. Pairs of what? Pairs of pointers. Of the two pointers of a pair, the first points to the current entry of the list, and the second, by default, points to the remainder of the list, or, if the end of the list has been reached, to a special datum known as NIL which among other things indicates that the end of the list has been reached. The pair itself is normally referred to as a ‘cons cell’ for reasons which are nerdy and not important just now (all right, because they are constructed using a function called cons, which is in itself believed to be simply an abbreviation of ‘construct’).

        Two functions are used to access the two pointers of the cell. In modern Lisps these functions are called first and rest, because a lot of people who aren’t greybeards find these names easier. But they aren’t the original names. The original names were CAR and CDR.

        Why?

        History

        @@ -34,6 +34,18 @@ RLN | | oo 7 a | O14 (read lines O and 1)

        Of course, this isn’t proof. If CAR and CDR used here are standard IBM 704 assembler mnemonics – as I believe they are – then what is CONS? It’s used in a syntactically identical way. If it also is an assembler mnemonic, then it’s hard to believe that, as legend relates, it is short for ‘construct’; on the other hand, if it’s a label representing an entry point into a subroutine, then why should CAR and CDR not also be labels?

        +
        +

        Edited 3rd April to add: I’ve found a document, not related to Lisp (although John McCarthy is credited as one of the authors), which does confirm – or strictly, amend – the story. This is the CODING for the MIT-IBM 704 COMPUTER, dating from October 1957. The registers of the 704 were divided into four parts, named respectively the prefix part, the address part, the tag part, and the decrement part, of 3, 15, 3, and 15 bits respectively. The decrement part was not used in addressing; that part of the folklore I was taught isn’t right. But the names are correct. Consider this excerpt :

        +
        +

        The address, tag and decrement parts of symbolic instructions are given in that order. In some cases the decrement, tag or address parts are not necessary; therefore the following combinations where OP represents the instruction abbreviation are permissible.

        +
        +

        This doesn’t prove there were individual machine instructions with the mnemonics CAR and CDR; in fact, I’m going to say with some confidence that there were not, by reference to the table of instructions appended to the same document. The instructions do have three letter mnemonics, and they do use ‘A’ and ‘D’ as abbreviations for ‘address’ and ‘decrement’ respectively, but CAR and CDR are not included.

        +

        So it seems probable that CAR and CDR were labels for subroutines, as I hypothesised above. But they were quite likely pre-existing subroutines, in use before the instantiation of the Lisp project, because they would be generally useful; and the suggestion that they are contractions of ‘contents of the address part’ and ‘contents of the decrement part’, respectively, seem confirmed.

        +

        And, going further down the rabbit hole, there’s this. In 1957, before work on the Lisp project started, McCarthy was writing functions to add list processing to the then-new FORTRAN language, on the very same IBM 704 machine.

        +
        +

        in this time any function that delivered integer values had to have a first letter X. Any function (as opposited to subroutines) had to have a last letter F in its name. Therefore the functions selecting parts of the IBM704 memory register (word) were introduced to be XCSRF, XCPRF, XCDRF, XCTRF and XCARF

        +
        +

        I think that the answer has to be that if CAR and CDR had been named by the early Lisp team – John McCarthy and his immediate colleagues – they would not have been named as they were. If not FRST and REST, as in more modern Lisps, then something like P1 and P2. CAR and CDR are distinctive and memorable (and therefore in my opinion worth preserving) because they very specifically name the parts of a cons cell and of nothing else.

        Let’s be clear, here: when CAR and CDR are used in Lisp, they are returning pointers, certainly – but not in the sense that one points to a page and the other to a word. Each is an offset into a cell array, which is almost certainly an array of single 36 bit words held on a single page. So both are in effect being used as decrements. Their use in Lisp is an overload onto their original semantic meaning; they are no longer being used for the purpose for which they are named.

        As far as I can tell, these names first appear in print in 1960, both in the Lisp 1 Programmer’s Manual referenced above, and in McCarthy’s paper Recursive Functions of Symbolic Expressions and Their Computation by Machine, Part I. The paper was published in April so was presumably written in 1959

        @@ -91,7 +103,14 @@ O14 (read lines O and 1)

        There’s a view in modern software theory – with which I strongly hold – that data should be immutable. Data that changes under you is the source of all sorts of bugs. And in modern multi threaded systems, the act of reading a datum whilst some other process is writing it, or worse, two processes attempting simultaneously to write the same datum, is a source of data corruption and even crashes. So I’m very wary of mutable data; and, in modern systems where we normally have a great deal of space and a lot of processor power, making fresh copies of data structures containing the change we wanted to make is a reasonable price to pay for avoiding a whole class of bugs.

        But early software was not like that. It was always constrained by the limits of the hardware on which it ran, to a degree that we are not. And the experience that we now have of the problems caused by mutable data, they did not have. So it’s core to the design of Lisp 1.5 that its lists are mutable; and, indeed, one of the biggest challenges in writing Beowulf has been implementing mutable lists in Clojure, a language carefully designed to prevent them.

        But, just because Lisp 1.5 lists can be mutable, should they be? And when should they be?

        -

        The problem here is that spine of the system I talked about earlier.

        +

        The problem here is that spine of the system I talked about earlier. If we build the execution stack on top of the oblist – as at present I do – then if we make a new version of the oblist with changes in it, the new changes will not be in the copy of the oblist that the stack is built on top of; and consequently, they’ll be invisible to the running program.

        +

        What I do at present, and what I think may be good enough, is that each time execution returns to the read-eval-print loop, the REPL, the user’s command line, I rebuild a new execution stack on the top of the oblist as it exists now. So, if the last operation modified the oblist, the next operation will see the new, modified version. But if someone tried to run some persistent program which was writing stuff to property values and hoping to read them back in the same computation, that wouldn’t work, and it would be a very hard bug to trace down.

        +

        So my options are:

        +
          +
        1. To implement PUT and GET in Clojure, so that they can operate on the current copy of the object list, not the one at the base of the stack. I’m slightly unwilling to do that, because my objective is to make Beowulf ultimately as self-hosting as possible.
        2. +
        3. To implement PUT and GET in Lisp, and have them destructively modify the working copy of the object list.
        4. +
        +

        Neither of these particularly appeal.

        How property lists should work

        I’m still not fully understanding how property lists in Lisp 1.5 are supposed to work.

        List format

        @@ -180,5 +199,64 @@ O14 (read lines O and 1)

        (They wrote amazingly clean code, those old masters. I could tell you a story about Chris Burton, the train, and the printer driver, that software people of today simply would not believe. But it’s true. And I think that what taught them that discipline was the high cost of even small errors.)

        Lisp 1.5 doesn’t have PUT, PUTPROP or DEFUN because setting properties individually, defining functions individually one at a time, was not something they ever thought about doing. And in learning that, I’ve learned more than I ever expected to about the real nature of Lisp 1.5, and the (great) people who wrote it.


        +

        Deeper delving

        +

        After writing, and publishing, this essay, I went on procrastinating, which is what I do when I’m sure I’m missing something; and to procrastinate, I went on reading the earliest design documents of Lisp I could find. And so I came across the MIT AI team’s first ever memo, written by John McCarthy in September 1958. And in that, I find this:

        +
        +

        3.2.1. First we have those that extract parts of a 704 word and form a word from parts. We shall distinguish the following parts of a word and indicate each of them by a characteristic letter.

        + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        Letter Description
        w the whole word
        p the prefix (bits s, 1, 2)
        i the indicator (bits 1 and 2)
        s the sign bit
        d the decrement (bits 3-17)
        t the tag (bits 18-20)
        a the address (bits 21-35)
        +
        +

        In the discussion of functions which access properties on page 58 of the Lisp 1.5 programmer’s manual, the word ‘indicator’ is used in preference to ‘symbol’ for the name of a property: for example

        +
        +

        The function deflist is a more general defining function. Its first argument is a list of pairs as for define. Its second argument is the indicator that is to be used. After deflist has been executed with (ui vi) among its first argument, the property list of ui will begin:

        +

        If deflist or define is used twice on the same object with the same indicator, the old value will be replaced by the new one.

        +
        +

        (my emphasis).

        +

        That use of ‘indicator’ has been nagging at me for a week. It looks like a term of art. If it’s just an ordinary atomic symbol, why isn’t it called a symbol?

        +

        Is it an indicator in the special sense of the indicator part of the machine word? If it were, then the property list could just be a flat list of values. And what’s been worrying and surprising me is that property lists are shown in the manual as flat lists. Eureka? I don’t think so.

        +

        The reason I don’t think so is that there are only two bits in the indicator part of the word, so only four distinct values; whereas we know that Lisp 1.5 has (at least) five distinct indicator values, APVAL, EXPR, FEXPR, SUBR and FSUBR.

        +

        Furthermore, on page 39, we have:

        +
        +

        A property list is characterized by having the special constant 777778 (i. e., minus 1) as the first element of the list. The rest of the list contains various properties of the atomic symbol. Each property is preceded by an atomic symbol which is called its indicator.

        +
        +

        (again, my emphasis)

        +

        But I’m going to hypothesise that the properties were originally intended to be discriminated by the indicator bits in the cons cell, that they were originally coded that way, and that there was some code which depended on property lists being flat lists; and that, when it was discovered that four indicators were not enough and that something else was going to have to be used, the new format of the property list using atomic symbols as indicators was bodged in.

        +

        So what this is about is I’ve spent most of a whole day procrastinating, because I’m not exactly sure how I’m going to make the change I’ve got to make. Versions of Beowulf up to and including 0.2.1 used the naive understanding of the architecture; version 0.3.0 should use the corrected version. But before it can, I need to be reasonably confident that I understand what the correct solution is.

        -

        I shall implement PUT, even though it isn’t in the spec, because it’s a useful building block on which to build DEFINE and DEFLIS, both of which are. And also, because PUT would have been very easy for the Lisp 1.5 implementers to implement, if it had been relevant to their working environment.

      \ No newline at end of file +

      I shall implement PUT, even though it isn’t in the spec, because it’s a useful building block on which to build DEFINE and DEFLIS, both of which are. And also, because PUT would have been very easy for the Lisp 1.5 implementers to implement, if it had been relevant to their working environment. And I shall implement property list as flat lists of interleaved ‘indicator’ symbols and values, even with that nonsense 777778 as a prefix, because now I know (or think I know) that it was a bodge, it seems right in the spirit of historical reconstruction to reconstruct the bodge.

      \ No newline at end of file diff --git a/project.clj b/project.clj index 0989300..c989d36 100644 --- a/project.clj +++ b/project.clj @@ -34,6 +34,5 @@ ["uberjar"] ["change" "version" "leiningen.release/bump-version"] ["vcs" "commit"]] - :target-path "target/%s" :url "https://github.com/simon-brooke/the-great-game") diff --git a/src/beowulf/bootstrap.clj b/src/beowulf/bootstrap.clj index 09b4ee2..b1ea963 100644 --- a/src/beowulf/bootstrap.clj +++ b/src/beowulf/bootstrap.clj @@ -9,7 +9,8 @@ ALLUPPERCASE are Lisp 1.5 functions (although written in Clojure) and that therefore all arguments must be numbers, symbols or `beowulf.cons_cell.ConsCell` objects." - (:require [beowulf.cons-cell :refer [make-beowulf-list make-cons-cell T]] + (:require [beowulf.cons-cell :refer [F make-beowulf-list make-cons-cell + pretty-print T]] [beowulf.host :refer [ASSOC ATOM CAAR CADAR CADDR CADR CAR CDR GET LIST NUMBERP PAIRLIS traced?]] [beowulf.oblist :refer [*options* NIL oblist]]) @@ -36,7 +37,147 @@ ;;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(declare APPLY EVAL) +(declare APPLY EVAL prog-eval) + +(def find-target + (memoize + (fn [target body] + (loop [body' body] + (cond + (= body' NIL) (throw (ex-info "Invalid GO target" + {:phase :lisp + :function 'PROG + :type :lisp + :code :A6})) + (= (.getCar body') target) body' + :else (recur (.getCdr body'))))))) + +(defn- prog-cond + "Like `EVCON`, q.v. except using `prog-eval` instead of `EVAL` and not + throwing an error if no clause matches." + [clauses vars env depth] + (loop [clauses' clauses] + (if-not (= clauses' NIL) + (let [test (prog-eval (CAAR clauses') vars env depth)] + (if (not (#{NIL F} test)) + (prog-eval (CADAR clauses') vars env depth) + (recur (.getCdr clauses')))) + NIL))) + +(defn prog-eval + "Like `EVAL`, q.v., except handling symbols, and expressions starting + `GO`, `RETURN`, `SET` and `SETQ` specially." + [expr vars env depth] + (cond + (number? expr) expr + (symbol? expr) (@vars expr) + (instance? ConsCell expr) (case (.getCar expr) + COND (prog-cond (.getCdr expr) + vars env depth) + GO (make-cons-cell + '*PROGGO* (.getCdr expr)) + RETURN (make-cons-cell + '*PROGRETURN* + (EVAL (.getCdr expr) env depth)) + SET (swap! vars + assoc + (prog-eval (CADR expr) + vars env depth) + (prog-eval (CADDR expr) + vars env depth)) + SETQ (swap! vars + assoc + (CADR expr) + (prog-eval (CADDR expr) + vars env depth)) + ;; else + (beowulf.bootstrap/EVAL expr env depth)))) + +(defn PROG + "The accursed `PROG` feature. See page 71 of the manual. + + Lisp 1.5 introduced `PROG`, and most Lisps have been stuck with it ever + since. It introduces imperative programming into what should be a pure + functional language, and consequently it's going to be a pig to implement. + + Broadly, `PROG` is a variadic pseudo function called as a `FEXPR` (or + possibly an `FSUBR`, although I'm not presently sure that would even work.) + + The arguments, which are unevaluated, are a list of forms, the first of + which is expected to be a list of symbols which will be treated as names + of variables within the program, and the rest of which (the 'program body') + are either lists or symbols. Lists are treated as Lisp expressions which + may be evaulated in turn. Symbols are treated as targets for the `GO` + statement. + + **GO:** + A `GO` statement takes the form of `(GO target)`, where + `target` should be one of the symbols which occur at top level among that + particular invocation of `PROG`s arguments. A `GO` statement may occur at + top level in a PROG, or in a clause of a `COND` statement in a `PROG`, but + not in a function called from the `PROG` statement. When a `GO` statement + is evaluated, execution should transfer immediately to the expression which + is the argument list immediately following the symbol which is its target. + + If the target is not found, an error with the code `A6` should be thrown. + + **RETURN:** + A `RETURN` statement takes the form `(RETURN value)`, where + `value` is any value. Following the evaluation of a `RETURN` statement, + the `PROG` should immediately exit without executing any further + expressions, returning the value. + + **SET and SETQ:** + In addition to the above, if a `SET` or `SETQ` expression is encountered + in any expression within the `PROG` body, it should affect not the global + object list but instead only the local variables of the program. + + **COND:** + In **strict** mode, when in normal execution, a `COND` statement none of + whose clauses match should not return `NIL` but should throw an error with + the code `A3`... *except* that inside a `PROG` body, it should not do so. + *sigh*. + + **Flow of control:** + Apart from the exceptions specified above, expressions in the program body + are evaluated sequentially. If execution reaches the end of the program + body, `NIL` is returned. + + Got all that? + + Good." + [program env depth] + (let [trace (traced? 'PROG) + vars (atom (reduce merge (map #(assoc {} % NIL) (.getCar program)))) + body (.getCdr program) + targets (set (filter symbol? body))] + (when trace (do + (println "Program:") + (pretty-print program))) ;; for debugging + (loop [cursor body] + (let [step (.getCar cursor)] + (when trace (do (println "Executing step: " step) + (println " with vars: " vars))) + (cond (= cursor NIL) NIL + (symbol? step) (recur step) + :else (let [v (prog-eval (.getCar cursor) vars env depth)] + (if (instance? ConsCell v) + (case (.getCar v) + *PROGGO* (let [target (.getCdr v)] + (if (targets target) + (recur (find-target target body)) + (throw (ex-info "Invalid GO target" + {:phase :lisp + :function 'PROG + :args program + :type :lisp + :code :A6})))) + *PROGRETURN* (.getCdr v) + ;; else + (recur (.getCdr cursor))) + (recur (.getCdr cursor))))))))) + + (defn try-resolve-subroutine "Attempt to resolve this `subr` with these `arg`." @@ -143,15 +284,26 @@ (defn- EVCON "Inner guts of primitive COND. All `clauses` are assumed to be `beowulf.cons-cell/ConsCell` objects. Note that tests in Lisp 1.5 - often return `F`, not `NIL`, on failure. + often return `F`, not `NIL`, on failure. If no clause matches, + then, strictly, we throw an error with code `:A3`. - See page 13 of the Lisp 1.5 Programmers Manual." + See pages 13 and 71 of the Lisp 1.5 Programmers Manual." [clauses env depth] - (let [test (EVAL (CAAR clauses) env depth)] - (if - (and (not= test NIL) (not= test 'F)) - (EVAL (CADAR clauses) env depth) - (EVCON (CDR clauses) env depth)))) + (loop [clauses' clauses] + (if-not (= clauses' NIL) + (let [test (EVAL (CAAR clauses') env depth)] + (if (not (#{NIL F} test)) + ;; (and (not= test NIL) (not= test F)) + (EVAL (CADAR clauses') env depth) + (recur (.getCdr clauses')))) + (if (:strict *options*) + (throw (ex-info "No matching clause in COND" + {:phase :eval + :function 'COND + :args (list clauses) + :type :lisp + :code :A3})) + NIL)))) (defn- EVLIS "Map `EVAL` across this list of `args` in the context of this @@ -214,9 +366,10 @@ :expr expr})) (symbol expr)) (= (ATOM (CAR expr)) T) (case (CAR expr) - QUOTE (CADR expr) - FUNCTION (LIST 'FUNARG (CADR expr)) COND (EVCON (CDR expr) env depth) + FUNCTION (LIST 'FUNARG (CADR expr)) + PROG (PROG (CDR expr) env depth) + QUOTE (CADR expr) ;; else (APPLY (CAR expr)