Readable Lisp S-expressions Git Repository
Readable Lisp/S-expressions with infix, functions, and indentation
Brought to you by:
dwheeler
Menu
▾
▴
Tree [323a7c] 0.7.1 / History
Read Me
Readable Lisp S-expressions Project
===================================
This software improves the readability of Lisp S-expressions, by
implementing three tiers of additional abbreviations in S-expressions.
These tiers are (oversimplified):
1. Curly-infix-expressions (c-expressions): Lists surrounded by {...} are
interpreted as infix notation, in a Lispy way.
2. Neoteric-expressions (n-expressions): An e(...) is interpreted as
(e ...), an e{...} is interpreted as e({...}).
3. Sweet-expressions (t-expressions): Parentheses are deduced from indentation:
- An indented line is a parameter of its parent.
- Later terms on a line are parameters of the first term.
- A line with exactly one term and no child lines is simply that term.
- Empty lines end the previous expression. Just type ENTER ENTER
to execute what you've typed.
Well-formatted traditional s-expressions continue to be read in normally,
so you only need to use the abbreviations when you find them useful.
For more information, see: http://readable.sourceforge.net.
In particular, see the [Tutorial], [Solution], and other pages on the wiki.
Lisp-based languages where this software can be helpful include Common Lisp,
Scheme (including guile), Emacs Lisp, Clojure, Arc, BitC, ACL2,
SUO-KIF, the GCC MiddleEndLispTranslator (MELT),
Satisfiability Modulo Theories Library (SMT-LIB), NewLisp, and ISLisp.
License
=======
The software is released under the MIT license, which permits practically
any use. The MIT license is an open source software / Free Software
license approved by both the OSI (opensource.org) as an open source software
license, and by the FSF (fsf.org) as a Free software license.
See the COPYING file for the license text.
Building and Installing
=======================
This software supports the usual GNU Build System conventions.
Here are the steps, spelled out.
1. Download/Prepare to configure
You need to get the files. You've probably done that, since you're
reading this, but here are the basics.
If you want to get the current stable version, go to:
http://readable.sourceforge.net
Click on "Download files", and download the current version.
Then uncompress them; one way is via the command line:
tar xvzf readable-*.tar.gz
cd readable-*
If you want to get the latest developmental version, download the
files from our git code repository & prepare it to be configured:
git clone git://git.code.sf.net/p/readable/code readable-code
cd readable-code
git checkout develop # The "master" branch is for final releases
autoreconf -i
2. Configure
As usual, configure. To accept all the defaults, installing to /usr/local:
./configure
If you want it to install to /usr (e.g., programs go in /usr/bin):
./configure --prefix=/usr
3. Build ("make") / test
Now build the code.
make
You can optionally run the testsuite; it's a very good idea:
make check
4. Install ("make install")
You actually don't *have* to install the software. Just run
"./unsweeten", "./sweeten", "./sweet-guile", and it'll work.
But it's often more convenient to install. Do this with:
make install
The usual conventions all work (DESTDIR, VPATH builds, etc.).
ANTLR-based grammar
===================
The "sweet.g" file contains a BNF for sweet-expressions in ANTLR v3 format.
You can use the ANTLRWorks IDE to manipulate it.
It is designed to generate Java, so you need a Java compiler and a
proper CLASSPATH setting to use it.
The "easy" way to use it is to download ANTLRWorks as a ".jar" file, and
store it in this directory.
Make sure the CLASSPATH includes (1) the jar file ANTLR or ANTLRWorks and
(2) the "output" subdirectory.
In ANTLRWorks, you may want to select File/Preferences, "Compiler" tab,
and create a custom Classpath that includes these absolute directory names
(separated by ";" in Windows or ":" everywhere else).
You can generate Java class files from ANTLRWorks using
"Generate/Generate files". Then go to the "output" subdirectory.
You need to compile and then run ("go.bat" does this for Windows;
"go" runs on Linux/Unix/Cygwin, and also does a test run).
A typical use process is:
1. Run "ANTLRWorks", e.g., "java antlrworks-*.jar"
2. Edit (and save) as you wish.
- Run Grammar/Check Grammar to do quick checks.
- You can use Run/Debug to debug; this can generate helpful parse trees.
3. To create an executable, select "Generate/Generate code".
Then on command line, "cd output" and "./go"
which will also run some tests.
Key files
=========
Some of the key files are:
## Installed:
Executables:
* unsweeten: A filter that reads in (from stdin) a file of
sweet-expressions, and outputs sweet-expressions. You can use this
in "makefiles" so that you can write files using sweet-expressions.
MIT license.
* sweeten: A filter that reads in s-expressions (Scheme format) from
standard in, and generates sweet-expressions on standard out. MIT license.
* neoteric-guile: Start up guile, but use neoteric-expressions to
interact with it. MIT license.
* sweet-guile: Start up guile, but use sweet-expressions to interact
with it. MIT license.
Documentation:
* README: This file.
* solution.md: A description of the notations this project implements.
See the project website for the current version of this.
* tutorial.md: A tutorial. See the project website for a
current version of this.
* spec-indent.txt: Detailed specification information on I-expressions,
the basis of sweet-expressions.
* spec-almkglor.txt: A not-so-updated specification for the
entire sweet-expression spec, created by Alan Manuel K. Gloria.
* sweeten.sscm: An example of code written using sweet-expressions.
This is the original source code for "sweeten", which reads
traditional s-expressions and writes sweet-expression versions of them.
The spec-* files need to be updated (volunteers welcome). For now, see
"solution.md" for the real specification.
## Not Installed:
* src/kernel.scm: An implementation of the three notation tiers
curly-infix-read, neoteric-read, and sweet-read. Implemented in the
Guile dialect of Scheme; it includes hooks for other dialects. This is
installed into the "readable" site directory of guile. MIT license.
* src/sweeten.sscm: The source of the "sweeten" program. It's written
in Scheme using sweet-expressions, so if you want to see what
sweet-expressions look like, well, here's an example.
* readable.cl: Formerly named "curly-infix.cl". This is Common Lisp
code to implement this. On load, the reader readtable is modified
to implement curly-infix in lists surrounded by {...}.
The curly-infix implementation is fine and ready to go.
There is an initial neoteric-read implementation, but it's not
ready for full use yet (help wanted!).
To try it out, run your implentation (e.g., clisp), then:
(load "readable.cl")
* SRFI-105.html - The SRFI defining curly-infix-expressions for Scheme
* SRFI-110.html - The draft SRFI defining sweet-expressions for Scheme
Key directories
===============
src/ - Most source files
bin/ - Generated command (script) files for installation
readable/ - Guile library (generated, don't edit these)
tests/ - Test scripts and test cases
The "src/" directory holds most of the source code.
A "make" will generate files in the top dir, bin/ directory, and the
readable/ directory. The generated files in the top directory are
scripts designed to invoke the locally-built readable library, even if
there's another one installed.
File suffixes are:
.cl - Common Lisp
.lisp - Common Lisp
.scm - Scheme
.sscm - Sweet-Scheme; Scheme written with sweet-expressions.
You can invoke the readers from your own Guile programs by doing:
(use-modules (readable kernel))
and you can even:
(replace-read sweet-read)
On Guile 2.0 there are occassional strangenesses in the interaction
between the module system and autocompilation - the particular
strangeness is when autocompilation is turned OFF. If you want to
use sweet-guile or neoteric-guile, turn ON autocompilation, as
otherwise use-modules will use the default reader rather than
what you replace.
External tool: ANTLRWorks
===================
The ANTLR BNF was developed using ANTLRworks version 1.4.3.
If you wish to edit or generate files from it, it is known
to work with file "antlrworks-1.4.3.jar" with the following attributes:
Bytes 3588307
MD5 9638f9b7b1b823fcaba977f06f0dd761
SHA-1 f7974cf14ac19c3aa1841ee88c6d2dcbad89af01
SHA-512 99374a96b541f09367af56bf704601204a6abb658ae9400776da15b4cae0e98674ee2a812d34ebad8a3fcfcde90087d031379ff88a3bd5acf02ddeaea924197b
ANTLRWorks 1.4.3 is available from:
http://www.antlr3.org/works/
in particular from:
http://www.antlr3.org/download/
The ANTLRWorks GUI is released under the BSD 3-clause license,
and it includes the ANTLR tool version 3.4, which is also
released under the BSD 3-clause license:
http://www.antlr3.org/license.html
IF you cannot find a copy, check:
http://sourceforge.net/projects/readable/files/
For more information
===================
For more information, see:
http://readable.sourceforge.net
Discussions are held on the mailing list.