Copyright (C) 2022-2024 Andrea G. Monaco

Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and this
notice are preserved.  This file is offered as-is, without any warranty.




al is a lisp implementation.  Right now it is just an interpreter, but I will
add some compilation later.  I aim for Common Lisp conformance, but I'm not
religious about it.

It's written in C89 and it also compiles with the -ansi option of gcc.

Currently it depends on GNU Readline (optionally) and on GNU Multiple Precision
Arithmetic Library.  It uses autotools for building.


If you have a cloned git repository and the last commit is not a versioned
release, you can execute set-version-from-git.sh to set a meaningful alisp
version in the relevant line of configure.ac.

To build from a git snapshot, start with

  $ autoreconf -i

(which is not needed in released tarballs) and then run the usual

  $ ./configure

configure only admits --with[out]-readline as options, to build with line
editing or not; also note that the test suite will not work without readline,
because the script is written around readline's unusual echo behavior.  Then

  $ make

plus optionally

  # make install

will build and optionally install the program.

A lisp file named cl.lisp contains many standard definitions.  By default, this
file gets loaded at startup from the current directory, unless you pass -q or
--dont-load-cl.  To load the file manually, run

  [CL-USER]> (load "cl.lisp")

at the al prompt.


There's a test script too.  Run it with

  $ ./test.pl

if you have perl on your machine.  You should expect a 100% success rate, or
maybe some failures at floating-point operations if they yield slightly
different results on your system.

There's another test script called meta_test.pl that runs test.pl many times.  I
wrote that script because I found that some memory bugs manifest only a fraction
of the times.



__Debugging__

The file al_gdb_debug.py defines a gdb command called al_print_object.  You may
load it with "source al_gdb_debug.py" in your gdb session.

Then the gdb command al_print_object takes a C pointer as argument and displays
the attached lisp object.  A string may be displayed like this

  (gdb) al_print_object obj
  "abc"
   1(0)

below the string you see the strong refcount and (in parenthesis) the weak
refcount of the object.

A list will be printed like this

  (        A         B         C)
   1(0) 1(0) 1(0) 1(0) 1(0) 1(0)

For each cons cell, the command displays the refcounts of the cell and then
those of the car.

Currently the command doesn't descend into arrays nor hash tables.



__Readline history__

al saves immediately each line to the history file, instead of saving the whole
history at program termination.  That's a design choice, so that I have the last
lines available after crashes.

The history file al_history can get quite big; if you delete it, test.pl and
meta_test.pl will get much faster.




See the NOTES file for some notes on design choices, portability and ANSI
conformance.




You can reach me at andrea.monaco@autistici.org.  Send any suggestion and bug
report that you wish, but please note that I don't take patches.



If you like this project, you can make a donation at
https://liberapay.com/andreamonaco or at https://www.patreon.com/andreamonaco.
Thank you very much!
