README

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 implementation and 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.  Installation instructions
are in "Install-howto.html".  Hands-on tutorials are in
"Scheme-tutorial.html" and "Common-lisp-tutorial.html".  These .html
files are generated from the equivalent .md (markdown) files.

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


Curly-infix-expression examples
===============================

Here are some examples of basic curly-infix-expressions:

    {3 + 4}             ; (+ 3 4)
    {a * {b + c}}       ; (* a (+ b c))

Neoteric-expression examples
============================

Here are some examples of neoteric expressions
(note that this notation is optional):

    cos(0)              ; (cos 0)
    if({n > max} max n) ; (if (> n max) max n)

Sweet-expression examples
=========================

You can optionally enable sweet-expressions. Remember:
   - 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.

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.

Here's another example of a sweet-expression and its meaning:

a b c d      ; (a b c d
  e f g      ;    (e f g)
  h i        ;    (h i
    j k l    ;       (j k l)
    m n o    ;       (m n o))
  p          ;    p
  q r s      ;    (q r s))



Maturity
========

This code is *mature* and *production-ready* for Scheme and Common Lisp.
It comes with an extensive test suite, which it passes.


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 itself.
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 the conditions for the "sweet-clisp" program.


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

Most people should get the current stable version.  To get the whole package:

* 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 are exactly the same instructions in HTML format
(you can use your web browser!).  The installation instructions are also at:
https://sourceforge.net/p/readable/wiki/Install-howto/

You can also get the development version using "git".
In git the "master" branch contains final released versions, while
the "develop" branch contains the version in development.

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 the installation.  For most people the automatic
install will "do the right thing".

Users who only want to use the Common Lisp library can use QuickLisp instead.


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, or use QuickLisp, as described in "Install-howto".
Once installed, you can directly use these notations within your
Common Lisp implementation.


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.md" is the official definition for all other Lisps.
The file "Solution.html" is the same thing in HTML format.
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.