Commit 6242aa47 authored by paysan's avatar paysan
Browse files

Ansified chapter 5

parent b94bb5da
......@@ -1586,7 +1586,7 @@ only a byte, let's make each ``slot'' one byte. We'll call the table
\forth{ROMANS}:
\begin{Code}
Create romans ( ones) char i c, char V c,
Create romans ( ones) char I c, char V c,
( tens) char X c, char L c,
( hundreds) char C c, char D c,
( thousands) char M c,
......@@ -1618,7 +1618,7 @@ Now we can find our way to any ``arm position'' by adding the contents of
\forth{ROMANS}:
\begin{Code}
: COLUMN ( -- adr-of-column ) ROMANS COLUMN# @ + ;
: column ( -- adr-of-column ) romans column# @ + ;
\end{Code}
Let's see if we can implement one of the words to display a symbol. We'll
start with \forth{ONER}.
......
......@@ -119,7 +119,7 @@ loads the chapters in the proper sequence.
\setcounter{screen}{1}
\begin{Screen}
\ QTF+ Load Screen 07/09/83
: RELEASE# ." 2.01" ;
: release# ." 2.01" ;
9 load \ compiler tools, language primitives
12 load \ video primitives
21 load \ editor
......@@ -206,8 +206,8 @@ For instance, these two ``skip-line''s keep the definition of
\forth{NUTATE} from being compiled without causing problems in
encountering either right parenthesis:
\begin{Code}
\ : NUTATE ( x y z )
\ swap rot (NUTATE) ;
\ : nutate ( x y z )
\ swap rot (nutate) ;
\end{Code}
\forthb{\bs S} is pronounced ``skip-screen.'' It causes the \Forth{}
interpreter to stop interpreting the screen entirely, as though there
......@@ -246,15 +246,15 @@ to the beginning of the chapter.
\begin{Screen}
\ GRAPHICS Chapter load 07/11/83
1 FH load \ dot-drawing primitive
2 FH 3 FH thru \ line-drawing primitives
4 FH 7 FH thru \ scaling, rotation
8 FH load \ box
9 FH 11 FH thru \ circle
1 fh load \ dot-drawing primitive
2 fh 3 fh thru \ line-drawing primitives
4 fh 7 fh thru \ scaling, rotation
8 fh load \ box
9 fh 11 fh thru \ circle
CORNER \ initialize relative position to low-left corner
corner \ initialize relative position to low-left corner
......@@ -283,20 +283,20 @@ single word, \forthb{FH} (see \App{C} for its definition).
The phrase
\begin{Code}
1 FH load
1 fh load
\end{Code}
is read ``1 from here \forth{LOAD},'' and is equivalent
to \forth{1 +LOAD}.
Similarly,
\begin{Code}
2 FH 5 FH thru
2 fh 5 fh thru
\end{Code}
is read ``2 from here, 5 from here \forth{THRU}.''
Some programmers begin each chapter with a dummy word; e.g.,
\begin{Code}
: VIDEO-IO ;
: video-io ;
\end{Code}
%Page 141 in first edition.
and list its name in the comment on the line where the chapter is
......@@ -471,15 +471,15 @@ Some might answer that rhetorical question: ``It's easier to remember
names than numbers.'' If that's so, then predefine those block numbers
as constants, e.g.:
\begin{Code}
90 Constant FRAMING
90 Constant framing
\end{Code}
Then to load the ``framing'' section, enter
\begin{Code}
FRAMING load
framing load
\end{Code}
Or, to list the section's load block, enter
\begin{Code}
FRAMING list
framing list
\end{Code}
(It's a convention that names of sections end in ``ING.'')
......@@ -527,7 +527,7 @@ page is called a ``triad;'' most \Forth{} systems include the word
\forth{TRIAD} to produce it, given as an argument the number of any of
the three screens in the triad. For instance, if you type
\begin{Code}
77 TRIAD
77 triad
\end{Code}
you'll get a page that includes 75, 76, and 77.
......@@ -666,12 +666,12 @@ one word per line.
%! There should be no page breaks between the text and code
\noindent \emph{Bad:}
\begin{Code}
: ARRIVING ." HELLO" ; : DEPARTING ." GOODBYE" ;
: arriving ." Hello" ; : departing ." Goodbye" ;
\end{Code}
\noindent \emph{Good:}
\begin{Code}
: ARRIVING ." HELLO" ;
: DEPARTING ." GOODBYE" ;
: arriving ." Hello" ;
: departing ." Goodbye" ;
\end{Code}
This rule makes it easier to find a definition in the listing. (When
definitions continue for more than one line, the subsequent lines
......@@ -684,8 +684,8 @@ leaves room for an explanatory comment on the same line. The
exception is a large ``family'' of words (defined by a common
defining-word) which do not need unique comments:
\begin{Code}
0 HUE BLACK 1 HUE BLUE 2 HUE GREEN
3 HUE CYAN 4 HUE RED 5 HUE MAGENTA
0 Hue black 1 Hue blue 2 Hue green
3 Hue cyan 4 Hue red 5 Hue magenta
\end{Code}
\begin{tip}
Leave lots of room at the bottom of the screen for later additions.
......@@ -725,8 +725,8 @@ it was at the beginning.} This extra bit of insurance can be
accomplished in this fashion:
\begin{Code}
base @ hex \ save original BASE on stack
0A2 Constant BELLS
0A4 Constant WHISTLES
0A2 Constant bells
0A4 Constant whistles
... etc. ...
base ! \ restore it
\end{Code}
......@@ -822,30 +822,30 @@ Here are some common errors of spacing and indentation:
\goodbreak\bigskip\noindent
\emph{Bad} (name not separated from the body of the definition):
\begin{Code}
: PUSH HEAVE HO ;
: push heave ho ;
\end{Code}
\emph{Good:}
\begin{Code}
: PUSH HEAVE HO ;
: push heave ho ;
\end{Code}
\emph{Bad} (subsequent lines not indented three spaces):
\begin{Code}
: RIDDANCE ( thing-never-to-darken-again -- )
DARKEN NEVER AGAIN ;
: riddance ( thing-never-to-darken-again -- )
darken never again ;
\end{Code}
\emph{Good:}
\begin{Code}
: RIDDANCE ( thing-never-to-darken-again -- )
DARKEN NEVER AGAIN ;
: riddance ( thing-never-to-darken-again -- )
darken never again ;
\end{Code}
\emph{Bad} (lack of phrasing):
\begin{Code}
: GETTYSBURG 4 SCORE 7 YEARS + AGO ;
: gettysburg 4 score 7 years + ago ;
\end{Code}
\goodbreak\noindent
\emph{Good:}
\begin{Code}
: GETTYSBURG 4 SCORE 7 YEARS + AGO ;
: gettysburg 4 score 7 years + ago ;
\end{Code}
Phrasing is a subjective art;
I've yet to see a useful set of formal rules.\\
......@@ -1107,7 +1107,7 @@ the entire stack
picture, along with the double-hyphen, separated by the ``or'' symbol.
For instance:
\begin{Code}
-FIND ( -- apf len t=found | -- f=not-found )
-find ( -- apf len t=found | -- f=not-found )
\end{Code}
This comment indicates that if the word is found, three arguments are
returned (with the flag on top); otherwise only a false flag is
......@@ -1125,7 +1125,7 @@ the same line, separated by three spaces:
\end{Code}
or listed vertically:
\begin{Code}
-FIND \ found:( -- apf len t )
-find \ found:( -- apf len t )
\ not-found:( -- f )
\end{Code}
\index{S!Stack-effect comment|)}%
......@@ -1139,7 +1139,7 @@ For example, here's the definition of an insert buffer called
\forth{|INSERT} :
\begin{Code}
Create |INSERT 64 allot \ { 1# | 63text }
Create |insert 64 allot \ { 1# | 63text }
\end{Code}
The ``faces'' (curly-brackets) begin and end the structure comment;
the bars separate the various elements in the structure; the numbers
......@@ -1167,23 +1167,23 @@ instance, if the preamble gives the above bit-pattern the name
``status,'' then ``status'' can be used in stack comments to indicate
values with that pattern:
\begin{Code}
: STATUS? ( -- status) ... ;
: status? ( -- status) ... ;
\end{Code}
If a \forthb{2VARIABLE} contains one double-length value, the comment
should be a stack picture that indicates the contents:
\begin{Code}
2Variable PRICE \ price in cents
2Variable price \ price in cents
\end{Code}
If a \forthb{2VARIABLE} contains two single-length data elements, it's
given a stack picture showing what would be on the stack after a
\forth{2@}. Thus:
\begin{Code}
2Variable MEASUREMENTS ( height weight )
2Variable measurements ( height weight )
\end{Code}
This is different from the comment that would be used if
\forth{MEASUREMENTS} were defined by \forthb{CREATE}.
\begin{Code}
Create MEASUREMENTS 4 allot \ { 2weight | 2height }
Create measurements 2 cells allot \ { 2weight | 2height }
\end{Code}
(While both statements produce the same result in the dictionary, the
use of \forthb{2VARIABLE} implies that the values will normally be
......@@ -1213,26 +1213,22 @@ text & sequence of characters, delimited by non-blank \\
\end{tabular}}
\medskip
Follow ``text'' with the actual delimiter required; e.g.:
\forth{text"} or \forth{text)}
Follow ``text'' with the actual delimiter required in angular brackets; e.g.:
\forth{"text<">"} or \forth{"text<)>"}
\vspace{1ex}\blackline{0ex}
\end{table*}
%% Note: AH : typewriter style footnote with *
%% Note: AH : text" and text) are literal examples,
%% and should be slanted or such.
The input-stream comment appears \emph{before} the stack comment, and
The input-stream comment appears \emph{within} the stack comment, and
is \emph{not} encapsulated between its own pair of parentheses, but
simply surrounded
%Page 156 in first edition.
by three spaces on each side. For instance, here's one way to comment
the definition of \forth{'} (tick) showing first the input-stream comment,
then the stack comment:
by quotes on each side. For instance, here's one way to comment
the definition of \forth{'} (tick) showing the input-stream comment,
together with the stack comment:
\begin{Code}
: ' \ name ( -- a)
\end{Code}
If you prefer to use \forth{(} , the comment would look like this:
\begin{Code}
: ' ( name ( -- a)
: ' ( "name" -- a )
\end{Code}
\index{S!String input, receiving|(}%
Incidentally, there are three distinct ways to receive string input.
......@@ -1291,12 +1287,12 @@ or
This definition takes as its incoming argument a number that
represents the number of spaces to type.
\begin{Code}
: ELEMENT ( element# -- 'element) 2* table + ;
: element ( element# -- 'element ) cells table + ;
\end{Code}
This definition converts an index, which it consumes, into an address
within a table of 2-byte elements corresponding to the indexed element.
\begin{Code}
: pad ( -- 'scratch-pad) here 80 + ;
: pad ( -- 'scratch-pad ) here 80 + ;
\end{Code}
This definition returns an address of a scratch region of memory.
......@@ -1304,24 +1300,24 @@ Occasionally, readability is best served by including both types of
comment. In this case, the purpose comment should appear last. For
instance:
\begin{Code}
: block ( n -- a) \ ensure block n in buffer at a
: block ( n -- a ) \ ensure block n in buffer at a
\end{Code}
\begin{tip}
Indicate the type of comment by ordering: input-stream comments first,
stack-effect comments second, purpose comments last.
Indicate the type of comment by ordering: input-stream and stack
comments first, purpose comments last.
\end{tip}
For example:
\begin{Code}
: GET \ name ( -- a) get first match
: get ( "name" -- a ) \ get first match
\end{Code}
If you prefer to use \forth{(}, then write:
\begin{Code}
: GET ( name ( -- a) ( get first match)
: get ( "name" -- a ) ( get first match)
\end{Code}
If necessary, you can put the purpose comment on a second line:
\begin{Code}
: word \ name ( c -- a)
: word ( c "name<c>" -- a )
\ scan for string delimt'd by "c"; leave at a
... ;
\end{Code}
......@@ -1358,18 +1354,17 @@ address is on the stack when the run-time code begins.
\bigskip\noindent
\emph{Bad} (run-time comment includes apf):
\begin{Code}
: ARRAY \ name ( #cells)
Create 2* allot
DOES> ( i apf -- 'cell) swap 2* + ;
: array ( "name" #cells -- )
Create cells allot
DOES> ( i apf -- 'cell ) swap cells + ;
\end{Code}
\goodbreak\noindent
\emph{Good:}
\begin{Code}
: ARRAY \ name ( #cells)
Create 2* allot
DOES> ( i -- 'cell) swap 2* + ;
: array ( "name" #cells -- )
Create cells allot
DOES> ( i -- 'cell ) swap cells + ;
\end{Code}
%% Note: AH: CELLS instead of 2* is indicated
Words defined by this word \forth{ARRAY} will exhibit the stack effect:
\begin{Code}
( i -- 'cell)
......@@ -1377,7 +1372,7 @@ Words defined by this word \forth{ARRAY} will exhibit the stack effect:
If the defining word does not specify the run-time behavior, there still
exists a run-time behavior, and it may be commented:
\begin{Code}
: Variable ( name ( -- ) Create 2 allot ;
: Variable ( name ( -- ) Create 1 cells allot ;
\ DOES> ( -- adr )
\end{Code}
\index{D!Defining words:!comments for|)}%
......@@ -1653,7 +1648,7 @@ years someone realized that a nicer name is \forth{WORDS}. Not only
does \forth{WORDS} sound more pleasant by itself, it also works nicely
with vocabulary names. For instance:
\begin{Code}
EDITOR words
editor words
\end{Code}
or
\begin{Code}
......@@ -1676,7 +1671,7 @@ word will be used in context. For instance:
%%!!!te This really seems to be a description environment
\ifeightyfour
\begin{Code}[fontfamily=cmss,commandchars=\&\{\}]
SHUTTER OPEN
shutter open
OPEN is the appropriate name for a word that sets a
bit in an I/O address identified with the name
SHUTTER.&medskip
......@@ -1697,25 +1692,25 @@ I'M HARRY
\end{Code}
\else
\begin{description}
\item[\forth{SHUTTER OPEN}]~
\item[\forth{shutter open}]~
\forth{OPEN} is the appropriate name for a word that sets a
bit in an I/O address identified with the name
\forth{SHUTTER}.
\item[\forth{3 BUTTON DOES IGNITION}]~
\item[\forth{3 button does ignition}]~
\forth{DOES} is a good choice for a word that vectors the
address of the function \forth{IGNITION} into a table of
functions, so that \forth{IGNITION} will be executed when
Button 3 is pushed.
\item[\forth{SAY HELLO}]~
\item[\forth{say hello}]~
\forth{SAY} is the perfect choice for vectoring \forth{HELLO} into an
execution variable. (When I first wrote this example
for Starting \Forth{}, I called it \forth{VERSION}. \person{Moore}
reviewed the manuscript and suggested \forth{SAY}, which is
clearly much better.)
\item[\forth{I'M HARRY}]~
\item[\forth{i'm harry}]~
The word \forth{I'M} seems more natural than \forth{LOGON HARRY},
\forth{LOGIN HARRY} or \forth{SESSION HARRY}, as often seen.
......@@ -1842,14 +1837,14 @@ But I suspect a hyphenated word of mixing two concepts.%
\end{interview}
Compare the following two strategies for saying the same thing:
\begin{Code}
ENABLE-LEFT-MOTOR LEFT MOTOR on
ENABLE-RIGHT-MOTOR RIGHT MOTOR on
DISABLE-LEFT-MOTOR LEFT MOTOR off
DISABLE-RIGHT-MOTOR RIGHT MOTOR off
ENABLE-LEFT-SOLENOID LEFT SOLENOID on
ENABLE-RIGHT-SOLENOID RIGHT SOLENOID on
DISABLE-LEFT-SOLENOID LEFT SOLENOID off
DISABLE-RIGHT-SOLENOID RIGHT SOLENOID off
enable-left-motor left motor on
enable-right-motor right motor on
disable-left-motor left motor off
disable-right-motor right motor off
enable-left-solenoid left solenoid on
enable-right-solenoid right solenoid on
disable-left-solenoid left solenoid off
disable-right-solenoid right solenoid off
\end{Code}
The syntax on the left requires eight dictionary entries; the syntax
on the right requires only six-and some of the words are likely to be
......@@ -1870,9 +1865,9 @@ factoring. The crime is similar to hyphenation, except that what
should be factored out is a number, not a word. A better factoring of
the above would be
\begin{Code}
1 CHANNEL
2 CHANNEL
3 CHANNEL
1 channel
2 channel
3 channel
\end{Code}
In this case, the three words were reduced to one.
......@@ -1881,7 +1876,7 @@ Often the bundling of names and numbers indicates fuzzy naming.
In the above case, more descriptive names might indicate the purpose
of the channels, as in
\begin{Code}
VOICE , TELEMETRY , GUITAR
voice , telemetry , guitar
\end{Code}
%% Note: AH: the commas be better left out here.
\index{B!Bundling of names and numbers|)}%
......@@ -1908,7 +1903,7 @@ convention extends to application words as well. If you have a
variable called \forth{DATE,} and you want a word that displays the
date, use the name
\begin{Code}
.DATE
.date
\end{Code}
\index{S!Suffixes|(}%
\index{P!Prefixes|(}%
......@@ -1933,11 +1928,11 @@ than to cram details of meaning into the name itself.
%Page 169 in first edition.
For instance, the phrase
\begin{Code}
... DONE IF CLOSE THEN ...
... done IF close THEN ...
\end{Code}
is just as readable as
\begin{Code}
... DONE? IF CLOSE THEN ...
... done? IF close THEN ...
\end{Code}
and cleaner as well. It is therefore preferable, unless we need an
additional word called \forth{DONE} (as a flag, for instance).
......@@ -1974,16 +1969,16 @@ One constant that pays for itself in most applications is
\forth{BL}\index{B!Blank space (BL)}
(the ASCII value for ``blank-space'').
The word \forthb{ASCII} is used primarily within colon definitions to
free you from having to know the literal value of an ASCII character.
For instance, instead of writing:
The word \forthb{[CHAR]} is used primarily within colon definitions to
free you from having to know the literal value of a character. For
instance, instead of writing:
\begin{Code}
: ( 41 word drop ; immediate
\end{Code}
where 41 is the ASCII representation for right-parenthesis, you can
write
\begin{Code}
: ( ASCII ) word drop ; immediate
: ( [char] ) word drop ; immediate
\end{Code}
\index{T!TRUE|(}%
\index{F!FALSE|(}%
......@@ -1993,11 +1988,11 @@ phrases such as
%Page 170 in first edition.
\begin{Code}
true 'STAMP? !
true 'stamp? !
\end{Code}
to set a flag or
\begin{Code}
false 'STAMP? !
false 'stamp? !
\end{Code}
to clear it.
......@@ -2013,11 +2008,11 @@ system), you can take this idea a step further and define:
\index{T!TRUE|)}\index{F!FALSE|)}\index{O!ON}\index{O!OFF}%
These words allow you to write:
\begin{Code}
'STAMP? on
'stamp? on
\end{Code}
or
\begin{Code}
'STAMP? off
'stamp? off
\end{Code}
Other names for these definitions include \forth{SET} and
\forth{RESET}, although \forth{SET} and \forth{RESET} most commonly
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment