BQUOTE

     By Kelly Roach.  Last revised 8-Mar-84.  Bugs, comments, and
questions can be sent to ROACH.PA.
     INTRODUCTION.  This package implements the "backquote convention"
punctuation marks "`", ",", and ",@" used in constructing lists.
To use, load <LISP>LIBRARY>BQUOTE.DCOM.  As an extra bonus, this package
offers all the behaviour <LISPUSERS>PQUOTE.DCOM has to offer.  You
should not load PQUOTE if you load BQUOTE.
     This package has many nice features that Interlisp's
nlambda BQUOTE "type-in" approach does not have.  Certain unexpected
breaks that are possible with Interlisp's nlambda BQUOTE do not occur
with this package.  Unlike Interlisp's BQUOTE, this package checks for
uncaptured commas, guarding against possible user error.   Backquotes
in files, in breaks during reads, around dots, and around other
backquotes are handled appropriately.  Backquoted forms are
prettyprinted for the user.
     FINDING BACKQUOTE.  Backquote is character 96.  To make the
backquote character easy to access, the keyactions of <LF> and
<SHIFT-LF> are switched by the BQUOTE package.  Typing <LF> gives
backquote and typing <SHIFT-LF> gives line feed.  (Use <SAME> on a
STAR keyboard.)
     USING BACKQUOTE.  The punctuation marks "`", ",", and ",@"
are used to build lists.  Backquote "`" is used just like quote "'"
and quotes everything in an expression not preceded by a comma ",".
Hence,
	`(A ,B ,C) translates to (LIST 'A B C)
	`(if ,C then ,F) translates to (LIST 'if C 'then F)
	`(it is ,(DATE)) translates to (LIST 'it 'is (DATE))
The punctuation ",@" can be used to enter a segment into a list, using
APPEND.  So we have,
	`(A ,@B) translates to (APPEND '(A) B)
	`(PROG ,V ,@B) translates to (APPEND (LIST 'PROG V) B)
	`(,F ,@M ,L) translates to (APPEND (LIST F) M (LIST L))
     You can also nest backquoted forms.  Do (SETQ X '(Y)).  Then,
	`(1 ,(A `(,X) B)) translates to (LIST 1 (A `(,X) B))
	`(1 `(2 ,,X)) translates to 
	     (LIST 1 (LIST `\BQUOTE (LIST 2 (LIST '\COMMA X))))
	`(1 `(2 ,,X)) evaluates to (1 `(2 ,(Y)))
The BQUOTE package represents forms like "`X", ",X", and ",@X" as
(\BQUOTE X), (\COMMA X), and (\COMMAAT X).  Avoid using the atoms
\BQUOTE, \COMMA, and \COMMAAT directly.
     To determine which commas are captured by which backquotes, think
of your list expression as a tree,
	"(A ,@B ,C . ,D)" has daughters "A", ",@B", ",C" and ",D"
	",X" has daughter "X"
	",@X" has daughter "X"
	",,@,X" has great granddaughter "X"
On any path from the root node of the tree to a terminal node of the
tree, backquotes capture commas just in the same way you would match
left and right parentheses in a parenthesized expression.  Work from
the root node towards the terminal node.  Some of the outermost
backquotes may not have matching commas.
     FONTS.  GACHA fonts normally don't have a backquote char.  The
BQUOTE package inserts backquote chars into GACHA fonts and adjusts
GACHA quote chars to be the mirror images of backquote chars.
     READTABLES & PRETTYPRINTING.  The BQUOTE package changes the
readtable syntax of "`" and "," to do the right thing in lisp
readtables.  Forms are added to PRETTYPRINTMACROS so that backqutoed
expressions are prettyprinted back the way you typed them in.  For
this prettyprinting to work, SYSPRETTYFLG must be T (the BQUOTE
package sets SYSPRETTYFLG when it is LOADed.)  When SYSPRETTYFLG is
NIL, backquoted forms will print out with atoms \BQUOTE, \COMMA, and
\COMMAAT visible.
     QUOTE CHAR.  BQUOTE arranges for expressions like (QUOTE X) to
print out as 'X.  <LISP>LIBRARY>PQUOTE also offers this capability
with respect to quote char.  If you use the BQUOTE package, you don't
need and you shouldn't use PQUOTE.
     BREAKING.  If for some reason you should break while a backquote
form is being read in (say one of your own read macros didn't go as
planned) the BQUOTE package will know how to handle this situation and
not get confused.  BQUOTE does this by adding a form to the system list
BREAKRESETFORMS that resets BQUOTE before and after a break.
     BQUOTE'S IMPLEMENTATION.  The BQUOTE package uses CLISP's own
mechanisms to store the translations of backquoted forms much as CLISP
might store the translation of a FOR loop.  Once a backquoted form is
translated, it does not need to be translated again.  Also like a FOR
loop, when you compile a backquoted form, you actually compile the
translation.  The BQUOTE package is smart about the way it puts
together its translations, so that there aren't unnecessary calls to
CONS, LIST, APPEND, or NCONC.
     COEXISTING WITH NON-BQUOTE USERS.  Because BQUOTE modifies
readtable syntax of characters "'", "`", and ",", there will be some
files created by people who don't use BQUOTE that cannot be properly
LOADed unless there is a way to temporarily turn BQUOTE off.  A BQUOTE
user can turn BQUOTE off by doing
	(BQUOTE.STOP)
and turn BQUOTE back on by doing
	(BQUOTE.START)
To LOAD a file FILE that contains quotes, backquotes, or commas that
aren't meant for BQUOTE, do
	(BQUOTE.STOP)
	(LOAD FILE)
	(BQUOTE.START)
Fortunately, most files created by non-BQUOTE users can be LOADed
safely without having to temporarily turn BQUOTE off.
     THINGS TO KNOW.  (1) The BQUOTE package uses backquote
and quote punctuation not only on your terminal, but in your files.
These files will not LOAD properly without the BQUOTE package loaded
into your environment.  (2) The BQUOTE package smashes GACHA fonts a
bit.  In order for hardcopy to come out right, HELVETICA backquotes
are substituted for GACHA backquotes in files.  (3) You should avoid
using atoms \BQUOTE, \COMMA, and \COMMAAT.  (4) DEDIT, MKSTRING, and
TTYIN "FIX"ing fail to prettyprint backquoted forms, but these
failures can be lived with. (5) The keyactions for <LF> and <SHIFT-LF>
(or <SAME> and <SHIFT-SAME>) are switched.