Ansified chapter 5

\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,

\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}.

\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

\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

\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

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

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.'')

\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.

%! 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

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.

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}

\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.\\

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

\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|)}%

\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

``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

\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.

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.

\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}

\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)

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|)}%

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}

%%!!!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

\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.

\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

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.

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|)}%

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|(}%

%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).

\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|(}%

%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.

\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