Readable Lisp S-expressions ("readable")
========================================

This "readable" software improves the readability of Lisp S-expressions
by adding up to three tiers of new s-expression abbreviations.
These tiers are (oversimplified):

1. Curly-infix-expressions (c-expressions): Lists with {...} are infix, in a
   Lispy way: {a op b ...} maps to (op a b ...). No precedence, by intent.
2. Neoteric-expressions (n-expressions): An e(...) maps to
   (e ...), and e{...} with content maps to 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.

Unlike nearly all past efforts to improve s-expression readability, these
are general (the notation is independent from any underlying semantic)
and homoiconic (the underlying data structure is clear from the syntax).
They are also backwards-compatible; nicely-formatted traditional
s-expressions continue work normally.  Thus, it's easy to transition to
these, and you can use traditional forms whenever it's convenient.

Lisp-based languages where this approach or software can be helpful
include Scheme (including guile), Common Lisp, Emacs Lisp, Clojure, Arc,
BitC, ACL2, SUO-KIF, the GCC MiddleEndLispTranslator (MELT),
Satisfiability Modulo Theories Library (SMT-LIB), NewLisp, and ISLisp.
For Scheme these notations are defined in SRFI-105 and SRFI-110.
At this time, the tools focus on Scheme and Common Lisp, but
some of the tools can be easily used with many other Lisps.

The file "Problem.html" describes the problem this is intended to solve, and
"Solution.html" describes these notations. Hands-on tutorials are in
"Scheme-tutorial.html" and "Common-lisp-tutorial.html".

For more information, see:
  http://readable.sourceforge.net


Example
=======

Here is an example of a sweet-expression:

define fibfast(n)   ; Typical function notation
  if {n < 2}        ; Indentation, infix {...}
     n              ; Single expr = no new list
     fibup n 2 1 0  ; Simple function calls

That sweet-expression would be interpreted as:

(define (fibfast n)
  (if (< n 2)
      n
      (fibup n 2 1 0)))

A sweet-expression reader would accept *either* one.


Maturity
========

This code is *mature* and *production-ready*, and comes with an
extensive test suite.


License
=======

With one exception, 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.

The one exception is the file "sweet-clisp", which interfaces to clisp.
Most of this file is also licensed under the MIT license.
However, that file contains code derived from the "clisp" program.
Clisp is licensed under the "GNU General Public License version 2 (GPLv2)",
so those parts are also under the GPLv2 (see the file for details).
The GPLv2 is also 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.GPL file for those conditions.


Getting, building, and installing
=================================

Most people should get the current stable version.  To get it:

* Use your web browser to view http://readable.sourceforge.net
* Click on "Download files"
* Download the current version.

You'll then need to uncompress it.  One way is via the command line:

    tar xvzf readable-*.tar.gz
    cd readable-*

Then follow the installation instructions in the file
"Install-howto.md".  Stable versions also have a file named
"Install-howto.html", which is exactly the same thing but in HTML format
(use your web browser!).  The installation instructions are also at:
https://sourceforge.net/p/readable/wiki/Install-howto/

This software supports the usual GNU Build System conventions, and
it should be easy to install on most systems.  If you have very
exotic needs, the file INSTALL gives details on how to precisely control
installation.



Scheme Tutorial
==============

File "Scheme-tutorial.html" is the Scheme tutorial on how to use it.
You need guile to follow it.


Common Lisp Tutorial
====================

File "Common-lisp-tutorial.html" is the Common Lisp tutorial for how to use it.
Any Common Lisp implementation should do, but you need the widely-used system
definition facility asdf.  A "make install" puts files in the usual place,
$PREFIX/share/common-lisp/source (where $PREFIX is /usr/local by default).


Specification
====================

For Scheme, SRFI-105 (in file "SRFI-105.html") is the official definition of
full curly-infix notation, and it also defines neoteric-expressions.
SRFI-110 (in file "SRFI-110.html" defines sweet-expressions.
SRFI-110 has an especially rigorous BNF.

The file "Solution.html" is the official definition for all other Lisps.
If it's unclear what something means, look at SRFI-105 and SRFI-110
for clarification, but note that the SRFIs include various
Scheme-specific material (e.g., #!sweet is a Scheme-specific mechanism
for enabling sweet-expressions).


Transitioning
=============

The "sweeten" tool is a pretty-printer that translates
s-expressions to sweet-expressions.  You can use "sweeten" to create a file,
hand-tweak the result to make it "prettier", and then use "diff-s-sweet"
to verify that your newly-formatted file has exactly the same meaning.

The "unsweeten" tool can be used as a sweet-expression pre-processor,
so you can use these notations even if your Lisp implementation does not
yet support them.

By default the "sweeten" and "unsweeten" tools process Scheme; if you
have Common Lisp (or something like it), provide the "-C" (Common Lisp)
option as documented.  They can be used as front-ends for other tools.


For more information
===================

For more information, see:
  http://readable.sourceforge.net

Discussions are held on its "readable-discuss" mailing list.