From 8b99c62ac3f51015bb06fbe2865832251e1518c1 Mon Sep 17 00:00:00 2001 From: Simon Brooke Date: Tue, 11 Apr 2023 00:35:45 +0100 Subject: [PATCH 1/4] char-reader is beginning to work, codox themes working. --- docs/codox/beowulf.bootstrap.html | 2 +- docs/codox/beowulf.cons-cell.html | 2 +- docs/codox/beowulf.core.html | 2 +- docs/codox/beowulf.gendoc.html | 2 +- docs/codox/beowulf.host.html | 2 +- docs/codox/beowulf.interop.html | 2 +- docs/codox/beowulf.io.html | 2 +- docs/codox/beowulf.manual.html | 2 +- docs/codox/beowulf.oblist.html | 2 +- docs/codox/beowulf.read.html | 2 +- docs/codox/beowulf.reader.char-reader.html | 7 +- docs/codox/beowulf.reader.generate.html | 2 +- docs/codox/beowulf.reader.macros.html | 2 +- docs/codox/beowulf.reader.parser.html | 2 +- docs/codox/beowulf.reader.simplify.html | 2 +- docs/codox/beowulf.scratch.html | 3 +- .../journeyman/css => docs/codox}/default.css | 0 docs/codox/further_reading.html | 2 +- .../css => docs/codox}/highlight.css | 0 docs/codox/index.html | 2 +- docs/codox/intro.html | 845 +++++++++++++++++- docs/codox/mexpr.html | 2 +- docs/codox/values.html | 2 +- project.clj | 16 +- .../codox/theme/journeyman/css/default.css | 563 ++++++++++++ .../codox/theme/journeyman/css/highlight.css | 97 ++ resources/codox/theme/journeyman/theme.edn | 11 + resources/codox/themes/journeyman/theme.edn | 1 - src/beowulf/core.clj | 7 +- src/beowulf/read.clj | 18 +- src/beowulf/reader/char_reader.clj | 80 +- 31 files changed, 1603 insertions(+), 81 deletions(-) rename {resources/codox/themes/journeyman/css => docs/codox}/default.css (100%) rename {resources/codox/themes/journeyman/css => docs/codox}/highlight.css (100%) create mode 100644 resources/codox/theme/journeyman/css/default.css create mode 100644 resources/codox/theme/journeyman/css/highlight.css create mode 100644 resources/codox/theme/journeyman/theme.edn delete mode 100644 resources/codox/themes/journeyman/theme.edn diff --git a/docs/codox/beowulf.bootstrap.html b/docs/codox/beowulf.bootstrap.html index 8301c99..72c621f 100644 --- a/docs/codox/beowulf.bootstrap.html +++ b/docs/codox/beowulf.bootstrap.html @@ -1,6 +1,6 @@ -beowulf.bootstrap documentation

Project

Topics

Namespaces

Public Vars

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

Project

Topics

Namespaces

Public Vars

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.

view source

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.

view source

find-target

TODO: write docs

view source

PROG

(PROG program env depth)

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

diff --git a/docs/codox/beowulf.cons-cell.html b/docs/codox/beowulf.cons-cell.html index 6e2b315..cc83668 100644 --- a/docs/codox/beowulf.cons-cell.html +++ b/docs/codox/beowulf.cons-cell.html @@ -1,3 +1,3 @@ -beowulf.cons-cell documentation

Project

Topics

Namespaces

Public Vars

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?

view source

F

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

view source

make-beowulf-list

(make-beowulf-list x)

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

view source

make-cons-cell

(make-cons-cell car cdr)

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

view source

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

view source

pretty-print

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

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

view source

T

The canonical true value.

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

Project

Topics

Namespaces

Public Vars

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?

view source

F

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

view source

make-beowulf-list

(make-beowulf-list x)

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

view source

make-cons-cell

(make-cons-cell car cdr)

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

view source

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

view source

pretty-print

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

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

view source

T

The canonical true value.

view source
\ No newline at end of file diff --git a/docs/codox/beowulf.core.html b/docs/codox/beowulf.core.html index 8b8b2ef..1d60abf 100644 --- a/docs/codox/beowulf.core.html +++ b/docs/codox/beowulf.core.html @@ -1,3 +1,3 @@ -beowulf.core documentation

Project

Topics

Namespaces

Public Vars

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.

view source

cli-options

TODO: write docs

view source

repl

(repl prompt)

Read/eval/print loop.

view source

stop-word

The word which, if submitted an an input line, will cause Beowulf to quit. Question: should this be forlǣte?

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

Project

Topics

Namespaces

Public Vars

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.

view source

cli-options

TODO: write docs

view source

repl

(repl prompt)

Read/eval/print loop.

view source

stop-word

The word which, if submitted an an input line, will cause Beowulf to quit. Question: should this be forlǣte?

view source
\ No newline at end of file diff --git a/docs/codox/beowulf.gendoc.html b/docs/codox/beowulf.gendoc.html index 763e8ab..fa4087e 100644 --- a/docs/codox/beowulf.gendoc.html +++ b/docs/codox/beowulf.gendoc.html @@ -1,4 +1,4 @@ -beowulf.gendoc documentation

Project

Topics

Namespaces

Public Vars

beowulf.gendoc

Generate table of documentation of Lisp symbols and functions.

+beowulf.gendoc documentation

Project

Topics

Namespaces

Public Vars

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.

view source

gen-doc-table

(gen-doc-table)

TODO: write docs

view source

gen-index

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

TODO: write docs

view source

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.

view source

infer-implementation

(infer-implementation entry)

TODO: write docs

view source

infer-signature

(infer-signature entry)

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

view source

infer-type

(infer-type entry)

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

view source

open-doc

(open-doc symbol)

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

view source
\ No newline at end of file diff --git a/docs/codox/beowulf.host.html b/docs/codox/beowulf.host.html index d6c6f6f..efef2cb 100644 --- a/docs/codox/beowulf.host.html +++ b/docs/codox/beowulf.host.html @@ -1,6 +1,6 @@ -beowulf.host documentation

Project

Topics

Namespaces

Public Vars

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

view source

AND

(AND & args)

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

+beowulf.host documentation

Project

Topics

Namespaces

Public Vars

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

view source

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.

view source

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.

view source

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.

view source

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.

view source

CAAAAR

macro

(CAAAAR x)

TODO: write docs

view source

CAAADR

macro

(CAAADR x)

TODO: write docs

view source

CAAAR

macro

(CAAAR x)

TODO: write docs

view source

CAADAR

macro

(CAADAR x)

TODO: write docs

view source

CAADDR

macro

(CAADDR x)

TODO: write docs

view source

CAADR

macro

(CAADR x)

TODO: write docs

view source

CAAR

macro

(CAAR x)

TODO: write docs

view source

CADAAR

macro

(CADAAR x)

TODO: write docs

view source

CADADR

macro

(CADADR x)

TODO: write docs

view source

CADAR

macro

(CADAR x)

TODO: write docs

view source

CADDAR

macro

(CADDAR x)

TODO: write docs

view source

CADDDR

macro

(CADDDR x)

TODO: write docs

view source

CADDR

macro

(CADDR x)

TODO: write docs

view source

CADR

macro

(CADR x)

TODO: write docs

view source

CAR

(CAR x)

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

view source

CDAAAR

macro

(CDAAAR x)

TODO: write docs

view source

CDAADR

macro

(CDAADR x)

TODO: write docs

view source

CDAAR

macro

(CDAAR x)

TODO: write docs

view source

CDADAR

macro

(CDADAR x)

TODO: write docs

view source

CDADDR

macro

(CDADDR x)

TODO: write docs

view source

CDADR

macro

(CDADR x)

TODO: write docs

view source

CDAR

macro

(CDAR x)

TODO: write docs

view source

CDDAAR

macro

(CDDAAR x)

TODO: write docs

view source

CDDADR

macro

(CDDADR x)

TODO: write docs

view source

CDDAR

macro

(CDDAR x)

TODO: write docs

view source

CDDDAR

macro

(CDDDAR x)

TODO: write docs

view source

CDDDDR

macro

(CDDDDR x)

TODO: write docs

view source

CDDDR

macro

(CDDDR x)

TODO: write docs

view source

CDDR

macro

(CDDR x)

TODO: write docs

view source

CDR

(CDR x)

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

view source

CONS

(CONS car cdr)

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

view source

CONSP

(CONSP o)

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

diff --git a/docs/codox/beowulf.interop.html b/docs/codox/beowulf.interop.html index cd46169..59e1c5b 100644 --- a/docs/codox/beowulf.interop.html +++ b/docs/codox/beowulf.interop.html @@ -1,6 +1,6 @@ -beowulf.interop documentation

Project

Topics

Namespaces

Public Vars

beowulf.interop

TODO: write docs

INTEROP

(INTEROP fn-symbol args)

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

+beowulf.interop documentation

Project

Topics

Namespaces

Public Vars

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. a sequence (list) of symbols forming a qualified path name bound to a function.
    3. diff --git a/docs/codox/beowulf.io.html b/docs/codox/beowulf.io.html index d5bae54..648f733 100644 --- a/docs/codox/beowulf.io.html +++ b/docs/codox/beowulf.io.html @@ -1,6 +1,6 @@ -beowulf.io documentation

    Project

    Topics

    Namespaces

    Public Vars

    beowulf.io

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

    +beowulf.io documentation

    Project

    Topics

    Namespaces

    Public Vars

    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.

    diff --git a/docs/codox/beowulf.manual.html b/docs/codox/beowulf.manual.html index cd01906..3a82449 100644 --- a/docs/codox/beowulf.manual.html +++ b/docs/codox/beowulf.manual.html @@ -1,3 +1,3 @@ -beowulf.manual documentation

    Project

    Topics

    Namespaces

    Public Vars

    beowulf.manual

    Experimental code for accessing the manual online.

    *manual-url*

    dynamic

    TODO: write docs

    view source

    format-page-references

    (format-page-references fn-symbol)

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

    view source

    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.

    view source

    page-url

    (page-url page-no)

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

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

    Project

    Topics

    Namespaces

    Public Vars

    beowulf.manual

    Experimental code for accessing the manual online.

    *manual-url*

    dynamic

    TODO: write docs

    view source

    format-page-references

    (format-page-references fn-symbol)

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

    view source

    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.

    view source

    page-url

    (page-url page-no)

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

    view source
    \ No newline at end of file diff --git a/docs/codox/beowulf.oblist.html b/docs/codox/beowulf.oblist.html index 74f48e7..ea54aa2 100644 --- a/docs/codox/beowulf.oblist.html +++ b/docs/codox/beowulf.oblist.html @@ -1,5 +1,5 @@ -beowulf.oblist documentation

    Project

    Topics

    Namespaces

    Public Vars

    beowulf.oblist

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

    +beowulf.oblist documentation

    Project

    Topics

    Namespaces

    Public Vars

    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.

    view source

    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?

    view source

    oblist

    The default environment.

    view source
    \ No newline at end of file diff --git a/docs/codox/beowulf.read.html b/docs/codox/beowulf.read.html index cfa7e94..1a7c002 100644 --- a/docs/codox/beowulf.read.html +++ b/docs/codox/beowulf.read.html @@ -1,6 +1,6 @@ -beowulf.read documentation

    Project

    Topics

    Namespaces

    Public Vars

    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

    Project

    Topics

    Namespaces

    Public Vars

    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 a014787..e726009 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

      Project

      Topics

      Namespaces

      Public Vars

        beowulf.reader.char-reader

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

        +beowulf.reader.char-reader documentation

        Project

        Topics

        Namespaces

        Public Vars

        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)

          @@ -10,4 +10,7 @@
        1. offers potential auto-completions taken from the value of (OBLIST), ideally the current value, not the value at the time the session started;
        2. and offer movement and editing within the line.
        -

        TODO: There are multiple problems with JLine; a better solution might be to start from here: https://stackoverflow.com/questions/7931988/how-to-manipulate-control-characters

        \ No newline at end of file +

        TODO: There are multiple problems with JLine; a better solution might be to start from here: https://stackoverflow.com/questions/7931988/how-to-manipulate-control-characters

        build-completer

        (build-completer)

        Build a completer which takes tokens from the oblist.

        +

        This is sort-of working, in as much as hitting on a blank line will show a table of values from the oblist, but hitting after you’ve started input does not show potential completions for tokens you’ve started.

        view source

        get-reader

        Return a reader, first constructing it if necessary.

        +

        NOTE THAT this is not settled API. The existence and call signature of this function is not guaranteed in future versions.

        view source

        read-chars

        (read-chars)

        A drop-in replacement for clojure.core/read-line, except that line editing and history should be enabled.

        +

        NOTE THAT this does not fully work yet, but it is in the API because I hope that it will work later!

        view source
        \ No newline at end of file diff --git a/docs/codox/beowulf.reader.generate.html b/docs/codox/beowulf.reader.generate.html index 58d4e15..f2d763e 100644 --- a/docs/codox/beowulf.reader.generate.html +++ b/docs/codox/beowulf.reader.generate.html @@ -1,6 +1,6 @@ -beowulf.reader.generate documentation

        Project

        Topics

        Namespaces

        Public Vars

        beowulf.reader.generate

        Generating S-Expressions from parse trees.

        +beowulf.reader.generate documentation

        Project

        Topics

        Namespaces

        Public Vars

        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 19c4982..55003ec 100644 --- a/docs/codox/beowulf.reader.macros.html +++ b/docs/codox/beowulf.reader.macros.html @@ -1,5 +1,5 @@ -beowulf.reader.macros documentation

        Project

        Topics

        Namespaces

        Public Vars

        beowulf.reader.macros

        Can I implement reader macros? let’s see!

        +beowulf.reader.macros documentation

        Project

        Topics

        Namespaces

        Public Vars

        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

        view source

        expand-macros

        (expand-macros form)

        TODO: write docs

        view source
        \ No newline at end of file diff --git a/docs/codox/beowulf.reader.parser.html b/docs/codox/beowulf.reader.parser.html index 7499c5e..25eb874 100644 --- a/docs/codox/beowulf.reader.parser.html +++ b/docs/codox/beowulf.reader.parser.html @@ -1,3 +1,3 @@ -beowulf.reader.parser documentation

        Project

        Topics

        Namespaces

        Public Vars

        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.

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

        Project

        Topics

        Namespaces

        Public Vars

        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.

        view source
        \ No newline at end of file diff --git a/docs/codox/beowulf.reader.simplify.html b/docs/codox/beowulf.reader.simplify.html index 52fa75b..013d66f 100644 --- a/docs/codox/beowulf.reader.simplify.html +++ b/docs/codox/beowulf.reader.simplify.html @@ -1,4 +1,4 @@ -beowulf.reader.simplify documentation

        Project

        Topics

        Namespaces

        Public Vars

        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

        view source

        remove-optional-space

        (remove-optional-space tree)

        TODO: write docs

        view source

        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.

        view source

        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

        Project

        Topics

        Namespaces

        Public Vars

        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

        view source

        remove-optional-space

        (remove-optional-space tree)

        TODO: write docs

        view source

        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.

        view source

        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.

        view source
        \ No newline at end of file diff --git a/docs/codox/beowulf.scratch.html b/docs/codox/beowulf.scratch.html index bdd1149..671f5a6 100644 --- a/docs/codox/beowulf.scratch.html +++ b/docs/codox/beowulf.scratch.html @@ -1,3 +1,4 @@ -beowulf.scratch documentation

        Project

        Topics

        Namespaces

        Public Vars

        beowulf.scratch

        This namespace is for temporary functions and is intentionally excluded from Git.

        accessor-body

        (accessor-body l v)

        TODO: write docs

        view source

        accessor-symbol

        (accessor-symbol l)

        Generate a symbol by prepending C and appending A to this list of string fragments l.

        view source

        accessors-generator

        (accessors-generator n)

        TODO: write docs

        view source

        manual-index

        TODO: write docs

        view source

        mogrify-plist

        (mogrify-plist entry fns)

        TODO: write docs

        view source
        \ No newline at end of file +beowulf.scratch documentation

        Project

        Topics

        Namespaces

        Public Vars

        beowulf.scratch

        This namespace is for temporary functions and is intentionally excluded from Git.

        fns

        TODO: write docs

        view source

        interop-listify-q-name

        (interop-listify-q-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.

        view source

        mogrify-plist

        (mogrify-plist entry fns)

        TODO: write docs

        view source
        \ No newline at end of file diff --git a/resources/codox/themes/journeyman/css/default.css b/docs/codox/default.css similarity index 100% rename from resources/codox/themes/journeyman/css/default.css rename to docs/codox/default.css diff --git a/docs/codox/further_reading.html b/docs/codox/further_reading.html index 4ff9617..2c027dd 100644 --- a/docs/codox/further_reading.html +++ b/docs/codox/further_reading.html @@ -1,6 +1,6 @@ -Further Reading

        Project

        Topics

        Namespaces

        Further Reading

        +Further Reading

        Project

        Topics

        Namespaces

        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. MIT AI Memo 1, John McCarthy, September 1958 This is, as far as I can find, the earliest specification document of the Lisp project.
          3. diff --git a/resources/codox/themes/journeyman/css/highlight.css b/docs/codox/highlight.css similarity index 100% rename from resources/codox/themes/journeyman/css/highlight.css rename to docs/codox/highlight.css diff --git a/docs/codox/index.html b/docs/codox/index.html index 5d09c60..01c5b4f 100644 --- a/docs/codox/index.html +++ b/docs/codox/index.html @@ -1,3 +1,3 @@ -Beowulf 0.3.0

          Project

          Topics

          Namespaces

          Beowulf 0.3.0

          Released under the GPL-2.0-or-later

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

          Installation

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

          [beowulf "0.3.0"]

          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.

          Public variables and functions:

          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.

          Public variables 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.

          Public variables and functions:

          beowulf.interop

          TODO: write docs

          Public variables and functions:

          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.generate

            Generating S-Expressions from parse trees.

            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.

            Public variables and functions:

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

            Project

            Topics

            Namespaces

            Beowulf 0.3.1-SNAPSHOT

            Released under the GPL-2.0-or-later

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

            Installation

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

            [beowulf "0.3.1-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.

            Public variables and functions:

            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.

            Public variables 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.

            Public variables and functions:

            beowulf.interop

            TODO: write docs

            Public variables and functions:

            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.generate

            Generating S-Expressions from parse trees.

            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.

            Public variables and functions:

            beowulf.scratch

            This namespace is for temporary functions and is intentionally excluded from Git.

            Public variables and functions:

            \ No newline at end of file diff --git a/docs/codox/intro.html b/docs/codox/intro.html index e54cf99..03c2696 100644 --- a/docs/codox/intro.html +++ b/docs/codox/intro.html @@ -1,14 +1,835 @@ - - - - Beowulf: Documentation - - - -

            Beowulf: Documentation

            + +beowulf

            Project

            Topics

            Namespaces

            beowulf

            +

            Þý liste cræfte spræc

            +

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

            +

            Beowulf logo

            +

            Contents

            + +Table of contents generated with markdown-toc +

            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.

            +

            BUT WHY?!!?!

            +

            Because.

            +

            Because Lisp is the only computer language worth learning, and if a thing is worth learning, it’s worth learning properly; which means going back to the beginning and trying to understand that.

            +

            Because there is, so far as I know, no working implementation of Lisp 1.5 for modern machines.

            +

            Because I’m barking mad, and this is therapy.

            +

            Status

            +

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

            + +

            Project Target

            +

            The project target is to be able to run the Wang algorithm for the propositional calculus given in chapter 8 of the Lisp 1.5 Programmer’s Manual. When that runs, the project is as far as I am concerned feature complete. I may keep tinkering with it after that and I’ll certainly accept pull requests which are in the spirit of the project (i.e. making Beowulf more usable, and/or implementing parts of Lisp 1.5 which I have not implemented), but this isn’t intended to be a new language for doing real work; it’s an educational and archaeological project, not serious engineering.

            +

            Some readline-like functionality would be really useful, but my attempt to integrate JLine has not (yet) been successful.

            +

            An in-core structure editor would be an extremely nice thing, and I may well implement one.

            +

            You are of course welcome to fork the project and do whatever you like with it!

            +

            Invoking

            +

            Invoke with

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

            (Obviously, check your version number)

            +

            Command line arguments as follows:

            +
              -h, --help                               Print this message
+  -p PROMPT, --prompt PROMPT               Set the REPL prompt to PROMPT
+  -r INITFILE, --read SYSOUTFILE           Read Lisp sysout from the file SYSOUTFILE 
+                                           (defaults to `resources/lisp1.5.lsp`)
+  -s, --strict                             Strictly interpret the Lisp 1.5 language, 
+                                           without extensions.
+
            +

            To end a session, type STOP at the command prompt.

            +

            Building and Invoking

            +

            Build with

            +
            lein uberjar
+
            +

            Reader macros

            +

            Currently SETQ and DEFUN are implemented as reader macros, sort of. It would now be possible to reimplement them as FEXPRs and so the reader macro functionality will probably go away.

            +

            Functions and symbols implemented

            + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
            Function Type Signature Implementation Documentation
            NIL Lisp variable ? see manual pages 22, 69
            T Lisp variable ? see manual pages 22, 69
            F Lisp variable ? see manual pages 22, 69
            ADD1 Host lambda function ? ?
            AND Host lambda function ? PREDICATE 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.
            APPEND Lisp lambda function ? see manual pages 11, 61
            APPLY Host lambda function ? 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.
            ASSOC Lisp lambda function, Host lambda function ? ? 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 Host lambda function ? PREDICATE 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.
            CAR Host lambda function ? Return the item indicated by the first pointer of a pair. NIL is treated specially: the CAR of NIL is NIL.
            CAAAAR Lisp lambda function ? ? ?
            CAAADR Lisp lambda function ? ? ?
            CAAAR Lisp lambda function ? ? ?
            CAADAR Lisp lambda function ? ? ?
            CAADDR Lisp lambda function ? ? ?
            CAADR Lisp lambda function ? ? ?
            CAAR Lisp lambda function ? ? ?
            CADAAR Lisp lambda function ? ? ?
            CADADR Lisp lambda function ? ? ?
            CADAR Lisp lambda function ? ? ?
            CADDAR Lisp lambda function ? ? ?
            CADDDR Lisp lambda function ? ? ?
            CADDR Lisp lambda function ? ? ?
            CADR Lisp lambda function ? ? ?
            CDAAAR Lisp lambda function ? ? ?
            CDAADR Lisp lambda function ? ? ?
            CDAAR Lisp lambda function ? ? ?
            CDADAR Lisp lambda function ? ? ?
            CDADDR Lisp lambda function ? ? ?
            CDADR Lisp lambda function ? ? ?
            CDAR Lisp lambda function ? ? ?
            CDDAAR Lisp lambda function ? ? ?
            CDDADR Lisp lambda function ? ? ?
            CDDAR Lisp lambda function ? ? ?
            CDDDAR Lisp lambda function ? ? ?
            CDDDDR Lisp lambda function ? ? ?
            CDDDR Lisp lambda function ? ? ?
            CDDR Lisp lambda function ? ? ?
            CDR Host lambda function ? Return the item indicated by the second pointer of a pair. NIL is treated specially: the CDR of NIL is NIL.
            CONS Host lambda function ? Construct a new instance of cons cell with this car and cdr.
            CONSP Host lambda function ? ? 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.
            COPY Lisp lambda function ? see manual pages 62
            DEFINE Host lambda function ? PSEUDO-FUNCTION 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.
            DIFFERENCE Host lambda function ? ?
            DIVIDE Lisp lambda function ? see manual pages 26, 64
            DOC Host lambda function ? ? 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.
            EFFACE Lisp lambda function ? PSEUDO-FUNCTION see manual pages 63
            ERROR Host lambda function ? PSEUDO-FUNCTION Throw an error
            EQ Host lambda function ? PREDICATE Returns T if and only if both x and y are bound to the same atom, else NIL.
            EQUAL Host lambda function ? PREDICATE 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
            EVAL Host lambda function ? 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.
            FACTORIAL Lisp lambda function ? ? ?
            FIXP Host lambda function ? PREDICATE ?
            GENSYM Host lambda function ? Generate a unique symbol.
            GET Host lambda function ? 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 Host lambda function ? PREDICATE ?
            INTEROP Host lambda function ? ? ?
            INTERSECTION Lisp lambda function ? ? ?
            LENGTH Lisp lambda function ? see manual pages 62
            LESSP Host lambda function ? PREDICATE ?
            MAPLIST Lisp lambda function ? FUNCTIONAL see manual pages 20, 21, 63
            MEMBER Lisp lambda function ? PREDICATE see manual pages 11, 62
            MINUSP Lisp lambda function ? PREDICATE see manual pages 26, 64
            NOT Lisp lambda function ? PREDICATE see manual pages 21, 23, 58
            NULL Lisp lambda function ? PREDICATE see manual pages 11, 57
            NUMBERP Host lambda function ? PREDICATE ?
            OBLIST Host lambda function ? 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.
            ONEP Lisp lambda function ? PREDICATE see manual pages 26, 64
            OR Host lambda function ? PREDICATE 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.
            PAIR Lisp lambda function ? see manual pages 60
            PAIRLIS Lisp lambda function, Host lambda function ? ? 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 Host lambda function ? ?
            PRETTY ? ? ?
            PRINT ? PSEUDO-FUNCTION see manual pages 65, 84
            PROG Host nlambda function ? 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 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 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.
            PROP Lisp lambda function ? FUNCTIONAL see manual pages 59
            QUOTE Lisp lambda function ? see manual pages 10, 22, 71
            QUOTIENT Host lambda function ? 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.
            RANGE Lisp lambda function ? ? ?
            READ Host lambda function ? PSEUDO-FUNCTION An implementation of a Lisp reader sufficient for bootstrapping; not necessarily the final Lisp reader. input should be either a string representation of a LISP expression, or else an input stream. A single form will be read.
            REMAINDER Host lambda function ? ?
            REPEAT Lisp lambda function ? ? ?
            RPLACA Host lambda function ? PSEUDO-FUNCTION 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 Host lambda function ? PSEUDO-FUNCTION 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)
            SEARCH Lisp lambda function ? FUNCTIONAL see manual pages 63
            SET Host lambda function ? PSEUDO-FUNCTION 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 Lisp lambda function, Host lambda function ? ?
            SUB2 Lisp lambda function ? ? ?
            SUBLIS Lisp lambda function ? see manual pages 12, 61
            SUBST Lisp lambda function ? see manual pages 11, 61
            SYSIN Host lambda function ? ? 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 Host lambda function ? ? 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.
            TERPRI ? PSEUDO-FUNCTION see manual pages 65, 84
            TIMES Host lambda function ? ?
            TRACE Host lambda function ? PSEUDO-FUNCTION Add this s to the set of symbols currently being traced. If s is not a symbol or sequence of symbols, does nothing.
            UNION Lisp lambda function ? ? ?
            UNTRACE Host lambda function ? PSEUDO-FUNCTION Remove this s from the set of symbols currently being traced. If s is not a symbol or sequence of symbols, does nothing.
            ZEROP Lisp lambda function ? PREDICATE see manual pages 26, 64
            +

            Functions described as ‘Lisp function’ above are defined in the default sysout file, resources/lisp1.5.lsp, which will be loaded by default unless you specify another initfile on the command line.

            +

            Functions described as ‘Host function’ are implemented in Clojure, but if you’re brave you can redefine them in Lisp and the Lisp definitions will take precedence over the Clojure implementations.

            +

            Architectural plan

            +

            Not everything documented in this section is yet built. It indicates the direction of travel and intended destination, not the current state.

            +

            resources/lisp1.5.lsp

            +

            The objective is to have within resources/lisp1.5.lsp, all those functions defined in the Lisp 1.5 Programmer’s Manual which can be implemented in Lisp.

            +

            This means that, while Beowulf is hosted on Clojure, all that would be required to rehost Lisp 1.5 on a different platform would be to reimplement

            +
              +
            • bootstrap.clj
              • +
            • host.clj
              • +
            • read.clj
              • +
            +

            The objective this is to make it fairly easy to implement Lisp 1.5 on top of any of the many Make A Lisp implementations.

            +

            beowulf/boostrap.clj

            +

            This file is essentially 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, to bootstrap the full Lisp 1.5 interpreter.

            +

            In addition it contains the function INTEROP, which allows host language functions to be called from Lisp.

            +

            beowulf/host.clj

            +

            This file 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/read.clj

            +

            This file 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. +
            2. It treats everything between a double semi-colon and an end of line as a comment, as most modern Lisps do; but I do not believe Lisp 1.5 had this feature.
              3. +
            +

            Commentary

            +

            What’s surprised me in working on this is how much more polished Lisp 1.5 is than legend had led me to believe. The language is remarkably close to Portable Standard Lisp which is in my opinion one of the best and most usable early Lisp implementations.

            +

            What’s even more surprising is how faithful a reimplementation of Lisp 1.5 the first Lisp dialect I learned, Acornsoft Lisp, turns out to have been.

            +

            I’m convinced you could still use Lisp 1.5 for interesting and useful software (which isn’t to say that modern Lisps aren’t better, but this is software which is almost sixty years old).

            +

            Installation

            +

            Download the latest release ‘uberjar’ and run it using:

            +
                java -jar <path name of uberjar>
+
            +

            Or clone the source and build it using:

            +
                lein uberjar`
+
            +

            To build it you will require to have Leiningen installed.

            +

            Input/output

            +

            Lisp 1.5 greatly predates modern computers. It had a facility to print to a line printer, or to punch cards on a punch-card machine, and it had a facility to read system images in from tape; but there’s no file I/O as we would currently understand it, and, because there are no character strings and the valid characters within an atom are limited, it isn’t easy to compose a sensible filename.

            +

            I’ve provided two functions to work around this problem.

            +

            SYSOUT

            +

            SYSOUT dumps the global object list to disk as a single S Expression (specifically: an association list). This allows you to persist your session, with all your current work, to disk. The function takes one argument, expected to be a symbol, and, if that argument is provided, writes a file whose name is that symbol with .lsp appended. If no argument is provided, it will construct a filename comprising the token Sysout, followed by the current date, followed by .lsp. In either case the file will be written to the directory given in the FILEPATH argument at startup time, or by default the current directory.

            +

            Obviously, SYSOUT may be called interactively (and this is the expected practice).

            +

            SYSIN

            +

            SYSIN reads a file from disk and overwrites the global object list with its contents. The expected practice is that this will be a file created by SYSOUT. A command line flag --read is provided so that you can specify

            +

            Learning Lisp 1.5

            +

            The Lisp 1.5 Programmer's Manual is still in print, ISBN 13 978-0-262-13011-0; but it’s also available online.

            +

            Other Lisp 1.5 resources

            +

            The main resource I’m aware of is the Software Preservation Society’s site, here. It has lots of fascinating stuff including full assembler listings for various obsolete processors, but I failed to find the Lisp source of Lisp functions as a text file, which is why resources/lisp1.5.lsp is largely copytyped and reconstructed from the manual.

            +

            Other implementations

            +

            There’s an online (browser native) Lisp 1.5 implementation here (source code here). It even has a working compiler!

            +

            History resources

            +

            I’m compiling a list of links to historical documents on Lisp 1.5.

            +

            License

            +

            Copyright © 2019 Simon Brooke. Licensed under the GNU General Public License, version 2.0 or (at your option) any later version.

            \ No newline at end of file diff --git a/docs/codox/mexpr.html b/docs/codox/mexpr.html index 7692fe9..a4cedae 100644 --- a/docs/codox/mexpr.html +++ b/docs/codox/mexpr.html @@ -1,6 +1,6 @@ -Interpreting M-Expressions

            Project

            Topics

            Namespaces

            Interpreting M-Expressions

            +Interpreting M-Expressions

            Project

            Topics

            Namespaces

            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 1bfdc12..0cfcf99 100644 --- a/docs/codox/values.html +++ b/docs/codox/values.html @@ -1,6 +1,6 @@ -The properties of the system, and their values

            Project

            Topics

            Namespaces

            The properties of the system, and their values

            +The properties of the system, and their values

            Project

            Topics

            Namespaces

            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?

            diff --git a/project.clj b/project.clj index 1fa5892..20483ff 100644 --- a/project.clj +++ b/project.clj @@ -2,16 +2,11 @@ :aot :all :cloverage {:output "docs/cloverage" :ns-exclude-regex [#"beowulf\.gendoc" #"beowulf\.scratch"]} - :codox {:html {:transforms [[:head] [:append - [:link {:rel "icon" - :type "image/x-icon" - :href "../img/beowulf_logo_favicon.png"}]]]} - :metadata {:doc "**TODO**: write docs" + :codox {:metadata {:doc "**TODO**: write docs" :doc/format :markdown} :output-path "docs/codox" :source-uri "https://github.com/simon-brooke/beowulf/blob/master/{filepath}#L{line}" - ;; :themes [:journeyman] - } + :themes [:journeyman]} :description "LISP 1.5 is to all Lisp dialects as Beowulf is to English literature." :license {:name "GPL-2.0-or-later" :url "https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html"} @@ -23,7 +18,7 @@ [clojure.java-time "1.2.0"] [environ "1.2.0"] [instaparse "1.4.12"] -;; [org.jline/jline "3.23.0"] + [org.jline/jline "3.23.0"] [rhizome "0.2.9"] ;; not needed in production builds ] :main beowulf.core @@ -31,7 +26,8 @@ [lein-codox "0.10.7"] [lein-environ "1.1.0"]] :profiles {:jar {:aot :all} - :uberjar {:aot :all}} + :uberjar {:aot :all} + :dev {:resource-paths ["resources"]}} :release-tasks [["vcs" "assert-committed"] ["change" "version" "leiningen.release/bump-version" "release"] ["vcs" "commit"] @@ -42,4 +38,4 @@ ["change" "version" "leiningen.release/bump-version"] ["vcs" "commit"]] :target-path "target/%s" - :url "https://github.com/simon-brooke/the-great-game") + :url "https://github.com/simon-brooke/beowulf") diff --git a/resources/codox/theme/journeyman/css/default.css b/resources/codox/theme/journeyman/css/default.css new file mode 100644 index 0000000..a445e91 --- /dev/null +++ b/resources/codox/theme/journeyman/css/default.css @@ -0,0 +1,563 @@ +body { + font-family: Helvetica, Arial, sans-serif; + font-size: 15px; + color: limegreen; + background-color: black; +} + +a { + color: lime; +} + +a:active, a:hover { + color: yellowgreen; +} + +a:visited { + color: green; +} + +pre, code { + font-family: Monaco, DejaVu Sans Mono, Consolas, monospace; + font-size: 9pt; + margin: 15px 0; + color: limegreen; + background-color: #111; +} + +h1 { + font-weight: normal; + font-size: 29px; + margin: 10px 0 2px 0; + padding: 0; +} + +h2 { + font-weight: normal; + font-size: 25px; +} + +th, td { + vertical-align: top; +} + +h5.license { + margin: 9px 0 22px 0; + color: lime; + font-weight: normal; + font-size: 12px; + font-style: italic; +} + +.document h1, .namespace-index h1 { + font-size: 32px; + margin-top: 12px; +} + +#header, #content, .sidebar { + position: fixed; +} + +#header { + top: 0; + left: 0; + right: 0; + height: 22px; + color: limegreen; + padding: 5px 7px; +} + +#content { + top: 32px; + right: 0; + bottom: 0; + overflow: auto; + background: black; + color: green; + padding: 0 18px; +} + +.sidebar { + position: fixed; + top: 32px; + bottom: 0; + overflow: auto; +} + +.sidebar.primary { + background: #080808; + border-right: solid 1px forestgreen; + left: 0; + width: 250px; +} + +.sidebar.secondary { + background: #111; + border-right: solid 1px darkgreen; + left: 251px; + width: 200px; +} + +#content.namespace-index, #content.document { + left: 251px; +} + +#content.namespace-docs { + left: 452px; +} + +#content.document { + padding-bottom: 10%; +} + +#header { + background: #080808; + box-shadow: 0 0 8px rgba(192, 255, 192, 0.4); + z-index: 100; +} + +#header h1 { + margin: 0; + padding: 0; + font-size: 18px; + font-weight: lighter; + text-shadow: -1px -1px 0px #333; +} + +#header h1 .project-version { + font-weight: normal; +} + +.project-version { + padding-left: 0.15em; +} + +#header a, .sidebar a { + display: block; + text-decoration: none; +} + +#header h2 { + float: right; + font-size: 9pt; + font-weight: normal; + margin: 4px 3px; + padding: 0; + color: #5f5; +} + +#header h2 a { + display: inline; +} + +.sidebar h3 { + margin: 0; + padding: 10px 13px 0 13px; + font-size: 19px; + font-weight: lighter; +} + +.sidebar h3 a { + color: #4f4; +} + +.sidebar h3.no-link { + color: green; +} + +.sidebar ul { + padding: 7px 0 6px 0; + margin: 0; +} + +.sidebar ul.index-link { + padding-bottom: 4px; +} + +.sidebar li { + display: block; + vertical-align: middle; +} + +.sidebar li a, .sidebar li .no-link { + border-left: 3px solid transparent; + padding: 0 10px; + white-space: nowrap; +} + +.sidebar li .no-link { + display: block; + color: #7F7; + font-style: italic; +} + +.sidebar li .inner { + display: inline-block; + padding-top: 7px; + height: 24px; +} + +.sidebar li a, .sidebar li .tree { + height: 31px; +} + +.depth-1 .inner { padding-left: 2px; } +.depth-2 .inner { padding-left: 6px; } +.depth-3 .inner { padding-left: 20px; } +.depth-4 .inner { padding-left: 34px; } +.depth-5 .inner { padding-left: 48px; } +.depth-6 .inner { padding-left: 62px; } + +.sidebar li .tree { + display: block; + float: left; + position: relative; + top: -10px; + margin: 0 4px 0 0; + padding: 0; +} + +.sidebar li.depth-1 .tree { + display: none; +} + +.sidebar li .tree .top, .sidebar li .tree .bottom { + display: block; + margin: 0; + padding: 0; + width: 7px; +} + +.sidebar li .tree .top { + border-left: 1px solid yellowgreen; + border-bottom: 1px solid yellowgreen; + height: 19px; +} + +.sidebar li .tree .bottom { + height: 22px; +} + +.sidebar li.branch .tree .bottom { + border-left: 1px solid yellowgreen; +} + +.sidebar.primary li.current a { + border-left: 3px solid goldenrod; + color: goldenrod; +} + +.sidebar.secondary li.current a { + border-left: 3px solid yellow; + color: yellow; +} + +.namespace-index h2 { + margin: 30px 0 0 0; +} + +.namespace-index h3 { + font-size: 16px; + font-weight: bold; + margin-bottom: 0; +} + +.namespace-index .topics { + padding-left: 30px; + margin: 11px 0 0 0; +} + +.namespace-index .topics li { + padding: 5px 0; +} + +.namespace-docs h3 { + font-size: 18px; + font-weight: bold; +} + +.public h3 { + margin: 0; + float: left; +} + +.usage { + clear: both; +} + +.public { + margin: 0; + border-top: 1px solid lime; + padding-top: 14px; + padding-bottom: 6px; +} + +.public:last-child { + margin-bottom: 20%; +} + +.members .public:last-child { + margin-bottom: 0; +} + +.members { + margin: 15px 0; +} + +.members h4 { + color: lime; + font-weight: normal; + font-variant: small-caps; + margin: 0 0 5px 0; +} + +.members .inner { + padding-top: 5px; + padding-left: 12px; + margin-top: 2px; + margin-left: 7px; + border-left: 1px solid #5f5; +} + +#content .members .inner h3 { + font-size: 12pt; +} + +.members .public { + border-top: none; + margin-top: 0; + padding-top: 6px; + padding-bottom: 0; +} + +.members .public:first-child { + padding-top: 0; +} + +h4.type, +h4.dynamic, +h4.added, +h4.deprecated { + float: left; + margin: 3px 10px 15px 0; + font-size: 15px; + font-weight: bold; + font-variant: small-caps; +} + +.public h4.type, +.public h4.dynamic, +.public h4.added, +.public h4.deprecated { + font-size: 13px; + font-weight: bold; + margin: 3px 0 0 10px; +} + +.members h4.type, +.members h4.added, +.members h4.deprecated { + margin-top: 1px; +} + +h4.type { + color: #717171; +} + +h4.dynamic { + color: #9933aa; +} + +h4.added { + color: #7acc32; +} + +h4.deprecated { + color: #880000; +} + +.namespace { + margin-bottom: 30px; +} + +.namespace:last-child { + margin-bottom: 10%; +} + +.index { + padding: 0; + font-size: 80%; + margin: 15px 0; + line-height: 16px; +} + +.index * { + display: inline; +} + +.index p { + padding-right: 3px; +} + +.index li { + padding-right: 5px; +} + +.index ul { + padding-left: 0; +} + +.type-sig { + clear: both; + color: goldenrod; +} + +.type-sig pre { + padding-top: 10px; + margin: 0; +} + +.usage code { + display: block; + margin: 2px 0; + color: limegreen; +} + +.usage code:first-child { + padding-top: 10px; +} + +p { + margin: 15px 0; +} + +.public p:first-child, .public pre.plaintext { + margin-top: 12px; +} + +.doc { + margin: 0 0 26px 0; + clear: both; +} + +.public .doc { + margin: 0; +} + +.namespace-index .doc { + margin-bottom: 20px; +} + +.namespace-index .namespace .doc { + margin-bottom: 10px; +} + +.markdown p, .markdown li, .markdown dt, .markdown dd, .markdown td { + line-height: 22px; +} + +.markdown li { + padding: 2px 0; +} + +.markdown h2 { + font-weight: normal; + font-size: 25px; + margin: 30px 0 10px 0; +} + +.markdown h3 { + font-weight: normal; + font-size: 20px; + margin: 30px 0 0 0; +} + +.markdown h4 { + font-size: 15px; + margin: 22px 0 -4px 0; +} + +.doc, .public, .namespace .index { + max-width: 680px; + overflow-x: visible; +} + +.markdown pre > code { + display: block; + padding: 10px; +} + +.markdown pre > code, .src-link a { + border: 1px solid lime; + border-radius: 2px; +} + +.markdown code:not(.hljs), .src-link a { + background: #111; +} + +pre.deps { + display: inline-block; + margin: 0 10px; + border: 1px solid lime; + border-radius: 2px; + padding: 10px; + background-color: #111; +} + +.markdown hr { + border-style: solid; + border-top: none; + color: goldenrod; +} + +.doc ul, .doc ol { + padding-left: 30px; +} + +.doc table { + border-collapse: collapse; + margin: 0 10px; +} + +.doc table td, .doc table th { + border: 1px solid goldenrod; + padding: 4px 6px; +} + +.doc table th { + background: #111; +} + +.doc dl { + margin: 0 10px 20px 10px; +} + +.doc dl dt { + font-weight: bold; + margin: 0; + padding: 3px 0; + border-bottom: 1px solid goldenrod; +} + +.doc dl dd { + padding: 5px 0; + margin: 0 0 5px 10px; +} + +.doc abbr { + border-bottom: 1px dotted goldenrod; + font-variant: none; + cursor: help; +} + +.src-link { + margin-bottom: 15px; +} + +.src-link a { + font-size: 70%; + padding: 1px 4px; + text-decoration: none; + color: lime5bb; +} diff --git a/resources/codox/theme/journeyman/css/highlight.css b/resources/codox/theme/journeyman/css/highlight.css new file mode 100644 index 0000000..d0cdaa3 --- /dev/null +++ b/resources/codox/theme/journeyman/css/highlight.css @@ -0,0 +1,97 @@ +/* +github.com style (c) Vasily Polovnyov +*/ + +.hljs { + display: block; + overflow-x: auto; + padding: 0.5em; + color: #333; + background: #f8f8f8; +} + +.hljs-comment, +.hljs-quote { + color: #998; + font-style: italic; +} + +.hljs-keyword, +.hljs-selector-tag, +.hljs-subst { + color: #333; + font-weight: bold; +} + +.hljs-number, +.hljs-literal, +.hljs-variable, +.hljs-template-variable, +.hljs-tag .hljs-attr { + color: #008080; +} + +.hljs-string, +.hljs-doctag { + color: #d14; +} + +.hljs-title, +.hljs-section, +.hljs-selector-id { + color: #900; + font-weight: bold; +} + +.hljs-subst { + font-weight: normal; +} + +.hljs-type, +.hljs-class .hljs-title { + color: #458; + font-weight: bold; +} + +.hljs-tag, +.hljs-name, +.hljs-attribute { + color: #000080; + font-weight: normal; +} + +.hljs-regexp, +.hljs-link { + color: #009926; +} + +.hljs-symbol, +.hljs-bullet { + color: #990073; +} + +.hljs-built_in, +.hljs-builtin-name { + color: #0086b3; +} + +.hljs-meta { + color: #999; + font-weight: bold; +} + +.hljs-deletion { + background: #fdd; +} + +.hljs-addition { + background: #dfd; +} + +.hljs-emphasis { + font-style: italic; +} + +.hljs-strong { + font-weight: bold; +} diff --git a/resources/codox/theme/journeyman/theme.edn b/resources/codox/theme/journeyman/theme.edn new file mode 100644 index 0000000..0875f7f --- /dev/null +++ b/resources/codox/theme/journeyman/theme.edn @@ -0,0 +1,11 @@ +{:resources ["css/default.css" "css/highlight.css"] + :transforms [[:head] [:append + [:link {:rel "stylesheet" + :type "text/css" + :href "css/default.css"}] + [:link {:rel "stylesheet" + :type "text/css" + :href "css/highlight.css"}] + [:link {:rel "icon" + :type "image/x-icon" + :href "../img/beowulf_logo_favicon.png"}]]]} \ No newline at end of file diff --git a/resources/codox/themes/journeyman/theme.edn b/resources/codox/themes/journeyman/theme.edn deleted file mode 100644 index e1fdd5e..0000000 --- a/resources/codox/themes/journeyman/theme.edn +++ /dev/null @@ -1 +0,0 @@ -{:resources ["css/default.css" "css/highlight.css"]} \ No newline at end of file diff --git a/src/beowulf/core.clj b/src/beowulf/core.clj index d20339d..dacedef 100644 --- a/src/beowulf/core.clj +++ b/src/beowulf/core.clj @@ -63,11 +63,10 @@ (defn repl "Read/eval/print loop." [prompt] - (loop [] - (print prompt) + (loop [] (flush) (try - (if-let [input (trim (read-from-console))] + (if-let [input (trim (read-from-console prompt))] (if (= input stop-word) (throw (ex-info "\nFærwell!" {:cause :quit})) (println @@ -116,7 +115,7 @@ (catch Throwable any (println any)))) (try - (repl (str (:prompt (:options args)) " ")) + (repl (:prompt (:options args))) (catch Exception e diff --git a/src/beowulf/read.clj b/src/beowulf/read.clj index 54fcfe4..38860dc 100644 --- a/src/beowulf/read.clj +++ b/src/beowulf/read.clj @@ -13,13 +13,14 @@ Both these extensions can be disabled by using the `--strict` command line switch." - (:require ;; [beowulf.reader.char-reader :refer [read-chars]] + (:require [beowulf.oblist :refer [*options*]] + [beowulf.reader.char-reader :refer [read-chars]] [beowulf.reader.generate :refer [generate]] [beowulf.reader.parser :refer [parse]] [beowulf.reader.simplify :refer [simplify]] [clojure.string :refer [join split starts-with? trim]]) - (:import [java.io InputStream] - [instaparse.gll Failure])) + (:import [instaparse.gll Failure] + [java.io InputStream])) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; @@ -83,23 +84,22 @@ (generate (simplify parse-tree))))) (defn read-from-console - "Attempt to read a complete lisp expression from the console. NOTE that this - will only really work for S-Expressions, not M-Expressions." - [] - (loop [r (read-line)] + "Attempt to read a complete lisp expression from the console." + [prompt] + (loop [r (read-chars prompt)] (if (and (= (count (re-seq #"\(" r)) (count (re-seq #"\)" r))) (= (count (re-seq #"\[" r)) (count (re-seq #"\]" r)))) r - (recur (str r "\n" (read-line)))))) + (recur (str r "\n" (read-chars "")))))) (defn READ "An implementation of a Lisp reader sufficient for bootstrapping; not necessarily the final Lisp reader. `input` should be either a string representation of a LISP expression, or else an input stream. A single form will be read." ([] - (gsp (read-from-console))) + (gsp (read-from-console (:prompt *options*)))) ([input] (cond (empty? input) (READ) diff --git a/src/beowulf/reader/char_reader.clj b/src/beowulf/reader/char_reader.clj index 883f8fa..a38f301 100644 --- a/src/beowulf/reader/char_reader.clj +++ b/src/beowulf/reader/char_reader.clj @@ -20,9 +20,12 @@ TODO: There are multiple problems with JLine; a better solution might be to start from here: https://stackoverflow.com/questions/7931988/how-to-manipulate-control-characters" - ;; (:import [org.jline.reader LineReader LineReaderBuilder] - ;; [org.jline.terminal TerminalBuilder]) - ) + (:require [beowulf.oblist :refer [*options* oblist]]) + (:import [org.jline.reader.impl.completer StringsCompleter] + [org.jline.reader.impl DefaultParser DefaultParser$Bracket] + [org.jline.reader LineReaderBuilder] + [org.jline.terminal TerminalBuilder] + [org.jline.widget AutopairWidgets AutosuggestionWidgets])) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; @@ -49,27 +52,56 @@ ;; looks as though you'd need a DPhil in JLine to write it, and I don't have ;; the time. -;; (def get-reader -;; "Return a reader, first constructing it if necessary. +(defn build-completer + "Build a completer which takes tokens from the oblist. -;; **NOTE THAT** this is not settled API. The existence and call signature of -;; this function is not guaranteed in future versions." -;; (memoize (fn [] -;; (let [term (.build (.system (TerminalBuilder/builder) true))] -;; (.build (.terminal (LineReaderBuilder/builder) term)))))) + This is sort-of working, in as much as hitting on a blank line will + show a table of values from the oblist, but hitting after you've + started input does not show potential completions for tokens you've started." + [] + (StringsCompleter. (map #(str (first %)) @oblist))) -;; (defn read-chars -;; "A drop-in replacement for `clojure.core/read-line`, except that line editing -;; and history should be enabled. +;; This breaks; it is not correctly resolving the Enum, although I can't work out +;; why not. +;; (defn build-parser +;; [] +;; (println "Building parser") +;; (let [parser (DefaultParser.)] +;; (doall +;; (.setEofOnUnclosedBracket +;; parser DefaultParser$Bracket/ROUND)))) + +(def get-reader + "Return a reader, first constructing it if necessary. -;; **NOTE THAT** this does not work yet, but it is in the API because I hope -;; that it will work later!" -;; [] -;; (let [eddie (get-reader)] -;; (loop [s (.readLine eddie)] -;; (if (and (= (count (re-seq #"\(" s)) -;; (count (re-seq #"\)" s))) -;; (= (count (re-seq #"\[]" s)) -;; (count (re-seq #"\]" s)))) -;; s -;; (recur (str s " " (.readLine eddie))))))) \ No newline at end of file + **NOTE THAT** this is not settled API. The existence and call signature of + this function is not guaranteed in future versions." + (memoize (fn [] + (let [term (.build (.system (TerminalBuilder/builder) true)) + reader (-> (LineReaderBuilder/builder) + (.terminal term) + (.completer (build-completer)) + ;; #(.parser % (build-parser)) + (.build)) + ;; apw (AutopairWidgets. reader false) + ;; asw (AutosuggestionWidgets. reader) + ] + ;; (.enable apw) + ;; (.enable asw) + reader)))) + +(defn read-chars + "A drop-in replacement for `clojure.core/read-line`, except that line editing + and history should be enabled. + + **NOTE THAT** this does not fully work yet, but it is in the API because I + hope that it will work later!" + [prompt] + (let [eddie (get-reader)] + (loop [s (.readLine eddie (str prompt " "))] + (if (and (= (count (re-seq #"\(" s)) + (count (re-seq #"\)" s))) + (= (count (re-seq #"\[]" s)) + (count (re-seq #"\]" s)))) + s + (recur (str s " " (.readLine eddie ":: "))))))) From 26e8c42ba4de185684c33b301a768946d6d29d32 Mon Sep 17 00:00:00 2001 From: Simon Brooke Date: Tue, 11 Apr 2023 12:11:28 +0100 Subject: [PATCH 2/4] Close #6: Done --- docs/cloverage/beowulf/bootstrap.clj.html | 14 +- docs/cloverage/beowulf/cons_cell.clj.html | 12 +- docs/cloverage/beowulf/core.clj.html | 46 +- docs/cloverage/beowulf/host.clj.html | 1313 +++++++++-------- docs/cloverage/beowulf/io.clj.html | 4 +- docs/cloverage/beowulf/oblist.clj.html | 4 +- docs/cloverage/beowulf/read.clj.html | 296 ++-- .../beowulf/reader/char_reader.clj.html | 208 ++- docs/cloverage/index.html | 136 +- resources/lisp1.5.lsp | 1 + src/beowulf/core.clj | 3 +- src/beowulf/host.clj | 81 +- src/beowulf/oblist.clj | 2 +- src/beowulf/read.clj | 26 +- test/beowulf/core_test.clj | 207 +-- test/beowulf/host_test.clj | 23 +- test/beowulf/lisp_test.clj | 50 +- 17 files changed, 1321 insertions(+), 1105 deletions(-) diff --git a/docs/cloverage/beowulf/bootstrap.clj.html b/docs/cloverage/beowulf/bootstrap.clj.html index c45387d..8a1fa87 100644 --- a/docs/cloverage/beowulf/bootstrap.clj.html +++ b/docs/cloverage/beowulf/bootstrap.clj.html @@ -331,13 +331,13 @@ 109                                   ;; else
            - + 110                                  (beowulf.bootstrap/EVAL expr
            - + 111                                                          (merge-vars vars env)
            - + 112                                                          depth))))
            @@ -352,13 +352,13 @@ 116     
            - + 117     Lisp 1.5 introduced `PROG`, and most Lisps have been stuck with it ever 
            - + 118     since. It introduces imperative programming into what should be a pure 
            - + 119     functional language, and consequently it's going to be a pig to implement.
            @@ -757,7 +757,7 @@ 251    (let [lisp-fn (value function-symbol '(EXPR FEXPR))
            - + 252          args' (cond (= NIL args) args
            diff --git a/docs/cloverage/beowulf/cons_cell.clj.html b/docs/cloverage/beowulf/cons_cell.clj.html index a229691..aaf1230 100644 --- a/docs/cloverage/beowulf/cons_cell.clj.html +++ b/docs/cloverage/beowulf/cons_cell.clj.html @@ -259,7 +259,7 @@ 085      (if
            - + 086       (or
            @@ -445,22 +445,22 @@ 147    clojure.lang.Counted
            - + 148    (count [this] (loop [cell this
            149                         result 1]
            - + 150                    (if
            - + 151                     (and (coll? (.getCdr cell)) (not= NIL (.getCdr cell)))
            - + 152                      (recur (.getCdr cell) (inc result))
            - + 153                      result)))
            diff --git a/docs/cloverage/beowulf/core.clj.html b/docs/cloverage/beowulf/core.clj.html index 209aa59..adf35d5 100644 --- a/docs/cloverage/beowulf/core.clj.html +++ b/docs/cloverage/beowulf/core.clj.html @@ -154,10 +154,10 @@ 050      :default default-sysout
            - + 051      :validate [#(and
            - + 052                   (.exists (io/file %))
            @@ -170,40 +170,40 @@ 055     ["-s" "--strict" "Strictly interpret the Lisp 1.5 language, without extensions."]
            - 056     ["-t" "--time" "Time evaluations."]]) + 056     ["-t" "--time" "Time evaluations."] +
            + + 057     ["-x" "--testing" "Disable the jline reader - useful when piping input."]])
            - 057   + 058  
            - 058  (defn- re  + 059  (defn- re 
            - 059    "Like REPL, but it isn't a loop and doesn't print." + 060    "Like REPL, but it isn't a loop and doesn't print."
            - 060    [input] + 061    [input]
            - 061    (EVAL (READ input) NIL 0)) + 062    (EVAL (READ input) NIL 0))
            - 062   + 063  
            - 063  (defn repl + 064  (defn repl
            - 064    "Read/eval/print loop." + 065    "Read/eval/print loop."
            - 065    [prompt] + 066    [prompt]
            - 066    (loop [] -
            - - 067      (print prompt) + 067    (loop [] 
            068      (flush) @@ -211,8 +211,8 @@ 069      (try
            - - 070        (if-let [input (trim (read-from-console))] + + 070        (if-let [input (trim (read-from-console prompt))]
            071          (if (= input stop-word) @@ -259,7 +259,7 @@ 085             data
            - + 086              (case (:cause data)
            @@ -316,13 +316,13 @@ 104          (str "Síðe " (System/getProperty "beowulf.version") "\n"))
            - + 105        (when
            106         (:help (:options args))
            - + 107          (:summary args))
            @@ -358,8 +358,8 @@ 118        (try
            - - 119          (repl (str (:prompt (:options args)) " ")) + + 119          (repl (:prompt (:options args)))
            120          (catch diff --git a/docs/cloverage/beowulf/host.clj.html b/docs/cloverage/beowulf/host.clj.html index 5a4bbed..6437d2b 100644 --- a/docs/cloverage/beowulf/host.clj.html +++ b/docs/cloverage/beowulf/host.clj.html @@ -274,7 +274,7 @@ 090    [l path]
            - + 091    (cond
            @@ -283,1439 +283,1490 @@ 093      (empty? path) l
            - - 094      :else + + 094      (not (instance? ConsCell l)) (throw (ex-info (str "Ne liste: "
            - - 095      (try + + 095                                                        l "; " (type l)) +
            + + 096                                                   {:phase :eval +
            + + 097                                                    :function "universal access function" +
            + + 098                                                    :args [l path] +
            + + 099                                                    :type :beowulf}))
            - 096        (case (last path) + 100      :else (case (last path)
            - 097          \a (uaf (.first l) (butlast path)) + 101              \a (uaf (.first l) (butlast path))
            - 098          \d (uaf (.getCdr l) (butlast path)) -
            - - 099          (throw (ex-info (str "uaf: unexpected letter in path (only `a` and `d` permitted): " (last path)) + 102              \d (uaf (.getCdr l) (butlast path))
            - 100                          {:cause  :uaf -
            - - 101                           :detail :unexpected-letter + 103              (throw (ex-info (str "uaf: unexpected letter in path (only `a` and `d` permitted): "
            - 102                           :expr   (last path)}))) + 104                                   (last path)) +
            + + 105                              {:phase :eval
            - 103        (catch ClassCastException e + 106                               :function "universal access function"
            - 104          (throw (ex-info -
            - - 105                  (str "uaf: Not a LISP list? " (type l)) -
            - - 106                  {:cause  :uaf + 107                               :args [l path]
            - 107                   :detail :not-a-lisp-list -
            - - 108                   :expr   l} -
            - - 109                  e)))))) + 108                               :type :beowulf})))))
            - 110   + 109  
            - 111  (defmacro CAAR [x] `(uaf ~x '(\a \a))) + 110  (defmacro CAAR [x] `(uaf ~x '(\a \a)))
            - 112  (defmacro CADR [x] `(uaf ~x '(\a \d))) + 111  (defmacro CADR [x] `(uaf ~x '(\a \d)))
            - - 113  (defmacro CDDR [x] `(uaf ~x '(\d \d))) + + 112  (defmacro CDDR [x] `(uaf ~x '(\d \d)))
            - 114  (defmacro CDAR [x] `(uaf ~x '(\d \a))) + 113  (defmacro CDAR [x] `(uaf ~x '(\d \a)))
            - 115   + 114  
            - 116  (defmacro CAAAR [x] `(uaf ~x '(\a \a \a))) + 115  (defmacro CAAAR [x] `(uaf ~x '(\a \a \a)))
            - 117  (defmacro CAADR [x] `(uaf ~x '(\a \a \d))) + 116  (defmacro CAADR [x] `(uaf ~x '(\a \a \d)))
            - 118  (defmacro CADAR [x] `(uaf ~x '(\a \d \a))) + 117  (defmacro CADAR [x] `(uaf ~x '(\a \d \a)))
            - 119  (defmacro CADDR [x] `(uaf ~x '(\a \d \d))) + 118  (defmacro CADDR [x] `(uaf ~x '(\a \d \d)))
            - 120  (defmacro CDDAR [x] `(uaf ~x '(\d \d \a))) + 119  (defmacro CDDAR [x] `(uaf ~x '(\d \d \a)))
            - 121  (defmacro CDDDR [x] `(uaf ~x '(\d \d \d))) + 120  (defmacro CDDDR [x] `(uaf ~x '(\d \d \d)))
            - 122  (defmacro CDAAR [x] `(uaf ~x '(\d \a \a))) + 121  (defmacro CDAAR [x] `(uaf ~x '(\d \a \a)))
            - 123  (defmacro CDADR [x] `(uaf ~x '(\d \a \d))) + 122  (defmacro CDADR [x] `(uaf ~x '(\d \a \d)))
            - 124   + 123  
            - 125  (defmacro CAAAAR [x] `(uaf ~x '(\a \a \a \a))) + 124  (defmacro CAAAAR [x] `(uaf ~x '(\a \a \a \a)))
            - 126  (defmacro CAADAR [x] `(uaf ~x '(\a \a \d \a))) + 125  (defmacro CAADAR [x] `(uaf ~x '(\a \a \d \a)))
            - 127  (defmacro CADAAR [x] `(uaf ~x '(\a \d \a \a))) + 126  (defmacro CADAAR [x] `(uaf ~x '(\a \d \a \a)))
            - 128  (defmacro CADDAR [x] `(uaf ~x '(\a \d \d \a))) + 127  (defmacro CADDAR [x] `(uaf ~x '(\a \d \d \a)))
            - 129  (defmacro CDDAAR [x] `(uaf ~x '(\d \d \a \a))) + 128  (defmacro CDDAAR [x] `(uaf ~x '(\d \d \a \a)))
            - 130  (defmacro CDDDAR [x] `(uaf ~x '(\d \d \d \a))) + 129  (defmacro CDDDAR [x] `(uaf ~x '(\d \d \d \a)))
            - 131  (defmacro CDAAAR [x] `(uaf ~x '(\d \a \a \a))) + 130  (defmacro CDAAAR [x] `(uaf ~x '(\d \a \a \a)))
            - 132  (defmacro CDADAR [x] `(uaf ~x '(\d \a \d \a))) + 131  (defmacro CDADAR [x] `(uaf ~x '(\d \a \d \a)))
            - 133  (defmacro CAAADR [x] `(uaf ~x '(\a \a \a \d))) + 132  (defmacro CAAADR [x] `(uaf ~x '(\a \a \a \d)))
            - 134  (defmacro CAADDR [x] `(uaf ~x '(\a \a \d \d))) + 133  (defmacro CAADDR [x] `(uaf ~x '(\a \a \d \d)))
            - 135  (defmacro CADADR [x] `(uaf ~x '(\a \d \a \d))) + 134  (defmacro CADADR [x] `(uaf ~x '(\a \d \a \d)))
            - 136  (defmacro CADDDR [x] `(uaf ~x '(\a \d \d \d))) + 135  (defmacro CADDDR [x] `(uaf ~x '(\a \d \d \d)))
            - 137  (defmacro CDDADR [x] `(uaf ~x '(\d \d \a \d))) + 136  (defmacro CDDADR [x] `(uaf ~x '(\d \d \a \d)))
            - 138  (defmacro CDDDDR [x] `(uaf ~x '(\d \d \d \d))) + 137  (defmacro CDDDDR [x] `(uaf ~x '(\d \d \d \d)))
            - 139  (defmacro CDAADR [x] `(uaf ~x '(\d \a \a \d))) + 138  (defmacro CDAADR [x] `(uaf ~x '(\d \a \a \d)))
            - 140  (defmacro CDADDR [x] `(uaf ~x '(\d \a \d \d))) + 139  (defmacro CDADDR [x] `(uaf ~x '(\d \a \d \d)))
            - 141   + 140  
            - 142  (defn RPLACA + 141  (defn RPLACA
            - 143    "Replace the CAR pointer of this `cell` with this `value`. Dangerous, should + 142    "Replace the CAR pointer of this `cell` with this `value`. Dangerous, should
            - 144    really not exist, but does in Lisp 1.5 (and was important for some + 143    really not exist, but does in Lisp 1.5 (and was important for some
            - 145    performance hacks in early Lisps)" + 144    performance hacks in early Lisps)"
            - 146    [^ConsCell cell value] + 145    [^ConsCell cell value]
            - 147    (if + 146    (if
            - 148     (instance? ConsCell cell) + 147     (instance? ConsCell cell)
            - 149      (if + 148      (if
            - 150       (or + 149       (or
            - 151        (instance? ConsCell value) + 150        (instance? ConsCell value)
            - 152        (number? value) + 151        (number? value)
            - 153        (symbol? value) + 152        (symbol? value)
            - 154        (= value NIL)) + 153        (= value NIL))
            - 155        (try + 154        (try
            - 156          (.rplaca cell value) + 155          (.rplaca cell value)
            - 157          cell + 156          cell
            - 158          (catch Throwable any + 157          (catch Throwable any
            - 159            (throw (ex-info + 158            (throw (ex-info
            - 160                    (str (.getMessage any) " in RPLACA: `") + 159                    (str (.getMessage any) " in RPLACA: `")
            - 161                    {:cause :upstream-error + 160                    {:cause :upstream-error
            - 162                     :phase :host + 161                     :phase :host
            - 163                     :function :rplaca + 162                     :function :rplaca
            - 164                     :args (list cell value) + 163                     :args (list cell value)
            - 165                     :type :beowulf} + 164                     :type :beowulf}
            - 166                    any)))) + 165                    any))))
            - 167        (throw (ex-info + 166        (throw (ex-info
            - 168                (str "Un-ġefōg þing in RPLACA: `" value "` (" (type value) ")") + 167                (str "Un-ġefōg þing in RPLACA: `" value "` (" (type value) ")")
            - 169                {:cause :bad-value + 168                {:cause :bad-value
            - 170                 :phase :host + 169                 :phase :host
            - 171                 :function :rplaca + 170                 :function :rplaca
            - 172                 :args (list cell value) + 171                 :args (list cell value)
            - 173                 :type :beowulf}))) + 172                 :type :beowulf})))
            - 174      (throw (ex-info + 173      (throw (ex-info
            - 175              (str "Uncynlic miercels in RPLACA: `" cell "` (" (type cell) ")") + 174              (str "Uncynlic miercels in RPLACA: `" cell "` (" (type cell) ")")
            - 176              {:cause :bad-cell + 175              {:cause :bad-cell
            - 177               :phase :host + 176               :phase :host
            - 178               :function :rplaca + 177               :function :rplaca
            - 179               :args (list cell value) + 178               :args (list cell value)
            - 180               :type :beowulf})))) + 179               :type :beowulf}))))
            - 181   + 180  
            - 182  (defn RPLACD + 181  (defn RPLACD
            - 183    "Replace the CDR pointer of this `cell` with this `value`. Dangerous, should + 182    "Replace the CDR pointer of this `cell` with this `value`. Dangerous, should
            - 184    really not exist, but does in Lisp 1.5 (and was important for some + 183    really not exist, but does in Lisp 1.5 (and was important for some
            - 185    performance hacks in early Lisps)" + 184    performance hacks in early Lisps)"
            - 186    [^ConsCell cell value] + 185    [^ConsCell cell value]
            - 187    (if + 186    (if
            - 188     (instance? ConsCell cell) + 187     (instance? ConsCell cell)
            - 189      (if + 188      (if
            - - 190       (or + + 189       (or
            - 191        (instance? ConsCell value) + 190        (instance? ConsCell value)
            - 192        (number? value) + 191        (number? value)
            - 193        (symbol? value) + 192        (symbol? value)
            - 194        (= value NIL)) + 193        (= value NIL))
            - 195        (try + 194        (try
            - 196          (.rplacd cell value) + 195          (.rplacd cell value)
            - 197          cell + 196          cell
            - 198          (catch Throwable any + 197          (catch Throwable any
            - 199            (throw (ex-info + 198            (throw (ex-info
            - 200                    (str (.getMessage any) " in RPLACD: `") + 199                    (str (.getMessage any) " in RPLACD: `")
            - 201                    {:cause :upstream-error + 200                    {:cause :upstream-error
            - 202                     :phase :host + 201                     :phase :host
            - 203                     :function :rplacd + 202                     :function :rplacd
            - 204                     :args (list cell value) + 203                     :args (list cell value)
            - 205                     :type :beowulf} + 204                     :type :beowulf}
            - 206                    any)))) + 205                    any))))
            - 207        (throw (ex-info + 206        (throw (ex-info
            - 208                (str "Un-ġefōg þing in RPLACD: `" value "` (" (type value) ")") + 207                (str "Un-ġefōg þing in RPLACD: `" value "` (" (type value) ")")
            - 209                {:cause :bad-value + 208                {:cause :bad-value
            - 210                 :phase :host + 209                 :phase :host
            - 211                 :function :rplacd + 210                 :function :rplacd
            - 212                 :args (list cell value) + 211                 :args (list cell value)
            - 213                 :type :beowulf}))) + 212                 :type :beowulf})))
            - 214      (throw (ex-info + 213      (throw (ex-info
            - 215              (str "Uncynlic miercels in RPLACD: `" cell "` (" (type cell) ")") + 214              (str "Uncynlic miercels in RPLACD: `" cell "` (" (type cell) ")")
            - 216              {:cause :bad-cell + 215              {:cause :bad-cell
            - 217               :phase :host + 216               :phase :host
            - 218               :detail :rplacd + 217               :detail :rplacd
            - 219               :args (list cell value) + 218               :args (list cell value)
            - 220               :type :beowulf}))));; PLUS + 219               :type :beowulf}))));; PLUS
            - 221   + 220  
            - 222  (defn LIST + 221  (defn LIST
            - 223    [& args] + 222    [& args]
            - 224    (make-beowulf-list args)) + 223    (make-beowulf-list args))
            - 225   + 224  
            - 226  ;;;; Basic predicates ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 225  ;;;; Basic predicates ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 227   + 226  
            - 228  (defmacro NULL + 227  (defmacro NULL
            - 229    "Returns `T` if and only if the argument `x` is bound to `NIL`; else `F`." + 228    "Returns `T` if and only if the argument `x` is bound to `NIL`; else `F`."
            - 230    [x] + 229    [x]
            - 231    `(if (= ~x NIL) T F)) + 230    `(if (= ~x NIL) T F))
            - 232   + 231  
            - 233  (defmacro NILP + 232  (defmacro NILP
            - 234    "Not part of LISP 1.5: `T` if `o` is `NIL`, else `NIL`." + 233    "Not part of LISP 1.5: `T` if `o` is `NIL`, else `NIL`."
            - 235    [x] + 234    [x]
            - 236    `(if (= ~x NIL) T NIL)) + 235    `(if (= ~x NIL) T NIL))
            - 237   + 236  
            - 238  (defn ATOM + 237  (defn ATOM
            - 239    "Returns `T` if and only if the argument `x` is bound to an atom; else `F`. + 238    "Returns `T` if and only if the argument `x` is bound to an atom; else `F`.
            - 240    It is not clear to me from the documentation whether `(ATOM 7)` should return + 239    It is not clear to me from the documentation whether `(ATOM 7)` should return
            - 241    `T` or `F`. I'm going to assume `T`." + 240    `T` or `F`. I'm going to assume `T`."
            - 242    [x] + 241    [x]
            - 243    (if (or (symbol? x) (number? x)) T F)) + 242    (if (or (symbol? x) (number? x)) T F))
            - 244   + 243  
            - 245  (defmacro ATOM? + 244  (defmacro ATOM?
            - 246    "The convention of returning `F` from predicates, rather than `NIL`, is going + 245    "The convention of returning `F` from predicates, rather than `NIL`, is going
            - 247    to tie me in knots. This is a variant of `ATOM` which returns `NIL` + 246    to tie me in knots. This is a variant of `ATOM` which returns `NIL`
            - 248    on failure." + 247    on failure."
            - 249    [x] + 248    [x]
            - 250    `(if (or (symbol? ~x) (number? ~x)) T NIL)) + 249    `(if (or (symbol? ~x) (number? ~x)) T NIL))
            - 251   + 250  
            - 252  (defn EQ + 251  (defn EQ
            - 253    "Returns `T` if and only if both `x` and `y` are bound to the same atom, + 252    "Returns `T` if and only if both `x` and `y` are bound to the same atom,
            - 254    else `NIL`." + 253    else `NIL`."
            - 255    [x y] + 254    [x y]
            - 256    (cond (and (instance? ConsCell x) + 255    (cond (and (instance? ConsCell x)
            - 257               (.equals x y)) T + 256               (.equals x y)) T
            - 258          (and (= (ATOM x) T) (= x y)) T + 257          (and (= (ATOM x) T) (= x y)) T
            - 259          :else NIL)) + 258          :else NIL))
            - 260   + 259  
            - 261  (defn EQUAL + 260  (defn EQUAL
            - 262    "This is a predicate that is true if its two arguments are identical + 261    "This is a predicate that is true if its two arguments are identical
            - 263    S-expressions, and false if they are different. (The elementary predicate + 262    S-expressions, and false if they are different. (The elementary predicate
            - 264    `EQ` is defined only for atomic arguments.) The definition of `EQUAL` is + 263    `EQ` is defined only for atomic arguments.) The definition of `EQUAL` is
            - 265    an example of a conditional expression inside a conditional expression. + 264    an example of a conditional expression inside a conditional expression.
            - 266   + 265  
            - 267    NOTE: returns `F` on failure, not `NIL`" + 266    NOTE: returns `F` on failure, not `NIL`"
            - 268    [x y] + 267    [x y]
            - 269    (cond + 268    (cond
            - 270      (= (ATOM x) T) (if (= x y) T F) + 269      (= (ATOM x) T) (if (= x y) T F)
            - 271      (= (EQUAL (CAR x) (CAR y)) T) (EQUAL (CDR x) (CDR y)) + 270      (= (EQUAL (CAR x) (CAR y)) T) (EQUAL (CDR x) (CDR y))
            - 272      :else F)) + 271      :else F))
            - 273   + 272  
            - 274  (defn AND + 273  (defn AND
            - 275    "`T` if and only if none of my `args` evaluate to either `F` or `NIL`, + 274    "`T` if and only if none of my `args` evaluate to either `F` or `NIL`,
            - 276     else `F`. + 275     else `F`.
            - 277      + 276     
            - 278     In `beowulf.host` principally because I don't yet feel confident to define + 277     In `beowulf.host` principally because I don't yet feel confident to define
            - 279     varargs functions in Lisp." + 278     varargs functions in Lisp."
            - 280    [& args] + 279    [& args]
            - 281    ;; (println "AND: " args " type: " (type args) " seq? " (seq? args)) + 280    ;; (println "AND: " args " type: " (type args) " seq? " (seq? args))
            - 282    ;; (println "  filtered: " (seq (filter #{F NIL} args))) + 281    ;; (println "  filtered: " (seq (filter #{F NIL} args)))
            - 283    (cond (= NIL args) T + 282    (cond (= NIL args) T
            - 284          (seq? args) (if (seq (filter #{F NIL} args)) F T) + 283          (seq? args) (if (seq (filter #{F NIL} args)) F T)
            - 285          :else T)) + 284          :else T)) +
            + + 285  
            286  
            - - 287   -
            - 288  (defn OR + 287  (defn OR
            - 289    "`T` if and only if at least one of my `args` evaluates to something other + 288    "`T` if and only if at least one of my `args` evaluates to something other
            - 290    than either `F` or `NIL`, else `F`. + 289    than either `F` or `NIL`, else `F`.
            - 291      + 290     
            - 292     In `beowulf.host` principally because I don't yet feel confident to define + 291     In `beowulf.host` principally because I don't yet feel confident to define
            - 293     varargs functions in Lisp." + 292     varargs functions in Lisp."
            - 294    [& args] + 293    [& args]
            - 295    ;; (println "OR: " args " type: " (type args) " seq? " (seq? args)) + 294    ;; (println "OR: " args " type: " (type args) " seq? " (seq? args))
            - 296    ;; (println "  filtered: " (seq (remove #{F NIL} args))) + 295    ;; (println "  filtered: " (seq (remove #{F NIL} args)))
            - 297    (cond (= NIL args) F + 296    (cond (= NIL args) F
            - 298          (seq? args) (if (seq (remove #{F NIL} args)) T F) + 297          (seq? args) (if (seq (remove #{F NIL} args)) T F)
            - 299          :else F)) + 298          :else F)) +
            + + 299  
            300  
            - - 301   + + 301  ;;;; Operations on lists ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 302  ;;;; Operations on lists ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 302  ;;
            - 303  ;; -
            - - 304  ;; TODO: These are candidates for moving to Lisp urgently! + 303  ;; TODO: These are candidates for moving to Lisp urgently!
            - 305   + 304  
            - 306  (defn ASSOC + 305  (defn ASSOC
            - 307    "If a is an association list such as the one formed by PAIRLIS in the above + 306    "If a is an association list such as the one formed by PAIRLIS in the above
            - 308    example, then assoc will produce the first pair whose first term is x. Thus + 307    example, then assoc will produce the first pair whose first term is x. Thus
            - 309    it is a table searching function. + 308    it is a table searching function.
            - 310   + 309  
            - 311    All args are assumed to be `beowulf.cons-cell/ConsCell` objects. + 310    All args are assumed to be `beowulf.cons-cell/ConsCell` objects.
            - 312    See page 12 of the Lisp 1.5 Programmers Manual. + 311    See page 12 of the Lisp 1.5 Programmers Manual.
            - 313      + 312     
            - 314     **NOTE THAT** this function is overridden by an implementation in Lisp, + 313     **NOTE THAT** this function is overridden by an implementation in Lisp,
            - 315     but is currently still present for bootstrapping." + 314     but is currently still present for bootstrapping."
            - 316    [x a] + 315    [x a]
            - 317    (cond + 316    (cond
            - 318      (= NIL a) NIL ;; this clause is not present in the original but is added for + 317      (= NIL a) NIL ;; this clause is not present in the original but is added for
            - 319      ;; robustness. + 318      ;; robustness.
            - 320      (= (EQUAL (CAAR a) x) T) (CAR a) + 319      (= (EQUAL (CAAR a) x) T) (CAR a)
            - 321      :else + 320      :else
            - 322      (ASSOC x (CDR a)))) + 321      (ASSOC x (CDR a))))
            - 323   + 322  
            - 324  (defn PAIRLIS + 323  (defn PAIRLIS
            - 325    "This function gives the list of pairs of corresponding elements of the + 324    "This function gives the list of pairs of corresponding elements of the
            - 326    lists `x` and `y`, and APPENDs this to the list `a`. The resultant list + 325    lists `x` and `y`, and APPENDs this to the list `a`. The resultant list
            - 327    of pairs, which is like a table with two columns, is called an + 326    of pairs, which is like a table with two columns, is called an
            - 328    association list. + 327    association list.
            - 329   + 328  
            - 330    Eessentially, it builds the environment on the stack, implementing shallow + 329    Eessentially, it builds the environment on the stack, implementing shallow
            - 331    binding. + 330    binding.
            - 332   + 331  
            - 333    All args are assumed to be `beowulf.cons-cell/ConsCell` objects. + 332    All args are assumed to be `beowulf.cons-cell/ConsCell` objects.
            - 334    See page 12 of the Lisp 1.5 Programmers Manual. + 333    See page 12 of the Lisp 1.5 Programmers Manual.
            - 335      + 334     
            - 336     **NOTE THAT** this function is overridden by an implementation in Lisp, + 335     **NOTE THAT** this function is overridden by an implementation in Lisp,
            - 337     but is currently still present for bootstrapping." + 336     but is currently still present for bootstrapping."
            - 338    [x y a] + 337    [x y a]
            - 339    (cond + 338    (cond
            - 340      ;; the original tests only x; testing y as well will be a little more + 339      ;; the original tests only x; testing y as well will be a little more
            - 341      ;; robust if `x` and `y` are not the same length. + 340      ;; robust if `x` and `y` are not the same length.
            - 342      (or (= NIL x) (= NIL y)) a + 341      (or (= NIL x) (= NIL y)) a
            - 343      :else (make-cons-cell + 342      :else (make-cons-cell
            - 344             (make-cons-cell (CAR x) (CAR y)) + 343             (make-cons-cell (CAR x) (CAR y))
            - 345             (PAIRLIS (CDR x) (CDR y) a)))) + 344             (PAIRLIS (CDR x) (CDR y) a))))
            - 346   + 345  
            - 347  ;;;; Arithmetic ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 346  ;;;; Arithmetic ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 348  ;; + 347  ;;
            - 349  ;; TODO: When in strict mode, should we limit arithmetic precision to that + 348  ;; TODO: When in strict mode, should we limit arithmetic precision to that
            - 350  ;; supported by Lisp 1.5? + 349  ;; supported by Lisp 1.5?
            - 351   + 350  
            - 352  (defn PLUS + 351  (defn PLUS
            - 353    [& args] + 352    [& args]
            - 354    (let [s (apply + args)] + 353    (let [s (apply + args)]
            - 355      (if (integer? s) s (float s)))) + 354      (if (integer? s) s (float s))))
            - 356   + 355  
            - 357  (defn TIMES + 356  (defn TIMES
            - 358    [& args] + 357    [& args]
            - 359    (let [p (apply * args)] + 358    (let [p (apply * args)]
            - 360      (if (integer? p) p (float p)))) + 359      (if (integer? p) p (float p))))
            - 361   + 360  
            - 362  (defn DIFFERENCE + 361  (defn DIFFERENCE
            - 363    [x y] + 362    [x y]
            - 364    (let [d (- x y)] + 363    (let [d (- x y)]
            - 365      (if (integer? d) d (float d)))) + 364      (if (integer? d) d (float d))))
            - 366   + 365  
            - 367  (defn QUOTIENT + 366  (defn QUOTIENT
            - 368    "I'm not certain from the documentation whether Lisp 1.5 `QUOTIENT` returned + 367    "I'm not certain from the documentation whether Lisp 1.5 `QUOTIENT` returned
            - 369    the integer part of the quotient, or a realnum representing the whole + 368    the integer part of the quotient, or a realnum representing the whole
            - 370    quotient. I am for now implementing the latter." + 369    quotient. I am for now implementing the latter."
            - 371    [x y] + 370    [x y]
            - 372    (let [q (/ x y)] + 371    (let [q (/ x y)]
            - 373      (if (integer? q) q (float q)))) + 372      (if (integer? q) q (float q))))
            - 374   + 373  
            - 375  (defn REMAINDER + 374  (defn REMAINDER
            - 376    [x y] + 375    [x y]
            - 377    (rem x y)) + 376    (rem x y))
            - 378   + 377  
            - 379  (defn ADD1 + 378  (defn ADD1
            - 380    [x] + 379    [x]
            - 381    (inc x)) + 380    (inc x))
            - 382   + 381  
            - 383  (defn SUB1 + 382  (defn SUB1
            - 384    [x] + 383    [x]
            - 385    (dec x)) + 384    (dec x))
            - 386   + 385  
            - 387  (defn FIXP + 386  (defn FIXP
            - 388    [x] + 387    [x]
            - 389    (if (integer? x) T F)) + 388    (if (integer? x) T F))
            - 390   + 389  
            - 391  (defn NUMBERP + 390  (defn NUMBERP
            - 392    [x] + 391    [x]
            - 393    (if (number? x) T F)) + 392    (if (number? x) T F))
            - 394   + 393  
            - 395  (defn LESSP + 394  (defn LESSP
            - 396    [x y] + 395    [x y]
            - 397    (if (< x y) T F)) + 396    (if (< x y) T F))
            - 398   + 397  
            - 399  (defn GREATERP + 398  (defn GREATERP
            - 400    [x y] + 399    [x y]
            - 401    (if (> x y) T F)) + 400    (if (> x y) T F))
            - 402   + 401  
            - 403  ;;;; Miscellaneous ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 402  ;;;; Miscellaneous ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 404   + 403  
            - 405  (defn GENSYM + 404  (defn GENSYM
            - 406    "Generate a unique symbol." + 405    "Generate a unique symbol."
            - 407    [] + 406    []
            - - 408    (symbol (upper-case (str (gensym "SYM"))))) + + 407    (symbol (upper-case (str (gensym "SYM")))))
            - 409   + 408  
            - 410  (defn ERROR + 409  (defn ERROR
            - 411    "Throw an error" + 410    "Throw an error"
            - 412    [& args] + 411    [& args]
            - 413    (throw (ex-info "LISP STÆFLEAHTER" {:args args + 412    (throw (ex-info "LISP STÆFLEAHTER" {:args args
            - 414                                        :phase :eval + 413                                        :phase :eval
            - 415                                        :function 'ERROR + 414                                        :function 'ERROR
            - 416                                        :type :lisp + 415                                        :type :lisp
            - 417                                        :code (or (first args) 'A1)}))) + 416                                        :code (or (first args) 'A1)})))
            - 418   + 417  
            - 419  ;;;; Assignment and the object list ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 418  ;;;; Assignment and the object list ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 420   + 419  
            - 421  (defn OBLIST + 420  (defn OBLIST
            - 422    "Return a list of the symbols currently bound on the object list. + 421    "Return a list of the symbols currently bound on the object list.
            - 423      + 422     
            - 424     **NOTE THAT** in the Lisp 1.5 manual, footnote at the bottom of page 69, it implies  + 423     **NOTE THAT** in the Lisp 1.5 manual, footnote at the bottom of page 69, it implies 
            - 425     that an argument can be passed but I'm not sure of the semantics of + 424     that an argument can be passed but I'm not sure of the semantics of
            - 426     this." + 425     this."
            - 427    [] + 426    []
            - 428    (if (instance? ConsCell @oblist) + 427    (if (instance? ConsCell @oblist)
            - 429      (make-beowulf-list (map CAR @oblist)) + 428      (make-beowulf-list (map CAR @oblist))
            - 430      NIL)) + 429      NIL))
            - 431   + 430  
            - 432  (def magic-marker + 431  (def magic-marker
            - 433    "The unexplained magic number which marks the start of a property list." + 432    "The unexplained magic number which marks the start of a property list."
            - 434    (Integer/parseInt "77777" 8)) + 433    (Integer/parseInt "77777" 8))
            - 435   + 434  
            - 436  (defn PUT + 435  (defn hit-or-miss-assoc
            - 437    "Put this `value` as the value of the property indicated by this `indicator`  + 436    "Find the position of the binding of this `target` in a Lisp 1.5 
            - 438     of this `symbol`. Return `value` on success. + 437     property list `plist`.
            - 439      + 438     
            - 440     NOTE THAT there is no `PUT` defined in the manual, but it would have been  + 439     Lisp 1.5 property lists are not assoc lists, but lists of the form
            - 441     easy to have defined it so I don't think this fully counts as an extension." + 440     `(name value name value name value...)`. It's therefore necessary to
            - 442    [symbol indicator value] -
            - - 443    (if-let [binding (ASSOC symbol @oblist)] -
            - - 444      (if-let [prop (ASSOC indicator (CDDR binding))] -
            - - 445        (RPLACD prop value) -
            - - 446        (RPLACD binding -
            - - 447                (make-cons-cell -
            - - 448                 magic-marker -
            - - 449                 (make-cons-cell -
            - - 450                  indicator -
            - - 451                  (make-cons-cell value (CDDR binding)))))) -
            - - 452      (swap! -
            - - 453       oblist -
            - - 454       (fn [ob s p v] -
            - - 455         (make-cons-cell -
            - - 456          (make-beowulf-list (list s magic-marker p v)) -
            - - 457          ob)) -
            - - 458       symbol indicator value))) -
            - - 459   -
            - - 460  (defn GET + 441     recurse down the list two entries at a time to avoid confusing names
            - 461    "From the manual: + 442     with values."
            - 462      + 443    [target plist]
            - - 463     '`get` is somewhat like `prop`; however its value is car of the rest of + + 444    (if (and (instance? ConsCell plist)(even? (count plist)))
            - - 464     the list if the `indicator` is found, and NIL otherwise.' -
            - - 465      -
            - - 466     It's clear that `GET` is expected to be defined in terms of `PROP`, but -
            - - 467     we can't implement `PROP` here because we lack `EVAL`; and we can't have -
            - - 468     `EVAL` here because both it and `APPLY` depends on `GET`. -
            - - 469      -
            - - 470     OK, It's worse than that: the statement of the definition of `GET` (and  -
            - - 471     of) `PROP` on page 59 says that the first argument to each must be a list; -
            - - 472     But the in the definition of `ASSOC` on page 70, when `GET` is called its -
            - - 473     first argument is always an atom. Since it's `ASSOC` and `EVAL` which I  -
            - - 474     need to make work, I'm going to assume that page 59 is wrong." -
            - - 475    [symbol indicator] -
            - - 476    (let [binding (ASSOC symbol @oblist) -
            - - 477          val (cond -
            - - 478                (= binding NIL) NIL -
            - - 479                (= magic-marker -
            - - 480                   (CADR binding)) (loop [b binding] -
            - - 481                                    ;;  (println "GET loop, seeking " indicator ":") -
            - - 482                                    ;;  (pretty-print b) -
            - - 483                                     (if (instance? ConsCell b) + + 445      (cond (= plist NIL) NIL
            - 484                                       (if (= (CAR b) indicator) + 446            (= (first plist) target) plist +
            + + 447            :else (hit-or-miss-assoc target (CDDR plist))) +
            + + 448      NIL)) +
            + + 449   +
            + + 450  (defn PUT +
            + + 451    "Put this `value` as the value of the property indicated by this `indicator`  +
            + + 452     of this `symbol`. Return `value` on success. +
            + + 453      +
            + + 454     NOTE THAT there is no `PUT` defined in the manual, but it would have been  +
            + + 455     easy to have defined it so I don't think this fully counts as an extension." +
            + + 456    [symbol indicator value] +
            + + 457    (let [binding (ASSOC symbol @oblist)] +
            + + 458      (if (instance? ConsCell binding) +
            + + 459        (let [prop (hit-or-miss-assoc indicator (CDDR binding))] +
            + + 460          (if (instance? ConsCell prop) +
            + + 461            (RPLACA (CDR prop) value)
            - 485                                         (CADR b) ;; <- this is what we should actually be returning + 462            (RPLACD binding +
            + + 463                    (make-cons-cell
            - 486                                         (recur (CDR b))) + 464                     magic-marker +
            + + 465                     (make-cons-cell
            - 487                                       NIL)) + 466                      indicator +
            + + 467                      (make-cons-cell value (CDDR binding))))))) +
            + + 468        (swap! +
            + + 469         oblist +
            + + 470         (fn [ob s p v] +
            + + 471           (make-cons-cell +
            + + 472            (make-beowulf-list (list s magic-marker p v)) +
            + + 473            ob)) +
            + + 474         symbol indicator value))) +
            + + 475    value) +
            + + 476   +
            + + 477  (defn GET +
            + + 478    "From the manual: +
            + + 479      +
            + + 480     '`get` is somewhat like `prop`; however its value is car of the rest of +
            + + 481     the list if the `indicator` is found, and NIL otherwise.' +
            + + 482      +
            + + 483     It's clear that `GET` is expected to be defined in terms of `PROP`, but +
            + + 484     we can't implement `PROP` here because we lack `EVAL`; and we can't have +
            + + 485     `EVAL` here because both it and `APPLY` depends on `GET`. +
            + + 486      +
            + + 487     OK, It's worse than that: the statement of the definition of `GET` (and  +
            + + 488     of) `PROP` on page 59 says that the first argument to each must be a list; +
            + + 489     But the in the definition of `ASSOC` on page 70, when `GET` is called its +
            + + 490     first argument is always an atom. Since it's `ASSOC` and `EVAL` which I  +
            + + 491     need to make work, I'm going to assume that page 59 is wrong." +
            + + 492    [symbol indicator] +
            + + 493    (let [binding (ASSOC symbol @oblist) +
            + + 494          val (cond +
            + + 495                (= binding NIL) NIL +
            + + 496                (= magic-marker +
            + + 497                   (CADR binding)) (loop [b binding] +
            + + 498                                    ;;  (println "GET loop, seeking " indicator ":") +
            + + 499                                    ;;  (pretty-print b) +
            + + 500                                     (if (instance? ConsCell b) +
            + + 501                                       (if (= (CAR b) indicator) +
            + + 502                                         (CADR b) ;; <- this is what we should actually be returning +
            + + 503                                         (recur (CDR b))) +
            + + 504                                       NIL))
            - 488                :else (throw + 505                :else (throw
            - 489                       (ex-info "Misformatted property list (missing magic marker)" + 506                       (ex-info "Misformatted property list (missing magic marker)"
            - 490                                {:phase :host + 507                                {:phase :host
            - 491                                 :function :get + 508                                 :function :get
            - 492                                 :args (list symbol indicator) + 509                                 :args (list symbol indicator)
            - 493                                 :type :beowulf})))] + 510                                 :type :beowulf})))]
            - 494      ;; (println "<< GET returning: " val) + 511      ;; (println "<< GET returning: " val)
            - 495      val)) + 512      val))
            - 496   + 513  
            - 497  (defn DEFLIST + 514  (defn DEFLIST
            - 498    "For each pair in this association list `a-list`, set the property with this + 515    "For each pair in this association list `a-list`, set the property with this
            - 499     `indicator` of the symbol which is the first element of the pair to the  + 516     `indicator` of the symbol which is the first element of the pair to the 
            - 500     value which is the second element of the pair. See page 58 of the manual." + 517     value which is the second element of the pair. See page 58 of the manual."
            - 501    [a-list indicator] + 518    [a-list indicator]
            - 502    (map + 519    (map
            - 503     #(PUT (CAR %) indicator (CDR %)) + 520     #(PUT (CAR %) indicator (CDR %))
            - 504     a-list)) -
            - - 505   -
            - - 506  (defn DEFINE -
            - - 507    "Bootstrap-only version of `DEFINE` which, post boostrap, can be overwritten  -
            - - 508    in LISP.  -
            - - 509   -
            - - 510    The single argument to `DEFINE` should be an association list of symbols to -
            - - 511     lambda functions. See page 58 of the manual." -
            - - 512    [a-list] -
            - - 513    (DEFLIST a-list 'EXPR)) -
            - - 514   -
            - - 515  (defn SET -
            - - 516    "Implementation of SET in Clojure. Add to the `oblist` a binding of the -
            - - 517     value of `var` to the value of `val`. NOTE WELL: this is not SETQ!" -
            - - 518    [symbol val] -
            - - 519    (PUT symbol 'APVAL val)) -
            - - 520   -
            - - 521  ;;;; TRACE and friends ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 521     a-list))
            522  
            - 523  (def traced-symbols + 523  (defn DEFINE
            - 524    "Symbols currently being traced." + 524    "Bootstrap-only version of `DEFINE` which, post boostrap, can be overwritten 
            - - 525    (atom #{})) + + 525    in LISP. 
            526  
            - - 527  (defn traced? + + 527    The single argument to `DEFINE` should be an association list of symbols to
            - 528    "Return `true` iff `s` is a symbol currently being traced, else `nil`." + 528     lambda functions. See page 58 of the manual."
            - 529    [s] -
            - - 530    (try (contains? @traced-symbols s) -
            - - 531         (catch Throwable _ nil))) -
            - - 532   -
            - - 533  (defn TRACE -
            - - 534    "Add this `s` to the set of symbols currently being traced. If `s` -
            - - 535     is not a symbol or sequence of symbols, does nothing." -
            - - 536    [s] + 529    [a-list]
            - 537    (swap! traced-symbols -
            - - 538           #(cond -
            - - 539              (symbol? s) (conj % s) -
            - - 540              (and (seq? s) (every? symbol? s)) (union % (set s)) -
            - - 541              :else %))) + 530    (DEFLIST a-list 'EXPR))
            - 542   + 531  
            - - 543  (defn UNTRACE + + 532  (defn SET
            - 544    "Remove this `s` from the set of symbols currently being traced. If `s` + 533    "Implementation of SET in Clojure. Add to the `oblist` a binding of the
            - 545     is not a symbol or sequence of symbols, does nothing." + 534     value of `var` to the value of `val`. NOTE WELL: this is not SETQ!" +
            + + 535    [symbol val] +
            + + 536    (PUT symbol 'APVAL val)) +
            + + 537   +
            + + 538  ;;;; TRACE and friends ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +
            + + 539   +
            + + 540  (def traced-symbols +
            + + 541    "Symbols currently being traced." +
            + + 542    (atom #{})) +
            + + 543   +
            + + 544  (defn traced? +
            + + 545    "Return `true` iff `s` is a symbol currently being traced, else `nil`."
            546    [s]
            + + 547    (try (contains? @traced-symbols s) +
            + + 548         (catch Throwable _ nil))) +
            + + 549   +
            + + 550  (defn TRACE +
            + + 551    "Add this `s` to the set of symbols currently being traced. If `s` +
            + + 552     is not a symbol or sequence of symbols, does nothing." +
            + + 553    [s] +
            + + 554    (swap! traced-symbols +
            + + 555           #(cond +
            + + 556              (symbol? s) (conj % s) +
            + + 557              (and (seq? s) (every? symbol? s)) (union % (set s)) +
            + + 558              :else %))) +
            + + 559   +
            + + 560  (defn UNTRACE +
            + + 561    "Remove this `s` from the set of symbols currently being traced. If `s` +
            + + 562     is not a symbol or sequence of symbols, does nothing." +
            + + 563    [s] +
            - 547    (cond + 564    (cond
            - 548      (symbol? s) (swap! traced-symbols #(set (remove (fn [x] (= s x)) %))) + 565      (symbol? s) (swap! traced-symbols #(set (remove (fn [x] (= s x)) %)))
            - 549      (and (seq? s) (every? symbol? s)) (map UNTRACE s)) + 566      (and (seq? s) (every? symbol? s)) (map UNTRACE s))
            - 550    @traced-symbols) + 567    @traced-symbols)
            - 551   + 568  
            - 552  ;;;; Extensions ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 569  ;;;; Extensions ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 553   + 570  
            - 554  (defn DOC + 571  (defn DOC
            - 555    "Open the page for this `symbol` in the Lisp 1.5 manual, if known, in the  + 572    "Open the page for this `symbol` in the Lisp 1.5 manual, if known, in the 
            - 556      default web browser. + 573      default web browser.
            - 557      + 574     
            - 558     **NOTE THAT** this is an extension function, not available in strct mode." + 575     **NOTE THAT** this is an extension function, not available in strct mode."
            - 559    [symbol] + 576    [symbol]
            - 560    (when (lax? 'DOC) + 577    (when (lax? 'DOC)
            - 561      (open-doc symbol))) + 578      (open-doc symbol)))
            - 562   + 579  
            - 563  (defn CONSP + 580  (defn CONSP
            - 564    "Return `T` if object `o` is a cons cell, else `F`. + 581    "Return `T` if object `o` is a cons cell, else `F`.
            - 565      + 582     
            - 566     **NOTE THAT** this is an extension function, not available in strct mode.  + 583     **NOTE THAT** this is an extension function, not available in strct mode. 
            - 567     I believe that Lisp 1.5 did not have any mechanism for testing whether an + 584     I believe that Lisp 1.5 did not have any mechanism for testing whether an
            - 568     argument was, or was not, a cons cell." + 585     argument was, or was not, a cons cell."
            - 569    [o] + 586    [o]
            - 570    (when (lax? 'CONSP) + 587    (when (lax? 'CONSP)
            - 571      (if (instance? ConsCell o) 'T 'F))) + 588      (if (instance? ConsCell o) 'T 'F)))
            diff --git a/docs/cloverage/beowulf/io.clj.html b/docs/cloverage/beowulf/io.clj.html index 2ef3c37..0eb19d4 100644 --- a/docs/cloverage/beowulf/io.clj.html +++ b/docs/cloverage/beowulf/io.clj.html @@ -334,13 +334,13 @@ 110     reference."
            - + 111    ([entry]
            112     (or (resolve-subr entry 'SUBR)
            - + 113         (resolve-subr entry 'FSUBR)))
            diff --git a/docs/cloverage/beowulf/oblist.clj.html b/docs/cloverage/beowulf/oblist.clj.html index f96cc9c..4ca6768 100644 --- a/docs/cloverage/beowulf/oblist.clj.html +++ b/docs/cloverage/beowulf/oblist.clj.html @@ -133,8 +133,8 @@ 043    "Command line options from invocation."
            - - 044    {}) + + 044    {:testing true})
            045   diff --git a/docs/cloverage/beowulf/read.clj.html b/docs/cloverage/beowulf/read.clj.html index ba3a47f..74998a3 100644 --- a/docs/cloverage/beowulf/read.clj.html +++ b/docs/cloverage/beowulf/read.clj.html @@ -50,283 +50,319 @@ 015    switch."
            - 016    (:require ;; [beowulf.reader.char-reader :refer [read-chars]] + 016    (:require [beowulf.oblist :refer [*options*]]
            - 017              [beowulf.reader.generate :refer [generate]] + 017              [beowulf.reader.char-reader :refer [read-chars]]
            - 018              [beowulf.reader.parser :refer [parse]] + 018              [beowulf.reader.generate :refer [generate]]
            - 019              [beowulf.reader.simplify :refer [simplify]] + 019              [beowulf.reader.parser :refer [parse]]
            - 020              [clojure.string :refer [join split starts-with? trim]]) + 020              [beowulf.reader.simplify :refer [simplify]]
            - 021    (:import [java.io InputStream] + 021              [clojure.string :refer [join split starts-with? trim]])
            - 022             [instaparse.gll Failure])) + 022    (:import [instaparse.gll Failure] +
            + + 023             [java.io InputStream]))
            - 023   + 024  
            - 024  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 025  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 025  ;;; + 026  ;;;
            - 026  ;;; This file provides the reader required for boostrapping. It's not a bad + 027  ;;; This file provides the reader required for boostrapping. It's not a bad
            - 027  ;;; reader - it provides feedback on errors found in the input - but it isn't + 028  ;;; reader - it provides feedback on errors found in the input - but it isn't
            - 028  ;;; the real Lisp reader. + 029  ;;; the real Lisp reader.
            - 029  ;;; + 030  ;;;
            - 030  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 031  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 031  ;;; + 032  ;;;
            - 032  ;;; Copyright (C) 2022-2023 Simon Brooke + 033  ;;; Copyright (C) 2022-2023 Simon Brooke
            - 033  ;;; + 034  ;;;
            - 034  ;;; This program is free software; you can redistribute it and/or + 035  ;;; This program is free software; you can redistribute it and/or
            - 035  ;;; modify it under the terms of the GNU General Public License + 036  ;;; modify it under the terms of the GNU General Public License
            - 036  ;;; as published by the Free Software Foundation; either version 2 + 037  ;;; as published by the Free Software Foundation; either version 2
            - 037  ;;; of the License, or (at your option) any later version. + 038  ;;; of the License, or (at your option) any later version.
            - 038  ;;;  + 039  ;;; 
            - 039  ;;; This program is distributed in the hope that it will be useful, + 040  ;;; This program is distributed in the hope that it will be useful,
            - 040  ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of + 041  ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
            - 041  ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the + 042  ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
            - 042  ;;; GNU General Public License for more details. + 043  ;;; GNU General Public License for more details.
            - 043  ;;;  + 044  ;;; 
            - 044  ;;; You should have received a copy of the GNU General Public License + 045  ;;; You should have received a copy of the GNU General Public License
            - 045  ;;; along with this program; if not, write to the Free Software + 046  ;;; along with this program; if not, write to the Free Software
            - 046  ;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA. + 047  ;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
            - 047  ;;; + 048  ;;;
            - 048  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 049  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 049   + 050  
            - 050  (defn strip-line-comments + 051  (defn strip-line-comments
            - 051    "Strip blank lines and comment lines from this string `s`, expected to + 052    "Strip blank lines and comment lines from this string `s`, expected to
            - 052     be Lisp source." + 053     be Lisp source."
            - 053    [^String s] + 054    [^String s]
            - 054    (join "\n" + 055    (join "\n"
            - 055          (remove + 056          (remove
            - 056           #(or (empty? %) + 057           #(or (empty? %)
            - 057                (starts-with? (trim %) ";;")) + 058                (starts-with? (trim %) ";;"))
            - 058           (split s #"\n")))) + 059           (split s #"\n"))))
            - 059   + 060  
            - 060  (defn number-lines + 061  (defn number-lines
            - 061    ([^String s] + 062    ([^String s]
            - 062     (number-lines s nil)) + 063     (number-lines s nil))
            - 063    ([^String s ^Failure e] + 064    ([^String s ^Failure e]
            - 064     (let [l (-> e :line) + 065     (let [l (-> e :line)
            - 065           c (-> e :column)] + 066           c (-> e :column)]
            - 066       (join "\n" + 067       (join "\n"
            - 067             (map #(str (format "%5d %s" (inc %1) %2) + 068             (map #(str (format "%5d %s" (inc %1) %2)
            - 068                        (when (= l (inc %1)) + 069                        (when (= l (inc %1))
            - 069                          (str "\n" (apply str (repeat c " ")) "^"))) + 070                          (str "\n" (apply str (repeat c " ")) "^")))
            - 070                  (range) + 071                  (range)
            - 071                  (split s #"\n")))))) + 072                  (split s #"\n"))))))
            - 072   + 073  
            - 073  (defn gsp + 074  (defn gsp
            - 074    "Shortcut macro - the internals of read; or, if you like, read-string. + 075    "Shortcut macro - the internals of read; or, if you like, read-string.
            - 075    Argument `s` should be a string representation of a valid Lisp + 076    Argument `s` should be a string representation of a valid Lisp
            - 076    expression." + 077    expression."
            - 077    [s] + 078    [s]
            - 078    (let [source (strip-line-comments s) + 079    (let [source (strip-line-comments s)
            - 079          parse-tree (parse source)] + 080          parse-tree (parse source)]
            - 080      (if (instance? Failure parse-tree) + 081      (if (instance? Failure parse-tree)
            - 081        (doall (println (number-lines source parse-tree)) + 082        (doall (println (number-lines source parse-tree))
            - 082               (throw (ex-info "Ne can forstande " (assoc parse-tree :source source)))) + 083               (throw (ex-info "Ne can forstande " (assoc parse-tree :source source))))
            - 083        (generate (simplify parse-tree))))) + 084        (generate (simplify parse-tree)))))
            - 084   + 085  
            - 085  (defn read-from-console -
            - - 086    "Attempt to read a complete lisp expression from the console. NOTE that this -
            - - 087     will only really work for S-Expressions, not M-Expressions." -
            - - 088    [] + 086  (defn- dummy-read-chars [prompt]
            - 089    (loop [r (read-line)] + 087    (loop [r "" p prompt]
            - - 090      (if (and (= (count (re-seq #"\(" r)) -
            - - 091             (count (re-seq #"\)" r))) -
            - - 092               (= (count (re-seq #"\[" r)) -
            - - 093                  (count (re-seq #"\]" r)))) -
            - - 094        r -
            - - 095        (recur (str r "\n" (read-line)))))) -
            - - 096   -
            - - 097  (defn READ -
            - - 098    "An implementation of a Lisp reader sufficient for bootstrapping; not necessarily -
            - - 099    the final Lisp reader. `input` should be either a string representation of a LISP -
            - - 100    expression, or else an input stream. A single form will be read." -
            - - 101    ([] -
            - - 102     (gsp (read-from-console))) -
            - - 103    ([input] -
            - - 104     (cond -
            - - 105       (empty? input) (READ) + + 088      (if (and (seq r)
            - 106       (string? input) (gsp input) + 089               (= (count (re-seq #"\(" r)) +
            + + 090                  (count (re-seq #"\)" r))) +
            + + 091               (= (count (re-seq #"\[" r)) +
            + + 092                  (count (re-seq #"\]" r)))) +
            + + 093        r +
            + + 094        (do +
            + + 095          (print (str p " ")) +
            + + 096          (flush) +
            + + 097          (recur (str r "\n" (read-line)) "::"))))) +
            + + 098   +
            + + 099  (defn read-from-console +
            + + 100    "Attempt to read a complete lisp expression from the console. +
            + + 101      +
            + + 102     There's a major problem here that the read-chars reader messes up testing. +
            + + 103     We need to be able to disable it while testing!" +
            + + 104    [prompt] +
            + + 105    (if (:testing *options*) +
            + + 106      (dummy-read-chars prompt) +
            + + 107      (read-chars prompt))) +
            + + 108   +
            + + 109  (defn READ +
            + + 110    "An implementation of a Lisp reader sufficient for bootstrapping; not necessarily +
            + + 111    the final Lisp reader. `input` should be either a string representation of a LISP +
            + + 112    expression, or else an input stream. A single form will be read." +
            + + 113    ([] +
            + + 114     (gsp (read-from-console (:prompt *options*)))) +
            + + 115    ([input] +
            + + 116     (cond +
            + + 117       (empty? input) (READ) +
            + + 118       (string? input) (gsp input)
            - 107       (instance? InputStream input) (READ (slurp input)) + 119       (instance? InputStream input) (READ (slurp input))
            - 108       :else    (throw (ex-info "READ: `input` should be a string or an input stream" {}))))) + 120       :else    (throw (ex-info "READ: `input` should be a string or an input stream" {})))))
            diff --git a/docs/cloverage/beowulf/reader/char_reader.clj.html b/docs/cloverage/beowulf/reader/char_reader.clj.html index f198c42..a0ac0f9 100644 --- a/docs/cloverage/beowulf/reader/char_reader.clj.html +++ b/docs/cloverage/beowulf/reader/char_reader.clj.html @@ -71,163 +71,259 @@ 022     https://stackoverflow.com/questions/7931988/how-to-manipulate-control-characters"
            - 023    ;; (:import [org.jline.reader LineReader LineReaderBuilder] + 023    (:require [beowulf.oblist :refer [*options* oblist]])
            - 024    ;;          [org.jline.terminal TerminalBuilder]) + 024    (:import [org.jline.reader.impl.completer StringsCompleter]
            - 025    ) + 025             [org.jline.reader.impl DefaultParser DefaultParser$Bracket] +
            + + 026             [org.jline.reader LineReaderBuilder] +
            + + 027             [org.jline.terminal TerminalBuilder] +
            + + 028             [org.jline.widget AutopairWidgets AutosuggestionWidgets]))
            - 026   + 029  
            - 027  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 030  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 028  ;;; + 031  ;;;
            - 029  ;;; Copyright (C) 2022-2023 Simon Brooke + 032  ;;; Copyright (C) 2022-2023 Simon Brooke
            - 030  ;;; + 033  ;;;
            - 031  ;;; This program is free software; you can redistribute it and/or + 034  ;;; This program is free software; you can redistribute it and/or
            - 032  ;;; modify it under the terms of the GNU General Public License + 035  ;;; modify it under the terms of the GNU General Public License
            - 033  ;;; as published by the Free Software Foundation; either version 2 + 036  ;;; as published by the Free Software Foundation; either version 2
            - 034  ;;; of the License, or (at your option) any later version. + 037  ;;; of the License, or (at your option) any later version.
            - 035  ;;;  + 038  ;;; 
            - 036  ;;; This program is distributed in the hope that it will be useful, + 039  ;;; This program is distributed in the hope that it will be useful,
            - 037  ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of + 040  ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
            - 038  ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the + 041  ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
            - 039  ;;; GNU General Public License for more details. + 042  ;;; GNU General Public License for more details.
            - 040  ;;;  + 043  ;;; 
            - 041  ;;; You should have received a copy of the GNU General Public License + 044  ;;; You should have received a copy of the GNU General Public License
            - 042  ;;; along with this program; if not, write to the Free Software + 045  ;;; along with this program; if not, write to the Free Software
            - 043  ;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA. + 046  ;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
            - 044  ;;; + 047  ;;;
            - 045  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 048  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 046   + 049  
            - 047  ;; It looks from the example given [here](https://github.com/jline/jline3/blob/master/demo/src/main/java/org/jline/demo/Repl.java) + 050  ;; It looks from the example given [here](https://github.com/jline/jline3/blob/master/demo/src/main/java/org/jline/demo/Repl.java)
            - 048  ;; as though JLine could be used to build a perfect line-reader for Beowulf; but it also + 051  ;; as though JLine could be used to build a perfect line-reader for Beowulf; but it also
            - 049  ;; looks as though you'd need a DPhil in JLine to write it, and I don't have + 052  ;; looks as though you'd need a DPhil in JLine to write it, and I don't have
            - 050  ;; the time. + 053  ;; the time.
            - 051   + 054   +
            + + 055  (defn build-completer
            - 052  ;; (def get-reader + 056    "Build a completer which takes tokens from the oblist.
            - 053  ;;   "Return a reader, first constructing it if necessary. + 057     
            - 054      + 058     This is sort-of working, in as much as hitting <TAB> on a blank line will 
            - 055  ;;    **NOTE THAT** this is not settled API. The existence and call signature of + 059     show a table of values from the oblist, but hitting <TAB> after you've 
            - 056  ;;    this function is not guaranteed in future versions." + 060     started input does not show potential completions for tokens you've started."
            - 057  ;;   (memoize (fn [] + 061    []
            - - 058  ;;   (let [term (.build (.system (TerminalBuilder/builder) true))] -
            - - 059  ;;     (.build (.terminal (LineReaderBuilder/builder) term)))))) + + 062    (StringsCompleter. (map #(str (first %)) @oblist)))
            - 060   + 063  
            - 061  ;; (defn read-chars + 064  ;; This breaks; it is not correctly resolving the Enum, although I can't work out
            - 062  ;;   "A drop-in replacement for `clojure.core/read-line`, except that line editing + 065  ;; why not.
            - 063  ;;    and history should be enabled. + 066  ;; (defn build-parser
            - 064      + 067  ;;   []
            - 065  ;;    **NOTE THAT** this does not work yet, but it is in the API because I hope  + 068  ;;   (println "Building parser")
            - 066  ;;    that it will work later!" + 069  ;;   (let [parser (DefaultParser.)]
            - 067  ;;   []  + 070  ;;     (doall
            - 068  ;;     (let [eddie (get-reader)] + 071  ;;      (.setEofOnUnclosedBracket 
            - 069  ;;       (loop [s (.readLine eddie)] + 072  ;;       parser DefaultParser$Bracket/ROUND)))) +
            + + 073   +
            + + 074  (def get-reader
            - 070  ;;       (if (and (= (count (re-seq #"\(" s)) + 075    "Return a reader, first constructing it if necessary.
            - 071  ;;            (count (re-seq #"\)" s))) + 076     
            - 072  ;;                (= (count (re-seq #"\[]" s)) + 077     **NOTE THAT** this is not settled API. The existence and call signature of
            - 073  ;;                   (count (re-seq #"\]" s)))) + 078     this function is not guaranteed in future versions." +
            + + 079    (memoize (fn [] +
            + + 080              (let [term (.build (.system (TerminalBuilder/builder) true)) +
            + + 081                    reader (-> (LineReaderBuilder/builder) +
            + + 082                                (.terminal  term) +
            + + 083                                (.completer  (build-completer))
            - 074  ;;         s + 084   ;;       #(.parser % (build-parser))
            - 075  ;;         (recur (str s " " (.readLine eddie))))))) + 085                                (.build)) +
            + + 086                    ;; apw (AutopairWidgets. reader false) +
            + + 087                    ;; asw (AutosuggestionWidgets. reader) +
            + + 088                    ] +
            + + 089                ;; (.enable apw) +
            + + 090                ;; (.enable asw) +
            + + 091                reader)))) +
            + + 092   +
            + + 093  (defn read-chars +
            + + 094    "A drop-in replacement for `clojure.core/read-line`, except that line editing +
            + + 095     and history should be enabled. +
            + + 096      +
            + + 097     **NOTE THAT** this does not fully work yet, but it is in the API because I  +
            + + 098     hope that it will work later!" +
            + + 099    [prompt] +
            + + 100    (let [eddie (get-reader)] +
            + + 101      (loop [s (.readLine eddie (str prompt " "))] +
            + + 102        (if (and (= (count (re-seq #"\(" s)) +
            + + 103                    (count (re-seq #"\)" s))) +
            + + 104                 (= (count (re-seq #"\[]" s)) +
            + + 105                    (count (re-seq #"\]" s)))) +
            + + 106          s +
            + + 107          (recur (str s " " (.readLine eddie ":: ")))))))
            diff --git a/docs/cloverage/index.html b/docs/cloverage/index.html index 8f8236c..69296cf 100644 --- a/docs/cloverage/index.html +++ b/docs/cloverage/index.html @@ -16,11 +16,11 @@ beowulf.bootstrap
            624
            352
            -63.93 % + style="width:64.03688524590164%; + float:left;"> 625
            351
            +64.04 %
            138
            beowulf.cons-cell
            348
            133
            -72.35 % + style="width:76.0914760914761%; + float:left;"> 366
            115
            +76.09 %
            109
            114
            9
            27
            -81.38 % + style="width:15.172413793103448%; + float:left;"> 22
            +84.83 % 27423145 beowulf.core
            198
            87
            -69.47 % + style="width:73.94366197183099%; + float:left;"> 210
            74
            +73.94 %
            50
            4
            15
            -78.26 % + style="width:78.26086956521739%; + float:left;"> 54
            2
            13
            +81.16 % 132669 beowulf.host
            1027
            1374
            -42.77 % + style="width:46.61776691116545%; + float:left;"> 1144
            1310
            +46.62 %
            137
            163
            37
            81
            -68.24 % -57166255 + style="width:23.954372623574145%; + float:left;"> 63
            +76.05 % +58867263 beowulf.interop
            181
            43.96 %
            33
            6
            32
            -54.93 % -1711271 + style="width:45.833333333333336%; + float:left;"> 33
            +54.17 % +1711272 beowulf.manual
            beowulf.oblist
            9
            + float:left;"> 11
            100.00 %
            beowulf.read
            87
            89
            -49.43 % + style="width:54.36893203883495%; + float:left;"> 112
            94
            +54.37 %
            21
            29
            3
            15
            -61.54 % -108939 +68.09 % +1201047 beowulf.reader.char-reader
            1
            -100.00 % + style="width:10.0%; + float:left;"> 7
            63
            +10.00 %
            1
            -100.00 % -7541 + style="width:26.31578947368421%; + float:left;"> 5
            14
            +26.32 % +107619 beowulf.reader.generate
            Totals: -64.63 % +65.64 % -74.41 % +75.70 % diff --git a/resources/lisp1.5.lsp b/resources/lisp1.5.lsp index e56bc7d..09bf054 100644 --- a/resources/lisp1.5.lsp +++ b/resources/lisp1.5.lsp @@ -170,6 +170,7 @@ (COND ((NULL X) (U)) ((EQ (CAR X) Y) (CDR X)) (T (PROP (CDR X) Y U))))) + (PUT 32767 SUBR (BEOWULF HOST PUT)) (QUOTE 32767 EXPR (LAMBDA (X) X)) (QUOTIENT 32767 SUBR (BEOWULF HOST QUOTIENT)) (RANGE diff --git a/src/beowulf/core.clj b/src/beowulf/core.clj index dacedef..74131ff 100644 --- a/src/beowulf/core.clj +++ b/src/beowulf/core.clj @@ -53,7 +53,8 @@ (.canRead (io/file %))) "Could not find sysout file"]] ["-s" "--strict" "Strictly interpret the Lisp 1.5 language, without extensions."] - ["-t" "--time" "Time evaluations."]]) + ["-t" "--time" "Time evaluations."] + ["-x" "--testing" "Disable the jline reader - useful when piping input."]]) (defn- re "Like REPL, but it isn't a loop and doesn't print." diff --git a/src/beowulf/host.clj b/src/beowulf/host.clj index 48f622d..56fae9a 100644 --- a/src/beowulf/host.clj +++ b/src/beowulf/host.clj @@ -91,22 +91,21 @@ (cond (= l NIL) NIL (empty? path) l - :else - (try - (case (last path) - \a (uaf (.first l) (butlast path)) - \d (uaf (.getCdr l) (butlast path)) - (throw (ex-info (str "uaf: unexpected letter in path (only `a` and `d` permitted): " (last path)) - {:cause :uaf - :detail :unexpected-letter - :expr (last path)}))) - (catch ClassCastException e - (throw (ex-info - (str "uaf: Not a LISP list? " (type l)) - {:cause :uaf - :detail :not-a-lisp-list - :expr l} - e)))))) + (not (instance? ConsCell l)) (throw (ex-info (str "Ne liste: " + l "; " (type l)) + {:phase :eval + :function "universal access function" + :args [l path] + :type :beowulf})) + :else (case (last path) + \a (uaf (.first l) (butlast path)) + \d (uaf (.getCdr l) (butlast path)) + (throw (ex-info (str "uaf: unexpected letter in path (only `a` and `d` permitted): " + (last path)) + {:phase :eval + :function "universal access function" + :args [l path] + :type :beowulf}))))) (defmacro CAAR [x] `(uaf ~x '(\a \a))) (defmacro CADR [x] `(uaf ~x '(\a \d))) @@ -433,6 +432,21 @@ "The unexplained magic number which marks the start of a property list." (Integer/parseInt "77777" 8)) +(defn hit-or-miss-assoc + "Find the position of the binding of this `target` in a Lisp 1.5 + property list `plist`. + + Lisp 1.5 property lists are not assoc lists, but lists of the form + `(name value name value name value...)`. It's therefore necessary to + recurse down the list two entries at a time to avoid confusing names + with values." + [target plist] + (if (and (instance? ConsCell plist)(even? (count plist))) + (cond (= plist NIL) NIL + (= (first plist) target) plist + :else (hit-or-miss-assoc target (CDDR plist))) + NIL)) + (defn PUT "Put this `value` as the value of the property indicated by this `indicator` of this `symbol`. Return `value` on success. @@ -440,22 +454,25 @@ 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." [symbol indicator value] - (if-let [binding (ASSOC symbol @oblist)] - (if-let [prop (ASSOC indicator (CDDR binding))] - (RPLACD prop value) - (RPLACD binding - (make-cons-cell - magic-marker - (make-cons-cell - indicator - (make-cons-cell value (CDDR binding)))))) - (swap! - oblist - (fn [ob s p v] - (make-cons-cell - (make-beowulf-list (list s magic-marker p v)) - ob)) - symbol indicator value))) + (let [binding (ASSOC symbol @oblist)] + (if (instance? ConsCell binding) + (let [prop (hit-or-miss-assoc indicator (CDDR binding))] + (if (instance? ConsCell prop) + (RPLACA (CDR prop) value) + (RPLACD binding + (make-cons-cell + magic-marker + (make-cons-cell + indicator + (make-cons-cell value (CDDR binding))))))) + (swap! + oblist + (fn [ob s p v] + (make-cons-cell + (make-beowulf-list (list s magic-marker p v)) + ob)) + symbol indicator value))) + value) (defn GET "From the manual: diff --git a/src/beowulf/oblist.clj b/src/beowulf/oblist.clj index 38aa999..8769b7f 100644 --- a/src/beowulf/oblist.clj +++ b/src/beowulf/oblist.clj @@ -41,5 +41,5 @@ (def ^:dynamic *options* "Command line options from invocation." - {}) + {:testing true}) diff --git a/src/beowulf/read.clj b/src/beowulf/read.clj index 38860dc..8ed736a 100644 --- a/src/beowulf/read.clj +++ b/src/beowulf/read.clj @@ -83,16 +83,28 @@ (throw (ex-info "Ne can forstande " (assoc parse-tree :source source)))) (generate (simplify parse-tree))))) -(defn read-from-console - "Attempt to read a complete lisp expression from the console." - [prompt] - (loop [r (read-chars prompt)] - (if (and (= (count (re-seq #"\(" r)) - (count (re-seq #"\)" r))) +(defn- dummy-read-chars [prompt] + (loop [r "" p prompt] + (if (and (seq r) + (= (count (re-seq #"\(" r)) + (count (re-seq #"\)" r))) (= (count (re-seq #"\[" r)) (count (re-seq #"\]" r)))) r - (recur (str r "\n" (read-chars "")))))) + (do + (print (str p " ")) + (flush) + (recur (str r "\n" (read-line)) "::"))))) + +(defn read-from-console + "Attempt to read a complete lisp expression from the console. + + There's a major problem here that the read-chars reader messes up testing. + We need to be able to disable it while testing!" + [prompt] + (if (:testing *options*) + (dummy-read-chars prompt) + (read-chars prompt))) (defn READ "An implementation of a Lisp reader sufficient for bootstrapping; not necessarily diff --git a/test/beowulf/core_test.clj b/test/beowulf/core_test.clj index 81cb86b..9c2029f 100644 --- a/test/beowulf/core_test.clj +++ b/test/beowulf/core_test.clj @@ -1,8 +1,9 @@ (ns beowulf.core-test - (:require [clojure.java.io :refer [reader]] - [clojure.string :refer [split]] - [clojure.test :refer [deftest is testing]] - [beowulf.core :refer [-main repl stop-word]])) + (:require [beowulf.core :refer [-main repl stop-word]] + [beowulf.oblist :refer [*options*]] + [clojure.java.io :refer [reader]] + [clojure.string :refer [split starts-with?]] + [clojure.test :refer [deftest is testing]])) ;; (deftest a-test ;; (testing "FIXME, I fail." @@ -20,45 +21,43 @@ (deftest repl-tests (testing "quit functionality" (with-open [r (reader (string->stream stop-word))] - (binding [*in* r] + (binding [clojure.core/*in* r + *options* (assoc *options* :testing true)] (is (thrown-with-msg? Exception #"\nFærwell!" (repl ""))))) - (let [expected nil actual (with-open [r (reader (string->stream stop-word))] (binding [*in* r] - (-main)))] + (-main "--testing")))] (is (= actual expected))))) -;; TODO: not working because STOP is not being recognised, but I haven't -;; worked out why not yet. It *did* work. - +;; The new read-chars interface is really messing with this. Need to sort out! +;; OK, binding `:testing` doesn't work because `*options*` gets rebound in main. +;; Need to be able to pass in a testing flag as argument to -main (deftest flag-tests - (testing "No flags" + (testing "Only testing flag" (let [expected-greeting "Hider wilcuman. Béowulf is mín nama." expected-quit-message (str "Sprecan '" stop-word "' tó laéfan") expected-result #".*\(3 \. 4\)" expected-prompt "Sprecan:: " expected-signoff "Færwell!" ;; anticipated output (note blank lines): - - ; Hider wilcuman. Béowulf is mín nama. - - ; Sprecan 'STOP' tó laéfan - - ; Sprecan:: > (3 . 4) - ; Sprecan:: - ; Færwell! + + ;; Hider wilcuman. Béowulf is mín nama. + + ;; Sprecan 'STOP' tó laéfan + + ;; Sprecan:: > (3 . 4) + ;; Sprecan:: + ;; Færwell! [_ greeting _ _ quit-message _ result prompt signoff] (with-open [r (reader (string->stream (str "cons[3; 4]\n" stop-word)))] (binding [*in* r] - (split (with-out-str (-main)) #"\n")))] + (split (with-out-str (-main "--testing")) #"\n")))] (is (= greeting expected-greeting)) - ; (is (= error expected-error)) (is (re-matches expected-result result)) (is (= quit-message expected-quit-message)) (is (= prompt expected-prompt)) - (is (= signoff expected-signoff)) - )) + (is (= signoff expected-signoff)))) (testing "unknown flag" (let [expected-greeting "Hider wilcuman. Béowulf is mín nama." expected-quit-message (str "Sprecan '" stop-word "' tó laéfan") @@ -69,115 +68,63 @@ [_ greeting _ error quit-message _ result prompt signoff] (with-open [r (reader (string->stream (str "cons[5; 6]\n" stop-word)))] (binding [*in* r] - (split (with-out-str (-main "--unknown")) #"\n")))] + (split (with-out-str (-main "--unknown" "--testing")) #"\n")))] (is (= greeting expected-greeting)) (is (re-matches expected-error error)) (is (re-matches expected-result result)) (is (= quit-message expected-quit-message)) (is (= prompt expected-prompt)) - (is (= signoff expected-signoff)) - )) - ; (testing "help" - ; (let [expected-greeting "Hider wilcuman. Béowulf is mín nama." - ; expected-h1 " -h, --help" - ; expected-quit-message (str "Sprecan '" stop-word "' tó laéfan") - ; expected-result #".*\(A \. B\)" - ; expected-prompt "Sprecan:: " - ; expected-signoff "Færwell!" - ; [_ greeting _ h1 _ _ _ _ quit-message _ result prompt signoff] - ; (with-open [r (reader (string->stream (str "cons[A; B]\n" stop-word)))] - ; (binding [*in* r] - ; (split (with-out-str (-main "--help")) #"\n")))] - ; (is (= greeting expected-greeting)) - ; (is (= h1 expected-h1)) - ; (is (re-matches expected-result result)) - ; (is (= quit-message expected-quit-message)) - ; (is (= prompt expected-prompt)) - ; (is (= signoff expected-signoff)) - ; )) - ; (testing "prompt" - ; (let [expected-greeting "Hider wilcuman. Béowulf is mín nama." - ; expected-quit-message (str "Sprecan '" stop-word "' tó laéfan") - ; expected-error "" - ; expected-result #".*\(A \. B\).*" - ; expected-prompt "? " - ; expected-signoff "Færwell!" - ; [_ greeting _ error quit-message _ result prompt signoff] - ; (with-open [r (reader (string->stream (str stop-word)))] - ; (binding [*in* r] - ; (split (with-out-str (-main "--prompt" "?")) #"\n")))] - ; (is (= greeting expected-greeting)) - ; (is (= error expected-error)) - ; (is (re-matches expected-result result )) - ; (is (= quit-message expected-quit-message)) - ; (is (= prompt expected-prompt)) - ; (is (= signoff expected-signoff)) - ; )) - ; (testing "read - file not found" - ; (let [expected-greeting "Hider wilcuman. Béowulf is mín nama." - ; expected-quit-message (str "Sprecan '" stop-word "' tó laéfan") - ; expected-error #"Failed to validate.*" - ; expected-result #".*\(A \. B\)" - ; expected-prompt "Sprecan:: " - ; expected-signoff "Færwell!" - ; [_ greeting _ error quit-message _ result prompt signoff] - ; (with-open [r (reader (string->stream (str "cons[A; B]\n" stop-word)))] - ; (binding [*in* r] - ; (split (with-out-str (-main "--read" "froboz")) #"\n")))] - ; (is (= greeting expected-greeting)) - ; (is (re-matches expected-error error)) - ; (is (re-matches expected-result result)) - ; (is (= quit-message expected-quit-message)) - ; (is (= prompt expected-prompt)) - ; (is (= signoff expected-signoff)) - ; )) - ; (testing "read - file found" - ; ;; TODO: there's no feedback from this because the initfile - ; ;; is not yet read. This will change - ; (let [expected-greeting "Hider wilcuman. Béowulf is mín nama." - ; expected-quit-message (str "Sprecan '" stop-word "' tó laéfan") - ; expected-error "" - ; expected-result #".*\(A \. B\)" - ; expected-prompt "Sprecan:: " - ; expected-signoff "Færwell!" - ; [_ greeting error quit-message _ _ result prompt signoff] - ; (with-open [r (reader (string->stream (str "cons[A; B]\n" stop-word)))] - ; (binding [*in* r] - ; (split (with-out-str (-main "--read" "README.md")) #"\n")))] - ; (is (= greeting expected-greeting)) - ; (is (= error expected-error)) - ; (is (re-matches expected-result result)) - ; (is (= quit-message expected-quit-message)) - ; (is (= prompt expected-prompt)) - ; (is (= signoff expected-signoff)) - ; )) - ; (testing "strict" - ; (let [expected-greeting "Hider wilcuman. Béowulf is mín nama." - ; expected-quit-message (str "Sprecan '" stop-word "' tó laéfan") - ; expected-error "" - ; expected-result #".*Cannot parse meta expressions in strict mode.*" - ; expected-prompt "Sprecan:: " - ; expected-signoff "Færwell!" - ; [_ greeting _ error quit-message _ result prompt signoff] - ; (with-open [r (reader (string->stream (str "cons[A; B]\n" stop-word)))] - ; (binding [*in* r] - ; (split (with-out-str (-main "--strict")) #"\n")))] - ; (is (= greeting expected-greeting)) - ; (is (= error expected-error)) - ; (is (re-matches expected-result result )) - ; (is (= quit-message expected-quit-message)) - ; (is (= prompt expected-prompt)) - ; (is (= signoff expected-signoff)) - ; )) - ; ; (testing "trace" - ; (let [expected-greeting "Hider wilcuman. Béowulf is mín nama." - ; expected-error "" - ; expected-trace #".*traced-eval.*" - ; [_ greeting _ error _ _ trace & _] - ; (with-open [r (reader (string->stream (str "cons[A; B]\n" stop-word)))] - ; (binding [*in* r] - ; (split (with-out-str (-main "--trace")) #"\n")))] - ; (is (= greeting expected-greeting)) - ; (is (= error expected-error)) - ; (is (re-matches expected-trace trace)) -) \ No newline at end of file + (is (= signoff expected-signoff)))) +;; ;; TODO: not working because STOP is not being recognised, but I haven't +;; ;; worked out why not yet. It *did* work. + +;; Hider wilcuman. Béowulf is mín nama. +;; -f FILEPATH, --file-path FILEPATH Set the path to the directory for reading and writing Lisp files. +;; -h, --help +;; -p PROMPT, --prompt PROMPT Sprecan:: Set the REPL prompt to PROMPT +;; -r SYSOUTFILE, --read SYSOUTFILE lisp1.5.lsp Read Lisp system from file SYSOUTFILE +;; -s, --strict Strictly interpret the Lisp 1.5 language, without extensions. +;; -t, --time Time evaluations. +;; -x, --testing Disable the jline reader - useful when piping input. +;; Sprecan 'STOP' tó laéfan + +;; Sprecan:: + + (testing "help" + (let [expected-greeting "Hider wilcuman. Béowulf is mín nama." + expected-h1 " -h, --help" + expected-quit-message (str "Sprecan '" stop-word "' tó laéfan") + expected-result #".*\(A \. B\)" + expected-prompt "Sprecan:: " + expected-signoff "Færwell!" + [_ greeting _ _ h1 _ _ _ _ _ quit-message _ result prompt signoff] + (with-open [r (reader (string->stream (str "cons[A; B]\n" stop-word)))] + (binding [*in* r] + (split (with-out-str (-main "--help" "--testing")) #"\n")))] + (is (= greeting expected-greeting)) + (is (= h1 expected-h1)) + (is (re-matches expected-result result)) + (is (= quit-message expected-quit-message)) + (is (starts-with? prompt expected-prompt)) + (is (= signoff expected-signoff)))) + (testing "prompt" + (let [expected-prompt "? " + [_ _ _ _ _ _ prompt _] + (with-open [r (reader (string->stream stop-word))] + (binding [*in* r] + (split (with-out-str (-main "--prompt" "?" "--testing")) #"\n")))] + (is (= prompt expected-prompt)))) + (testing "read - file not found" + (let [expected-error #"Failed to validate.*" + [_ _ _ error _ _ _ _ _] + (with-open [r (reader (string->stream (str "cons[A; B]\n" stop-word)))] + (binding [*in* r] + (split (with-out-str (-main "--testing" "--read" "froboz")) #"\n")))] + (is (re-matches expected-error error)))) + (testing "strict" + (let [expected-result #".*Cannot parse meta expressions in strict mode.*" + [_ _ _ _ _ _ result _ _] + (with-open [r (reader (string->stream (str "cons[A; B]\n" stop-word)))] + (binding [*in* r] + (split (with-out-str (-main "--strict" "--testing")) #"\n")))] + (is (re-matches expected-result result ))))) diff --git a/test/beowulf/host_test.clj b/test/beowulf/host_test.clj index 7e5e1ff..5f73ea8 100644 --- a/test/beowulf/host_test.clj +++ b/test/beowulf/host_test.clj @@ -1,9 +1,21 @@ (ns beowulf.host-test - (:require [clojure.test :refer [deftest is testing]] - [beowulf.cons-cell :refer [F make-beowulf-list T]] - [beowulf.host :refer [CDR DIFFERENCE NUMBERP PLUS RPLACA RPLACD TIMES]] + (:require [beowulf.cons-cell :refer [F make-beowulf-list T]] + [beowulf.host :refer [CDR DIFFERENCE GENSYM GET NUMBERP PLUS PUT + RPLACA RPLACD TIMES]] + [beowulf.io :refer [SYSIN]] [beowulf.oblist :refer [NIL]] - [beowulf.read :refer [gsp]])) + [beowulf.read :refer [gsp]] + [clojure.test :refer [deftest is testing use-fixtures]])) + +(use-fixtures :once (fn [f] + (try (when (SYSIN "resources/lisp1.5.lsp") + (f)) + (catch Throwable any + (throw (ex-info "Failed to load Lisp sysout" + {:phase test + :function 'SYSIN + :file "resources/lisp1.5.lsp"} + any)))))) (deftest destructive-change-test (testing "RPLACA" @@ -64,7 +76,8 @@ (let [expected 6 actual (TIMES 2 3)] (is (= actual expected)))) - (testing DIFFERENCE + (testing "DIFFERENCE" (let [expected -1 actual (DIFFERENCE 1 2)] (is (= actual expected))))) + diff --git a/test/beowulf/lisp_test.clj b/test/beowulf/lisp_test.clj index 7d9fa64..5095999 100644 --- a/test/beowulf/lisp_test.clj +++ b/test/beowulf/lisp_test.clj @@ -1,11 +1,11 @@ (ns beowulf.lisp-test "The idea here is to test actual Lisp functions" - (:require [clojure.test :refer [deftest testing is use-fixtures]] - [beowulf.bootstrap :refer [EVAL]] + (:require [beowulf.bootstrap :refer [EVAL]] [beowulf.cons-cell :refer [make-beowulf-list]] - [beowulf.io :refer [SYSIN]] - ;; [beowulf.oblist :refer [NIL]] - [beowulf.read :refer [READ]])) + [beowulf.io :refer [SYSIN]] ;; [beowulf.oblist :refer [NIL]] + [beowulf.oblist :refer [NIL]] + [beowulf.read :refer [READ]] + [clojure.test :refer [deftest is testing use-fixtures]])) (defn- reps "'Read eval print string', or 'read eval print single'. @@ -165,4 +165,42 @@ (SETQ X (ADD1 X)) (COND ((EQ X 5) (RETURN X)) (T (GO START))))")] - (is (= actual expected))))) \ No newline at end of file + (is (= actual expected))))) + + +(deftest put-get-tests + (let [symbol 'TESTSYMBOL + p1 'TESTPROPONE + p2 'TESTPROPTWO] + (testing "GET - property should be missing" + (let [expected "NIL" + actual (reps "(GET 'TESTSYMBOL 'TESTPROPONE)")] + (is (= actual expected)))) + (testing "PUT and GET: value of new property; change value of property" + (let [prop (reps "(GENSYM)") + val1 (reps "(GENSYM)") + val2 (reps "(GENSYM)") + expected1 val1 + actual1 (when (reps (str "(PUT '" symbol " '" prop " '" val1 ")")) + (reps (str "(GET '" symbol " '" prop ")"))) + expected2 val2 + actual2 (when (reps (str "(PUT '" symbol " '" prop " '" val2 ")")) + (reps (str "(GET '" symbol " '" prop ")")))] + (is (not= val1 val2)) + (is (= actual1 expected1) "The value set can be retrieved.") + (is (= actual2 expected2) "The value is changed."))) + (testing "PUT and GET: different properties have independent values" + (let [val1 (reps "(GENSYM)") + val2 (reps "(GENSYM)") + expected1 val1 + actual1 (when (reps (str "(PUT '" symbol " '" p1 " '" val1 ")")) + (reps (str "(GET '" symbol " '" p1 ")"))) + expected2 val2 + actual2 (when (reps (str "(PUT '" symbol " '" p2 " '" val2 ")")) + (reps (str "(GET '" symbol " '" p2 ")"))) + expected3 val1 + actual3 (reps (str "(GET '" symbol " '" p1 ")"))] + (is (not= val1 val2)) + (is (= actual1 expected1) "The value set can be retrieved.") + (is (= actual2 expected2) "Values are independent.") + (is (= actual3 expected3) "Setting a second property does not obliterate the first."))))) \ No newline at end of file From 7c4d3668a8343da630a3f37a77c04b0d0649b557 Mon Sep 17 00:00:00 2001 From: Simon Brooke Date: Tue, 11 Apr 2023 15:18:52 +0100 Subject: [PATCH 3/4] Lots of new unit tests. --- docs/cloverage/beowulf/host.clj.html | 227 ++--- docs/cloverage/index.html | 30 +- docs/codox/beowulf.bootstrap.html | 19 +- docs/codox/beowulf.cons-cell.html | 15 +- docs/codox/beowulf.core.html | 7 +- docs/codox/beowulf.gendoc.html | 11 +- docs/codox/beowulf.host.html | 99 ++- docs/codox/beowulf.interop.html | 16 +- docs/codox/beowulf.io.html | 16 +- docs/codox/beowulf.manual.html | 7 +- docs/codox/beowulf.oblist.html | 8 +- docs/codox/beowulf.read.html | 13 +- docs/codox/beowulf.reader.char-reader.html | 24 +- docs/codox/beowulf.reader.generate.html | 23 +- docs/codox/beowulf.reader.macros.html | 5 +- docs/codox/beowulf.reader.parser.html | 4 +- docs/codox/beowulf.reader.simplify.html | 9 +- docs/codox/beowulf.scratch.html | 8 +- docs/codox/further_reading.html | 30 +- docs/codox/index.html | 18 +- docs/codox/intro.html | 943 ++++----------------- docs/codox/mexpr.html | 15 +- docs/codox/values.html | 211 ++--- project.clj | 5 +- src/beowulf/host.clj | 9 +- test/beowulf/host_test.clj | 222 ++++- 26 files changed, 866 insertions(+), 1128 deletions(-) diff --git a/docs/cloverage/beowulf/host.clj.html b/docs/cloverage/beowulf/host.clj.html index 6437d2b..e11a000 100644 --- a/docs/cloverage/beowulf/host.clj.html +++ b/docs/cloverage/beowulf/host.clj.html @@ -130,19 +130,19 @@ 042    [symbol]
            - + 043    (when (:strict *options*)
            - + 044      (throw (ex-info (format "%s ne āfand innan Lisp 1.5" symbol)
            - + 045                      {:type :strict
            046                       :phase :host
            - + 047                       :function symbol})))
            @@ -283,19 +283,19 @@ 093      (empty? path) l
            - + 094      (not (instance? ConsCell l)) (throw (ex-info (str "Ne liste: "
            - + 095                                                        l "; " (type l))
            - + 096                                                   {:phase :eval
            097                                                    :function "universal access function"
            - + 098                                                    :args [l path]
            @@ -310,19 +310,19 @@ 102              \d (uaf (.getCdr l) (butlast path))
            - + 103              (throw (ex-info (str "uaf: unexpected letter in path (only `a` and `d` permitted): "
            - + 104                                   (last path))
            - + 105                              {:phase :eval
            106                               :function "universal access function"
            - + 107                               :args [l path]
            @@ -568,7 +568,7 @@ 188      (if
            - + 189       (or
            @@ -580,7 +580,7 @@ 192        (symbol? value)
            - + 193        (= value NIL))
            @@ -619,13 +619,13 @@ 205                    any))))
            - + 206        (throw (ex-info
            - + 207                (str "Un-ġefōg þing in RPLACD: `" value "` (" (type value) ")")
            - + 208                {:cause :bad-value
            @@ -634,19 +634,19 @@ 210                 :function :rplacd
            - + 211                 :args (list cell value)
            212                 :type :beowulf})))
            - + 213      (throw (ex-info
            - + 214              (str "Uncynlic miercels in RPLACD: `" cell "` (" (type cell) ")")
            - + 215              {:cause :bad-cell
            @@ -655,7 +655,7 @@ 217               :detail :rplacd
            - + 218               :args (list cell value)
            @@ -682,7 +682,7 @@ 226  
            - + 227  (defmacro NULL
            @@ -691,13 +691,13 @@ 229    [x]
            - + 230    `(if (= ~x NIL) T F))
            231  
            - + 232  (defmacro NILP
            @@ -706,7 +706,7 @@ 234    [x]
            - + 235    `(if (= ~x NIL) T NIL))
            @@ -847,13 +847,13 @@ 281    ;; (println "  filtered: " (seq (filter #{F NIL} args)))
            - + 282    (cond (= NIL args) T
            283          (seq? args) (if (seq (filter #{F NIL} args)) F T)
            - + 284          :else T))
            @@ -889,13 +889,13 @@ 295    ;; (println "  filtered: " (seq (remove #{F NIL} args)))
            - + 296    (cond (= NIL args) F
            - + 297          (seq? args) (if (seq (remove #{F NIL} args)) T F)
            - + 298          :else F))
            @@ -1078,7 +1078,7 @@ 358    (let [p (apply * args)]
            - + 359      (if (integer? p) p (float p))))
            @@ -1093,7 +1093,7 @@ 363    (let [d (- x y)]
            - + 364      (if (integer? d) d (float d))))
            @@ -1153,7 +1153,7 @@ 383    [x]
            - + 384    (dec x))
            @@ -1165,7 +1165,7 @@ 387    [x]
            - + 388    (if (integer? x) T F))
            @@ -1189,7 +1189,7 @@ 395    [x y]
            - + 396    (if (< x y) T F))
            @@ -1201,7 +1201,7 @@ 399    [x y]
            - + 400    (if (> x y) T F))
            @@ -1237,7 +1237,7 @@ 411    [& args]
            - + 412    (throw (ex-info "LISP STÆFLEAHTER" {:args args
            @@ -1249,7 +1249,7 @@ 415                                        :type :lisp
            - + 416                                        :code (or (first args) 'A1)})))
            @@ -1334,7 +1334,7 @@ 443    [target plist]
            - 444    (if (and (instance? ConsCell plist)(even? (count plist))) + 444    (if (and (instance? ConsCell plist) (even? (count plist)))
            445      (cond (= plist NIL) NIL @@ -1558,215 +1558,218 @@ 518    [a-list indicator]
            - - 519    (map + + 519    (doall
            - - 520     #(PUT (CAR %) indicator (CDR %)) + + 520     (map +
            + + 521      #(when (PUT (CAR %) indicator (CDR %)) (CAR %))
            - 521     a-list)) + 522      a-list)))
            - 522   + 523  
            - 523  (defn DEFINE + 524  (defn DEFINE
            - 524    "Bootstrap-only version of `DEFINE` which, post boostrap, can be overwritten  + 525    "Bootstrap-only version of `DEFINE` which, post boostrap, can be overwritten 
            - 525    in LISP.  + 526    in LISP. 
            - 526   + 527  
            - 527    The single argument to `DEFINE` should be an association list of symbols to + 528    The single argument to `DEFINE` should be an association list of symbols to
            - 528     lambda functions. See page 58 of the manual." + 529     lambda functions. See page 58 of the manual."
            - 529    [a-list] + 530    [a-list]
            - 530    (DEFLIST a-list 'EXPR)) + 531    (DEFLIST a-list 'EXPR))
            - 531   + 532  
            - 532  (defn SET + 533  (defn SET
            - 533    "Implementation of SET in Clojure. Add to the `oblist` a binding of the + 534    "Implementation of SET in Clojure. Add to the `oblist` a binding of the
            - 534     value of `var` to the value of `val`. NOTE WELL: this is not SETQ!" + 535     value of `var` to the value of `val`. NOTE WELL: this is not SETQ!"
            - 535    [symbol val] + 536    [symbol val]
            - 536    (PUT symbol 'APVAL val)) + 537    (PUT symbol 'APVAL val))
            - 537   + 538  
            - 538  ;;;; TRACE and friends ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 539  ;;;; TRACE and friends ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 539   + 540  
            - 540  (def traced-symbols + 541  (def traced-symbols
            - 541    "Symbols currently being traced." + 542    "Symbols currently being traced."
            - 542    (atom #{})) + 543    (atom #{}))
            - 543   + 544  
            - 544  (defn traced? + 545  (defn traced?
            - 545    "Return `true` iff `s` is a symbol currently being traced, else `nil`." + 546    "Return `true` iff `s` is a symbol currently being traced, else `nil`."
            - 546    [s] + 547    [s]
            - 547    (try (contains? @traced-symbols s) + 548    (try (contains? @traced-symbols s)
            - 548         (catch Throwable _ nil))) + 549         (catch Throwable _ nil)))
            - 549   + 550  
            - 550  (defn TRACE + 551  (defn TRACE
            - 551    "Add this `s` to the set of symbols currently being traced. If `s` + 552    "Add this `s` to the set of symbols currently being traced. If `s`
            - 552     is not a symbol or sequence of symbols, does nothing." + 553     is not a symbol or sequence of symbols, does nothing."
            - 553    [s] + 554    [s]
            - 554    (swap! traced-symbols + 555    (swap! traced-symbols
            - 555           #(cond + 556           #(cond
            - 556              (symbol? s) (conj % s) + 557              (symbol? s) (conj % s)
            - 557              (and (seq? s) (every? symbol? s)) (union % (set s)) + 558              (and (seq? s) (every? symbol? s)) (union % (set s))
            - 558              :else %))) + 559              :else %)))
            - 559   + 560  
            - 560  (defn UNTRACE + 561  (defn UNTRACE
            - 561    "Remove this `s` from the set of symbols currently being traced. If `s` + 562    "Remove this `s` from the set of symbols currently being traced. If `s`
            - 562     is not a symbol or sequence of symbols, does nothing." + 563     is not a symbol or sequence of symbols, does nothing."
            - 563    [s] + 564    [s]
            - 564    (cond + 565    (cond
            - 565      (symbol? s) (swap! traced-symbols #(set (remove (fn [x] (= s x)) %))) + 566      (symbol? s) (swap! traced-symbols #(set (remove (fn [x] (= s x)) %)))
            - 566      (and (seq? s) (every? symbol? s)) (map UNTRACE s)) + 567      (and (seq? s) (every? symbol? s)) (map UNTRACE s))
            - 567    @traced-symbols) + 568    @traced-symbols)
            - 568   + 569  
            - 569  ;;;; Extensions ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + 570  ;;;; Extensions ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            - 570   + 571  
            - 571  (defn DOC + 572  (defn DOC
            - 572    "Open the page for this `symbol` in the Lisp 1.5 manual, if known, in the  + 573    "Open the page for this `symbol` in the Lisp 1.5 manual, if known, in the 
            - 573      default web browser. + 574      default web browser.
            - 574      + 575     
            - 575     **NOTE THAT** this is an extension function, not available in strct mode." + 576     **NOTE THAT** this is an extension function, not available in strct mode."
            - 576    [symbol] + 577    [symbol]
            - 577    (when (lax? 'DOC) + 578    (when (lax? 'DOC)
            - 578      (open-doc symbol))) + 579      (open-doc symbol)))
            - 579   + 580  
            - 580  (defn CONSP + 581  (defn CONSP
            - 581    "Return `T` if object `o` is a cons cell, else `F`. + 582    "Return `T` if object `o` is a cons cell, else `F`.
            - 582      + 583     
            - 583     **NOTE THAT** this is an extension function, not available in strct mode.  + 584     **NOTE THAT** this is an extension function, not available in strct mode. 
            - 584     I believe that Lisp 1.5 did not have any mechanism for testing whether an + 585     I believe that Lisp 1.5 did not have any mechanism for testing whether an
            - 585     argument was, or was not, a cons cell." + 586     argument was, or was not, a cons cell."
            - 586    [o] + 587    [o]
            - 587    (when (lax? 'CONSP) + 588    (when (lax? 'CONSP)
            - 588      (if (instance? ConsCell o) 'T 'F))) + 589      (if (instance? ConsCell o) 'T 'F)))
            diff --git a/docs/cloverage/index.html b/docs/cloverage/index.html index 69296cf..dbe60af 100644 --- a/docs/cloverage/index.html +++ b/docs/cloverage/index.html @@ -67,20 +67,20 @@ beowulf.host
            1144
            1310
            -46.62 % + style="width:56.44047135310849%; + float:left;"> 1389
            1072
            +56.44 %
            163
            37
            63
            -76.05 % -58867263 + style="width:75.37878787878788%; + float:left;"> 199
            32
            33
            +87.50 % +58967264 beowulf.interop
            Totals: -65.64 % +68.60 % -75.70 % +77.76 % diff --git a/docs/codox/beowulf.bootstrap.html b/docs/codox/beowulf.bootstrap.html index 72c621f..eaa1806 100644 --- a/docs/codox/beowulf.bootstrap.html +++ b/docs/codox/beowulf.bootstrap.html @@ -1,17 +1,24 @@ beowulf.bootstrap documentation

            Project

            Topics

            Namespaces

            Public Vars

            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.

            view source

            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.

            view source

            find-target

            TODO: write docs

            view source

            PROG

            (PROG program env depth)

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

            +

            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.

            +
            view source

            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.

            +
            view source

            find-target

            TODO: write docs

            +
            view source

            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 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.

            +

            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 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.

            +

            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.

            view source

            prog-eval

            (prog-eval expr vars env depth)

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

            view source

            try-resolve-subroutine

            (try-resolve-subroutine subr args)

            Attempt to resolve this subr with these args.

            view source
            \ No newline at end of file +

            Good.

            +
            view source

            prog-eval

            (prog-eval expr vars env depth)

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

            +
            view source

            try-resolve-subroutine

            (try-resolve-subroutine subr args)

            Attempt to resolve this subr with these args.

            +
            view source
            \ No newline at end of file diff --git a/docs/codox/beowulf.cons-cell.html b/docs/codox/beowulf.cons-cell.html index cc83668..39996a5 100644 --- a/docs/codox/beowulf.cons-cell.html +++ b/docs/codox/beowulf.cons-cell.html @@ -1,3 +1,16 @@ -beowulf.cons-cell documentation

            Project

            Topics

            Namespaces

            Public Vars

            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?

            view source

            F

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

            view source

            make-beowulf-list

            (make-beowulf-list x)

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

            view source

            make-cons-cell

            (make-cons-cell car cdr)

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

            view source

            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

            view source

            pretty-print

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

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

            view source

            T

            The canonical true value.

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

            Project

            Topics

            Namespaces

            Public Vars

            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?

            +
            view source

            F

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

            +
            view source

            make-beowulf-list

            (make-beowulf-list x)

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

            +
            view source

            make-cons-cell

            (make-cons-cell car cdr)

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

            +
            view source

            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

            +
            view source

            pretty-print

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

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

            +
            view source

            T

            The canonical true value.

            +
            view source
            \ No newline at end of file diff --git a/docs/codox/beowulf.core.html b/docs/codox/beowulf.core.html index 1d60abf..f796bb3 100644 --- a/docs/codox/beowulf.core.html +++ b/docs/codox/beowulf.core.html @@ -1,3 +1,8 @@ -beowulf.core documentation

            Project

            Topics

            Namespaces

            Public Vars

            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.

            view source

            cli-options

            TODO: write docs

            view source

            repl

            (repl prompt)

            Read/eval/print loop.

            view source

            stop-word

            The word which, if submitted an an input line, will cause Beowulf to quit. Question: should this be forlǣte?

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

            Project

            Topics

            Namespaces

            Public Vars

            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.

            +
            view source

            cli-options

            TODO: write docs

            +
            view source

            repl

            (repl prompt)

            Read/eval/print loop.

            +
            view source

            stop-word

            The word which, if submitted an an input line, will cause Beowulf to quit. Question: should this be forlǣte?

            +
            view source
            \ No newline at end of file diff --git a/docs/codox/beowulf.gendoc.html b/docs/codox/beowulf.gendoc.html index fa4087e..c40564c 100644 --- a/docs/codox/beowulf.gendoc.html +++ b/docs/codox/beowulf.gendoc.html @@ -1,4 +1,13 @@ beowulf.gendoc documentation

            Project

            Topics

            Namespaces

            Public Vars

            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.

            view source

            gen-doc-table

            (gen-doc-table)

            TODO: write docs

            view source

            gen-index

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

            TODO: write docs

            view source

            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.

            view source

            infer-implementation

            (infer-implementation entry)

            TODO: write docs

            view source

            infer-signature

            (infer-signature entry)

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

            view source

            infer-type

            (infer-type entry)

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

            view source

            open-doc

            (open-doc symbol)

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

            view source
            \ No newline at end of file +

            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.

          +
          view source

          gen-doc-table

          (gen-doc-table)

          TODO: write docs

          +
          view source

          gen-index

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

          TODO: write docs

          +
          view source

          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.

          +
          view source

          infer-implementation

          (infer-implementation entry)

          TODO: write docs

          +
          view source

          infer-signature

          (infer-signature entry)

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

          +
          view source

          infer-type

          (infer-type entry)

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

          +
          view source

          open-doc

          (open-doc symbol)

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

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/beowulf.host.html b/docs/codox/beowulf.host.html index efef2cb..0a9aadc 100644 --- a/docs/codox/beowulf.host.html +++ b/docs/codox/beowulf.host.html @@ -1,19 +1,94 @@ -beowulf.host documentation

          Project

          Topics

          Namespaces

          Public Vars

          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

          view source

          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.

          view source

          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

          Project

          Topics

          Namespaces

          Public Vars

          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

          +
          view source

          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.

          +
          view source

          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.

          view source

          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.

          view source

          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.

          view source

          CAAAAR

          macro

          (CAAAAR x)

          TODO: write docs

          view source

          CAAADR

          macro

          (CAAADR x)

          TODO: write docs

          view source

          CAAAR

          macro

          (CAAAR x)

          TODO: write docs

          view source

          CAADAR

          macro

          (CAADAR x)

          TODO: write docs

          view source

          CAADDR

          macro

          (CAADDR x)

          TODO: write docs

          view source

          CAADR

          macro

          (CAADR x)

          TODO: write docs

          view source

          CAAR

          macro

          (CAAR x)

          TODO: write docs

          view source

          CADAAR

          macro

          (CADAAR x)

          TODO: write docs

          view source

          CADADR

          macro

          (CADADR x)

          TODO: write docs

          view source

          CADAR

          macro

          (CADAR x)

          TODO: write docs

          view source

          CADDAR

          macro

          (CADDAR x)

          TODO: write docs

          view source

          CADDDR

          macro

          (CADDDR x)

          TODO: write docs

          view source

          CADDR

          macro

          (CADDR x)

          TODO: write docs

          view source

          CADR

          macro

          (CADR x)

          TODO: write docs

          view source

          CAR

          (CAR x)

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

          view source

          CDAAAR

          macro

          (CDAAAR x)

          TODO: write docs

          view source

          CDAADR

          macro

          (CDAADR x)

          TODO: write docs

          view source

          CDAAR

          macro

          (CDAAR x)

          TODO: write docs

          view source

          CDADAR

          macro

          (CDADAR x)

          TODO: write docs

          view source

          CDADDR

          macro

          (CDADDR x)

          TODO: write docs

          view source

          CDADR

          macro

          (CDADR x)

          TODO: write docs

          view source

          CDAR

          macro

          (CDAR x)

          TODO: write docs

          view source

          CDDAAR

          macro

          (CDDAAR x)

          TODO: write docs

          view source

          CDDADR

          macro

          (CDDADR x)

          TODO: write docs

          view source

          CDDAR

          macro

          (CDDAR x)

          TODO: write docs

          view source

          CDDDAR

          macro

          (CDDDAR x)

          TODO: write docs

          view source

          CDDDDR

          macro

          (CDDDDR x)

          TODO: write docs

          view source

          CDDDR

          macro

          (CDDDR x)

          TODO: write docs

          view source

          CDDR

          macro

          (CDDR x)

          TODO: write docs

          view source

          CDR

          (CDR x)

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

          view source

          CONS

          (CONS car cdr)

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

          view source

          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.

          view source

          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.

          view source

          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.

          view source

          DIFFERENCE

          (DIFFERENCE x y)

          TODO: write docs

          view source

          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.

          view source

          EQ

          (EQ x y)

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

          view source

          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

          view source

          ERROR

          (ERROR & args)

          Throw an error

          view source

          FIXP

          (FIXP x)

          TODO: write docs

          view source

          GENSYM

          (GENSYM)

          Generate a unique symbol.

          view source

          GET

          (GET symbol indicator)

          From the manual:

          +

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

          +
          view source

          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.

          +
          view source

          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.

          +
          view source

          CAAAAR

          macro

          (CAAAAR x)

          TODO: write docs

          +
          view source

          CAAADR

          macro

          (CAAADR x)

          TODO: write docs

          +
          view source

          CAAAR

          macro

          (CAAAR x)

          TODO: write docs

          +
          view source

          CAADAR

          macro

          (CAADAR x)

          TODO: write docs

          +
          view source

          CAADDR

          macro

          (CAADDR x)

          TODO: write docs

          +
          view source

          CAADR

          macro

          (CAADR x)

          TODO: write docs

          +
          view source

          CAAR

          macro

          (CAAR x)

          TODO: write docs

          +
          view source

          CADAAR

          macro

          (CADAAR x)

          TODO: write docs

          +
          view source

          CADADR

          macro

          (CADADR x)

          TODO: write docs

          +
          view source

          CADAR

          macro

          (CADAR x)

          TODO: write docs

          +
          view source

          CADDAR

          macro

          (CADDAR x)

          TODO: write docs

          +
          view source

          CADDDR

          macro

          (CADDDR x)

          TODO: write docs

          +
          view source

          CADDR

          macro

          (CADDR x)

          TODO: write docs

          +
          view source

          CADR

          macro

          (CADR x)

          TODO: write docs

          +
          view source

          CAR

          (CAR x)

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

          +
          view source

          CDAAAR

          macro

          (CDAAAR x)

          TODO: write docs

          +
          view source

          CDAADR

          macro

          (CDAADR x)

          TODO: write docs

          +
          view source

          CDAAR

          macro

          (CDAAR x)

          TODO: write docs

          +
          view source

          CDADAR

          macro

          (CDADAR x)

          TODO: write docs

          +
          view source

          CDADDR

          macro

          (CDADDR x)

          TODO: write docs

          +
          view source

          CDADR

          macro

          (CDADR x)

          TODO: write docs

          +
          view source

          CDAR

          macro

          (CDAR x)

          TODO: write docs

          +
          view source

          CDDAAR

          macro

          (CDDAAR x)

          TODO: write docs

          +
          view source

          CDDADR

          macro

          (CDDADR x)

          TODO: write docs

          +
          view source

          CDDAR

          macro

          (CDDAR x)

          TODO: write docs

          +
          view source

          CDDDAR

          macro

          (CDDDAR x)

          TODO: write docs

          +
          view source

          CDDDDR

          macro

          (CDDDDR x)

          TODO: write docs

          +
          view source

          CDDDR

          macro

          (CDDDR x)

          TODO: write docs

          +
          view source

          CDDR

          macro

          (CDDR x)

          TODO: write docs

          +
          view source

          CDR

          (CDR x)

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

          +
          view source

          CONS

          (CONS car cdr)

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

          +
          view source

          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.

          +
          view source

          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.

          +
          view source

          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.

          +
          view source

          DIFFERENCE

          (DIFFERENCE x y)

          TODO: write docs

          +
          view source

          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.

          +
          view source

          EQ

          (EQ x y)

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

          +
          view source

          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

          +
          view source

          ERROR

          (ERROR & args)

          Throw an error

          +
          view source

          FIXP

          (FIXP x)

          TODO: write docs

          +
          view source

          GENSYM

          (GENSYM)

          Generate a unique symbol.

          +
          view source

          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.

          view source

          GREATERP

          (GREATERP x y)

          TODO: write docs

          view source

          lax?

          (lax? symbol)

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

          view source

          LESSP

          (LESSP x y)

          TODO: write docs

          view source

          LIST

          (LIST & args)

          TODO: write docs

          view source

          magic-marker

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

          view source

          NILP

          macro

          (NILP x)

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

          view source

          NULL

          macro

          (NULL x)

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

          view source

          NUMBERP

          (NUMBERP x)

          TODO: write docs

          view source

          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.

          view source

          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.

          view source

          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.

          +

          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.

          +
          view source

          GREATERP

          (GREATERP x y)

          TODO: write docs

          +
          view source

          hit-or-miss-assoc

          (hit-or-miss-assoc target plist)

          Find the position of the binding of this target in a Lisp 1.5 property list plist.

          +

          Lisp 1.5 property lists are not assoc lists, but lists of the form (name value name value name value...). It’s therefore necessary to recurse down the list two entries at a time to avoid confusing names with values.

          +
          view source

          lax?

          (lax? symbol)

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

          +
          view source

          LESSP

          (LESSP x y)

          TODO: write docs

          +
          view source

          LIST

          (LIST & args)

          TODO: write docs

          +
          view source

          magic-marker

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

          +
          view source

          NILP

          macro

          (NILP x)

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

          +
          view source

          NULL

          macro

          (NULL x)

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

          +
          view source

          NUMBERP

          (NUMBERP x)

          TODO: write docs

          +
          view source

          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.

          +
          view source

          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.

          +
          view source

          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.

          view source

          PLUS

          (PLUS & args)

          TODO: write docs

          view source

          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.

          view source

          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.

          view source

          REMAINDER

          (REMAINDER x y)

          TODO: write docs

          view source

          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)

          view source

          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)

          view source

          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!

          view source

          SUB1

          (SUB1 x)

          TODO: write docs

          view source

          TIMES

          (TIMES & args)

          TODO: write docs

          view source

          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.

          view source

          traced-symbols

          Symbols currently being traced.

          view source

          traced?

          (traced? s)

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

          view source

          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

          view source

          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.

          view source
          \ No newline at end of file +

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

          +
          view source

          PLUS

          (PLUS & args)

          TODO: write docs

          +
          view source

          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.

          +
          view source

          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.

          +
          view source

          REMAINDER

          (REMAINDER x y)

          TODO: write docs

          +
          view source

          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)

          +
          view source

          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)

          +
          view source

          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!

          +
          view source

          SUB1

          (SUB1 x)

          TODO: write docs

          +
          view source

          TIMES

          (TIMES & args)

          TODO: write docs

          +
          view source

          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.

          +
          view source

          traced-symbols

          Symbols currently being traced.

          +
          view source

          traced?

          (traced? s)

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

          +
          view source

          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

          +
          view source

          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.

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/beowulf.interop.html b/docs/codox/beowulf.interop.html index 59e1c5b..f1fcf7e 100644 --- a/docs/codox/beowulf.interop.html +++ b/docs/codox/beowulf.interop.html @@ -1,11 +1,17 @@ -beowulf.interop documentation

          Project

          Topics

          Namespaces

          Public Vars

          beowulf.interop

          TODO: write docs

          INTEROP

          (INTEROP fn-symbol args)

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

          +beowulf.interop documentation

          Project

          Topics

          Namespaces

          Public Vars

          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. -
          2. a sequence (list) of symbols forming a qualified path name bound to a function.
            3. +
          3. a symbol bound in the host environment to a function; or
            4. +
          4. a sequence (list) of symbols forming a qualified path name bound to a function.

          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.

          view source

          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.

          view source

          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.

          view source

          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.

          view source

          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.

          view source
          \ No newline at end of file +

          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.

          +
          view source

          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.

          +
          view source

          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.

          +
          view source

          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.

          +
          view source

          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.

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/beowulf.io.html b/docs/codox/beowulf.io.html index 648f733..c87c07b 100644 --- a/docs/codox/beowulf.io.html +++ b/docs/codox/beowulf.io.html @@ -2,12 +2,18 @@ ""> beowulf.io documentation

          Project

          Topics

          Namespaces

          Public Vars

          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.

          +

          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

          view source

          resolve-subr

          (resolve-subr entry)(resolve-subr entry prop)

          If this oblist entry references a subroutine, attempt to fix up that reference.

          view source

          safely-wrap-subr

          (safely-wrap-subr entry)

          TODO: write docs

          view source

          safely-wrap-subrs

          (safely-wrap-subrs objects)

          TODO: write docs

          view source

          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

          +
          view source

          resolve-subr

          (resolve-subr entry)(resolve-subr entry prop)

          If this oblist entry references a subroutine, attempt to fix up that reference.

          +
          view source

          safely-wrap-subr

          (safely-wrap-subr entry)

          TODO: write docs

          +
          view source

          safely-wrap-subrs

          (safely-wrap-subrs objects)

          TODO: write docs

          +
          view source

          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.

          view source

          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.

          view source
          \ No newline at end of file +

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

          +
          view source

          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.

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/beowulf.manual.html b/docs/codox/beowulf.manual.html index 3a82449..3631591 100644 --- a/docs/codox/beowulf.manual.html +++ b/docs/codox/beowulf.manual.html @@ -1,3 +1,8 @@ -beowulf.manual documentation

          Project

          Topics

          Namespaces

          Public Vars

          beowulf.manual

          Experimental code for accessing the manual online.

          *manual-url*

          dynamic

          TODO: write docs

          view source

          format-page-references

          (format-page-references fn-symbol)

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

          view source

          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.

          view source

          page-url

          (page-url page-no)

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

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

          Project

          Topics

          Namespaces

          Public Vars

          beowulf.manual

          Experimental code for accessing the manual online.

          +

          *manual-url*

          dynamic

          TODO: write docs

          +
          view source

          format-page-references

          (format-page-references fn-symbol)

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

          +
          view source

          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.

          +
          view source

          page-url

          (page-url page-no)

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

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/beowulf.oblist.html b/docs/codox/beowulf.oblist.html index ea54aa2..155a64b 100644 --- a/docs/codox/beowulf.oblist.html +++ b/docs/codox/beowulf.oblist.html @@ -1,5 +1,9 @@ beowulf.oblist documentation

          Project

          Topics

          Namespaces

          Public Vars

          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.

          view source

          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?

          view source

          oblist

          The default environment.

          view source
          \ No newline at end of file +

          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.

          +
          view source

          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?

          +
          view source

          oblist

          The default environment.

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/beowulf.read.html b/docs/codox/beowulf.read.html index 1a7c002..bd83a97 100644 --- a/docs/codox/beowulf.read.html +++ b/docs/codox/beowulf.read.html @@ -3,7 +3,14 @@ beowulf.read documentation

          Project

          Topics

          Namespaces

          Public Vars

          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. -
          2. It treats everything between a double semi-colon and an end of line as a comment, as most modern Lisps do; but I do not believe Lisp 1.5 had this feature.
            3. +
          3. 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;
            4. +
          4. It treats everything between a double semi-colon and an end of line as a comment, as most modern Lisps do; but I do not believe Lisp 1.5 had this feature.
          -

          Both these extensions can be disabled by using the --strict command line switch.

          gsp

          (gsp s)

          Shortcut macro - the internals of read; or, if you like, read-string. Argument s should be a string representation of a valid Lisp expression.

          view source

          number-lines

          (number-lines s)(number-lines s e)

          TODO: write docs

          view source

          READ

          (READ)(READ input)

          An implementation of a Lisp reader sufficient for bootstrapping; not necessarily the final Lisp reader. input should be either a string representation of a LISP expression, or else an input stream. A single form will be read.

          view source

          read-from-console

          (read-from-console)

          Attempt to read a complete lisp expression from the console. NOTE that this will only really work for S-Expressions, not M-Expressions.

          view source

          strip-line-comments

          (strip-line-comments s)

          Strip blank lines and comment lines from this string s, expected to be Lisp source.

          view source
          \ No newline at end of file +

          Both these extensions can be disabled by using the --strict command line switch.

          +

          gsp

          (gsp s)

          Shortcut macro - the internals of read; or, if you like, read-string. Argument s should be a string representation of a valid Lisp expression.

          +
          view source

          number-lines

          (number-lines s)(number-lines s e)

          TODO: write docs

          +
          view source

          READ

          (READ)(READ input)

          An implementation of a Lisp reader sufficient for bootstrapping; not necessarily the final Lisp reader. input should be either a string representation of a LISP expression, or else an input stream. A single form will be read.

          +
          view source

          read-from-console

          (read-from-console prompt)

          Attempt to read a complete lisp expression from the console.

          +

          There’s a major problem here that the read-chars reader messes up testing. We need to be able to disable it while testing!

          +
          view source

          strip-line-comments

          (strip-line-comments s)

          Strip blank lines and comment lines from this string s, expected to be Lisp source.

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/beowulf.reader.char-reader.html b/docs/codox/beowulf.reader.char-reader.html index e726009..9ef00d6 100644 --- a/docs/codox/beowulf.reader.char-reader.html +++ b/docs/codox/beowulf.reader.char-reader.html @@ -2,15 +2,19 @@ ""> beowulf.reader.char-reader documentation

          Project

          Topics

          Namespaces

          Public Vars

          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)

          +

          What’s needed (rough specification)

            -
          1. Carriage return does not cause input to be returned, unless a. the number of open brackets ( and closing brackets ) match; and b. the number of open square brackets [ and closing square brackets ] also match;
            2. -
          2. aborts editing and returns the string STOP;
            3. -
          3. and scroll back and forward through history, but ideally I’d like this to be the Lisp history (i.e. the history of S-Expressions actually read by READ, rather than the strings which were supplied to READ);
            4. -
          4. offers potential auto-completions taken from the value of (OBLIST), ideally the current value, not the value at the time the session started;
            5. -
          5. and offer movement and editing within the line.
            6. +
          6. Carriage return does not cause input to be returned, unless a. the number of open brackets ( and closing brackets ) match; and b. the number of open square brackets [ and closing square brackets ] also match;
            7. +
          7. aborts editing and returns the string STOP;
            8. +
          8. and scroll back and forward through history, but ideally I’d like this to be the Lisp history (i.e. the history of S-Expressions actually read by READ, rather than the strings which were supplied to READ);
            9. +
          9. offers potential auto-completions taken from the value of (OBLIST), ideally the current value, not the value at the time the session started;
            10. +
          10. and offer movement and editing within the line.
          -

          TODO: There are multiple problems with JLine; a better solution might be to start from here: https://stackoverflow.com/questions/7931988/how-to-manipulate-control-characters

          build-completer

          (build-completer)

          Build a completer which takes tokens from the oblist.

          -

          This is sort-of working, in as much as hitting on a blank line will show a table of values from the oblist, but hitting after you’ve started input does not show potential completions for tokens you’ve started.

          view source

          get-reader

          Return a reader, first constructing it if necessary.

          -

          NOTE THAT this is not settled API. The existence and call signature of this function is not guaranteed in future versions.

          view source

          read-chars

          (read-chars)

          A drop-in replacement for clojure.core/read-line, except that line editing and history should be enabled.

          -

          NOTE THAT this does not fully work yet, but it is in the API because I hope that it will work later!

          view source
          \ No newline at end of file +

          TODO: There are multiple problems with JLine; a better solution might be to start from here: https://stackoverflow.com/questions/7931988/how-to-manipulate-control-characters

          +

          build-completer

          (build-completer)

          Build a completer which takes tokens from the oblist.

          +

          This is sort-of working, in as much as hitting on a blank line will show a table of values from the oblist, but hitting after you’ve started input does not show potential completions for tokens you’ve started.

          +
          view source

          get-reader

          Return a reader, first constructing it if necessary.

          +

          NOTE THAT this is not settled API. The existence and call signature of this function is not guaranteed in future versions.

          +
          view source

          read-chars

          (read-chars prompt)

          A drop-in replacement for clojure.core/read-line, except that line editing and history should be enabled.

          +

          NOTE THAT this does not fully work yet, but it is in the API because I hope that it will work later!

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/beowulf.reader.generate.html b/docs/codox/beowulf.reader.generate.html index f2d763e..417a91e 100644 --- a/docs/codox/beowulf.reader.generate.html +++ b/docs/codox/beowulf.reader.generate.html @@ -1,13 +1,13 @@ -beowulf.reader.generate documentation

          Project

          Topics

          Namespaces

          Public Vars

          beowulf.reader.generate

          Generating S-Expressions from parse trees.

          -

          From Lisp 1.5 Programmers Manual, page 10

          +beowulf.reader.generate documentation

          Project

          Topics

          Namespaces

          Public Vars

          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:

          We are now in a position to define the universal LISP function evalquote[fn;args], When evalquote is given a function and a list of arguments for that function, it computes the value of the function applied to the arguments. LISP functions have S-expressions as arguments. In particular, the argument fn of the function evalquote must be an S-expression. Since we have been writing functions as M-expressions, it is necessary to translate them into S-expressions.

          -

          The following rules define a method of translating functions written in the meta-language into S-expressions. 1. If the function is represented by its name, it is translated by changing all of the letters to upper case, making it an atomic symbol. Thus car is translated to CAR. 2. If the function uses the lambda notation, then the expression λ[[x ..;xn]; ε] is translated into (LAMBDA (X1 ...XN) ε*), where ε* is the translation of ε. 3. If the function begins with label, then the translation of label[α;ε] is (LABEL α* ε*).

          -

          Forms are translated as follows: 1. A variable, like a function name, is translated by using uppercase letters. Thus the translation of var1 is VAR1. 2. The obvious translation of letting a constant translate into itself will not work. Since the translation of x is X, the translation of X must be something else to avoid ambiguity. The solution is to quote it. Thus X is translated into (QUOTE X). 3. The form fn[argl;. ..;argn] is translated into (fn* argl* ...argn*) 4. The conditional expression [pl-el;...;pn-en] is translated into (COND (p1* e1*)...(pn* en*))

          -

          Examples

          +

          The following rules define a method of translating functions written in the meta-language into S-expressions. 1. If the function is represented by its name, it is translated by changing all of the letters to upper case, making it an atomic symbol. Thus car is translated to CAR. 2. If the function uses the lambda notation, then the expression λ[[x ..;xn]; ε] is translated into (LAMBDA (X1 ...XN) ε*), where ε* is the translation of ε. 3. If the function begins with label, then the translation of label[α;ε] is (LABEL α* ε*).

          +

          Forms are translated as follows: 1. A variable, like a function name, is translated by using uppercase letters. Thus the translation of var1 is VAR1. 2. The obvious translation of letting a constant translate into itself will not work. Since the translation of x is X, the translation of X must be something else to avoid ambiguity. The solution is to quote it. Thus X is translated into (QUOTE X). 3. The form fn[argl;. ..;argn] is translated into (fn* argl* ...argn*) 4. The conditional expression [pl-el;...;pn-en] is translated into (COND (p1* e1*)...(pn* en*))

          +

          Examples

            M-expressions                                  S-expressions             
 
   x                                              X                         
@@ -21,4 +21,15 @@
        T->ff[car[x]]]]]                              (COND ((ATOM X) X) 
                                                          ((QUOTE T)(FF (CAR X))))))
          -

          quote ends

          gen-cond

          (gen-cond p context)

          Generate a cond statement from this simplified parse tree fragment p; returns nil if p does not represent a (MEXPR) cond statement.

          view source

          gen-cond-clause

          (gen-cond-clause p context)

          Generate a cond clause from this simplified parse tree fragment p; returns nil if p does not represent a cond clause.

          view source

          gen-dot-terminated-list

          (gen-dot-terminated-list p)

          Generate a list, which may be dot-terminated, from this partial parse tree ‘p’. Note that the function acts recursively and progressively decapitates its argument, so that the argument will not always be a valid parse tree.

          view source

          gen-fn-call

          (gen-fn-call p context)

          Generate a function call from this simplified parse tree fragment p; returns nil if p does not represent a (MEXPR) function call.

          view source

          gen-iexpr

          (gen-iexpr tree context)

          TODO: write docs

          view source

          generate

          (generate p)(generate p context)

          Generate lisp structure from this parse tree p. It is assumed that p has been simplified.

          view source

          generate-assign

          (generate-assign tree context)

          Generate an assignment statement based on this tree. If the thing being assigned to is a function signature, then we have to do something different to if it’s an atom.

          view source

          generate-defn

          (generate-defn tree context)

          TODO: write docs

          view source

          generate-set

          (generate-set tree context)

          Actually not sure what the mexpr representation of set looks like

          view source

          strip-leading-zeros

          (strip-leading-zeros s)(strip-leading-zeros s prefix)

          read-string interprets strings with leading zeros as octal; strip any from this string s. If what’s left is empty (i.e. there were only zeros, return "0".

          view source
          \ No newline at end of file +

          quote ends

          +

          gen-cond

          (gen-cond p context)

          Generate a cond statement from this simplified parse tree fragment p; returns nil if p does not represent a (MEXPR) cond statement.

          +
          view source

          gen-cond-clause

          (gen-cond-clause p context)

          Generate a cond clause from this simplified parse tree fragment p; returns nil if p does not represent a cond clause.

          +
          view source

          gen-dot-terminated-list

          (gen-dot-terminated-list p)

          Generate a list, which may be dot-terminated, from this partial parse tree ‘p’. Note that the function acts recursively and progressively decapitates its argument, so that the argument will not always be a valid parse tree.

          +
          view source

          gen-fn-call

          (gen-fn-call p context)

          Generate a function call from this simplified parse tree fragment p; returns nil if p does not represent a (MEXPR) function call.

          +
          view source

          gen-iexpr

          (gen-iexpr tree context)

          TODO: write docs

          +
          view source

          generate

          (generate p)(generate p context)

          Generate lisp structure from this parse tree p. It is assumed that p has been simplified.

          +
          view source

          generate-assign

          (generate-assign tree context)

          Generate an assignment statement based on this tree. If the thing being assigned to is a function signature, then we have to do something different to if it’s an atom.

          +
          view source

          generate-defn

          (generate-defn tree context)

          TODO: write docs

          +
          view source

          generate-set

          (generate-set tree context)

          Actually not sure what the mexpr representation of set looks like

          +
          view source

          strip-leading-zeros

          (strip-leading-zeros s)(strip-leading-zeros s prefix)

          read-string interprets strings with leading zeros as octal; strip any from this string s. If what’s left is empty (i.e. there were only zeros, return "0".

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/beowulf.reader.macros.html b/docs/codox/beowulf.reader.macros.html index 55003ec..5c9d10c 100644 --- a/docs/codox/beowulf.reader.macros.html +++ b/docs/codox/beowulf.reader.macros.html @@ -2,4 +2,7 @@ ""> beowulf.reader.macros documentation

          Project

          Topics

          Namespaces

          Public Vars

          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

          view source

          expand-macros

          (expand-macros form)

          TODO: write docs

          view source
          \ No newline at end of file +

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

          +

          *readmacros*

          dynamic

          TODO: write docs

          +
          view source

          expand-macros

          (expand-macros form)

          TODO: write docs

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/beowulf.reader.parser.html b/docs/codox/beowulf.reader.parser.html index 25eb874..c4a43f0 100644 --- a/docs/codox/beowulf.reader.parser.html +++ b/docs/codox/beowulf.reader.parser.html @@ -1,3 +1,5 @@ -beowulf.reader.parser documentation

          Project

          Topics

          Namespaces

          Public Vars

          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.

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

          Project

          Topics

          Namespaces

          Public Vars

          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.

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/beowulf.reader.simplify.html b/docs/codox/beowulf.reader.simplify.html index 013d66f..2b3f8ba 100644 --- a/docs/codox/beowulf.reader.simplify.html +++ b/docs/codox/beowulf.reader.simplify.html @@ -1,4 +1,9 @@ -beowulf.reader.simplify documentation

          Project

          Topics

          Namespaces

          Public Vars

          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

          view source

          remove-optional-space

          (remove-optional-space tree)

          TODO: write docs

          view source

          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.

          view source

          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.

          view source
          \ No newline at end of file +beowulf.reader.simplify documentation

          Project

          Topics

          Namespaces

          Public Vars

          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

          +
          view source

          remove-optional-space

          (remove-optional-space tree)

          TODO: write docs

          +
          view source

          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.

          +
          view source

          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.

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/beowulf.scratch.html b/docs/codox/beowulf.scratch.html index 671f5a6..3209599 100644 --- a/docs/codox/beowulf.scratch.html +++ b/docs/codox/beowulf.scratch.html @@ -1,4 +1,8 @@ -beowulf.scratch documentation

          Project

          Topics

          Namespaces

          Public Vars

          beowulf.scratch

          This namespace is for temporary functions and is intentionally excluded from Git.

          fns

          TODO: write docs

          view source

          interop-listify-q-name

          (interop-listify-q-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.

          view source

          mogrify-plist

          (mogrify-plist entry fns)

          TODO: write docs

          view source
          \ No newline at end of file +beowulf.scratch documentation

          Project

          Topics

          Namespaces

          Public Vars

          beowulf.scratch

          This namespace is for temporary functions and is intentionally excluded from Git.

          +

          fns

          TODO: write docs

          +
          view source

          interop-listify-q-name

          (interop-listify-q-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.

          +
          view source

          mogrify-plist

          (mogrify-plist entry fns)

          TODO: write docs

          +
          view source
          \ No newline at end of file diff --git a/docs/codox/further_reading.html b/docs/codox/further_reading.html index 2c027dd..d2d3a62 100644 --- a/docs/codox/further_reading.html +++ b/docs/codox/further_reading.html @@ -1,17 +1,19 @@ -Further Reading

          Project

          Topics

          Namespaces

          Further Reading

          +Further Reading

          Project

          Topics

          Namespaces

          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. -
          2. MIT AI Memo 1, John McCarthy, September 1958 This is, as far as I can find, the earliest specification document of the Lisp project.
            3. -
          3. Lisp 1 Programmer’s Manual, Phyllis Fox, March 1960
            4. -
          4. 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.
            5. -
          5. Early LISP History (1956 - 1959), Herbert Stoyan, August 1984
            6. -
          6. -

            The Roots of Lisp, Paul Graham, 2001

            7. -
          7. -

            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.

            -
            8. -
          \ No newline at end of file +
        3. 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.
          4. +
        4. MIT AI Memo 1, John McCarthy, September 1958 This is, as far as I can find, the earliest specification document of the Lisp project.
          5. +
        5. Lisp 1 Programmer’s Manual, Phyllis Fox, March 1960
          6. +
        6. 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.
          7. +
        7. Early LISP History (1956 - 1959), Herbert Stoyan, August 1984
          8. +
        8. +

          The Roots of Lisp, Paul Graham, 2001

          +
          9. +
        9. 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.

          +
          +
          10. +
        +
        \ No newline at end of file diff --git a/docs/codox/index.html b/docs/codox/index.html index 01c5b4f..f1b6eac 100644 --- a/docs/codox/index.html +++ b/docs/codox/index.html @@ -1,3 +1,19 @@ -Beowulf 0.3.1-SNAPSHOT

        Project

        Topics

        Namespaces

        Beowulf 0.3.1-SNAPSHOT

        Released under the GPL-2.0-or-later

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

        Installation

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

        [beowulf "0.3.1-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.

        Public variables and functions:

        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.

        Public variables 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.

        Public variables and functions:

        beowulf.interop

        TODO: write docs

        Public variables and functions:

        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.generate

        Generating S-Expressions from parse trees.

        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.

        Public variables and functions:

        beowulf.scratch

        This namespace is for temporary functions and is intentionally excluded from Git.

        Public variables and functions:

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

        Project

        Topics

        Namespaces

        Beowulf 0.3.1-SNAPSHOT

        Released under the GPL-2.0-or-later

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

        Installation

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

        [beowulf "0.3.1-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.

        +

        Public variables and functions:

        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.

        +

        Public variables 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.

        +

        Public variables and functions:

        beowulf.interop

        TODO: write docs

        +

        Public variables and functions:

        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.generate

        Generating S-Expressions from parse trees.

        +

        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.

        +

        Public variables and functions:

        beowulf.scratch

        This namespace is for temporary functions and is intentionally excluded from Git.

        +

        Public variables and functions:

        \ No newline at end of file diff --git a/docs/codox/intro.html b/docs/codox/intro.html index 03c2696..5aea87d 100644 --- a/docs/codox/intro.html +++ b/docs/codox/intro.html @@ -1,64 +1,64 @@ -beowulf

        Project

        Topics

        Namespaces

        beowulf

        -

        Þý liste cræfte spræc

        +beowulf

        Project

        Topics

        Namespaces

        beowulf

        +

        Þý liste cræfte spræc

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

        Beowulf logo

        -

        Contents

        +

        Contents

        +

        Table of contents generated with markdown-toc

        +

        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.

        -

        BUT WHY?!!?!

        +

        BUT WHY?!!?!

        Because.

        Because Lisp is the only computer language worth learning, and if a thing is worth learning, it’s worth learning properly; which means going back to the beginning and trying to understand that.

        Because there is, so far as I know, no working implementation of Lisp 1.5 for modern machines.

        Because I’m barking mad, and this is therapy.

        -

        Status

        +

        Status

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

        -

        Project Target

        +

        Project Target

        The project target is to be able to run the Wang algorithm for the propositional calculus given in chapter 8 of the Lisp 1.5 Programmer’s Manual. When that runs, the project is as far as I am concerned feature complete. I may keep tinkering with it after that and I’ll certainly accept pull requests which are in the spirit of the project (i.e. making Beowulf more usable, and/or implementing parts of Lisp 1.5 which I have not implemented), but this isn’t intended to be a new language for doing real work; it’s an educational and archaeological project, not serious engineering.

        Some readline-like functionality would be really useful, but my attempt to integrate JLine has not (yet) been successful.

        An in-core structure editor would be an extremely nice thing, and I may well implement one.

        You are of course welcome to fork the project and do whatever you like with it!

        -

        Invoking

        +

        Invoking

        Invoke with

        java -jar target/uberjar/beowulf-0.3.0-standalone.jar --help
        @@ -72,764 +72,171 @@ without extensions.

        To end a session, type STOP at the command prompt.

        -

        Building and Invoking

        +

        Building and Invoking

        Build with

        lein uberjar
        -

        Reader macros

        +

        Reader macros

        Currently SETQ and DEFUN are implemented as reader macros, sort of. It would now be possible to reimplement them as FEXPRs and so the reader macro functionality will probably go away.

        -

        Functions and symbols implemented

        +

        Functions and symbols implemented

        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        Function Type Signature Implementation Documentation
        NIL Lisp variable ? see manual pages 22, 69
        T Lisp variable ? see manual pages 22, 69
        F Lisp variable ? see manual pages 22, 69
        ADD1 Host lambda function ? ?
        AND Host lambda function ? PREDICATE 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.
        APPEND Lisp lambda function ? see manual pages 11, 61
        APPLY Host lambda function ? 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.
        ASSOC Lisp lambda function, Host lambda function ? ? 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 Host lambda function ? PREDICATE 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.
        CAR Host lambda function ? Return the item indicated by the first pointer of a pair. NIL is treated specially: the CAR of NIL is NIL.
        CAAAAR Lisp lambda function ? ? ?
        CAAADR Lisp lambda function ? ? ?
        CAAAR Lisp lambda function ? ? ?
        CAADAR Lisp lambda function ? ? ?
        CAADDR Lisp lambda function ? ? ?
        CAADR Lisp lambda function ? ? ?
        CAAR Lisp lambda function ? ? ?
        CADAAR Lisp lambda function ? ? ?
        CADADR Lisp lambda function ? ? ?
        CADAR Lisp lambda function ? ? ?
        CADDAR Lisp lambda function ? ? ?
        CADDDR Lisp lambda function ? ? ?
        CADDR Lisp lambda function ? ? ?
        CADR Lisp lambda function ? ? ?
        CDAAAR Lisp lambda function ? ? ?
        CDAADR Lisp lambda function ? ? ?
        CDAAR Lisp lambda function ? ? ?
        CDADAR Lisp lambda function ? ? ?
        CDADDR Lisp lambda function ? ? ?
        CDADR Lisp lambda function ? ? ?
        CDAR Lisp lambda function ? ? ?
        CDDAAR Lisp lambda function ? ? ?
        CDDADR Lisp lambda function ? ? ?
        CDDAR Lisp lambda function ? ? ?
        CDDDAR Lisp lambda function ? ? ?
        CDDDDR Lisp lambda function ? ? ?
        CDDDR Lisp lambda function ? ? ?
        CDDR Lisp lambda function ? ? ?
        CDR Host lambda function ? Return the item indicated by the second pointer of a pair. NIL is treated specially: the CDR of NIL is NIL.
        CONS Host lambda function ? Construct a new instance of cons cell with this car and cdr.
        CONSP Host lambda function ? ? 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.
        COPY Lisp lambda function ? see manual pages 62
        DEFINE Host lambda function ? PSEUDO-FUNCTION 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.
        DIFFERENCE Host lambda function ? ?
        DIVIDE Lisp lambda function ? see manual pages 26, 64
        DOC Host lambda function ? ? 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.
        EFFACE Lisp lambda function ? PSEUDO-FUNCTION see manual pages 63
        ERROR Host lambda function ? PSEUDO-FUNCTION Throw an error
        EQ Host lambda function ? PREDICATE Returns T if and only if both x and y are bound to the same atom, else NIL.
        EQUAL Host lambda function ? PREDICATE 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
        EVAL Host lambda function ? 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.
        FACTORIAL Lisp lambda function ? ? ?
        FIXP Host lambda function ? PREDICATE ?
        GENSYM Host lambda function ? Generate a unique symbol.
        GET Host lambda function ? 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 Host lambda function ? PREDICATE ?
        INTEROP Host lambda function ? ? ?
        INTERSECTION Lisp lambda function ? ? ?
        LENGTH Lisp lambda function ? see manual pages 62
        LESSP Host lambda function ? PREDICATE ?
        MAPLIST Lisp lambda function ? FUNCTIONAL see manual pages 20, 21, 63
        MEMBER Lisp lambda function ? PREDICATE see manual pages 11, 62
        MINUSP Lisp lambda function ? PREDICATE see manual pages 26, 64
        NOT Lisp lambda function ? PREDICATE see manual pages 21, 23, 58
        NULL Lisp lambda function ? PREDICATE see manual pages 11, 57
        NUMBERP Host lambda function ? PREDICATE ?
        OBLIST Host lambda function ? 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.
        ONEP Lisp lambda function ? PREDICATE see manual pages 26, 64
        OR Host lambda function ? PREDICATE 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.
        PAIR Lisp lambda function ? see manual pages 60
        PAIRLIS Lisp lambda function, Host lambda function ? ? 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 Host lambda function ? ?
        PRETTY ? ? ?
        PRINT ? PSEUDO-FUNCTION see manual pages 65, 84
        PROG Host nlambda function ? 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 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 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.
        PROP Lisp lambda function ? FUNCTIONAL see manual pages 59
        QUOTE Lisp lambda function ? see manual pages 10, 22, 71
        QUOTIENT Host lambda function ? 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.
        RANGE Lisp lambda function ? ? ?
        READ Host lambda function ? PSEUDO-FUNCTION An implementation of a Lisp reader sufficient for bootstrapping; not necessarily the final Lisp reader. input should be either a string representation of a LISP expression, or else an input stream. A single form will be read.
        REMAINDER Host lambda function ? ?
        REPEAT Lisp lambda function ? ? ?
        RPLACA Host lambda function ? PSEUDO-FUNCTION 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 Host lambda function ? PSEUDO-FUNCTION 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)
        SEARCH Lisp lambda function ? FUNCTIONAL see manual pages 63
        SET Host lambda function ? PSEUDO-FUNCTION 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 Lisp lambda function, Host lambda function ? ?
        SUB2 Lisp lambda function ? ? ?
        SUBLIS Lisp lambda function ? see manual pages 12, 61
        SUBST Lisp lambda function ? see manual pages 11, 61
        SYSIN Host lambda function ? ? 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 Host lambda function ? ? 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.
        TERPRI ? PSEUDO-FUNCTION see manual pages 65, 84
        TIMES Host lambda function ? ?
        TRACE Host lambda function ? PSEUDO-FUNCTION Add this s to the set of symbols currently being traced. If s is not a symbol or sequence of symbols, does nothing.
        UNION Lisp lambda function ? ? ?
        UNTRACE Host lambda function ? PSEUDO-FUNCTION Remove this s from the set of symbols currently being traced. If s is not a symbol or sequence of symbols, does nothing.
        ZEROP Lisp lambda function ? PREDICATE see manual pages 26, 64
        Function Type Signature Implementation Documentation
        NIL Lisp variable ? see manual pages 22, 69
        T Lisp variable ? see manual pages 22, 69
        F Lisp variable ? see manual pages 22, 69
        ADD1 Host lambda function ? ?
        AND Host lambda function ? PREDICATE 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.
        APPEND Lisp lambda function ? see manual pages 11, 61
        APPLY Host lambda function ? 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.
        ASSOC Lisp lambda function, Host lambda function ? ? 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 Host lambda function ? PREDICATE 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.
        CAR Host lambda function ? Return the item indicated by the first pointer of a pair. NIL is treated specially: the CAR of NIL is NIL.
        CAAAAR Lisp lambda function ? ? ?
        CAAADR Lisp lambda function ? ? ?
        CAAAR Lisp lambda function ? ? ?
        CAADAR Lisp lambda function ? ? ?
        CAADDR Lisp lambda function ? ? ?
        CAADR Lisp lambda function ? ? ?
        CAAR Lisp lambda function ? ? ?
        CADAAR Lisp lambda function ? ? ?
        CADADR Lisp lambda function ? ? ?
        CADAR Lisp lambda function ? ? ?
        CADDAR Lisp lambda function ? ? ?
        CADDDR Lisp lambda function ? ? ?
        CADDR Lisp lambda function ? ? ?
        CADR Lisp lambda function ? ? ?
        CDAAAR Lisp lambda function ? ? ?
        CDAADR Lisp lambda function ? ? ?
        CDAAR Lisp lambda function ? ? ?
        CDADAR Lisp lambda function ? ? ?
        CDADDR Lisp lambda function ? ? ?
        CDADR Lisp lambda function ? ? ?
        CDAR Lisp lambda function ? ? ?
        CDDAAR Lisp lambda function ? ? ?
        CDDADR Lisp lambda function ? ? ?
        CDDAR Lisp lambda function ? ? ?
        CDDDAR Lisp lambda function ? ? ?
        CDDDDR Lisp lambda function ? ? ?
        CDDDR Lisp lambda function ? ? ?
        CDDR Lisp lambda function ? ? ?
        CDR Host lambda function ? Return the item indicated by the second pointer of a pair. NIL is treated specially: the CDR of NIL is NIL.
        CONS Host lambda function ? Construct a new instance of cons cell with this car and cdr.
        CONSP Host lambda function ? ? 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.
        COPY Lisp lambda function ? see manual pages 62
        DEFINE Host lambda function ? PSEUDO-FUNCTION 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.
        DIFFERENCE Host lambda function ? ?
        DIVIDE Lisp lambda function ? see manual pages 26, 64
        DOC Host lambda function ? ? 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.
        EFFACE Lisp lambda function ? PSEUDO-FUNCTION see manual pages 63
        ERROR Host lambda function ? PSEUDO-FUNCTION Throw an error
        EQ Host lambda function ? PREDICATE Returns T if and only if both x and y are bound to the same atom, else NIL.
        EQUAL Host lambda function ? PREDICATE 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
        EVAL Host lambda function ? 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.
        FACTORIAL Lisp lambda function ? ? ?
        FIXP Host lambda function ? PREDICATE ?
        GENSYM Host lambda function ? Generate a unique symbol.
        GET Host lambda function ? 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 Host lambda function ? PREDICATE ?
        INTEROP Host lambda function ? ? ?
        INTERSECTION Lisp lambda function ? ? ?
        LENGTH Lisp lambda function ? see manual pages 62
        LESSP Host lambda function ? PREDICATE ?
        MAPLIST Lisp lambda function ? FUNCTIONAL see manual pages 20, 21, 63
        MEMBER Lisp lambda function ? PREDICATE see manual pages 11, 62
        MINUSP Lisp lambda function ? PREDICATE see manual pages 26, 64
        NOT Lisp lambda function ? PREDICATE see manual pages 21, 23, 58
        NULL Lisp lambda function ? PREDICATE see manual pages 11, 57
        NUMBERP Host lambda function ? PREDICATE ?
        OBLIST Host lambda function ? 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.
        ONEP Lisp lambda function ? PREDICATE see manual pages 26, 64
        OR Host lambda function ? PREDICATE 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.
        PAIR Lisp lambda function ? see manual pages 60
        PAIRLIS Lisp lambda function, Host lambda function ? ? 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 Host lambda function ? ?
        PRETTY ? ? ?
        PRINT ? PSEUDO-FUNCTION see manual pages 65, 84
        PROG Host nlambda function ? 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 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 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.
        PROP Lisp lambda function ? FUNCTIONAL see manual pages 59
        QUOTE Lisp lambda function ? see manual pages 10, 22, 71
        QUOTIENT Host lambda function ? 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.
        RANGE Lisp lambda function ? ? ?
        READ Host lambda function ? PSEUDO-FUNCTION An implementation of a Lisp reader sufficient for bootstrapping; not necessarily the final Lisp reader. input should be either a string representation of a LISP expression, or else an input stream. A single form will be read.
        REMAINDER Host lambda function ? ?
        REPEAT Lisp lambda function ? ? ?
        RPLACA Host lambda function ? PSEUDO-FUNCTION 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 Host lambda function ? PSEUDO-FUNCTION 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)
        SEARCH Lisp lambda function ? FUNCTIONAL see manual pages 63
        SET Host lambda function ? PSEUDO-FUNCTION 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 Lisp lambda function, Host lambda function ? ?
        SUB2 Lisp lambda function ? ? ?
        SUBLIS Lisp lambda function ? see manual pages 12, 61
        SUBST Lisp lambda function ? see manual pages 11, 61
        SYSIN Host lambda function ? ? 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 Host lambda function ? ? 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.
        TERPRI ? PSEUDO-FUNCTION see manual pages 65, 84
        TIMES Host lambda function ? ?
        TRACE Host lambda function ? PSEUDO-FUNCTION Add this s to the set of symbols currently being traced. If s is not a symbol or sequence of symbols, does nothing.
        UNION Lisp lambda function ? ? ?
        UNTRACE Host lambda function ? PSEUDO-FUNCTION Remove this s from the set of symbols currently being traced. If s is not a symbol or sequence of symbols, does nothing.
        ZEROP Lisp lambda function ? PREDICATE see manual pages 26, 64

        Functions described as ‘Lisp function’ above are defined in the default sysout file, resources/lisp1.5.lsp, which will be loaded by default unless you specify another initfile on the command line.

        Functions described as ‘Host function’ are implemented in Clojure, but if you’re brave you can redefine them in Lisp and the Lisp definitions will take precedence over the Clojure implementations.

        -

        Architectural plan

        +

        Architectural plan

        Not everything documented in this section is yet built. It indicates the direction of travel and intended destination, not the current state.

        -

        resources/lisp1.5.lsp

        +

        resources/lisp1.5.lsp

        The objective is to have within resources/lisp1.5.lsp, all those functions defined in the Lisp 1.5 Programmer’s Manual which can be implemented in Lisp.

        This means that, while Beowulf is hosted on Clojure, all that would be required to rehost Lisp 1.5 on a different platform would be to reimplement

          -
        • bootstrap.clj
          • -
        • host.clj
          • -
        • read.clj
          • +
        • bootstrap.clj
          • +
        • host.clj
          • +
        • read.clj

        The objective this is to make it fairly easy to implement Lisp 1.5 on top of any of the many Make A Lisp implementations.

        -

        beowulf/boostrap.clj

        +

        beowulf/boostrap.clj

        This file is essentially 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, to bootstrap the full Lisp 1.5 interpreter.

        In addition it contains the function INTEROP, which allows host language functions to be called from Lisp.

        -

        beowulf/host.clj

        +

        beowulf/host.clj

        This file 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/read.clj

        +

        beowulf/read.clj

        This file 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. -
        2. It treats everything between a double semi-colon and an end of line as a comment, as most modern Lisps do; but I do not believe Lisp 1.5 had this feature.
          3. +
        3. 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;
          4. +
        4. It treats everything between a double semi-colon and an end of line as a comment, as most modern Lisps do; but I do not believe Lisp 1.5 had this feature.
        -

        Commentary

        -

        What’s surprised me in working on this is how much more polished Lisp 1.5 is than legend had led me to believe. The language is remarkably close to Portable Standard Lisp which is in my opinion one of the best and most usable early Lisp implementations.

        +

        Commentary

        +

        What’s surprised me in working on this is how much more polished Lisp 1.5 is than legend had led me to believe. The language is remarkably close to Portable Standard Lisp which is in my opinion one of the best and most usable early Lisp implementations.

        What’s even more surprising is how faithful a reimplementation of Lisp 1.5 the first Lisp dialect I learned, Acornsoft Lisp, turns out to have been.

        I’m convinced you could still use Lisp 1.5 for interesting and useful software (which isn’t to say that modern Lisps aren’t better, but this is software which is almost sixty years old).

        -

        Installation

        +

        Installation

        Download the latest release ‘uberjar’ and run it using:

        -
            java -jar <path name of uberjar>
+
            java -jar <path name of uberjar>
 
        
 
        Or clone the source and build it using:
        
-
            lein uberjar`
+
            lein uberjar`
 
        
 
        To build it you will require to have Leiningen installed.
        
-
        Input/output
        
+
        Input/output
        
 
        Lisp 1.5 greatly predates modern computers. It had a facility to print to a line printer, or to punch cards on a punch-card machine, and it had a facility to read system images in from tape; but there’s no file I/O as we would currently understand it, and, because there are no character strings and the valid characters within an atom are limited, it isn’t easy to compose a sensible filename.
        
 
        I’ve provided two functions to work around this problem.
        
-
        SYSOUT
        
+
        SYSOUT
        
 
        SYSOUT dumps the global object list to disk as a single S Expression (specifically: an association list). This allows you to persist your session, with all your current work, to disk. The function takes one argument, expected to be a symbol, and, if that argument is provided, writes a file whose name is that symbol with .lsp appended. If no argument is provided, it will construct a filename comprising the token Sysout, followed by the current date, followed by .lsp. In either case the file will be written to the directory given in the FILEPATH argument at startup time, or by default the current directory.
        
 
        Obviously, SYSOUT may be called interactively (and this is the expected practice).
        
-
        SYSIN
        
-
        SYSIN reads a file from disk and overwrites the global object list with its contents. The expected practice is that this will be a file created by SYSOUT. A command line flag --read is provided so that you can specify 
        
-
        Learning Lisp 1.5
        
+
        SYSIN
        
+
        SYSIN reads a file from disk and overwrites the global object list with its contents. The expected practice is that this will be a file created by SYSOUT. A command line flag --read is provided so that you can specify
        
+
        Learning Lisp 1.5
        
 
        The Lisp 1.5 Programmer's Manual is still in print, ISBN 13 978-0-262-13011-0; but it’s also available online.
        
-
        Other Lisp 1.5 resources
        
+
        Other Lisp 1.5 resources
        
 
        The main resource I’m aware of is the Software Preservation Society’s site, here. It has lots of fascinating stuff including full assembler listings for various obsolete processors, but I failed to find the Lisp source of Lisp functions as a text file, which is why resources/lisp1.5.lsp is largely copytyped and reconstructed from the manual.
        
-
        Other implementations
        
+
        Other implementations
        
 
        There’s an online (browser native) Lisp 1.5 implementation here (source code here). It even has a working compiler!
        
-
        History resources
        
+
        History resources
        
 
        I’m compiling a list of links to historical documents on Lisp 1.5.
        
-
        License
        
-
        Copyright © 2019 Simon Brooke. Licensed under the GNU General Public License, version 2.0 or (at your option) any later version.
        \ No newline at end of file +

        License

        +

        Copyright © 2019 Simon Brooke. Licensed under the GNU General Public License, version 2.0 or (at your option) any later version.

        +
        \ No newline at end of file diff --git a/docs/codox/mexpr.html b/docs/codox/mexpr.html index a4cedae..16334dd 100644 --- a/docs/codox/mexpr.html +++ b/docs/codox/mexpr.html @@ -1,16 +1,16 @@ -Interpreting M-Expressions

        Project

        Topics

        Namespaces

        Interpreting M-Expressions

        +Interpreting M-Expressions

        Project

        Topics

        Namespaces

        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.

        Consequently, the Beowulf parser can parse the M-Expression grammar as stated in the manual, and generate S-Expressions from it according to the table specified on page 10 of the manual.

        There are two problems with this.

        -

        Problems with interpreting M-Expressions

        -

        Generating idiomatic Lisp

        +

        Problems with interpreting M-Expressions

        +

        Generating idiomatic Lisp

        In the M-Expression notation, a lower case character or sequence of characters represents a variable; an upper case character represents a constant. As the manual says,

        -

        2 . The obvious translation of letting a constant translate into itself will not work. Since the translation of x is X, the translation of X must be something else to avoid ambiguity. The solution is to quote it. Thus X is translated into (QUOTE X).

        +

        2 . The obvious translation of letting a constant translate into itself will not work. Since the translation of x is X, the translation of X must be something else to avoid ambiguity. The solution is to quote it. Thus X is translated into (QUOTE X).

        Thus, necessarily, the translation of a constant must always be quoted. In practice, key constants in Lisp such as T are bound to themselves, so it is idiomatic in Lisp, certainly in the way we have learned to use it, to write, for example,

        (SET (QUOTE NULL) 
@@ -32,11 +32,12 @@
 
        Is the value of NIL the atom NIL, or is it the empty list ()? If the former, then the translation from the M-Expression above is correct. However, that means that recursive functions which recurse down a list seeking the end will fail. So the latter must be the case.
        
 
        NULL is described thus (Ibid, p11):
        
 
        
-  
        This is a predicate useful for deciding when a list is exhausted. It is true if and only if its argument is NIL.
        
+
        This is a predicate useful for deciding when a list is exhausted. It is true if and only if its argument is NIL.
        
 
        
 
        NIL is used explicitly in an M-Expression for example in the definition of intersection (Ibid, p15).
        
 
        I think there is an ambiguity in referencing constants which are not bound to themselves in the M-Expression notation as given in the manual. This is particularly problematic with regards to NIL and F, but there may be others instances.
        
 
        However, so long as F is bound to NIL, and NIL is also bound to NIL (both of which are true by default, although changeable by the user), and NIL is the special marker used in the CDR of the last cons cell of a flat list, this is a difference which in practice does not make a difference. I still find it worrying, though, that rebinding variables could lead to disaster.
        
-
        Curly braces
        
+
        Curly braces
        
 
        The use of curly braces is not defined in the grammar as stated on page 10. They are not used in the initial definition of APPLY on page 13, but they are used in the more developed restatement on page 70. I believe they are to be read as indicating a section of assembly code to be assembled by the Lisp Assembly Program – but I don’t find the exposition here particularly clear and I’m not sure of this.
        
-
        Consequently, the M-Expression interpreter in Beowulf does not interpret curly braces.
        \ No newline at end of file +

        Consequently, the M-Expression interpreter in Beowulf does not interpret curly braces.

        +
        \ No newline at end of file diff --git a/docs/codox/values.html b/docs/codox/values.html index 0cfcf99..d156cd7 100644 --- a/docs/codox/values.html +++ b/docs/codox/values.html @@ -1,27 +1,29 @@ -The properties of the system, and their values

        Project

        Topics

        Namespaces

        The properties of the system, and their values

        -

        here be dragons

        +The properties of the system, and their values

        Project

        Topics

        Namespaces

        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 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

        -

        Lisp was originally written on an IBM 704 computer at Massachusetts Institute of Technology, almost seventy years ago.

        +

        History

        +

        Lisp was originally written on an IBM 704 computer at Massachusetts Institute of Technology, almost seventy years ago.

        The machine had registers which were not eight, or sixteen, or thirty two, or sixty four, bits wide, or any other number which would seem rational to modern computer scientists, but thirty six. Myth - folk memory - tells us that the machine’s memory was arranged in pages. As I understand it (but this truly is folk memory) the offset within the page of the word to be fetched was known as the ‘decrement’, while the serial number of the page in the addressing sequence was known as the ‘address’. To fetch a word from memory, you first had to select the page using the ‘address’, and secondly the word itself using the ‘decrement’. So there were specific instructions for selecting the address, and the decrement, from the register separately.

        There were two mnemonics for the machine instructions used to access the content of these registers, respectively:

        -
        CAR
        -
        -

        Contents of the Address part of Register; and

        -
        CDR
        -
        -

        Contents of the Decrement part of Register.

        +
        CAR
        +
        +

        Contents of the Address part of Register; and

        +
        +
        CDR
        +
        +

        Contents of the Decrement part of Register.

        +

        Is this actually true?

        I think so. If you look at page 80 of the Lisp 1 Programmer’s Manual, you will see this:

        -
        TEN                       (the TEN-Mode is entered)
+
        TEN                       (the TEN-Mode is entered)
 
 O CAR   (((A,B),C)) () \
                         |
@@ -38,23 +40,23 @@ O14 (read lines O and 1)
 
        
 
        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.
        
+
        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. 
        
+
        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
        
+
        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
        
-
        Grey Anatomy
        
-
        The Object List
        
+
        Grey Anatomy
        
+
        The Object List
        
 
        Lisp keeps track of values by associating them with names. It does so by having what is in effect a global registry of all the names it knows to which values are attached. This being a list processing language, that was of course, in early Lisps, a list: a single specialised first class list known as the ‘object list’, or oblist for short.
        
-
        Of course, a list need not just be a list of single items, it can be a list of pairs: it can be a list of pairs of the form (name . value). Hold onto that, because I want to talk about another fundamental part of a working Lisp system, the stack. 
        
-
        The Stack
        
+
        Of course, a list need not just be a list of single items, it can be a list of pairs: it can be a list of pairs of the form (name . value). Hold onto that, because I want to talk about another fundamental part of a working Lisp system, the stack.
        
+
        The Stack
        
 
        Considering the case of pure interpreter first, let’s think about how a function keeps track of the data it’s working on. In order to do its work, it probably calls other functions, to which it passes off data, and they in turn probably call further functions. So, when control returns to our first function, how does it know where its data is? The answer is that each function pushes its argument bindings onto the stack when it starts work, and pops them off again when it exits. So when control returns to a function, its own data is still on the top of the stack. Or, to be precise, actually it doesn’t; in practice the function EVAL does it for each function in turn. But it doesn’t matter: it gets done.
        
 
        What is this stack? Well, it’s a list of (name . value) pairs. At least, it is in pure Lisps; Clojure, because it runs on the Java Virtual Machine and interoperates with other software running on the JVM, uses the JVM stack which is a permanently reserved vector of memory never used for anything else. Consequently it cannot be very large; and the consequence of that is that it’s very easy to crash JVM programs because they’ve run out of stack space.
        
 
        The advantage of organising your stack as a vector is that on average it’s usually slightly more memory efficient, and that it’s somewhat faster to access. The disadvantage is you need a contiguous block of memory for it, and once you’ve run out, you’ve at best lost both those advantages but in the normal case your program just crashes. Also, the memory you’ve reserved for the stack isn’t available for any other use, even during the most of the time that the stack isn’t using most of it. So of course there’s a temptation to keep the amount reserved for the stack as small as possible.
        
@@ -62,7 +64,7 @@ O14 (read lines O and 1)
 
        The advantage of organising your stack as a list is that, while there is any memory left on the machine at all, you cannot run out of stack.
        
 
        ### The Spine
        
 
        So, there’s an object list where you associate names and values, and there’s a stack where you associate names and values. But, why do they have to be different? And why do you have to search in two places to find the value of a name?
        
-
        The answer is – or it was, and arguably it should be – that you don’t. The stack can simply be pushed onto the front of the object list. This has multiple advantages. The first and most obvious is that you only have to search in one place for the value associated with a name. 
        
+
        The answer is – or it was, and arguably it should be – that you don’t. The stack can simply be pushed onto the front of the object list. This has multiple advantages. The first and most obvious is that you only have to search in one place for the value associated with a name.
        
 
        The second is more subtle: a function can mask a variable in the object list by binding the same name to a new value, and the functions to which it then calls will only see that new value. This is useful if, for example, printed output is usually sent to the user’s terminal, but for a particular operation you want to send it to a line printer or to a file on disk. You simply rebind the name of the standard output stream to your chosen output stream, and call the function whose output you want to redirect.
        
 
        So, in summary, there’s a lot of merit in making the stack and the object list into a single central structure on which the architecture of our Lisp system is built. But there’s more we need to record, and it’s important.
        
 
        ### Fields and Properties
        
@@ -72,35 +74,35 @@ O14 (read lines O and 1)
 
        But if instead of storing a table for each sort of thing on which we hold data, and a row in that table for each item of that sort on which we store data, we simply tagged each thing on which we hold data with those things which are interesting about them? We could tag my friend Lucy with the fact she’s on pilgrimage, and what her pilgrimage route is. Those aren’t things we need to know about most people, it would be absurdly wasteful to add a column to a person table to record pilgrimage route. So in a conventional data system we would lose that data.
        
 
        Lisp has had, right back from the days of Lisp 1.5 – so, for sixty-five years – a different solution. We can give every symbol arbitrarily many, arbitrarily different, properties. A property is a (name . value) pair. We don’t have to store the same properties for every object. The values of the properties don’t have to have a fixed size, and they don’t have to take up space they don’t need. It’s like having a table with as many fields as we choose, and being able to add more fields at any time.
        
 
        So, in summary, I knew, in building Beowulf, that I’d have to implement property lists. I just didn’t know how I was going to do it.
        
-
        Archaeology
        
+
        Archaeology
        
 
        What I’m doing with Beowulf is trying to better understand the history of Lisp by reconstructing a very early example; in this case, Lisp 1.5, from about 1962, or sixty one years ago.
        
 
        I had had the naive assumption that entries on the object list in early Lisps had their CAR pointing to the symbol and their CDR pointing to the related value. Consequently, in building beowulf, I could not work out where the property list went. More careful reading of the text implies, but does not explicitly state, that my naive assumption is wrong.
        
 
        Instead, it appears that the CAR points to the symbol, as expected, but the CDR points to the property list; and that on the property list there are privileged properties at least as follows:
        
 
        
-  
        APVAL
        
-  
        the simple straightforward ordinary value of the symbol, considered as a variable;
        
-  
        EXPR
        
-  
        the definition of the function considered as a normal lambda expression (arguments to be evaluated before applying);
        
-  
        FEXPR
        
-  
        the definition of a function which should be applied to unevaluated arguments (what InterLisp and Portable Standard Lisp would call ‘nlambda’);
        
-  
        SUBR
        
-  
        the definition of a compiled subroutine which should be applied to evaluated arguments;
        
-  
        FSUBR
        
-  
        the definition of a compiled subroutine which should be applied to unevaluated arguments.
        
+
        APVAL
        
+
        the simple straightforward ordinary value of the symbol, considered as a variable;
        
+
        EXPR
        
+
        the definition of the function considered as a normal lambda expression (arguments to be evaluated before applying);
        
+
        FEXPR
        
+
        the definition of a function which should be applied to unevaluated arguments (what InterLisp and Portable Standard Lisp would call ‘nlambda’);
        
+
        SUBR
        
+
        the definition of a compiled subroutine which should be applied to evaluated arguments;
        
+
        FSUBR
        
+
        the definition of a compiled subroutine which should be applied to unevaluated arguments.
        
 
        
 
        I think there was also another privileged property value which contained the property considered as a constant, but I haven’t yet confirmed that.
        
 
        From this it would seem that Lisp 1.5 was not merely a ‘Lisp 2’ but in fact a ‘Lisp 6’, with six effectively first class namespaces. In fact it’s not as bad as that, because of the way EVAL is evaluated.
        
 
        Essentially the properties are tried in turn, and only the first value found is used. Thus the heirarchy is
        
 
          
-  
        1. APVAL
          2. 
-  
        2. EXPR
          3. 
-  
        3. FEXPR
          4. 
-  
        4. SUBR
          5. 
-  
        5. FSUBR
          6. 
+
        6. APVAL
          7. 
+
        7. EXPR
          8. 
+
        8. FEXPR
          9. 
+
        9. SUBR
          10. 
+
        10. FSUBR
          11. 
 
        
 
        This means that, while the other potential values can be retrieved from the property list, interpreted definitions (if present) will always be preferred to uninterpreted definitions, and lambda function definitions (which evaluate their arguments), where present, will always be preferred to non-lamda definitions, which don’t.
        
 
        BUT NOTE THAT the APVAL value is sought only when seeking a variable value for the symbol, while the others are only when seeking a function value, so Lisp 1.5 is a ‘Lisp 2’, not a ‘Lisp 1’. I strongly believe that this is wrong: a function is a value, and should be treated as such. But at the same time I do acknowledge the benefit of being able to store both source and compiled forms of the function as properties of the same symbol.
        
-
        The persistent problem
        
+
        The persistent problem
        
 
        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?
        
@@ -108,50 +110,50 @@ O14 (read lines O and 1)
 
        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. 
-  
        2. To implement PUT and GET in Lisp, and have them destructively modify the working copy of the object list.
          3. 
+
        3. 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.
          4. 
+
        4. To implement PUT and GET in Lisp, and have them destructively modify the working copy of the object list.
          5. 
 
        
 
        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
        
-
        Firstly, are they association lists comprising dotted pairs of (property-name . value), i.e.: 
        
+
        How property lists should work
        
+
        I’m still not fully understanding how property lists in Lisp 1.5 are supposed to work.
        
+
        List format
        
+
        Firstly, are they association lists comprising dotted pairs of (property-name . value), i.e.:
        
 
        
-  
        ((property-name1 . value1) (property-name2 . value2) … (property-namen . valuen))
        
+
        ((property-name1 . value1) (property-name2 . value2) … (property-namen . valuen))
        
 
        
 
        I have assumed so, and that is what I presently intend to implement, but the diagrams on pages 59 and 60 seem rather to show a flat list of interleaved names and values:
        
 
        
-  
        (property-name1 value1 property-name2 value2 … property-namen valuen)
        
+
        (property-name1 value1 property-name2 value2 … property-namen valuen)
        
 
        
 
        I cannot see what the benefit of this latter arrangement is, and I’m unwilling to do it, although I think it may be what was done. But if it was done that way, why was it done that way? These were bright people, and they certainly knew about association lists. So… I’m puzzled.
        
-
        Function signatures
        
+
        Function signatures
        
 
        To associate the value of a property with a symbol, we need three things: we need the symbol, we need the property name, and we need the value. For this reason, Portable Standard Lisp and others has a function put with three arguments:
        
 
        
-  
        (Put U:id IND:id PROP:any): any The indicator IND with the property PROP is placed on the property list of the id U. If the action of Put occurs, the value of PROP is returned. If either of U and IND are not ids the type mismatch error occurs and no property is placed. (Put 'Jim 'Height 68) The above returns 68 and places (Height . 68) on the property list of the id Jim
        
+
        (Put U:id IND:id PROP:any): any The indicator IND with the property PROP is placed on the property list of the id U. If the action of Put occurs, the value of PROP is returned. If either of U and IND are not ids the type mismatch error occurs and no property is placed. (Put 'Jim 'Height 68) The above returns 68 and places (Height . 68) on the property list of the id Jim
        
 
        
 
        Cambridge Lisp is identical to this except in lower case. InterLisp and several others have putprop:
        
 
        
-  
        (PUTPROP ATM PROP VAL) [Function] Puts the property PROP with value VAL on the property list of ATM. VAL replaces any previous value for the property PROP on this property list. Returns VAL.
        
+
        (PUTPROP ATM PROP VAL) [Function] Puts the property PROP with value VAL on the property list of ATM. VAL replaces any previous value for the property PROP on this property list. Returns VAL.
        
 
        
 
        The execrable Common Lisp uses its execrable macro setf but really the less said about that the better.
        
-
        So I was looking for a function of three arguments to set properties, and I didn’t find one. 
        
+
        So I was looking for a function of three arguments to set properties, and I didn’t find one.
        
 
        There’s a function DEFINE which takes one argument, an association list of pairs:
        
-
        	(function-name . function-definition)`
+
        	(function-name . function-definition)`
 
        
 
        So how does that work, if what it’s doing is setting properties? If all you’re passing is pairs of name and definition, where does the property name come from?
        
 
        The answer is as follows, taken from the manual:
        
 
        
-  
        define [x] : EXPR pseudo-function
        
-  
        The argument of define, x, is a list of pairs
        
-  
        
-    
        ((ul vl) (u2 v2) … (un vn))
        
-  
        
-  
        where each u is a name and each v is a λ-expression for a function . For each pair, define puts an EXPR on the property list for u pointing to v. The function of define puts things on at the front of the property list. The value of define is the list of us.
        
+
        define x : EXPR pseudo-function
        
+
        The argument of define, x, is a list of pairs
        
+
        
+
        ((ul vl) (u2 v2) … (un vn))
        
+
        
+
        where each u is a name and each v is a λ-expression for a function . For each pair, define puts an EXPR on the property list for u pointing to v. The function of define puts things on at the front of the property list. The value of define is the list of us.
        
 
        
 
        So, in fact, the value of the property being set by define is fixed: hard wired, not parameterised. That seems an astonishing decision, until you realise that Lisp 1.5’s creators weren’t creating their functions one by one, in a playful exploration with their system, but entering them in a batch.
        
-
        Learning by doing
        
+
        Learning by doing
        
 
        In fact, when I got over my surprise, I realised that that (name . function-definition) list is actually very much like this, which is an excerpt from a sysout from a Beowulf prototype:
        
-
        (...
+
        (...
 	(MAPLIST LAMBDA (L F) 
            (COND ((NULL L) NIL) 
                  ((QUOTE T) (CONS (F (CAR L)) (MAPLIST (CDR L) F)))))
@@ -172,81 +174,45 @@ O14 (read lines O and 1)
 
        Because the point of a sysout is you don’t write it. The point about the REPL – the Read Eval Print Loop which is the heart of the interactive Lisp development cycle, where you sit playing with things and fiddling with them interactively, and where when one thing works you get onto the next without bothering to make some special effort to record it.
        
 
        The point of a sysout is that, at the end of the working day, you invoke one function
        
 
-  
-    
-      
-      
-      
-      
-      
-    
-  
-  
-    
-      
-      
-      
-      
-      
-    
-  
+
+
+
+
+
+
        Function Type Signature Implementation Documentation 
        SYSOUT Host function (SYSOUT); (SYSOUT FILEPATH) SUBR 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. 
         Function  Type  Signature  Implementation  Documentation 
         SYSOUT        Host function   (SYSOUT); (SYSOUT FILEPATH)  SUBR     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. 
        
 
        
 
        At the start of the next working day, you load that sysout in and continue your session.
        
 
        The sysout captures the entire working state of the machine. No-one types it in, as an operation in itself. Instead, data structures – corpuses of functions among them – simply build up on the object list almost casually, as a side effect of the fact that you’re enjoying exploring your problem and finding elegant ways of solving it. So SYSOUT and SYSIN seem to me, as someone who all his adult life has worked with Lisp interactively, as just an automatic part of the cycle of the day.
        
-
        The process of discovery
        
-
        The thing is, I don’t think anyone is ever going to use Beowulf the way Lisp 1.5 was used. I mean, probably, no one is ever going to use Beowulf at all; but if they did they wouldn’t use Beowulf the way Lisp 1.5 was used. 
        
+
        The process of discovery
        
+
        The thing is, I don’t think anyone is ever going to use Beowulf the way Lisp 1.5 was used. I mean, probably, no one is ever going to use Beowulf at all; but if they did they wouldn’t use Beowulf the way Lisp 1.5 was used.
        
 
        I’m a second generation software person. I have worked, in my career, with two people who personally knew and had worked with Alan Turing. I have worked with, and to an extent been mentored by, Chris Burton, who in his apprenticeship was part of the team that built the Manchester Mark One, and who in his retirement led the team who restored it. But I never knew the working conditions they were accustomed to. In my first year at university we used card punches, and, later, when we had a bit of seniority, teletypewriters (yes, that’s what TTY stands for), but by the time I’d completed my undergraduate degree and become a research associate I had a Xerox 1108 workstation with a huge bitmapped graphic screen, and an optical mouse, goddamit, running InterLisp, all to myself.
        
 
        People in the heroic age did not have computers all to themselves. They did not have terminals all to themselves. They didn’t sit at a terminal experimenting in the REPL. They wrote their algorithms in pencil on paper. When they were certain they’d got it right, they’d use a card punch to punch a deck of cards carrying the text of the program, and then they were certain they’d got that right, they’d drop it into the input hopper. Some time later their batch would run, and the operator would put the consequent printout into their pigeon hole for them to collect.
        
 
        (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:
        
+
        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) 
        
+
        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.
        
+
        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?
        
@@ -254,10 +220,11 @@ O14 (read lines O and 1)
 
        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.
        
+
        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. 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 +

        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 20483ff..64742f2 100644 --- a/project.clj +++ b/project.clj @@ -19,11 +19,12 @@ [environ "1.2.0"] [instaparse "1.4.12"] [org.jline/jline "3.23.0"] - [rhizome "0.2.9"] ;; not needed in production builds + [com.github.seancorfield/expectations "2.0.165"] + ;; [rhizome "0.2.9"] ;; not needed in production builds ] :main beowulf.core :plugins [[lein-cloverage "1.2.2"] - [lein-codox "0.10.7"] + [lein-codox "0.10.8"] [lein-environ "1.1.0"]] :profiles {:jar {:aot :all} :uberjar {:aot :all} diff --git a/src/beowulf/host.clj b/src/beowulf/host.clj index 56fae9a..81e17ba 100644 --- a/src/beowulf/host.clj +++ b/src/beowulf/host.clj @@ -441,7 +441,7 @@ recurse down the list two entries at a time to avoid confusing names with values." [target plist] - (if (and (instance? ConsCell plist)(even? (count plist))) + (if (and (instance? ConsCell plist) (even? (count plist))) (cond (= plist NIL) NIL (= (first plist) target) plist :else (hit-or-miss-assoc target (CDDR plist))) @@ -516,9 +516,10 @@ `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." [a-list indicator] - (map - #(PUT (CAR %) indicator (CDR %)) - a-list)) + (doall + (map + #(when (PUT (CAR %) indicator (CDR %)) (CAR %)) + a-list))) (defn DEFINE "Bootstrap-only version of `DEFINE` which, post boostrap, can be overwritten diff --git a/test/beowulf/host_test.clj b/test/beowulf/host_test.clj index 5f73ea8..4d43b1e 100644 --- a/test/beowulf/host_test.clj +++ b/test/beowulf/host_test.clj @@ -1,11 +1,14 @@ (ns beowulf.host-test - (:require [beowulf.cons-cell :refer [F make-beowulf-list T]] - [beowulf.host :refer [CDR DIFFERENCE GENSYM GET NUMBERP PLUS PUT - RPLACA RPLACD TIMES]] + (:require [beowulf.cons-cell :refer [F make-beowulf-list make-cons-cell T]] + [beowulf.host :refer [ADD1 AND CADDDR CAR CDR DEFINE DIFFERENCE + ERROR FIXP GREATERP lax? LESSP NILP NULL + NUMBERP OR PLUS RPLACA RPLACD SUB1 TIMES uaf]] [beowulf.io :refer [SYSIN]] - [beowulf.oblist :refer [NIL]] + [beowulf.oblist :refer [*options* NIL]] [beowulf.read :refer [gsp]] - [clojure.test :refer [deftest is testing use-fixtures]])) + [clojure.test :refer [deftest is testing use-fixtures]] + [expectations.clojure.test + :refer [defexpect expect more-> more-of]])) (use-fixtures :once (fn [f] (try (when (SYSIN "resources/lisp1.5.lsp") @@ -20,31 +23,44 @@ (deftest destructive-change-test (testing "RPLACA" (let - [l (make-beowulf-list '(A B C D E)) - target (CDR l) - expected "(A F C D E)" - actual (do (RPLACA target 'F) (print-str l))] + [l (make-beowulf-list '(A B C D E)) + target (CDR l) + expected "(A F C D E)" + actual (do (RPLACA target 'F) (print-str l))] (is (= actual expected))) (is (thrown-with-msg? - Exception - #"Un-ġefōg þing in RPLACA.*" - (RPLACA (make-beowulf-list '(A B C D E)) "F")) + Exception + #"Un-ġefōg þing in RPLACA.*" + (RPLACA (make-beowulf-list '(A B C D E)) "F")) "You can't represent a string in Lisp 1.5") (is (thrown-with-msg? - Exception - #"Uncynlic miercels in RPLACA.*" - (RPLACA '(A B C D E) 'F)) - "You can't RPLACA into anything which isn't a MutableSequence.") - ) - (testing "RPLACA" + Exception + #"Uncynlic miercels in RPLACA.*" + (RPLACA '(A B C D E) 'F)) + "You can't RPLACA into anything which isn't a MutableSequence.")) + (testing "RPLACD" (let - [l (make-beowulf-list '(A B C D E)) - target (CDR l) - expected "(A B . F)" - actual (do (RPLACD target 'F) (print-str l))] + [l (make-beowulf-list '(A B C D E)) + target (CDR l) + expected "(A B . F)" + actual (do (RPLACD target 'F) (print-str l))] (is (= actual expected))) - ) - ) + (let + [l (make-beowulf-list '(A B C D E)) + target (CDR l) + expected "(A B)" + actual (do (RPLACD target NIL) (print-str l))] + (is (= actual expected))) + (is (thrown-with-msg? + Exception + #"Un-ġefōg þing in RPLACD.*" + (RPLACD (make-beowulf-list '(A B C D E)) :a)) + "You can't represent a keyword in Lisp 1.5") + (is (thrown-with-msg? + Exception + #"Uncynlic miercels in RPLACD.*" + (RPLACD "ABCDE" 'F)) + "You can't RPLACD into anything which isn't a MutableSequence."))) (deftest numberp-tests (testing "NUMBERP" @@ -71,13 +87,171 @@ (let [expected 3.5 actual (PLUS 1.25 9/4)] (is (= actual expected)) + (is (float? actual))) + (let [expected 3.5 + actual (PLUS -2.5 6)] + (is (= actual expected) "Negative numbers are cool.") (is (float? actual)))) (testing "TIMES" (let [expected 6 actual (TIMES 2 3)] + (is (= actual expected))) + (let [expected 2.5 + actual (TIMES 5 0.5)] (is (= actual expected)))) (testing "DIFFERENCE" (let [expected -1 actual (DIFFERENCE 1 2)] + (is (= actual expected))) + (let [expected (float 0.1) + actual (DIFFERENCE -0.1 -0.2)] + (is (= actual expected)))) + (testing "ADD1" + (let [expected -1 + actual (ADD1 -2)] + (is (= actual expected))) + (let [expected (float 3.5) + actual (ADD1 2.5)] + (is (= actual expected)))) + (testing "SUB1" + (let [expected -3 + actual (SUB1 -2)] + (is (= actual expected))) + (let [expected (float 1.5) + actual (SUB1 2.5)] (is (= actual expected))))) +(deftest laxness + (testing "lax" + (let [expected true + actual (lax? 'Test)] + (is (= actual expected) "Pass, the Queen's Cat, and all's well"))) + (testing "strict" + (binding [*options* (assoc *options* :strict true)] + (is (thrown-with-msg? Exception #".*ne āfand innan Lisp 1.5" (lax? 'Test)))))) + +(deftest access-tests + (testing "primitive access" + (let [cell (make-cons-cell 1 7)] + (let [expected 1 + actual (CAR cell)] + (is (= actual expected))) + (let [expected 7 + actual (CDR cell)] + (is (= actual expected)))) + (is (thrown-with-msg? Exception #".*Ne can tace CAR of.*" (CAR 7))) + (is (thrown-with-msg? Exception #".*Ne can tace CDR of.*" (CDR 'A))) + (is (thrown-with-msg? Exception #".*Ne liste.*" (CADDDR "Foo"))) + (is (thrown-with-msg? Exception #".*uaf: unexpected letter in path.*" + (uaf (make-beowulf-list '(A B C D)) + '(\d \a \z \e \d)))))) + +(deftest misc-predicate-tests + (testing "NULL" + (let [expected T + actual (NULL NIL)] + (is (= actual expected))) + (let [expected F + actual (NULL (make-beowulf-list '(A B C)))] + (is (= actual expected)))) + (testing "NILP" + (let [expected T + actual (NILP NIL)] + (is (= actual expected))) + (let [expected NIL + actual (NILP (make-beowulf-list '(A B C)))] + (is (= actual expected)))) + (testing "AND" + (let [expected T + actual (AND)] + (is (= actual expected))) + (let [expected T + actual (AND T T)] + (is (= actual expected))) + (let [expected T + actual (AND T T T)] + (is (= actual expected))) + (let [expected T + actual (AND 1 'A (make-beowulf-list '(A B C)))] + (is (= actual expected))) + (let [expected F + actual (AND NIL)] + (is (= actual expected))) + (let [expected F + actual (AND T T F T)] + (is (= actual expected)))) + (testing "OR" + (let [expected F + actual (OR)] + (is (= actual expected))) + (let [expected T + actual (OR NIL T)] + (is (= actual expected))) + (let [expected T + actual (OR T F T)] + (is (= actual expected))) + (let [expected T + actual (OR 1 F (make-beowulf-list '(A B C)))] + (is (= actual expected))) + (let [expected F + actual (OR NIL)] + (is (= actual expected))) + (let [expected F + actual (OR NIL F)] + (is (= actual expected)))) + (testing "FIXP" + (let [expected F + actual (FIXP NIL)] + (is (= actual expected))) + (let [expected F + actual (FIXP 'A)] + (is (= actual expected))) + (let [expected F + actual (FIXP 3.2)] + (is (= actual expected))) + (let [expected T + actual (FIXP 7)] + (is (= actual expected)))) + (testing "LESSP" + (let [expected F + actual (LESSP 7 3)] + (is (= actual expected))) + (let [expected T + actual (LESSP -7 3.5)] + (is (= actual expected))) + (let [expected F + actual (LESSP 3.14 3.14)] + (is (= actual expected)))) + (testing "GREATERP" + (let [expected T + actual (GREATERP 7 3)] + (is (= actual expected))) + (let [expected F + actual (GREATERP -7 3.5)] + (is (= actual expected))) + (let [expected F + actual (GREATERP 3.14 3.14)] + (is (= actual expected))))) + +;; Really tricky to get DEFINE set up for testing here. It works OK in the +;; REPL, but there's nonsense going on with lazy sequences. Better to +;; reimplement in Lisp. +;; (deftest define-tests +;; (testing "DEFINE" +;; (let [expected "(FF)" +;; actual (str (doall (DEFINE +;; (gsp "((FF LAMBDA (X) (COND ((ATOM X) X) (T (FF (CAR X))))))"))))] +;; (is (= actual expected))))) + +(defexpect error-without-code + (expect (more-> clojure.lang.ExceptionInfo type + (more-of {:keys [:phase :function :args :type :code]} + 'A1 code) ex-data) + (ERROR))) + +(defexpect error-with-code + (let [x 'X1] + (expect (more-> clojure.lang.ExceptionInfo type + (more-of {:keys [:phase :function :args :type :code]} + x code) ex-data) + (ERROR x)))) From e9406d557403726c00137352966d81bcf25df027 Mon Sep 17 00:00:00 2001 From: Simon Brooke Date: Wed, 12 Apr 2023 09:04:44 +0100 Subject: [PATCH 4/4] Very close to working FSUBRs - but not quite there. --- doc/lisp1.5.md | 5 +- resources/lisp1.5.lsp | 12 ++++ resources/sexpr/conc.lsp | 8 ++- src/beowulf/bootstrap.clj | 112 ++++++++++++++++++++++++-------------- src/beowulf/host.clj | 34 +++++++++--- src/beowulf/io.clj | 7 ++- 6 files changed, 126 insertions(+), 52 deletions(-) diff --git a/doc/lisp1.5.md b/doc/lisp1.5.md index 6042cc8..11fe6db 100644 --- a/doc/lisp1.5.md +++ b/doc/lisp1.5.md @@ -1721,6 +1721,7 @@ represented in storage only once, The following simple example has been included to illustrate the exact construction of list structures. Two types of list structures are shown, and a function for deriving one from the other is given in LISP. + We assume that we have a list of the form n, = ((A B C) (D E F),... , (X Y z)), @@ -2709,7 +2710,9 @@ If `deflist` or `define` is used twice on the same object with the same indicato The function attrib concatenates its two arguments by changing the last element of its first argument to point to the second argument. Thus it is commonly used to tack something onto the end of a property list. The value of attrib is the second argument. For example -attrib[~~; (EXPR (LAMBDA (X) (COND ((ATOM X) X) (T (FF (CAR x))))))] +``` +attrib[FF; (EXPR (LAMBDA (X) (COND ((ATOM X) X) (T (FF (CAR x))))))] +``` would put EXPR followed by the LAMBDA expression for FF onto the end of the prop- erty list for FF. diff --git a/resources/lisp1.5.lsp b/resources/lisp1.5.lsp index 09bf054..ad537a5 100644 --- a/resources/lisp1.5.lsp +++ b/resources/lisp1.5.lsp @@ -25,6 +25,7 @@ (T (ASSOC X (CDR L))))) SUBR (BEOWULF HOST ASSOC)) (ATOM 32767 SUBR (BEOWULF HOST ATOM)) + (ATTRIB 32767 SUBR (BEOWULF HOST ATTRIB)) (CAR 32767 SUBR (BEOWULF HOST CAR)) (CAAAAR 32767 EXPR (LAMBDA (X) (CAR (CAR (CAR (CAR X)))))) (CAAADR 32767 EXPR (LAMBDA (X) (CAR (CAR (CAR (CDR X)))))) @@ -55,6 +56,16 @@ (CDDDR 32767 EXPR (LAMBDA (X) (CDR (CDR (CDR X))))) (CDDR 32767 EXPR (LAMBDA (X) (CDR (CDR X)))) (CDR 32767 SUBR (BEOWULF HOST CDR)) + (CONC + 32767 + FEXPR + (LABEL + ARGS + (COND + ((COND + ((ONEP (LENGTH ARGS)) ARGS) + (T (ATTRIB (CAR ARGS) (APPLY CONC (CDR ARGS) NIL)))) + ARGS)))) (CONS 32767 SUBR (BEOWULF HOST CONS)) (CONSP 32767 SUBR (BEOWULF HOST CONSP)) (COPY @@ -188,6 +199,7 @@ (LAMBDA (N X) (COND ((EQ N 0) NIL) (T (CONS X (REPEAT (SUB1 N) X)))))) (RPLACA 32767 SUBR (BEOWULF HOST RPLACA)) (RPLACD 32767 SUBR (BEOWULF HOST RPLACD)) + (SASSOC 32767 SUBR (BEOWULF BOOTSTRAP SASSOC)) (SEARCH 32767 EXPR (LAMBDA (X P F U) (COND ((NULL X) (U X)) diff --git a/resources/sexpr/conc.lsp b/resources/sexpr/conc.lsp index 2738a45..ebd03b1 100644 --- a/resources/sexpr/conc.lsp +++ b/resources/sexpr/conc.lsp @@ -1 +1,7 @@ -;; TODO \ No newline at end of file +;; This isn't working but it's really not far off. + +(PUT 'CONC 'FEXPR + ;; possibly ARGS should be (ARGS)... + '(LABEL ARGS + (COND ((COND ((ONEP (LENGTH ARGS)) ARGS) + (T (ATTRIB (CAR ARGS) (APPLY CONC (CDR ARGS) NIL)))) ARGS)))) \ No newline at end of file diff --git a/src/beowulf/bootstrap.clj b/src/beowulf/bootstrap.clj index d530f62..60f6f11 100644 --- a/src/beowulf/bootstrap.clj +++ b/src/beowulf/bootstrap.clj @@ -11,9 +11,9 @@ objects." (: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]]) + [beowulf.host :refer [ASSOC ATOM CAAR CADAR CADDR CADR CAR CDR + CONS ERROR GET LIST NUMBERP PAIRLIS traced?]] + [beowulf.oblist :refer [*options* NIL]]) (:import [beowulf.cons_cell ConsCell] [clojure.lang Symbol])) @@ -41,6 +41,12 @@ ;;;; The PROGram feature ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +(def ^:dynamic + *depth* + "Stack depth. Unfortunately we need to be able to pass round depth for + functions which call EVAL/APPLY but do not know about depth." + 0) + (def find-target (memoize (fn [target body] @@ -228,6 +234,21 @@ (first (remove #(= % NIL) (map #(GET s %) indicators)))))) +(defn SASSOC + "Like `ASSOC`, but with an action to take if no value is found. + + From the manual, page 60: + + 'The function `sassoc` searches `y`, which is a list of dotted pairs, for + a pair whose first element that is `x`. If such a pair is found, the value + of `sassoc` is this pair. Otherwise the function `u` of no arguments is + taken as the value of `sassoc`.'" + [x y u] + (let [v (ASSOC x y)] + (if-not (= v NIL) v + (APPLY u NIL NIL)))) + + ;;;; APPLY ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defn try-resolve-subroutine @@ -275,6 +296,24 @@ (trace-response function-symbol result depth) result)) +(defn- apply-label + "Apply in the special case that the first element in the function is `LABEL`." + [function args environment depth] + (APPLY + (CADDR function) + args + (CONS + (CONS (CADR function) (CADDR function)) + environment) + depth)) + +(defn- apply-lambda + "Apply in the special case that the first element in the function is `LAMBDA`." + [function args environment depth] + (EVAL + (CADDR function) + (PAIRLIS (CADR function) args environment) depth)) + (defn APPLY "Apply this `function` to these `arguments` in this `environment` and return the result. @@ -282,38 +321,32 @@ 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." - [function args environment depth] - (trace-call 'APPLY (list function args environment) depth) - (let [result (cond - (= NIL function) (if (:strict *options*) - NIL - (throw (ex-info "NIL sí ne þegnung" - {:phase :apply - :function "NIL" - :args args - :type :beowulf}))) - (= (ATOM function) T) (apply-symbolic function args environment (inc depth)) - :else (case (first function) - LABEL (APPLY - (CADDR function) - args - (make-cons-cell - (make-cons-cell - (CADR function) - (CADDR function)) - environment) - depth) - FUNARG (APPLY (CADR function) args (CADDR function) depth) - LAMBDA (EVAL - (CADDR function) - (PAIRLIS (CADR function) args environment) depth) - (throw (ex-info "Ungecnáwen wyrþan sí þegnung-weard" - {:phase :apply - :function function - :args args - :type :beowulf}))))] - (trace-response 'APPLY result depth) - result)) + ([function args environment] + (APPLY function args environment *depth*)) + ([function args environment depth] + (binding [*depth* (inc depth)] + (trace-call 'APPLY (list function args environment) depth) + (let [result (cond + (= NIL function) (if (:strict *options*) + NIL + (throw (ex-info "NIL sí ne þegnung" + {:phase :apply + :function "NIL" + :args args + :type :beowulf}))) + (= (ATOM function) T) (apply-symbolic function args environment (inc depth)) + :else (case (first function) + LABEL (apply-label function args environment depth) + FUNARG (APPLY (CADR function) args (CADDR function) depth) + LAMBDA (apply-lambda function args environment depth) + ;; else + (throw (ex-info "Ungecnáwen wyrþan sí þegnung-weard" + {:phase :apply + :function function + :args args + :type :beowulf}))))] + (trace-response 'APPLY result depth) + result)))) ;;;; EVAL ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; @@ -412,11 +445,10 @@ (EVLIS (CDR expr) env depth) env depth)) - :else (APPLY - (CAR expr) - (EVLIS (CDR expr) env depth) - env - depth))] + :else (EVAL (CONS (CDR (SASSOC (CAR expr) env (fn [] (ERROR 'A9)))) + (CDR expr)) + env + (inc depth)))] (trace-response 'EVAL result depth) result))) diff --git a/src/beowulf/host.clj b/src/beowulf/host.clj index 81e17ba..9c0bdb5 100644 --- a/src/beowulf/host.clj +++ b/src/beowulf/host.clj @@ -216,7 +216,7 @@ :phase :host :detail :rplacd :args (list cell value) - :type :beowulf}))));; PLUS + :type :beowulf})))) (defn LIST [& args] @@ -447,6 +447,26 @@ :else (hit-or-miss-assoc target (CDDR plist))) NIL)) +(defn ATTRIB + "Destructive append. From page 59 of the manual: + + The function `attrib` concatenates its two arguments by changing the last + element of its first argument to point to the second argument. Thus it + is commonly used to tack something onto the end of a property list. + The value of `attrib` is the second argument. + + For example + ``` + attrib[FF; (EXPR (LAMBDA (X) (COND ((ATOM X) X) (T (FF (CAR x))))))] + ``` + would put EXPR followed by the LAMBDA expression for FF onto the end of + the property list for FF." + [x e] + (loop [l x] + (cond + (instance? ConsCell (CDR l)) (recur (CDR l)) + :else (when (RPLACD l e) e)))) + (defn PUT "Put this `value` as the value of the property indicated by this `indicator` of this `symbol`. Return `value` on success. @@ -459,6 +479,8 @@ (let [prop (hit-or-miss-assoc indicator (CDDR binding))] (if (instance? ConsCell prop) (RPLACA (CDR prop) value) + ;; The implication is ATTRIB was used here, but I have not made that + ;; work and this does work, so if it ain't broke don't fix it. (RPLACD binding (make-cons-cell magic-marker @@ -494,13 +516,9 @@ val (cond (= binding NIL) NIL (= magic-marker - (CADR binding)) (loop [b binding] - ;; (println "GET loop, seeking " indicator ":") - ;; (pretty-print b) - (if (instance? ConsCell b) - (if (= (CAR b) indicator) - (CADR b) ;; <- this is what we should actually be returning - (recur (CDR b))) + (CADR binding)) (let [p (hit-or-miss-assoc indicator binding)] + (if-not (= NIL p) + (CADR p) NIL)) :else (throw (ex-info "Misformatted property list (missing magic marker)" diff --git a/src/beowulf/io.clj b/src/beowulf/io.clj index 62ead4c..d798762 100644 --- a/src/beowulf/io.clj +++ b/src/beowulf/io.clj @@ -91,7 +91,8 @@ ([] (SYSOUT nil)) ([filepath] - (spit (full-path (str filepath)) + (let [destination (full-path (str filepath))] + (spit destination (with-out-str (println (apply str (repeat 79 ";"))) (println (format ";; Beowulf %s Sysout file generated at %s" @@ -103,7 +104,9 @@ (println) (let [output (safely-wrap-subrs @oblist)] (pretty-print output) - ))))) + ))) + (println "Saved sysout to " destination) + NIL))) (defn resolve-subr "If this oblist `entry` references a subroutine, attempt to fix up that