137 lines
4.1 KiB
Groff
137 lines
4.1 KiB
Groff
.TH UNSWEETEN 1 local
|
|
.SH NAME
|
|
sweeten \- filter to translate Lisp/Scheme s-expressions to sweet-expressions
|
|
.SH SYNOPSIS
|
|
.ll +8
|
|
.B sweeten [-b | --builtin-reader] [-C | --common-lisp] [-n] [file]...
|
|
.ll -8
|
|
.br
|
|
.SH DESCRIPTION
|
|
.PP
|
|
.I sweeten
|
|
translates Lisp/Scheme s-expressions to sweet-expressions.
|
|
If no file is listed, it takes input from standard input,
|
|
and results are sent to standard output.
|
|
If one or more files are listed, they are processed in order,
|
|
with results sent to standard output.
|
|
.PP
|
|
Sweet-expressions are a way to represent Lisp/Scheme data and programs
|
|
that adds additional abbreviations beyond those in traditional s-expressions.
|
|
Well-formatted S-expressions should work as-is, but
|
|
sweet-expressions are intended to be easier for humans to understand.
|
|
Unlike most past efforts to make Lisp more readable, the
|
|
sweet-expression approach is
|
|
.I generic
|
|
(the notation does not depend on an underlying semantic) and
|
|
.I homoiconic
|
|
(the underlying data structure is clear from the syntax).
|
|
.PP
|
|
Sweet-expressions are actually the top of three tiers of notation,
|
|
each of which builds on the previous one.
|
|
For more information, see the man page for
|
|
.IR unsweeten .
|
|
|
|
.PP
|
|
Only semicolon comments outside any datum are copied to the output.
|
|
Block comments and comments inside a datum are never copied.
|
|
|
|
.PP
|
|
Sweeten creates only one of many possible representations of its input.
|
|
You may choose to tweak the results of
|
|
.IR sweeten ;
|
|
if you do, you can choose to use
|
|
.I diff-s-sweet(1)
|
|
to confirm that the resulting tweaked file is
|
|
semantically identical to the original.
|
|
|
|
.PP
|
|
By default it uses the reader of the underlying implementation (guile).
|
|
|
|
.PP
|
|
For more information, see
|
|
http://readable.sourceforge.net.
|
|
|
|
|
|
.SH OPTIONS
|
|
|
|
.TP 6
|
|
.BI -b
|
|
Use a built-in reader (instead of the guile read routine);
|
|
this may work better for your input.
|
|
|
|
.TP
|
|
.BI -C
|
|
Use a modified built-in reader (instead of the guile read routine)
|
|
designed to read Common Lisp.
|
|
|
|
.TP
|
|
.BI -n
|
|
Do not use "!" as an indentation character.
|
|
|
|
|
|
.\" .SH "ENVIRONMENT"
|
|
.\" .PP
|
|
|
|
.SH BUGS
|
|
.PP
|
|
This program assumes that the input does not contain any cycles
|
|
(improper lists are okay).
|
|
It can handle input with shared structures (without cycles), but
|
|
the fact that they are shared is lost in the result.
|
|
.PP
|
|
The Common Lisp reader (invoked with -C)
|
|
has not been as well tested.
|
|
It should work just fine for readings s-expressions that are
|
|
legal in both Scheme and Common Lisp.
|
|
It can also handle #\'name as an abbreviation for (function\ name),
|
|
as well as a few Common Lisp capabilities like #:, #., #+, and #P.
|
|
|
|
.SH EXAMPLES
|
|
.PP
|
|
The sweeten tool could be sent the following traditional s-expression:
|
|
.PP
|
|
(define (factorial n)
|
|
(if (<= n 1)
|
|
1
|
|
(* n (factorial (- n 1)))))
|
|
|
|
.PP
|
|
Sweeten might choose to represent it this way:
|
|
|
|
.PP
|
|
define factorial(n)
|
|
if {n <= 1}
|
|
1
|
|
{n * factorial{n - 1}}
|
|
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
.IR unsweeten(1) ,
|
|
.IR diff-s-sweet(1) ,
|
|
.IR sweet-run(1) .
|
|
|
|
.SH "COPYRIGHT NOTICE"
|
|
.PP
|
|
Copyright \(co 2012 David A. Wheeler
|
|
.PP
|
|
This software (including the documentation)
|
|
is released as open source software under the "MIT" license:
|
|
.PP
|
|
Permission is hereby granted, free of charge, to any person obtaining a
|
|
copy of this software and associated documentation files (the "Software"),
|
|
to deal in the Software without restriction, including without limitation
|
|
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
|
and/or sell copies of the Software, and to permit persons to whom the
|
|
Software is furnished to do so, subject to the following conditions:
|
|
.PP
|
|
The above copyright notice and this permission notice shall be included
|
|
in all copies or substantial portions of the Software.
|
|
.PP
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
|
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
OTHER DEALINGS IN THE SOFTWARE.
|
|
|