30 lines
14 KiB
HTML
30 lines
14 KiB
HTML
<!DOCTYPE html PUBLIC ""
|
||
"">
|
||
<html><head><meta charset="UTF-8" /><title>beowulf.bootstrap documentation</title><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" /></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">Beowulf</span> <span class="project-version">0.3.1-SNAPSHOT</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1 "><a href="further_reading.html"><div class="inner"><span>Further Reading</span></div></a></li><li class="depth-1 "><a href="intro.html"><div class="inner"><span>beowulf</span></div></a></li><li class="depth-1 "><a href="mexpr.html"><div class="inner"><span>Interpreting M-Expressions</span></div></a></li><li class="depth-1 "><a href="values.html"><div class="inner"><span>The properties of the system, and their values</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>beowulf</span></div></div></li><li class="depth-2 branch current"><a href="beowulf.bootstrap.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>bootstrap</span></div></a></li><li class="depth-2 branch"><a href="beowulf.cons-cell.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>cons-cell</span></div></a></li><li class="depth-2 branch"><a href="beowulf.core.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>core</span></div></a></li><li class="depth-2 branch"><a href="beowulf.gendoc.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>gendoc</span></div></a></li><li class="depth-2 branch"><a href="beowulf.host.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>host</span></div></a></li><li class="depth-2 branch"><a href="beowulf.interop.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>interop</span></div></a></li><li class="depth-2 branch"><a href="beowulf.io.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>io</span></div></a></li><li class="depth-2 branch"><a href="beowulf.manual.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>manual</span></div></a></li><li class="depth-2 branch"><a href="beowulf.oblist.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>oblist</span></div></a></li><li class="depth-2 branch"><a href="beowulf.read.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>read</span></div></a></li><li class="depth-2"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>reader</span></div></div></li><li class="depth-3 branch"><a href="beowulf.reader.char-reader.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>char-reader</span></div></a></li><li class="depth-3 branch"><a href="beowulf.reader.generate.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>generate</span></div></a></li><li class="depth-3 branch"><a href="beowulf.reader.macros.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>macros</span></div></a></li><li class="depth-3 branch"><a href="beowulf.reader.parser.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>parser</span></div></a></li><li class="depth-3"><a href="beowulf.reader.simplify.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>simplify</span></div></a></li></ul></div><div class="sidebar secondary"><h3><a href="#top"><span class="inner">Public Vars</span></a></h3><ul><li class="depth-1"><a href="beowulf.bootstrap.html#var-*depth*"><div class="inner"><span>*depth*</span></div></a></li><li class="depth-1"><a href="beowulf.bootstrap.html#var-APPLY"><div class="inner"><span>APPLY</span></div></a></li><li class="depth-1"><a href="beowulf.bootstrap.html#var-apply-label"><div class="inner"><span>apply-label</span></div></a></li><li class="depth-1"><a href="beowulf.bootstrap.html#var-EVAL"><div class="inner"><span>EVAL</span></div></a></li><li class="depth-1"><a href="beowulf.bootstrap.html#var-find-target"><div class="inner"><span>find-target</span></div></a></li><li class="depth-1"><a href="beowulf.bootstrap.html#var-PROG"><div class="inner"><span>PROG</span></div></a></li><li class="depth-1"><a href="beowulf.bootstrap.html#var-prog-eval"><div class="inner"><span>prog-eval</span></div></a></li><li class="depth-1"><a href="beowulf.bootstrap.html#var-SASSOC"><div class="inner"><span>SASSOC</span></div></a></li><li class="depth-1"><a href="beowulf.bootstrap.html#var-try-resolve-subroutine"><div class="inner"><span>try-resolve-subroutine</span></div></a></li><li class="depth-1"><a href="beowulf.bootstrap.html#var-value"><div class="inner"><span>value</span></div></a></li></ul></div><div class="namespace-docs" id="content"><h1 class="anchor" id="top">beowulf.bootstrap</h1><div class="doc"><div class="markdown"><p>Lisp as defined in Chapter 1 (pages 1-14) of the <code>Lisp 1.5 Programmer's Manual</code>; that is to say, a very simple Lisp language, which should, I believe, be sufficient in conjunction with the functions provided by <code>beowulf.host</code>, be sufficient to bootstrap the full Lisp 1.5 interpreter..</p>
|
||
<p>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 <code>beowulf.cons_cell.ConsCell</code> objects.</p>
|
||
</div></div><div class="public anchor" id="var-*depth*"><h3>*depth*</h3><h4 class="dynamic">dynamic</h4><div class="usage"></div><div class="doc"><div class="markdown"><p>Stack depth. Unfortunately we need to be able to pass round depth for functions which call EVAL/APPLY but do not know about depth.</p>
|
||
</div></div><div class="src-link"><a href="https://github.com/simon-brooke/beowulf/blob/master/src/beowulf/bootstrap.clj#L45">view source</a></div></div><div class="public anchor" id="var-APPLY"><h3>APPLY</h3><div class="usage"><code>(APPLY function args environment)</code><code>(APPLY function args environment depth)</code></div><div class="doc"><div class="markdown"><p>Apply this <code>function</code> to these <code>arguments</code> in this <code>environment</code> and return the result.</p>
|
||
<p>For bootstrapping, at least, a version of APPLY written in Clojure. All args are assumed to be symbols or <code>beowulf.cons-cell/ConsCell</code> objects. See page 13 of the Lisp 1.5 Programmers Manual.</p>
|
||
</div></div><div class="src-link"><a href="https://github.com/simon-brooke/beowulf/blob/master/src/beowulf/bootstrap.clj#L352">view source</a></div></div><div class="public anchor" id="var-apply-label"><h3>apply-label</h3><div class="usage"><code>(apply-label function args environment depth)</code></div><div class="doc"><div class="markdown"><p>Apply in the special case that the first element in the function is <code>LABEL</code>.</p>
|
||
</div></div><div class="src-link"><a href="https://github.com/simon-brooke/beowulf/blob/master/src/beowulf/bootstrap.clj#L332">view source</a></div></div><div class="public anchor" id="var-EVAL"><h3>EVAL</h3><div class="usage"><code>(EVAL expr)</code><code>(EVAL expr env depth)</code></div><div class="doc"><div class="markdown"><p>Evaluate this <code>expr</code> and return the result. If <code>environment</code> is not passed, it defaults to the current value of the global object list. The <code>depth</code> argument is part of the tracing system and should not be set by user code.</p>
|
||
<p>All args are assumed to be numbers, symbols or <code>beowulf.cons-cell/ConsCell</code> objects. However, if called with just a single arg, <code>expr</code>, I’ll assume it’s being called from the Clojure REPL and will coerce the <code>expr</code> to <code>ConsCell</code>.</p>
|
||
</div></div><div class="src-link"><a href="https://github.com/simon-brooke/beowulf/blob/master/src/beowulf/bootstrap.clj#L446">view source</a></div></div><div class="public anchor" id="var-find-target"><h3>find-target</h3><div class="usage"></div><div class="doc"><div class="markdown"><p><strong>TODO</strong>: write docs</p>
|
||
</div></div><div class="src-link"><a href="https://github.com/simon-brooke/beowulf/blob/master/src/beowulf/bootstrap.clj#L51">view source</a></div></div><div class="public anchor" id="var-PROG"><h3>PROG</h3><div class="usage"><code>(PROG program env depth)</code></div><div class="doc"><div class="markdown"><p>The accursed <code>PROG</code> feature. See page 71 of the manual.</p>
|
||
<p>Lisp 1.5 introduced <code>PROG</code>, 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.</p>
|
||
<p>Broadly, <code>PROG</code> is a variadic pseudo function called as a <code>FEXPR</code> (or possibly an <code>FSUBR</code>, although I’m not presently sure that would even work.)</p>
|
||
<p>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 <code>GO</code> statement.</p>
|
||
<p><strong>GO:</strong> A <code>GO</code> statement takes the form of <code>(GO target)</code>, where <code>target</code> should be one of the symbols which occur at top level among that particular invocation of <code>PROG</code>s arguments. A <code>GO</code> statement may occur at top level in a PROG, or in a clause of a <code>COND</code> statement in a <code>PROG</code>, but not in a function called from the <code>PROG</code> statement. When a <code>GO</code> statement is evaluated, execution should transfer immediately to the expression which is the argument list immediately following the symbol which is its target.</p>
|
||
<p>If the target is not found, an error with the code <code>A6</code> should be thrown.</p>
|
||
<p><strong>RETURN:</strong> A <code>RETURN</code> statement takes the form <code>(RETURN value)</code>, where <code>value</code> is any value. Following the evaluation of a <code>RETURN</code> statement, the <code>PROG</code> should immediately exit without executing any further expressions, returning the value.</p>
|
||
<p><strong>SET and SETQ:</strong> In addition to the above, if a <code>SET</code> or <code>SETQ</code> expression is encountered in any expression within the <code>PROG</code> body, it should affect not the global object list but instead only the local variables of the program.</p>
|
||
<p><strong>COND:</strong> In <strong>strict</strong> mode, when in normal execution, a <code>COND</code> statement none of whose clauses match should not return <code>NIL</code> but should throw an error with the code <code>A3</code>… <em>except</em> that inside a <code>PROG</code> body, it should not do so. <em>sigh</em>.</p>
|
||
<p><strong>Flow of control:</strong> Apart from the exceptions specified above, expressions in the program body are evaluated sequentially. If execution reaches the end of the program body, <code>NIL</code> is returned.</p>
|
||
<p>Got all that?</p>
|
||
<p>Good.</p>
|
||
</div></div><div class="src-link"><a href="https://github.com/simon-brooke/beowulf/blob/master/src/beowulf/bootstrap.clj#L136">view source</a></div></div><div class="public anchor" id="var-prog-eval"><h3>prog-eval</h3><div class="usage"><code>(prog-eval expr vars env depth)</code></div><div class="doc"><div class="markdown"><p>Like <code>EVAL</code>, q.v., except handling symbols, and expressions starting <code>GO</code>, <code>RETURN</code>, <code>SET</code> and <code>SETQ</code> specially.</p>
|
||
</div></div><div class="src-link"><a href="https://github.com/simon-brooke/beowulf/blob/master/src/beowulf/bootstrap.clj#L85">view source</a></div></div><div class="public anchor" id="var-SASSOC"><h3>SASSOC</h3><div class="usage"><code>(SASSOC x y u)</code></div><div class="doc"><div class="markdown"><p>Like <code>ASSOC</code>, but with an action to take if no value is found.</p>
|
||
<p>From the manual, page 60:</p>
|
||
<p>‘The function <code>sassoc</code> searches <code>y</code>, which is a list of dotted pairs, for a pair whose first element that is <code>x</code>. If such a pair is found, the value of <code>sassoc</code> is this pair. Otherwise the function <code>u</code> of no arguments is taken as the value of <code>sassoc</code>.’</p>
|
||
</div></div><div class="src-link"><a href="https://github.com/simon-brooke/beowulf/blob/master/src/beowulf/bootstrap.clj#L253">view source</a></div></div><div class="public anchor" id="var-try-resolve-subroutine"><h3>try-resolve-subroutine</h3><div class="usage"><code>(try-resolve-subroutine subr args)</code></div><div class="doc"><div class="markdown"><p>Attempt to resolve this <code>subr</code> with these <code>args</code>.</p>
|
||
</div></div><div class="src-link"><a href="https://github.com/simon-brooke/beowulf/blob/master/src/beowulf/bootstrap.clj#L270">view source</a></div></div><div class="public anchor" id="var-value"><h3>value</h3><div class="usage"><code>(value s)</code><code>(value s indicators)</code></div><div class="doc"><div class="markdown"><p>Seek a value for this symbol <code>s</code> by checking each of these indicators in turn.</p>
|
||
</div></div><div class="src-link"><a href="https://github.com/simon-brooke/beowulf/blob/master/src/beowulf/bootstrap.clj#L243">view source</a></div></div></div></body></html> |