\input texinfo.tex @c This is -*- Texinfo -*-.

@c This file is part of the JitterLisp manual, which is part of GNU Jitter.
@c Copyright (C) 2017-2021  Luca Saiu
@c Updated in 2022 and 2024 by Luca Saiu
@c Written by Luca Saiu

@c Permission is granted to copy, distribute and/or modify this
@c document under the terms of the GNU Free Documentation License,
@c Version 1.3 or any later version published by the Free Software
@c Foundation; with no Invariant Sections, no Front-Cover Texts, and
@c with the Back-Cover Text being ``You have freedom to copy and
@c modify this manual, like GNU software.''.  A copy of the license
@c is included in the section entitled ``GNU Free Documentation
@c License''.
@c The code examples contained in this manual are released into the
@c public domain, up to the extent of the applicable law.


@c Conditionals
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@c @set this if building a preview for myself rather than a nice clean manual
@c to be distributed.
@c @set preview

@c @set this if I decide to include license texts.  It will look silly unless
@c the manual is long.
@c @set includelicenses

@c @set this is I really want to typeset the PDF version in color.  It is
@c probably a bad idea.
@set color


@c Index settings which must come early
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@c Define a symbol index, with entries typeset in @code .
@defcodeindex sy

@c @c Merge index entries for symbols to the concept index.
@c I've noticed that it's unfortunately impossible to reliably print
@c both indices, when one is merged into the other.
@c @syncodeindex sy cp


@c File name and title
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@setfilename jitterlisp.info
@include version-jitterlisp.texi
@settitle The JitterLisp manual, for GNU Jitter version @value{VERSION}


@c Global settings
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@documentencoding UTF-8
@c As Bruno Haible told me, @documentlanguage is recommended against for
@c English and leaving it out might in fact make builds easier on some
@c older systems:
@c   https://lists.gnu.org/archive/html/bug-bison/2019-05/msg00034.html
@c
@c I am leaving this comment mostly as a note for myself, in case I forget
@c about this later and wanted to specify the language in a bout of pedantry.
@c
@c @documentlanguage en   @c No: see above.

@syncodeindex pg cp

@c @ignore
@afourpaper
@c @end ignore

@c Use color for previews, which are not to be printed.  On screen it is
@c convenient to check that links point to the right thing.
@ifset preview
@set color
@end ifset @c preview

@ifclear color
@c Don't use color for hyperlinks.  If the manual is really to be printed
@c out it will almost certainly be in black and white.
@tex
\global\def\linkcolor{0 0 0}
\global\def\urlcolor{0 0 0}
@end tex
@end ifclear @c color

@c FIXME: comment
@ifset color
@tex
\global\def\linkcolor{0.75 0 0}
\global\def\urlcolor{0 0 0.75}
@end tex
@end ifset @c color

@ignore
@fonttextsize 10
@afivepaper
@smallbook
@c @pagesizes 200mm,100mm
@c @cropmarks
@end ignore

@c This is for production of a nice manual; I might want to enable it
@c when the actual manual is written.  The default (start chapters on
@c pages of any parity) looks less nice.
@ifclear preview
@setchapternewpage odd
@end ifclear @c preview

@c This come in handy for private testing printouts.
@ifset preview
@setchapternewpage off
@end ifset @c preview

@c Information for the Info directory
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@dircategory Programming
@direntry
* The JitterLisp manual: (jitterlisp).  An efficient Lisp system using a Jittery VM.
* @command{jitterlisp}:  (jitterlisp).  Invoking @command{jitterlisp}.
@end direntry


@c Macros
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@iftex
@macro epsilonsubscript{subscript}
@inlineraw{tex,$@varepsilon_{\subscript\}$}@inlineraw{tex,{}}
@end macro
@end iftex

@ifnottex
@ifhtml
@macro epsilonsubscript{subscript}
@inlineraw{html,&epsilon;<sub>\subscript\</sub>}
@end macro
@end ifhtml
@ifnothtml
@macro epsilonsubscript{subscript}
epsilon\subscript\
@end macro
@end ifnothtml
@end ifnottex

@macro epsilonzero{}
@epsilonsubscript{0}
@end macro

@macro epsilonone{}
@epsilonsubscript{1}
@end macro

@rmacro fixme{text}
@strong{[@emph{FIXME}: \text\]}
@end rmacro

@rmacro fill
@fixme{Fill this.}
@end rmacro

@c This occurs a lot of times, so a macro comes in handy.
@rmacro nothing
@code{#<nothing>}
@end rmacro

@rmacro rephrase{text}
@strong{[@emph{REPHRASE}: \text\]}
@end rmacro


@c Copying conditions
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@copying
This is the manual for JitterLisp
@c (edition @value{EDITION} for
(for GNU Jitter version @value{VERSION},
last updated on @value{UPDATED}), an efficient Lisp system using a Jittery VM.

@noindent
@c NOTE FOR MYSELF: keep consistent with the legal notice at the top.
Copyright @copyright{} 2017-2021  Luca Saiu@*
Updated in 2022 by Luca Saiu@*
Written by Luca Saiu.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation;
@ifset includelicenses
  with the Invariant Sections being ``GNU General Public License'' and
  ``GNU Free Documentation License'',
@end ifset @c includelicenses
with no Front-Cover texts and with the Back-Cover text being
``@emph{You have freedom to copy and modify this manual, like GNU
software.}''.

A copy of the GNU Free Documentation License is
@ifset includelicenses
  included in this book in the appendix entitled ``GNU Free
  Documentation License'', and the license text is also
@end ifset @c includelicenses
distributed in electronic form along with the software in the file
@file{doc/COPYING.DOC}, and available on the web at the URL
@url{https://www.gnu.org/licenses/fdl.html}.

All the code examples contained in this manual are released into the
public domain, up to the extent of the applicable law.
@end quotation

The author's personal web site @url{https://ageinghacker.net} contains
his contact information.
@end copying


@c Title page
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@titlepage
@title JitterLisp
@subtitle An efficient Lisp system, conceived as an advanced example for GNU Jitter
@subtitle for Jitter version @value{VERSION}, updated in @value{UPDATED-MONTH}
@c @author Luca Saiu (@email{positron@@gnu.org}, @url{https://ageinghacker.net})
@c @author Luca Saiu (@url{https://ageinghacker.net})
@c @author Luca Saiu (@email{positron@@gnu.org})
@author Luca Saiu
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage


@c Contents (only actually used for the hardcopy version)
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@contents


@c First page for the Info version, with the main menu
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@ifnottex
@node Top
@top JitterLisp

@c An @insertcopying within the Top node is not explicitly mandated by
@c the GNU Standards, nor even suggested in the Texinfo documentation;
@c however without such a line the Info and HTML versions don't bear any
@c copying information near the beginning.  Notice that the very short
@c introduction about what the software is comes from @copying.
@insertcopying
@end ifnottex

@menu
Overview
* Introduction::                   What JitterLisp is and why you should care.
* Using JitterLisp::               How to build and run the software.

Reference documentation
* Lisp reference::                 Documentation for the Lisp system.
* C API::                          Using JitterLisp with C (not).

Inner workings and development
* Internals::                      How JitterLisp works under the hood.
@c Licenses
@c * GNU General Public License::     How you can share and modify the software.
@c * GNU Free Documentation License:: How you can share and modify this manual.
@ifset includelicenses

Licenses
* GNU General Public License::     How you can share and modify the software.
* GNU Free Documentation License:: How you can share and modify this manual.
@end ifset @c includelicenses

Indices
* Symbol and reserved syntax index:: A link to the documentation for each
                                   predefined global variable or piece of
                                   reserved syntax.
* Concept index::                  The key words of this manual, with links.

@ifset preview
Temporary stuff, for myself
* Stuff still to be written:: What will be in this manual but is not fully written yet.
* Stuff still to be implemented:: What will exist in the implementation in the future.
@end ifset @c preview
@end menu


@c Introduction
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@c The introduction is written in the first person singular, and uses
@c a more informal tone than the rest.  The clear fracture in style
@c from the introduction to the first chapter is intentional, meant to
@c convey first a more personal, vaguely sentimental touch, and then
@c the reliable terseness of comprehensive documentation.  This
@c distinction should be kept.

@node Introduction
@c @unnumbered Introduction
@chapter Introduction

JitterLisp is a comparatively simple and efficient Lisp system,
relying on a Jittery virtual machine for compiled code.

@menu
* History::                            How JitterLisp came to be.
* Goals::                              Why I though the world needed another Lisp.
* Features and influences::            What JitterLisp can do and where it comes from.
* License::                            JitterLisp is released under the GNU GPLv3+.
@end menu

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node History
@section History
@cindex history
@cindex epsilon
@cindex GNU epsilon
@cindex Jitter
@cindex sub-project
@c @cindex @ @epsilonzero{} @c The initial forced space is less ugly than the alternative.
Jitter (@pxref{Top,,, jitter, The GNU Jitter Manual}) was borne
out of an attempt to optimize the programming language GNU epsilon
(@pxref{Top,,, epsilon, The GNU epsilon Manual}), my main long-term
project.  Dissatisfied with the speedup provided by a simple
direct-threaded virtual machine I started exploring more advanced
techniques, and the experiment eventually grew into the current
virtual machine generator.
@ignore
Even if it can certainly be said that
Jitter is a sub-project which got way out of hand I am happy with the
end result, and believe that others will find it useful.
@end ignore
@ignore
Useful as it is, Jitter could certainly be called a sub-project which
got out of hand.
@end ignore
@ignore
Even if it could certainly be called a sub-project which got out of hand I
am happy with Jitter, and believe that others will find it useful as well.
@end ignore
A sub-project, some might argue, that got out of hand.

@c Shortly after my public presentation of Jitter at the 2017 edition of
@c the GNU Hackers Meeting a friend @fixme{ask permission to mention him
@c by name} expressed interest in Jitter and wanted to use it in a new
@c software of his, even in its unpolished state.

@c In order to provide him with a practical example to use as a reference
@c before the official Jitter documentation was ready I quickly put
@c together the ``structured'' example, a simple imperative programming
@c language based on a Jittery VM.

@c The structured example proved useful as a stopgap solution and I added
@c a few more features to Jitter at my friend's @fixme{see above}
@c request, but we both knew it was not enough.  Jitter needed to be
@c stressed to find bugs and tested on a practical application.  A real
@c programming language.  A Lisp.

Still, Jitter had seen no major application yet.  It needed to be
stressed to find bugs and embedded in a practical system for me to
discover what was missing and fill the gaps.  I wanted a real
application.  A real programming language.  A Lisp.

@cindex sub-sub-project
And the sub-sub-project has now also gotten out of hand, again
branching off in its own interesting direction.

@c independent goals of its own.


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Goals
@section Goals

JitterLisp lives somewhere near the boundary between the end of the
domain of complex toys, and where simple real Lisp systems begin;
@c
as long as we keep seeing it as an example for Jitter either
classification will do.
@c JitterLisp is a complex toy, or a simple real Lisp system; either will
@c work as long as we keep seeing it as an example for Jitter.
As for concrete applications it can certainly be made practical: the
Lisp library can be extended, and JitterLisp itself could become both
embeddable and extensible in C without unreasonable effort.  If in the
future I bent the system in some of these directions, as I might
well do, I guess the result would be useful; but writing yet another
Lisp system was never my primary goal.

Even without the ambitious scope of Jitter I consider JitterLisp
useful to show the level of performance within the reach of small,
clean systems.  JitterLisp gets many design decisions correct but is
not perfect or exceptionally clever; still it appears more efficient
than every mature ``dynamic language'' implementation, in some cases
to a spectacular degree---due more to the faults of others than to any
merit of mine.

@cindex Schadenfreude
I will not even try to hide my own personal goal for JitterLisp: being
able to say that @emph{most language implementations are inexcusably
bad}, as in fact they are, with a real implementation to present as
a comparison point and not just a proof of concept; and numbers.
@*
@cindex Schadenfreude
And so here I stand, claiming my right to rub JitterLisp on everyone's
face.  How good it feels.


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Features and influences
@section Features and influences
@cindex design criterion
@cindex criterion, for feature inclusion
@cindex feature inclusion criterion
@cindex feature
Every time I had to choose whether to support a feature or to omit it
for simplicity my decision relied on two criteria:
@itemize @bullet
@cindex criterion, for feature inclusion
@cindex feature inclusion criterion
@item
@emph{Can the feature be omitted while keeping the language
realistic?}
JitterLisp should remain a Lisp, not more difficult to learn for a
Lisper than another simple dialect nor too fundamentally different.
JitterLisp must also be a reasonably practical system with the core
features a programmer would expect, and not just an idealized prototype.
@*
It must be possible to compare the JitterLisp @emph{language} with
standard dialects, and find them similar in practice.

@cindex criterion, for feature inclusion
@cindex feature inclusion criterion
@item
@emph{Is the feature critical for performance?}  If omitting the
feature granted JitterLisp a performance advantage with respect to
other Lisps at the cost of making JitterLisp very cumbersome to use,
then not supporting it would make performance comparisons unfair.
Where, on the other hand, a feature has no performance overhead
(particularly when not in use), I can in good conscience leave it out
and claim that an extended JitterLisp with the feature would still
perform as well as the current system.
@*
The language must make comparisons between the JitterLisp
@emph{implementation} and other Lisp implementations possible, and fair.
@end itemize
@noindent
In the end the relative weight associated to each of the two criteria
can only be a judgment call and some grey areas will remain, no matter
how I strive for fairness.
In case some reader felt that I skewed the comparison to JitterLisp's
advantage by choosing to include or exclude some feature, I am open to
discussion.

@cindex compatibility, other Lisp dialects (none)
@cindex influence
@cindex Common Lisp
@cindex Scheme
@cindex macro
JitterLisp draws inspiration from both Common Lisp and Scheme, without
being compatible with either.
However a competent programmer should be able to write code running
unchanged on top of JitterLisp, a Common Lisp system or a Scheme system,
through a layer of simple macros.

@cindex epsilon
Several design ideas originate from my own GNU epsilon.

@menu
* Comparison with other Lisps::     Some features come from Common Lisp and Scheme.
* epsilonian features::             Others are reminiscent of GNU epsilon.
* Simplifications::                 What JitterLisp lacks and why.
@end menu


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Comparison with other Lisps
@subsection Comparison with other Lisps
The JitterLisp language is first of all a Lisp dialect, and as such
will feel familiar to any programmer already mastering any other Lisp.

@cindex feature
@cindex lexical scoping
@cindex scoping, lexical
@cindex static scoping
@cindex iteration
@cindex recursion
@cindex macro
@cindex Lisp/1
@cindex /1, Lisp
@cindex procedure
@cindex higher order
@cindex order, higher
@cindex compiled procedure
@cindex interpreted procedure
@cindex garbage collection
@cindex homoiconicity
@cindex quoting
@cindex quasiquoting
JitterLisp is a
@emph{lexically-scoped}
@emph{higher-order}
@emph{homoiconic}@footnote{@anchor{homoiconicity-footnote}@fixme{justify; not as homoiconic as other Lisps appear, but still more than epsilon.  I argue that any Lisp system aiming at decent performance must do something like that; the difference is that I @emph{expose} this mechanism.}}
@emph{Lisp/1}
featuring
@emph{closures},
@emph{garbage collection},
@emph{quasiquoting} and
Turing-complete @emph{macros}.

@cindex feature
@cindex expression
@cindex sub-expression
@cindex statement (absent in JitterLisp)
@cindex top-level form (absent in JitterLisp)
@cindex form, top-level (absent in JitterLisp)
Every syntactic form in JitterLisp is an @emph{expression}, and nontrivial
expressions will contain sub-expressions; JitterLisp has no ``statements'' as
a distinct syntactic category, nor special forms which are only valid
at the top level.
@cindex feature
@cindex tail call
@cindex space overhead, tail call
@cindex mutability, variable
@cindex variable
Variables are @emph{mutable} by default, and @emph{iteration} and
@emph{recursion} are both supported.  @emph{Tail calls} incur no
space overhead except in inter-calls between compiled and interpreted
code.

@cindex feature
@cindex type
@cindex datatype
@cindex empty list
@cindex symbol
@cindex cons
@cindex cdr
@cindex list
@cindex character
@cindex procedure
@c FIXME: mention strings when I add them
@c FIXME: mention vectors when I add them
Typing is @emph{dynamic}.  JitterLisp datatypes include the
@emph{empty list} object,
@emph{symbols}, @emph{characters}, @emph{conses} and
@emph{procedures}.  Non-empty lists are cdr-nested conses.
@cindex fixnum
@cindex number
@c FIXME: fixnum only -- no floats -- no bignums -- change when I add more types
At the present time @emph{fixnums} are the only numeric type.

@cindex feature
@cindex procedure
@cindex compiled procedure
@cindex interpreted procedure
@cindex procedure, compiled
@cindex procedure, interpreted
@cindex identity, procedure across compiling
Each procedure may be either @emph{interpreted} or @emph{compiled},
and procedures of different kinds are allowed to call each other
with no restrictions and no difference in observable behavior
apart from performance.
Interpreted procedures can be compiled at run time without
affecting their @emph{identity} as objects.

@fixme{quoting and quasiquoting are Lispy, not epsilonian}

@fixme{compare with standard Lisp dialects}

@fixme{Many of the superficial features of JitterLisp, particularly at the
lexical level, come from Scheme}

@fixme{@code{define} operating at the top level, like Common Lisp's
@code{defun} but differently from Scheme}


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node epsilonian features
@subsection epsilonian features

@cindex dynamic language
@cindex reflection
@cindex Abstract Syntax Tree (AST)
@cindex macroexpansion
JitterLisp is
@c at the same time
more @emph{``dynamic''} and more
@emph{reflective} than typical Lisp dialects: any expression is
allowed to define, remove or alter any non-constant global binding;
the @emph{Abstract Syntax Tree} returned by macroexpansion and contained
within each closure is a recursive data structure describing an
expression in a @emph{minimalistic core language} which can be interpreted,
compiled, analyzed, optimized or in general used like any other data
structure, at run time, in the language itself.

@cindex compiler
@cindex Abstract Syntax Tree (AST)
Exposed ASTs and reflection make it possible and natural for the
compiler to be implemented as an ordinary procedure, itself written in
Lisp and running on top of the interpreter or compiled by itself at
run time.

@cindex quasiquoting
@cindex macro
@cindex Common Lisp
@cindex GNU epsilon
@cindex epsilon
These distinctly epsilonian features, while important in making the
internal implementation simpler and more elegant, are meant to be
invisible to the casual user.
In particular user macros operate on ordinary
non-AST Lisp data structures, usually through Lisp quasiquoting, and
will feel instantly familiar to any Common Lisp or Emacs Lisp programmer;
the fact that the core Lisp forms are themselves predefined macros
expanding to ASTs may be safely ignored in almost all programs as an
implementation detail.

@xref{Interaction example} for a quick demo session introducing most
of the non-traditional features likely to surprise a Lisp user.


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Simplifications
@subsection Simplifications

@menu
* Intentionally omitted features::            What I didn't include, on purpose.
* Desirable but not implemented features::    What I would like to include.
@end menu

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Intentionally omitted features
@subsubsection Intentionally omitted features

@fixme{no modules, packages or namespaces}

@syindex values@r{ (@emph{non-existing} form)}
@fixme{no @code{values}}

@syindex call/cc@r{ (@emph{non-existing} form)}
@fixme{no continuations}

@syindex throw@r{ (@emph{non-existing} form)}
@syindex catch@r{ (@emph{non-existing} form)}
@fixme{no exceptions}

@cindex variadic, procedure (absent in JitterLisp)
@fixme{no variadic procedures (but I do have variadic macros)}

@fixme{no OO}

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Desirable but not implemented features
@subsubsection Desirable but not implemented features

@fixme{no stack traces}

@fixme{no type dispatching}

@fixme{only a small library}



@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node License
@section License

@cindex free software
@cindex GPL
@cindex GNU General Public License
@cindex General Public License
@cindex license, for JitterLisp
@cindex software, license
@cindex copying (software software)
JitterLisp is free software, distributed under the GNU General Public
License, version 3 or later.
@ifset includelicenses
  @xref{GNU General Public License} for the full text of the software license.
@end ifset @c includelicenses
@cindex no warranty
@cindex warranty, lack thereof
There is no warranty whatsoever.

@cindex free documentation
@cindex FDL
@cindex GNU Free Documentation License
@cindex Free Documentation License
@cindex license, for this manual
@cindex manual, license
This manual is free documentation, distributed under the GNU Free
Documentation License, version 1.3 or later.
@ifset includelicenses
  @xref{GNU Free Documentation License} for the full text of the manual license.
@end ifset @c includelicenses


@c Here starts the actual documentation, written in a slightly more formal
@c tone but still in the first person singular.  I find it appropriate for the
@c JitterLisp's manual to have a less formal tone than Jitter's.

@c Using JitterLisp
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Using JitterLisp
@chapter Using JitterLisp
@cindex usage (JitterLisp)

@cindex source
@cindex distribution
JitterLisp is distributed along with GNU Jitter as an advanced example
of its use, and must be compiled from the source code.

@cindex cross compilation
@cindex GNU build system
@cindex GNU conventions, build system
@cindex build system
@cindex distribution
@cindex Jitter
@cindex build directory (Jitter)
JitterLisp has no separate distribution or build system of its own,
but is easy to build from the Jitter build directory.  The build
process follows the GNU conventions and supports cross-compilation.

@cindex REPL
@cindex Read-Eval-Print Loop
@cindex GNU, standard options, command-line
@cindex file (JitterLisp code)
@cindex interaction (REPL)
Once compiled JitterLisp is quite friendly to use.  It supports
GNU-style command-line options and can work either interactively with
a REPL, or by running Lisp code from text files.

@menu
* Obtaining the software::                 Where to download from.
* Building JitterLisp::                    JitterLisp is easy to build at
                                           the same time as Jitter.
* JitterLisp executables::                 Multiple compatible JitterLisp programs.
* Installing JitterLisp::                  No need to.
* Invoking JitterLisp::                    The command line interface.
* Interaction example::                    A demo session showing the main
                                           features.
@end menu


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Obtaining the software
@section Obtaining the software

@cindex obtaining
@cindex downloading
@cindex distribution

@cindex C
@cindex source
@cindex distribution
@cindex git
JitterLisp is distributed as an example within Jitter, and can be
obtained along with the Jitter source code.  It is written in C and itself,
and the virtual machine it relies on for compiled closures is generated by
Jitter.
The current web page for Jitter, containing a link to a publicly
readable git repository, is on my web site at the URL
@url{https://www.gnu.org/software/jitter} .

@cindex branch, git
@cindex git branch
@cindex @code{master}, git branch
As of 2021 JitterLisp's development takes place on the
main git branch named @code{master}.

@cindex feedback
@cindex contacting the author
@cindex author, contacting
@cindex Luca Saiu, contacting
@cindex Saiu, Luca, contacting
I welcome feedback.  If you need to contact me or want to discuss about
JitterLisp please
@pxref{Contacting the author,,, jitter, The Jitter Manual}.


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Building JitterLisp
@section Building JitterLisp

@cindex build directory (Jitter)
JitterLisp belongs to Jitter's examples.  The examples are not built
by the default @command{make} target but are easy to generate by running
@example
make examples
@end example
@noindent
from the Jitter build directory, or by running the test suite as
explained below.

@cindex test suite, Jitter
@cindex @code{check}, make target (Jitter)
@cindex @command{make check} (Jitter)
@cindex build directory (Jitter)
The Jitter test suite includes many cases based on JitterLisp, as compiled
JitterLisp procedures are a convenient and realistic way of stressing Jitter
and testing its generated code.
Running Jitter's test suite with
@example
make check
@end example
@noindent
(@pxref{Running the test suite,,, jitter, The Jitter Manual})
from its build directory is sufficient to build JitterLisp as a side
effect, in all of the variants (@pxref{JitterLisp executables}) supported
by the Jitter configuration.
I highly recommend running the test suite in any case before using
Jitter.

@cindex cross compilation
@cindex Jitter
@cindex GNU Coding Standards
@cindex GNU build system
@cindex Coding Standards, GNU
@cindex build system, GNU
@cindex GNU Autoconf
@cindex GNU Automake
@cindex Autoconf
@cindex Automake
@cindex tarball, stable release (not yet)
@xref{Working with the Jitter sources,,, jitter, The Jitter Manual} for
detailed building instructions.  The build system follows the modern GNU
style and in particular the common practices and suggestions from the GNU
Coding Standards
(@pxref{Top,,, standards, The GNU Coding Standards}), which sets a few
additional requirements such as GNU Autoconf and GNU Automake for
``developers''---with the caveat that, at the present time before I
release official stable tarballs, every user has to follow the
developer instructions.

@cindex Boehm-Demers garbage collector
@cindex garbage collector, Boehm-Demers
@cindex Hans Boehm's garbage collector
Even if the dependency is not mandatory I strongly recommend the
Boehm-Demers garbage collector, packaged by every modern GNU/Linux
distributions and also easy to install from sources.
@cindex Readline
@cindex GNU Readline
@cindex Libtextstyle
@cindex GNU Libtextstyle
Other optional
dependencies are the GNU Readline and GNU Libtextstyle libraries.
@*
@cindex @file{configure} script, Jitter
Both dependencies are automatically checked by Jitter's @file{configure}
script; if a library or its C headers are missing the corresponding
functionality will be disabled, or some JitterLisp variants will not be
built.

@cindex cross compiling
@cindex directory, build (Jitter)
@cindex build directory (Jitter)
Jitter's build system encourages a separate build directory and
supports advanced features such as cross compilation, but is
standard enough to just work with the usual command line
@example
./bootstrap && ./configure && make
@end example
@noindent in most practical cases.

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node JitterLisp executables
@section JitterLisp executables

@cindex @file{configure} script, Jitter
According to the system characteristics as detected by Jitter's
@file{configure} script and to configure-time options supplied by the
user the build system will compile different versions of JitterLisp,
with the intent of testing and benchmarking Jitter.

These different compiled programs will exhibit different performance
profiles, but still be equivalent in terms of Lisp functionality.

@cindex configuration item, JitterLisp
One JitterLisp executable is built for each combination of the
following configuration items:
@table @emph
@cindex safe, JitterLisp configuration item
@cindex unsafe, JitterLisp configuration item
@item safety
a JitterLisp program may be @dfn{safe} and check for operand types
before executing every operation, or @dfn{unsafe} and omit some
checks.  An unsafe Lisp will be more efficient, but subject to crashes
in case of user error;

@cindex Boehm-Demers garbage collector
@cindex garbage collector, Boehm-Demers
@cindex Hans Boehm's garbage collector
@cindex litter
@item garbage collection
@anchor{litter}
JitterLisp supports the Boehm-Demers garbage collector but can also
allocate heap memory without ever freeing the space, either because the
garbage collection library is not available or for performance testing.
The two possible configuration values are called @dfn{Boehm} or
@dfn{litter}, respectively.

@cindex dispatch, Jitter
@item dispatch
there are currently four @dfn{dispatches} supported by Jitter:
@dfn{@code{switch}-dispatching},
@dfn{direct threading},
@dfn{minimal threading} and
@dfn{no threading} (@pxref{Dispatches,,, jitter, The Jitter Manual}),
each with its own performance and portability profile.
JitterLisp will run with any dispatch.
@end table

@cindex build directory (Jitter)
Unless some configuration choice has been disabled multiplying
the number of choices for each of the three items gives a total
of
16 @c sixteen
combinations and therefore
16 @c sixteen
different executables, recognizable by suffixes in
their file name.
The safety suffix may be empty or @samp{--unsafe},
the garbage collection suffix @samp{--boehm} or empty,
and the dispatch suffix one of
@samp{--switch},
@samp{--direct-threading},
@samp{--minimal-threading} and
@samp{--no-threading}.
@*
A good combination for general use will be
@emph{safe}-@emph{Boehm}-@emph{no-threading}, implemented in the file
@file{bin/jitterlisp--boehm--no-threading} relative to Jitter's build
directory.
A user measuring performance in a ``lowest-overhead'' context might
want to try @file{bin/jitterlisp--unsafe--no-threading}, paying close
attention to how much memory is used.
The shell command
@example
ls bin/jitterlisp*
@end example
@noindent will print the full list of available JitterLisp programs.

``Default'' JitterLisp executables, with no dispatch suffix
in their name are also built using the best dispatch
available in the current configuration.  In the example above
@file{bin/jitterlisp--boehm} will have the same functionality as
@file{bin/jitterlisp--boehm--no-threading}.

@cindex invoking
@cindex command line
@cindex option, command line (@command{jitterlisp})
@cindex @command{jitterlisp} and related executables, invoking
In the following examples I will arbitrarily refer to
@file{bin/jitterlisp--boehm} as the executable to run.  The executable
name is easy to replace with another, in case that configuration is
not available; every JitterLisp executable supports the same
command-line interface.
@cindex current working directory
@cindex directory, current working
The current working directory is always irrelevant when invoking any
JitterLisp executable without file arguments, which makes the
@file{bin/} component of the path name safe to freely adapt as well.


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Installing JitterLisp
@section Installing JitterLisp

@cindex installing (by hand, for the time being)
The Jitter build system does not support installing examples at the
present time.

@cindex GNU Libtool
@cindex Libtool
It would certainly be possible to directly use Libtool and install
Jitter's libraries and executables.
@cindex @file{configure} script, Jitter
@cindex @option{--disable-shared}, Jitter @file{configure} option
@cindex shared library
@cindex static library
@cindex library (native, non-Lisp)
However, as a simpler alternative, a user can configure
Jitter to generate static libraries only by calling @file{configure}
with the option @option{--disable-shared},
and then build the examples.  Each JitterLisp executable will be one
self-contained file with no external run-time dependencies, easy to
copy by hand into some directory within @env{PATH} or to another
convenient location.

@cindex library file, JitterLisp
@cindex initialization file, JitterLisp
@cindex license, text in JitterLisp executables
@cindex GPL
@cindex GNU General Public License
If the Jitter libraries are statically linked and every dynamic
library is correctly installed then the JitterLisp executables will
not access any other file by default: the large Lisp initialization
file and the GPL license text are in fact embedded as constants within
the native compiled file image (@pxref{constant-strings}).


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@c This node name is required by the GNU Coding Standards.  However nothing
@c requires it to be a *chapter* name.
@node Invoking JitterLisp
@section Invoking JitterLisp
@cindex invoking
@cindex command line

@cindex Read-Eval-Print Loop
A user can either run JitterLisp @dfn{interactively} via a
@dfn{Read-Eval-Print Loop}, or use it to execute Lisp programs from
any number of text files.

An interactive run is the default: simply invoking a JitterLisp
executable with no arguments, for example by typing
@example
bin/jitterlisp--boehm
@end example
@noindent
at the shell prompt will print a welcome banner and then wait for the
user to type in Lisp forms; the system will evaluate one form, print
its result unless the result is @nothing{}, and then go back to waiting
for the next form.
@*
@cindex GNU Readline
@cindex Readline
User input supports the line-editing facilities of GNU Readline, as long
as Jitter has been configured with Readline support.  Lisp forms entered by
the user are allowed to span multiple lines.
@*
@cindex input, closing
@cindex @key{C-d}, terminal input closing
The user can exit by closing the input, typically by pressing
@key{C-d} on an empty line on GNU and other Unix systems.

@cindex non-option argument
@cindex file name, non-option argument
@cindex path name, file, non-option argument
Any @dfn{non-option argument} on the command line is taken as the
relative path name of one Lisp file to run; JitterLisp accepts an
arbitrary number of file names on the command line, and executes them
in the given order.  JitterLisp will omit the banner and, by default,
run @dfn{non-interactively} if it receives any file name, exiting without
executing the REPL.
@*
@cindex @file{-}, command-line non-option argument
@cindex standard input
@cindex input, standard
A single dash @samp{-} is a non-option argument and stands for the
process standard input, from which the program will read Lisp forms.
Like the path name for a Lisp file, a @code{-} argument will make
JitterLisp default to non-interactive mode.

@cindex output
@cindex I/O
Lisp forms @emph{from input files or @samp{-}}, in either interactive
or non-interactive mode, will be evaluated without automatically
printing each result, to avoid clutter in the output.  Of course a
Lisp program may still call I/O procedures (@pxref{Input and output})
in order to print out information as desired, without such
@emph{explicit} output being suppressed.

A run-time error while executing a Lisp program given on the command line
will cause JitterLisp to exit with failure, without processing any
remaining Lisp file.

@cindex option, command line (@command{jitterlisp})
@cindex command line option (@command{jitterlisp})
@cindex @command{jitterlisp} and related executables, invoking
JitterLisp executables default to treating any command-line argument
beginning with a dash (@samp{-}) as an @dfn{option} which affects the
system behavior in one of the ways described in this section.
The exceptions are arguments constituted by exactly a single dash, as
explained above, or any arguments following an argument constituted by
exactly two dashes (@samp{--}): those are interpreted as non-options.

@cindex default, command-line option
Several JitterLisp options affect the software behavior in some way
which can be negated by another option restoring the default.  When
both an option and its opposite are given, the @emph{last} option on
the command line prevails.

@cindex negative option, command line
@cindex line editing
@cindex alias, shell
@cindex shell alias
I call @dfn{negative options} the options whose only purpose is to
negate the effect of other options, restoring the default
behavior.  Negative options are useful for canceling the effect of
some option which is convenient to always pass and then occasionally
override, for example as part of a shell alias or by quick
interactive line editing of a complex shell command line.
@*
The output of @option{--help}, described below, shows negative options
marked as @samp{(default)}.

@cindex common GNU options, command-line
@cindex standard GNU options, command-line
@cindex GNU, standard options, command-line
@cindex command-line options
@cindex options, command-line
JitterLisp supports the standard GNU command-line options:
@table @option
@cindex @option{--version}, command-line option
@item --version
Print version information and legal notices for JitterLisp, then exit
with success.
Since JitterLisp is distributed along with Jitter and currently lacks
a version number of its own, the output will actually reflect
@emph{Jitter}'s version.

@cindex @option{-?}, command-line option
@cindex @option{--help}, command-line option
@item -?@r{, }--help
Print a terse description of JitterLisp's command-line interface including
the options documented here, then exit with success.

@cindex @option{--usage}, command-line option
@item --usage
Print a list of the options documented here with no explanation, then
exit with success.

@cindex @option{--}, command-line option
@item --
Stop option processing, and interpret any following argument in the
command line as a non-option.  This may be useful to execute Lisp files
whose path name starts with a dash.
@end table

@cindex shell
@cindex script, shell
Checking JitterLisp's version to obtain a version number and nothing
more may be of some use in shell scripts:
@table @option
@cindex @option{--dump-version}, command-line option
@item --dump-version
Print JitterLisp's version number and exit with success.  The output is
in a single line with no spaces, and does not contain JitterLisp's name
or any other information.
@end table

The following options affect JitterLisp's interaction mode:
@table @option
@cindex @option{-r}, command-line option
@cindex @option{--no-repl}, command-line option
@cindex @option{--batch}, command-line option
@item -q@r{, }--no-repl@r{, }--batch
Run in non-interactive mode, without a REPL, independently from
non-option arguments.

@cindex @option{--repl}, command-line option
@cindex @option{--no-batch}, command-line option
@item --repl@r{, }--no-batch
Run in interactive mode even if non-option arguments are given; in
this case start the REPL @emph{after} executing the given Lisp files.
@end table

It may be useful to run JitterLisp for evaluating one or a few Lisp
forms from the command line, possibly along with some Lisp program
passed as a non-option argument:
@table @option
@cindex @option{-e}, command-line option
@cindex @option{--eval}, command-line option
@item -e @var{sexprs}@r{, }--eval=@var{sexprs}
Evaluate the given possibly empty sequence of forms, printing the
final result (@pxref{Sequencing}).
Evaluation and printing takes place @emph{after} running all the Lisp
files from non-option arguments, and @emph{before} executing the REPL
(when in interactive mode).
@*
This option does not by itself change JitterLisp's mode to
non-interactive.
@end table
@noindent
Unfortunately the quoting rules for Bourne shells make Lisp quoting
and quasiquoting
(@pxref{Quoting and quasiquoting})
somewhat inconvenient to use from the Unix command line:
@c @codequoteundirected on
@example
bin/jitterlisp--boehm --no-repl --eval='(let ((a 42)) `(a is ,a))'
bin/jitterlisp--boehm --no-repl --eval="(let ((a 'b)) \`(a is ,a))"
bin/jitterlisp--boehm --no-repl --eval='(let ((a '\''b)) `(a is ,a))'
bin/jitterlisp--boehm --no-repl --eval=\'the-result-is-a-symbol
@end example
@c @codequoteundirected off
@noindent
At least in simple cases a user should be able to work around such
problems by defining a macro in a Lisp file, to be used in the
@option{--eval} argument without requiring complex quoting in the
command line.  An alternative is avoiding the quoting prefix notation
(@pxref{prefix-notation})
altogether, writing for example
@code{(quote b)}
instead of
@code{'b} within single-quoted shell text.

Some options affect the way JitterLisp prints out information and let
users deviate from the default behavior.
@table @option
@cindex @option{--no-omit-nothing}, command-line option
@item --no-omit-nothing
Print back @nothing{} when it occurs as the result of a user form
(@pxref{Uniques}),
in interactive use or with @option{--eval}.  The default is to omit
it, as @nothing{} represents an ``uninteresting'' result from a form
which is normally evaluated for its side effects.

@cindex @option{--colorize}, command-line option
@item --colorize
@cindex font
@cindex color
Print Lisp data using color and font variations to make different
object types easier to distinguish at a glance.
@cindex font
@cindex color
@cindex highlight, Lisp type
@cindex terminal escape sequence, ANSI
@cindex ANSI terminal escape sequence
@cindex escape sequence, ANSI terminal
@cindex sequence, escape, ANSI terminal
The current implementation, quite crude, relies on ANSI terminal
escape sequences and uses a choice of colors suitable for a black
or dark background.

@cindex color
@cindex font
The default is to always use the default terminal color and font,
without emitting escape sequences.

@cindex @option{--compact-uninterned}, command-line option
@cindex @option{-c}, command-line option
@item -c@r{, }--compact-uninterned
Print uninterned symbols
(@pxref{uninterned-symbols})
in an alternative, more compact notation using a per-symbol index
rather than a memory address.  The index may theoretically wrap
around after allocating a very high number of uninterned symbols.

@cindex @option{--cross-disassembler}, command-line option
@cindex disassembly, cross
@cindex cross-disassembly
@item --cross-disassembler
Use the cross-disassembler specified at Jitter configuration time
(@pxref{Disassembly,,, jitter, The Jitter Manual})
rather than the default native disassembler to print out native
code for compiled closures
(@pxref{disassembly}).

@cindex emulator
@cindex @command{objdump}
@cindex GNU binutils
@cindex architecture, hardware
@cindex hardware architecture, host (cross-compilation)
@cindex host (cross-compilation)
@cindex disassembly
@cindex disassembly, cross
The cross-disassembler is useful for running JitterLisp on an emulator
for a foreign hardware architecture, using an @command{objdump}
executable from cross-configured GNU binutils having a name different
from the @command{objdump} program running on the host machine.

@cindex disassembly
@cindex disassembly, native
The default, reasonable for running JitterLisp without command-line
options on the host architecture it was configured for, is using the
native disassembler.

@cindex @option{--free-routines}, command-line option
@cindex routine, Jittery
@cindex routine, non-executable, Jittery
@cindex routine, executable, Jittery
@cindex non-executable, Jittery routine
@item --free-routines
Normally, when compiling a closure (@pxref{Compilation}) the
JitterLisp system keeps two versions of the resulting VM routine in
memory: one @dfn{non-executable routine}, and one @dfn{executable
routine}.  The executable routine is necessary for executing the
closure code, and therefore will always remain in memory until
garbage-collected---or for ever, in the case of littering JitterLisp
programs.  The non-executable routine, on the other hand, can be
destroyed immediately at compilation time to save memory; its only
purpose after compilation is debugging, using @code{disassemble} and
@code{disassemble-vm} (@pxref{Compilation} and @pxref{Disassembly,,,
jitter, The Jitter Manual}).

By default JitterLisp keeps non-executable routines in memory, and
garbage-collects them along with executable routines.  By specifying
this option only executable routines are kept, which saves memory at
the cost of making debugging output less friendly if not, according to
the dispatch, completely useless.

@cindex @option{--no-verbose-litter}, command-line option
@item --no-verbose-litter
@cindex litter
@cindex standard error
@cindex message, litter allocation
A JitterLisp executable littering memory (@pxref{litter}) will by
default print a message to the standard error every time a new block
of memory is allocated.  Such warnings, although distracting, are
useful to remind the user that the running program is allocating
memory from a growing heap which will not be freed, and are therefore
enabled by default.
@*
Non-littering executables will accept and silently ignore verbose
littering options.

@cindex message, litter allocation
This option suppresses litter-allocation messages.

@cindex @option{--time=@var{time}}, command-line option
@cindex @samp{no}, option argument for @option{--time=@var{time}}
@cindex @samp{yes}, option argument for @option{--time=@var{time}}
@cindex @samp{verbose}, option argument for @option{--time=@var{time}}
@item --time[=@var{time}]
When this option is given with @var{time} unspecified or different from
@samp{no} the REPL times interactive commands and prints a human-readable
message specifying the elapsed time in seconds after each evaluation.
Valid values for @var{time} are @samp{no}, @samp{yes} and @samp{verbose}.
A @var{time} value of @samp{verbose} causes the timed command to be printed
back along with the time, which is convenient when interactively running
multiple commands on the same line, to be executed in sequence and timed
independently.

The default is not printing timings, as with @samp{no}, when the option is
not given.  Giving the option without specifying @var{time} is equivalent to
setting @var{time} to @samp{yes}.

Only commands executed by the REPL are timed: this excludes library
initialization, code from Lisp files specified in the command line,
and arguments from the @option{--eval} option.

@cindex @option{--omit-nothing}, command-line option
@item --omit-nothing
@cindex @option{--no-colorize}, command-line option
@item --no-colorize
@cindex @option{--no-compact-uninterned}, command-line option
@item --no-compact-uninterned
@cindex @option{--no-cross-disassembler}, command-line option
@item --no-cross-disassembler
@cindex @option{--no-free-routines}, command-line option
@item --no-free-routines
@cindex @option{--verbose-litter}, command-line option
@item --verbose-litter
@cindex @option{--no-time}, command-line option
@item --no-time
These are the negative counterparts of the options above, restoring
the respective default behaviors.
@end table

The last group of options is mostly meant for the development of
JitterLisp itself with respect to debugging or benchmarking.
@table @option
@cindex @option{-v}, command-line option
@cindex @option{--verbose}, command-line option
@item -v@r{, }--verbose
@cindex verbosity
@cindex debug
Print out debugging information about JitterLisp's execution progress,
including the full macroexpansion and evaluation of each library form
executed at startup.
The default it not to print such information.

This option may occasionally be useful to discover the approximate
origin of a problem, such as which of several provided Lisp files
caused an error.

@cindex @option{--no-optimization-rewriting}, command-line option
@item --no-optimization-rewriting
@cindex rewriting
@cindex VM instruction rewriting
@cindex instruction, VM, rewriting
@cindex compilation
Disable VM instruction rewriting (@pxref{Instruction rewriting,,,
jitter, The Jitter Manual}).  This is only useful for debugging
rewrite rules or benchmarking their effect, or theoretically for
making compilation more efficient at the price of slower execution
of compiled code.

Instruction rewriting is enabled by default.

@cindex @option{--no-library}, command-line option
@item --no-library
@cindex library, default, Lisp
@cindex default library, Lisp
@cindex Lisp default library
@cindex C
Do not run the default Lisp library at initialization, exposing only
the language and library features implemented in C.

@cindex core macro
@cindex C, macro defined in
@cindex macro, core
@cindex primitive wrapper
The predefined Lisp globals available when using this option will be
limited to the ones marked as ``core macro'', and ``primitive
wrapper'' in the reference documentation (@pxref{Lisp reference}),
plus the associated primitives; in particular there will be no support
for high-level macro definitions (@pxref{high-level-macros}),
AST optimization
(@pxref{AST optimization})
or compilation
(@pxref{Compilation}).
A few globals documented as ``macro'' have actually two separate
implementations, the first in C as a ``core macro'', to be used at
initialization for bootstrapping the system, and then a second,
cleaner or more powerful redefinition as an ordinary ``macro'',
in Lisp.  The option @option{--no-library} exposes the
core macro implementation in this case, which may differ in subtle
ways from the normally available definition, and in fact is allowed
to contradict the specification in this manual.

This option is meant for debugging JitterLisp itself.

@cindex @option{--no-verbose}, command-line option
@item --no-verbose
@cindex @option{--optimization-rewriting}, command-line option
@item --optimization-rewriting
@cindex @option{--library}, command-line option
@item --library
The negative versions of the options above.
@end table


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Interaction example
@section Interaction example
This section will present the main features setting JitterLisp apart
from other Lisp systems to readers already familiar with other Lisp
dialects.

@cindex beginner
@cindex promising beginner
@cindex ambition
@cindex learning Lisp
@cindex programmer, non-
I believe that a sufficiently motivated beginner should be able to
follow this section, possibly after first understanding the fundamentals
of Lisp from the beginning of the reference part of this document
(@pxref{Lisp reference}).
I am particularly interested in feedback from readers who cannot
program yet or are only weak programmers but are making a serious
attempt to learn by following this route; any beginner with useful
feedback to provide, positive or negative, is welcome to contact me
(@pxref{Contacting the author,,, jitter, The Jitter Manual}).

???????????
@fixme{Write this}
@fixme{it's a stack machine}

@fixme{@code{+} is a macro}

@fixme{look at an interpreted closure}

@fixme{@code{macroexpand}}

@fixme{do some simple computation over ASTs}

@fixme{optimize explicitly}

@fixme{optimize retroactively}

@ignore
@result{} foo
@expansion{} foo
@print{} foo
@error{} foo
@end ignore

@fixme{These are just ideas.  The variable @code{x} is unbound.}
@example
(append '(a b c) '(1 (2 3) 4))
  @result{} (a b c 1 (2 3) 4)


x
  @error{} unbound variable x
'x
  @result{} x
(macroexpand x)
  @error{} unbound variable x

(macroexpand 'x)
  @result{} [variable x]
(macroexpand ''x)
  @result{} [literal x]
(macroexpand '''x)
  @result{} [literal (quote x)]
(macroexpand ''''x)
  @result{} [literal (quote (quote x))]

(define (twice n)
  (* n 2))
(twice 10)
  @result{} 20
twice
  @result{}
  #<interpreted-closure () (#<u680>)
    [primitive #<primitive 2* 1-ary> [variable #<u680>]]>

(define-macro (when-zero discriminand . body)
  `(when (zero? ,discriminand) ,@@body))

(macroexpand '(when-zero a b c))
  @result{}
  [if [call [variable zero?] [variable a]]
        [sequence [variable b]
                  [variable c]]
        [literal #<nothing>]]
(when-zero 42 (display 'foo) (newline))
  @expansion{}
  [if [call [variable zero?] [literal 42]]
      [sequence [call [variable display] [literal foo]]
                [call [variable newline]]]
      [literal #<nothing>]]
  @result{}
  @nothing{}

;; For people familiar with Common Lisp:
(define-macro (defun operator formals . body-forms)
  `(define (,operator ,@@formals)
     ,@@body-forms))
(define-macro (defmacro operator formals . body-forms)
  `(define-macro (,operator . ,formals) ;; FIXME: why not (,operator ,@@formals) ?
     ,@@body-forms))
;; And then:
(defun successor (n)
  (+ n 1))
(defmacro when-zero (discriminand . body)
  `(when (zero? ,discriminand)
     ,@@body))

(define my-even?
  (letrec ((my-even? (lambda (n)
                       (cond ((= n 0)  #t)
                             ((= n 1)  #f)
                             (else     (my-odd? (- n 1))))))
           (my-odd?  (lambda (n)
                       (cond ((= n 0)  #f)
                             ((= n 1)  #t)
                             (else     (my-even? (- n 1)))))))
    my-even?))
(lambda () (letrec ((f 1) (g 2)) f))
  @result{}
  #<interpreted-closure () ()
    [let #<u702> [literal #<undefined>]
      [let #<u703> [literal #<undefined>]
        [sequence [set! #<u702> [literal 1]]
                  [sequence [set! #<u703> [literal 2]]
                            [variable #<u702>]]]]]>
(macroexpand '(begin))
  @result{} [literal #<nothing>]
(macroexpand '(begin (newline)))
  @result{} [call [variable newline]]
(macroexpand '(newline))
  @result{} [call [variable newline]]
(macroexpand '(begin (display 42) (newline)))
  @result{}
  [sequence [call [variable display] [literal 42]]
            [call [variable newline]]]
(macroexpand '(begin (display 42) (newline) (newline)))
  @result{}
  [sequence [call [variable display] [literal 42]]
            [sequence [call [variable newline]]
                      [call [variable newline]]]]

@end example



@c Lisp reference
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Lisp reference
@chapter Lisp reference

@fill

@cindex homoiconicity
@fixme{we will first define Lisp data structures, then show how some
of them are mapped into expressions}
@fixme{@pxref{homoiconicity-footnote}}
@menu
* Lisp data::                           The possible shapes of Lisp objects.
* Abstract Syntax Trees and their semantics:: The core language.
* Mapping Lisp data to expressions::    Homoiconicity, the JitterLisp way.
* Program structure::                   What a JitterLisp program looks like.
* Lisp language forms::                 The JitterLisp predefined language constructs.
* Lisp library::                        What predefined globals do.
@end menu


@c Lisp data
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Lisp data
@section Lisp data

@cindex boxed, Lisp object
@cindex unboxed, Lisp object
@fixme{boxed and unboxed objects}

@cindex read syntax
@cindex write syntax
@cindex syntax
All Lisp data have an @dfn{output notation}, and some can be
read from input via a @dfn{read syntax} as well.  The two syntaxes,
where both defined, are compatible.
@*
For example the number @code{1234}, the boolean @code{#t} and the
symbol @code{this-is-a-symbol} are written back by the system (when they
occur as results in the REPL, or in output) as @code{1234},
@code{#t} and @code{this-is-a-symbol}, in the same syntax available to
the user for data input.  However some other objects such as
procedures can be described in the output (for example
@samp{#<interpreted-closure () (x-1 x-0) [primitive #<primitive cons
2-ary> [variable x-1] [variable x-0]]>}), but have no corresponding
read syntax to be directly input as immediates.  Any object can still
be built programmatically.

@cindex address
@cindex sharing
@cindex substructure sharing
@cindex DAG, output syntax
@cindex Directed Acyclic Graph, output syntax
@cindex circularity
@cindex cycle (of pointers, within a Lisp object)
@fixme{Out of convenience the written notation of an object does not
necessarily convey all of the information about it; for example, the
memory address where an object is stored does not appear, yet is
important in the execution semantics in order to check whether two
objects are the same.  The output notation @emph{does} express the presence of
substructure sharing within a single Lisp object, currently without
showing more detail: an ellipsis (@samp{...}) within a printed object
stands for another boxed Lisp sub-object, it is not specified which,
that has been already printed at least once as part of object being
shown.  This does not distinguish between Direct-Acyclic-Graph
structures, where two pointers simply converge to the same address,
and pointer cycles making circular or ``infinite'' structures.  Shared
structures have no read syntax but can be built programmatically.}

It is worth to stress how the language defined in the rest of
this section describes @emph{Lisp data}, and not necessarily valid
Lisp expressions.  For example @code{foo} denotes a symbol object, but
simply typing @code{foo} at the first REPL prompt will cause an
unbound-variable error---in such a case the symbol object @code{foo}
will be macroexpanded into a @emph{variable} named @samp{foo}, even
when no such variable exists.
In the same way the read (and write) syntax @code{(1 2 3)} denotes a
well-formed Lisp datum, but would macroexpand to a @emph{procedure call} with
@code{1} as the operator, immediately causing a failure on evaluation.
@xref{Quoting and quasiquoting} for information about the @dfn{quoting}
syntax for building expressions evaluating to literal Lisp objects.

@fill

Every Lisp datum contains a @dfn{value} and a @dfn{type}.  Given a
datum it is always possible to check for its type at run time by means
of some predefined procedure (@pxref{type-checking-procedures}).

Since JitterLisp has, at least currently, no subtyping relation, each
object belongs to exactly one of the following types.  However some
predefined procedures are provided to check whether an object belongs
to one of several related data types; for example @code{closure?} will
recognize either an interpreted closure or a compiled closure as a
``closure''.

@fixme{any two object are comparable by identity: see @code{eq?}.}

@anchor{macroexpansion}
@fixme{talk about macroexpansion}

@menu
* Uniques::                 A few special objects.
* Fixnums::                 Smallish-range integers.
* Characters::              The fundamental elements of text.
* Symbols::                 Comparable and usually named objects.
* Conses::                  Mutable object pairs.
* Boxes::                   Mutable objects contining another object.
* Interpreted closures::    Procedures to be interpreted.
* Compiled closures::       Faster procedures for the VM.
* Primitives::              Procedure-like objects implemented in C.
* Abstract Syntax Trees::   Code to be interpreted or compiled.
* Macros::                  Procedure-like things to generate ASTs.
* Primitive macros::        Macros implemented in C.
@end menu

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Uniques
@subsection Uniques
@cindex unique

@fill
@fixme{immutability}

@cindex empty list
@cindex list, empty
A unique object important in practice is @dfn{the empty list}:
@syindex ()@r{ (empty list object)}
@syindex @r{parentheses (}@code{()}@r{), empty list object}
@deffn {unique} ()
In read syntax it is acceptable to separate the open and closed
parentheses with arbitrary whitespace or comments, in which last case
the closed parentheses will be found on a separate line.
@end deffn
@noindent
There exists exactly one empty list object, written as @code{()}.  It
is used, in particular, as the trailing part of the of every list
@emph{spine}:
@pxref{lists}.

@cindex Boolean
@cindex Boolean, canonical
@cindex canonical Boolean
@cindex true
@cindex false
A @dfn{Boolean} or @dfn{canonical Boolean} object represents a truth
value, either @dfn{false} or @dfn{true}.  There are exactly two
Booleans:
@syindex #f
@deffn  {unique} #f
@syindex #t
@deffnx {unique} #t
The false object is written as @code{#f};
the true object is written as @code{#t}.
@end deffn
@noindent
@cindex generalized Boolean
@cindex Boolean, generalized
@cindex conditional
@cindex loop
In practical use @code{#f} tends to be more important than @code{#t},
as JitterLisp conditionals and loops distinguish between the @code{#f}
value and @emph{any other} Lisp object which is taken as ``true'' for
the purposes of tests.  A Lisp object used as a Boolean
in this extended sense is called a @dfn{generalized Boolean}.  Of
course generalized Booleans are not necessarily unique objects.

@fixme{a few words about the following uniques}
@syindex #<nothing>@r{ (no read syntax)}
@deffn  {unique, no read syntax} #<nothing>
@syindex #<eof>@r{ (no read syntax)}
@deffnx {unique, no read syntax} #<eof>
@syindex #<undefined>@r{ (no read syntax)}
@deffnx {unique, no read syntax} #<undefined>
@end deffn
@fixme{what they are used for}

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Fixnums
@subsection Fixnums
@cindex fixnum

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Characters
@subsection Characters
@cindex character

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Symbols
@subsection Symbols
@cindex symbol

@anchor{uninterned-symbols}

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Conses
@subsection Conses
@cindex cons
A @dfn{cons} is a pair object containing exactly two other Lisp
objects, allowed to be conses in their turn or objects of any other types.
Conses are mutable, in the sense that the two components of a cons can
be changed at run time while keeping the identity of the cons object.

@cindex car
@cindex cdr
The first object contained in a cons is called its @dfn{car}, the second is
called its @dfn{cdr}.

@cindex syntax, cons
@cindex read syntax, cons
@cindex output syntax, cons
@syindex (@r{ (open parenthesis, cons syntax)}
@syindex )@r{ (closed parenthesis, cons syntax)}
@syindex @r{parenthesis, cons syntax}
@syindex .@r{ (dot, cons syntax)}
@syindex @r{dot (}@code{.}@r{), cons syntax}
@syindex @r{period (}@code{.}@r{), cons syntax}
@quotation Syntax
If @var{a} and @var{b} are two Lisp objects, then
@code{(@var{a} . @var{b})} is a cons containing
@var{a} as its car and @var{b} as its cdr.
@end quotation

@cindex composed selector, cons
Let @var{S} be any nonempty sequence of the characters ``a'' and
``d''.  Then the @dfn{ca@var{S}r} of a cons is the car of the
c@var{S}r of the cons, and its @dfn{cd@var{S}r} is the cdr of its
c@var{S}r.
@cindex caddr
For example the caddr of an object is the car of the cdr
of its cdr.  Such @dfn{composed cons selector} names are convenient to
use when referring to nested components of a cons, and the JitterLisp
library provides functionality to access them with any @var{S} of
length 1, 2 and 3---therefore, for a level of nesting up to 4.

@anchor{lists}
@cindex list
A @dfn{list} is either the empty list object or a cons whose cdr is
another list.
For example @code{()}, @code{(#t . ())}, @code{(#f . (3 . ()))}
and @code{((1 . 2) . ())} are lists;
@code{(#t . #t)} is not a list.

@cindex sublist
@cindex element, list
A @dfn{sublist} of a nonempty list is either its cdr or a sublist of
its cdr.
The @dfn{elements} of a nonempty list are the car of the list and the
elements of its sublists.
The empty list has no sublists and no elements.
@*
For example the list
@code{(foo . (10 . (bar . ())))} has the three sublists
@code{(10 . (bar . ()))},
@code{(bar . ())}
and
@code{()},
and the three elements
@code{foo}, @code{10} and @code{bar}.
@c The empty list @code{()} has no sublists and no elements.
Given a nonempty list its first element and its first sublist can always
be found by taking, respectively, the car and the cdr of the list.  Taking
the car and cdr of the first sublist yields the second element and the
second sublist of the original list, and so on.
@*
It is easy to see how some composed cons selectors applied to a list
identify specific sublists and elements: the list sublists will be its
cdr, cddr, cdddr, cddddr, and so on; then taking the car of the list
itself and its sublists yields the list elements: therefore the first,
second, third and fourth element of a list will be respectively its car,
cadr, caddr and cadddr.

@cindex spine, list
The following notation makes lists much easier to write, as it
suppresses every dot on the list @dfn{spine} and many parentheses; it
can be used on many non-list conses as well:
@cindex compact cons notation
@cindex cons notation, compact
@cindex notation, cons, compact
@syindex @r{parenthesis, compact cons notation}
@syindex .@r{ (dot), compact cons notation}
@syindex @r{dot (}@code{.}@r{), compact cons notation}
@syindex @r{period (}@code{.}@r{), compact cons notation}
@quotation Compact cons notation
Let @var{a} and @var{b} be two objects.
When @var{b} is either the empty list @code{()} or a cons, the
cons @code{(@var{a} . @var{b})} can be written in the
@dfn{compact cons notation}: in compact notation @emph{both} the dot
and the parentheses around @var{b} are omitted.

JitterLisp always adopts the compact cons notation in output, whenever
applicable.  Its use in input is optional.
@end quotation
@noindent
For example
@code{(7)} is a compact way of writing @code{(7 . ())},
@code{(1 2)} is a compact way of writing @code{(1 . (2 . ()))},
@code{((a))} is a compact way of writing @code{((a . ()) . ())},
and @code{(10 a . #t)} is a compact way of writing the non-list
@code{(10 . (a . #t))}.

@anchor{prefix-notation}
A further syntactic convenience is available for particular conses,
which are also lists:
@cindex notation, prefix
@cindex prefix notation
@quotation Prefix notation
Let @var{q} be the read syntax for a Lisp object.  Then:
@itemize
@item
@syindex '@r{ (apostrophe, prefix for @code{quote})}
@syindex @r{apostrophe (}'@r{), prefix for @code{quote}}
@code{'@var{q}} is an alternative read syntax for @code{(quote @var{q})};
@item
@syindex `@r{ (backtick, prefix for @code{quasiquote})}
@syindex @r{backtick (}`@r{), prefix for @code{quasiquote}}
@code{`@var{q}} is an alternative read syntax for @code{(quasiquote @var{q})};
@item
@syindex ,@r{ (comma, prefix for @code{unquote})}
@syindex @r{comma (},@r{), prefix for @code{unquote}}
@code{,@var{q}} is an alternative read syntax for @code{(unquote @var{q})};
and
@item
@syindex ,@@@r{ (comma at, prefix for @code{unquote-splicing})}
@syindex @r{comma at (},@@@r{), prefix for @code{unquote-splicing}}
@code{,@@@var{q}} is an alternative read syntax for @code{(unquote-splicing @var{q})}.
@end itemize
The prefix notation is recognized by the reader, but currently not emitted
in output.  Its use in input, again, is optional.
@end quotation
@noindent
The prefix notation serves to express quoting and quasiquoting in a more
convenient way: @pxref{Quoting and quasiquoting}.

It is worth stressing that lists are not special at the language
level and do not constitute a separate type: the name ``list'' is
just a characterization of the shape of some objects, common in
practice, which include the empty list object and some conses.

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Boxes
@subsection Boxes
@cindex box

Boxes have no read syntax.

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Interpreted closures
@subsection Interpreted closures
@cindex interpreted closure

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Compiled closures
@subsection Compiled closures
@cindex compiled closure
@fixme{An interpreted closure can destructively change to a compiled
closure (but not vice-versa) without changing its identity.}

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Primitives
@subsection Primitives
@cindex primitive

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Abstract Syntax Trees
@subsection Abstract Syntax Trees
@cindex Abstract Syntax Tree (AST)
An @dfn{Abstract Syntax Tree} or @dfn{AST} is a recursive type
representing code as a data structure.  ASTs only support the core
language forms which remain after macroexpanding away
(@pxref{macroexpansion}, @pxref{Macroexpanding})
every macro use: Lisp code rewritten
not to use any macro turns into an AST, which can be then interpreted or
compiled, or even analyzed and transformed by other Lisp code.

@cindex reflection
@cindex self-compiler
@cindex self-optimizer
@cindex compiler, self-
@cindex optimizer, self-
JitterLisp in fact contains no executor for Lisp: there are only an
@dfn{AST interpreter}, written in C, and an @dfn{AST compiler}
written in Lisp and translating ASTs into code for the Jittery VM.
It is thanks to the reflection capabilities provided by the AST data
type that it is possible to write a self-compiler, and also a
self-optimizer, in the language itself.

Even if ASTs have no read syntax the JitterLisp library provides
facilities to conveniently inspect and build ASTs: @pxref{AST
operations}.

@xref{Abstract Syntax Trees and their semantics} for a complete description of
the structure of Abstract Syntax Trees and their behavior.

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Macros
@subsection Macros
@cindex macro (type)

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Primitive macros
@subsection Primitive macros
@cindex primitive macro


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Abstract Syntax Trees and their semantics
@section Abstract Syntax Trees and their semantics
@cindex Abstract Syntax Tree (AST)
JitterLisp code is executed by first translating user syntax into
@dfn{Abstract Syntax Trees}, which are easy to interpret or compile.
Far from being only an implementation device, JitterLisp ASTs are also
exposed to the user who may execute them
(@pxref{Code execution})
and also work on them just as on any other Lisp data structure.

There is no read syntax allowing the user to directly enter an AST as
a literal datum; however the library includes sufficient functionality
to inspect or build ASTs (@pxref{AST operations}).  Such functionality
is used extensively in macroexpansion and compilation.

@menu
* AST syntax::       A definition of the possible shapes for correct ASTs.
* AST semantics::    How the evaluation of an AST behaves.
@end menu

@c @@@@@@@@@@@@@@@
@node AST syntax
@subsection AST syntax

@cindex syntax (output), ASTs
@cindex AST output syntax
@cindex AST syntax (output)
ASTs define a minimalistic programming language, operating on
Lisp data but otherwise not particularly similar to Lisp.  The syntax
given here is the @emph{output} syntax used by the implementation for
printing AST data, for example as the result of @code{macroexpand}
(@pxref{Macroexpanding}).  This syntax is designed to be simple and
unambiguous.  In order to visually stand apart from user syntax it
indicates grouping by brackets (@samp{[}, @samp{]}) rather than
parentheses.

@cindex @code{.} AST meta-syntax
@cindex dot (@code{.}), AST meta-syntax
A dot (@samp{.}) in the syntax below indicates the convention of
writing a sequence of zero or more entities, represented in memory as
a list, @emph{without} the surrounding parentheses.  For example a
valid primitive following the syntax
@samp{[primitive @var{operator} . @var{operands}]}
will be @code{[primitive + [literal 2] [variable x]]},
where @code{[literal 2]} and @code{[variable x]} are ASTs encoded as
the two elements of a list within the AST for the primitive.

@cindex expression, AST
Every AST represents an @dfn{expression}.  Each expression has exactly
one of the following forms, named after the identifier immediately
following the open bracket:
@itemize @bullet
@c -------
@cindex literal, AST syntax
@item @code{[literal @var{value}]}, a @dfn{literal}.

@cindex value, literal, AST syntax
The literal @var{value} may be any Lisp datum.
@c -------

@cindex variable, AST syntax
@cindex reference, variable, AST syntax
@item @code{[variable @var{name}]}, a @dfn{variable} or @dfn{variable reference}.

@cindex name, variable, AST syntax
The variable @var{name} must be a symbol.
@c -------

@cindex primitive, AST syntax
@item @code{[primitive @var{operator} . @var{operands}]}, a @dfn{primitive} or @dfn{primitive use}.

@cindex operator, primitive, AST syntax
@cindex primitive name, primitive, AST syntax
The primitive @var{operator} or @dfn{primitive name} must be a symbol
which is the name of a primitive.
@cindex operands, primitive, AST syntax
The primitive @var{operands} must be a list of ASTs, having exactly
as many elements as the arguments expected by the named primitive.
@c -------

@cindex let, AST syntax
@cindex block, AST syntax
@item @code{[let @var{name} @var{bound-expression} @var{body}]}, a @dfn{let} or @dfn{block}.

@cindex bound variable, block, AST syntax
@cindex name, block, AST syntax
The @var{name} or @dfn{bound variable name} in a block must be a symbol.
@cindex bound expression, block, AST syntax
A block @var{bound-expression} must be an AST.
@cindex body, block, AST syntax
A block @var{body} must also be an AST.
@c -------

@cindex global definition, AST syntax
@item @code{[define @var{name} @var{expression}]}, a @dfn{definition} or @dfn{global definition}.

@cindex name, global definition, AST syntax
The @dfn{global definition} @var{name} must be a symbol.
@cindex expression, global definition, AST syntax
The definition @var{expression} or @dfn{defined expression} must be an AST.
@c -------

@cindex assignment, AST syntax
@cindex set!, AST syntax
@item @code{[set! @var{name} @var{expression}]}, an @dfn{assignment}.

@cindex name, assignment, AST syntax
@cindex variable name, assignment, AST syntax
@cindex expression, assignment, AST syntax
The @dfn{assignment} variable @var{name} must be a symbol.
The assignment @var{expression} must be an AST.
@c -------

@cindex sequence, AST syntax
@item @code{[sequence @var{expression-0} @var{expression-1}]}, a @dfn{sequence}.

@cindex first expression, sequence, AST syntax
@cindex second expression, sequence, AST syntax
@cindex expresion-0, sequence, AST syntax
@cindex expresion-1, sequence, AST syntax
Each of the @dfn{first expression} or @var{expression-0} and
the @dfn{second expression} or @var{expression-1} in a sequence must be
an AST.
@c -------

@cindex conditional, AST syntax
@cindex if, AST syntax
@item @code{[if @var{condition} @var{then-branch} @var{else-branch}]}, a @dfn{conditional}.

@cindex condition, conditional, AST syntax
@cindex then branch, conditional, AST syntax
@cindex else branch, conditional, AST syntax
@cindex branch, conditional, AST syntax
The conditional @var{condition} and its two @dfn{branches} must
all be ASTs.
@c -------

@cindex while, AST syntax
@cindex loop, AST syntax
@item @code{[while @var{guard} @var{body}]}, a @dfn{while} or @dfn{loop}.

@cindex guard, while, AST syntax
@cindex body, while, AST syntax
Each of the loop @var{guard} and @var{body} must be an AST.
@c -------

@cindex lambda, AST syntax
@cindex abstraction, AST syntax
@item @code{[lambda @var{formals} @var{body}]}, a @dfn{lambda} or @dfn{abstraction}.

@cindex formal, lambda, AST syntax
@cindex argument (formal), lambda, AST syntax
The lambda or @dfn{abstraction} @var{formals} or @dfn{formal arguments}
must be a list of symbols, all different from one another.
@cindex body, lambda, AST syntax
The lambda @var{body} must be an AST.
@c -------

@cindex call, AST syntax
@cindex procedure call, AST syntax
@item @code{[call @var{operator} . @var{operands}]}, a @dfn{call} or @dfn{procedure call}.

@cindex operator, call, AST syntax
@cindex call name, call, AST syntax
The call (or @dfn{procedure call}) @var{operator} must be an AST.
@cindex operands, call, AST syntax
The call @var{operands} must be a list of ASTs.
@c -------
@end itemize

@cindex minimalism
@cindex complexity, syntax
@cindex syntactic complexity
The forms above specify @emph{the entirety} of the AST syntax: every
JitterLisp form, before being executed, is translated into an AST having
one of the shapes described above, which in many cases will contain other
ASTs; all the language power and complexity arise solely from the
@emph{combination} of those AST forms.
@*
@cindex syntactic abstraction
@cindex abstraction, syntactic
@cindex macro
Conspicuously absent from the forms above is any form of
@dfn{syntactic abstraction} such as macros: macros serve to automatically
rewrite complex user syntax into a combination of simple ASTs, so that no
use of a macro survives the expansion process.

@cindex syntactic constraint, AST
@cindex AST syntactic constraint
It is important to notice that the syntactic constraints specified
above, for example @code{[if@tie{}@r{@dots{}}]} having exactly three
subforms and the first component of @code{[set!@tie{}@r{@dots{}}]} being a
symbol, are verified at AST construction time: it is impossible to
build a syntactically incorrect AST without immediately failing.
In this sense only syntactically correct ASTs may be said to ``exist''.

@c @@@@@@@@@@@@@@@
@node AST semantics
@subsection AST semantics
@cindex imperative
@cindex scoping
@cindex state
@cindex global state
@cindex eager
@cindex call-by-value
JitterLisp ASTs constitute an eager imperative call-by-value language
based on named, lexically scoped variables and global state.

What follows is an attempt of describing the behavior of AST
evaluation in a precise way without the burden of complicated
notation.

@cindex operational semantics (in the reader's head)
@cindex logic rules, operational semantics (in the reader's head)
The mathematically inclined reader will see immediately how the AST
semantics would be easy to model in an operational style, with logic
rules having multiple premises and one conclusion.
Here I will content myself with rendering such rules into more
accessible English.

@menu
* Semantics preliminaries::      The general ideas, and the entities involved.
* Failure::                      JitterLisp handles failure in a crude way.
* AST semantics in detail::      How each AST behaves.
* From ASTs to JitterLisp::      You can see what macros do by looking at ASTs.
@end menu

@c @@@@@@@@
@node Semantics preliminaries
@subsubsection Semantics preliminaries

@cindex lexical scoping
@cindex static scoping
@cindex scoping, lexical
JitterLisp, like most modern Lisp dialects with the (now partial)
exception of Emacs Lisp, is @dfn{lexically scoped}.  This means that a
variable use refers to the innermost variable binding with the same
name which syntactically contains the variable AST as a sub-AST.  This
reference may be different from the @emph{most recent}
binding in time still in force for the same variable---which is used
in ``dynamically scoped'' languages, but not in JitterLisp.

An @dfn{environment} is a mapping from each variable name to its
associated value.  During the evaluation of an AST some environment is
always implicitly in force, which dictates the current value of every
variable.

Variable scopes can be @emph{nested}, adding bindings to the local
environment which are visible by variable references until the scope
ends.
An inner block or call may @dfn{shadow} a variable binding, by
re-binding a variable with the same name to a possibly new value and
thus making the original variable temporarily inaccessible, as long as
the new environment re-binding the same variable is in force.

Some variables may be @dfn{globally bound}: the global binding for a
variable records the default value of a variable to be used when a
variable is not bound in the currently active environment.

@c @@@@@@@@
@node Failure
@subsubsection Failure

@cindex error
@cindex failure
JitterLisp treats @dfn{failure} or @dfn{errors} in a trivial way.

@cindex failure, out of the REPL
@cindex error, out of the REPL
If evaluation fails at any point out of the REPL, then the error is
fatal: the execution ends, and the JitterLisp program exits reporting
failure.

@cindex failure, at the REPL
@cindex error, at the REPL
If evaluation fails when evaluating a form entered at the REPL, then
the error is equally unrecoverable, and the AST evaluation terminates
reporting failure; however the REPL is @emph{not} exited, and the user
has the opportunity to try and execute other forms in a state altered
by the changes which were executed with success @emph{before} the
error, starting again in an empty local environment.

@cindex exceptions (@emph{non-existing} feature)
JitterLisp currently provides no exception system, either at the AST
level or as part of higher layers.
@*
@syindex throw@r{ (@emph{non-existing} form)}
@syindex catch@r{ (@emph{non-existing} form)}
@syindex error
The @code{error} primitive (@pxref{Erroring out}) provides a way to
explicitly fail under program control, but it is not possible to
recover from such a failure with any form similar to ``@code{catch}''
or ``@code{try}'' as they exist in other Lisp dialects or in other
languages.

@c @@@@@@@@
@node AST semantics in detail
@subsubsection AST semantics in detail

An AST is evaluated in a given @emph{environment}, which is empty at
the top level.

Evaluating an AST will either fail or yield exactly one value, allowed
to have any JitterLisp data type (@pxref{Lisp data}), as the
@dfn{result}.
@fixme{non-termination}

In the following, particularly within examples, I will use the
following notation:
@smallquotation Evaluation notation
@c@*
@*
@var{form}, @var{environment} @result{} @var{result} [@print{} @var{output}]
@*
@c@*
@var{form}, @var{environment} @error{}
@c@*
@end smallquotation
To mean, respectively, that a given form evaluated with a given environment
either returns a result (possibly with an output side effect), or fails.  An
environment, as stated already, is a mapping from variables to values.

@fixme{Update the evaluation notation and the description below: a form should return a
new environment as the result, and possibly a new global environment as well.}
@fixme{distinguish environment extension from environment update.  This is important
for let versus set!, below.}

@cindex circularity (forbidden), AST
@cindex cyclicity (forbidden), AST
@cindex DAG, AST in memory
@cindex Directed Acyclic Graph, AST in memory
@cindex structure sharing, AST
ASTs must be finite in size and non-circular@footnote{At the time of
writing this restriction is moot.  It is in fact impossible in the
current implementation to build a circular AST, for two reasons: first
of all, ASTs are immutable from JitterLisp, with the currently
existing primitives; second, @code{letrec} (@pxref{Blocks}) relies on
assignment to a variable when building circular closures, and the
strict constraint-checking policy of ASTs along with call-by-value
evaluation prevents a ``temporary'' value from being used inside an AST
to be built and then replaced later.}; however different parts of the
same AST are allowed to share structure, as long as AST objects in
memory form a DAG and not a cyclic graph.

@itemize @bullet
@cindex literal, AST semantics
@item @code{[literal @var{value}]}

@cindex value, literal, AST semantics
Evaluating a literal AST yields its value as the result, as contained
within the AST and independently from its type, without any further
processing, independently from the environment.
The evaluation of a literal AST always terminates and never fails.

@smallquotation Examples
@itemize @bullet
@item
@verb{|[literal #t]|}, @{@} @result{} @verb{|#t|}
@item
@verb{|[literal (a . 42)]|}, @{@} @result{} @verb{|(a . 42)|}
@item
@verb{|[literal a]|}, @{@} @result{} @verb{|a|}
@item
@verb{|[literal a]|}, @{@verb{|a|} = @verb{|42|}@} @result{} @verb{|a|}
@item
@verb{|[literal [literal a]]|}, @{@} @result{} @verb{|[literal a]|}
@end itemize
@end smallquotation
@c -------

@cindex variable, AST semantics
@item @code{[variable @var{name}]}

@cindex name, variable, AST semantics
If the named variable is bound in the current environment, then the
result is its value in the environment; otherwise, if the variable is
not bound in the environment but is bound globally, the result is
its global value.  If the variable is unbound both in the environment
and globally then the form evaluation fails.

@smallquotation Examples
@itemize @bullet
@item
@verb{|[variable a]|}, @{@} @result{} @verb{|4|} if @code{a} is globally bound to @verb{|4|}
@item
@verb{|[variable a]|}, @{@} @error{} if @code{a} is globally unbound
@item
@verb{|[variable a]|}, @{@verb{|a|} = @verb{|7|}@} @result{} @verb{|7|} independently from global bindings
@end itemize
@end smallquotation
@c -------

@cindex primitive, AST semantics
@item @code{[primitive @var{operator} . @var{operands}]}

@cindex operator, primitive, AST semantics
@cindex primitive name, primitive, AST semantics
@cindex operands, primitive, AST semantics
@cindex operand values, primitive, AST semantics
Evaluating a primitive begins by evaluating the operands, in a strict
left-to-right order, to obtain the @dfn{operand values} as results.
Then, unless evaluation has failed already on the operands, the result
is the result of applying the primitive to the operand values,
according to the primitive behavior.  This primitive application may
fail, for example if the operand values do not have the expected types,
in which case the evaluation of the entire AST fails.

@smallquotation Examples
@itemize @bullet
@item
@verb{|[primitive 1+ [literal 42]]|}, @{@} @result{} @verb{|43|}
@item
@verb{|[primitive negate [variable a]]|}, @{@verb{|a|} = @verb{|7|}@} @result{} @verb{|-7|}
@item
@verb{|[primitive 1+ [variable a]]|}, @{@} @error{} if @verb{|a|} is globally unbound or bound to a non-number
@item
@verb{|[primitive 1+ [literal a]]|}, @{@} @error{}
@item
@verb{|[primitive display [literal 42]]|}, @{@} @result{} @verb{|#<nothing>|} @print{} @verb{|42|}
@end itemize
@end smallquotation

@c -------
@cindex let, AST semantics
@cindex block, AST semantics
@item @code{[let @var{name} @var{bound-expression} @var{body}]}

@cindex bound variable, block, AST semantics
@cindex name, block, AST semantics
@cindex bound expression, block, AST semantics
@cindex body, block, AST semantics
@cindex local variable
A block serves to introduce a @dfn{local variable}, whose binding is visible
within the body.

@cindex bound value, block
Evaluating a block starts with the evaluation of the bound expression in the
current environment, whose result is the @dfn{bound value}.
Then the block body is evaluated in an environment extended by binding the
bound variable to the bound value: the result of this evaluation of the body
is the result of evaluation of the block.

If evaluating either the bound expression or the body fails, then the
evaluation of the entire block fails.

@smallquotation Examples
@itemize @bullet
@item
@verb{|[let a [literal 42] [primitive 1+ [variable a]]]|}, @{@} @result{} @verb{|43|}
@item
@verb{|[let a [primitive 1+ [literal 42]] [primitive negate [variable a]]]|}, @{@} @result{} @verb{|-43|}
@item
@verb{|[let a [literal 42] [let a [literal #t] [variable a]]]|}, @{@} @result{} @verb{|#t|}
@end itemize
@end smallquotation

@c -------
@cindex global definition, AST semantics
@item @code{[define @var{name} @var{expression}]}

@cindex name, global definition, AST semantics
@cindex expression, global definition, AST semantics
A global definition serves to alter the @emph{global binding} of a
variable.

@cindex defined value, global definition
In order to evaluate a global definition we first evaluate its
expression in the current environment, obtaining the @dfn{defined
value}.  Then we alter the global binding for the named variable,
setting it to the defined value.  Only the @emph{global} binding
is ever altered by @code{define}, even if the variable happens to
be bound locally at the time of the definition.

A global definition fails if either the expression fails or the
named variable has already been made constant (@pxref{constants}).

@syindex #<nothing>@r{ (no read syntax)}
The result of a global definition AST is @code{#<nothing>}.

@c -------
@cindex assignment, AST semantics
@cindex set!, AST semantics
@item @code{[set! @var{name} @var{expression}]}

@cindex name, assignment, AST semantics
@cindex variable name, assignment, AST semantics
@cindex expression, assignment, AST semantics
An assignment @emph{destructively} modifies the given environment,
replacing the current value for the name variable with another.  This
altered binding is visible in the following code using the same
environment.

An assignment evaluation starts by evaluating the expression in the
given environment, yielding the @dfn{assigned value} as result.  Then,
unless the expression evaluation failed, we alter a binding.  If the
named variable is locally bound, then the local environment is
modified by changing the binding for the named variable to the
assigned value; otherwise, if the named variable is globally bound,
we set its global binding to the assigned value.

Evaluating an assignment AST fails when evaluating the expression
fails, or because the variable is unbound (@emph{both} locally and
globally) at the time of the assignment, or because the variable is
locally unbound and globally bound as a constant.

@syindex #<nothing>@r{ (no read syntax)}
The result of an assignment AST is @code{#<nothing>}.

@c -------
@cindex sequence, AST semantics
@item @code{[sequence @var{expression-0} @var{expression-1}]}

@cindex first expression, sequence, AST semantics
@cindex second expression, sequence, AST semantics
@cindex expresion-0, sequence, AST semantics
@cindex expresion-1, sequence, AST semantics

A sequence serves to evaluate two ASTs one after the other.  The fact
that the sub-ASTs of a sequence are exactly two is not a limitation,
since by nesting sequences one inside the other, it is possible to
evaluate any number of ASTs.

Evaluation starts by evaluating the first expression in the given
environment, ignoring its result.  Then, in the same environment,
the second expression is evaluated; its result will be the result of
the sequence AST evaluation.

Evaluating a sequence fails if evaluating either the first or the
second expression fails.

@c -------
@cindex conditional, AST semantics
@item @code{[if @var{condition} @var{then-branch} @var{else-branch}]}

@cindex condition, conditional, AST semantics
@cindex then branch, conditional, AST semantics
@cindex else branch, conditional, AST semantics
@cindex branch, conditional, AST semantics
@fixme{write}

@c -------
@cindex while, AST semantics
@cindex loop, AST semantics
@item @code{[while @var{guard} @var{body}]}

@cindex guard, while, AST semantics
@cindex body, while, AST semantics
@fixme{write}

@c -------
@cindex lambda, AST semantics
@cindex abstraction, AST semantics
@item @code{[lambda @var{formals} @var{body}]}

@cindex formal, lambda, AST semantics
@cindex argument (formal), lambda, AST semantics
@cindex body, lambda, AST semantics
@fixme{write}

@c -------
@cindex call, AST semantics
@cindex procedure call, AST semantics
@item @code{[call @var{operator} . @var{operands}]}

@cindex operator, call, AST semantics
@cindex call name, call, AST semantics
@cindex operands, call, AST semantics
@fixme{write}

@c -------
@end itemize

@c @@@@@@@@
@node From ASTs to JitterLisp
@subsubsection From ASTs to JitterLisp

At this point, in principle, it would be possible to describe how each
individual JitterLisp form expands into ASTs.

Except in interesting or particularly subtle cases, I will avoid such pedantry.

In fact one of the justifications for having a core-based language
like JitterLisp (and epsilon) is that once the core and the expansion
mechanisms are specified in a sufficiently formal way, every language
extension automatically inherits the mathematical precision of its
definition; the source code of each macro can be, I argue, a rigorous
enough specification.

@syindex begin
@cindex C, macro defined in
@cindex macro, core
@cindex core macro
Not more than a handful of macros called @dfn{core macros} are
defined in C, and even those
should present no particular difficulty.  For example @code{begin}
(@pxref{Sequencing}) is a core macro, defined in
@file{jitterlisp-macros.c}:
@smallformat
@verbatim
/* Return the expansion of the given list of forms as a sequence.
   This is what the primitive macro begin does and the same code is
   used whenever a form sequence is allowed, for example in a lambda
   body. */
static jitterlisp_object
jitterlisp_macroexpand_begin (jitterlisp_object forms,
                              jitterlisp_object env)
{
  /* Zero-form body. */
  if (JITTERLISP_IS_EMPTY_LIST (forms))
    return jitterlisp_ast_make_literal (JITTERLISP_NOTHING);

  /* Ill-formed body. */
  if (! JITTERLISP_IS_CONS (forms))
    jitterlisp_error_cloned ("begin: non-list body");

  /* At this point we have to look inside the cons. */
  jitterlisp_object first = JITTERLISP_EXP_C_A_CAR(forms);
  jitterlisp_object rest = JITTERLISP_EXP_C_A_CDR(forms);

  /* One-form body. */
  if (JITTERLISP_IS_EMPTY_LIST (rest))
    return jitterlisp_macroexpand (first, env);

  /* Multiple-form body. */
  return jitterlisp_ast_make_sequence
            (jitterlisp_macroexpand (first, env),
             jitterlisp_macroexpand_begin (rest, env));
}
@end verbatim
@end smallformat

@syindex begin
@syindex macroexpand
@cindex macroexpansion
@cindex REPL
The code shows that the sub-forms within a @code{begin} form are
recursively expanded in right-nested sequence ASTs, and that there are
special cases for a @code{begin} with zero or one sub-forms.  It is
easy to check that this is indeed the case, by observing the ASTs
generated by @code{macroexpand} from @code{begin} forms at the REPL:
@smallexample
(macroexpand '(begin))
  @result{}
  [literal #<nothing>]
(macroexpand '(begin 42))
  @result{}
  [literal 42]
(macroexpand '(begin (display 42)))
  @result{}
  [call [variable display] [literal 42]]
(macroexpand '(begin (display 42) (newline)))
  @result{}
  [sequence
    [call [variable display] [literal 42]]
    [call [variable newline]]]
(macroexpand '(begin (display 42) (newline) (display 43) (newline)))
  @result{}
  [sequence
    [call [variable display] [literal 42]]
    [sequence
      [call [variable newline]]
      [sequence
        [call [variable display] [literal 43]]
        [call [variable newline]]]]]
@end smallexample

@syindex macroexpand
@cindex macroexpansion
The description above should be sufficient for a motivated reader,
along with @code{macroexpand} and the informal description in the
following, to follow the details of every macro definition in the
implementation.


@c @@@@@@@@@@@@@@@@@@@
@node Mapping Lisp data to expressions
@section Mapping Lisp data to expressions

@fill
@fixme{ASTs are validated at construction time: the implementation
never needs to worry about whether an already existing AST is
syntactically well-formed; this makes interpretation more efficient
and other things simpler.}


@c Program structure
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Program structure
@section Program structure

@fixme{Write this}

@menu
* Expressions::                     Evaluating a form for a result or for side effects.
* Definitions::                     Giving global names to objects.
* Constants::                       Some symbols can't be globally mutated.
@end menu

@c @@@@@@@@@@@@@@@@@@@
@node Expressions
@subsection Expressions
@fill


@c @@@@@@@@@@@@@@@@@@@
@node Definitions
@subsection Definitions
@fill


@c @@@@@@@@@@@@@@@@@@@
@node Constants
@subsection Constants
@fixme{primitive wrappers are global constants}


@c Lisp language forms
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Lisp language forms
@section Lisp language forms

@fixme{Write this.}

@cindex language form
@cindex form, language
The distinction between language and library is not clear-cut in a
system like JitterLisp with strong syntactic abstraction, where almost
all of the language is implemented in itself.  Here I present the
linguistic features which are ``fundamental'' in a conceptual way,
independently from the way they are implemented.

Users interested in distinguishing which individual feature is
implemented in C rather than as a Lisp macro may check the tag (``macro''
or ``core macro'', and only occasionally in this chapter ``primitive wrapper'')
in the documentation of each item and then follow the
sources, with the caveat that a few (important) forms are implemented
more than once: first by a temporary definition in C, in order to run
the library and initialize the global state; then, from the library
itself, the feature is re-defined in Lisp in a more general or
powerful way.

@fixme{Write this}

@fixme{lexical scoping}

@fixme{left-to-right}

@fixme{case sensitive}

@fixme{metasyntactic conventions: the dot}

@fixme{erroring out}

@cindex form, language
@cindex language form

@fixme{Write something}

@fixme{There is a lot of redundancy, by design.  It is desirable to
use the most specific form available, for readability and occasionally
also for efficiency's sake.}

@fixme{dot notation, again, like in AST syntax: here, however, we are
speaking of user syntax with Lisp conses.}

@menu
* Definition forms::         Adding or changing global variable bindings.
* Sequencing::               Executing multiple forms one after the other.
* Conditionals::             Evaluating different forms according to the result of another.
* Procedures::               Making anonymous procedure objects or ``closures''.
* Blocks::                   Establishing local variable bindings.
* Assignment::               Changing existing variable bindings.
* Loops::                    Performing the same action multiple times.
* Making macros::            Building new macros.
* Quoting and quasiquoting:: Building literal or mostly literal objects.
@end menu

@c @@@@@@@@@@@
@node Definition forms
@subsection Definition forms

@syindex define
@deffn  {macro} define defined-thing . forms
@syindex define-constant
@deffnx {macro} define-constant defined-thing . forms
@syindex define-non-optimized
@deffnx {macro} define-non-optimized defined-thing . forms
@syindex define-constant-non-optimized
@deffnx {macro} define-constant-non-optimized defined-thing . forms
@fixme{Write this}
@end deffn

@anchor{define-macro}
@syindex define-macro
@deffn  {macro} define-macro (name . args-pattern) . forms
@end deffn

@syindex macrolet@r{ (@emph{non-existing} form)}
There is currently no syntactic support for local macros, such as
Common Lisp's @code{macrolet}.


@c @@@@@@@@@@@
@node Sequencing
@subsection Sequencing

@cindex sequencing
@fixme{sequencing is nice}

@fixme{``implicit @code{progn}'' or ``implicit @code{begin}'': I do it
in more cases than Common Lisp and Scheme}

@syindex begin
@deffn {macro} begin . forms
@fixme{Write this}
@end deffn

@syindex begin-from-first
@deffn {macro} begin-from-first index . forms
@fixme{Write this}
@end deffn

@syindex begin1
@syindex begin2
@syindex begin3
@syindex begin4
@deffn {macro} begin1 form-1 . other-forms
@deffnx {macro} begin2 form-1 form-2 . other-forms
@deffnx {macro} begin3 form-1 form-2 form-3 . other-forms
@deffnx {macro} begin4 form-1 form-2 form-3 form-4 . other-forms
@fixme{Write this}
@end deffn

@syindex begin-from-last
@deffn {macro} begin-from-last index . forms
@fixme{Write this}
@end deffn

@syindex begin-1
@syindex begin-2
@syindex begin-3
@syindex begin-4
@deffn {macro} begin-1 form-1 . other-forms
@deffnx {macro} begin-2 form-1 form-2 . other-forms
@deffnx {macro} begin-3 form-1 form-2 form-3 . other-forms
@deffnx {macro} begin-4 form-1 form-2 form-3 form-4 . other-forms
@fixme{Write this}

@code{begin-1} is only provided for symmetry, and is functionally
equivalent to @code{begin} with the restriction of requiring at least
one form.
@end deffn


@c @@@@@@@@@@@
@node Conditionals
@subsection Conditionals

@cindex conditional
A @dfn{conditional} form consists in evaluating some @dfn{condition}
form and then decide which form to evaluate next according to the
result of the condition.

@syindex if
@deffn {core macro} if condition then-form . else-forms
@fixme{Write this}
@end deffn

@syindex when
@deffn {macro} when condition . forms
@fixme{Write this}
@end deffn

@syindex unless
@deffn {macro} unless condition . forms
@fixme{Write this}
@end deffn

@syindex cond
@deffn {core macro} cond . clauses
@fixme{Write this}
@end deffn

@syindex case
@deffn {macro} case discriminand . clauses
@fixme{Write this}
@end deffn


@c @@@@@@@@@@@
@node Procedures
@subsection Procedures

@anchor{lambda}
@syindex lambda
@deffn  {core macro} lambda formals . forms
@end deffn


@c @@@@@@@@@@@
@node Blocks
@subsection Blocks

@cindex block
A @dfn{block} introduces a scope where some variables are locally
bound.

@cindex lexical scoping
@cindex static scoping
@cindex scoping, lexical
Following a lexical scoping discipline a variable binding is visible
in the syntactic region where it has been bound and in every callee,
as long as it is not shadowed by an inner binding for the same
variable.

@anchor{let}
@syindex let
@syindex let*
@syindex letrec
@syindex @r{named} let
@syindex let@r{, named}
@deffn {macro} let bindings . forms
@deffnx {core macro} let* bindings . forms
@deffnx {macro} letrec bindings . forms
@deffnx {macro} let name bindings . forms
@fixme{Write this}

The fourth variant, with @var{name} being a symbol, is listed here out of completeness
but belongs with looping forms; @pxref{named-let,, named @code{let}} for its description.
@end deffn

@anchor{destructuring-bind}
@syindex destructuring-bind
@deffn {macro} destructuring-bind pattern structure . forms
@cindex template (Common Lisp)
@cindex pattern
@fixme{Write this.  Common Lisp calls ``template'' what I call ``pattern''.}
@end deffn

@c @@@@@@@@@@@
@node Assignment
@subsection Assignment

@cindex assignment
An @dfn{assignment} operation destructively modifies an existing variable binding.

@syindex set!
@deffn {core macro} set! x . forms
Evaluate the forms @var{forms} left-to-right, then assign the result of the last one
(or @nothing{} if no forms were given) to the innermost binding for the variable
@var{x}.

Error out if @var{x} is not a symbol, if @var{x} is unbound, or if the binding for
@var{x} is global and constant.
@end deffn

@cindex constant
@anchor{constants}
@fixme{speak about constants}
@quotation Rationale
@fixme{efficiency of compiled code}
@end quotation

@syindex make-constant!
@deffn {primitive wrapper} make-constant! e
@fixme{write.  @var{e} must evaluate to a symbol, which is allowed to be
@emph{also} lexically
bound; however only its global binding is affected.
  If called on a globally unbound symbol, it becomes impossible to ever assign
  @emph{or define} it.}
@end deffn

@c @@@@@@@@@@@
@node Loops
@subsection Loops

@cindex loop
A @dfn{loop} form consists in executing the same @dfn{body forms} potentially multiple
times, in sequence.

@syindex while
@deffn {core macro} while guard . forms
@fixme{Write this}
@end deffn

@syindex do
@deffn {macro} do clauses (guard . result-forms) . body-forms
@fixme{Write this}
@end deffn

@syindex dotimes
@syindex dotimesdown
@deffn  {macro} dotimes (x count-form . result-forms) . body-forms
@deffnx {macro} dotimesdown (x count-form . result-forms) . body-forms
@fixme{Write this}
@end deffn

@syindex dolist
@deffn {macro} dolist (x list-form . result-forms) . body-forms
@fixme{Write this}
@end deffn

@anchor{named-let}
@syindex named-let
@deffn  {macro} named-let name bindings . forms
@syindex @r{named} let
@syindex let@r{, named}
@deffnx {macro} let name bindings . forms
@fixme{Write this}

The other, simpler, syntax for @code{let} is described among block
forms: @pxref{let,, @code{let}}.
@end deffn

@c @@@@@@@@@@@
@node Making macros
@subsection Making macros

@anchor{low-level-macros}

@syindex low-level-macro
@deffn {core macro} low-level-macro . forms
@syindex low-level-macro-args
@fixme{Write this.  Speak of @code{low-level-macro-args}}
@end deffn

@anchor{high-level-macros}

@syindex macro
@deffn {macro} macro (macro-name . pattern) . forms
@fixme{Write this.  This uses @code{destructuring bind}
@pxref{destructuring-bind}}
@end deffn

@syindex define
@syindex define-macro
The macros above would suffice, along with @code{define}, for globally
binding macros.  However @code{define-macro} is provided as a more convenient
syntax: @pxref{define-macro}.


@c @@@@@@@@@@@
@node Quoting and quasiquoting
@subsection Quoting and quasiquoting

@cindex quoting
@syindex quote
@deffn {core macro} quote thing
@end deffn

@cindex quasiquoting
@syindex quasiquote
@syindex unquote
@syindex unquote-splicing
@deffn {macro} quasiquote template
@end deffn

@syindex quote
@syindex quasiquote
@syindex unquote
@syindex unquote-splicing
@syindex '@r{ (apostrophe, prefix for @code{quote})}
@syindex `@r{ (backtick, prefix for @code{quasiquote})}
@syindex ,@r{ (comma, prefix for @code{unquote})}
@syindex ,@@@r{ (comma at, prefix for @code{unquote-splicing})}
@syindex @r{apostrophe (}'@r{), prefix for @code{quote}}
@syindex @r{backtick (}`@r{), prefix for @code{quasiquote}}
@syindex @r{comma (},@r{), prefix for @code{unquote}}
@syindex @r{comma at (},@@@r{), prefix for @code{unquote-splicing}}
@fixme{link prefixes.  Remind that ' is usable}


@c Lisp library
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Lisp library
@section Lisp library

@fixme{Write this}

@fixme{Every symbol documented here is a global constant, except for
macros; rationale: it is convenient to be able to re-define macros in a
backwards-compatible way, and macros are not critical to performance as
macro calls are always replaced with AST combinations before evaluation}

@menu
* Type checking::                     Testing a datum's type at run time.
* Boolean operations::                Working with Booleans.
* Arithmetic::                        Operations on numbers.
* Number comparison::                 Comparing numbers.
* Symbol handling::                   Working with symbols.
* Box handling::                      Working with boxes.
* Cons handling::                     Working with conses.
* List handling::                     Working with list-shaped objects.
* Alist handling::                    Working with association lists.
* Higher order::                      Procedures working with procedures.
* Variadic utility::                  Helpers for defining variadic macros.
* Sets as lists::                     Sets as unordered list of elements
                                      compared with @code{eq?}.
* AST operations::                    Working with Abstract Syntax Trees.
* AST optimization::                  Rewriting an AST into a better AST.
* Macroexpanding::                    Explicitly expanding macros from user
                                      code.
* Code execution::                    @code{eval}, @code{apply} and friends.
* Compilation::                       Turning interpreted closures into code.
* Input and output::                  How to read and write.
* Debugging and profiling::           Convenient functionality for developers.
* Legal notices::                     Printing legal notices.
* Unclassified::                      stuff to move.
@end menu


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Type checking
@subsection Type checking

@cindex type checking
@cindex checking, type
@anchor{type-checking-procedures}

@menu
* Actual type checking::                    Testing an object type.
* Pseudo-type checking::                    Testing an object type and shape.
@end menu

@c @@@@@@@@@@@@
@node Actual type checking
@subsubsection Actual type cheking

@fixme{``Actual'' is a terrible word to use here.}

@fixme{Write.  These return a canonical Boolean and never fail.}

@syindex fixnum?
@deffn  {primitive wrapper} fixnum? x
@syindex boolean?
@deffnx {primitive wrapper} unique? x
@syindex unique?
@deffnx {primitive wrapper} boolean? x
@syindex character?
@deffnx {primitive wrapper} character? x
@syindex null?
@deffnx {primitive wrapper} null? x
@syindex eof?
@deffnx {primitive wrapper} eof? x
@syindex nothing?
@deffnx {primitive wrapper} nothing? x
@syindex undefined?
@deffnx {primitive wrapper} undefined? x
@syindex box?
@deffnx {primitive wrapper} box? x
@syindex symbol?
@deffnx {primitive wrapper} symbol? x
@syindex cons?
@deffnx {primitive wrapper} cons? x
@syindex primitive?
@deffnx {primitive wrapper} primitive? x
@syindex macro?
@deffnx {primitive wrapper} macro? x
@syindex interpreted-closure?
@deffnx {primitive wrapper} interpreted-closure? x
@syindex compiled-closure?
@deffnx {primitive wrapper} compiled-closure? x
@syindex ast?
@deffnx {primitive wrapper} ast? x
@end deffn

@syindex non-null?
@syindex non-cons?
@syindex non-symbol?
@deffn  {primitive wrapper} non-null? x
@deffnx {primitive wrapper} non-cons? x
@deffnx {primitive wrapper} non-symbol? x
@end deffn

@c @@@@@@@@@@@@
@node Pseudo-type checking
@subsubsection Pseudo-type checking

@syindex number?
@deffn {procedure} number? x
@end deffn

@syindex closure?
@deffn {procedure} closure? x
@end deffn

@syindex list?
@deffn {procedure} list? x
@end deffn

@syindex singleton?
@deffn {procedure} singleton? x
@end deffn

@syindex null-or-singleton?
@deffn {procedure} null-or-singleton? x
@end deffn

@syindex symbols?
@deffn {procedure} symbols? x
@end deffn

@syindex alist?
@deffn {procedure} alist? x
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Boolean operations
@subsection Boolean operations

@syindex not
@deffn {primitive wrapper} not x
@end deffn

@syindex or
@deffn  {macro} or . clauses
@syindex lispy-or
@deffnx {macro} lispy-or . clauses
@end deffn

@syindex and
@deffn  {macro} and . clauses
@syindex lispy-and
@syindex lispy-or  @c Not a mistake: there is a reference.
@deffnx {macro} lispy-and . clauses
@fixme{@code{lispy-and} is provided just for symmetry with @code{lispy-or},
and is in fact an alias for @code{and}.  The traditional Lisp
definition for @code{and} introduces no inefficiencies in this
case, differently from the traditional Lisp implementation of
@code{or}.}
@end deffn

@syindex boolean-canonicalize
@deffn {primitive wrapper} boolean-canonicalize x
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Arithmetic
@subsection Arithmetic

@fixme{fixnum only for the time being}

@syindex negate
@deffn  {primitive wrapper} negate x
@end deffn

@syindex 1+
@deffn  {primitive wrapper} 1+ x
@syindex 1-
@deffnx {primitive wrapper} 1- x
@end deffn

@syindex 2*
@deffn  {primitive wrapper} 2* x
@syindex 2/
@deffnx {primitive wrapper} 2/ x
@syindex 2quotient
@deffnx {primitive wrapper} 2quotient x
@syindex 2remainder
@deffnx {primitive wrapper} 2remainder x
@end deffn

@syindex primordial-+
@deffn  {primitive wrapper} primordial-+ x y
@syindex primordial--
@deffnx {primitive wrapper} primordial-- x y
@syindex primordial-*
@deffnx {primitive wrapper} primordial-* x y
@syindex primordial-/
@deffnx {primitive wrapper} primordial-/ x y
@syindex quotient
@deffnx {primitive wrapper} quotient x y
@syindex remainder
@deffnx {primitive wrapper} remainder x y
@end deffn

@syindex *-by-sums-procedure
@deffn {procedure} *-by-sums-procedure x y
@end deffn

@syindex **-procedure
@deffn {procedure} **-procedure b e
@end deffn

@syindex +
@deffn  {macro} + . args
@syindex *
@deffnx {macro} * . args
@syindex *-by-sums
@deffnx {macro} *-by-sums . args
@syindex **
@deffnx {macro} ** . args
@end deffn

@syindex -
@deffn {macro} - . args
@end deffn

@syindex /
@deffn {macro} / . args
@end deffn

@syindex square
@deffn {procedure} square x
@end deffn

@syindex even?
@deffn {procedure} even? x
@syindex odd?
@deffnx {procedure} odd? x
@end deffn



@syindex fixnum-bit-no
@deffn {fixnum} fixnum-bit-no
@end deffn

@syindex most-negative-fixnum
@deffn {fixnum} most-negative-fixnum
@syindex most-positive-fixnum
@deffnx {fixnum} most-positive-fixnum
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Number comparison
@subsection Number comparison

@fixme{fixnum only for the time being}

@syindex zero?
@deffn  {primitive wrapper} zero? x
@syindex non-zero?
@deffnx {primitive wrapper} non-zero? x
@syindex positive?
@deffnx {primitive wrapper} positive? x
@syindex non-positive?
@deffnx {primitive wrapper} non-positive? x
@syindex negative?
@deffnx {primitive wrapper} negative? x
@syindex non-negative?
@deffnx {primitive wrapper} non-negative? x
@end deffn

@syindex =
@deffn  {primitive wrapper} = x y
@syindex <
@deffnx {primitive wrapper} < x y
@syindex >
@deffnx {primitive wrapper} > x y
@syindex <=
@deffnx {primitive wrapper} <= x y
@syindex >=
@deffnx {primitive wrapper} >= x y
@syindex <>
@deffnx {primitive wrapper} <> x y
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Symbol handling
@subsection Symbol handling

@syindex gensym
@deffn {primitive wrapper} gensym
@end deffn

@syindex interned-symbols
@deffn {primitive wrapper} interned-symbols
@end deffn

@syindex symbol-global
@deffn {primitive wrapper} symbol-global s
@end deffn

@syindex make-constant!
@deffn {primitive wrapper} make-constant! s
@end deffn

@syindex constant?
@deffn {primitive wrapper} constant? s
@end deffn

@syindex defined?
@deffn {primitive wrapper} defined? s
@end deffn

@syindex undefine
@deffn {primitive wrapper} undefine s
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Box handling
@subsection Box handling

@syindex box
@deffn {primitive wrapper} box x
@end deffn

@syindex box-get
@deffn {primitive wrapper} box-get b
@end deffn

@syindex box-set!
@deffn {primitive wrapper} box-set! b x
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Cons handling
@subsection Cons handling

@syindex cons
@deffn {primitive wrapper} cons a b
@end deffn

@syindex car
@deffn  {primitive wrapper} car c
@syindex cdr
@deffnx {primitive wrapper} cdr c
@end deffn

@syindex caar
@deffn  {procedure} caar c
@syindex cdar
@deffnx {procedure} cdar c
@syindex cadr
@deffnx {procedure} cadr c
@syindex cddr
@deffnx {procedure} cddr c
@syindex caaar
@deffnx {procedure} caaar c
@syindex cadar
@deffnx {procedure} cadar c
@syindex caadr
@deffnx {procedure} caadr c
@syindex caddr
@deffnx {procedure} caddr c
@syindex cdaar
@deffnx {procedure} cdaar c
@syindex cddar
@deffnx {procedure} cddar c
@syindex cdadr
@deffnx {procedure} cdadr c
@syindex cdddr
@deffnx {procedure} cdddr c
@syindex caaaar
@deffnx {procedure} caaaar c
@syindex caadar
@deffnx {procedure} caadar c
@syindex caaadr
@deffnx {procedure} caaadr c
@syindex caaddr
@deffnx {procedure} caaddr c
@syindex cadaar
@deffnx {procedure} cadaar c
@syindex caddar
@deffnx {procedure} caddar c
@syindex cadadr
@deffnx {procedure} cadadr c
@syindex cadddr
@deffnx {procedure} cadddr c
@syindex cdaaar
@deffnx {procedure} cdaaar c
@syindex cdadar
@deffnx {procedure} cdadar c
@syindex cdaadr
@deffnx {procedure} cdaadr c
@syindex cdaddr
@deffnx {procedure} cdaddr c
@syindex cddaar
@deffnx {procedure} cddaar c
@syindex cdddar
@deffnx {procedure} cdddar c
@syindex cddadr
@deffnx {procedure} cddadr c
@syindex cddddr
@deffnx {procedure} cddddr c
@end deffn

@syindex set-car!
@deffn  {primitive wrapper} set-car! c x
@syindex set-cdr!
@deffnx {primitive wrapper} set-cdr! c x
@end deffn

@syindex set-caar!
@deffn  {procedure} set-caar! c x
@syindex set-cdar!
@deffnx {procedure} set-cdar! c x
@syindex set-cadr!
@deffnx {procedure} set-cadr! c x
@syindex set-cddr!
@deffnx {procedure} set-cddr! c x
@syindex set-caaar!
@deffnx {procedure} set-caaar! c x
@syindex set-cadar!
@deffnx {procedure} set-cadar! c x
@syindex set-caadr!
@deffnx {procedure} set-caadr! c x
@syindex set-caddr!
@deffnx {procedure} set-caddr! c x
@syindex set-cdaar!
@deffnx {procedure} set-cdaar! c x
@syindex set-cddar!
@deffnx {procedure} set-cddar! c x
@syindex set-cdadr!
@deffnx {procedure} set-cdadr! c x
@syindex set-cdddr!
@deffnx {procedure} set-cdddr! c x
@syindex set-caaaar!
@deffnx {procedure} set-caaaar! c x
@syindex set-caadar!
@deffnx {procedure} set-caadar! c x
@syindex set-caaadr!
@deffnx {procedure} set-caaadr! c x
@syindex set-caaddr!
@deffnx {procedure} set-caaddr! c x
@syindex set-cadaar!
@deffnx {procedure} set-cadaar! c x
@syindex set-caddar!
@deffnx {procedure} set-caddar! c x
@syindex set-cadadr!
@deffnx {procedure} set-cadadr! c x
@syindex set-cadddr!
@deffnx {procedure} set-cadddr! c x
@syindex set-cdaaar!
@deffnx {procedure} set-cdaaar! c x
@syindex set-cdadar!
@deffnx {procedure} set-cdadar! c x
@syindex set-cdaadr!
@deffnx {procedure} set-cdaadr! c x
@syindex set-cdaddr!
@deffnx {procedure} set-cdaddr! c x
@syindex set-cddaar!
@deffnx {procedure} set-cddaar! c x
@syindex set-cdddar!
@deffnx {procedure} set-cdddar! c x
@syindex set-cddadr!
@deffnx {procedure} set-cddadr! c x
@syindex set-cddddr!
@deffnx {procedure} set-cddddr! c x
@end deffn

@syindex car-or-nil
@deffn  {procedure} car-or-nil c
@syindex cdr-or-nil
@deffnx {procedure} cdr-or-nil c
@end deffn

@syindex improper-list
@deffn  {macro} improper-list first-element . more-elements
@syindex cons*
@deffnx {macro} cons* first-element . more-elements
@end deffn

@syindex circular-list
@deffn {macro} circular-list first-element . more-elements
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node List handling
@subsection List handling

@syindex singleton
@deffn {procedure} singleton
@end deffn

@syindex list
@deffn {macro} list . elements
@end deffn

@syindex replicate
@deffn  {procedure} replicate n x
@syindex make-list
@deffnx {procedure} make-list n x
@end deffn

@syindex last-cons
@deffn {procedure} last-cons xs
@end deffn

@syindex last
@deffn {procedure} last xs
@end deffn

@syindex all-but-last
@deffn  {procedure} all-but-last xs
@syindex all-but-last-reversed
@deffnx {procedure} all-but-last-reversed xs
@end deffn

@syindex length
@deffn {procedure} length xs
@end deffn

@syindex reverse
@deffn  {procedure} reverse xs
@syindex reverse!
@deffnx {procedure} reverse! xs
@end deffn

@syindex append-procedure
@deffn  {procedure} append-procedure xs ys
@syindex append-reversed
@deffnx {procedure} append-reversed xs ys
@syindex append!-procedure
@deffnx {procedure} append!-procedure xs ys
@end deffn

@syindex append
@deffn  {macro} append . xss
@syindex append!
@deffnx  {macro} append! . xss @c Yes, this works even with zero arguments.
@end deffn

@syindex flatten
@deffn  {procedure} flatten xss
@syindex flatten!
@deffnx {procedure} flatten! xss
@syindex flatten-reversed
@deffnx {procedure} flatten-reversed xss
@syindex flatten-reversed!
@deffnx {procedure} flatten-reversed! xss
@end deffn

@syindex list-copy
@deffn {procedure} list-copy xs
@end deffn

@syindex nth-cons
@deffn  {procedure} nth-cons xs n
@syindex nth-cons-or-nil
@deffnx {procedure} nth-cons-or-nil xs n
@end deffn

@syindex nth
@deffn {procedure} nth xs n
@end deffn

@syindex take
@deffn  {procedure} take xs n
@syindex take-reversed
@deffnx {procedure} take-reversed xs n
@syindex take!
@deffnx {procedure} take! xs n
@end deffn

@syindex drop
@deffn  {procedure} drop xs n
@syindex drop!
@deffnx {procedure} drop! xs n
@end deffn

@syindex zip
@deffn  {procedure} zip xs n
@syindex zip-reversed
@deffnx {procedure} zip-reversed xs n
@end deffn

@syindex unzip
@deffn  {procedure} unzip xs n
@syindex unzip-reversed
@deffnx {procedure} unzip-reversed xs n
@end deffn

@syindex map
@deffn  {procedure} map f xs
@syindex map-reversed
@deffnx {procedure} map-reversed f xs
@syindex map!
@deffnx {procedure} map! f xs
@end deffn

@syindex fold-left
@deffn {procedure} fold-left f x xs
@end deffn

@syindex fold-right
@deffn  {procedure} fold-right f xs y
@syindex fold-right!
@deffnx {procedure} fold-right! f xs y
@end deffn

@syindex exists?
@deffn  {procedure} exists? p xs
@syindex for-all?
@deffnx {procedure} for-all? p xs
@end deffn

@syindex filter
@deffn  {procedure} filter p xs
@syindex filter-reversed
@deffnx {procedure} filter-reversed p xs
@end deffn

@syindex range
@deffn  {procedure} range a b
@syindex range-reversed
@deffnx {procedure} range-reversed a b
@end deffn

@syindex iota
@deffn {procedure} iota n
@end deffn

@syindex sort
@deffn {procedure} sort xs
@end deffn

@syindex list-has?
@deffn {procedure} list-has? xs x
@end deffn

@syindex list-without
@deffn  {procedure} list-without xs x
@syindex list-without!
@deffnx {procedure} list-without! xs x
@end deffn

@syindex all-different?
@deffn {procedure} all-different?
@fixme{quadratic}
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Alist handling
@subsection Alist handling

@syindex assq
@deffn {procedure} assq key alist
@end deffn

@syindex rassq
@deffn {procedure} rassq value alist
@end deffn

@syindex del-assq-1
@deffn {procedure} del-assq-1 key alist
@end deffn

@syindex del-assq
@deffn  {procedure} del-assq key alist
@syindex del-assq-noncopying
@deffnx {procedure} del-assq-noncopying key alist
@end deffn

@syindex del-assq-list
@deffn  {procedure} del-assq-list keys alist
@syindex del-assq-list-noncopying
@deffnx {procedure} del-assq-list-noncopying keys alist
@end deffn

@syindex alist-copy
@deffn {procedure} alist-copy alist
@end deffn

@syindex alist-get
@deffn {procedure} alist-get key alist
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Higher order
@subsection Higher order

@syindex compose-procedure
@deffn  {procedure} compose-procedure f g
@syindex compose-eta
@deffnx {procedure} compose-eta f g
@end deffn

@syindex compose
@deffn  {macro} compose . fs
@syindex compose-pipeline
@deffnx {macro} compose-pipeline . fs
@end deffn

@syindex square-function
@deffn  {procedure} square-function f
@syindex square-function-eta
@deffnx {procedure} square-function-eta f
@end deffn

@syindex iterate
@deffn  {procedure} iterate f n
@syindex iterate-eta
@deffnx {procedure} iterate-eta f n
@syindex iterate-pre
@deffnx {procedure} iterate-pre f n
@syindex iterate-post
@deffnx {procedure} iterate-post f n
@end deffn

@anchor{lambda-wrapper}
@syindex lambda-wrapper
@deffn {macro} lambda-wrapper rator arity
@end deffn

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Variadic utility
@subsection Variadic utility

@syindex define-left-nested-variadic-extension
@deffn  {macro} define-left-nested-variadic-extension name original-name neutral
@syindex define-right-nested-variadic-extension
@deffnx {macro} define-right-nested-variadic-extension name original-name neutral
@syindex define-associative-variadic-extension
@deffnx {macro} define-associative-variadic-extension name original-name neutral
@end deffn

@fixme{yes, the things that follow are really procedures}

@syindex variadic-left-deep
@deffn  {procedure} variadic-left-deep rator neutral rands
@syindex variadic-right-deep
@deffnx {procedure} variadic-right-deep rator neutral rands
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Sets as lists
@subsection Sets as lists

@fixme{Performance caveat}

@fixme{order caveat}

@fixme{The word ``set'' as used here refers to a collection of objects in the
mathematical sense, and has nothing to do with the action of ``setting'' as
performed by @code{set-@var{thing}!} procedures.}

@syindex set-empty
@deffn {unique} set-empty
@end deffn

@syindex set-empty?
@deffn {procedure} set-empty? s
@end deffn

@syindex set-singleton
@deffn {procedure} set-singleton x
@end deffn

@syindex set
@deffn  {macro} set . elements
@end deffn

@syindex set-has?
@deffn {procedure} set-has? s x
@end deffn

@syindex set-with
@deffn {procedure} set-with s x
@end deffn

@syindex set-without
@deffn {procedure} set-without s x
@end deffn

@syindex set-unite-procedure
@deffn  {procedure} set-unite-procedure s1 s2
@syindex set-intersect-procedure
@deffnx {procedure} set-intersect-procedure s1 s2
@syindex set-subtract-procedure
@deffnx {procedure} set-subtract-procedure s1 s2
@end deffn

@syindex set-unite
@deffn  {macro} set-unite . sets
@syindex set-intersect
@deffnx {macro} set-intersect . sets
@syindex set-subtract
@deffnx {macro} set-subtract first-set . other-sets
@end deffn

@syindex list->set
@deffn  {procedure} list->set xs
@end deffn

@syindex set->list@r{ (@emph{non-existing} procedure)}
@fixme{No @code{set->list} is needed}.


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node AST operations
@subsection AST operations

@fixme{if the argument is not an AST these all fail.}

@syindex ast-literal?
@deffn  {primitive wrapper} ast-literal?
@syindex ast-variable?
@deffnx {primitive wrapper} ast-variable?
@syindex ast-define?
@deffnx {primitive wrapper} ast-define?
@syindex ast-if?
@deffnx {primitive wrapper} ast-if?
@syindex ast-set!?
@deffnx {primitive wrapper} ast-set!?
@syindex ast-while?
@deffnx {primitive wrapper} ast-while?
@syindex ast-primitive?
@deffnx {primitive wrapper} ast-primitive?
@syindex ast-call?
@deffnx {primitive wrapper} ast-call?
@syindex ast-lambda?
@deffnx {primitive wrapper} ast-lambda?
@syindex ast-let?
@deffnx {primitive wrapper} ast-let?
@syindex ast-sequence?
@deffnx {primitive wrapper} ast-sequence?
@end deffn

@fixme{types: when we fail}

@syindex ast-literal
@deffn  {primitive wrapper} ast-literal value
@syindex ast-variable
@deffnx {primitive wrapper} ast-variable name
@syindex ast-define
@deffnx {primitive wrapper} ast-define name body
@syindex ast-if
@deffnx {primitive wrapper} ast-if condition then else
@syindex ast-set!
@deffnx {primitive wrapper} ast-set! name body
@syindex ast-while
@deffnx {primitive wrapper} ast-while guard body
@syindex ast-primitive
@deffnx {primitive wrapper} ast-primitive operator operands
@syindex ast-call
@deffnx {primitive wrapper} ast-call operator operands
@syindex ast-lambda
@deffnx {primitive wrapper} ast-lambda formals body
@syindex ast-let
@deffnx {primitive wrapper} ast-let bound-name bound-form body
@syindex ast-sequence
@deffnx {primitive wrapper} ast-sequence first second
@end deffn

@fixme{these fail if the argument is not an AST or if it's an AST of the
wrong case}
@fixme{no destructive operations right now.  They would be easy to
add, even if using them in an unrestricted way might destroy compiler
properties; anyway, it is already possible to destroy the same
compiler implied properties, by violating other unenforced invariants}

@syindex ast-literal-value
@deffn  {primitive wrapper} ast-literal-value ast
@syindex ast-variable-name
@deffnx {primitive wrapper} ast-variable-name ast
@syindex ast-define-name
@deffnx {primitive wrapper} ast-define-name ast
@syindex ast-define-body
@deffnx {primitive wrapper} ast-define-body ast
@syindex ast-if-condition
@deffnx {primitive wrapper} ast-if-condition ast
@syindex ast-if-then
@deffnx {primitive wrapper} ast-if-then ast
@syindex ast-if-else
@deffnx {primitive wrapper} ast-if-else ast
@syindex ast-set!-name
@deffnx {primitive wrapper} ast-set!-name ast
@syindex ast-set!-body
@deffnx {primitive wrapper} ast-set!-body ast
@syindex ast-while-guard
@deffnx {primitive wrapper} ast-while-guard ast
@syindex ast-while-body
@deffnx {primitive wrapper} ast-while-body ast
@syindex ast-primitive-operator
@deffnx {primitive wrapper} ast-primitive-operator ast
@syindex ast-primitive-operands
@deffnx {primitive wrapper} ast-primitive-operands ast
@syindex ast-call-operator
@deffnx {primitive wrapper} ast-call-operator ast
@syindex ast-call-operands
@deffnx {primitive wrapper} ast-call-operands ast
@syindex ast-lambda-formals
@deffnx {primitive wrapper} ast-lambda-formals ast
@syindex ast-lambda-body
@deffnx {primitive wrapper} ast-lambda-body ast
@syindex ast-let-bound-name
@deffnx {primitive wrapper} ast-let-bound-name ast
@syindex ast-let-bound-form
@deffnx {primitive wrapper} ast-let-bound-form ast
@syindex ast-let-body
@deffnx {primitive wrapper} ast-let-body ast
@syindex ast-sequence-first
@deffnx {primitive wrapper} ast-sequence-first ast
@syindex ast-sequence-second
@deffnx {primitive wrapper} ast-sequence-second ast
@end deffn

@fixme{An example showing a constuction, check and field access for the same case,
to highlight the lexical conventions.}


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node AST optimization
@subsection AST optimization

@fill


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Macroexpanding
@subsection Macroexpanding

@syindex macrolet@r{ (@emph{non-existing} form)}
@fixme{There is currently no syntactic support for local macros, such as
Common Lisp's @code{macrolet}.}

@syindex primordial-macroexpand
@deffn {primitive wrapper} primordial-macroexpand form env
@end deffn

@cindex macroexpansion
@syindex macroexpand
@deffn {macro} macroexpand form . optional-env
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Code execution
@subsection Code execution

@syindex apply
@deffn  {primitive wrapper} apply operator operands
@syindex apply-primitive
@deffnx {primitive wrapper} apply-primitive operator operands
@end deffn

@syindex primordial-eval
@deffn {primitive wrapper} primordial-eval form env
@end deffn

@syindex eval
@deffn {macro} eval form . optional-env
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Compilation
@subsection Compilation

@anchor{disassembly}

@fill


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Input and output
@subsection Input and output

@cindex GNU Readline
@cindex Readline
@cindex I/O
@cindex input
JitterLisp provides very crude I/O functionalities.  Files are not
implemented, so input and output only use the standard input and
standard output, respectively, or the terminal via ReadLine.

@menu
* Character I/O::                     Reading and writing one character at a time.
* Lisp object I/O::                   Reading and writing entire Lisp objects.
@end menu

@c @@@@@@@@@
@node Character I/O
@subsubsection Character I/O

@cindex character-based input/output
@cindex input/output, character-based

The following functionality provides a thin wrapper over C for reading
or writing one character at a time.

@syindex character-read
@deffn {primitive wrapper} character-read
Read a single character from the terminal and return it, or return @code{#<eof>}
if the input ends.

The implementation is a thin wrapper over the @code{getchar} function from the C library.
@end deffn

@syindex character-display
@deffn {primitive wrapper} character-display c
Print the single character @var{c} to the standard output.  Error out if
@var{c} is not a character object.
@end deffn

@syindex newline
@deffn {primitive wrapper} newline
Print a newline character to the standard output.

If @code{newline} were not already provided in the library it could be defined as:
@example
(define-constant (newline)
  (character-display #\newline))
@end example
@end deffn


@c @@@@@@@@@
@node Lisp object I/O
@subsubsection Lisp object I/O

@cindex object, Lisp, input/output
@cindex Lisp object, input/output
@cindex input/output, for Lisp objects

@syindex read
@deffn {primitive wrapper} read
@cindex Readline
Read one Lisp object in its input representation from the terminal, using the
Readline functionality if enabled, and return it.
Return @code{#<eof>} if the input ends @emph{before} an object is entered.

The input may span several lines and include whitespace or even Lisp comments, but
the read object must be exactly one.

Error out on syntax error, or if a second object starts after the first.
@end deffn

@syindex display
@deffn {primitive wrapper} display thing
Emit the printed representation of @var{thing} to the standard output.
No newline character or other terminator is added.
@end deffn

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Debugging and profiling
@subsection Debugging and profiling

@cindex location, print
@cindex data location, print
@cindex print, location
@syindex print-locations
@deffn {primitive wrapper} print-locations
Print data location information, mapping runtime VM data structures
into hardware machine resources.  This is convenient for reading
disassemblies.
@end deffn

@cindex defective specialised instruction, print
@cindex print, defective specialised instructions
@cindex VM instruction, specialised
@cindex instruction, VM, specialised
@cindex call-related VM instruction
@syindex print-defects
@anchor{@samp{print-defects}}
@deffn {primitive wrapper} print-defects
Print the names of all defective specialised instructions.  Notice
that the set of defective specialised instructions may be different
from the set of replaced specialised instructions: when
@emph{any} call-related specialised instruction is defective then
@emph{every} call-related specialised instruction will be replaced.
@*
The output is meant for the user.
@end deffn

@cindex defective specialised instruction, print replacements
@cindex print replacements, defective specialised instructions
@cindex replacement, defective specialised instructions, printing
@cindex VM instruction, specialised
@cindex instruction, VM, specialised
@cindex call-related VM instruction
@syindex print-defect-replacements
@deffn {primitive wrapper} print-defect-replacements
Print information about defective specialised instruction, listing
the name of each replaced specialised instruction along with the
specialised instruction replacing it.  About the difference between
defective specialised instruction and replaced specialised instruction
@pxref{@samp{print-defects}}.
@*
The output is meant for the user.
@end deffn


@cindex profile, specialised, print
@cindex print, profile, specialised
@cindex specialised, profile, print
@syindex print-profile-specialized
@deffn {primitive wrapper} print-profile-specialized
Print cumulative profile information about the specialised
VM instructions run up to this point.  This just prints a warning if
JitterLisp was not compiled with profiling instrumentation enabled,
defining at least one of the CPP macros @code{JITTERLISPVM_PROFILE_COUNT}
and @code{JITTERLISPVM_PROFILE_SAMPLE}; since profiling instrumentation
incurs a performance penalty it is disabled by default.
@end deffn

@cindex profile, unspecialised, print
@cindex print, profile, unspecialised
@cindex unspecialised, profile, print
@syindex print-profile-unspecialized
@deffn {primitive wrapper} print-profile-unspecialized
This primitive wrapper behaves exactly like
@code{print-profile-specialized}, except that it prints information
about @emph{unspecialised} VM instructions.
@end deffn

@cindex profile, reset
@cindex reset, profile
@syindex reset-profile!
@deffn {primitive wrapper} reset-profile!
Reset profile information, changing the execution count for every
instruction back to zero.
@end deffn

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Legal notices
@subsection Legal notices

@cindex copying (software)
@syindex copying
@deffn  {primitive wrapper} copying
@syindex no-warranty
@cindex no warranty
@cindex warranty, lack thereof
@deffnx {primitive wrapper} no-warranty
Display legal notices by printing, respectively, the full text of the GNU GPL
or an excerpt explaining how there is no warranty of any kind.
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@
@node Unclassified
@subsection Unclassified (move)

@syindex identity
@deffn {procedure} identity x
@end deffn

@syindex eq?
@deffn  {primitive wrapper} eq? x y
@syindex not-eq?
@deffnx {primitive wrapper} not-eq? x y
@end deffn

@anchor{Erroring out}
@syindex error
@deffn {primitive wrapper} error thing
@end deffn

@syindex gc
@deffn {primitive wrapper} gc
@end deffn


@c C API
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node C API
@chapter C API

@fill


@c Internals
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Internals
@chapter Internals

@anchor{constant-strings}
@cindex library file, JitterLisp
@cindex initialization file, JitterLisp
@fill

@fixme{it's a stack machine: two stacks plus registers.  Explain calling
conventions.  Explain closure representations.  Explain tagging, possibly
at the beginning}


@ifset includelicenses
@node GNU General Public License
@appendix GNU General Public License
@cindex GPL
@cindex GNU General Public License
@cindex software, license
@cindex license, for JitterLisp
@include gpl.texi

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@cindex FDL
@cindex GNU Free Documentation License
@cindex documentation, license
@cindex manual, license
@cindex license, for this manual
@include fdl.texi
@end ifset @c includelicenses


@c Indices
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Symbol and reserved syntax index
@unnumbered Symbol and reserved syntax index

What follows is an alphabetical list of read syntax (@pxref{Lisp
data}) and predefined JitterLisp globals, without distinction between
core definitions coming from the C code and library definitions from
the library written in Lisp and executed at startup.

In the same sense the index glosses over the difference in type among
globally defined variables: some may be procedures or primitive wrappers
and other macros, from either the core or the library.

Most of the symbols named here are constant.  Some, particularly
macros, may not be.

@cindex symbol index
@cindex index, for symbols
@printindex sy


@node Concept index
@unnumbered Concept index

@cindex concept index
@cindex index, for concepts
@printindex cp


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@c The actual documentation for the user ends here.
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@


@ifset preview
@c Stuff still to be written
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Stuff still to be written
@appendix Stuff still to be written

@fixme{Write this}


@c Stuff still to be implemented.
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Stuff still to be implemented
@appendix Stuff still to be implemented

@fixme{Write this}
@end ifset


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@c Footer.
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@bye
Local Variables:
  eval: (flyspell-mode t)
  eval: (ispell-change-dictionary "british")
  compile-command: "bash -ci 'make -C ~/repos/jitter/_build/native-gcc-11 info pdf'"
End:
