thisforth ci86gnrversion Manual

# thisforth Version [ ci86gnrversion ] GLOSSARY

# GLOSSARY INDEX

Here you can select the glossary entry of a word. All words in the basic set are documented.

!CSP ! #> #BUFF #S # $!-BD $! $+! $, $@ $C+ $I $S <# <> < ' (+LOOP) (;) (;CODE) (>IN) (?DO) (ABORT") (ACCEPT) (BACK (BLK) (BUFFER) (CREATE) (D.R) (DO) (FIND) (FORWARD (LINE) (LOOP) (NUMBER) (PARSE) (WORD) ( */MOD */ * +! +BUF +LOOP +ORIGIN + , --> -TRAILING - ." .( .R .SIGNON .S . /MOD / 0< 0= 0BRANCH 0 1+ 1- 2! 2* 2/ 2@ 2DROP 2DUP 2OVER 2SWAP : ;CODE ; = >BODY >CFA >DFA >FFA >IN >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 BL BM BODY> BRANCH BYE C! C, C/L C@ CATCH CELL+ CELLS CFA> CHAR+ CHARS CHAR CLOSE-FILE CMOVE COLD CONSTANT CONTEXT CORA CORE COUNT CO CPU CREATE-FILE CREATE CR CSP CURRENT D+ D.R D. DABS DECIMAL DEFINITIONS DELETE-FILE DEPTH DIGIT DISK-ERROR DLITERAL DNEGATE DOES> DO DPL DP DROP DSP! DSP@ DUP ELSE EMIT EMPTY-BUFFERS EM ENVIRONMENT? ENVIRONMENT ERASE ERROR ERRSCR ETYPE EVALUATE EXECUTE EXIT-CODE EXIT FARMOVE FENCE FILL FIND FIRST FLD FLUSH FM/MOD FOR-VOCS FOR-WORDS FORGET-VOC FORGET FORTH FORWARD) FOUND GET-FILE HANDLER HERE HEX HIDDEN HLD HOLD ID. IF IMMEDIATE INCLUDED INDEX INTERPRET INVERT IN[] IN I J KEY? KEY L! L@ LATEST LEAVE LIMIT LINOS5 LINOS LIST LITERAL LIT LOAD LOCK LOOP LSHIFT M* M/MOD MAX MESSAGE MIN MOD MOVE MS NAME NEGATE NOOP NUMBER Number_1 Number_2 OFFSET OK ONLY OPEN-FILE OPTIONS OPT OR OUT OVER P! P@ PAD PC! PC@ POSTPONE PREFIX PRESENT PREVIOUS PREV PUT-FILE Prefix_" Prefix_& Prefix_+ Prefix_- Prefix_0 Prefix_7 Prefix_B Prefix_^ Prefix__TICK 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 R\W S" S0 S>D SAVE-INPUT SAVE SCR SDLITERAL SEEK SET-SRC SET-TERM SHELL SIGN SKIP SM/REM SOURCE SPACES SPACE SRC STALEST STATE SUPPLIER SWAP SYSTEM TASK TERMIO THEN THROW THRU TIB TOGGLE TRIAD TYPE U< U. U0 UM* UM/MOD UNLOCK UNLOOP UNTIL UPDATE USER VARIABLE VERSION VOC-LINK VOCABULARY WARM WARNING WHERE WHILE WITHIN WORDS WORD WRITE-FILE XOR ZEN ['] [CHAR] [COMPILE] [ \ ] _ ~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.

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

#### WORDSET BLOCKS

- OVERVIEW OF BLOCKS
- #BUFF
- ?DISK-ERROR
- B/BUF
- BLOCK-EXIT
- BLOCK-FILE
- BLOCK-HANDLE
- BLOCK-INIT
- BLOCK
- DISK-ERROR
- EMPTY-BUFFERS
- R\W
- UPDATE
- (BUFFER)
- +BUF
- FIRST
- FLUSH
- LIMIT
- OFFSET
- PREV
- RESTORE-INPUT
- RESTORE
- SAVE-INPUT
- SAVE
- SEEK
- STALEST

#### 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
- (LOOP)
- 0BRANCH
- BACK)
- BRANCH
- FORWARD)

#### WORDSET DEFINING

- OVERVIEW OF DEFINING
- :
- ;
- CONSTANT
- CREATE
- DOES>
- USER
- VARIABLE
- VOCABULARY
- (;CODE)
- (CREATE)
- ;CODE

#### WORDSET DENOTATIONS

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

#### WORDSET DICTIONARY

- OVERVIEW OF DICTIONARY
- '
- ,
- >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
- CFA>
- 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
- GET-FILE
- INCLUDED
- 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
- FLD
- HLD
- NUMBER

#### WORDSET INIT

- OVERVIEW OF INIT
- +ORIGIN
- ABORT
- COLD
- OK
- OPTIONS
- QUIT
- WARM

#### WORDSET INPUT

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

#### WORDSET JUGGLING

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

#### 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
- FARMOVE
- FILL
- L!
- L@
- MOVE
- P!
- P@
- PC!
- PC@
- 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
- UM*
- UM/MOD

#### WORDSET OPERATINGSYSTEM

- OVERVIEW OF OPERATINGSYSTEM
- ARGS
- BYE
- EXIT-CODE
- LINOS5
- LINOS
- MS
- SHELL
- SYSTEM
- 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
- (PARSE)
- (WORD)
- (
- ?BLANK
- CHAR
- EVALUATE
- INTERPRET
- IN[]
- SET-SRC
- SOURCE
- SRC
- STATE
- WORD
- [CHAR]
- [
- \
- ]

#### 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
- DEPTH
- DSP!
- DSP@
- R0
- R>
- R@
- RDROP
- RSP!
- RSP@
- S0

#### WORDSET STRING

- OVERVIEW OF STRING
- $!-BD
- $!
- $+!
- $,
- $@
- $C+
- $I
- $S
- -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

## ?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.

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 . Close the currently open block file BLOCK-HANDLE, i.e. 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 may be changed and is used by the BLOCK-INIT command.

GLOSSARY INDEX

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

## 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 fails silently. You must activate mnemonic error messages explicitly by setting WARNING.

GLOSSARY INDEX

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

## BLOCK

STACKEFFECT: n --- addr

DESCRIPTION:

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) R\W OFFSET UPDATE FLUSH LOAD

## DISK-ERROR

STACKEFFECT: --- addr

DESCRIPTION:

This flag is not used, errors are thrown. .

GLOSSARY INDEX

SEE ALSO: BLOCKS BLOCK

## EMPTY-BUFFERS

STACKEFFECT:

DESCRIPTION:

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

## R\W

STACKEFFECT: addr blk n ---

DESCRIPTION:

The ciforth primitive for read-write of blocks. addr specifies the source or destination block buffer, blk is the sequential number of the referenced physical block; and n is a control variable for n=0 write and n=l read. R\W determines the location on mass storage, performs the read or write and throws an exception on errors.

GLOSSARY INDEX

SEE ALSO: BLOCKS BLOCK DISK-ERROR

## UPDATE

STACKEFFECT:

DESCRIPTION:

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 SCREEN

## (BUFFER)

STACKEFFECT: n --- addr

DESCRIPTION:

Return the addres addr of a buffer assigned to block n . The buffer layout is as follows: a cell with the block number, a cell with the status, and the content. The status is negative for locked, zero for free and one for present and unlocked. 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, the stalest buffer is freed. The contents of that buffer is written to the disc, if it was marked as updated. In ciforth this is never needed, 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 ciforth. If all buffers were locked, (BUFFER) freezes the system.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ BLOCK STALEST PREV #BUFF LOCK UNLOCK

## +BUF

STACKEFFECT: addr1 --- addr2 ff

DESCRIPTION:

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

## FIRST

STACKEFFECT: --- n

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: BLOCKS~ BLOCK LIMIT

## FLUSH

STACKEFFECT:

DESCRIPTION:

Make sure that the content of all UPDATE d block buffers has been transferred to disk. They are no longer associated with a block and their content is no longer available.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ EMPTY-BUFFERS BLOCK SCREEN

## LIMIT

STACKEFFECT: ---- n

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

## OFFSET

STACKEFFECT: --- addr

DESCRIPTION:

A user variable which contains a block offset to disc drives; in this way a part of it is available for boot-code. As blocks are allocated in a file on the host operating system it is 0. The contents of OFFSET is added to the stack number by BLOCK before calling R\W.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ BLOCK MESSAGE

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

## RESTORE-INPUT

STACKEFFECT: n1 n2 n3 3---f

DESCRIPTION:

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: BLOCKS~ RESTORE 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: BLOCKS~ RESTORE-INPUT SAVE-INPUT

## SAVE-INPUT

STACKEFFECT: --- n1 n2 n3 3

DESCRIPTION:

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: BLOCKS~ RESTORE RESTORE-INPUT

## SAVE

STACKEFFECT: ---

DESCRIPTION:

Save the content of SRC on the return stack prior to changing the current input source. This must be balanced by a RESTORE in the same definition.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ RESTORE SAVE-INPUT

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

## STALEST

STACKEFFECT: --- addr

DESCRIPTION:

A variable containing the address of the oldest block buffer, the first candidate to be claimed if a new one is needed.

GLOSSARY INDEX

SEE ALSO: BLOCKS~ BLOCK

# COMPILING

OVERVIEW:

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

## DLITERAL

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

DESCRIPTION:

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 in ciforth, the number will just remain on the stack.

GLOSSARY INDEX

SEE ALSO: COMPILING LITERAL LIT

## LITERAL

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

DESCRIPTION:

If compiling, then compile the stack value n as a 32 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 in ciforth, the number will just remain on the stack.

GLOSSARY INDEX

SEE ALSO: COMPILING LIT LITERAL

## POSTPONE

STACKEFFECT:

DESCRIPTION:

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:

Used in a colon-definition in form:

: xxx [COMPILE] FORTH ;

[COMPILE] will force the compilation of an immediate definitions, that would otherwise execute during compilation. The above example will select the FORTH vocabulary when xxx executes, rather than at compile time.

GLOSSARY INDEX

SEE ALSO: COMPILING POSTPONE

## LIT

STACKEFFECT: --- n

DESCRIPTION:

Within a colon-definition, LIT is compiled followed by a 32 bit literal number given during compilation. Later execution of LIT causes the contents of this next dictionary cell to be pushed to the stack.

GLOSSARY INDEX

SEE ALSO: COMPILING~ LITERAL

## SDLITERAL

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

DESCRIPTION:

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~ SLITERAL DLITERAL

# 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:

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). Upon exiting the loop, the parameters are discarded and execution continues ahead. At compile time, +LOOP compiles the run-time word (+LOOP) and the branch offset computed from HERE to the address left on the stack by DO . n2 is used for compile time error checking.

GLOSSARY INDEX

SEE ALSO: CONTROL

## ?DO

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

DESCRIPTION:

Occurs in a colon-definition in form:

?DO ... LOOP

It behaves like DO , with the exception that if n1 and n2 are equal the loop body is not executed.

GLOSSARY INDEX

SEE ALSO: CONTROL DO I LOOP +LOOP LEAVE

## AGAIN

STACKEFFECT: addr n --- (compiling)

DESCRIPTION:

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:

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

## CO

STACKEFFECT:

DESCRIPTION:

Return suspend 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:

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

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 emplaces BRANCH reserving a branch offset, leaves the 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

## EXIT

STACKEFFECT:

DESCRIPTION:

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:

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

## I

STACKEFFECT: --- n

DESCRIPTION:

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:

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:

Termination 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

## LOOP

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

DESCRIPTION:

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 (LOOP) and uses addr to calculate an offset to DO . n2 is used for compile time error checking.

GLOSSARY INDEX

SEE ALSO: CONTROL +LOOP

## RECURSE

STACKEFFECT: (varies)

DESCRIPTION:

Do a recursive call of the definition being compiled.

GLOSSARY INDEX

SEE ALSO: CONTROL :

## REPEAT

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

DESCRIPTION:

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:

Skip over an area in memory, where the length is given in the next cell. 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:

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: --- n

DESCRIPTION:

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.

GLOSSARY INDEX

SEE ALSO: CONTROL DO LOOP +LOOP (BACK (FORWARD EXIT

## UNTIL

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

DESCRIPTION:

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:

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:

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:

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:

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

GLOSSARY INDEX

SEE ALSO: CONTROL~ DO

## (FORWARD

STACKEFFECT: --- addr

DESCRIPTION:

Start a forward branch by leaving the address that must be backpatched with an offset into addr. Usage is POSTPONE BRANCH (FORWARD .. FORWARD)

GLOSSARY INDEX

SEE ALSO: CONTROL~ IF

## (LOOP)

STACKEFFECT:

DESCRIPTION:

The run-time proceedure compiled by LOOP which increments the loop index and tests for loop completion.

GLOSSARY INDEX

SEE ALSO: CONTROL~ LOOP

## 0BRANCH

STACKEFFECT: f ---

DESCRIPTION:

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

## 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:

The run-time proceedure to unconditionally branch. An in-line offset is added to the interpretive pointer IP to branch ahead or back. BRANCH is compiled by ELSE AGAIN REPEAT .

GLOSSARY INDEX

SEE ALSO: CONTROL~ 0BRANCH

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

# DEFINING

OVERVIEW:

The wordset DEFINING contains words that add new entries to the dictionary. 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:

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 (I) are executed rather than being compiled.

GLOSSARY INDEX

SEE ALSO: DEFINING

## ;

STACKEFFECT:

DESCRIPTION:

Terminate a colon-definition and stop further compilation. Compiles the run-time EXIT .

GLOSSARY INDEX

SEE ALSO: DEFINING :

## CONSTANT

STACKEFFECT: n ---

DESCRIPTION:

A defining word used in the form: n CONSTANT cccc to create word cccc , with its data field containing n . When cccc is later executed, it will push the value of n to the stack.

GLOSSARY INDEX

SEE ALSO: DEFINING VARIABLE

## CREATE

STACKEFFECT:

DESCRIPTION:

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 data field has yet to be allocated and the execution action can be changed. ciforth is byte aligned, so no extra measures are needed.

GLOSSARY INDEX

SEE ALSO: DEFINING DOES> ;CODE ALLOT , C,

## DOES>

STACKEFFECT:

DESCRIPTION:

A word which is normally use to specify the run-time action within a high-level defining word. DOES> modifies the behaviour of the latest word as to execute the sequence of compiled word addresses following DOES> . Used in combination with CREATE . 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, multidimensional arrays, and compiler generation.

GLOSSARY INDEX

SEE ALSO: DEFINING

## USER

STACKEFFECT: n ---

DESCRIPTION:

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 fixed offset relative to the user pointer register UP for this user variable. 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 ciforth the UP is fixed.

GLOSSARY INDEX

SEE ALSO: DEFINING VARIABLE +ORIGIN CONTEXT >DFA

## VARIABLE

STACKEFFECT:

DESCRIPTION:

A defining word used in the form: VARIABLE cccc When VARIABLE is executed, it creates the definition cccc with its data field pointing to a data location. When cccc is later executed, the content of its data field (containing n ) is left on the stack, so that a fetch or store may access this location.

GLOSSARY INDEX

SEE ALSO: DEFINING USER CONSTANT

## VOCABULARY

STACKEFFECT:

DESCRIPTION:

A defining word used in the form: VOCABULARY cccc to create a vocabulary 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 searched first by INTERPRET . A vocabulary 's data content field contains at first the dovoc pointer (like for any DOES> word) , then follows its body. The body contains the vocabulary link field address ( VLFA ). The VLFA points to the VLFA of the next vocabulary or a nil pointer for the end. Then follows a dummy dea that serves as word list identifier or WID in the sense of the ISO standard. It has empty fields, except for the link field. The link field address contains the DEA of the latest word of the vocabulary or a nil pointer if empty. Executing the vocabulary 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. The vocabularies generated are IMMEDIATE words.

GLOSSARY INDEX

SEE ALSO: DEFINING VOC-LINK DEFINITIONS

## (;CODE)

STACKEFFECT:

DESCRIPTION:

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~ (CREATE) ;CODE

## (CREATE)

STACKEFFECT: sc ---

DESCRIPTION:

This is the basis for all defining words. It lays down the string sc in the dictionary, then creates a dictionary entries with that string as the namefield. It is linked into the CURRENT word list. The code field and data field both point to the area owned by this header, i.e. immediately following the completed header as appropriate for a low level (assembler) definition. The flag field is empty , so not HIDDEN.

GLOSSARY INDEX

SEE ALSO: DEFINING~ CREATE

## ;CODE

STACKEFFECT:

DESCRIPTION:

Used in the form: : cccc CREATE .... ;CODE assembly mnemonics Stop compilation and terminate a new defining word cccc by compiling (;CODE). Set ASSEMBLER to the top of the search order order. Start assembling to machine code the following mnemonics. When cccc later executes in the form: cccc nnnn the word nnnn will be created with its execution proceedure given by the machine code following cccc . That is, when nnnn is executed, it does so by jumping to the code after nnnn . Because of intimate relation to the assembler, it is present in loadable form in the screens file ``forth.lab'' .

GLOSSARY INDEX

SEE ALSO: DEFINING~ (;CODE) LOAD :

# DENOTATIONS

OVERVIEW:

The wordset DENOTATIONS contains prefixes (mostly one letter words) that introduce a denotation, i.e. a generalisation of NUMBER . Any word starting with the prefix is considered found in the dictionary and the prefix word executed. These 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 wordset, called 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 in the dictionary do not contain the prefix. Apart from Prefix_0 , the vocabulary 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.

## Prefix_"

STACKEFFECT: --- sc

DESCRIPTION:

Parse a " delimited string and leave it on the stack. A " can be embedded in a string by doubling it. This is a denotation: during compilation this behaviour is compiled.

GLOSSARY INDEX

SEE ALSO: DENOTATIONS

## Prefix_&

STACKEFFECT: --- c

DESCRIPTION:

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:

Implements NUMBER for numbers that start with + .

GLOSSARY INDEX

SEE ALSO: DENOTATIONS

## Prefix_-

STACKEFFECT: --- s/d

DESCRIPTION:

Implements NUMBER for numbers that start with - .

GLOSSARY INDEX

SEE ALSO: DENOTATIONS

## Prefix_0

STACKEFFECT: --- s/d

DESCRIPTION:

Implements NUMBER for 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 B 7

## Prefix_7

STACKEFFECT: --- s/d

DESCRIPTION:

Implements NUMBER for numbers that start with 7 . Similar words are present for all decimal and hex digits.

GLOSSARY INDEX

SEE ALSO: DENOTATIONS 0 B

## Prefix_B

STACKEFFECT: --- s/d

DESCRIPTION:

Implements NUMBER for numbers that start with B . Similar words are present for all decimal and hex digits.

GLOSSARY INDEX

SEE ALSO: DENOTATIONS 0 7

## Prefix_^

STACKEFFECT: --- b

DESCRIPTION:

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 &

## Prefix__TICK

STACKEFFECT: --- addr

DESCRIPTION:

Used in the form:

'nnnn

In interpret mode it leaves the execution token (equivalent to the 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 ciforth it can be used in compilation mode too, it then compiles the address as a literal. It is recommended that one never compiles or postpones it. (Use a combination of WORD and FIND 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 forthcode({'}) by a space, the ISO-conforming version of ' is found.

GLOSSARY INDEX

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

# 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:

Used in the form:

' nnnn

It leaves the execution token (equivalent to the 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 WORD and FIND 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:

Store n into the next available dictionary memory cell, advancing the dictionary pointer.

GLOSSARY INDEX

SEE ALSO: DICTIONARY DP C,

## >BODY

STACKEFFECT: dea --- addr

DESCRIPTION:

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>

## ALLOT

STACKEFFECT: n ---

DESCRIPTION:

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 CELL+

## BODY>

STACKEFFECT: addr --- dea

DESCRIPTION:

Convert the data field addr of a definition created with a CREATE / DOES> construct to its dea. Where >BODY keeps working after revectoring , 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:

Store 8 bits of b into the next available dictionary byte, advancing the dictionary pointer.

GLOSSARY INDEX

SEE ALSO: DICTIONARY DP ,

## DP

STACKEFFECT: ---- addr

DESCRIPTION:

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:

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.

GLOSSARY INDEX

SEE ALSO: DICTIONARY CONTEXT PRESENT (FIND)

## FORGET

STACKEFFECT:

DESCRIPTION:

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.

GLOSSARY INDEX

SEE ALSO: DICTIONARY PRESENT CONTEXT FIND (FIND) VOCABULARY

## HERE

STACKEFFECT: --- addr

DESCRIPTION:

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 unusual 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:

Leave the address of the text output buffer, which is a fixed offset above HERE. The area growing downword from PAD is used for numeric conversion.

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 denotations 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. Prefix words are most 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. It is recommended that the only smart words present are prefix words.

GLOSSARY INDEX

SEE ALSO: DICTIONARY IMMEDIATE

## 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 a denotation word, the name must match sc exactly.

GLOSSARY INDEX

SEE ALSO: DICTIONARY FOUND CONTEXT FIND (FIND) VOCABULARY

## WORDS

STACKEFFECT:

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: DICTIONARY CONTEXT

## [']

STACKEFFECT: --- addr

DESCRIPTION:

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 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 vocabulary, 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 FIND 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. This is the address that is compiled within high level definitions, so it serves as an execution token. In ciforth it has offset 0, so it is actually the same as the DEA.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ ' CFA> >DFA >FFA >LFA >NFA >SFA >PHA

## >DFA

STACKEFFECT: dea --- addr

DESCRIPTION:

Given a dictionary entry addres return its data field address addr . This points to the code for a code word, 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~ ' >BODY >CFA >FFA >LFA >NFA >SFA >PHA

## >FFA

STACKEFFECT: dea --- addr

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ ' >CFA >DFA >LFA >NFA

## >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~ ' >CFA >DFA >FFA >NFA >PHA >SFA

## >NFA

STACKEFFECT: dea --- nfa

DESCRIPTION:

Given a dictionary entry addres return the name field address.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ ' >CFA >DFA >FFA >LFA >SFA

## >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~ ' >CFA >BODY

## >SFA

STACKEFFECT: dea --- addr

DESCRIPTION:

Given a dictionary entry addres return the source field address addr .

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ ' >CFA >DFA >FFA >LFA >NFA

## >VFA

STACKEFFECT: dea --- cfa

DESCRIPTION:

Given the dictionary entry addres of a vocabulary return the address of the link to the next vocabulary.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ VOCABULARY >CFA >WID

## >WID

STACKEFFECT: dea --- wid

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ VOCABULARY >CFA (FIND)

## >XFA

STACKEFFECT: dea --- addr

DESCRIPTION:

Given a dictionary entry addres return the extra field address addr .

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ ' >CFA >DFA >FFA >LFA >NFA

## CFA>

STACKEFFECT: cfa --- dea

DESCRIPTION:

Convert the code field address of a definition to its dictionary entry address dea.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ ' >CFA

## FENCE

STACKEFFECT: --- addr

DESCRIPTION:

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 wid --x1...xn

DESCRIPTION:

For all words from a word list identified by wid execute xt with as data x1..xn plus the DEA of those words. xt must have the stack diagram x1..xn dea --- x1..xn. Note that you can use the 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 (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 vocabulary 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:

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. This is an vector in behalf of optimisation, that starts as a noop, and can be filled in if the extra field is used for optimisation.

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. 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 has a non-zero name field.

GLOSSARY INDEX

SEE ALSO: DICTIONARY~ FIND CORA

# DOUBLE

OVERVIEW:

The wordset DOUBLE contains words that manipulate double's. In this 32 Forth you would hardly need doubles if it weren't for the NUMBER formatting wordset that uses them exclusively.

## D+

STACKEFFECT: d1 d2 --- dsum

DESCRIPTION:

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:

Leave the absolute value ud of a double number d .

GLOSSARY INDEX

SEE ALSO: DOUBLE DNEGATE ABS

## DNEGATE

STACKEFFECT: d1 --- d2

DESCRIPTION:

d2 is the negation of d1.

GLOSSARY INDEX

SEE ALSO: DOUBLE D+

## S>D

STACKEFFECT: n --- d

DESCRIPTION:

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 vocabulary and those words needed to recognize them as Forth environment queries. Note that these are not environment variables in the sense that are passed from an operating system to a program.

## CORE

STACKEFFECT: --- ff

DESCRIPTION:

An environment query whether the CORE wordset is present.

GLOSSARY INDEX

SEE ALSO: ENVIRONMENTS ENVIRONMENT?

## CPU

STACKEFFECT: --- d

DESCRIPTION:

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:

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 vocabulary and i*x is what is left by the word if executed.

GLOSSARY INDEX

SEE ALSO: ENVIRONMENTS VOCABULARY

## NAME

STACKEFFECT: --- sc

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: ENVIRONMENTS ENVIRONMENT?

## SUPPLIER

STACKEFFECT: --- sc

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: ENVIRONMENTS ENVIRONMENT?

## VERSION

STACKEFFECT: --- sc

DESCRIPTION:

An environment query giving the version 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 signalled by the kernel go through this word, allowing to catch e.g. errors in accessing the block file.

GLOSSARY INDEX

SEE ALSO: ERRORS ERROR ?ERRUR

## ?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:

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:

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. This word is executed by THROW before restarting the interpreter and can be revectored to give more elaborate diagnostics.

GLOSSARY INDEX

SEE ALSO: ERRORS ?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 unfeasible.

GLOSSARY INDEX

SEE ALSO: ERRORS C/L MESSAGE

## MESSAGE

STACKEFFECT: n ---

DESCRIPTION:

MESSAGE is generally used to print error and warning messages. 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. The messages with negative offset contain the strings belonging to the return values for Linux system calls . 0 MESSAGE will print version information about the library file, the messages sit in. If WARNING is zero (disc unavailable), the message will simply be ignored.

GLOSSARY INDEX

SEE ALSO: ERRORS ERROR

## THROW

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

DESCRIPTION:

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:

A user variable containing a value controlling messages. If it is 1, a library file is open, and messages are fetched from it. If it is 0, messages will be presented by number only. Don't set WARNING to 1 if there is no block system available, because the error system will call itself recursively. This may lead to a crash.

GLOSSARY INDEX

SEE ALSO: ERRORS MESSAGE ERROR ERRSCR

## WHERE

STACKEFFECT: --- addr

DESCRIPTION:

A user variable pair which contains the start of the source and the character position of the last error that was 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 are underlying the BLOCKS facilities.

## CLOSE-FILE

STACKEFFECT: fileid --- ior

DESCRIPTION:

Close the file with file handle in fileid. Return a result code into ior. The latter is the Linux error code negated, to be inspected using MESSAGE.

GLOSSARY INDEX

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

## CREATE-FILE

STACKEFFECT: sc u --- fileid ior

DESCRIPTION:

Create a file with name sc and file access privileges u 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.

GLOSSARY INDEX

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

## DELETE-FILE

STACKEFFECT: sc --- ior

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: FILES PUT-FILE OPEN-FILE THROW

## INCLUDED

STACKEFFECT: sc1 --- i*x

DESCRIPTION:

Interpret the content of the file with name sc1 as if it was typed from the console, leaving result i*x.

GLOSSARY INDEX

SEE ALSO: FILES LOAD

## OPEN-FILE

STACKEFFECT: sc fam --- fileid ior

DESCRIPTION:

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, to be inspected using MESSAGE. fam is one of 0=READ_ONLY, 1=WRITE_ONLY, 2=READ_WRITE.

GLOSSARY INDEX

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

## PUT-FILE

STACKEFFECT: sc1 sc2 ---

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: FILES GET-FILE OPEN-FILE THROW

## READ-FILE

STACKEFFECT: addr n1 fd --- n2 ior

DESCRIPTION:

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, to be inspected using MESSAGE.

GLOSSARY INDEX

SEE ALSO: FILES OPEN-FILE WRITE-FILE REPOSITION-FILE R\W

## REPOSITION-FILE

STACKEFFECT: ud fd --- ior

DESCRIPTION:

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:

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, to be inspected using MESSAGE.

GLOSSARY INDEX

SEE ALSO: FILES OPEN-FILE READ-FILE REPOSITION-FILE R\W

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

# 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:

Terminates numeric output conversion by dropping d, leaving the formatted string sc .

GLOSSARY INDEX

SEE ALSO: FORMATTING <#

## #S

STACKEFFECT: d1 --- d2

DESCRIPTION:

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:

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

## <#

STACKEFFECT:

DESCRIPTION:

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:

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

## BASE

STACKEFFECT: --- addr

DESCRIPTION:

A user variable containing the current number base used for input and output conversion.

GLOSSARY INDEX

SEE ALSO: FORMATTING DECIMAL HEX <#

## DECIMAL

STACKEFFECT:

DESCRIPTION:

Set the numeric conversion BASE for decimal input-output.

GLOSSARY INDEX

SEE ALSO: FORMATTING HEX

## HEX

STACKEFFECT:

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: FORMATTING DECIMAL

## HOLD

STACKEFFECT: c ---

DESCRIPTION:

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:

Stores an ASCII minus-sign - just before 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.

GLOSSARY INDEX

SEE ALSO: FORMATTING~ NUMBER ?BLANK

## 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 only a don't care value and a false flag.

GLOSSARY INDEX

SEE ALSO: FORMATTING~

## DPL

STACKEFFECT: ---- addr

DESCRIPTION:

A user variable containing the address of the decimal point on double integer input, or a nil pointer. It may also be used to hold the output column location of a decimal point, in user generated formating.

GLOSSARY INDEX

SEE ALSO: FORMATTING~ <# FLD HLD

## FLD

STACKEFFECT: --- addr

DESCRIPTION:

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:

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

GLOSSARY INDEX

SEE ALSO: FORMATTING~ <# DPL FLD

## NUMBER

STACKEFFECT: --- s/d

DESCRIPTION:

This word is intended to be called from single character denotation words, hence the parse pointer is decremented, to include this first character. Convert characters from the current input source into a number, and compile or execute this number. 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.

GLOSSARY INDEX

SEE ALSO: FORMATTING~ BASE (NUMBER)

# INIT

OVERVIEW:

The wordset INIT 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, so one can access or modify the boot-up parameters. During run time user variables are fetched from the current user area, via a pointer at 0 +ORIGIN . This can be swapped to get a fresh set of user variables, for multi-asking. One can access or modify the boot-up parameters, prior to saving a customised boot image. It will also change the initialisation by COLD.

GLOSSARY INDEX

SEE ALSO: INIT USER

## ABORT

STACKEFFECT:

DESCRIPTION:

Restart the system. In addition and before the actions of QUIT, clear also the data stack and reset the search order, reset the exception mechanism and set the numeric base to default. As required by ISO it 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: INIT WARM

## COLD

STACKEFFECT:

DESCRIPTION:

Reinitialise the system. Clear all block buffers. Reinitialise all user variables to their boot up values values, i.a. the stacks and the dictionary pointer . Opens the file that contains the blocks. Restart via ABORT . May be called from the terminal to remove application programs and restart, as long as there are no new vocabularies with definitions. But it is better to say BYE to Forth and start again.

GLOSSARY INDEX

SEE ALSO: INIT WARM BLOCK LIST

## OK

STACKEFFECT:

DESCRIPTION:

Takes care of printing the okay-message, after interpreting a line. Default it prints ``OK'' only for an interactive session in interpret STATE.

GLOSSARY INDEX

SEE ALSO: INIT QUIT COLD

## OPTIONS

STACKEFFECT: f1 -- f2

DESCRIPTION:

Handle command line options, i.e. execute the screen corresponding to the option letter. Accept and return a flag f whether the signon message must be displayed. By redefining this as a NOOP, the handling of options during cold boot is suppressed, useful for turnkey applications. By redefining as DROP 0, execution and signon are suppressed.

GLOSSARY INDEX

SEE ALSO: INIT COLD

## QUIT

STACKEFFECT:

DESCRIPTION:

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: INIT TIB ABORT

## WARM

STACKEFFECT:

DESCRIPTION:

Perform a so called "warm" start. In addition and before the actions of ABORT, discard blocks; they may not be written back to mass storage. Display the sign on message.

GLOSSARY INDEX

SEE ALSO: INIT ABORT

# 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

GLOSSARY INDEX

SEE ALSO: INPUT KEY KEY? ACCEPT

## >IN

STACKEFFECT: --- addr

DESCRIPTION:

Return a variable that contains the offset from the start 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 IN. The variable >IN is not actually used and its content must be fetched immediately.

GLOSSARY INDEX

SEE ALSO: INPUT (>IN) IN

## ACCEPT

STACKEFFECT: addr count --- n

DESCRIPTION:

Transfer at most count characters from the terminal to address, until a RET is received. 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. Note that excess characters after count are ignored. The number of characters not including the RET is returned into n.

GLOSSARY INDEX

SEE ALSO: INPUT (ACCEPT) KEY KEY? (ACCEPT)

## IN

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

GLOSSARY INDEX

SEE ALSO: INPUT >IN WORD (WORD) NUMBER (PARSE) IN[]

## KEY?

STACKEFFECT: --- ff

DESCRIPTION:

Return into ff return 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:

Leave the ASCII value of the next terminal key struck.

GLOSSARY INDEX

SEE ALSO: INPUT ACCEPT KEY?

## 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:

A user variable containing the address of the terminal input buffer.

GLOSSARY INDEX

SEE ALSO: INPUT QUIT

## (>IN)

STACKEFFECT: --- addr

DESCRIPTION:

If the standard word >IN is used, this variable contains the offset from the start 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 IN .

GLOSSARY INDEX

SEE ALSO: INPUT~ >IN IN

## 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 WORD . 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 reading after a RET occurs) REMAINDER 2@ contains the part of TIB that is not yet consumed by (ACCEPT) , and outside the reach of SRC . All system call errors result in an exception. For redirected I/O this word may generate an end-of-pipe exception.

GLOSSARY INDEX

SEE ALSO: INPUT~ ACCEPT (ACCEPT)

## REMAINDER

STACKEFFECT: --- addr

DESCRIPTION:

A pointer to a constant string that contains the balance of characters fetched into the input buffer, but not yet consumed. 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 termio 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~ SET-TERM

## TERMIO

STACKEFFECT: --- addr

DESCRIPTION:

Leave the address of the terminal description, this has the layout of a c-structure termio .

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's. Design your word such that you need them as little as possible, because they are confusing.

## 2DROP

STACKEFFECT: n1 n2 ---

DESCRIPTION:

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:

Duplicate the double number on the stack.

GLOSSARY INDEX

SEE ALSO: JUGGLING OVER

## 2OVER

STACKEFFECT: d1 d2 --- d1 d2 d1

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: JUGGLING 2DUP

## 2SWAP

STACKEFFECT: d1 d2 --- d2 d1

DESCRIPTION:

Exchange the top doubles on the stack.

GLOSSARY INDEX

SEE ALSO: JUGGLING ROT

## ?DUP

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

DESCRIPTION:

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:

Drop the number from the stack.

GLOSSARY INDEX

SEE ALSO: JUGGLING DUP

## DUP

STACKEFFECT: n --- n n

DESCRIPTION:

Duplicate the value on the stack.

GLOSSARY INDEX

SEE ALSO: JUGGLING OVER

## OVER

STACKEFFECT: nl n2 --- nl n2 n1

DESCRIPTION:

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:

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:

Exchange the top two values on the stack.

GLOSSARY INDEX

SEE ALSO: JUGGLING ROT

# 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 32 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:

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

GLOSSARY INDEX

SEE ALSO: LOGIC <

## 0=

STACKEFFECT: n --- ff

DESCRIPTION:

Leave a true flag ff is the number n is equal to zero, otherwise leave a false flag.

GLOSSARY INDEX

SEE ALSO: LOGIC =

## <>

STACKEFFECT: n1 n2 --- ff

DESCRIPTION:

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:

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:

Leave a true flag if n1=n2 ; otherwise leave a false flag.

GLOSSARY INDEX

SEE ALSO: LOGIC < > 0= -

## >

STACKEFFECT: n1 n2 --- ff

DESCRIPTION:

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:

Leave the bitwise logical and of n1 and n2 as n3 .

GLOSSARY INDEX

SEE ALSO: LOGIC XOR OR

## INVERT

STACKEFFECT: n1 --- n2

DESCRIPTION:

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:

Leave the bit-wise logical or of two 32-bit values.

GLOSSARY INDEX

SEE ALSO: LOGIC AND XOR

## U<

STACKEFFECT: u1 u2 --- ff

DESCRIPTION:

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:

Leave the bitwise logical exclusive or of two 32-bit values.

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:

Store all 32 bits of n at addr .

GLOSSARY INDEX

SEE ALSO: MEMORY @ C! 2! L! P! PC!

## +!

STACKEFFECT: n addr ---

DESCRIPTION:

Add n to the value addr.

GLOSSARY INDEX

SEE ALSO: MEMORY TOGGLE !

## 2!

STACKEFFECT: addr--- x1 x2

DESCRIPTION:

Store a pair of 32 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:

Leave a pair of 32 bits values x1 x2 from consequitive cells at addr . x2 is fetched from the lowest address.

GLOSSARY INDEX

SEE ALSO: MEMORY 2! @ C@

## @

STACKEFFECT: addr --- n

DESCRIPTION:

Leave the 32 bit contents n of addr .

GLOSSARY INDEX

SEE ALSO: MEMORY ! C@ 2@ P@ PC@ L@

## ALIGNED

STACKEFFECT: addr1 --- addr2

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: MEMORY ALIGN

## ALIGN

STACKEFFECT: ---

DESCRIPTION:

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:

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:

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:

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:

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

GLOSSARY INDEX

SEE ALSO: MEMORY

## CELLS

STACKEFFECT: n1 --- n2

DESCRIPTION:

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 both 16 and 32 bits systems, thanks to this.

GLOSSARY INDEX

SEE ALSO: MEMORY CELL+

## CHAR+

STACKEFFECT: n1 --- n2

DESCRIPTION:

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:

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

## CORA

STACKEFFECT: addr1 addr2 len -- n

DESCRIPTION:

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. It would have been named COMPARE , if that were not taken by ISO.

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:

This is shorthand for 0 FILL.

GLOSSARY INDEX

SEE ALSO: MEMORY BLANK FILL

## FARMOVE

STACKEFFECT: faraddr1 faraddr2 count ---

DESCRIPTION:

Move count bytes beginning at faraddr1 to faraddr2. Segments that are zero are replaced by defaults: data segment selector for source, extra segment selector for destination. Copying is done from low to high offset, so there may be memory propagating. This is not easily seen from the _SEGMENT_'s{}_PROTECTED_({{, particularly not so in protected mode}}). As the Intel 86-family is byte-addressing there are no restrictions.

GLOSSARY INDEX

SEE ALSO: MEMORY MOVE CMOVE

## FILL

STACKEFFECT: addr u b ---

DESCRIPTION:

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: n faraddr ---

DESCRIPTION:

Store 32 bits of n at segment address pair faraddr.

GLOSSARY INDEX

SEE ALSO: MEMORY L@ ! C! 2!

## L@

STACKEFFECT: faraddr --- n

DESCRIPTION:

Leave the 32 bit contents of segment address pair faraddr.

GLOSSARY INDEX

SEE ALSO: MEMORY L! @ C@ 2@

## MOVE

STACKEFFECT: from to count ---

DESCRIPTION:

Move the 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.

GLOSSARY INDEX

SEE ALSO: MEMORY

## P!

STACKEFFECT: n port ---

DESCRIPTION:

Store the 32 bit data n to the port address port. In practice on a IBM PC architecture a port address is 10 bits. You can use ports only after asking permission (using e.g. ioperm ) and being super user.

GLOSSARY INDEX

SEE ALSO: MEMORY P@ PC! PC@ !

## P@

STACKEFFECT: port --- n

DESCRIPTION:

Fetch the 32 bit contents n from the port address port. A port address is always 16 bits. In practice on a IBM PC architecture a port address is 10 bits. You can use ports only after asking permission (using e.g. ioperm ) and being super user.

GLOSSARY INDEX

SEE ALSO: MEMORY P! PC@ PC! @

## PC!

STACKEFFECT: b port ---

DESCRIPTION:

Store a byte b to the port address port. A port address is always 16 bits. In practice on a IBM PC architecture a port address is 10 bits. You can use ports only after asking permission (using e.g. ioperm ) and being super user.

GLOSSARY INDEX

SEE ALSO: MEMORY PC@ P! P@ !

## PC@

STACKEFFECT: port --- b

DESCRIPTION:

Fetch a byte b from the port address port. A port address is always 16 bits. In practice on a IBM PC architecture a port address is 10 bits. You can use ports only after asking permission (using e.g. ioperm ) and being super user.

GLOSSARY INDEX

SEE ALSO: MEMORY PC! P@ P! @

## TOGGLE

STACKEFFECT: addr b ---

DESCRIPTION:

Complement the contents of addr by the bit pattern b .

GLOSSARY INDEX

SEE ALSO: MEMORY XOR +!

## WITHIN

STACKEFFECT: n1 n2 n3 --- ff

DESCRIPTION:

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:

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. What is taken into account by user variables is the initialisation variable at 0 +ORIGIN . 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 MULTIPLYING wordset. In this 32-bit Forth you will have less need, but scaling remain tricky.. Formatting is done with double's exclusively, and relies on this wordset. Operators with mixed precision and unsigned operators allow to build arbitrary precision operators from them in high level code.

## */MOD

STACKEFFECT: n1 n2 n3 --- n4 n5

DESCRIPTION:

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 or n5 overflows. n1 n2 * n3 / gives an incorrect answer as soon as n1 n2 * overflows.

GLOSSARY INDEX

SEE ALSO: MULTIPLYING */ /MOD

## */

STACKEFFECT: n1 n2 n3 --- n4

DESCRIPTION:

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.

GLOSSARY INDEX

SEE ALSO: MULTIPLYING */MOD /MOD

## FM/MOD

STACKEFFECT: d n1 --- n2 n3

DESCRIPTION:

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 M/MOD / M*

## M*

STACKEFFECT: n1 n2 --- d

DESCRIPTION:

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 M/MOD SM/REM *

## M/MOD

STACKEFFECT: ud1 u2 --- u3 ud4

DESCRIPTION:

An unsigned mixed magnitude math operation which leaves a double quotient ud4 and remainder u3 , from a double dividend ud1 and single divisor u2.

GLOSSARY INDEX

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

## SM/REM

STACKEFFECT: d n1 --- n2 n3

DESCRIPTION:

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 M/MOD / M*

## UM*

STACKEFFECT: u1 u2 --- ud

DESCRIPTION:

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:

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 a null ended array of arguments strings, then by a null ended array of environment strings.

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM SYSTEM

## BYE

STACKEFFECT: ---

DESCRIPTION:

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

## LINOS5

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

DESCRIPTION:

Do a Linux 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

## LINOS

STACKEFFECT: n1 n2 n3 n---ret

DESCRIPTION:

Do a Linux 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, such as known by errno . This makes available all facilities present in Linux, except those with 4 or 5 parameters that are handled by LINOS5 .

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM ?ERRUR

## MS

STACKEFFECT: n ---

DESCRIPTION:

Wait for n milliseconds.

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM KEY?

## SHELL

STACKEFFECT: ---addr

DESCRIPTION:

Leave the address addr of a counted string, the name of a file that contains the command interpreter, or shell. This name may be changed an 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:

Have the operating system execute the command contained in the string sc.

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM BLOCK ?ERROR ?ERRUR

## ZEN

STACKEFFECT: sc --- addr

DESCRIPTION:

Leaves an address that contains a zero-ended (c-type) equivalent of sc. The same buffer is reused, such that this word is not reentrant. Use the word immediately, e.g. its intended used is passing parameters to the operating system. In fact this is RW-BUFFER .

GLOSSARY INDEX

SEE ALSO: OPERATINGSYSTEM OPEN-FILE LINOS LINOS5

# 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 worrysome 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:

Leave the signed product n3 of two signed numbers n1 and n2 .

GLOSSARY INDEX

SEE ALSO: OPERATOR + - / MOD

## +

STACKEFFECT: n1 n2 --- sum

DESCRIPTION:

Leave the sum of n1 and n2 .

GLOSSARY INDEX

SEE ALSO: OPERATOR - * / MOD

## -

STACKEFFECT: n1 n2 --- diff

DESCRIPTION:

Leave the difference of n1 and n2 .

GLOSSARY INDEX

SEE ALSO: OPERATOR NEGATE + * / MOD

## /MOD

STACKEFFECT: n1 n2 --- rem quot

DESCRIPTION:

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:

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

GLOSSARY INDEX

SEE ALSO: OPERATOR + - * MOD */MOD

## ABS

STACKEFFECT: n --- u

DESCRIPTION:

Leave the absolute value of n as u .

GLOSSARY INDEX

SEE ALSO: OPERATOR DABS

## LSHIFT

STACKEFFECT: u1 n --- u2

DESCRIPTION:

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:

Leave the greater of two numbers.

GLOSSARY INDEX

SEE ALSO: OPERATOR MIN

## MIN

STACKEFFECT: n1 n2 --- min

DESCRIPTION:

Leave the smaller of two numbers.

GLOSSARY INDEX

SEE ALSO: OPERATOR MAX

## MOD

STACKEFFECT: n1 n2 --- mod

DESCRIPTION:

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:

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

GLOSSARY INDEX

SEE ALSO: OPERATOR -

## RSHIFT

STACKEFFECT: u1 n --- u2

DESCRIPTION:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

If n is greater or equal to zero, display as much spaces.

GLOSSARY INDEX

SEE ALSO: OUTPUT SPACE OUT

## SPACE

STACKEFFECT:

DESCRIPTION:

Transmit an ASCII blank to the output device.

GLOSSARY INDEX

SEE ALSO: OUTPUT EMIT OUT

## TYPE

STACKEFFECT: addr count ---

DESCRIPTION:

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 Linux. 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:

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

## (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. The difference with an ISO PARSE is that ISO considers control characters a match for a blank.

GLOSSARY INDEX

SEE ALSO: PARSING WORD (WORD)

## (WORD)

STACKEFFECT: --- sc

DESCRIPTION:

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.

GLOSSARY INDEX

SEE ALSO: PARSING BLK WORD IN

## (

STACKEFFECT:

DESCRIPTION:

{{Used in the form: forthsamp({{( 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{{}}_VERBOSE_({{, so colon definitions can be commented too}}). A blank after the word forthcode({{(}}) is required.}}

GLOSSARY INDEX

SEE ALSO: PARSING \

## ?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.

GLOSSARY INDEX

SEE ALSO: PARSING BL SPACE

## CHAR

STACKEFFECT: --- c

DESCRIPTION:

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:

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 not 1) or compile it (STATE is 1). A word is blank-delimited and looked up in the vocabularies of search-order. Note that the denotations in the ONLY wordlist match numbers. If it is not found at all, it is an ERROR. 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 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 are ignored in ciforth. )

GLOSSARY INDEX

SEE ALSO: PARSING WORD NUMBER BLK DPL

## IN[]

STACKEFFECT: ---addr c

DESCRIPTION:

Parse the current input source leaving the next character c and its address addr . 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 IN

## 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 followed by a call to INTERPRET.

GLOSSARY INDEX

SEE ALSO: PARSING EVALUATE INTERPRET

## SOURCE

STACKEFFECT: --- addr n1

DESCRIPTION:

Return the address and length of the current input source .

GLOSSARY INDEX

SEE ALSO: PARSING SRC SOURCE-ID

## 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 and non-inclusive highest 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 using RESTORE-INPUT, or changing only the third cell. The third cell has the alias IN . Words like >IN BLK SOURCE SOURCE-ID are secondary, and return their output by ``second-guessing'' SRC .

GLOSSARY INDEX

SEE ALSO: PARSING BLK SOURCE-ID

## STATE

STACKEFFECT: --- addr

DESCRIPTION:

A user variable containing the compilation state. A non-zero value indicates compilation.

GLOSSARY INDEX

SEE ALSO: PARSING

## WORD

STACKEFFECT: c ---addr

DESCRIPTION:

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 (WORD) (PARSE) BLK IN

## [CHAR]

STACKEFFECT: --- c

DESCRIPTION:

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:

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:

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:

Resume compilation, to the completion of a colon-definition.

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

## -->

STACKEFFECT:

DESCRIPTION:

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: SCREEN LOCK CATCH LOAD

## 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:

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:

Interrupt the current input source in order to interpret screen 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 #BUFF THRU QUIT EXIT --> LIST

## LOCK

STACKEFFECT: n ---

DESCRIPTION:

Lock the block n. Multiple locks are possible, and require multiple unlocks. Probably, because 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 UNLOCK #BUFF

## R#

STACKEFFECT: --- addr

DESCRIPTION:

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:

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

GLOSSARY INDEX

SEE ALSO: SCREEN BLOCK

## THRU

STACKEFFECT: n1 n2 --- ??

DESCRIPTION:

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:

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:

Unlock the block n. 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 #BUFF

## (BLK)

STACKEFFECT: --- addr

DESCRIPTION:

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:

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, and 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:

Issue an error message if not executing.

GLOSSARY INDEX

SEE ALSO: SECURITY ?ERROR

## ?LOADING

STACKEFFECT:

DESCRIPTION:

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:

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.

GLOSSARY INDEX

SEE ALSO: STACKS LIST

## >R

STACKEFFECT: n ---

DESCRIPTION:

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@

## DEPTH

STACKEFFECT: --- n1

DESCRIPTION:

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@

## 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:

A user variable containing the initial location of the return stack.

GLOSSARY INDEX

SEE ALSO: STACKS RSP!

## R>

STACKEFFECT: --- n

DESCRIPTION:

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:

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@

## 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:

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:

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: addr --- sc

DESCRIPTION:

From address addr fetch a string constant sc .

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 $@ $! $+!

## $I

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 $S CORA

## $S

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 $I CORA

## -TRAILING

STACKEFFECT: sc1 --- sc2

DESCRIPTION:

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:

A constant that leaves the ASCII value for "blank".

GLOSSARY INDEX

SEE ALSO: STRING

## COUNT

STACKEFFECT: addr1 --- addr2 n

DESCRIPTION:

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 addr n from the brain damaged string variable at addr1 .

GLOSSARY INDEX

SEE ALSO: STRING TYPE

## S"

STACKEFFECT: --- addr1 n

DESCRIPTION:

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:

This is shorthand for ``1 +''.

GLOSSARY INDEX

SEE ALSO: SUPERFLUOUS CELL+ 1-

## 1-

STACKEFFECT: n1 --- n2

DESCRIPTION:

This is shorthand for 1 -.

GLOSSARY INDEX

SEE ALSO: SUPERFLUOUS 1+

## 2*

STACKEFFECT: n1 --- n2

DESCRIPTION:

Perform an arithmetical {shift} left. The bit pattern of n1 is shifted to the left, with a result identical to 1 LSHIFT. This word should not be used.

GLOSSARY INDEX

SEE ALSO: SUPERFLUOUS 2/

## 2/

STACKEFFECT: n1 --- n2

DESCRIPTION:

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. This is the same as S>D 2 FM/MOD SWAP DROP. It is not the same as 2 / , nor is it the same as 1 RSHIFT. This confusing word should never be used.

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 VOCABULARY and filled by defining words while that vocabulary 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 no name, but a word list identifier or WID, which is inconvenient. We use vocabulary words created by the defining word VOCABULARY . They are used to manipulate the word list's that are associated with them. So vocabularies are nearly the wordlist 's of the ISO standard, the primary difference is that they have a name.

## ALSO

STACKEFFECT:

DESCRIPTION:

Duplicate the topmost WID in the search order stack. If there were already 16 WID 's, ciforth looses the last one. This is not counting the ONLY search order. You seldomly want to use this word, because in ciforth by naming a vocabulary you add it to the order.

GLOSSARY INDEX

SEE ALSO: WORDLISTS CONTEXT VOCABULARY

## ASSEMBLER

STACKEFFECT:

DESCRIPTION:

The name of the vocabulary to make machine code definitions. In ciforth execution it pushes the associated word list to the top of the CONTEXT stack. (For ISO-compliance it would replace the top.) ASSEMBLER is immediate, so it will execute during the creation of a colon-definition, to select this vocabulary at compile time. 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 VOCABULARY LOAD

## CONTEXT

STACKEFFECT: --- addr

DESCRIPTION:

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. CONTEXT is the last user variable at offset 37 , such that new user variables may be allocated using offsets of 37+16 and up.

GLOSSARY INDEX

SEE ALSO: WORDLISTS PRESENT VOCABULARY CURRENT USER

## CURRENT

STACKEFFECT: --- addr

DESCRIPTION:

A user variable containing the WID of a vocabulary 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 VOCABULARY CONTEXT

## DEFINITIONS

STACKEFFECT:

DESCRIPTION:

Used in the form: cccc DEFINITIONS Make the top most search order word list, (context), the compilation word list (current). In the example, executing vocabulary 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 VOCABULARY

## ENVIRONMENT

STACKEFFECT:

DESCRIPTION:

The name of the ENVIRONMENT vocabulary. 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 VOCABULARY

## FORTH

STACKEFFECT:

DESCRIPTION:

The name of the primary vocabulary. Execution pushes the FORTH WID to the top of the search order . (For ISO-compliance it would replace the top.) Until additional user word list 's are created, new user definitions become a part of FORTH . FORTH is immediate, so it will execute during the creation of a colon-definition, to select this word list at compile time.

GLOSSARY INDEX

SEE ALSO: WORDLISTS CONTEXT VOCABULARY

## LATEST

STACKEFFECT: --- addr

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: WORDLISTS VOCABULARY

## ONLY

STACKEFFECT:

DESCRIPTION:

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 VOCABULARY. The associated word list contains mainly prefix words, that scan denotations and are described in the chapter DENOTATIONS. If found the parse pointer is moved back to immediately after the prefix, and the corresponding denotation definition executed. If you want to add a denotation, add it to the ONLY wordlist preferably. This prevents masking regular words with the same prefix.

GLOSSARY INDEX

SEE ALSO: WORDLISTS PREFIX

## PREVIOUS

STACKEFFECT:

DESCRIPTION:

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

GLOSSARY INDEX

SEE ALSO: WORDLISTS CONTEXT VOCABULARY

## VOC-LINK

STACKEFFECT: --- addr

DESCRIPTION:

A user variable containing the dictionary entry address of the word most recently created by VOCABULARY . All vocabulary names are linked by these fields to allow FORGET to find all vocabularies.

GLOSSARY INDEX

SEE ALSO: WORDLISTS~ VOCABULARY