ci86.lina64.html 5.4.1 Manual

# ci86.lina64.html Version [ 5.4.1 ] GLOSSARY

# GLOSSARY INDEX

Here you can select the glossary entry of a word. All words in the basic set are documented. This is for reference. If you don't understand ciforth concepts (printed in italics), you have to look them up in the concept index of the real manual, either printed, PostScript or pdf. (Info won't do, it lacks indices or content overview).

!CSP ! #> #BUFF #S # $!-BD $! $+! $, $/ $@ $C+ $\ $^ <# <> < ' (+LOOP) (;) (;CODE) (>IN) (?DO) (ABORT") (ACCEPT) (BACK (BLK) (BUFFER) (CREATE) (D.R) (DO) (FIND) (FORWARD (LINE) (NUMBER) */MOD */ * +! +BUF +LOOP +ORIGIN + , --> -TRAILING - ." .( .R .SIGNON .S . /MOD / 0< 0= 0BRANCH 0 1+ 1- 2! 2* 2, 2/ 2@ 2DROP 2DUP 2OVER 2SWAP ; = >BODY >CFA >DFA >FFA >LFA >NFA >NUMBER >PHA >R >SFA >VFA >WID >XFA > ?BLANK ?COMP ?CSP ?DELIM ?DISK-ERROR ?DO ?DUP ?ERROR ?ERRUR ?EXEC ?LOADING ?PAIRS ?STACK ? @ ABORT" ABORT ABS ACCEPT AGAIN ALIGNED ALIGN ALLOT ALSO AND ARGS ASSEMBLER B/BUF BACK) BASE BEGIN BLANK BLK BLOCK-EXIT BLOCK-FILE BLOCK-HANDLE BLOCK-INIT BLOCK-READ BLOCK-SEEK BLOCK-WRITE BLOCK BL BM BODY> BRANCH BYE C! C, C/L C@ CATCH CELL+ CELLS CHAR+ CHARS CHAR CLOSE-FILE CLS CMOVE COLD CONSTANT CONTEXT CORA CORE COUNT CO CPU CREATE-FILE CREATE CR CSP CURRENT D+ D.R D. DABS DATA DECIMAL DEFINITIONS DELETE-FILE DEPTH DIGIT DISK-ERROR DLITERAL DNEGATE DOES> DO DPL DP DROP DSP! DSP@ DUP ECL ELSE EMIT EMPTY-BUFFERS EM ENVIRONMENT? ENVIRONMENT ERASE ERROR ERRSCR ETYPE EVALUATE EXECUTE EXIT-CODE EXIT FENCE FILE-POSITION FILL FIND FLD FLUSH FM/MOD FOR-VOCS FOR-WORDS FORGET-VOC FORGET FORTH FORWARD) FOUND GET-FILE HANDLER HEADER HERE HEX HIDDEN HLD HOLD ID. IF IMMEDIATE INCLUDED INCLUDE INDEX INTERPRET INVERT I J KEY? KEY L! L@ LATEST LEAVE LINK LIST LITERAL LIT LOAD LOCK LOOP LSHIFT M* M/MOD MAX-USER MAX MESSAGE MIN MOD MOVE MS NAMESPACE NAME NAME NEGATE NIP NOOP NUMBER Number_1 Number_2 OFFSET OK ONLY OPEN-FILE OPTIONS OPT OR OUT OVER PAD PARSE PC! PC@ POSTPONE PP@@ PP PREFIX PRESENT PREVIOUS PUT-FILE PW! PW@ Prefix_" Prefix_& Prefix_+ Prefix_- Prefix_0 Prefix_7 Prefix_B Prefix_TICK Prefix_^ QUIT R# R0 R> R@ RDROP READ-FILE RECURSE REFILL-TIB REMAINDER REPEAT REPOSITION-FILE RESTORE-INPUT RESTORE ROT RSHIFT RSP! RSP@ RUBOUT RW-BUFFER S" S0 S>D SAVE-INPUT SAVE SCR SDLITERAL SET-SRC SET-TERM SHELL SIGN SKIP SM/REM SOURCE SPACES SPACE SRC STATE SUPPLIER SWAP SYSTEM TASK-SIZE TASK TERMIO THEN THROW THRU TIB TOGGLE TRIAD TYPE U< U. U0 UDM/MOD UM* UM/MOD UNLOCK UNLOOP UNTIL UPDATE USER VARIABLE VERSION VOC-LINK WARM WARNING WHERE WHILE WITHIN WORDLIST WORDS WORD WRITE-FILE XOR XOS5 XOS ZEN ['] [CHAR] [COMPILE] [ \ ] _FIRST _INIT _LIMIT _PREV _left_parenthesis_ _ colon ~MATCH

# GLOSSARY INDEX BY WORDSET

Here you can select the description of a Wordsets: small sets of words that work together. These are intended to give more insight in how to use the words in cooperation.

Note: the first reference under `see also' of a word is the wordset to which it belongs.

SCREEN MULTIPLYING BLOCKS WORDLISTS PARSING LIBRARY SUPERFLUOUS COMPILING CONTROL DEFINING DENOTATIONS DICTIONARY DOUBLE ENVIRONMENTS ERRORS FILES FORMATTING INITIALISATIONS INPUT JUGGLING LOGIC MEMORY MISC OPERATINGSYSTEM OPERATOR OUTPUT SECURITY STACKS STRING

#### WORDSET BLOCKS

- OVERVIEW OF BLOCKS
- #BUFF
- -->
- ?DISK-ERROR
- B/BUF
- BLOCK-EXIT
- BLOCK-FILE
- BLOCK-HANDLE
- BLOCK-INIT
- BLOCK-READ
- BLOCK-WRITE
- BLOCK
- DISK-ERROR
- EMPTY-BUFFERS
- UPDATE
- (BUFFER)
- +BUF
- BLOCK-SEEK
- FLUSH
- OFFSET
- _FIRST
- _LIMIT
- _PREV

#### WORDSET COMPILING

- OVERVIEW OF COMPILING
- DLITERAL
- LITERAL
- POSTPONE
- [COMPILE]
- LIT
- SDLITERAL

#### WORDSET CONTROL

- OVERVIEW OF CONTROL
- +LOOP
- ?DO
- AGAIN
- BEGIN
- CO
- DO
- ELSE
- EXIT
- IF
- I
- J
- LEAVE
- LOOP
- RECURSE
- REPEAT
- SKIP
- THEN
- UNLOOP
- UNTIL
- WHILE
- (+LOOP)
- (;)
- (?DO)
- (BACK
- (DO)
- (FORWARD
- 0BRANCH
- BACK)
- BRANCH
- FORWARD)

#### WORDSET DEFINING

- OVERVIEW OF DEFINING
- ;
- CONSTANT
- CREATE
- DATA
- DOES>
- MAX-USER
- NAMESPACE
- USER
- VARIABLE
- WORDLIST
- colon
- (;CODE)
- (CREATE)
- HEADER
- LINK

#### WORDSET DENOTATIONS

- OVERVIEW OF DENOTATIONS
- Prefix_"
- Prefix_&
- Prefix_+
- Prefix_-
- Prefix_0
- Prefix_7
- Prefix_B
- Prefix_TICK
- Prefix_^

#### WORDSET DICTIONARY

- OVERVIEW OF DICTIONARY
- '
- ,
- 2,
- >BODY
- ALLOT
- BODY>
- C,
- DP
- FIND
- FORGET
- FOUND
- HERE
- ID.
- IMMEDIATE
- PAD
- PREFIX
- PRESENT
- WORDS
- [']
- (FIND)
- >CFA
- >DFA
- >FFA
- >LFA
- >NFA
- >PHA
- >SFA
- >VFA
- >WID
- >XFA
- FENCE
- FOR-VOCS
- FOR-WORDS
- FORGET-VOC
- HIDDEN
- OPT
- ~MATCH

#### WORDSET DOUBLE

- OVERVIEW OF DOUBLE
- D+
- DABS
- DNEGATE
- S>D

#### WORDSET ENVIRONMENTS

- OVERVIEW OF ENVIRONMENTS
- CORE
- CPU
- ENVIRONMENT?
- NAME
- SUPPLIER
- VERSION

#### WORDSET ERRORS

- OVERVIEW OF ERRORS
- ?ERROR
- ?ERRUR
- ABORT"
- CATCH
- ERROR
- ERRSCR
- MESSAGE
- THROW
- WARNING
- WHERE
- (ABORT")
- HANDLER

#### WORDSET FILES

- OVERVIEW OF FILES
- CLOSE-FILE
- CREATE-FILE
- DELETE-FILE
- FILE-POSITION
- GET-FILE
- INCLUDED
- INCLUDE
- OPEN-FILE
- PUT-FILE
- READ-FILE
- REPOSITION-FILE
- WRITE-FILE
- RW-BUFFER

#### WORDSET FORMATTING

- OVERVIEW OF FORMATTING
- #>
- #S
- #
- <#
- >NUMBER
- BASE
- DECIMAL
- HEX
- HOLD
- SIGN
- (NUMBER)
- DIGIT
- DPL
- ECL
- FLD
- HLD
- NUMBER

#### WORDSET INITIALISATIONS

- OVERVIEW OF INITIALISATIONS
- +ORIGIN
- ABORT
- COLD
- OK
- OPTIONS
- QUIT
- WARM
- _INIT

#### WORDSET INPUT

- OVERVIEW OF INPUT
- (ACCEPT)
- ACCEPT
- KEY?
- KEY
- PP
- RUBOUT
- TIB
- (>IN)
- REFILL-TIB
- REMAINDER
- SET-TERM
- TERMIO

#### WORDSET JUGGLING

- OVERVIEW OF JUGGLING
- 2DROP
- 2DUP
- 2OVER
- 2SWAP
- ?DUP
- DROP
- DUP
- NIP
- OVER
- ROT
- SWAP

#### WORDSET LIBRARY

- OVERVIEW OF LIBRARY

#### WORDSET LOGIC

- OVERVIEW OF LOGIC
- 0<
- 0=
- <>
- <
- =
- >
- AND
- INVERT
- OR
- U<
- XOR

#### WORDSET MEMORY

- OVERVIEW OF MEMORY
- !
- +!
- 2!
- 2@
- @
- ALIGNED
- ALIGN
- BLANK
- BM
- C!
- C@
- CELL+
- CELLS
- CHAR+
- CHARS
- CMOVE
- CORA
- EM
- ERASE
- FILL
- L!
- L@
- MOVE
- PC!
- PC@
- PW!
- PW@
- TASK-SIZE
- TOGGLE
- WITHIN

#### WORDSET MISC

- OVERVIEW OF MISC
- .SIGNON
- EXECUTE
- NOOP
- TASK
- U0
- _

#### WORDSET MULTIPLYING

- OVERVIEW OF MULTIPLYING
- */MOD
- */
- FM/MOD
- M*
- M/MOD
- SM/REM
- UDM/MOD
- UM*
- UM/MOD

#### WORDSET OPERATINGSYSTEM

- OVERVIEW OF OPERATINGSYSTEM
- ARGS
- BYE
- EXIT-CODE
- MS
- SHELL
- SYSTEM
- XOS5
- XOS
- ZEN

#### WORDSET OPERATOR

- OVERVIEW OF OPERATOR
- *
- +
- -
- /MOD
- /
- ABS
- LSHIFT
- MAX
- MIN
- MOD
- NEGATE
- RSHIFT

#### WORDSET OUTPUT

- OVERVIEW OF OUTPUT
- (D.R)
- ."
- .(
- .R
- .
- ?
- CR
- D.R
- D.
- EMIT
- ETYPE
- OUT
- SPACES
- SPACE
- TYPE
- U.

#### WORDSET PARSING

- OVERVIEW OF PARSING
- ?BLANK
- CHAR
- EVALUATE
- INTERPRET
- NAME
- PARSE
- PP@@
- RESTORE-INPUT
- RESTORE
- SAVE-INPUT
- SAVE
- SET-SRC
- SOURCE
- SRC
- STATE
- WORD
- [CHAR]
- [
- \
- ]
- _left_parenthesis_

#### WORDSET SCREEN

- OVERVIEW OF SCREEN
- (LINE)
- C/L
- INDEX
- LIST
- LOAD
- LOCK
- R#
- SCR
- THRU
- TRIAD
- UNLOCK
- (BLK)
- BLK

#### WORDSET SECURITY

- OVERVIEW OF SECURITY
- !CSP
- ?COMP
- ?CSP
- ?DELIM
- ?EXEC
- ?LOADING
- ?PAIRS
- ?STACK
- CSP

#### WORDSET STACKS

- OVERVIEW OF STACKS
- .S
- >R
- CLS
- DEPTH
- DSP!
- DSP@
- R0
- R>
- R@
- RDROP
- RSP!
- RSP@
- S0

#### WORDSET STRING

- OVERVIEW OF STRING
- $!-BD
- $!
- $+!
- $,
- $/
- $@
- $C+
- $\
- $^
- -TRAILING
- BL
- COUNT
- S"

#### WORDSET SUPERFLUOUS

- OVERVIEW OF SUPERFLUOUS
- 0
- 1+
- 1-
- 2*
- 2/
- Number_1
- Number_2

#### WORDSET WORDLISTS

- OVERVIEW OF WORDLISTS
- ALSO
- ASSEMBLER
- CONTEXT
- CURRENT
- DEFINITIONS
- ENVIRONMENT
- FORTH
- LATEST
- ONLY
- PREVIOUS
- VOC-LINK

# BLOCKS

OVERVIEW:

The block mechanism connects to the Forth system a single background storage divided in numbered blocks. The wordset BLOCKS contains words to input and output to this mass storage. In this ciforth blocks reside in a file, by default named ``forth.lab''. . Most blocks are used for the SCREEN facility, where each block contains source code.

## #BUFF

STACKEFFECT: --- n

DESCRIPTION:

() A constant that leaves the number of block buffers. Because a buffer that is being interpreted is locked in memory, this is also a limit to the nesting depth of blocks loading other blocks.

GLOSSARY INDEX

SEE ALSO: BLOCKS BLOCK THRU LOAD LOCK

## -->

STACKEFFECT:

DESCRIPTION:

(I,WANT) Continue interpretation with the next disc screen. If the current input source is not from a block, a crash will ensue. If this new screen is left by throw of an exception, the screen may remain locked until a QUIT, or any uncaught exception.

GLOSSARY INDEX

SEE ALSO: BLOCKS LOCK CATCH LOAD

## ?DISK-ERROR

STACKEFFECT: n---

DESCRIPTION:

() Interpret n as the status of a disk i/o call and signal an error if it contains an error condition. It is only used to signal errors related to accessing the BLOCK-FILE.

GLOSSARY INDEX

SEE ALSO: BLOCKS BLOCK-FILE BLOCK-HANDLE BLOCK-INIT BLOCK-EXIT

## B/BUF

STACKEFFECT: --- n

DESCRIPTION:

() This constant leaves the number of bytes per disc buffer, the byte count read from disc by BLOCK . The ISO standard fixes this to 1024.

GLOSSARY INDEX

SEE ALSO: BLOCKS (BUFFER)

## BLOCK-EXIT

STACKEFFECT: ---

DESCRIPTION:

() A block file must have been opened by BLOCK-INIT . All blocks are unlocked. Any changed blocks are written back to mass storage. Close the currently open block file BLOCK-HANDLE, such that the mass storage words no longer work, and will result in error messages. If error messages were fetched from disk, they no longer are.

GLOSSARY INDEX

SEE ALSO: BLOCKS BLOCK LIST LOAD DISK-ERROR WARNING

## BLOCK-FILE

STACKEFFECT: ---addr

DESCRIPTION:

() Leave the address addr of a counted string, the name of a library file in which blocks are (to be) allocated. The name may contain a path and be at most 252 characters long. The default name is forth.lab . This name is typically changed during installation and is used by the BLOCK-INIT command.

GLOSSARY INDEX

SEE ALSO: BLOCKS BLOCK-HANDLE BLOCK-INIT LIST LOAD $@

## BLOCK-HANDLE

STACKEFFECT: ---n

DESCRIPTION:

() Leave a file handle in n . If it is negative there is no block file open, otherwise the handle is used by the system to access blocks.

GLOSSARY INDEX

SEE ALSO: BLOCKS BLOCK-FILE BLOCK-INIT BLOCK-EXIT

## BLOCK-INIT

STACKEFFECT: n ---

DESCRIPTION:

() Map the blocks on the block file BLOCK-FILE, i.e. the mass storage words refer to the blocks in this file. The handle BLOCK-HANDLE can be used to access it, with access code n (2 for read and write). This command signals failure by a negative handle in BLOCK-HANDLE. You must activate mnemonic error messages explicitly by setting WARNING.

GLOSSARY INDEX

SEE ALSO: BLOCKS BLOCK LIST LOAD BLOCK-EXIT OPEN-FILE

## BLOCK-READ

STACKEFFECT: addr blk ---

DESCRIPTION:

() The ciforth primitive for reading of blocks. addr specifies the destination block buffer, blk is the sequential number of the referenced physical block BLOCK-READ determines the location on mass storage, performs the read and throws an exception on errors.

GLOSSARY INDEX

SEE ALSO: BLOCKS BLOCK DISK-ERROR BLOCK-WRITE BLOCK-INIT

## BLOCK-WRITE

STACKEFFECT: addr blk ---

DESCRIPTION:

() The ciforth primitive for writing of blocks. addr specifies the source or destination block buffer, blk is the sequential number of the referenced physical block. BLOCK-WRITE determines the location on mass storage, performs the write and throws an exception on errors.

GLOSSARY INDEX

SEE ALSO: BLOCKS BLOCK DISK-ERROR BLOCK-READ BLOCK-INIT

## BLOCK

STACKEFFECT: n --- addr

DESCRIPTION:

(ISO,FIG) Leave addr, the disc buffer containing block n, which is the physical disk block OFFSET+n. The address left is the field within the buffer to be used for data storage. If the block is not already in memory, it is transferred from disc to a new buffer allocated by (BUFFER) . Blocks are generally used to contain source code to be interpreted by LOAD. They can be equally useful to contain other data, e.g. for implementing a database.

GLOSSARY INDEX

SEE ALSO: BLOCKS (BUFFER) BLOCK-READ BLOCK-WRITE OFFSET UPDATE FLUSH LOAD

## DISK-ERROR

STACKEFFECT: --- addr

DESCRIPTION:

() This variable is not used in thisforth, errors are thrown.

GLOSSARY INDEX

SEE ALSO: BLOCKS BLOCK

## EMPTY-BUFFERS

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) Mark all block-buffers as empty. Updated blocks are not written to the disc. This is an initialization proceedure before first use of the disc. The usage as an ``undo'' is infeasible in ciforth.

GLOSSARY INDEX

SEE ALSO: BLOCKS FLUSH BLOCK SCREEN UPDATE

## UPDATE

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) Marks the most recently referenced block (pointed to by _PREV ) as altered. The block will subsequently be transferred automatically to disc should its buffer be required for storage of a different block. In fact the block is transferred to disk immediately.

GLOSSARY INDEX

SEE ALSO: BLOCKS BLOCK EMPTY-BUFFERS

## (BUFFER)

STACKEFFECT: n --- addr

DESCRIPTION:

() Return the addres addr of a buffer assigned to identification n , probably a block number. Block numbers are positive, so a negative value can be used for a buffer that is used for some other purpose. The buffer layout is as follows: a cell with n, a cell with the status, and the content of length B/BUF . The status is negative for locked. The l.s.b. gives zero for free and one for valid data. The block is not read from the disc. The buffer is either one that was already assigned, or else a free buffer. If there is none free, some non-locked buffer is freed. The contents of that buffer is written to the disc, if it was marked as updated. In ciforth this will never happen, because updated blocks are written immediately. In ciforth blocks can be locked, and locked buffers are never freed by (BUFFER) . An update flag would somehow be multiplexed with the lock count, but it is not needed in this ciforth. If all buffers were locked, (BUFFER) throws exception 48.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ BLOCK _PREV #BUFF LOCK UNLOCK

## +BUF

STACKEFFECT: addr1 --- addr2 ff

DESCRIPTION:

(FIG) Advance the disc buffer address addr1 to the address of the next buffer addr2 . Boolean ff is false when addr2 is the buffer presently pointed to by variable _PREV.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ BLOCK

## BLOCK-SEEK

STACKEFFECT: n---

DESCRIPTION:

() A block file must have been opened by BLOCK-INIT . Position the file pointer at block n in behalf of subsequent reads and writes.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ BLOCK LIST LOAD BLOCK-READ BLOCK-WRITE

## FLUSH

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) Make sure that the content of all UPDATE d block buffers has been transferred to disk. The buffers are no longer associated with a block and their content is no longer available. In ciforth no transfer takes place, because mass storage is updated automatically in the background.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ EMPTY-BUFFERS BLOCK

## OFFSET

STACKEFFECT: --- addr

DESCRIPTION:

(U) A user variable which contains a block offset. The contents of OFFSET is added to the argument for BLOCK before reading or writing blocks. In this way a part of disc drives can be reserved for boot-code. As blocks are allocated in a file on the host operating system it is 0.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ BLOCK MESSAGE BLOCK-READ BLOCK-WRITE

## _FIRST

STACKEFFECT: --- addr1

DESCRIPTION:

() A constant that leaves the address of the block buffer lowest in memory.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ BLOCK _LIMIT

## _LIMIT

STACKEFFECT: ---- addr1

DESCRIPTION:

() A constant leaving the address just above the highest memory available for a disc buffer. Actually this is the highest system memory.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ BLOCK _FIRST

## _PREV

STACKEFFECT: --- addr

DESCRIPTION:

() A variable containing the address of the disc buffer (not its content field!) most recently referenced. The UPDATE command marks this buffer to be written to disc.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ (BUFFER)

# COMPILING

OVERVIEW:

The wordset COMPILING contains words that compile words and numbers. They need special attention because these words in general execute during compilation See also IMMEDIATE . Numbers are compiled in line , behind a word that fetches them.

## DLITERAL

STACKEFFECT: d --- d (executing) d --- (compiling)

DESCRIPTION:

(I) If compiling, compile a stack double number into a literal. Later execution of the definition containing the literal will push it to the stack. If executing, the number will just remain on the stack.

GLOSSARY INDEX

SEE ALSO: COMPILING LITERAL LIT STATE

## LITERAL

STACKEFFECT: n --- n (executing) n --- (compiling)

DESCRIPTION:

(ISO,I,C) If compiling, then compile the stack value n as a 64 bit literal. The intended use is: : xxx [ calculate ] LITERAL ; Compilation is suspended for the compile time calculation of a value. Compilation is resumed and LITERAL compiles this value. Later execution of the definition containing the literal will push it to the stack. If executing, the number will just remain on the stack.

GLOSSARY INDEX

SEE ALSO: COMPILING LIT SDLITERAL STATE

## POSTPONE

STACKEFFECT:

DESCRIPTION:

(ISO,I,C) Used in a colon-definition in the form:

: xxx POSTPONE SOME-WORD

POSTPONE will postpone the compilation behaviour of SOME-WORD to the definition being compiled. If SOME-WORD is an immediate word this is similar to [COMPILE] SOME-WORD.

GLOSSARY INDEX

SEE ALSO: COMPILING [COMPILE]

## [COMPILE]

STACKEFFECT:

DESCRIPTION:

(ISO,I,C) Used in a colon-definition in the form:

: xxx ... [COMPILE] IF ... ;

[COMPILE] will force the compilation of an immediate definition, that would otherwise execute during compilation. The above example will perform IF when xxx executes, rather than introducing conditional code in xxx itself.

GLOSSARY INDEX

SEE ALSO: COMPILING POSTPONE

## LIT

STACKEFFECT: --- n

DESCRIPTION:

(FIG,C) Within a colon-definition, LIT is compiled followed by a 64 bit literal number given during compilation. Later execution of LIT causes the contents of this next dictionary cell to be pushed to the stack. This word is compiled by LITERAL .

GLOSSARY INDEX

SEE ALSO: COMPILING~ LITERAL

## SDLITERAL

STACKEFFECT: d --- s/d (executing) / d --- (compiling)

DESCRIPTION:

(I) If compiling, compile a stack double number into a literal or double literal, depending on whether DPL contains a nil pointer or points into the input. Later execution of the definition containing the literal will push it to the stack. If executing, the number will remain on the stack.

GLOSSARY INDEX

SEE ALSO: COMPILING~ LITERAL DLITERAL STATE

# CONTROL

OVERVIEW:

The wordset CONTROL contains words that influence the control flow of a program, i.e. the sequence in which commands are executed in compiled words. With control words you can have actions performed repeatedly, or depending on conditions.

## +LOOP

STACKEFFECT: n1 --- (run) / addr n2 --- (compile)

DESCRIPTION:

(ISO,I,C) Used in a colon-definition in the form:

DO ... n1 +LOOP

At run-time, +LOOP selectively controls branching back to the corresponding DO based on n1 , the loop index and the loop limit. The signed increment n1 is added to the index and the total compared to the limit. The branch back to DO occurs until the new index is equal to or greater than the limit (n1>0), or until the new index is equal to or less than the limit (n1<0). Negative increments cannot be combined with ?DO , this deviates from the ISO standard. Upon exiting the loop, the parameters are discarded and execution continues ahead. At compile-time, LOOP compiles code to the above effect, existing of (+LOOP) 0BRANCH UNLOOP and uses addr , left on the stack by DO, to calculate the branch offset from HERE. n2 is used for compile time error checking.

GLOSSARY INDEX

SEE ALSO: CONTROL LOOP

## ?DO

STACKEFFECT: n1 n2 --- (execute) addr n --- (compile)

DESCRIPTION:

(NISO,I,C) Occurs in a colon-definition in form:

?DO ... LOOP

It behaves like DO, with the exception that if n1 is less than n2 the loop body is not executed. This is intended to suppress the unwanted behaviour of looping through the whole number range, ciforth deviates from ISO in that it also suppresses the unwanted behaviour of looping through almost the whole number range for an input of e.g.

1 2

However, negative increments are made impossible for forthword(?DO) this way.

GLOSSARY INDEX

SEE ALSO: CONTROL DO I LOOP +LOOP LEAVE

## AGAIN

STACKEFFECT: addr n --- (compiling)

DESCRIPTION:

(ISO,FIG,I,C) Used in a colon-definition in the form:

BEGIN ... AGAIN

At run-time, AGAIN forces execution to return to the corresponding BEGIN . There is no effect on the stack. Execution cannot leave this loop except for EXIT. At compile time, AGAIN compiles BRANCH with an offset from HERE to addr. n is used for compile-time error checking.

GLOSSARY INDEX

SEE ALSO: CONTROL BEGIN

## BEGIN

STACKEFFECT: --- addr n (compiling)

DESCRIPTION:

(ISO,FIG,I) Occurs in a colon-definition in one of the forms:

BEGIN ... UNTIL

BEGIN ... AGAIN

BEGIN ... WHILE ... REPEAT

At run-time, BEGIN marks the start of a sequence that may be repetitively executed. It serves as a return point from the corresponding UNTIL , AGAIN or REPEAT . When executing UNTIL a return to BEGIN will occur if the top of the stack is false; for AGAIN and REPEAT a return to BEGIN always occurs. At compile time BEGIN leaves its return address and n for compiler error checking.

GLOSSARY INDEX

SEE ALSO: CONTROL (BACK DO

## CO

STACKEFFECT:

DESCRIPTION:

() Return to the caller, suspending interpretation of the current definition, such that when the caller exits, this definition is resumed. The return stack must not be engaged, such as between >R and R> , or DO and LOOP .

GLOSSARY INDEX

SEE ALSO: CONTROL EXIT

## DO

STACKEFFECT: n1 n2 --- (execute) addr n --- (compile)

DESCRIPTION:

(ISO,FIG,I,C) Occurs in a colon-definition in form: DO ... LOOP At run time, DO begins a sequence with repetitive execution controlled by a loop limit n1 and an index with initial value n2 . DO removes these from the stack. Upon reaching LOOP the index is incremented by one. Until the new index equals or exceeds the limit, execution loops back to just after DO ; otherwise the loop parameters are discarded and execution continues ahead. Both n1 and n2 are determined at run-time and may be the result of other operations. Within a loop I will copy the current value of the index to the stack. With +LOOP it can be used with other increments than one. It deviates from the ISO standard in that that if n1 is equal to n2 the loop is never executed even once. When compiling within the colon definition, DO compiles (DO) and leaves the following address addr and n for later error checking.

GLOSSARY INDEX

SEE ALSO: CONTROL I LOOP +LOOP LEAVE

## ELSE

STACKEFFECT: addr1 n1 --- addr2 n2 (compiling)

DESCRIPTION:

(ISO,FIG,I,C) Occurs within a colon-definition in the form:

IF ... ELSE ... THEN

At run-time, ELSE executes after the true part following IF . ELSE forces execution to skip over the following false part and resumes execution after the THEN . It has no stack effect. At compile-time ELSE compiles BRANCH and reserves a places for a branch offset, leaving its address addr2 and n2 for error testing. ELSE also resolves the pending forward branch from IF by calculating the offset from addr1 to HERE and storing at addr1 .

GLOSSARY INDEX

SEE ALSO: CONTROL (FORWARD FORWARD) BRANCH

## EXIT

STACKEFFECT:

DESCRIPTION:

(ISO) Stop interpretation of the current definition. The return stack must not be engaged, such as between >R and R> , or DO and LOOP . In ciforth it can also be used to terminate interpretation from a string, block or file, or a line from the current input stream.

GLOSSARY INDEX

SEE ALSO: CONTROL (;)

## IF

STACKEFFECT: f --- (run-time) / --- addr n (compile)

DESCRIPTION:

(ISO,FIG,I,C) Occurs in a colon-definition in form:

IF (tp) ... THEN

or

IF (tp) ... ELSE (fp) ... THEN

At run-time, IF selects execution based on a boolean flag. If f is true (non-zero), execution continues ahead thru the true part. If f is false (zero), execution skips till just after ELSE to execute the false part. After either part, execution resumes after THEN. ELSE and its false part are optional; if missing, false execution skips to just after THEN . At compile-time IF compiles 0BRANCH and reserves space for an offset at addr . addr and n are used later for resolution of the offset and error testing.

GLOSSARY INDEX

SEE ALSO: CONTROL (FORWARD 0BRANCH

## I

STACKEFFECT: --- n

DESCRIPTION:

(ISO,FIG,C) Used within a do-loop to copy the loop index to the stack.

GLOSSARY INDEX

SEE ALSO: CONTROL DO LOOP +LOOP

## J

STACKEFFECT: --- n

DESCRIPTION:

(ISO,FIG,C) Used within a nested do-loop to copy the loop index of the outer do-loop to the stack.

GLOSSARY INDEX

SEE ALSO: CONTROL DO LOOP +LOOP

## LEAVE

STACKEFFECT:

DESCRIPTION:

(ISO) Terminate a do-loop by branching to directly behind the end of a loop started by DO or ?DO , so after the corresponding LOOP or +LOOP .

GLOSSARY INDEX

SEE ALSO: CONTROL UNLOOP

## LOOP

STACKEFFECT: --- (run) addr n --- (compiling)

DESCRIPTION:

(ISO,I,C) Occurs in a colon-definition in form:

DO ... LOOP

At run-time, LOOP selectively controls branching back to the corresponding DO based on the loop index and limit. The loop index is incremented by one and compared to the limit. The branch back to DO occurs until the index equals or exceeds the limit; at that time, the parameters are discarded and execution continues ahead. At compile-time, LOOP compiles code to the above effect, existing of ONE (+LOOP) 0BRANCH UNLOOP and uses addr to calculate an offset to be used by 0BRANCH . n is used for compile time error checking.

GLOSSARY INDEX

SEE ALSO: CONTROL +LOOP

## RECURSE

STACKEFFECT: (varies)

DESCRIPTION:

(ISO) Do a recursive call of the definition being compiled.

GLOSSARY INDEX

SEE ALSO: CONTROL :

## REPEAT

STACKEFFECT: addr1 n1 addr2 n2--- (compiling)

DESCRIPTION:

(ISO,FIG,I,C) Used within a colon-definition in the form:

BEGIN ... WHILE ... REPEAT

At run-time, REPEAT forces an unconditional branch back to just after the corresponding BEGIN . At compile-time, REPEAT compiles BRANCH and the offset from HERE to addr2 . Then it fills in another branch offset at addr1 left there by WHILE . n1 n2 is used for error testing.

GLOSSARY INDEX

SEE ALSO: CONTROL WHILE

## SKIP

STACKEFFECT:

DESCRIPTION:

(C) Skip over an area in memory, where the length is given in the next cell, then align. This length doesn't include the length cell, so it is compatible with $@ . Internal, used for nested compilation and compiling strings.

GLOSSARY INDEX

SEE ALSO: CONTROL BRANCH

## THEN

STACKEFFECT: addr n --- (compile)

DESCRIPTION:

(ISO,FIG,I,C) Occurs in a colon-definition in form:

IF ... THEN

IF ... ELSE ... THEN

At run-time, THEN serves only as the destination of a forward branch from IF or ELSE . It marks the conclusion of the conditional structure. At compile-time, THEN computes the forward branch offset from addr to HERE and stores it at addr . n is used for error tests.

GLOSSARY INDEX

SEE ALSO: CONTROL FORWARD) IF ELSE

## UNLOOP

STACKEFFECT:

DESCRIPTION:

(ISO,I,C) Discard the loop parameters. Must be used when the regular end of the loop is by-passed. That means it is not ended via LOOP +LOOP or LEAVE, but my means of EXIT or unstructured branching. In this Forth the parameters are the address after the loop, the end limit, end the current index. af .

GLOSSARY INDEX

SEE ALSO: CONTROL DO LEAVE 0BRANCH (FORWARD

## UNTIL

STACKEFFECT: f --- (run-time) / addr n --- (compile)

DESCRIPTION:

(ISO,FIG,I,C) Occurs within a colon-definition in the form:

BEGIN ... UNTIL

At run-time, UNTIL controls the conditional branch back to the corresponding BEGIN. If f is false, execution returns to just after BEGIN , otherwise execution continues ahead. At compile-time, UNTIL compiles 0BRANCH and an offset from HERE to addr. n is used for error tests.

GLOSSARY INDEX

SEE ALSO: CONTROL BEGIN

## WHILE

STACKEFFECT: f --- (run-time) / addr1 nl --- addr2 n1 addr1 n2 (compile-time)

DESCRIPTION:

(ISO,FIG,I,C) Occurs in a colon-definition in the form: BEGIN ... WHILE (tp) ... REPEAT At run-time, WHILE selects conditional execution based on boolean flag f . If f is true (non-zero), WHILE continues execution of the true part thru to REPEAT , which then branches back to BEGIN . If f is false (zero), execution skips to just after REPEAT , exiting the structure. At compile time, WHILE compiles 0BRANCH and tucks the target address addr2 under the addr1 left there by BEGIN . The stack values will be resolved by REPEAT . n1 and n2 provide checks for compiler security.

GLOSSARY INDEX

SEE ALSO: CONTROL (FORWARD BEGIN

## (+LOOP)

STACKEFFECT: n ---

DESCRIPTION:

(C) The run-time proceedure compiled by +LOOP, which increments the loop index by n and tests for loop completion.

GLOSSARY INDEX

SEE ALSO: CONTROL~ +LOOP

## (;)

STACKEFFECT:

DESCRIPTION:

() This is a synonym for EXIT. It is the run-time word compiled at the end of a colon-definition which returns execution to the calling proceedure. Stop interpretation of the current definition. The return stack must not be engaged.

GLOSSARY INDEX

SEE ALSO: CONTROL~ EXIT

## (?DO)

STACKEFFECT:

DESCRIPTION:

(C) The run-time proceedure compiled by ?DO which prepares the return stack, where the looping bookkeeping is kept.

GLOSSARY INDEX

SEE ALSO: CONTROL~ ?DO

## (BACK

STACKEFFECT: --- addr

DESCRIPTION:

() Start a backward branch by leaving the target address HERE into addr. Usage is (BACK .. POSTPONE BRANCH BACK)

GLOSSARY INDEX

SEE ALSO: CONTROL~ BACK) BEGIN DO

## (DO)

STACKEFFECT:

DESCRIPTION:

(C) The run-time proceedure compiled by DO which prepares the return stack, where the looping bookkeeping is kept.

GLOSSARY INDEX

SEE ALSO: CONTROL~ DO UNLOOP

## (FORWARD

STACKEFFECT: --- addr

DESCRIPTION:

() Start a forward branch by allocating space for an offset, that must be backpatched into addr. Usage is POSTPONE BRANCH (FORWARD .. FORWARD)

GLOSSARY INDEX

SEE ALSO: CONTROL~ IF BRANCH 0BRANCH

## 0BRANCH

STACKEFFECT: f ---

DESCRIPTION:

(FIG,C) The run-time proceedure to conditionally branch. If f is false (zero), the following in-line parameter is added to the interpretive pointer to branch ahead or back. Compiled by IF , UNTIL , and WHILE .

GLOSSARY INDEX

SEE ALSO: CONTROL~ BRANCH (FORWARD (BACK SKIP

## BACK)

STACKEFFECT: addr ---

DESCRIPTION:

() Complete a backward branch by compiling an offset from HERE to addr, left there by {{{(BACK}}} . Usage is (BACK .. POSTPONE BRANCH BACK)

GLOSSARY INDEX

SEE ALSO: CONTROL~ LOOP UNTIL

## BRANCH

STACKEFFECT:

DESCRIPTION:

(FIG,C) The run-time proceedure to unconditionally branch. An in-line offset is added to the interpretive pointer HIP to branch ahead or back. BRANCH is compiled by ELSE AGAIN REPEAT .

GLOSSARY INDEX

SEE ALSO: CONTROL~ 0BRANCH (FORWARD (BACK

## FORWARD)

STACKEFFECT: addr ---

DESCRIPTION:

() Complete a forward branch by backpatching an offset from HERE into addr, left there by {{{(FORWARD}}} . Usage is POSTPONE BRANCH (FORWARD .. FORWARD)

GLOSSARY INDEX

SEE ALSO: CONTROL~ LOOP UNTIL REPEAT

# DEFINING

OVERVIEW:

The wordset DEFINING contains words that add new entries to the dictionary, or are related to those words. A number of such defining word's are predefined, but there is also the possibility to make new defining words, using CREATE and DOES> .

## ;

STACKEFFECT:

DESCRIPTION:

(ISO,FIG,I,C) Terminate a colon-definition and stop further compilation. Compiles the run-time (;) .

GLOSSARY INDEX

SEE ALSO: DEFINING :

## CONSTANT

STACKEFFECT: n ---

DESCRIPTION:

(ISO,FIG) A defining word used in the form: n CONSTANT cccc to create word cccc , where the content of its data field address is n . When cccc is later executed, it will push the value of n to the stack.

GLOSSARY INDEX

SEE ALSO: DEFINING VARIABLE >DFA

## CREATE

STACKEFFECT:

DESCRIPTION:

(ISO) A defining word used in the form: CREATE cccc Later execution of cccc returns its data field , i.e. the value of HERE immediately after executing CREATE . It can be the base of a new defining word if used in the form:

: CREATOR CREATE aaaa DOES> bbbb ; CREATOR cccc

The second line has the effect of creating a word cccc . Its datastructure is build by the code aaaa and when executing cccc , its data field is pushed on the stack, then the code bbbb is executed. Space in this forthdefi({data field}) has yet to be allocated. The forthdefi({DFA}) (data field address) points to the the execution action that can be changed by forthcode({DOES>}) . ciforth is byte aligned, so no extra measures are needed.

GLOSSARY INDEX

SEE ALSO: DEFINING >BODY DOES> ;CODE ALLOT , >DFA

## DATA

STACKEFFECT:

DESCRIPTION:

() A defining word used in the form: DATA cccc When DATA is executed, it creates the definition cccc whose data field address contains a pointer n to HERE. This code is typically followed by some data allocation word like forthcode({ALLOT}) or forthcode({{{{,}}}}) . forthcode({DOES>}) must not be used with forthsamp({cccc}). When cccc is later executed, this pointer n is left on the stack, so that data can be accessed.

GLOSSARY INDEX

SEE ALSO: DEFINING VARIABLE CREATE >DFA

## DOES>

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) A word which is used in combination with CREATE to specify the run-time action within a high-level defining word. DOES> modifies the default behaviour of the created word so as to execute the sequence of compiled word addresses following DOES> . When the DOES> part executes it begins with the address of the data field of the word on the stack. This allows interpretation using this area or its contents. Typical uses include the Forth assembler, arrays and matrices, and compiler generation.

GLOSSARY INDEX

SEE ALSO: DEFINING

## MAX-USER

STACKEFFECT: --- addr

DESCRIPTION:

(U) A user variable which contains the offset of next user variable. It is measured in cells from the start of the user area.

GLOSSARY INDEX

SEE ALSO: DEFINING BLOCK USER MESSAGE U0

## NAMESPACE

STACKEFFECT:

DESCRIPTION:

() A defining word used in the form: NAMESPACE cccc to create a namespace definition cccc . It will create a word listin the ISO sense. Subsequent use of cccc will push this word list (the word list associated with cccc) to the top of the search order in CONTEXT. So it will be searched first by INTERPRET . A word create by NAMESPACE is not immediate. This is also different among Forth implementations. A namespace 's data content field contains at first the dovoc pointer (like for any DOES> word) , then follows its body. The body contains the namespace ("vocabulary") link field address ( VLFA ). The VLFA points to the VLFA of the next namespace or a nil pointer for the end. Then follows a wordlist word list identifier or WID . Executing the namespace means pushing its WID on top of the CONTEXT order. In ciforth when there can be at most 16 word list 's in the search order, the oldest one gets lost.

GLOSSARY INDEX

SEE ALSO: DEFINING ALSO PREVIOUS WORDLIST DEFINITIONS FOR-VOCS >WID

## USER

STACKEFFECT: n ---

DESCRIPTION:

(ISO) A defining word used in the form: n USER cccc which creates a user variable cccc . The data field of cccc contains n as a byte offset relative to the user pointer register UP for this user variable, which is n CELLS. When cccc is later executed, it places the sum of its offset and the user area base address on the stack as the storage address of that particular variable. In this ciforth forthsamp({UP}) is coupled to the return stack. This means that with a switch of the return stack{,} forthsamp({UP}) is switched also automatically. It is best to do MAX-USER @ DUP USER cccc 1 MAX-USER ! reflecting the current allocation in the user area.

GLOSSARY INDEX

SEE ALSO: DEFINING VARIABLE +ORIGIN CONTEXT >DFA

## VARIABLE

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) A defining word used in the form: VARIABLE cccc When VARIABLE is executed, it creates the definition cccc whose data field address contains a pointer n to a data location, that can contain one cell. When cccc is later executed, this pointer n is left on the stack, so that a fetch or store may access this location.

GLOSSARY INDEX

SEE ALSO: DEFINING USER CONSTANT >DFA DATA

## WORDLIST

STACKEFFECT: --- wid

DESCRIPTION:

(ISO) This words creates an empty wordlist which is a single header structure dea that serves as a word list identifier or WID in the sense of the ISO standard. Definitions will be added to it after it has been copied to CURRENT. This handle can be placed in the top of the search order CONTEXT and the wordlist will be searched. This word underlies NAMESPACE, there is no VLFA. A wid's significant fields are the flag field and the link field. The flag field indicates that it is dummy, i.e. not intended to be executed. The link field address contains the dea of the latest word of the wordlist or a nil pointer if empty. The namefield points to an empty string

GLOSSARY INDEX

SEE ALSO: DEFINING NAMESPACE ALSO >FFA >LFA FOR-WORDS

## colon

STACKEFFECT:

DESCRIPTION:

(ISO,FIG,E) Used in the form called a colon-definition:

: cccc ... ;

Creates a dictionary entry defining cccc as equivalent to the following sequence of Forth word definitions '...' until the next ';' or ';CODE'. The word is added as the latest into the CURRENT word list. The compiling process is done by the text interpreter as long as STATE is non-zero. Words with the immediate bit set, attribute I, are executed rather than being compiled.

GLOSSARY INDEX

SEE ALSO: DEFINING (CREATE)

## (;CODE)

STACKEFFECT:

DESCRIPTION:

(WANT,C) The run-time proceedure, compiled by ;CODE, that rewrites the code field of the most recently defined word to point to the following machine code sequence. It is used after CREATE instead of DOES> if the code following is assembler code instead of high level code.

GLOSSARY INDEX

SEE ALSO: DEFINING~ ;CODE

## (CREATE)

STACKEFFECT: sc ---

DESCRIPTION:

() This is the basis for all defining words, including those which lack a data field in the ISO sense: : USER VARIABLE NAMESPACE CONSTANT DATA . It creates a header with name sc in the dictionary and links it into the CURRENT word list.

GLOSSARY INDEX

SEE ALSO: DEFINING~ HEADER LINK CREATE

## HEADER

STACKEFFECT: sc --- dea

DESCRIPTION:

() Create a dictionary entry structure for the word sc and returns its address into dea. A pointer to each of its fields is called a "field address" for code data flag line name source extra. In particular note that a data field address is not a data field in the ISO sense. HEADER initializes the code field addres and data field address to contain a same pointer to the area owned by this header, i.e. immediately following the completed header as appropriate for a low level (assembler) definition. The flag and link fields are initialised to zero , so not HIDDEN. The name sc is laid down in the dictionary before the header and filled in into the name field. The source field is filled in to best knowledge.

GLOSSARY INDEX

SEE ALSO: DEFINING~ (CREATE) >CFA >DFA >FFA >LFA >NFA >SFA >XFA LINK

## LINK

STACKEFFECT: dea wid ---

DESCRIPTION:

() Links the Forth word represented by dea into the wordlist represented by wid as the latest entry. Alternatively, consider wid as an other dea2. Link dea between the dea2 and its successor in the linked list.

GLOSSARY INDEX

SEE ALSO: DEFINING~ HEADER (CREATE)

# DENOTATIONS

OVERVIEW:

The wordset DENOTATIONS contains prefixes (mostly one letter words) that introduce a denotation, i.e. a generalisation of NUMBER . PREFIX turns the latest definition into a prefix, similar to IMMEDIATE. If a word starting with the prefix is looked up in the dictionary, the prefix is found and executed. Prefix words parse input and leave a constant (number, char or string) on the stack, or compile such constant, depending on STATE. For a kernel system it is guaranteed that they reside in the minimum search order wordlist, associated with the namespace ONLY. To make a distinction with the same words in other wordlists, the names of denotations are prepended with ``Prefix_'' in the documentation. Actual names consists of the one character following ``Prefix_''. Apart from Prefix_0 , ONLY contains entries for all hex digits 1...9 and A...F. Like NUMBER always did, all denotations behave identical in interpret and compile mode and they are not supposed to be postponed. The use of prefixes for other purposes than denotations require great care.

## Prefix_"

STACKEFFECT: --- sc

DESCRIPTION:

(I,P) Parse a " delimited string and leave it on the stack as a stringconstant , i.e. an address and a length. A " can be embedded in a string by doubling it. The string is permanent and takes dictionary space. The cell below the address contains the length, so DROP 1 CELLS - can be used as a single cell reference. This is a denotation: during compilation this behaviour is compiled.

GLOSSARY INDEX

SEE ALSO: DENOTATIONS

## Prefix_&

STACKEFFECT: --- c

DESCRIPTION:

(I,P) Leave c the non blank char that follows. Skip another blank character. This is a denotation: during compilation this behaviour is compiled.

GLOSSARY INDEX

SEE ALSO: DENOTATIONS ^

## Prefix_+

STACKEFFECT: --- s/d

DESCRIPTION:

(I,P) A prefix that handles numbers that start with + .

GLOSSARY INDEX

SEE ALSO: DENOTATIONS NUMBER (NUMBER) 7 B

## Prefix_-

STACKEFFECT: --- s/d

DESCRIPTION:

(I,P) A prefix that handles numbers that start with - .

GLOSSARY INDEX

SEE ALSO: DENOTATIONS NUMBER (NUMBER) 7 B

## Prefix_0

STACKEFFECT: --- s/d

DESCRIPTION:

(I,P) A prefix that handles numbers that start with 0 . Similar words are present for all decimal and hex digits. ISO compatibility ony requires that denotators for decimal digits are present, one can always use a leading zero.

GLOSSARY INDEX

SEE ALSO: DENOTATIONS NUMBER (NUMBER) B 7

## Prefix_7

STACKEFFECT: --- s/d

DESCRIPTION:

(I,P) A prefix that handles numbers that start with 7 . Similar words are present for all decimal and hex digits.

GLOSSARY INDEX

SEE ALSO: DENOTATIONS NUMBER (NUMBER) 0 B

## Prefix_B

STACKEFFECT: --- s/d

DESCRIPTION:

(I,P) A prefix that handles numbers that start with B . Similar words are present for all decimal and hex digits.

GLOSSARY INDEX

SEE ALSO: DENOTATIONS NUMBER (NUMBER) 0 7

## Prefix_TICK

STACKEFFECT: --- addr

DESCRIPTION:

(I,P) Used in the form:

'nnnn

In interpret mode it leaves the execution token (equivalent to the dea dictionary entry address) of dictionary word nnnn. If the word is not found after a search of the search order an appropriate error message is given. In compile mode it finds the same address, then compiles it as a literal. It is recommended that one never compiles or postpones it. (Use a combination of NAME and FOUND or any form of explicit parsing and searching instead.) Furthermore it is recommended that for non-portable code ' is used in its denotation form without the space. Note that if you separate ' by a space, the ISO-conforming version of ' is found.

GLOSSARY INDEX

SEE ALSO: DENOTATIONS HEADER CONTEXT ' ['] PRESENT >CFA >DFA >FFA >LFA

## Prefix_^

STACKEFFECT: --- b

DESCRIPTION:

(I,P) Leave b the control character value of the char that follows i.e. ^A results in 1 and so on. Skip another blank character. This is a denotation: during compilation this behaviour is compiled.

GLOSSARY INDEX

SEE ALSO: DENOTATIONS &

# DICTIONARY

OVERVIEW:

The wordset DICTIONARY contains words that at a lower level than the wordset DEFINING concern the memory area that is allocated to the dictionary. They may add data to the dictionary at the expense of the free space, one cell or one byte at a time, or allocate a buffer at once. The dictionary space may also be shrunk, and the words that were there are lost. The dictionary entry address or dea represents a word. It is the lowest address of a record with fields. Words to access those fields also belong to this wordset.

## '

STACKEFFECT: --- addr

DESCRIPTION:

(ISO,FIG) Used in the form:

' nnnn

It leaves the execution token (equivalent to the dea dictionary entry address) of dictionary word nnnn. If the word is not found after a search of the search order an appropriate error message is given. If compiled the searching is done while the word being compiled is executed. Because this is so confusing, it is recommended that one never compiles or postpones '. (Use a combination of NAME and FOUND or any form of explicit parsing and searching instead.) Furthermore it is recommended that for non-portable code ' is used in its denotation form without the space.

GLOSSARY INDEX

SEE ALSO: DICTIONARY ['] FOUND >CFA >DFA >FFA >LFA >NFA >SFA >XFA

## ,

STACKEFFECT: n ---

DESCRIPTION:

(ISO,FIG) Store n into the next available dictionary memory cell, advancing the dictionary pointer.

GLOSSARY INDEX

SEE ALSO: DICTIONARY DP C,

## 2,

STACKEFFECT: d ---

DESCRIPTION:

(ISO,FIG) Store the most significand cell of d into the next available dictionary cell, advancing the dictionary pointer, then the least significand one. .

GLOSSARY INDEX

SEE ALSO: DICTIONARY DP ,

## >BODY

STACKEFFECT: dea --- addr

DESCRIPTION:

(ISO) Given the dictionary entry address dea of a definition created with a CREATE / DOES> construct, return its data field (in the ISO sense) addr.

GLOSSARY INDEX

SEE ALSO: DICTIONARY ' >CFA >DFA >PHA BODY> DATA

## ALLOT

STACKEFFECT: n ---

DESCRIPTION:

(ISO,FIG) Add the signed number to the dictionary pointer DP . May be used to reserve dictionary space or re-origin memory. As the Pentium is a byte-addressable machine n counts bytes.

GLOSSARY INDEX

SEE ALSO: DICTIONARY HERE ,

## BODY>

STACKEFFECT: addr --- dea

DESCRIPTION:

() Convert the data field addr of a definition created with a CREATE / DOES> construct to its dea. ( addr is not a header data field address) Where >BODY keeps working for a copy of the header, BODY> does not. There is some logic to this, because the dea to which the body belongs is no longer unique.

GLOSSARY INDEX

SEE ALSO: DICTIONARY ' >BODY

## C,

STACKEFFECT: b ---

DESCRIPTION:

(ISO,FIG) Store the least significand bits of b into the next available dictionary byte, advancing the dictionary pointer.

GLOSSARY INDEX

SEE ALSO: DICTIONARY DP ,

## DP

STACKEFFECT: ---- addr

DESCRIPTION:

(FIG,U,L) A user variable, the dictionary pointer, which contains the address of the next free memory above the dictionary. The value may be read by HERE and altered by ALLOT .

GLOSSARY INDEX

SEE ALSO: DICTIONARY

## FIND

STACKEFFECT: addr ---xt 1/xt -1/addr 0

DESCRIPTION:

(ISO,WANT) For the old fashioned string (stored with a preceding character count) at addr find a Forth word in the current search order. Return its execution token xt. If the word is immediate, also return 1, otherwise also return -1. If it is not found, leave the original addr and a zero. In ciforth the alternative FOUND is used, that uses a regular stringconstant , hence this is a loadable extension.

GLOSSARY INDEX

SEE ALSO: DICTIONARY FOUND CONTEXT PRESENT (FIND)

## FORGET

STACKEFFECT:

DESCRIPTION:

(ISO,FIG,E) Executed in the form: FORGET cccc Deletes definition named cccc from the dictionary with all entries physically following it. Recover the space that was in use.

GLOSSARY INDEX

SEE ALSO: DICTIONARY FENCE FORGET-VOC

## FOUND

STACKEFFECT: sc --- dea

DESCRIPTION:

() Look up the string sc in the dictionary observing the current search order. If found, leave the dictionary entry address dea of the first entry found, else leave a nil pointer. If the first part of the string matches a denotation word, that word is found, whether the denotation is correct or not. The dea allows to retrieve all properties of the word such as whether it is immediate.

GLOSSARY INDEX

SEE ALSO: DICTIONARY PP FIND PRESENT CONTEXT (FIND) PREFIX

## HERE

STACKEFFECT: --- addr

DESCRIPTION:

(ISO,FIG) Leave the address addr of the next available dictionary location.

GLOSSARY INDEX

SEE ALSO: DICTIONARY DP

## ID.

STACKEFFECT: dea ---

DESCRIPTION:

() Print a definition's name from its dictionary entry address. For dummy entries print nothing.

GLOSSARY INDEX

SEE ALSO: DICTIONARY ' >FFA >NFA

## IMMEDIATE

STACKEFFECT:

DESCRIPTION:

() Mark the most recently made definition so that when encountered at compile time, it will be executed rather than being compiled, i.e. the immediate bit in its header is set. This method allows definitions to handle special compiling situations, rather than build them into the fundamental compiler. The user may force compilation of an immediate definition by preceding it with POSTPONE .

GLOSSARY INDEX

SEE ALSO: DICTIONARY

## PAD

STACKEFFECT: --- addr

DESCRIPTION:

(ISO,FIG) Leave the address of the text output buffer, which is a fixed offset above HERE. The area growing downward from PAD is used for numeric conversion. The use of PAD is reserved for applications.

GLOSSARY INDEX

SEE ALSO: DICTIONARY

## PREFIX

STACKEFFECT:

DESCRIPTION:

() Mark the most recently made definition a prefix. If searching the wordlists for a name that starts with the prefix, the prefix is a match for that name. This method allows to define numbers, and other denotation's such as strings, in a modular and extensible fashion. A prefix word finds the interpreter pointer pointing to the remainder of the name (or number) sought for, and must compile that remainder. Some prefixes, like Prefix_7, decrement the parse pointer by one before starting to parse. Prefix words are mostly both immediate and smart, i.e. they behave differently when compiled, than interpreted. The result is that the compiled code looks the same and behaves the same than the interpreted code. Postponing prefix words voids your warranty. It is recommended that the only smart words present are prefix words.

GLOSSARY INDEX

SEE ALSO: DICTIONARY PP@@ IMMEDIATE Prefix_0 ONLY

## PRESENT

STACKEFFECT: sc --- dea

DESCRIPTION:

() If the string sc is present as a word name in the current search order, return its dea, else leave a nil pointer. For a denotation word, the name must match sc exactly.

GLOSSARY INDEX

SEE ALSO: DICTIONARY FOUND CONTEXT (FIND) NAMESPACE FIND

## WORDS

STACKEFFECT:

DESCRIPTION:

(ISO) List the names of the definitions in the topmost word list of the search order.

GLOSSARY INDEX

SEE ALSO: DICTIONARY CONTEXT

## [']

STACKEFFECT: --- addr

DESCRIPTION:

(ISO,I) Used in the form:

['] nnnn

In compilation mode it leaves the execution token (equivalent to the dictionary entry address) of dictionary word nnnn. So as a compiler directive it compiles the address as a literal. If the word is not found after a search of the search order an appropriate error message is given. It is recommended that where you can't use a denotation, or don't want to, you use a combination of NAME and FOUND (or WORD and FIND) instead.

GLOSSARY INDEX

SEE ALSO: DICTIONARY FOUND ' EXECUTE

## (FIND)

STACKEFFECT: sc wid --- sc dea

DESCRIPTION:

() Search down from the WID wid for a word with name sc. A WID is mostly a dummy dea found in the data field of a namespace, fetched from CURRENT or an other wid in the search order . Leave the dictionary entry address dea of the first entry found, else leave a zero. Do not consume the string sc, as this is a repetitive action.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ ~MATCH FOUND PRESENT >WID

## >CFA

STACKEFFECT: dea --- addr

DESCRIPTION:

() Given a dictionary entry addres dea return its code field address addr. By jumping indirectly via this address the definition dea is executed. In ciforth it has offset 0, so it is actually the same as the dea.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ Prefix_' HEADER

## >DFA

STACKEFFECT: dea --- addr

DESCRIPTION:

() Given a dictionary entry addres return its data field address addr . This contains a pointer to the code for a code word, to the data for a word defined by VARIABLE or DATA , to the high level code for a colon-definition, and to the DOES> pointer for a word build using CREATE. Normally this is the area behind the header, found via >PHA .

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ Prefix_' >BODY HEADER

## >FFA

STACKEFFECT: dea --- addr

DESCRIPTION:

() Given a dictionary entry addres return its flag field address addr .

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ Prefix_' HEADER IMMEDIATE PREFIX

## >LFA

STACKEFFECT: dea --- addr

DESCRIPTION:

() Given a dictionary entry addres return its link field address addr. It contains the dea of the previous word.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ Prefix_' HEADER

## >NFA

STACKEFFECT: dea --- nfa

DESCRIPTION:

() Given a dictionary entry addres return the name field address.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ Prefix_' HEADER ID.

## >PHA

STACKEFFECT: dea --- addr

DESCRIPTION:

() Given a dictionary entry addres return the past header address. Here starts the area that no longer belongs to the header of a dictionary entry, but most often it is owned by it.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ Prefix_' HEADER >BODY

## >SFA

STACKEFFECT: dea --- addr

DESCRIPTION:

() Given a dictionary entry addres return the source field address addr. If its content is higher than 1000, that is a pointer to after the name of the definition in the source code. This assumes that the source is still present in memory, which is true during development. If the content is zero, it is a kernel word and the source is not available interactively. Otherwise it is the block number from which the definition was compiled. No attempt is made to erase this information when it becomes incorrect, for e.g. turnkey programs.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ Prefix_' HEADER

## >VFA

STACKEFFECT: dea --- cfa

DESCRIPTION:

() Given the dictionary entry addres of a namespace return the address of the link to the next namespace. Traditionally this was called vocabulary, hence the V.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ NAMESPACE >CFA >WID

## >WID

STACKEFFECT: dea --- wid

DESCRIPTION:

() Given the dictionary entry addres dea of a namespace return its WID wid, a dummy dea that serves as the start of a dictionary search.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ NAMESPACE >VFA (FIND)

## >XFA

STACKEFFECT: dea --- addr

DESCRIPTION:

() Given a dictionary entry addres return the extra field address addr . This is a field in the header that is free for an application to use for whatever purpose.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ Prefix_' OPT HEADER

## FENCE

STACKEFFECT: --- addr

DESCRIPTION:

(FIG,U) A user variable containing an address below which FORGET ting is trapped. To forget below this point the user must alter the contents of FENCE .

GLOSSARY INDEX

SEE ALSO: DICTIONARY~

## FOR-VOCS

STACKEFFECT: x1..xn xt --- x1...xn

DESCRIPTION:

() For all vocabularies execute xt with as data the dea of those words. xt must have the stack diagram x1..xn dea --- x1..xn

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ FOR-WORDS EXECUTE

## FOR-WORDS

STACKEFFECT: x1...xn xt dea --- x1...xn

DESCRIPTION:

() For all words starting with and including dea execute xt with as data x1..xn plus the dea of those words by following the link fields. xt must have the stack diagram x1..xn dea' --- x1..xn. Mostly the dea will identify a WID. In that case all words of a wordlist are handled. If you don't want to include the WID itself, you can ignore it based on the dummy flag in its flag field. Note that you can use the forthdefi({dea}) of any word as a WID and the remainder of the word list will be searched.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ FOR-VOCS EXECUTE

## FORGET-VOC

STACKEFFECT: addr wid --- addr

DESCRIPTION:

() Remove all words whose dea is greater (which mostly means later defined) than addr from a wordlist given by wid . This works too if links have been redirected, such that some earlier words point back to later defined words. Leave addr (as FORGET-VOC is intended to be used with FOR-VOCS) . If any whole namespace is removed, the search order is reset to ONLY FORTH. The space freed is not recovered.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ FORGET

## HIDDEN

STACKEFFECT: dea ---

DESCRIPTION:

() Make the word with dictionary entry address dea unfindable, by toggling the "smudge bit" in a definitions' flag field. If however it was the dea of an unfindable word, it is made findable again. Used during the definition of a colon word to prevents an uncompleted definition from being found during dictionary searches, until compiling is completed without error. It also prevents that a word can be used recursively.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ IMMEDIATE RECURSE

## OPT

STACKEFFECT: sc dea --- sc dea1

DESCRIPTION:

() This is a vector in behalf of optimisation, that starts as a noop, and can be filled in if the extra field is used for optimisation. It must adhere to the following specification: Search down from the dea dea for a word with name sc. Replace dea with dea1 if the dictionary part between both could not contain the name searched for. dea1 being a null pointer means that the dictionary doesn't contain the name.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ ~MATCH FIND >XFA

## ~MATCH

STACKEFFECT: sc dea --- sc dea n

DESCRIPTION:

() Intended to cooperate with (FIND) . Compares the string constant sc with the dea dea's name, Returns into n the difference between the first characters that compare unequal, or zero if the strings are the same up to the smallest length. It is required that the dea contains a pointer to a string variable, which may contain an empty string.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ FOUND CORA

# DOUBLE

OVERVIEW:

The wordset DOUBLE contains words that manipulate double's.

## D+

STACKEFFECT: d1 d2 --- dsum

DESCRIPTION:

(ISO,FIG) Leave the double number dsum: the sum of two double numbers d1 and d2 .

GLOSSARY INDEX

SEE ALSO: DOUBLE DNEGATE +

## DABS

STACKEFFECT: d --- ud

DESCRIPTION:

(ISO,FIG) Leave the absolute value ud of a double number d .

GLOSSARY INDEX

SEE ALSO: DOUBLE DNEGATE ABS

## DNEGATE

STACKEFFECT: d1 --- d2

DESCRIPTION:

(ISO) d2 is the negation of d1.

GLOSSARY INDEX

SEE ALSO: DOUBLE D+

## S>D

STACKEFFECT: n --- d

DESCRIPTION:

(ISO) Sign extend a single number to form a double number.

GLOSSARY INDEX

SEE ALSO: DOUBLE

# ENVIRONMENTS

OVERVIEW:

The wordset ENVIRONMENTS contains all words of the ENVIRONMENT namespace and those words needed to recognize them as Forth environment queries. Note that these are not environment variables in the sense that they are passed from an operating system to a program.

## CORE

STACKEFFECT: --- ff

DESCRIPTION:

(ISO) An environment query whether the CORE wordset is present.

GLOSSARY INDEX

SEE ALSO: ENVIRONMENTS ENVIRONMENT?

## CPU

STACKEFFECT: --- d

DESCRIPTION:

(CI) An environment query returning the cpu-type to be printed as a base-36 number.

GLOSSARY INDEX

SEE ALSO: ENVIRONMENTS ENVIRONMENT?

## ENVIRONMENT?

STACKEFFECT: sc --- i*x true/false

DESCRIPTION:

(ISO) If the string sc is a known environment attribute, leave into i*x the information about that attribute and a true flag, else leave a false flag. In fact the flag indicates whether the words is present in the ENVIRONMENT namespace and i*x is what is left by the word if executed.

GLOSSARY INDEX

SEE ALSO: ENVIRONMENTS NAMESPACE

## NAME

STACKEFFECT: --- sc

DESCRIPTION:

(CI) An environment query giving the name of this Forth as a string constant.

GLOSSARY INDEX

SEE ALSO: ENVIRONMENTS ENVIRONMENT?

## SUPPLIER

STACKEFFECT: --- sc

DESCRIPTION:

(CI) An environment query giving the SUPPLIER of this Forth as a string constant.

GLOSSARY INDEX

SEE ALSO: ENVIRONMENTS ENVIRONMENT?

## VERSION

STACKEFFECT: --- sc

DESCRIPTION:

(CI) An environment query giving the version "5.4.1" of this Forth as a string constant.

GLOSSARY INDEX

SEE ALSO: ENVIRONMENTS ENVIRONMENT?

# ERRORS

OVERVIEW:

The wordset ERRORS contains words to handle errors and exceptions.

## ?ERROR

STACKEFFECT: f n ---

DESCRIPTION:

() If the boolean flag is true, signal an error with number n. This means that an exception is thrown, and it is remembered that this is the original place where the exception originated. If the exception is never caught, an error message is displayed using ERROR . All errors signaled by the kernel go through this word.

GLOSSARY INDEX

SEE ALSO: ERRORS ERROR ?ERRUR THROW

## ?ERRUR

STACKEFFECT: n ---

DESCRIPTION:

() Handle the possible error n in Unix fashion. If it is zero or positive, this means okay. If it is negative, its value identifies an error condition. This error is handled in the same way as by ?ERROR .

GLOSSARY INDEX

SEE ALSO: ERRORS ERROR ?ERROR

## ABORT"

STACKEFFECT: f ---

DESCRIPTION:

(ISO,I,C) Usage is : <SOME> ... ABORT" <message>" ... ;. If ABORT" finds a non-zero f on the stack, the <message> is displayed and an ABORT is executed. Otherwise proceed with the words after <message>. This word can only be used in compile mode.

GLOSSARY INDEX

SEE ALSO: ERRORS ?ERROR

## CATCH

STACKEFFECT: ... xt --- ... tc

DESCRIPTION:

(ISO) Execute xt. If it executes successfully, i.e. no THROW is executed by xt, leave a zero into tc in addition to any stack effect xt itself might have. Otherwise in tc the non-zero throw code is left, and the stack depth is restored. The values of the parameters for xt could have been modified. In general, there is nothing useful that can be done with those stack items. Since the stack depth is known, the application may DROP those items.

GLOSSARY INDEX

SEE ALSO: ERRORS THROW QUIT HANDLER

## ERROR

STACKEFFECT: n ---

DESCRIPTION:

() Notify the user that an uncaught exception or error with number n has occurred. The word that caused it is found using WHERE and displayed . Also n is passed to MESSAGE in order to give a description of the error, clamped to the range [-256, 63]. This word is executed by THROW before restarting the interpreter and can be revectored to give more elaborate diagnostics, or even do a last minute recovery.

GLOSSARY INDEX

SEE ALSO: ERRORS MESSAGE ?ERROR WARNING

## ERRSCR

STACKEFFECT: --- addr

DESCRIPTION:

() A variable containing the address of the number of the screen from which messages are offset. Messages correspond with lines and the offset may be positive or negative. 0 MESSAGE prints the first line of this screen. Traditionally this was screen 4, but the negative Unix error numbers makes this infeasible.

GLOSSARY INDEX

SEE ALSO: ERRORS C/L MESSAGE

## MESSAGE

STACKEFFECT: n ---

DESCRIPTION:

() MESSAGE is generally used to print error and warning messages. If WARNING is zero (disc unavailable), this is a noop. Print on the standard error channel the text of line n relative to screen ERRSCR . n may be positive or negative and beyond just screen ERRSCR. A certain range around 0 is reserved. The messages with small positive offset contain ciforth error messages. The messages with small negative offset contain the strings belonging to the return values for Linux system calls . 0 MESSAGE will print version information about the library file where the messages sit in.

GLOSSARY INDEX

SEE ALSO: ERRORS ERROR BLOCK-FILE

## THROW

STACKEFFECT: ... tc --- ... / ... tc

DESCRIPTION:

(ISO) If tc is zero, it is merely discarded. If we are executing under control of a CATCH , see CATCH for the effect of a non-zero tc. If we are executing not under control of a CATCH, a non-zero tc gives a message to the effect that this exception has occurred and starts Forth anew.

GLOSSARY INDEX

SEE ALSO: ERRORS CATCH QUIT HANDLER ?ERROR ERROR

## WARNING

STACKEFFECT: --- addr

DESCRIPTION:

(FIG,U) A user variable containing a value controlling messages. If it is 1, a library file is assumed to be open, and messages are fetched from it. If it is 0, error messages will be presented by number only.

GLOSSARY INDEX

SEE ALSO: ERRORS MESSAGE ERROR ERRSCR

## WHERE

STACKEFFECT: --- addr

DESCRIPTION:

(U) A user variable pair which contains the start of the source and the position after the last character parsed when an error thrown by ?ERROR, so not of exceptions thrown. The contents of WHERE is interpreted by ERROR if the corresponding exception was never caught.

GLOSSARY INDEX

SEE ALSO: ERRORS THROW CATCH

## (ABORT")

STACKEFFECT: f ---

DESCRIPTION:

() The run time action of ABORT" .

GLOSSARY INDEX

SEE ALSO: ERRORS~

## HANDLER

STACKEFFECT: --- addr

DESCRIPTION:

() A user variable address containing a pointer to the last exception intercepting frame activated by CATCH . It points into the return stack. If there is a THROW, the return stack is restored from HANDLER effecting a multiple level return. It is called a frame because more things are restored, such as the position of the data stack top, and the previous value of HANDLER .

GLOSSARY INDEX

SEE ALSO: ERRORS~ CATCH THROW

# FILES

OVERVIEW:

The wordset FILES contains words to input and output to files, or load words from files. They also are underlying the BLOCKS facilities.

## CLOSE-FILE

STACKEFFECT: fileid --- ior

DESCRIPTION:

(ISO) Close the file with file handle in fileid. Return a result code into ior. The latter is the Linux error code negated, usable as a throw code.

GLOSSARY INDEX

SEE ALSO: FILES OPEN-FILE READ-FILE WRITE-FILE CREATE-FILE DELETE-FILE

## CREATE-FILE

STACKEFFECT: sc fam --- fileid ior

DESCRIPTION:

(ISO) Create a file with name sc and file access method fam . If the file already exists, it is truncated to zero length. Return a file handle into fileid and a result code into ior. The latter is the errno negated, to be inspected using MESSAGE . The handle is open for READ_WRITE, so fam is in fact ignored. The access privileges default to octal 755. This can be changed by applying mask 8 LSHIFT OR where mask contains the privilege bits one wants to change.

GLOSSARY INDEX

SEE ALSO: FILES OPEN-FILE READ-FILE WRITE-FILE DELETE-FILE

## DELETE-FILE

STACKEFFECT: sc --- ior

DESCRIPTION:

(ISO) Delete the file with name sc. Return a result code into ior. The latter is the errno negated, to be inspected using MESSAGE .

GLOSSARY INDEX

SEE ALSO: FILES OPEN-FILE READ-FILE WRITE-FILE CREATE-FILE

## FILE-POSITION

STACKEFFECT: fd --- ud ior

DESCRIPTION:

(ISO) ud is the file current position for the file that is open at fd. ior is 0 for success, or otherwise errno negated . Information about error codes can be found by MESSAGE.

GLOSSARY INDEX

SEE ALSO: FILES OPEN-FILE REPOSITION-FILE

## GET-FILE

STACKEFFECT: sc1 --- sc2

DESCRIPTION:

() Get the content of the file with name sc1; leave it as a string sc2. Any errors are thrown. The file is permanently stored at HERE .

GLOSSARY INDEX

SEE ALSO: FILES PUT-FILE OPEN-FILE THROW

## INCLUDED

STACKEFFECT: sc1 --- i*x

DESCRIPTION:

(ISO) Interpret the content of the file with name sc1 as if it was typed from the console, leaving result i*x. The file is permanently stored in the dictionary, but trimmed in compiled programs.

GLOSSARY INDEX

SEE ALSO: FILES LOAD INCLUDE

## INCLUDE

STACKEFFECT: "name" --- i*x

DESCRIPTION:

(ISO) Interpret the content of the file with "name" as if it was typed from the console, leaving result i*x. The file is permanently stored in the dictionary, but trimmed in compiled programs.

GLOSSARY INDEX

SEE ALSO: FILES LOAD

## OPEN-FILE

STACKEFFECT: sc fam --- fileid ior

DESCRIPTION:

(ISO) Open the file with name sc and file access method fam. Return a file handle into fileid and a result code into ior. The latter is the errno error code negated, usable as a throw code. fam is one of 0=READ_ONLY, 1=WRITE_ONLY, 2=READ_WRITE.

GLOSSARY INDEX

SEE ALSO: FILES READ-FILE WRITE-FILE CREATE-FILE DELETE-FILE CLOSE-FILE

## PUT-FILE

STACKEFFECT: sc1 sc2 ---

DESCRIPTION:

() Save the string constant sc1 to a file with the name sc2. Any errors are thrown.

GLOSSARY INDEX

SEE ALSO: FILES GET-FILE OPEN-FILE THROW

## READ-FILE

STACKEFFECT: addr n1 fd --- n2 ior

DESCRIPTION:

(ISO) Read n characters to addr from current position of the file that is open at fd . n2 is the number of characters successfully read, this may be zero. ior is 0 for success, or otherwise errno error code negated, usable as a throw code.

GLOSSARY INDEX

SEE ALSO: FILES OPEN-FILE WRITE-FILE REPOSITION-FILE BLOCK-READ

## REPOSITION-FILE

STACKEFFECT: ud fd --- ior

DESCRIPTION:

(ISO) Position the file that is open at fd at position ud. ior is 0 for success, or otherwise errno negated . Information about error codes can be found by MESSAGE.

GLOSSARY INDEX

SEE ALSO: FILES OPEN-FILE READ-FILE WRITE-FILE

## WRITE-FILE

STACKEFFECT: addr n fd --- u1

DESCRIPTION:

(ISO) Write n characters from addr to the file that is open at fd , starting at its current position. u1 is 0 for success, or otherwise errno error code negated, usable as a throw code.

GLOSSARY INDEX

SEE ALSO: FILES OPEN-FILE READ-FILE REPOSITION-FILE BLOCK-WRITE

## RW-BUFFER

STACKEFFECT: --- addr

DESCRIPTION:

() A constant that leaves the address of a disk buffer used by file i/o words.

GLOSSARY INDEX

SEE ALSO: FILES~ READ-FILE OPEN-FILE ZEN

# FORMATTING

OVERVIEW:

The wordset FORMATTING generates formatted output for numbers, i.e. printing the digits in a field with a certain width, possibly with sign etc. This is possible in any number base. (Normally base 10 is used, which means that digits are found as a remainder by dividing by 10). Formatting in Forth is always based on double numbers. Single numbers are handled by converting them to double first. This requires some double precision operators to be present in the Forth core. See also DOUBLE wordset. See also MULTIPLYING wordset.

## #>

STACKEFFECT: d --- sc

DESCRIPTION:

(ISO,FIG) Terminates numeric output conversion by dropping d, leaving the formatted string sc .

GLOSSARY INDEX

SEE ALSO: FORMATTING <#

## #S

STACKEFFECT: d1 --- d2

DESCRIPTION:

(ISO,FIG) Generates ASCII text in the text output buffer, by the use of {{{#}}}, until a zero double number d2 results. Used between <# and #>.

GLOSSARY INDEX

SEE ALSO: FORMATTING

## #

STACKEFFECT: d1 --- d2

DESCRIPTION:

(ISO,FIG) Generate from a double number d1, the next ASCII character which is placed in an output string. Result d2 is the quotient after division by BASE, and is maintained for further processing. Used between <# and #>.

GLOSSARY INDEX

SEE ALSO: FORMATTING #S HLD

## <#

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) Setup for pictured numeric output formatting using the words: <# # #S SIGN #> The conversion is done on a double number producing text growing down from PAD .

GLOSSARY INDEX

SEE ALSO: FORMATTING DPL HLD HOLD FLD

## >NUMBER

STACKEFFECT: ud1 addr1 u1 --- ud2 addr2 u2

DESCRIPTION:

(ISO) ud2 is the result of converting the characters within the character string specified by addr1 u1 into digits, using the number in BASE , and adding each into ud1 after multiplying ud1 by the number in BASE . Conversion continues until a character that is not convertible is encountered or the string is entirely converted. addr2 is the location of the first unconverted character or the first character past the end of the string if the string was entirely converted. u2 is the number of unconverted characters in the string. If ud2 overflows, in ciforth ud2 will be incorrect, but no crash will result. Both - and + are considered unconvertible character's by >NUMBER .

GLOSSARY INDEX

SEE ALSO: FORMATTING NUMBER DIGIT DPL

## BASE

STACKEFFECT: --- addr

DESCRIPTION:

(ISO,FIG,U) A user variable containing the current number base used for input and output conversion.

GLOSSARY INDEX

SEE ALSO: FORMATTING DECIMAL HEX <#

## DECIMAL

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) Set the numeric conversion BASE for decimal input-output.

GLOSSARY INDEX

SEE ALSO: FORMATTING HEX

## HEX

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) Set the numeric conversion BASE for hexadecimal (base 16) input-output.

GLOSSARY INDEX

SEE ALSO: FORMATTING DECIMAL

## HOLD

STACKEFFECT: c ---

DESCRIPTION:

(ISO,FIG) Add the character c to the beginning of the output string. It must be executed for numeric formatting inside a <# and #> construct .

GLOSSARY INDEX

SEE ALSO: FORMATTING # DIGIT

## SIGN

STACKEFFECT: n ---

DESCRIPTION:

(ISO,FIG) Add an ASCII minus-sign - inside a <# and #> construct to the beginning of a converted numeric output string in the text output buffer when n is negative. Must be used between <# and #> .

GLOSSARY INDEX

SEE ALSO: FORMATTING HOLD

## (NUMBER)

STACKEFFECT: --- d1

DESCRIPTION:

() Convert the ASCII text at the current input source with regard to BASE . The new value is accumulated into double number d1 , being left. A decimal point, anywhere, signifies that the input is to be considered as a double. ISO requires it to be at the end of the number. ciforth allows any number of decimal points with the same meaning. ciforth also allows any number of comma's that are just ignored, to improve readability. If the first unconvertible digit is not a blank, this is an error. This word is used by all number prefixes. ciforth guarantees that PP points directly after a number parsed, such that for double numbers PP@ DPL @ - 1- gives the number of decimals.

GLOSSARY INDEX

SEE ALSO: FORMATTING~ NUMBER ?BLANK Prefix_7

## DIGIT

STACKEFFECT: c n1 --- n2 true (ok) c n1 --- x false (bad)

DESCRIPTION:

() Converts the ASCII character c (using base n1 ) to its binary equivalent n2 , accompanied by a true flag. If the conversion is invalid, leaves a don't care value and a false flag.

GLOSSARY INDEX

SEE ALSO: FORMATTING~

## DPL

STACKEFFECT: ---- addr

DESCRIPTION:

(FIG,U) A user variable containing the address of the decimal point on double integer or floating point input, or a nil pointer.

GLOSSARY INDEX

SEE ALSO: FORMATTING~ <# FLD HLD

## ECL

STACKEFFECT: ---- addr

DESCRIPTION:

() A user variable containing the address of the exponential sign in a floating point input, or a nil pointer.

GLOSSARY INDEX

SEE ALSO: FORMATTING~ DPL

## FLD

STACKEFFECT: --- addr

DESCRIPTION:

(FIG,U) A user variable for control of number output field width. Unused in the kernel of ciforth.

GLOSSARY INDEX

SEE ALSO: FORMATTING~

## HLD

STACKEFFECT: --- addr

DESCRIPTION:

(FIG) A user variable that holds the address of the latest character of text during numeric output conversion.

GLOSSARY INDEX

SEE ALSO: FORMATTING~ <# DPL FLD HOLD

## NUMBER

STACKEFFECT: --- s/d

DESCRIPTION:

() This word is intended to be called from (aliased as) single character denotation words, marked as PREFIX IMMEDIATE. Therefore it decrements the parse pointer to include this first character. Starting with this character, it converts characters from the current input source into a number, and compiles or executes this number, depending on STATE. If the string contains a decimal point it is a double else a single integer number. If numeric conversion is not possible, an error message will be given. Any comma's in the number are ignored, to help in structuring large numbers. Traditionally comma's also signified double precision numbers. Revectoring forthcode({NUMBER}) affects all applicable number prefixes. In this way floating point numbers can be accomodated.

GLOSSARY INDEX

SEE ALSO: FORMATTING~ BASE (NUMBER)

# INITIALISATIONS

OVERVIEW:

The wordset INITIALISATIONS contains words to initialise, reinitialise or configure Forth.

## +ORIGIN

STACKEFFECT: n --- addr

DESCRIPTION:

() Leave the memory address relative by n bytes to the area from which the user variables are initialised during startup. Given a user variable the phrase >DFA @ +ORIGIN finds the address where its initial value is stored. One can access or modify those boot-up parameters, prior to saving a customised image in behalf of turnkey programs. This will affect the initialisation by COLD. In this forth switching of the user area in behalf of multi-tasking is accomplished automatically when the return stack is switched.

GLOSSARY INDEX

SEE ALSO: INITIALISATIONS USER

## ABORT

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) Restart the interpreter. In addition and before the actions of QUIT, clear also the data stack and reset the exception mechanism. This word is silent. This may be confusing at times, because you can't tell the difference between a word that is still busy or that has aborted.

GLOSSARY INDEX

SEE ALSO: INITIALISATIONS WARM _INIT

## COLD

STACKEFFECT:

DESCRIPTION:

(FIG) When called for the first time it initialises all user variables to their boot up values values, i.a. the stacks and the dictionary pointer . Initialise the system as per _INIT. Handle command line options, if any, as per OPTIONS. Show signon message and restart via ABORT . May be called from the terminal to restart, while keeping all definitions. But it is better to say BYE to Forth and start again.

GLOSSARY INDEX

SEE ALSO: INITIALISATIONS WARM _INIT OPTIONS

## OK

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) Takes care of printing the okay-message, after interpreting a line. Default it prints ``OK'' only for an interactive session in interpret STATE. It can be revectored to show debugging info or give a prompt.

GLOSSARY INDEX

SEE ALSO: INITIALISATIONS QUIT COLD

## OPTIONS

STACKEFFECT: ft --- f2

DESCRIPTION:

(CI) Handle command line option. If an option is given at startup, execute the screen corresponding to the option letter and return a false flag into f2, otherwise leave a true flag. This is used to suppress the signon message if there is an option. An option screen can always decide to execute .SIGNON. By redefining OPTIONS as DROP 0, the handling of options during cold boot is suppressed, useful for turnkey applications.

GLOSSARY INDEX

SEE ALSO: INITIALISATIONS COLD

## QUIT

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) Restart the interpreter. Clear the return stack, stop compilation, and return control to the operators terminal, or to the redirected input stream. This means (ACCEPT) user input to somewhere in the terminal input buffer, and then INTERPRET with that as a SOURCE . No message is given.

GLOSSARY INDEX

SEE ALSO: INITIALISATIONS TIB ABORT

## WARM

STACKEFFECT:

DESCRIPTION:

(FIG) Perform a so called "warm" start. Reinitialise the system as per INIT. Show the signon message and restart via ABORT .

GLOSSARY INDEX

SEE ALSO: INITIALISATIONS ABORT

## _INIT

STACKEFFECT:

DESCRIPTION:

(FIG) Initialise or reinitialise the system. Reset the data stack, the search order, the number base and the exception mechanism. Initialise the block mechanism. Any blocks that have not yet been written back to mass storage are discarded. Now open the file that contains the blocks, in read-only mode. After _INIT we have the following situation. The search order contains the FORTH words, plus ONLY with i.a. number handling. Definitions are added to the FORTH namespace. The number base is decimal.

GLOSSARY INDEX

SEE ALSO: INITIALISATIONS WARM COLD FORTH BLOCK-INIT BASE S0

# INPUT

OVERVIEW:

The wordset INPUT contains words to get input from the terminal and such. See also FILES for disk I/O. See also BLOCKS for access of blocks.

## (ACCEPT)

STACKEFFECT: --- sc

DESCRIPTION:

() Accept characters from the terminal, until a RET is received and return the result as a constant string sc. It doesn't contain any line ending, but the buffer still does and after 1+ the string ends in a LF. The editing functions are the same as with ACCEPT . This is lighter on the system and sometimes easier to use than ACCEPT This input remains valid until the next time that the console buffer is refilled. With TIBSIZE characters the terminal input buffer overflows, with unpredictable results.

GLOSSARY INDEX

SEE ALSO: INPUT KEY KEY? ACCEPT PP@@ REFILL-TIB

## ACCEPT

STACKEFFECT: addr count --- n

DESCRIPTION:

(ISO) Transfer at most count characters from the terminal to addr . The transfer takes place when a RET is received, and excess characters after count are ignored. The simple tty editing functions of Linux are observed, i.e. the ``erase'' (delete a character) and ``kill'' (delete a line) characters. Typically these are the backspace key and ^U. The number of characters not including the RET is returned into n.

GLOSSARY INDEX

SEE ALSO: INPUT (ACCEPT) KEY KEY?

## KEY?

STACKEFFECT: --- ff

DESCRIPTION:

(ISO) Return into ff whether a character is available. The next execution of KEY will return the character immediately.

GLOSSARY INDEX

SEE ALSO: INPUT KEY ACCEPT KEY?

## KEY

STACKEFFECT: --- c

DESCRIPTION:

(ISO,FIG) Leave the ASCII value of the next terminal key struck.

GLOSSARY INDEX

SEE ALSO: INPUT ACCEPT KEY?

## PP

STACKEFFECT: --- addr

DESCRIPTION:

() A user variable containing a pointer within the current input text buffer (terminal or disc) from which the next text will be accepted. All parsing words use and move the value of PP . This is different from how ISO >IN works, in the sense that zeroing it doesn't reset the parse pointer to the start of the current line.

GLOSSARY INDEX

SEE ALSO: INPUT (>IN) WORD NAME NUMBER PARSE PP@@

## RUBOUT

STACKEFFECT: --- c

DESCRIPTION:

() A user variable, leaving the key code that must delete the last character from the input buffer. In this ciforth it is not used, as the terminal input editing is left to the host operating system.

GLOSSARY INDEX

SEE ALSO: INPUT USER

## TIB

STACKEFFECT: --- addr

DESCRIPTION:

(ISO,FIG,U) A user variable containing the address of the terminal input buffer. Traditionally, this was used for file i/o too, but not so in ciforth.

GLOSSARY INDEX

SEE ALSO: INPUT QUIT

## (>IN)

STACKEFFECT: --- addr

DESCRIPTION:

() This is a user variable that is foreseen for code that fakes the behaviour of >IN in ciforth. This could be part of the code loaded by "-legacy-" WANTED . (The word >IN is intended to be used in the context that the source is interpreted line by line.) In ciforth the parse pointer PP is used by the system instead of >IN .

GLOSSARY INDEX

SEE ALSO: INPUT~ >IN PP

## REFILL-TIB

STACKEFFECT: ---

DESCRIPTION:

() Accept characters from the terminal input stream such as to fill up TIB . Normally this means until a RET. It is now consumable by ACCEPT or after SET-SRC by Forth parsing words like NAME . The editing functions are those described by ACCEPT. Immediately, after REFILL-TIB REMAINDER 2@ defines the characters ready in the input buffer. All characters are retained including the RET. If the input is redirected (such that after a RET more characters are available) REMAINDER 2@ contains the part of TIB that is not yet consumed by (ACCEPT) , and outside the reach of SRC . All errors from Linux result in an exception. The end of normal or redirected I/O results in an an end-of-pipe exception in this word, which terminates ci86.lina64.html and is not considered an error condition.

GLOSSARY INDEX

SEE ALSO: INPUT~ ACCEPT (ACCEPT)

## REMAINDER

STACKEFFECT: --- addr

DESCRIPTION:

() A pointer to a constant string that contains the balance of characters fetched from the the input stream, but not yet part of the input buffer. Unless there is redirection from a file, this contains an empty string. Used as in REMAINDER 2@ .

GLOSSARY INDEX

SEE ALSO: INPUT~ REFILL-TIB

## SET-TERM

STACKEFFECT: len b ---

DESCRIPTION:

() Set the terminal length to len and toggle the c_lflag field with b in the termios structure TERMIO . In particular toggling with 0x0A makes that the terminal doesn't wait for a RET. This word is invalid for pipes, and is replaced by a 2DROP in that case.

GLOSSARY INDEX

SEE ALSO: INPUT~ TERMIO KEY

## TERMIO

STACKEFFECT: --- addr

DESCRIPTION:

() Leave the address of the terminal description, this has the layout of a c-structure termios .

GLOSSARY INDEX

SEE ALSO: INPUT~ SET-TERM

# JUGGLING

OVERVIEW:

The wordset JUGGLING contains words that change order of data on the data stack . The necessity for this arise, because the data you want to feed to a Forth word is not directly accessible, i.e. on top of the stack. It is also possible that you need the same data twice, because you have to feed it to two different words. Design your word such that you need them as little as possible, because they are confusing.

## 2DROP

STACKEFFECT: n1 n2 ---

DESCRIPTION:

(ISO) Drop the topmost two numbers (or one double number) from the stack.

GLOSSARY INDEX

SEE ALSO: JUGGLING DROP 2DUP

## 2DUP

STACKEFFECT: d --- d d

DESCRIPTION:

(ISO) Duplicate the double number on the stack.

GLOSSARY INDEX

SEE ALSO: JUGGLING OVER

## 2OVER

STACKEFFECT: d1 d2 --- d1 d2 d1

DESCRIPTION:

(ISO) Copy the second stack double, placing it as the new top.

GLOSSARY INDEX

SEE ALSO: JUGGLING OVER

## 2SWAP

STACKEFFECT: d1 d2 --- d2 d1

DESCRIPTION:

(ISO) Exchange the top doubles on the stack.

GLOSSARY INDEX

SEE ALSO: JUGGLING SWAP

## ?DUP

STACKEFFECT: n1 --- n1 (if zero) / n1 --- n1 n1 (non-zero)

DESCRIPTION:

(ISO,FIG) Reproduce n1 only if it is non-zero. This is usually used to copy a value just before IF , to eliminate the need for an ELSE part to drop it.

GLOSSARY INDEX

SEE ALSO: JUGGLING DUP _

## DROP

STACKEFFECT: n ---

DESCRIPTION:

(ISO,FIG) Drop the number from the stack.

GLOSSARY INDEX

SEE ALSO: JUGGLING DUP SWAP OVER

## DUP

STACKEFFECT: n --- n n

DESCRIPTION:

(ISO,FIG) Duplicate the value on the stack.

GLOSSARY INDEX

SEE ALSO: JUGGLING OVER SWAP DROP

## NIP

STACKEFFECT: n1 n2---n2

DESCRIPTION:

(ISO) Drop the second number from the stack.

GLOSSARY INDEX

SEE ALSO: JUGGLING DUP DROP SWAP OVER

## OVER

STACKEFFECT: nl n2 --- nl n2 n1

DESCRIPTION:

(ISO,FIG) Copy the second stack value, placing it as the new top.

GLOSSARY INDEX

SEE ALSO: JUGGLING DUP

## ROT

STACKEFFECT: nl n2 n3 --- n2 n3 nl

DESCRIPTION:

(ISO,FIG) Rotate the top three values on the stack, bringing the third to the top.

GLOSSARY INDEX

SEE ALSO: JUGGLING SWAP

## SWAP

STACKEFFECT: n1 n2 --- n2 n1

DESCRIPTION:

(ISO,FIG) Exchange the top two values on the stack.

GLOSSARY INDEX

SEE ALSO: JUGGLING ROT

# LIBRARY

OVERVIEW:

The words of the library have nothing particular in common, except that they are available in the Library Accessable by Block LAB and not the ciforth kernel. All of them can be loaded from the library by WANT SOME_WORD. Most common ISO words are available. The assembler is loaded by WANT ASSEMBLERi86 . Floating point is loaded by WANT -fp- . Interactive controle structures are loaded by WANT -scripting- . Multi-tasking is loaded by WANT THREAD-PET . The memory wordset is loaded by WANT ALLOCATE . Useful application words in the LAB are i.a. : ALIAS QSORT MERGE-SORT . Useful debugging words in the LAB are i.a. : DO-DEBUG LOCATE SEE REGRESS . Non-iso words are supposedly usable from the description that goes with the code.

# LOGIC

OVERVIEW:

The wordset LOGIC contains logic operators and comparison operators. A comparison operator (such as = ) delivers a Forth flag, -1 for true, 0 for false, representing a condition (such as equality of two numbers). The number -1 has all bits set to one. The logical operators ( AND etc.) work on all 64 bits, one by one. In this way they are useful for mask operations, as well as for combining conditions represented as flag's. But beware that IF only cares whether the top of the stack is non-zero, such that - can mean non-equal to IF. Such conditions (often named just flag's) cannot be directly combined using logical operators, but 0= 0= can help.

## 0<

STACKEFFECT: n --- ff

DESCRIPTION:

(ISO,FIG) Leave a true flag if the number is less than zero (negative), otherwise leave a false flag.

GLOSSARY INDEX

SEE ALSO: LOGIC < 0=

## 0=

STACKEFFECT: n --- ff

DESCRIPTION:

(ISO,FIG) Leave a true flag ff is the number n is equal to zero, otherwise leave a false flag. It may be aliased to NOT , which inverts a flag.

GLOSSARY INDEX

SEE ALSO: LOGIC = 0<

## <>

STACKEFFECT: n1 n2 --- ff

DESCRIPTION:

(ISO) Leave a true flag if n1 is not equal than n2 ; otherwise leave a false flag.

GLOSSARY INDEX

SEE ALSO: LOGIC > = 0<

## <

STACKEFFECT: n1 n2 --- ff

DESCRIPTION:

(ISO) Leave a true flag if n1 is less than n2 ; otherwise leave a false flag.

GLOSSARY INDEX

SEE ALSO: LOGIC = > 0<

## =

STACKEFFECT: n1 n2 --- ff

DESCRIPTION:

(ISO,FIG) Leave a true flag if n1=n2 ; otherwise leave a false flag.

GLOSSARY INDEX

SEE ALSO: LOGIC < > 0= -

## >

STACKEFFECT: n1 n2 --- ff

DESCRIPTION:

(ISO) Leave a true flag if n1 is greater than n2 ; otherwise leave a false flag.

GLOSSARY INDEX

SEE ALSO: LOGIC < = 0<

## AND

STACKEFFECT: n1 n2 --- n3

DESCRIPTION:

(ISO,FIG) Leave the bitwise logical and of n1 and n2 as n3 . For Forth flags (0 or -1) this is the logical and operator.

GLOSSARY INDEX

SEE ALSO: LOGIC XOR OR

## INVERT

STACKEFFECT: n1 --- n2

DESCRIPTION:

(ISO) Invert all bits of n1 leaving n2 . For pure flags (0 or -1) this is the logical not operator.

GLOSSARY INDEX

SEE ALSO: LOGIC AND OR

## OR

STACKEFFECT: n1 n2 --- n3

DESCRIPTION:

(ISO,FIG) Leave the bit-wise logical or of two 64-bit values. For Forth flags (0 or -1) this is the logical or operator.

GLOSSARY INDEX

SEE ALSO: LOGIC AND XOR

## U<

STACKEFFECT: u1 u2 --- ff

DESCRIPTION:

(ISO) Leave a true flag if u1 is less than u2 ; otherwise leave a false flag.(Interpreted as unsigned numbers).

GLOSSARY INDEX

SEE ALSO: LOGIC <

## XOR

STACKEFFECT: nl n2 --- n3

DESCRIPTION:

(ISO,FIG) Leave the bitwise logical exclusive or of two 64-bit values. For Forth flags (0 or -1) this is the logical xor operator.

GLOSSARY INDEX

SEE ALSO: LOGIC AND OR

# MEMORY

OVERVIEW:

The wordset MEMORY contains words to fetch and store numbers from doubles, cells or bytes in memory. There are also words to copy blocks of memory or fill them, and words that fetch a cell, operate on it and store it back.

## !

STACKEFFECT: n addr ---

DESCRIPTION:

(ISO,FIG) Store all 64 bits of n at addr .

GLOSSARY INDEX

SEE ALSO: MEMORY @ C! 2! FAR! PW! PC!

## +!

STACKEFFECT: n addr ---

DESCRIPTION:

(ISO,FIG) Add n to the value at addr.

GLOSSARY INDEX

SEE ALSO: MEMORY TOGGLE !

## 2!

STACKEFFECT: x1 x2 addr ---

DESCRIPTION:

(ISO) Store a pair of 64 bits values x1 x2 to consecutive cells at addr . x2 is stored at the lowest address.

GLOSSARY INDEX

SEE ALSO: MEMORY 2@ ! C!

## 2@

STACKEFFECT: addr--- x1 x2

DESCRIPTION:

(ISO) Leave a pair of 64 bits values x1 x2 from consecutive cells at addr . x2 is fetched from the lowest address.

GLOSSARY INDEX

SEE ALSO: MEMORY 2! @ C@

## @

STACKEFFECT: addr --- n

DESCRIPTION:

(ISO,FIG) Leave the 64 bit contents n of addr .

GLOSSARY INDEX

SEE ALSO: MEMORY ! C@ 2@ PW@ PC@ FAR@

## ALIGNED

STACKEFFECT: addr1 --- addr2

DESCRIPTION:

(ISO) Make sure that addr1 is aligned by advancing it if necessary to addr2.

GLOSSARY INDEX

SEE ALSO: MEMORY ALIGN

## ALIGN

STACKEFFECT: ---

DESCRIPTION:

(ISO) Make sure that HERE is aligned by advancing it if necessary. This means that data of any size can be fetched from that address efficiently.

GLOSSARY INDEX

SEE ALSO: MEMORY ALIGNED

## BLANK

STACKEFFECT: addr count ---

DESCRIPTION:

(ISO) This is shorthand for ``BL FILL''.

GLOSSARY INDEX

SEE ALSO: MEMORY

## BM

STACKEFFECT: ---- addr

DESCRIPTION:

() A constant leaving the address of the lowest memory in use by Forth.

GLOSSARY INDEX

SEE ALSO: MEMORY DP EM

## C!

STACKEFFECT: b addr ---

DESCRIPTION:

(ISO) Store 8 bits of b at addr . In ciforth , running on the Intel architectures there are no restrictions regarding byte addressing.

GLOSSARY INDEX

SEE ALSO: MEMORY C@ !

## C@

STACKEFFECT: addr --- b

DESCRIPTION:

(ISO) Leave the 8 bit contents of memory address. In ciforth , running on the Intel architectures there are no restrictions regarding byte addressing.

GLOSSARY INDEX

SEE ALSO: MEMORY C! @ 2@

## CELL+

STACKEFFECT: n1 --- n2

DESCRIPTION:

(ISO) Advance the memory pointer n1 by one (in this case 64 bits) cell to n2. This is invaluable for writing portable code. Much of the library code of ciforth runs on 64, 32 and 16 bits systems, thanks to this.

GLOSSARY INDEX

SEE ALSO: MEMORY

## CELLS

STACKEFFECT: n1 --- n2

DESCRIPTION:

(ISO) Return the equivalent of n1 cells in bytes: n2. This is invaluable for writing portable code. Much of the library code of ciforth runs on 64, 32 and 16 bits systems, thanks to this.

GLOSSARY INDEX

SEE ALSO: MEMORY CELL+

## CHAR+

STACKEFFECT: n1 --- n2

DESCRIPTION:

(ISO) Advance the memory pointer n1 by one character to n2. In ciforth this means one byte. Bytes are the address units ISO is talking about. Unfortunately the ISO standard has no way to address bytes.

GLOSSARY INDEX

SEE ALSO: MEMORY CELL+

## CHARS

STACKEFFECT: n1 --- n2

DESCRIPTION:

(ISO) Return the equivalent of n1 chars in bytes: n2. In ciforth this is a NOOP. Unfortunately the ISO standard has no way to address bytes.

GLOSSARY INDEX

SEE ALSO: MEMORY CELLS

## CMOVE

STACKEFFECT: from to count ---

DESCRIPTION:

() Move the count quantity of characters beginning at address from to address to . The contents of address from is moved first proceeding toward high memory, such that memory propagation occurs. As the Intel 86-family is byte-addressing there are no restrictions in ciforth.

GLOSSARY INDEX

SEE ALSO: MEMORY MOVE CHARS

## CORA

STACKEFFECT: addr1 addr2 len --- n

DESCRIPTION:

(CIF) Compare the memory areas at addr1 and addr2 over a length len . For the first bytes that differ, return -1 if the byte from addr1 is less (unsigned) than the one from addr2, and 1 if it is greater. If all len bytes are equal, return zero. This is an abbreviation of COMPARE-AREA.

GLOSSARY INDEX

SEE ALSO: MEMORY

## EM

STACKEFFECT: ---- addr

DESCRIPTION:

() A constant leaving the address just above the highest memory in use by Forth.

GLOSSARY INDEX

SEE ALSO: MEMORY DP BM

## ERASE

STACKEFFECT: addr n ---

DESCRIPTION:

(ISO) This is shorthand for 0 FILL.

GLOSSARY INDEX

SEE ALSO: MEMORY BLANK FILL

## FILL

STACKEFFECT: addr u b ---

DESCRIPTION:

(ISO,FIG) If u is not zero, store b in each of u consecutive bytes of memory beginning at addr .

GLOSSARY INDEX

SEE ALSO: MEMORY BLANK ERASE

## L!

STACKEFFECT: u addr ---

DESCRIPTION:

() Store the 32-bit contents of u at addr .

GLOSSARY INDEX

SEE ALSO: MEMORY L@ ! C! 2! PW! PC! FAR!

## L@

STACKEFFECT: addr --- u

DESCRIPTION:

(ISO,FIG) Leave the 32 bit contents u of addr .

GLOSSARY INDEX

SEE ALSO: MEMORY ! C@ 2@ PW@ PC@ FAR@

## MOVE

STACKEFFECT: from to count ---

DESCRIPTION:

(ISO) Move count bytes beginning at address from to address to, such that the destination area contains what the source area contained, regardless of overlaps. As the Intel 86-family is byte-addressing there are no restrictions. Because in ciforth bytes (address units) and characters are the same the difference with CMOVE amounts to MOVE being an intelligent move.

GLOSSARY INDEX

SEE ALSO: MEMORY

## PC!

STACKEFFECT: b port ---

DESCRIPTION:

() Store a byte b to the port address port. You can use ports only after asking permission (using e.g. ioperm ) and being super user.

GLOSSARY INDEX

SEE ALSO: MEMORY PC@ PW! P@ !

## PC@

STACKEFFECT: port --- b

DESCRIPTION:

() Fetch a byte b from the port address You can use ports only after asking permission (using e.g. ioperm ) and being super user.

GLOSSARY INDEX

SEE ALSO: MEMORY PC! PW@ PW! @

## PW!

STACKEFFECT: n port ---

DESCRIPTION:

() Store the 16-bit data n to the 16-bits port address port. You can use ports only after asking permission (using e.g. ioperm ) and being super user.

GLOSSARY INDEX

SEE ALSO: MEMORY PW@ PC! PC@ !

## PW@

STACKEFFECT: port --- n

DESCRIPTION:

() Fetch the 16-bit contents n from the port address port. You can use ports only after asking permission (using e.g. ioperm ) and being super user.

GLOSSARY INDEX

SEE ALSO: MEMORY PW! PC@ PC! @

## TASK-SIZE

STACKEFFECT: ---- n

DESCRIPTION:

() A constant leaving the total size of the per task areas: data stack, return stack, terminal input buffer plus user area. The data stack of the main task runs down to HERE .

GLOSSARY INDEX

SEE ALSO: MEMORY DSP@ RSP@ TIB

## TOGGLE

STACKEFFECT: addr b ---

DESCRIPTION:

(NFIG) Complement the contents of addr by the bit pattern b .

GLOSSARY INDEX

SEE ALSO: MEMORY XOR +!

## WITHIN

STACKEFFECT: n1 n2 n3 --- ff

DESCRIPTION:

(ISO) Return a flag indicating that n1 is in the range n2 (inclusive) to n3 (non-inclusive). This works for signed as well as unsigned numbers. This is shorthand for: OVER - >R - R U<

GLOSSARY INDEX

SEE ALSO: MEMORY < U<

# MISC

OVERVIEW:

The wordset MISC contains words that defy categorisation.

## .SIGNON

STACKEFFECT: ---

DESCRIPTION:

() Print a message identifying the version of this Forth. The name of the processor known from the environment query CPU is printed using the bizarre convention of a base-36 number. This is a tribute to those FIG-pioneers.

GLOSSARY INDEX

SEE ALSO: MISC ABORT COLD

## EXECUTE

STACKEFFECT: xt ---

DESCRIPTION:

(ISO,FIG) Execute the definition whose execution token is given by xt . The code field address serves as an execution token. (It even has offset 0, but one should not assume that a dea is an execution token in portable code.)

GLOSSARY INDEX

SEE ALSO: MISC ' >CFA

## NOOP

STACKEFFECT:

DESCRIPTION:

() Do nothing. Primarily useful as a placeholder.

GLOSSARY INDEX

SEE ALSO: MISC

## TASK

STACKEFFECT:

DESCRIPTION:

() A no-operation word which marks the boundary between the Forth system and applications.

GLOSSARY INDEX

SEE ALSO: MISC COLD

## U0

STACKEFFECT: --- addr

DESCRIPTION:

() A user variable, leaving the start address of the user area. This is for reference only. After initialisation user variables derive their start address from the return stack pointer. This might be used for task switching.

GLOSSARY INDEX

SEE ALSO: MISC USER +ORIGIN

## _

STACKEFFECT: --- x

DESCRIPTION:

() Leave an undefined value x. Presumably it is to be dropped at some time, or it is a place holder.

GLOSSARY INDEX

SEE ALSO: MISC

# MULTIPLYING

OVERVIEW:

The original 16 bits Forth's have problems with overflow (See also OPERATOR). Operators with intermediate results of double precision, mostly scaling operators, solve this and are present in the See also MULTIPLYING wordset. In this 64 bit Forth you will have less need, but scaling remains tricky. When you divide a 2.n digit number by an n digit number you get an n-digit quotient and an n-digit remainder. So naturally many operators in this set have a mix of double and single numbers in their stack diagram: they are mixed magnitude. All those have M in the name. Furthermore all operations are signed, with the exception of the ones starting with U . Those have unsigned operands exclusively. The irregularly named word M/MOD is a relic from the fig-forth era; preferably its alias UDM/MOD is to be used. Output formatting is done with double's exclusively, and relies on this wordset and the DOUBLE wordset. Operators with mixed magnitude and unsigned operators allow to build arbitrary precision operators from them in high level code.

## */MOD

STACKEFFECT: n1 n2 n3 --- n4 n5

DESCRIPTION:

(ISO,FIG) Leave the quotient n5 and remainder n4 of the operation n1*n2/n3 (using symmetric division). A double precision intermediate product is used giving correct results, unless n4 overflows. Then ciforth will give a floating point exception.

GLOSSARY INDEX

SEE ALSO: MULTIPLYING */ /MOD

## */

STACKEFFECT: n1 n2 n3 --- n4

DESCRIPTION:

(ISO,FIG) Leave the ratio n4 = n1*n2/n3 where all are signed numbers(using symmetric division). A double precision intermediate product is used giving correct results, unless n4 overflows. Then ciforth will give a floating point exception.

GLOSSARY INDEX

SEE ALSO: MULTIPLYING */MOD /MOD

## FM/MOD

STACKEFFECT: d n1 --- n2 n3

DESCRIPTION:

(ISO) A mixed magnitude math operator which leaves the signed remainder n2 and signed quotient n3 from a double number dividend d and divisor n1. This is floored division{}, i.e. the remainder takes its sign from the divisor.

GLOSSARY INDEX

SEE ALSO: MULTIPLYING SM/REM UDM/MOD / M*

## M*

STACKEFFECT: n1 n2 --- d

DESCRIPTION:

(ISO,FIG) A mixed magnitude math operation which leaves the double number d : the signed product of two signed number n1 and n2 .

GLOSSARY INDEX

SEE ALSO: MULTIPLYING UDM/MOD SM/REM *

## M/MOD

STACKEFFECT: ud1 u2 --- u3 ud4

DESCRIPTION:

(CIF,FIG) This is an irregarly named alias of UDM/MOD .

GLOSSARY INDEX

SEE ALSO: MULTIPLYING UDM/MOD

## SM/REM

STACKEFFECT: d n1 --- n2 n3

DESCRIPTION:

(ISO) A mixed magnitude math operator which leaves the signed remainder n2 and signed quotient n3 from a double number dividend d and divisor n1. This is a symmetric division{}, i.e. the remainder takes its sign from the dividend.

GLOSSARY INDEX

SEE ALSO: MULTIPLYING UDM/MOD FM/MOD / M*

## UDM/MOD

STACKEFFECT: ud1 u2 --- u3 ud4

DESCRIPTION:

(CIF,FIG) An unsigned mixed magnitude math operation which leaves a double quotient ud4 and remainder u3 , from a double dividend ud1 and single divisor u2. Unlike with UM/MOD the quotient can not overflow. The traditional alias forthcdefi(M/MOD) dates from the fig-forth era.

GLOSSARY INDEX

SEE ALSO: MULTIPLYING UM/MOD SM/REM M*

## UM*

STACKEFFECT: u1 u2 --- ud

DESCRIPTION:

(ISO) A mixed magnitude math operation which leaves the double number ud : the unsigned product of two unsigned numbers u1 and u2 .

GLOSSARY INDEX

SEE ALSO: MULTIPLYING UM/MOD M* *

## UM/MOD

STACKEFFECT: ud u1 --- u2 u3

DESCRIPTION:

(ISO) Leave the unsigned remainder u2 and unsigned quotient u3 from the unsigned double dividend ud and unsigned divisor u1 .

GLOSSARY INDEX

SEE ALSO: MULTIPLYING UM* SM/REM /

# OPERATINGSYSTEM

OVERVIEW:

The wordset OPERATINGSYSTEM contains words that call the underlying operating system or functions available in the BIOS-rom.

## ARGS

STACKEFFECT: --- addr

DESCRIPTION:

() Return the addr of ARGS a user variable that contains a system dependant pointer to any arguments that are passed from the operating system to ciforth during startup. In this ciforth it points to an area with the argument count, followed by a null ended array of arguments c-strings, then by a null ended array of environment c-strings. C-string are chars followed by a zero byte and no preceeding count.

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM SYSTEM

## BYE

STACKEFFECT: ---

DESCRIPTION:

(ISO) Return to the host environment Linux.

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM COLD EXIT-CODE

## EXIT-CODE

STACKEFFECT: addr ---

DESCRIPTION:

() Return addr the address of a variable with the exit code. Its content is passed to the host environment while going BYE . It is custom to return zero if there are no errors. Linux allows only single byte return codes.

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM BYE

## MS

STACKEFFECT: n ---

DESCRIPTION:

(ISO) Wait for n milliseconds.

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM KEY?

## SHELL

STACKEFFECT: ---addr

DESCRIPTION:

() Leave the address addr of a string variable, the name of a file that contains the command interpreter, or shell. This name may be changed and is used by the SYSTEM command. The name may contain a path and be at most 252 characters long. The default name is /bin/sh .

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM SYSTEM $@

## SYSTEM

STACKEFFECT: sc ---

DESCRIPTION:

(ISO) Have the operating system execute the command contained in the string sc.

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM ?ERRUR SHELL

## XOS5

STACKEFFECT: n1 n2 n3 n4 n5 n---ret

DESCRIPTION:

() Do a traditional Unix type system call n (man 2) with parameters n1 n2 n3 n4 n5. ret is the return value of the call. If it is negative, it is mostly an error, such as known by errno . This makes available all facilities present in Linux.

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM ?ERRUR

## XOS

STACKEFFECT: n1 n2 n3 n---ret

DESCRIPTION:

() Do a traditional Unix type system call n (man 2) with parameters n1 n2 n3. ret is the return value of the call. If it is negative, it is mostly an error. Note, that the c standard library functions store the return value in errno and return -1. This makes available all facilities present in Linux, except those with 4 or 5 parameters that are handled by XOS5 .

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM ?ERRUR

## ZEN

STACKEFFECT: sc --- addr

DESCRIPTION:

() Leaves an address that contains a zero-ended (c-type) equivalent of sc. The same buffer (in fact RW-BUFFER) is reused, such that this word is not reentrant. The size available is SIZE_RWBUF minus one for the zero character. Use the word immediately, its intended used is passing parameters to the operating system.

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM OPEN-FILE XOS XOS5

# OPERATOR

OVERVIEW:

The wordset OPERATOR contains the familiar operators for addition, multiplication etc. The result of the operation is always an integer number, so division can't be precise. On ciforth all division operations are compatible with symmetric division. The ISO standard require a Forth to choose between floored or symmetric division for its standard operations. Divisions involving negative numbers have an interpretation problem. In any case we want the combination of / and MOD (remainder) to be such that you can get the original n back from the two values left by n m MOD and n m / by performing m * + . This is true for all Forth's. On ciforth the / is a symmetric division, i.e. -n m / give the same result as n m /, but negated. The foregoing rule now has the consequence that m MOD has 2|m|-1 possible outcomes instead of |m| . This is very worrisome for mathematicians, who stick to the rule that m MOD has |m| outcomes: 0 ... |m|-1, or -|m|+1 ... 0 for negative numbers. (floored division).

## *

STACKEFFECT: n1 n2 --- n3

DESCRIPTION:

(ISO,FIG) Leave the signed product n3 of two signed numbers n1 and n2 .

GLOSSARY INDEX

SEE ALSO: OPERATOR + - / MOD

## +

STACKEFFECT: n1 n2 --- sum

DESCRIPTION:

(ISO,FIG) Leave the sum of n1 and n2 .

GLOSSARY INDEX

SEE ALSO: OPERATOR - * / MOD

## -

STACKEFFECT: n1 n2 --- diff

DESCRIPTION:

(ISO,FIG) Leave the difference of n1 and n2 .

GLOSSARY INDEX

SEE ALSO: OPERATOR NEGATE + * / MOD

## /MOD

STACKEFFECT: n1 n2 --- rem quot

DESCRIPTION:

(ISO,FIG) Leave the remainder and signed quotient of n1 and n2 . The remainder has the sign of the dividend (i.e. symmetric division).

GLOSSARY INDEX

SEE ALSO: OPERATOR */MOD */ SM/REM

## /

STACKEFFECT: n1 n2 --- quot

DESCRIPTION:

(ISO,FIG) Leave the signed quotient of n1 and n2 . (using symmetric division).

GLOSSARY INDEX

SEE ALSO: OPERATOR + - * MOD */MOD

## ABS

STACKEFFECT: n --- u

DESCRIPTION:

(ISO,FIG) Leave the absolute value of n as u .

GLOSSARY INDEX

SEE ALSO: OPERATOR DABS

## LSHIFT

STACKEFFECT: u1 n --- u2

DESCRIPTION:

(ISO) Perform a logical {{{shift}}} of the bits of u1 to the left by n places. Put zero into the places uncovered by the {{{{shift}}}}.

GLOSSARY INDEX

SEE ALSO: OPERATOR RSHIFT 2*

## MAX

STACKEFFECT: n1 n2 --- max

DESCRIPTION:

(ISO,FIG) Leave the greater of two numbers.

GLOSSARY INDEX

SEE ALSO: OPERATOR MIN

## MIN

STACKEFFECT: n1 n2 --- min

DESCRIPTION:

(ISO,FIG) Leave the smaller of two numbers.

GLOSSARY INDEX

SEE ALSO: OPERATOR MAX

## MOD

STACKEFFECT: n1 n2 --- mod

DESCRIPTION:

(ISO,FIG) Leave the remainder of n1 divided by n2 , with the same sign as n1 (i.e. symmetric division).

GLOSSARY INDEX

SEE ALSO: OPERATOR + - * / MOD */MOD

## NEGATE

STACKEFFECT: n1 --- n2

DESCRIPTION:

(ISO,FIG) Leave the two's complement of a number, i.e. n2 is -n1

GLOSSARY INDEX

SEE ALSO: OPERATOR -

## RSHIFT

STACKEFFECT: u1 n --- u2

DESCRIPTION:

(ISO) Perform a logical {{{shift}}} of the bits of u1 to the right by n places. Put zero into the places uncovered by the {{{{shift}}}}.

GLOSSARY INDEX

SEE ALSO: OPERATOR LSHIFT 2/

# OUTPUT

OVERVIEW:

The wordset OUTPUT contains words to output to the terminal and such. See also FILES for disk I/O. See also BLOCKS for blocks.

## (D.R)

STACKEFFECT: d n ---sc

DESCRIPTION:

(ISO,FIG) Format a signed double number d right aligned in a field n characters wide to the string sc. Enlarge the field, if needed. So a field length of 0 results effectively in free format.

GLOSSARY INDEX

SEE ALSO: OUTPUT OUT D. D.R

## ."

STACKEFFECT:

DESCRIPTION:

(ISO,FIG,I) Used in the form: ." cccc" In a definition it compiles an in-line string cccc (as if the denotation "cccc" was used) followed by TYPE . In ciforth ." behaves the same way in interpret mode. In ciforth the number of characters has no limit. In ciforth ." always has an effect on HERE during interpretation. In ISO programs you may only use this word during compilation. We recommend that ." cccc" is replaced by "cccc" TYPE.

GLOSSARY INDEX

SEE ALSO: OUTPUT OUT

## .(

STACKEFFECT:

DESCRIPTION:

(I) In ciforth this is an alias for ." , except that the string is closed with ) instead of parsed as per " . In ISO programs you may only use this word while interpreting. We recommend that .( cccc) is replaced by "cccc" TYPE.

GLOSSARY INDEX

SEE ALSO: OUTPUT OUT ."

## .R

STACKEFFECT: n1 n2 ---

DESCRIPTION:

() Print a signed number n1 right aligned in a field n2 characters wide. Enlarge the field, if needed. So a field length of 0 results effectively in free format.

GLOSSARY INDEX

SEE ALSO: OUTPUT OUT . (D.R)

## .

STACKEFFECT: n ---

DESCRIPTION:

(ISO,FIG) Print the number n1 observing the current BASE, followed by a blank.

GLOSSARY INDEX

SEE ALSO: OUTPUT OUT U. .R D.R D. (D.R)

## ?

STACKEFFECT: addr ---

DESCRIPTION:

(ISO,FIG) Print the value contained at the address addr observing the current BASE, followed by a blank.

GLOSSARY INDEX

SEE ALSO: OUTPUT OUT .

## CR

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) Transmit character(s) to the terminal, that result in a "carriage return" and a "line feed". This means that the cursor is positioned at the start of the next line, if needed the display is scrolled.

GLOSSARY INDEX

SEE ALSO: OUTPUT OUT

## D.R

STACKEFFECT: d n ---

DESCRIPTION:

(ISO,FIG) Print a signed double number d right aligned in a field n characters wide. Enlarge the field, if needed. So a field length of 0 results effectively in free format.

GLOSSARY INDEX

SEE ALSO: OUTPUT OUT D. (D.R)

## D.

STACKEFFECT: d ---

DESCRIPTION:

(ISO,FIG) Print the signed double number d, observing the current BASE, followed by a blank.

GLOSSARY INDEX

SEE ALSO: OUTPUT OUT . D.R (D.R)

## EMIT

STACKEFFECT: c ---

DESCRIPTION:

(ISO,FIG) Transmit ASCII character c to the output device. For this ciforth all terminal I/O goes through TYPE. In this ciforth EMIT maintains OUT.

GLOSSARY INDEX

SEE ALSO: OUTPUT TYPE OUT

## ETYPE

STACKEFFECT: addr count ---

DESCRIPTION:

() Transmit count characters from addr to the standard error device. It is high level so error output can be redirected, by revectoring it. Or you may use redirection by Linux. In this ciforth strings may contain embedded LF 's with the effect of a new line at that point in the output.

GLOSSARY INDEX

SEE ALSO: OUTPUT EMIT TYPE

## OUT

STACKEFFECT: --- addr

DESCRIPTION:

(U) A user variable that reflects the position at the current line of the output device where the next character transmitted will appear. The first position is zero. Only an explicit CR will reset OUT , not an LF embedded in a string that is TYPEd.

GLOSSARY INDEX

SEE ALSO: OUTPUT EMIT TYPE CR

## SPACES

STACKEFFECT: n ---

DESCRIPTION:

(ISO,FIG) If n is greater or equal to zero, display as much spaces.

GLOSSARY INDEX

SEE ALSO: OUTPUT SPACE OUT

## SPACE

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) Transmit an ASCII blank to the output device.

GLOSSARY INDEX

SEE ALSO: OUTPUT EMIT OUT

## TYPE

STACKEFFECT: addr count ---

DESCRIPTION:

(ISO,FIG) Transmit count characters from addr to the output device. All terminal I/O goes through this word. It is high level so terminal I/O can be redirected, by revectoring it and the usual redirection or tee-ing by _OS_. In this ciforth strings may contain embedded LF 's with the effect of a new line at that point in the output, however in that case OUT is not observed.

GLOSSARY INDEX

SEE ALSO: OUTPUT EMIT OUT ETYPE

## U.

STACKEFFECT: u ---

DESCRIPTION:

(ISO) Print the unsigned number u observing the current BASE, followed by a blank.

GLOSSARY INDEX

SEE ALSO: OUTPUT OUT . .R D.R D. (D.R)

# PARSING

OVERVIEW:

The outer interpreter is responsible for parsing, i.e. it gets a word from the current input source and interprets or compiles it, advancing the PP pointer. The wordset PARSING contains the words used by this interpreter and other words that consume characters from the input source. In this way the outer interpreter need not be very smart, because its capabilities can be extended by new words based on those building blocks.

## ?BLANK

STACKEFFECT: c --- ff

DESCRIPTION:

() For the character c return whether this is considered to be white space into the flag ff . At least the space, ASCII null, the tab and the carriage return and line feed characters are white space. In ciforth all control characters are considered white space.

GLOSSARY INDEX

SEE ALSO: PARSING BL SPACE

## CHAR

STACKEFFECT: --- c

DESCRIPTION:

(ISO,I) Parse a word and leave c the first non blank char of that word in the input source. If compiled the searching is done while the word being compiled is executed. Because this is so confusing, it is recommended that one never compiles or postpones CHAR.

GLOSSARY INDEX

SEE ALSO: PARSING Prefix_& [CHAR] '

## EVALUATE

STACKEFFECT: sc --- ??

DESCRIPTION:

(ISO) Interpret the content of sc. Afterwards return to the current input source .

GLOSSARY INDEX

SEE ALSO: PARSING LOAD INCLUDE SET-SRC

## INTERPRET

STACKEFFECT: ?? --- ??

DESCRIPTION:

() Repeatedly fetch the next text word from the current input source and execute it (STATE is 0) or compile it (STATE is 1). A word is blank-delimited and looked up in the vocabularies of search-order. It can be either matched exactly, or it can match a prefix. If it is matched regularly the parse pointer remains after the blank delimiter as required by ISO. If a word matches a prefix, INTERPRET sets back the parse pointer to immediately after the prefix, A word that matches a prefix is called a denotation; mostly this is a number. If it is not found at all, it is an ERROR. Prefixes are present in the namespace ONLY which comprises the minimum search order and is always present as the last wordlist in the search order. An application can add prefixes in whatever namespace is suitable. A denotation is a number, a double number, a character or a string etc. Denotations are handled respectively by the words 0 ... F & " and any other word of the ONLY wordlist, depending on the first characters. The denotation parsing is extendable, e.g. after loading a floating point package floating point numbers are recognized. character or characters. A number is converted according to the current base. If a decimal point is found as part of a number, the number value that is left is a double number, otherwise it is a single number. Comma's in numbers are ignored by ciforth.

GLOSSARY INDEX

SEE ALSO: PARSING NAME (NUMBER) NUMBER BLK DPL

## NAME

STACKEFFECT: --- sc

DESCRIPTION:

(CI) Parse the current input source for a word, i.e. blank-delimited as per ?BLANK . Skip leading delimiters then advance the input pointer to past the next delimiter or past the end of the input source. Leave the word found as a string constant sc. As it goes with string constants, you may not alter its content, nor assume anything is appended. Note that this is more deserving of the name ``WORD'' than what is in the ISO standard, that can be used to parse lines. Contrast this to a PREFIX word that leaves the input pointer past itself.

GLOSSARY INDEX

SEE ALSO: PARSING BLK WORD PP

## PARSE

STACKEFFECT: c --- sc

DESCRIPTION:

() Scan the current input source for the character c . Return sc: a string from the current position in the input stream, ending before the first such character, or at the end of the current input source if it isn't there. The character is consumed. As it goes with string constants, you may not alter its content, nor assume anything is appended. So no leading delimiters are skipped.

GLOSSARY INDEX

SEE ALSO: PARSING WORD NAME

## PP@@

STACKEFFECT: ---addr c

DESCRIPTION:

(CI) Parse the current input source leaving the address addr of the next character c . If at the end of the input source, leave a pointer past the end and a zero. Advance the input pointer to the next character.

GLOSSARY INDEX

SEE ALSO: PARSING BLK WORD PP

## RESTORE-INPUT

STACKEFFECT: n1 n2 n3 3---f

DESCRIPTION:

(ISO,WANT) Restore the input source stream from what was saved by SAVE-INPUT . ciforth is always able to restore the input across different input sources, as long as the input to be restored was not exhausted. This has the effect of chaining, and doesn't affect the return from nested calls be it interpreting, loading or evaluating. ciforth always returns a true into f. The input source abandoned will never be closed properly, so use should be restricted to the same input source.

GLOSSARY INDEX

SEE ALSO: PARSING SAVE SAVE-INPUT

## RESTORE

STACKEFFECT: ---

DESCRIPTION:

() This must follow a SAVE in the same definition. Restore the content of SRC from the return stack thus restoring the current input source to what it was when the SAVE was executed.

GLOSSARY INDEX

SEE ALSO: PARSING SET-SRC RESTORE-INPUT

## SAVE-INPUT

STACKEFFECT: --- n1 n2 n3 3

DESCRIPTION:

(ISO,WANT) Get a complete specification of the input source stream. For ciforth this is the content of SRC. ciforth needs 3 cells, and is always able to RESTORE an input saved like this. In practice the use of SAVE-INPUT should be restricted to restoring input of the same stream.

GLOSSARY INDEX

SEE ALSO: PARSING SAVE RESTORE-INPUT

## SAVE

STACKEFFECT: ---

DESCRIPTION:

() Save the content of SRC on the return stack to prepare for changing the current input source. This must be balanced by a RESTORE in the same definition. CO can be used between the two.

GLOSSARY INDEX

SEE ALSO: PARSING SET-SRC SAVE-INPUT

## SET-SRC

STACKEFFECT: sc ---

DESCRIPTION:

() Make the string constant sc the current input source. This input is chained, i.e. exhausting it has the same effect as exhausting the input that called SET-SRC. In practice this word is almost always surrounded by call's to forthcode({SAVE}) and forthcode({RESTORE}) and then followed by a call to INTERPRETor some such.

GLOSSARY INDEX

SEE ALSO: PARSING SRC SAVE EVALUATE INTERPRET

## SOURCE

STACKEFFECT: --- addr n1

DESCRIPTION:

(ISO) Return the address and length of the current input source .

GLOSSARY INDEX

SEE ALSO: PARSING SRC

## SRC

STACKEFFECT: addr ---

DESCRIPTION:

() Return the address addr of the current input source specification, allocated in the user area. It consists of three cells: the lowest address of the parse area, the non-inclusive highest address of the parse area and a pointer to the next character to be parsed. Changing SRC takes immediate effect, and must be atomic, by changing only the third cell or by e.g. using SET-SRC. The third cell has the alias PP . Words like >IN BLK SOURCE are secondary, and return their output by ``second-guessing'' SRC .

GLOSSARY INDEX

SEE ALSO: PARSING SAVE RESTORE PP BLK

## STATE

STACKEFFECT: --- addr

DESCRIPTION:

(ISO,U) A user variable containing the compilation state. A non-zero value indicates compilation. In ciforth it then contains 1.

GLOSSARY INDEX

SEE ALSO: PARSING [ ]

## WORD

STACKEFFECT: c ---addr

DESCRIPTION:

(ISO,FIG,WANT) Parse the current input source using c for a delimiter. Skip leading delimiters then advance the input pointer to past the next delimiter or past the end of the input source. Leave at addr a copy of the string, that was surrounded by c in the input source. This is an oldfashioned string to be fetched by COUNT , not $@ . In ciforth the character string is positioned at the dictionary buffer HERE . WORD leaves the character count in the first byte, the characters, and ends with two or more blanks.

GLOSSARY INDEX

SEE ALSO: PARSING NAME PARSE BLK IN

## [CHAR]

STACKEFFECT: --- c

DESCRIPTION:

(ISO I) A compiling word. Parse a word. Add the run time behaviour: leave c, the first non blank char of that word in the input source. In ciforth this word works also in interpret mode.

GLOSSARY INDEX

SEE ALSO: PARSING Prefix_& CHAR

## [

STACKEFFECT:

DESCRIPTION:

(ISO,FIG,I,) Used in a colon-definition in form:

: xxx [ words ] more ;

Suspend compilation. The words after [ are executed, not compiled. This allows calculation or compilation exceptions before resuming compilation with ]

GLOSSARY INDEX

SEE ALSO: PARSING LITERAL ]

## \

STACKEFFECT:

DESCRIPTION:

(ISO,I) Used in the form: \ cccc Ignore a comment that will be delimited by the end of the current line. May occur during execution or in a colon-definition. Blank space after the word \ is required.

GLOSSARY INDEX

SEE ALSO: PARSING (

## ]

STACKEFFECT:

DESCRIPTION:

(ISO,FIG) Resume compilation, to the completion of a colon-definition.

GLOSSARY INDEX

SEE ALSO: PARSING [

## (

STACKEFFECT:

DESCRIPTION:

(ISO,FIG,I) Used in the form: ( cccc). Ignore a comment that will be delimited by a right parenthesis that must be in the same input source, i.e. on the same line for terminal input, or in the same string, block or file, when that is the input. It is an immediate word. So colon definitions can be commented too. A blank after the word ( is required.

GLOSSARY INDEX

SEE ALSO: PARSING \

# SCREEN

OVERVIEW:

Most of the blocks mass storage is used for screen's that have 16 lines of 64 characters. They are used for source code and documentation. Each screen is one BLOCK as required by ISO. The SCREEN wordset contains facilities to view screens, and load them, that is compiling them and thus extending the base system. A system is customized by loading source screens, possibly one of these extension is a text editor for screens.

## (LINE)

STACKEFFECT: n1 n2 --- sc

DESCRIPTION:

() Convert the line number n1 and the screen n2 to a string sc the content of the line (without the trailing new line).

GLOSSARY INDEX

SEE ALSO: SCREEN LINE

## C/L

STACKEFFECT: --- c

DESCRIPTION:

() A constant that leaves the number of characters on a line of a standard screen: 64. The last character of each line is a LF.

GLOSSARY INDEX

SEE ALSO: SCREEN LIST LINE

## INDEX

STACKEFFECT: from to ---

DESCRIPTION:

() Print the first line of each screen over the inclusive range from , to . This is used to view the comment lines of an area of text on disc screens.

GLOSSARY INDEX

SEE ALSO: SCREEN LIST

## LIST

STACKEFFECT: n ---

DESCRIPTION:

(ISO,FIG) Display the ASCII text of screen n. The number of the screen is always printed in decimal. SCR contains the screen number during and after this process.

GLOSSARY INDEX

SEE ALSO: SCREEN BLOCK

## LOAD

STACKEFFECT: n --- ??

DESCRIPTION:

(ISO,FIG) Interrupt the current input source in order to interpret screen n . While the screen is interpreted, it is locked, meaning that it cannot be associated with a different screen nr than n . The stack changes in according with the words executed. At the end of the screen, barring errors or forced changes, it continues with the interrupted input source.

GLOSSARY INDEX

SEE ALSO: SCREEN BLOCK LOCK #BUFF THRU QUIT EXIT --> LIST

## LOCK

STACKEFFECT: n ---

DESCRIPTION:

(CI) Lock the buffer with identification n, mostly a block number. Multiple locks are possible, and require multiple unlocks. Probably, it is to become the current input source. The result is that its buffer will not be reclaimed until an UNLOCK occurs.

GLOSSARY INDEX

SEE ALSO: SCREEN BLOCK (BUFFER ,UNLOCK,#BUFF)

## R#

STACKEFFECT: --- addr

DESCRIPTION:

(U) A user variable which may contain the location of an editing cursor, or other file related function. Unused in the kernel of ciforth.

GLOSSARY INDEX

SEE ALSO: SCREEN

## SCR

STACKEFFECT: --- addr

DESCRIPTION:

(U) A user variable containing the screen number most recently reference by LIST .

GLOSSARY INDEX

SEE ALSO: SCREEN BLOCK

## THRU

STACKEFFECT: n1 n2 --- ??

DESCRIPTION:

(ISO,FIG) Interrupt the current input source in order to interpret screen n1 through n2 (inclusive). The stack changes in according with the words executed. At the end of the screens, barring errors or forced changes, it continues with the interrupted input source.

GLOSSARY INDEX

SEE ALSO: SCREEN #BUFF BLOCK LOAD QUIT EXIT -->

## TRIAD

STACKEFFECT: scr ---

DESCRIPTION:

(FIG,WANT) Display on the selected output device the three screens which include that numbered scr , beginning with a screen evenly divisible by three. Output is suitable for source text records, and includes a reference line at the bottom taken from line 0 of the first error screen.

GLOSSARY INDEX

SEE ALSO: SCREEN MESSAGE ERRSCR

## UNLOCK

STACKEFFECT: n ---

DESCRIPTION:

(CI) Unlock the buffer with identification n, mostly a block number. Probably, because it is no longer the current input source. The result is that its buffer can again be reclaimed. Unlocking without a previous lock may lead to a crash.

GLOSSARY INDEX

SEE ALSO: SCREEN LOCK (BUFFER) #BUFF

## (BLK)

STACKEFFECT: --- addr

DESCRIPTION:

(U) When the standard word BLK is used, this user variable reflects the state of the current input source. It indicates the block number being interpreted, or zero, if input is being taken from the terminal input buffer. Changing BLK has no effect, and its content must be fetched before the current input source has changed.

GLOSSARY INDEX

SEE ALSO: SCREEN~ BLOCK TIB

## BLK

STACKEFFECT: --- addr

DESCRIPTION:

(ISO) When the standard word BLK is used, the content of the user variable (BLK) is refreshed to reflect the state of the current input source and its address is returned in addr . It indicates the block number being interpreted, or zero, if input is being taken from the terminal input buffer. In ciforth changing the content at addr has no effect, which may not be ISO compliant. Its content must be fetched before the current input source has changed.

GLOSSARY INDEX

SEE ALSO: SCREEN~ BLOCK TIB

# SECURITY

OVERVIEW:

The wordset SECURITY contains words that are used by control words to abort with an error message if the control structure is not correct. Some say that this is not Forth-like. You only need to know them if you want to extend the CONTROL wordset.

## !CSP

STACKEFFECT:

DESCRIPTION:

() Save the stack position in CSP. Used as part of the compiler security.

GLOSSARY INDEX

SEE ALSO: SECURITY

## ?COMP

STACKEFFECT:

DESCRIPTION:

() Issue error message if not compiling.

GLOSSARY INDEX

SEE ALSO: SECURITY ?ERROR

## ?CSP

STACKEFFECT:

DESCRIPTION:

() Issue error message if stack position differs from value saved in CSP .

GLOSSARY INDEX

SEE ALSO: SECURITY

## ?DELIM

STACKEFFECT:

DESCRIPTION:

() Parse a character and issue error message if it is not a blank delimiter.

GLOSSARY INDEX

SEE ALSO: SECURITY

## ?EXEC

STACKEFFECT:

DESCRIPTION:

(FIG,WANT) Issue an error message if not executing.

GLOSSARY INDEX

SEE ALSO: SECURITY ?ERROR

## ?LOADING

STACKEFFECT:

DESCRIPTION:

(FIG,WANT) Issue an error message if not loading

GLOSSARY INDEX

SEE ALSO: SECURITY ?ERROR

## ?PAIRS

STACKEFFECT: n1 n2 ---

DESCRIPTION:

() Issue an error message if n1 does not equal n2 . The message indicates that compiled conditionals do not match.

GLOSSARY INDEX

SEE ALSO: SECURITY ?ERROR

## ?STACK

STACKEFFECT:

DESCRIPTION:

() Issue an error message if the stack is out of bounds.

GLOSSARY INDEX

SEE ALSO: SECURITY ?ERROR

## CSP

STACKEFFECT: ---- addr

DESCRIPTION:

(U) A user variable temporarily storing the stack pointer position, for compilation error checking.

GLOSSARY INDEX

SEE ALSO: SECURITY

# STACKS

OVERVIEW:

The wordset STACKS contains words related to the data stack and return stack. Words can be moved between both stacks. Stacks can be reinitialised and the value used to initialise the stack pointer's can be altered.

## .S

STACKEFFECT: from to ---

DESCRIPTION:

() Print the stack, in the current base. For stack underflow print nothing.

GLOSSARY INDEX

SEE ALSO: STACKS LIST

## >R

STACKEFFECT: n ---

DESCRIPTION:

(ISO,FIG,C) Remove a number from the data stack and place as the most accessable on the return stack. Use should be balanced with R> in the same definition.

GLOSSARY INDEX

SEE ALSO: STACKS R@

## CLS

STACKEFFECT: i*x --

DESCRIPTION:

() Clear the data stack

GLOSSARY INDEX

SEE ALSO: STACKS DSP!

## DEPTH

STACKEFFECT: --- n1

DESCRIPTION:

(ISO) Leave into n1 the number of items on the data stack, before n1 was pushed.

GLOSSARY INDEX

SEE ALSO: STACKS DSP@

## DSP!

STACKEFFECT: addr ---

DESCRIPTION:

() Initialize the data stack pointer with addr .

GLOSSARY INDEX

SEE ALSO: STACKS DSP@ S0

## DSP@

STACKEFFECT: --- addr

DESCRIPTION:

() Return the address addr of the data stack position, as it was before DSP@ was executed.

GLOSSARY INDEX

SEE ALSO: STACKS S0 DSP!

## R0

STACKEFFECT: --- addr

DESCRIPTION:

(U) A user variable containing the initial location of the return stack.

GLOSSARY INDEX

SEE ALSO: STACKS RSP!

## R>

STACKEFFECT: --- n

DESCRIPTION:

(ISO,FIG) Remove the top value from the return stack and leave it on the data stack .

GLOSSARY INDEX

SEE ALSO: STACKS >R R@

## R@

STACKEFFECT: --- n

DESCRIPTION:

(ISO) Copy the top of the return stack to the data stack.

GLOSSARY INDEX

SEE ALSO: STACKS >R <R

## RDROP

STACKEFFECT: ---

DESCRIPTION:

() Remove the top value from the return stack.

GLOSSARY INDEX

SEE ALSO: STACKS >R R@ R>

## RSP!

STACKEFFECT: addr ---

DESCRIPTION:

() Initialize the return stack pointer with addr.

GLOSSARY INDEX

SEE ALSO: STACKS RSP@ R0

## RSP@

STACKEFFECT: --- addr

DESCRIPTION:

() Return the address addr of the current return stack position, i.e. pointing the current topmost value.

GLOSSARY INDEX

SEE ALSO: STACKS R0 RSP!

## S0

STACKEFFECT: --- addr

DESCRIPTION:

(U) A user variable that contains the initial value for the data stack pointer.

GLOSSARY INDEX

SEE ALSO: STACKS DSP!

# STRING

OVERVIEW:

The wordset STRING contains words that manipulate strings of characters. In ciforth strings have been given their civil rights. So they are entitled to a denotation (the word " ) and have a proper fetch and store. An (address length) pair is considered a string constant. It may be trimmed, but the data referring to via the address must not be changed. It can be stored in a buffer, a string variable, that contains in its first cell the count. Formerly this was in the first byte, and these are called old fashioned string's (or less flatteringly: brain-damaged).

## $!-BD

STACKEFFECT: sc addr ---

DESCRIPTION:

(WANT) Store a string constant sc in the old fashioned string variable at address addr, i.e. it can be fetched with COUNT. (Where would that BD come from?)

GLOSSARY INDEX

SEE ALSO: STRING COUNT $!

## $!

STACKEFFECT: sc addr ---

DESCRIPTION:

() Store a string constant sc in the string variable at address addr.

GLOSSARY INDEX

SEE ALSO: STRING $@ $+! $C+

## $+!

STACKEFFECT: sc addr ---

DESCRIPTION:

() Append a string constant sc to the string variable at address addr.

GLOSSARY INDEX

SEE ALSO: STRING $@ $! $C+

## $,

STACKEFFECT: sc --- addr

DESCRIPTION:

() Allocate and store a string constant sc in the dictionary and leave its address addr.

GLOSSARY INDEX

SEE ALSO: STRING $@ $!

## $/

STACKEFFECT: sc c --- sc1 sc2

DESCRIPTION:

() Find the first c in the string constant sc and split it at that address. Return the strings after and before c into sc1 and sc2 respectively. If the character is not present sc1 is a null string (its address is zero) and sc2 is the original string. Both sc1 and sc2 may be empty strings (i.e. their count is zero), if c is the last or first character in sc .

GLOSSARY INDEX

SEE ALSO: STRING $^ CORA $@

## $@

STACKEFFECT: addr --- sc

DESCRIPTION:

() From address addr fetch a string constant sc . This is similar to COUNT with a cell-length instead of a char-length.

GLOSSARY INDEX

SEE ALSO: STRING $! $+! $C+

## $C+

STACKEFFECT: c addr ---

DESCRIPTION:

() Append a char c to the string variable at address addr.

GLOSSARY INDEX

SEE ALSO: STRING $! $+! & ^ CHAR

## $\

STACKEFFECT: sc c --- sc1 sc2

DESCRIPTION:

() Find the first c in the string constant sc from the back and split it at that address. Return the strings before and after c into sc1 and sc2 respectively. If the character is not present sc1 is a null string (its address is zero) and sc2 is the original string. Both sc1 and sc2 may be empty strings (i.e. their count is zero), if c is the last or first character in sc .

GLOSSARY INDEX

SEE ALSO: STRING $^ CORA $@

## $^

STACKEFFECT: sc c --- addr

DESCRIPTION:

() Find the first c in the string constant sc and return its addr if present. Otherwise return a nil pointer. A null string (0 0) or an empty string are allowed, and result in not found.

GLOSSARY INDEX

SEE ALSO: STRING $/ CORA $@

## -TRAILING

STACKEFFECT: sc1 --- sc2

DESCRIPTION:

(ISO) Trim the string constant sc1 so as not to contain trailing blank space and leave it as sc2 .

GLOSSARY INDEX

SEE ALSO: STRING ?BLANK

## BL

STACKEFFECT: --- c

DESCRIPTION:

(ISO.FIG) A constant that leaves the ASCII value for "blank".

GLOSSARY INDEX

SEE ALSO: STRING

## COUNT

STACKEFFECT: addr1 --- addr2 n

DESCRIPTION:

(ISO,FIG) Leave the byte address addr2 and byte count n of a message text beginning at address addr1 . It is presumed that the first byte at addr1 contains the text byte count and the actual text starts with the second byte. Alternatively stated, fetch a string constant addr2 n from the brain damaged string variable at addr1 .

GLOSSARY INDEX

SEE ALSO: STRING TYPE

## S"

STACKEFFECT: --- addr1 n

DESCRIPTION:

(ISO) Used in the form: S" cccc" Leaves an in-line string cccc (delimited by the trailing ") as a constant string addr1 n . In ciforth the number of characters has no limit and using S" has always an effect on HERE, even during interpretation. In ciforth a " can be embedded in a string by doubling it. In non-portable code denotations are recommended.

GLOSSARY INDEX

SEE ALSO: STRING "

# SUPERFLUOUS

OVERVIEW:

The wordset SUPERFLUOUS contains words that are superfluous, because they are equivalent to small sequences of code. Traditionally one hoped to speed Forth up by coding these words directly.

## 0

STACKEFFECT: --- 0

DESCRIPTION:

() Leave the number 0.

GLOSSARY INDEX

SEE ALSO: SUPERFLUOUS CONSTANT

## 1+

STACKEFFECT: n1 --- n2

DESCRIPTION:

(ISO,FIG) This is shorthand for ``1 +''.

GLOSSARY INDEX

SEE ALSO: SUPERFLUOUS CELL+ 1-

## 1-

STACKEFFECT: n1 --- n2

DESCRIPTION:

(ISO) This is shorthand for 1 -.

GLOSSARY INDEX

SEE ALSO: SUPERFLUOUS 1+

## 2*

STACKEFFECT: n1 --- n2

DESCRIPTION:

(ISO) Perform an arithmetical {shift} left. The bit pattern of n1 is shifted to the left, with a result identical to 1 LSHIFT.

GLOSSARY INDEX

SEE ALSO: SUPERFLUOUS 2/

## 2/

STACKEFFECT: n1 --- n2

DESCRIPTION:

(ISO) Perform an arithmetical {shift} right. The bit pattern of n1 is shifted to the right, except that the left most bit (``sign bit'') remains the same, called "arithmetic shift". On this 2-complement machine this is the same as 2 / .

GLOSSARY INDEX

SEE ALSO: SUPERFLUOUS 2*

## Number_1

STACKEFFECT: --- 1

DESCRIPTION:

() Leave the number 1.

GLOSSARY INDEX

SEE ALSO: SUPERFLUOUS CONSTANT

## Number_2

STACKEFFECT: --- 2

DESCRIPTION:

() Leave the number 2.

GLOSSARY INDEX

SEE ALSO: SUPERFLUOUS CONSTANT

# WORDLISTS

OVERVIEW:

The dictionary is subdivided in non-overlapping subsets: the word list's (See also DICTIONARY). They are created by the defining word NAMESPACE and filled by defining words while that namespace is CURRENT . They regulate how words are found; different vocabularies can have words with the same names. A word list in the ISO sense has a word list identifier or WID, but no name which is inconvenient. We use namespace words created by the defining word NAMESPACE . They are used to manipulate the word list's that are associated with them. So namespaces are nearly the wordlist 's of the ISO standard, the primary difference is that they have a name. In most Forth literature namespaces are referred to as vocabularies, and a word forthcode({VOCABULARY}) is used to create them.

## ALSO

STACKEFFECT:

DESCRIPTION:

(ISO) Duplicate the topmost WID in the search order stack. If there were already 16 WID 's, ciforth looses the last one, i.e. the first added to the search order probably FORTH. This is probably fatal. ONLY remains in the search order and ONLY FORTH can be used to recover. Using namespaces you will not need to use this word, because in ciforth by executing a namespace you add it to the order. This is different than the words defined by the customary forthcode({VOCABULARY}) that replaces the topmost wordlist.

GLOSSARY INDEX

SEE ALSO: WORDLISTS CONTEXT NAMESPACE

## ASSEMBLER

STACKEFFECT:

DESCRIPTION:

(WANT,NISO,FIG) The name of the namespace that contains machine code definitions. In ciforth execution it pushes the associated word list to the top of the CONTEXT stack. (A traditional VOCABULARY would replace the top.) This word makes only sense in combination with the words that belong to it. So it is present in loadable form in the screens file ``forth.lab'' .

GLOSSARY INDEX

SEE ALSO: WORDLISTS NAMESPACE LOAD

## CONTEXT

STACKEFFECT: --- addr

DESCRIPTION:

(FIG,U) The context is the address where the WID is found of the wordlist that is searched first. In ciforth addr actually points to the search order, a row of WID 's ending with the minimum search order WID. The corresponding wordlists are searched in that order for definitions during interpretation. This row of WID's is allocated in the user variable space allowing for compilation in threads. It may contain up to 16 WID 's in this ciforth, while the ISO Search-Order wordset requires a capacity of at least 8.

GLOSSARY INDEX

SEE ALSO: WORDLISTS PRESENT NAMESPACE CURRENT USER

## CURRENT

STACKEFFECT: --- addr

DESCRIPTION:

(FIG,U) A user variable containing the WID of a namespace to which new words will be added. It is the compilation word list in the sense of the ISO standard. The WID has the structure of a dictionary entry. This allows to link in a new word between the link field of the WID and the next definition.

GLOSSARY INDEX

SEE ALSO: WORDLISTS NAMESPACE CONTEXT

## DEFINITIONS

STACKEFFECT:

DESCRIPTION:

(ISO) Used in the form: cccc DEFINITIONS Make the top most search order word list, (context), the compilation word list (current). In the example, executing namespace name cccc add it to the top of the search order and executing DEFINITIONS will result in new definitions added to cccc .

GLOSSARY INDEX

SEE ALSO: WORDLISTS CONTEXT NAMESPACE

## ENVIRONMENT

STACKEFFECT:

DESCRIPTION:

() The name of the ENVIRONMENT namespace. The associated word list contains environment queries. The names of words present in ENVIRONMENT are recognized by ENVIRONMENT?. This word list is not intended to be used as a CONTEXT word list; and only as a CURRENT whenever you want to add an environment query.

GLOSSARY INDEX

SEE ALSO: WORDLISTS NAMESPACE

## FORTH

STACKEFFECT:

DESCRIPTION:

(NISO,FIG) The name of the primary namespace. Execution pushes the FORTH WID to the top of the search order . (For ISO-compliance it would replace the top, however the phrase ONLY FORTH has the effect required by ISO.) Until additional user word list 's are created, new user definitions become a part of FORTH .

GLOSSARY INDEX

SEE ALSO: WORDLISTS CONTEXT NAMESPACE

## LATEST

STACKEFFECT: --- addr

DESCRIPTION:

(FIG) Leave the dictionary entry address addr of the topmost word in the CURRENT word list.

GLOSSARY INDEX

SEE ALSO: WORDLISTS NAMESPACE

## ONLY

STACKEFFECT:

DESCRIPTION:

(NISO) Set the minimum search order, such that only denotation's (numbers etc.) can be found plus the word FORTH. By using FORTH one can regain control towards a startup search order. ONLY is actually a regular NAMESPACE. The associated word list contains mainly prefix words, that scan denotations and are described in the chapter DENOTATIONS. If you want to add a denotation, add it to the ONLY wordlist preferably. This prevents masking regular words that start with the prefix.

GLOSSARY INDEX

SEE ALSO: WORDLISTS PREFIX PP >WID

## PREVIOUS

STACKEFFECT:

DESCRIPTION:

(ISO) Pop the topmost WID from the search order stack. If empty still the ONLY search order is left.

GLOSSARY INDEX

SEE ALSO: WORDLISTS CONTEXT NAMESPACE

## VOC-LINK

STACKEFFECT: --- addr

DESCRIPTION:

(U) A user variable containing the dictionary entry address of the word most recently created by NAMESPACE . All namespace names are linked by these fields to allow FORGET to find all vocabularies.

GLOSSARY INDEX

SEE ALSO: WORDLISTS~ NAMESPACE