cubed4th 2.0.20221024
: cubed4th 'PYTHON 'FORTH 'OOP + * 3 ^ ;
Requires Python: >=3.7

# -- THE FORTH-79 STANDARD --

The folling text was performed by OCR and contain mistakes.

# WORDS

NB: The words come from the FORTH-79 standard.  For the 2.0 release all the words that make sense will be implemented.  Its not currently noted anywhere which words have no implemention.

## Stack Manipulation

|   Name    |   Stack Effects   |   Description |
|   --------    | -------   | -------   |
|   DUP |   ( n - n n ) |   Duplicate top of stack  |
|   DROP    |   ( n - ) |   Discard Top of Stack    |
|   SWAP    |   ( n1 n2 - n2 n1 )   |   Exchange top two stack items    |
|   OVER    |   ( n1 n2 - n1 n2 n1 )    |   Make a copy of second item on top   |
|   ROT |   ( n1 n2 n3 - n2 n3 n1 ) |   Rotate third item to top "rote" |
|   [PICK](https://forth-standard.org/standard/core/PICK)   |   ( n1 - n2 ) |   Copy n1-th item to top (thus 1 PICK = DUP, 2 PICK = OVER)   |
|   ROLL    |   (n - )  |   Rotate the n1 - th item to top (thus 2 ROLL = SWAP, 3 ROLL = ROT    |
|   ?DUP    |   ( n - n (n) )   |   Dupliicate only if non-zero. "query-dup"    |
|   >R  |   ( n - ) |   Move top item to "return stack" for temporary storage (use caution). "to-r"     |
|   R>  |   ( - n ) |   Retrieve item from return stack. "r-from"   |
|   R@  |   ( - n ) |   Copy top of return stack onto stack. "r-fetch"  |
|   DEPTH   |   ( - n ) |   Count number of items in stack  |

# DEFINITIONS OF TERMS

These definitions, when in lower  case, are terms used within  this
Standard.  They present terms as specifically used within FORTH.

## A

### address, ~~byte~~ hashable object

An ~~unsigned  number~~ hashable object that locates an ~~8-bit byte~~ object in a  standard
~~FORTH  address space over {0..65,535}~~ Python dictionary.  ~~It  may   be a  native
machine address  or a representation  on  a  virtual  machine,
locating the  'addr-th' byte  within  the virtual byte address
space.~~  Address arithmetic is ~~modulo 65,536 without overflow~~ infinite positive, infinite negative and any string.

### address, compilation

The numerical  value  equivalent to a  FORTH word  definition,
which   is  compiled   for  that   definition.   The   address
interpreter  uses  this  value  to  locate  the  machine  code
corresponding to  each definition.   (May also  be called  the
code field address.)

### address, native machine

The natural address representation of the host computer.

### address, parameter field

The address of the first byte of memory associated with a word
definition  for the  storage of  compilation addresses  (in a
colon-definition), numeric data and text characters.

### arithmetic

~~All integer arithmetic is performed  with signed 16 or 32  bit
two's complement results, unless noted.~~  Numbers follow python rules
with integers being Decimal class, floating points being infinite procession
with support for complex numbers.  The to_number function shown here details
the various modes available to color4th:

```python

    def to_number(e, t, c, token):

        if not isinstance(token, str):
            return (True, token)

        if not token[0] in e.digits:
            return (False, None)

        if token in e.root.words or token in t.words:
            return (False, None)

        token = token.replace("_", "")

        base = t.base
        if token[0] == "#":
            token = token[1:]
        elif token[0] == "$":
            base = 16
            token = token[1:]
        elif token[0] == "%":
            base = 2
            token = token[1:]

        if token[0] == "-":
            if len(token) == 1:
                return (False, None)
            if not token[1].isdigit():
                return (False, None)

        if "j" in token:
            return (True, complex(token))
        else:
            if "." in token:
                if base == 10:
                    return (True, Decimal(token))
                else:
                    return (True, Decimal(int(token, base)))
            else:
                return (True, int(token, base))

```

## B

### block

The  unit  of  data from  mass  storage,  referenced by  block
number.  A  block must  contain 1024  bytes regardless  of the
minimum  data  unit  read/written  from  mass  storage.    The
translation from block number to device and physical record is
a function of the implementation.

### block buffer

A memory area where a mass storage block is maintained.

### byte

An assembly  of 8  bits.  In  reference to  memory, it  is the
storage capacity for 8 bits.

## C

### cell

A 16-bit memory  location.  The n-th  cell contains the  2n-th
and (2n+1)-th byte of the FORTH address space.  The byte order
is presently unspecified.

### character

A 7-bit  number which  represents a  terminal character.   The
ASCII character set is considered standard.  When contained in
a larger field, the higher order bits are zero.

### compilation

The action of accepting text  words from the input stream  and
placing   corresponding   compilation  addresses   in   a  new
dictionary entry.

## D

### defining word

A word that,  when executed, creates  a new dictionary  entry.
The new  word name  is taken  from the  input stream.   If the
input stream is exhausted before the new name is available, an
error condition exists.  Common defining words are:
:  CONSTANT  CREATE

### definition

See 'word definition'.

### dictionary

A structure of  word definitions  in  a computer memory.    In
systems with  a text  interpreter, the  dictionary entries are
organized in  vocabularies to  enable location  by name.   The
dictionary is extensible, growing toward high memory.

## E

### equivalent execution

For the  execution of  a standard  program, a  set of non-tine
dependent  inputs  will produce  the  same non-time  dependent
outputs on any FORTH Standard System with sufficient resources
to execute  the program.   Only standard  source code  will be
transportable.

### error condition

An exceptional condition which  requires action by the  system
other than the expected function.  Actions may be:

1.   ignore, and continue
2.   display a message
3.   execute a particular word
4.   interpret a block
5.   return control  to the text interpreter

A Standard System shall be  provided with a tabulation of  the
action  taken  for all  specified  error conditions.   General
error conditions:

1.   input stream exhausted before a required <name>.
2.   empty stack and full stack for the text interpreter.
3.   an unknown word, not a valid number for the text
interpreter.
4.   compilation of incorrectly nested conditionals.
5.   interpretation of words restricted to compilation.
6.   FORGETing within the system to a point that removes
a word required for correct execution.
7.   insufficient space remaining in the dictionary.

## F

### false

A zero number represents the false condition flag.

### flag

A number  that may have two logical states, zero and non-zero.
These  are  named  'true'  =  non-zero,  and  'false'  = zero.
Standard word definitions leave 1 for true, 0 for false.

## G

### glossary

A  set  of  word  definitions  given  in  a  natural  language
describing the corresponding computer execution action.

## H

## I

### immediate word

A  word  defined  to  automatically  execute  when encountered
during compilation, which handles exception cases to the usual
compilation.   See  IF LITERAL  ."  etc.

### input stream

A  sequence  of  characters  available  to  the  system,   for
processing  by  the   text  interpreter.   The   input  stream
conventionally may be taken from a terminal (via the  terminal
input buffer) and mass storage (via a block buffer).  >IN  and
BLK specify the input stream.  Words using or altering >IN and
BLK are responsible for  maintaining and restoring control  of
the input stream.

### interpreter, address

The (set of) word definitions which interprets (sequences  of)
FORTH compilation addresses  by executing the  word definition
specified for each one.

### interpreter, text

The (set of) word  definitions that repeatedly accepts  a word
name  from  the   input  stream,  locates   the  corresponding
dictionary  entry,  and  starts  the  address  interpreter  to
execute it.  Text in the input stream interpreted  as a number
leaves the corresponding  value on the   data stack.  When  in
the compile mode,  the addresses of  FORTH words are  compiled
into the  dictionary for  later interpretation  by the address
interpreter.  In this case, numbers are compiled, to be placed
on the data  stack when later  interpreted.  Numbers shall  be
accepted unsigned or negatively signed, according to BASE.

## J

## K

## L

### load

The  acceptance  of  text  from  a  mass  storage  device  and
execution   of  the   dictionary  definition   of  the   words
encountered.  This  is the  general method  for compilation of
new definitions into the dictionary.

## M

### mass storage

Data  is read  from mass  storage in  the form  of 1024  byte
blocks.  This data is  held in block buffers.   When indicated
as UPDATEd (modified) data will be ultimately written to  mass
storage.

## N

### number

When  values exist within a larger field, the high order  bits
are zero.  When stored in memory the byte order of a number is
unspecified.

### type range    minimum field

    bit  0..1  1
    character 0..1277
    byte 0..2558
    number    -32,768..32,76716
    positive number0..32,767 16
    unsigned numberO..65,535 16
    double number  -2,147,483,648..
       2,147,483,647    32
    positive double number   0..2,147,483,647    32
    unsigned double number   0..4,294,967,295    32

When represented on the stack, the higher 16-bits (with  sign)
of a double  number are most  accessible.  When in  memory the
higher 16-bits are at the lower address.  Storage extends over
four bytes toward high memory.  The byte order within each  16
-bit field is unspecified.

## O

### output, pictured

The use of numeric output primitives, which convert  numerical
values  into  text  strings.   The operators  are  used  in  a
sequence  which resembles a symbolic 'picture' of the  desired
text  format.    Conversion proceeds from low digit  to  high,
from high memory to low.

## P

### program

A  complete specification of execution to achieve  a  specific
function  (application  task) expressed in FORTH  source  code
form.

## Q

## R

### return

The   means  of  terminating  text  from  the  input   stream.
(Conventionally a null (ASCII 0) indicates end of text in  the
input  stream.   This character is left by  the  'return'  key
actuation  of the operator's terminal, as an absolute  stopper
to text interpretation.)

## S

### screen

Textual data  arranged for  editing.  By  convention, a screen
consists of  16 lines  (numbered 0  thru 15)  of 64 characters
each.  Screens usually contain program source text, but may be
used to view mass storage data.   The first  byte of  a screen
occupies the first byte of a mass storage block,  which is the
beginning point for text interpretation during a load.

### source definition

Text consisting of  word names suitable  for execution by  the
text interpreter.   Such text  is usually  arranged in screens
and maintained on a mass storage device.

### stack, data

A last in, first out list consisting of 16-bit binary  values.
This  stack  is  primarily used to  hold  intermediate  values
during  execution  of  word  definitions.   Stack  values  may
represent numbers, characters, addresses, boolean values, etc.

When the name 'stack' is used, it implies the data stack.

### stack, return

A last in, first out list which contains the machine addresses
of word definitions whose execution has not been completed  by
the address interpreter.  As a word definition passes  control
to  another  definition,  the return point is  placed  on  the
return stack.

The return stack may cautiously be used for other values, such
as   loop   control   parameters,   and   for   pointers   for
interpretation of text.

### string

A sequence of 8-bit bytes containing ASCII characters, located
in memory by an initial byte address and byte count.

## T

### transportability

This  term indicates that equivalent execution results when  a
program  is executed on other than the system on which it  was
created.  See 'equivalent execution'.

### true

A non-zero value represents the true condition flag.  Any non-
zero value will be accepted by a standard word as 'true';  all
standard words return one when leaving a ' true' flag.

## Q

## R

## S

## T

## U

### user area

An  area  in  memory  which  contains  the  storage  for  user
variables.

### variables, user

So  that the words of the FORTH vocabulary may  be  re-entrant
(to  different  users),  a copy of  each  system  variable  is
maintained in the user area.

## V

### vocabulary

An ordered list of word definitions.  Vocabulary lists are  an
advantage in reducing dictionary search time and in separating
different word definitions that may carry the sane name.

## W

### word

A sequence of characters terminated by at least one blank  (or
'return').   Words are usually obtained via the input  stream,
from a terminal or mass storage device.

### word definition

A   named   FORTH  execution  procedure  compiled   into   the
dictionary.  Its execution may be defined in terms of  machine
code, as a sequence of compilation addresses or other compiled
words.   If named, it nay be located by specifying  this  name
and the vocabulary in which it is located.

### word name

The  name  of  a  word definition.   Standard  names  must  be
distinguished by their length and first thirty-one characters,
and may not contain an ASCII null, blank, or 'return'.

### word set

A   group   of  FORTH  word  definitions  listed   by   common
characteristics.  The standard word sets consist of:

    Required Word Set
    Nucleus Words
    Interpreter Words
    Compiler Words
    Device Words

    Extension Word Sets
    32-bit Word Set
    Assembler Ward Set

Included as reference material only:
Reference Word Set

### word set, compiler

Words  which  add  new procedures to  the  dictionary  or  aid
compilation by adding compilation addresses or data structures
to the dictionary.

### word set, devices

Words  which  allow  access  to  mass  storage  and   computer
peripheral devices.

### word set, interpreter

Words  which  support  interpretation of text  input  from   a
terminal  or  mass  storage  by  execution  of   corresponding
dictionary entries, vocabularies, and terminal output.

### word set, nucleus

The FORTH words generally defined in machine  code that create
the  stacks  and fundamental stack  operators  (virtual  FORTH
machine).

### word set, reference

This set of words is provided as a reference document only, as
a  set of formerly standardized words and candidate words  for
standardization.

### word set, required

The  minimum words needed to compile and execute all  Standard
Programs.

### word, standard

A  named  FORTH procedure definition, formally   reviewed  and
accepted  by the Standards Team.  A serial  number  identifier
{100..999} indicates a Standard Word.  A functional alteration
of  a  Standard Word will require assignment of a  new  serial
number identifier.

The  serial number identifier has no required use, other  than
to  correlate  the definition name with  its  unique  Standard
definition.


## X

## Y

## Z









The MIT License (MIT)
=====================

Copyright (c) 2021 - 2021, Scott.McCallum@Snoware.enterprises

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.