ANEW --TOOLGLOS--                             \  Wil Baden  2003-02-08

\  *******************************************************************
\  *                                                                 *
\  *  Wil Baden  2003-02-08                                          *
\  *                                                                 *
\  *                        Toolbelt Glossary                        *
\  *                                                                 *
\  *   !+             BL-Skip        HIWORD         SKIP             *
\  *   !++            BOUNDS         HUNT           SPLIT            *
\  *   #BACKSPACE-CHAR               Is-Alnum       Split-Next-Line  *
\  *   #Chars/Line    BUFFER:        Is-Alpha       SPLIT[           *
\  *   #EOL-CHAR      C!++           Is-Digit       STARTS?          *
\  *   #TAB-CHAR      C#             Is-Lower       STRING,          *
\  *   'th            C+!            Is-Upper       String->Lower    *
\  *   (.)            C@++           Is-White       String->Upper    *
\  *   ++             CELL           JOIN           STRING/          *
\  *   ,"             CELL-          LEXEME         TEMP             *
\  *   -CELL          Char>Lower     LOWORD         th-Word          *
\  *   .LOWER         Char>Upper     MAX-N          th-Word-Back     *
\  *   .UPPER         CHOP           Memory-Check   th-Word-Forward  *
\  *   /COUNTED-STRING               Next-Word      THIRD            *
\  *   /PAD           COMPARE(NC)    NOT            TIMER            *
\  *   /SPLIT         CONTAINS?      OFF            TRIM             *
\  *   2NIP           COUNTER        OFFSET:        UNDER+           *
\  *   3DROP          EMPTY          ON             View-Next-Line   *
\  *   3DUP           END-C@         ORIF           VOCABULARY       *
\  *   @+             End-Word       OUT            [DEFINED]        *
\  *   @++            ENDS?          PLACE          [UNDEFINED]      *
\  *   ADDRESS-UNIT-BITS             POSSIBLY       [VOID]           *
\  *   ANDIF          ENUM           R'@            \\               *
\  *   ANEW           EQUALS?        Replace-Char                    *
\  *   APPEND         EXPIRED        REWIND-FILE                     *
\  *   Append-Char    File-Check     SCAN                            *
\  *   BACK           FLAG           SCAN[                           *
\  *   BACK[          FOURTH         SIGN-BIT                        *
\  *   BL-Scan        H#             SIMILAR?                        *
\  *                                                                 *
\  *******************************************************************

\\ ***************************  GLOSSARY  ****************************

!+                                                              COMMON
   Use `!++`.

!++                          ( addr n -- addr+cell )            COMMON
   Store _n_ as the contents of _addr_, and increment _addr_ by
   cell size.  `OVER !  CELL+`

#BACKSPACE-CHAR               ( -- n )                          COMMON
   The backspace character.  "the backspace character"

#Chars/Line                   ( -- n )                        TOOL2002
   Preferred width of line in text files.  User defined and
   changeable.  "number of characters for each line"

#EOL-CHAR                     ( -- char )                     TOOL2002
   The end-of-line character. 13 for Mac and DOS, 10 for Unix.
   "the end-of-line character"

#TAB-CHAR                    ( -- n )                           COMMON
   The tab character,  9.  "the tab character"

'th                          ( n "addr" -- &addr[n] )         TOOL2002
   The address `_n_ CELLS _addr_ +`.

(.)                             ( n -- str len )              TOOL2002
   Convert number to string.

++                         ( addr -- )  [Not used]              COMMON
   Add 1 at _addr_.  "increment"

,"                           ( "<ccc><quote>" -- )            TOOL2002
   Store a quote-delimited string in data space as a counted string.
   See file QUOT2002

-CELL                        ( -- n )   [Not used]              COMMON
   Negative of address units in a cell.

.LOWER                       ( str /str -- )                  CHARCASE
   Display in lowercase.

.UPPER                       ( str /str -- )                  CHARCASE
   Display in uppercase.

/COUNTED-STRING          ( -- n )                               COMMON
   Maximum size of a counted string, in characters.

/PAD                         ( -- n )                           COMMON
   Size of the scratch area pointed to by `PAD`, in characters.

/SPLIT                                                        CHARSCAN
   Synonym of `CHOP`.  For backward compatibility.

2NIP                         ( w x y z -- y z )               TOOL2002
   Drop the third and fourth elements from the stack.

3DROP                        ( x y z -- )                     TOOL2002
   Drop the top three elements from the stack.

3DUP                         ( x y z -- x y z x y z )         TOOL2002
   Copy top three elements on the stack onto top of stack.

@+                                                              COMMON
   Use `@+`.

@++                         ( addr -- addr+cell n )             COMMON
   Copy contents of _addr_ onto stack, and increment _addr_ by cell
   size.  `DUP CELL+ SWAP  @`

ADDRESS-UNIT-BITS            ( -- n )                           COMMON
   Size of one address unit, in bits.

ANDIF                           ( p "... THEN" -- flag )      TOOL2002
   Given `p ANDIF q THEN`:
   If _p_ is 0 then test _q_ will not be performed and the result
   will be _p_, i.e. 0;
   If _p_ is not 0 then the result will be _q_.

ANEW                            ( "name" -- )( Run: -- )      TOOL2002
   Compiler directive used in the form: `ANEW _name_`. If the word
   _name_ already exists, it and all subsequent words are
   forgotten from the current dictionary, then a `MARKER` word
   _name_ is created. This is usually placed at the start of a
   file. When the code is reloaded, any prior version is
   automatically pruned from the dictionary.
   Executing _name_ will also cause it to be forgotten, since
   it is a `MARKER` word.
   Useful implementation factor of `EMPTY`.

APPEND                       ( str len addr -- )              TOOL2002
   Catenate the string at _str_, whose length is _len_, to the
   counted string already existing at _addr_.  Does not check
   whether space is allocated for the final string.  AKA `+PLACE`.

Append-Char                ( char addr -- )                     COMMON
   Append _char_ at the end of counted string _addr_, incrementing
   the count at _addr_.

BACK                      ( str /str char -- str /str-i )     CHARSCAN
   Scan for given _char_ from back to front.

BACK[ char-test ]BACK                                         CHARSCAN
   Scan with _char-test_ from back to front.

BL-Scan                                                         COMMON
   Use `BL SCAN`.

BL-Skip                                                         COMMON
   Use `BL SKIP`.

BOUNDS                       ( str len -- str+len str )       TOOL2002
   Convert _str len_ to range for DO-loop.

BUFFER:                      ( n "name" -- )                  TOOL2002
   Create buffer _name_ of length _n_ in data space.

C!++                          ( addr n -- addr+cell )           COMMON
   Store _n_ as the character at _addr_, and increment _addr_ by
   character size.  `OVER C!  CHAR+`

C#                           ( -- addr )                      TOOL2002
   Variable for character count.  Should be updated by `CR`, `EMIT`,
   `TYPE`, etc.

C+!                          ( n addr -- )                    TOOL2002
   Add the low-order byte of _n_ to the byte at _addr_, removing
   both from the stack.

C@++                         ( addr -- addr+cell n )            COMMON
   Copy the character at _addr_ onto stack, and increment _addr_ by
   character size.  `DUP CHAR+ SWAP  C@`

CELL                         ( -- n )   [Not used]              COMMON
   Address units (i.e. bytes) in a cell.

CELL-                        ( addr -- addr' )                  COMMON
   Decrement address by one cell.  `1 CELLS -`

Char>Lower                   ( c -- C )                       CHARCASE
   Convert character to lowercase.

Char>Upper                   ( c -- C )                       CHARCASE
   Convert character to uppercase.  Uses `Uppercase-Map`.

CHOP                 ( a m a+i m-i -- a+i m-i a i )           CHARSCAN
   Chop a character string _a m_ at place given by _a+i m-i_.

COMPARE(NC)           ( str1 len1 str2 len2 -- flag )         CHARCASE
   Case insensitive comparison of two strings.  Returns -1, 0,
   or 1.  AKA `ICOMPARE` in VFX.  Uses `Char>Upper`.

CONTAINS?  ( str_1 /str_1 str_2 /str_2 -- str_1 /str_1 flag )  CHARSCAN
   Test that _str_1_ contains _str_2_.

COUNTER                      ( -- ms )                        TOOL2002
   Return the current value of the millisecond timer.

EMPTY                        ( -- )                           TOOL2002
   Reset the dictionary to a predefined golden state, discarding
   all definitions and releasing all allocated data space beyond
   that state.
   This `EMPTY` uses `--EMPTY--` to separate kernel words and
   user words.  Rename `--EMPTY--` if you wish.
   `MARKER --EMPTY--` will setup a new golden area for `EMPTY`.
   `--EMPTY--` will restore the previous golden area.

END-C@                    ( str /str -- char )                CHARSCAN
   The last character of _str /str_.

End-Word       ( str /str -- str+i /str-i )                   CHARSCAN
   The last word in a string after trimming.

ENDS?      ( str /str ending /ending -- str /str flag )       CHARSCAN
   Check end of string.

ENUM                         ( n1 "name" -- n2 )                COMMON
    Define name as a constant with value n1, then increment n1 to
    return n2. Useful for defining a sequential list of constants.

EQUALS?            ( str /str pat /pat -- str /str flag )     CHARSCAN
   Check for the string equal to the pattern.

EXPIRED                      ( u -- flag )                    TOOL2002
   Return true if the current millisecond timer reading has passed
   _u_.

File-Check                   ( n -- )                         TOOL2002
   Check for file access error.

FLAG                         ( -- addr )                      TOOL2002
   Promiscuous variable available in any task.

FOURTH                       ( w x y z -- w x y z w )         TOOL2002
   Copy fourth element on the stack onto top of stack.

H#                           ( "hexnumber" -- n )             TOOL2002
   Get the next word in the input stream as an unsigned hex
   single-number literal. (Adopted from Open Firmware.)
   "The best way to manage BASE is to establish a global default,
   e.g. DECIMAL. If you change to another, e.g. HEX, you assume
   responsibility for changing back when you're done with it. The
   scope of a changed region can be part of a file or all of a
   file, but shouldn't span files. Always return to your default
   at the end of a file _if_ you've changed it. This minimizes
   fussy saving & restoring, and you always know where you are."
   -- Elizabeth D. Rather

HIWORD                       ( hilo -- hi )                     COMMON
   The high part of the word.  `16 RSHIFT`

HUNT           ( str /str pat /pat -- str+I /str-i )          CHARSCAN
   Scan for a string, _pat /pat_, rather than a character. The
   result is like the other scanning functions, and can be
   used with `2dup` and `CHOP` to split a line.

Is-Alnum                     ( char -- flag )                 CHARCASE
   Test _char_ for alphanumeric.

Is-Alpha                     ( char -- flag )                 CHARCASE
   Test for alphabetic.

Is-Digit                     ( char -- flag )                 CHARCASE
   Test _char_ for digit.

Is-Lower                     ( char -- flag )                 CHARCASE
   Test for lowercase letter.

Is-Upper                     ( char -- flag )                 CHARCASE
   Test for uppercase letter.

Is-White                     ( char -- flag )                 TOOL2002
   Test _char_ for white space.  Any character with value
   less than 33 is taken as white space.

JOIN          ( str_1 /str_1 str_2 /str_2 -- str_3 /str_3)    CHARSCAN
   Join _str_1_ . then _str_2_.

LEXEME                       ( "name" -- str len )  [Not used]  COMMON
   Get the next word on the line as a character string. If it's a
   single character, use it as the delimiter to get a string. This
   function has been replaced by `BL WORD COUNT Check-Quote`,
   `PARSE-WORD Check-Quote`, and `Next-Word Check-Quote`.

LOWORD                       ( hilo -- lo )                     COMMON
   The low part of the word.  `H# FFFF AND`

MAX-N                                                           COMMON
   The largest usable signed integer. `H# 7FFFFFFF`

Memory-Check                 ( n -- )                         TOOL2002
   Check for memory allocation error.

Next-Word                    ( -- str len )                   TOOL2002
   Get the next word in the input stream as a character string -
   extending the search across line breaks as necessary, until the
   end-of-file is reached - and return its address and length.
   Returns a string length of 0 at the end of the file.

NOT                          ( x -- flag )                    TOOL2002
   Identical to `0=`, used for program clarity to reverse the
   result of a previous test.  It should used only when `0=` as
   well as `INVERT` could take its place.

OFF                          ( addr  -- )                     TOOL2002
   Set the flag at _addr_ to true.  Already defined in many
   implementations.

OFFSET:               ( n "name" -- )( Run: addr -- addr+n )  TOOL2002
   Field-defining word.  Creates a word which adds a constant to
   the number (usually an address) on top of the stack.  Used  in
   the form  _n OFFSET: <fieldname>_  to create a field definition
   <fieldname>.  AKA `FIELD`.  (`FIELD` has been given other
   conflicting definitions, so `OFFSET:` hopes to avoid conflict.)

ON                           ( addr -- )                      TOOL2002
   Set the flag at _addr_ to false.  Already defined in many
   implementations.

ORIF                            ( p "... THEN" -- flag )      TOOL2002
   Given `p ORIF q THEN`: If _p_ is 0 then the result will be _q_;
   If _p_ is not 0 then test _q_ will not be performed and the
   result will be _p_.

OUT                          ( -- addr )                      TOOL2002
   Promiscuous variable available in any task.

PLACE                        ( str len addr -- )              TOOL2002
   Copy the string at _str_, whose length is _len_, to _addr_,
   formatting it as a counted string, i.e., the length is in the
   first byte.  Does not check whether space is allocated for the
   final string.

POSSIBLY                        ( "name" -- )                 TOOL2002
   Execute _name_ if it exists; otherwise, do nothing. Useful
   implementation factor of `ANEW`.

R'@                          ( -- x )( R: x y -- x y )        TOOL2002
   The second element on the return stack.

Replace-Char                  ( str /str char char_2 -- )     CHARSCAN
   Replace each occurrence of _char_ with _char_2_.

REWIND-FILE                  ( file-id -- ior )               TOOL2002
   Reposition the file at its beginning.

SCAN      ( str str+i len-i )                                 CHARSCAN
   Look for a particular character in the specified string.
   BL is treated as any white space.

SCAN[ char-test ]SCAN          ( str len -- str+i len-i )     CHARSCAN
   Look for a character that satisfies _char-test_ in the
   specified string

SIGN-BIT                                                        COMMON
   Mask for the sign bit of a number. `H# 80000000`.

SIMILAR?           ( str /str pat /pat -- str /str flag )     CHARSCAN
   Check for the string equal to the pattern ignoring case.

SKIP      ( str len char -- str+i len-i )                     CHARSCAN
   Advance past leading occurrences of a particular character.
   BL is treated as any white space.

SPLIT        ( str /str char -- str+i /str-i str i )          CHARSCAN
   Divide a string at a given character. The first part of the
   string is on top, the remaining part is underneath. The
   remaining part begins with the scanned-for character.

Split-Next-Line                                                 COMMON
   Function common to line filters and `SLURP.  It is not a general
   tool.

SPLIT[ char-test ]SPLIT  ( str /str char -- str+i /str-i str i )  CHARSCAN
   Divide a string at a character satisfying _char-test_.
   The first part of the  string is on top, the remaining part
   is underneath. The remaining part begins with the character
   satisfying _char-test_.

STARTS?    ( str /str start /start -- str /str flag )         CHARSCAN
   Check start of string.

STRING,                      ( str len -- )                   TOOL2002
   Store a string in data space as a counted string.

String->Lower                ( str len -- )                   CHARCASE
   Convert string into lowercase.

String->Upper                ( str len -- )                   CHARCASE
   Convert string into uppercase.

STRING/            ( str /str i -- str+/str-i i )             CHARSCAN
   Get ending characters.

TEMP                         ( -- addr )                      TOOL2002
   Promiscuous variable available in any task.

th-Word                  ( str /str n -- str+i /str-i )       CHARSCAN
   The _n_th white-space delimited substring of _str len_.

th-Word-Back             ( str /str n -- str /str-i )         CHARSCAN
   All before the _n_th white-space delimited substring of
   _str /str_

th-Word-Forward          ( str /str n -- str+i /str-i )       CHARSCAN
   The _n_th white-space delimited substring of _str len_ and
   what follows it.

THIRD                        ( x y z -- x y z x )             TOOL2002
   Copy third element on the stack onto top of stack.

TIMER                        ( u -- )                         TOOL2002
   Repeat COUNTER, then subtract the two values and display the
   interval between the two in milliseconds.

TRIM                     ( str /str -- str /str-i )           CHARSCAN
   Remove white space from the end of a string by changing
   the count of the string.
   To remove white space from the start of a string, use `BL SKIP`.

UNDER+                       ( x y z -- x+z y )                 COMMON
   Add value to the number just under the top stack item. (_Thinking
   Forth_, p. 171)

View-Next-Line                                                  COMMON
   Function common to line filters and `SLURP.  It is not a general
   tool.

VOCABULARY                   ( "name" -- )                    TOOL2002
   Create a word list _name_. Subsequent execution of _name_
   replaces the first word list in the search order with _name_.
   When _name_ is made the compilation word list, new definitions
   will be added to _name_'s list.

[DEFINED]                    ( "name" -- flag )               TOOL2002
   Search the dictionary for _name_. If _name_ is found, return
   TRUE; otherwise return FALSE. Immediate for use in definitions.

[UNDEFINED]                  ( "name" -- flag )               TOOL2002
   Search the dictionary for _name_. If _name_ is found, return
   FALSE; otherwise return TRUE. Immediate for use in definitions.

[VOID]                       ( -- false )                       COMMON
   Immediate FALSE.  Immediate so it can comment out sections of code
   within definitions.

\\                           ( "...<eof>" -- )                TOOL2002
   During an INCLUDE operation, treat anything following this word
   as a comment; i.e., nothing after `\\` is interpreted in a
   source file will be interpreted or compiled.

\\   //   \\   //   \\   //   \\   //   \\   //   \\   //   \\   //   \\