summaryrefslogtreecommitdiff
path: root/support/splint/cweb/splint.w
diff options
context:
space:
mode:
Diffstat (limited to 'support/splint/cweb/splint.w')
-rw-r--r--support/splint/cweb/splint.w258
1 files changed, 147 insertions, 111 deletions
diff --git a/support/splint/cweb/splint.w b/support/splint/cweb/splint.w
index e50e090c32..4bf32953ff 100644
--- a/support/splint/cweb/splint.w
+++ b/support/splint/cweb/splint.w
@@ -1,4 +1,4 @@
-% Copyright 2012-2020, Alexander Shibakov
+% Copyright 2012-2024, Alexander Shibakov
% This file is part of SPLinT
%
% SPLinT is free software: you can redistribute it and/or modify
@@ -13,19 +13,12 @@
%
% You should have received a copy of the GNU General Public License
% along with SPLinT. If not, see <http://www.gnu.org/licenses/>.
-%
-\newwrite\gindex % index entries generated by the various parsers, \prodstyle{...} commands, etc.
-%
+
\input limbo.sty
\input frontmatter.sty
\def\optimization{5}
\input yy.sty
\modenormal
-\input noweb.sty
- \xreflocaltrue
- \readlxrefs % read the reference file if exists before any sections appear
- \newwrite\xrefstream % references for noweb like style of sectioning.
- \immediate\openout\xrefstream=\jobname.xxr
% multi-column output
\input dcols.sty
\topskip=9pt % this is a purely aesthetic choice, also negating the \raggedbottom
@@ -71,9 +64,9 @@
\defreserved{Y}{\.{Y}}
\showlastactiontrue
+\initauxstream
@**Introduction.
-\setupfootnotes
\splint\footnote{I was tempted to call the package {\tt ParLALRgram}
which stands for Parsing {\sc LALR} Grammars or {\tt PinT} for
`Parsing in \TeX' but both sounded too generic.} (Simple Parsing and
@@ -117,9 +110,9 @@ output is some very rudimentary post- and pre-processing.
Our main concern is thus \CWEAVE\ that not only pretty prints the
program but also creates an index, cross-references all the
sections, etc. Getting \CWEAVE\ to pretty print a language other than
-\Cee\ requires some additional attention. A true digital warrior would
+\Cee\ requires some additional effort. A true digital warrior would
probably try to decipher \CWEAVE's output `in the raw' but, alas, my
-WebFu is not that strong. The loophole comes in the form of a rarely
+(C)WebFu is not that strong. The loophole comes in the form of a rarely
(for a good reason) used \CWEB\ command: the verbatim (\.{@@=...@@>})
output. The material to be output by this construct undergoes minimal
processing and is put inside \.{\\vb\{}$\ldots$\.{\}}. All that is
@@ -134,9 +127,9 @@ merely a brief overview of the approach.
Every \CWEB\ document is split into {\em sections}, each divided into
three parts (any one of which can be empty): the \TeX\ part, the middle part, and
-the \Cee\ part (which should more appropriately be called the {\em code
-part\/}). The code part of each\footnote{With the exception of the nameless \.{@@c}
-sections.} section carries a name for cross referencing
+the \Cee\ part (which should more appropriately be called the {\em code\/} or
+the {\em program\/} part). The \Cee\ part of each\footnote{With the exception of the
+nameless \.{@@c} (or \.{@@p}) sections.} section carries a name for cross referencing
purposes. The sections themselves are automatically numbered by \CWEAVE\ and
their code parts may be referenced from other sections, as well
as included in other sections' code parts using \CWEB's cross referencing
@@ -151,7 +144,7 @@ The original \CWEB\ macros (from \.{cwebmac.tex}) used the numbers
generated by \CWEAVE\ to refer to specific sections. This was true
for the table of contents, as well as the index entries. The macros
used by \splint\ adopt a different convention, proposed by N.~Ramsey
-for his literate programming software, \noweb. In the new system
+for his literate programming software \noweb. In the new system
(which will be referred to as the \noweb\ style of cross referencing),
each section is labelled by the page number where it starts and an
alphabetic character that indicates the order of appearance of the
@@ -163,10 +156,13 @@ section.
The top level (\.{@@**}) sections, introducing
major portions of the code have also been given more prominent
-appearance and carry a chapter number in addition to the the \noweb\
-style section number (the latter is used for cross references, as the
-chapter number gives no indication as to where the said chapter is
-located).
+appearance. They display the chapter number using a large typeface
+and omit the marginal section reference. References to such sections
+are typeset as {\it cnnn\/} where {\it nnn\/} represents the chapter
+number. While such references obscure the page number, hopefully one keeps
+the number of chapters, as well as such references, small. This
+modification improves the appearance of the first chapter pages.
+
\CWEB\ also generates an {\em index\/} of all the identifiers (with
some exceptions, such as single letter names) appearing in the
@@ -247,7 +243,7 @@ important application.
@*1 Parsing and parsers.
At an abstract level, a {\em parser@^parser@>\/} is just a routine
-that transforms text. Naturally, not every possible tranformation is
+that transforms text. Naturally, not every possible transformation is
beneficial, so, informally, the value of a parser lies in its ability
to expose some {\em meaning\/} in the text. If valid texts are reduced
to a small finite set (while each text can be arbitrarily long) one
@@ -342,7 +338,7 @@ longer strings.
Computing $m$ and $n$ above now reduces to incrementing an appropriate
variable upon exiting the corresponding function. More important,
-however, is the observation that this parsing algorithm can be
+however, is the observation that this parser specification can be
extracted from the grammar in a very straightforward fashion. To
better illustrate the r\^ole of the grammar in the choice of the
parsing algorithm, consider the following syntax for the same
@@ -364,10 +360,10 @@ astring:
\noindent While the language is unchanged, so the algorithm
above still works, the lookahead tokens are not {\em immediately\/}
apparent upon looking at the productions. Some preprocessing must take
-place before one can decide on the choice of parser states and the
-appropriate lookahead tokens. Such algorithms indeed exist and result
-in what is known as an {\sc LR} parser for the fragment above
-(actually, a simpler {\sc LALR} parser may be built for this
+place before one can decide on the choice of the parser states and the
+appropriate lookahead tokens. Such parser generating algorithms
+indeed exist and will produce what is known as an {\sc LR} parser
+for the fragment above (actually, a simpler {\sc LALR} parser may be built for this
grammar\footnote{Both of these algorithms will use the parser stack
more efficiently, effectively resolving the `call stack depth' issue
mentioned earlier.}). One can see that some grammar types may make
@@ -411,11 +407,12 @@ non_terminal:
@g
@ $\ldots$ if the syntax is correct.
-In case it is a bit off (note the missing colon after \.{whoops}), the parser will give up and
+In case it is a bit off (note the missing colon after \.{whoops} below), the parser will give up and
you will see a different result. The code in the fragment below is easily
recognizable, and some parts of it (all of \Cee\ code, in fact) are
still pretty printed by \CWEAVE. Only the verbatim portion is left
-unprocessed.
+unprocessed. The layout of the original code is reproduced unchanged, including the braces and production separators (i.e.\
+\.{\yl}) normally removed by the parser for presentation purposes.
@<A silly example@>=
@G
whoops
@@ -478,7 +475,7 @@ automatically from the \CWEB\ source file by the
\CWEAVE\ processing stage. All of these definitions can be
overwritten to get the desired output (say, one might want to typeset
\.{ID} in a roman font, as `identifier'; all that needs to be done to
-make this possible is a macro that says \.{\\prettywordpair\{ID\}\{\{\\rm
+make this possible is to provide a macro that says \.{\\prettywordpair\{ID\}\{\{\\rm
identifier\}\}} in an appropriate namespace (usually
\.{\\hostparternamespace})). The file \.{btokenset.sty} input above
contains a number of such definitions.
@@ -567,11 +564,11 @@ the file below.
@*1 On debugging. This concludes a short introduction to the \bison\
grammar pretty printing using this macro collection. It would be
-incomplete, however, without a short reference to debugging\footnote{Here
-we are talking about debugging the output produced by \CWEAVE\ when
+incomplete, however, without a short reference to debugging\footnote{At
+the moment we are discussing debugging the output produced by \CWEAVE\ when
the included \bison\ parser is used, {\it not\/} debugging parsers
written with the help of this software: the latter topic is covered in more
-detail later on}. There is a
+detail later on.}. There is a
fair amount of debugging information that the macros can output,
unfortunately, very little of it is tailored to the {\em use\/} of the
macros in the \bison\ parser. Most of it is designed to help build a
@@ -653,7 +650,7 @@ identifier determines its association with the appropriate set.}.
a collection of parsers, usually derived from a common set of
productions, and sharing a common lexer. As the name suggests, the
parsers in the collection are tried in order until the input is parsed
-successfully or every parser has been tried. This terminology may be the
+successfully or every parser has been tried. This terminology may become a
source of some confusion, since each parsing algorithm used by \bison\
maintains several stacks. We will always refer to them by naming a specific
task the stack is used for (such as the {\em value stack\/} or the
@@ -687,7 +684,7 @@ productions.
\aterm{term} in a narrow sense, an `element' of a grammar. Instead of
a long winded definition, an example, such as \prodstyle{ID} should
suffice. Terms are further classified into {\it terminals\/} (tokens)
-and {\it nonterminals\/} (which can be intuitively thought of as
+and {\it nonterminals\/} (which may be intuitively thought of as
composite terms).
\aterm{token} in short, an element of a set. Usually encoded as an
@@ -734,7 +731,7 @@ some attention, as well. There are a number of excellent programs
written to automate this step in much the same fashion as \bison\
automates the generation of parsers. One such tool, \flex, though
(in the opinion of this author) slightly lacking in the simplicity and
-elegance as compared to \bison, was used to implement the lexer for
+elegance when compared to \bison, was used to implement the lexer for
this software suite. Lexing in \TeX\ will be discussed in considerable
detail later in this manual.
@@ -750,7 +747,7 @@ syntax-directed translation} (which requires an appropriate
abstraction to represent \bison's actions inside \TeX). We shall
begin by discussing the parsing process itself.
-@*1 Arrays, stacks and the parser.
+@*1 Arrays, stacks, and the parser.
Let us briefly examine the programming environment offered by \TeX.
Designed for typesetting, \TeX's remarkable language
provides a layer of macro processing atop of a set of commands that
@@ -826,7 +823,9 @@ implementation). Since stacks pop up and disappear frequently (what
else are stacks to do?), list macros are usually used to store
them. The optimized parser uses a separate \.{\\count} register to
keep track of the top of the stack in the corresponding associative
-array.
+array\footnote{Which means, unfortunately, that making such fully optimized
+parser {\em reentrant\/} would take an extraordinary amount of effort. Hence,
+if reentrancy is a requirement, stacks are better kept inside list macros.}.
Let us now switch our attention
to the code that implements the parser and scanner {\it functions\/}.
@@ -1175,8 +1174,10 @@ token and move on but what if this was a control sequence? After all,
just as easily as \.{\\string} makes a sequence into characters,
\.{\\csname}$\,\ldots\,$\.{\\endcsname} pair will make any sequence of
characters into a control sequence so determining the end the character
-sequence produced by \.{\\string} may prove impossible. Huh~$\ldots$
-
+sequence produced by \.{\\string} may prove impossible.
+$$
+\hbox{Huh~$\ldots$}
+$$
What we need is a backup mechanism: keeping a copy of the
token sequence ahead, one can use \.{\\string} to see whether
the next token is a real
@@ -1233,7 +1234,7 @@ or even {\it tokener}), discussed in the next section.
@*1 Lexing in \TeX. In a typical system that uses a parser to process
text, the parsing pass is usually split into several stages: the raw
input, the lexical analysis (or simply {\it lexing}), and the parsing
-proper. The {\it lexing\/} (also called {\it scanning}, we use these
+proper. The {\it lexing\/} pass (also called {\it scanning}, we use these
terms interchangeably) clumps various sequences of characters into
{\it tokens\/} to facilitate the parsing stage. The reasons for this
particular hierarchy are largely pragmatic and are partially historic
@@ -1242,7 +1243,7 @@ phases, as well, although it usually isn't).
If one recalls a few basic facts from the formal language theory, it
becomes obvious that a lexer, that parses {\it regular\/} languages,
-can (theoretically) be replaced by an {\sc LALR} parser, that parses {\it
+can be (in theory) replaced by an {\sc LALR} parser, that parses {\it
context-free\/} ones (or some subset thereof, which is
still a super set of all regular languages). A common justification given for
creating specialized lexers is efficiency and speed. The
@@ -1266,7 +1267,10 @@ matching input is accepted. The only straightforward way to do this
with a traditional parser is to parse longer and longer inputs again
and again. While this process can be optimized to a certain degree,
the fact that a parser has a {\it stack\/} to maintain limits its
-ability to back up.
+ability to back up\footnote{It should be also mentioned that the fact that
+the lexing pass takes place prior to the parser consuming the resulting tokens
+allows one to process some grammars that are not context free. See, for example
+the {\em parser hack\/} used to process |typedef|s in \Cee.}.
As an aside, the mechanism by which \CWEB\ assembles its `scraps'
into chunks of recognized code is essentially iterative lexing,
@@ -1450,7 +1454,7 @@ altering the grammar mentioned above apply in this case, as well, only
at the `lexical analysis level'. At a minimum, the set of tokens
matched by the scanner would have to be altered.
-A much more satisfying approach involves inserting the hints at the input stage and
+A much more satisfying approach, however, involves inserting the hints at the input stage and
passing this information to the scanner and the parser as part of the token
`values'. The hints themselves can masquerade as characters ignored by the scanner
(white space\footnote{Or even the `intercharacter space', to make the
@@ -1482,7 +1486,8 @@ This is exactly what the scanner produced by the tools in this package
does: along with the main stream of tokens meant for the parser, it
produces two\footnote{There would be no difficulty in splitting either
of these streams into multiple `substreams' by modifying the stream
-extraction macros accordingly.} hidden streams (called the \.{\\yyformat} stream and
+extraction macros accordingly.} hidden streams\namedspot{parser.streams}
+(called the \.{\\yyformat} stream and
the \.{\\yystash} stream) and provides the parser with two
strings (currently only strings of digits are used although arbitrary
sequences of \TeX\ tokens can be used as pointers) with the promise
@@ -1490,10 +1495,13 @@ that {\it all the `hints' between the beginning of the corresponding
stream and the point labeled by the current stream pointer appeared
among the characters up to and, possibly, including the ones matched
as the current token}. The macros to extract the relevant parts of the
-streams (\.{\\yyreadfifo} and its cousins) are provided for the
+streams (\.{\\consumelistupto} and its cousins) are provided for the
convenience of the parser designer.
-The \.{\\yystash} stream collects all the typesetting commands inserted by
+What the parser does with these pointers and the information they provide, is
+up to the parser designer (the parsers for \flex\ and \bison\ syntax
+in this package use somewhat different strategies).
+The \.{\\yystash} stream currently collects all the typesetting commands inserted by
\CWEB\ to be possibly used in displaying the action code in \bison\
productions, for example. Because of this, it may appear in somewhat
unexpected places, introducing spaces where the programmer did not
@@ -1505,10 +1513,10 @@ The interested reader can consult the input routine macros in
\.{yyinput.sty} for the
details of the internal representation of the streams.
-In the interest of full disclosure, let me point out that this simple
+In the interest of full disclosure, it should be pointed out that this simple
technique introduces a significant strain on \TeX's
computational resources: the lowest level macros, the ones that handle
-character input and are thus executed (sometimes multiple times), for
+character input and are thus executed (in some cases multiple times), for
{\it every\/} character in the input stream are rather complicated and
therefore, slow. Whenever the use of such streams is not desired a simpler
input routine can be written to speed up the process (see
@@ -1517,9 +1525,13 @@ input routine can be written to speed up the process (see
Finally, while probably not directly related to the present
discussion, this approach has one more interesting feature: after the
parser is finished, the parser output and the streams exist
-`statically', fully available for any last minute preprocessing or for
+`statically', fully available for any last minute postprocessing or for
debugging purposes, if necessary\footnote{One may think of the parser output
-as an {\it executable abstract syntax tree (AST)}.}. Under most circumstances, the parser
+as an {\it executable abstract syntax tree\/} (\AST\ or \EAST\ if one
+likes cute abbreviations, or even e\AST\ for an extra touch of modernity).
+This parser feature is used to implement the facility that allows easy referencing of
+productions in the section that implements the action code for one. See \.{yyunion.sty}
+and the source of this file (\.{splint.w}) for details.}. Under most circumstances, the parser
output is `executed' and the macros in the output are the ones reading
the various streams using the pointers supplied at the parsing stage
(at least, this is the case for all the parsers supplied with the
@@ -1532,7 +1544,9 @@ how the tables produced by \bison\ get converted into \TeX\ {\it macros\/}
that drive the parser in {\it \TeX}.
The tables that drive the \bison\ input parsers
-are collected in \.{\{b,d,f,g,n\}yytab.tex} and \.{small\_tab.tex}. Each
+are collected in \.{\{b,d,f,g,n\}yytab.tex}, \.{small\_tab.tex} and other similarly named
+files\footnote{Incidentally, one of the names above is not used anymore. See the \.{cweb}
+directory after a successful build to find out which. Aren't footnotes great?!}. Each
one of these files contains the tables that implement a specific parser
used during different stages of processing.
Their exact function is well explained
@@ -1584,30 +1598,34 @@ it after \.{\\classexpand} (such sequences are usually prepared by the
\bison\ from your grammar).
You can give a case a readable label (say, \.{brackets}) and enclose
-this label in \.{\\raw}$\ldots$\.{\\raw}. A word of caution: an `\.{a}'
-inside of \.{\\raw}$\ldots$\.{\\raw} (which is most likely an
-\.{a}$_{11}$ unless you played with the category codes before loading the
-\.{\\switchon} macros) and the one outside it are two different
+this label in \.{\\raw}$\ldots$\.{\\raw}. A word of caution: an
+`\.{a}' inside of \.{\\raw}$\ldots$\.{\\raw} (which is most likely an
+\.{a}$_{11}$ unless you played with the category codes before loading
+the \.{\\switchon} macros) and the one outside it are two different
characters, as one is no longer a letter (category 11) in the eyes of
\TeX\ whereas the other one still is. For this reason one should not
-use characters other than letters in h\.{\{}is\.{,}er\.{\}} state
-{\em names}: the way a state picks an action does not distinguish between,
+use characters other than letters in h\.{\{}is\.{,}er\.{\}} state {\em
+names\/} if such characters can form tokens by themselves:
+the way a state picks an action does not distinguish between,
say, a `\.{(}' in `\.{(letter)}' and a stand alone `\.{(}' and may
pick an action that you did not intend\footnote{One way to mitigate
this is by putting such named states at the end of the switch, {\em
-after\/} the actions labelled by the standalone characters.}.
-This applies even if `\.{(}'
-is not among the characters explicitly inserted in the state macro: if
-an action for a given character is not found in the state macro, the
-\.{\\switchon} macro will insert a current \.{\\default} action
-instead, which most often you would want to be \.{\\yylex} or
-\.{\\yyinput} (i.e.\ skip this token). If a single `\.{(}' or `\.{)}' matches
-the braced group that follows `\.{(letter)}' chaos may ensue (most
-likely \TeX\ will keep reading past the \.{\\end} or \.{\\yyeof} that
-should have terminated the input). Make the names of character
-categories as unique as possible: the \.{\\switchon} is simply a
-string matching mechanism, with the added differentiation between
-characters of different categories.
+after\/} the actions labelled by the standalone characters. There is nothing
+special about non-letter characters, of course. To continue the \.{letter}
+example, placing a state named \.{let} {\em after\/} the \.{letter} one
+will make it essentially invisible to the switch macros for the reasons
+explained before this footnote.}. This applies even if `\.{(}' is not among
+the characters explicitly
+inserted in the state macro: if an action for a given character is not
+found in the state macro, the \.{\\switchon} macro will insert a
+current \.{\\default} action instead, which most often you would want
+to be \.{\\yylex} or \.{\\yyinput} (i.e.\ skip this token). If a
+single `\.{(}' or `\.{)}' matches the braced group that follows
+`\.{(letter)}' chaos may ensue (most likely \TeX\ will keep reading
+past the \.{\\end} or \.{\\yyeof} that should have terminated the
+input). Make the names of character categories as unique as possible:
+the \.{\\switchon} is simply a string matching mechanism, with the
+added differentiation between characters of different categories.
Finally, the construct \.{\\statecomment}{\it
anything\/}\.{\\statecomment} allows you to insert comments in the
@@ -1620,15 +1638,14 @@ makes the debugging information difficult to decipher). The debugging
mode for the lexer implemented with these macros is activated by
\.{\\tracedfatrue}.
-The functionality of the \.{\\switchon} (as well as the \.{\\switchonwithtype}, which
-is capable of some rudimentary type checking) macros (for `historical'
-reasons, one can also use \.{\\action} as a synonym for the latter) has been
-implemented in a number of other macro packages (see \cite[Fi] that
-discusses the well-known and widely used \.{\\CASE} and \.{\\FIND}
-macros). The macros in this collection have the additional property
-that the only assignments that persist after the \.{\\switchon}
-completes are the ones performed by the user code inside the selected
-case.
+The functionality of the \.{\\switchon} (as well as the
+\.{\\switchonwithtype}, which is capable of some rudimentary type
+checking) macros has been implemented in a number of other macro
+packages (see \cite[Fi] that discusses the well-known and widely used
+\.{\\CASE} and \.{\\FIND} macros). The macros in this collection have
+the additional property that the only assignments that persist after
+the \.{\\switchon} completes are the ones performed by the user code
+inside the selected case.
This last property of the switch macros is implemented using another
mechanism that is part of this macro suite: the `subroutine-like'
@@ -1662,7 +1679,10 @@ be able to write parsers of arbitrary sophistication:
value of the $n$-th term of the rule's right hand side, $n>0$. The left
hand side of a production is accessed through \.{\\yyval}. A
convenient shortcut is \.{\\yy0\{{\rm \TeX\space material}\}} which
-will expand (as in \.{\\edef}) the `\TeX\ material' inside the braces. Thus, a simple way
+will expand (as in \.{\\edef}) the `\TeX\ material' inside the braces and store the result
+in \.{\\yyval} (note that this only works if a sequence of \.{0}s, possibly followed or preceeded
+by spaces are the only tokens between \.{\\yy} and the opening braces; see the discussion of
+\.{\\bb} macros below for a description of what happens in other cases). Thus, a simple way
to concatenate the values of the first two production terms is
\.{\\yy0\{\\the\\yy(1)\\the\\yy(2)\}}. The included \bison\
parser can also be used to provide support for `symbolic names',
@@ -1673,8 +1693,9 @@ however.
There is also a \.{\\bb$\,n$} macro, that has no analogue in the
`real' \bison\ parsers, and provides access to the term
-values in the `natural order' (e.g.~\.{\\bb1} is the last term read). Its
-intended use is with the `inline' rules (see the main parser for
+values in the `natural order' (e.g.~\.{\\bb1} is the last term in the part of
+the production preceeding the action). Its intended use is with the `inline'
+rules (see the main parser for
such examples). As of version \.{3.0} \bison\ no longer outputs
|yyrhs| and |yyprhs|, which makes it impossible to produce the
|yyrthree| array necessary for processing such rules in the `left to right'
@@ -1682,13 +1703,41 @@ order. One might also note that the new notation is better suited for
the inline rules since the value that is pushed on the stack is that
of \.{\\bb0}, i.e.~the term implicitly inserted by \bison. Be aware
that there are no \.{\\bb[$\cdot$]} or \.{\\bb($\cdot$)} versions of
-these macros, for obvious reasons. A less obvious feature of this
+these macros, for obvious reasons\footnote{The obvious reason is the mechanism
+used by \.{\\yy[$\cdot$]} and \.{\\yy($\cdot$)} to make them expandable.
+These macros are basically references to the appropriate token registers. Since
+the \.{\\bb} macros were designed for the environment where \.{\\yylen} is unknown,
+establishing such references before the action is executed is not possible. A
+less obvious reason is the author's lazy approach.}. A less obvious feature of this
macro is its `nonexpandable' nature. This means they cannot be used
-inside \.{\\edef}. Thus, the most common use pattern is
-\.{\\bb$\,n$\{\\toks$\,m$\}} with a subsequent expansion of
-\.{\\toks$\,m$}. Making these macros expandable is certainly possible
+inside \.{\\edef} (just like its \.{\\yy$\,n$} counterpart, it makes several
+assignments which will not be executed by \.{\\edef}).
+Thus, the most common use pattern is \.{\\bb$\,n$\{\\toks$\,m$\}} (where $n>0$)
+with a subsequent expansion of \.{\\toks$\,m$}\footnote{Similar to how \.{\\yy$\,n$} macros
+work, whenever $n>0$, this pattern simply puts the contents of the braced group
+that follows in front of a (braced) single expansion of the appropriate
+value on the stack. If, as in the example above, the contents of the
+braced group are \.{\\toks$\,m$}, this effectively stores the value of the braced group in
+the token register. In the case $n=0$ the meaning is different:
+the stack value {\em corresponding to the implicit term\/} becomes the expanded (by \.{\\edef})
+contents of the braced group following \.{\\bb$\,n$}.}.
+Making these macros expandable is certainly possible
but does not seem crucial for the intended limited use pattern.
+Finally, the scripts included with \splint\ include a postprocessor
+(see the appropriate~\.{Makefile} for further details) that allows the
+use of the `native' \bison\ term references (i.e.\ of the form
+\.{\char`\$}$\ldots$) to access the value stack\footnote{Incidentally,
+\bison\ itself uses a preprocessor (\.{M4}) to turn its term references
+into valid \Cee.}. Utilizing the postprocessor allows any syntax for
+term references used by \bison\ to be used inside \.{TeX}$\ldots$ \Cee\ macros.
+In this case a typical
+idiom is \.{\\the\char`\$[term\_name]} to get the value of
+\prodstyle{term_name}. While storing a new value for the term (i.e.\
+modifying the value stack) is also possible, it is not very
+straightforward and thus not recommended. This applies to all forms of
+term references discussed above.
+
Naturally, a parser writer may need a number of other data
abstractions to complete the task. Since these are highly dependent on
the nature of the processing the parser is supposed to provide, we
@@ -1703,7 +1752,8 @@ most importantly, to create `reentrant' parsers that can, e.g.\ call
{\it themselves\/} recursively.
@*1 `Optimization'.
-\namedspot{optimization}By default, the generated parser and scanner keep all of their tables
+\namedspot{optimization}By default, the generated parser and scanner
+keep all of their tables
in separate token registers. Each stack is kept in a single macro (this
description is further complicated by the support for parser {\it
namespaces\/} that exists even for unoptimized parsers but this
@@ -1806,7 +1856,8 @@ appropriate terms in a production. If mathematics pays your bills, use
\let\hostparsernamespace\mainnamespace % to typeset examples in the text
% properly
-@**Index. This section is, perhaps, the most valuable product of
+@**Index. \global\let\secrangedisplay\empty% do not show the current section range anymore
+This section is, perhaps, the most valuable product of
\CWEB's labors. It lists references to definitions (set in {\it
italic}) as well as uses for each \Cee\ identifier used in the
source. Special facilities have been added to extend the indexing to
@@ -1845,7 +1896,7 @@ appeared on the left hand side of a production. A production:
}%
\beginmprod
left_hand_side:
- term.1 term.2 term.3 \{\stashed{|TeX_("/do/something/yy(1)");|}\}
+ term.1 term.2 term.3 \{\stashed{|TeX_("/do/something/with/yy(1)");|}\}
\endmprod
inside the \TeX\ part of a \CWEB\ section will generate several
index entries, as well, including the entries for any
@@ -1865,20 +1916,18 @@ available, thus avoiding referencing the same token twice).
\TeX\ control sequences are listed following the index of all \bison\ and \flex\
entries. The different sections of the index are separated by a {\it dinkus\/}
-(\dinkus). Since it is nearly impossible to determine at what point a
+(\dinkus)@^dinkus (\dinkus)@>. Since it is nearly impossible to determine at what point a
\TeX\ macro is defined (and most of them are defined outside of the
\CWEB\ sources), only their uses are listed (to be more precise, {\it
every\/} appearance of a macro is assumed to be its use). In a few cases, a
`graphic' representation for a control sequence appears in the index (for
-example, {\let\writetexidxentry\writetextxtidxentry
-\def\texnspace{texline}\def\texispace{index}\inlineTeXx{/getfirst}} represents
+example, \texref{/getfirst} represents
{\let\writetexidxentry\writetextxtidxentry
\def\texnspace{other}\def\texispace{other}\inlineTeXx{/getfirst}$\!$}).
The index entries are ordered alphabetically. The
latter may not be entirely obvious in the cases when the `graphical
representation' of the corresponding token manifests a significant
-departure from its string version (such as
-{\let\writetexidxentry\writetextxtidxentry|TeX_("/yy(1)");|}
+departure from its string version (such as \texref{/yy(1)}
instead of {\def\texnspace{other}\def\texispace{other}%
\let\writetexidxentry\writetextxtidxentry
|TeX_("/yy(1)");|$\!$}). Incidentally, for the examples on this page
@@ -1886,11 +1935,8 @@ instead of {\def\texnspace{other}\def\texispace{other}%
the `graphic' as well as `text' versions of the control sequence are
indexed. It is instructive to verify that their location in the index
corresponds to the `spelling' of their visual representation (thus,
-{\let\writetexidxentry\writetextxtidxentry
-\def\texnspace{texline}\def\texispace{index}\inlineTeXx{/getfirst}}
-appears under `p'). One should also be aware that the indexing of some terms has
-been suppressed, since they appear too often.
-\unsetfootnotes % this way the footnote stream is not affected by the extra index pages
+\texref{/getfirst} appears under `p'). One should also be aware that
+the indexing of some terms has been suppressed, since they appear too often.
% TODO: explain the visibility system. Note the anomalous order of \prodstyle{term.1}
% vs.~\prodstyle{term0} due to the dot in \.{term.1}, which is otherwise invisible. Underscore the
% importance of following a consistent naming scheme, including the `stringized' versions
@@ -1899,15 +1945,5 @@ been suppressed, since they appear too often.
@q the lack of control over the generation of \CWEB's index; the correct order @>
@q of index entries depends on the placement of this inclusion @>
@i alphas.hx
-
-\closeout\gindex
-\termindexfalse % do not attach indexing entries to the terms in the index, or the section list
-\def\next{\expandafter\eatone\string}
-\edef\unindexable{{\next\the}{\next\nx}{\next\yy}{\next\yylexnext}{\next\else}{\next\fi}{\next\yyBEGIN}{\next\next}}
-\input gindex.sty
-%\indexverbosetrue
-\let\inx\inxmod
-\let\fin\finmod
-\lxrefseparator % start generating section lists
-%\displaytokenrawtrue % so that the `nonstringified' version of the token is displayed as well
-\def\topofcontents{\null\vskip-3\baselineskip\centerline{C{\sc ONTENTS} (\sc\uppercase\expandafter{\title})}\medskip}
+\makeunindexablex{{\csstring\the}{\csstring\nx}{\csstring\yy}{\csstring\yylexnext}%
+ {\csstring\else}{\csstring\fi}{\csstring\yyBEGIN}{\csstring\next}}