This file explains the format of word descriptions in the other files in this directory. A brief description of the functionality of each word set is also given.
Files in This Directory _______________________________________________________
This directory contains the semantic description of all the words provided in the AForth kernel or supplied as include files to be included by the words 'INCLUDED' or 'INCLUDE-FILE'. The files are:
!ReadMe1st
This file is the one you are reading now. It explains the format of word descriptions used in the other files in this directory.
Words
List of all words included in AForth and the ANS standard.
Core
Semantics for the Core and Core Extensions word sets. These word sets include the words most commonly used in applications.
Error
Semantics for the Error handling word set. Description of structured error handling of AForth and explanation of error messages, their meaning and when to expect them.
File
Semantics for the File Access and File Access Extensions word sets. These word sets handles all about sequential and random access files.
Memory
Semantics for the Memory Allocation word set. This word set offers dynamic memory allocation and deallocation.
Search
Semantics for the Search Order word set. This word set handles all about word lists and search orders. Only the more advanced user/programmer will ever need this.
String
Semantics for the String handling word set. In this release of AForth, only a single word is present from this word set, namely 'COMPARE'.
Toolkit
Semantics for the Programming Tools word set. This word set provides simple debugging facilities and programming aids.
RISCOS
Semantics for the non-standard words, which are supplied to ease the use of Forth with RISC-OS. This word set provides support for SWI calls, the CLI and control of ESCAPES in order to enable multi-tasking in the Wimp.
Graphics
Semantics for the Graphics word set which is supplied as source file. The Graphics word set covers about the same graphics functionality as provided by ARM BBC BASIC.
Format of Word Semantic Descriptions __________________________________________
A semantic description of a word means: what the word does when executed or compiled, ie. a description of a command.
Each word description starts with a header containing: the name in upper case letters, the name of the wordset the word belongs to, the word attributes and finally a stack diagram.
The word name is self-explanatory. The stack parameters are given as described below in the section 'Stack Notation'. The word set designator shows which word set the word belongs to. It can be one of the following:
Core Core word set
Double Double number word set
File File Access word set
Toolkit Programmers Toolkit word set
Search Search order word set
String String handling word set
Memory Memory allocation word set
Error Error handling word set
Float Floating-point word set
If "Ext" is appended to the word set designator, it means that the word is from the corresponding Extension word set.
The word attributes signifies any special behaviour of the word. It can be either 'C', meaning that it's a compile only word and thus only can be used in a definition, or it can be 'D' meaning that the word is a defining word, and thus compiles a new definition when executed.
After the header comes a textual explanation of the word's behaviour. If the word has different behaviour in execute and compile mode, the explanation is split in two sections, each preceeded by 'Execution:' or 'Compilation:' respectively. Some few words have also a seperate entry for interpretation mode, ie. what the word does when input at the Forth prompt.
--------------
Stack Notation
--------------
Stack parameters are described via stack diagrams that look like this:
( before -- after )
The "before" parameters are those the word expects on the stack when executed. The "after" corresponds to the values left on the stack after execution of the word. The right most value are the last number pushed on the stack, ie. we say it is the item on top of the stack or the value last pushed onto the stack. If no specific stack is mentioned, the data stack is implied. Sometimes the data stack is also called the parameter stack.
If the return stack is used, the stack diagram is amended to look like this:
( R: before -- after )
If the Floating point stack is used in looks like this:
( F: before -- after )
The following list shows the abbreviations used in stack parameter diagrams. It also gives the data type and its value range in the AForth implementation.
In AForth c-addr and addr are synonyms for any address. a-addr means an aligned address.
------------------------
Text Input Abbreviations
------------------------
Some words require a text string to follow the word in the input stream. This action is represented by including the following notation in a stack diagram:
<char> A delimiting character, marking the end of the stream being parsed.
<eol> Delimiter, marking the end of line. In AForth the end of line
characters are any of the ASCII characters 0, 10 or 13.
<blank> A space, or any control character in the ASCII range 0..31
<blanks> One or more <blank>s.
ccc A sequence of arbitrary characters, parsed from the input stream.
name A word name parsed from the input stream.
-----------------------
Data Type Compatability
-----------------------
Data type compatability is a new concept introduced by the ANS standard. It defines the level of portability expected from a program and should therefore possess no significance to the casual user.
The following table represents how the data types are related to each other in respect of subtypes, ie. which data types are a subset of other data types. A chain rule applies to data type compatability such that, if datatype x is a subtype of y and y is a subtype of z then x is also a subtype of z.
char -> +n -> w
+n -> n -> w
+n -> u -> w
flag -> mask -> w
a-addr -> c-addr -> addr -> u -> w
+d -> d -> wd
+d -> ud -> wd
It should be noted that the Forth compiler performs no data type checking whatsoever, so care should be taken. The table should be applied to any program meant to be portable.
