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 > ?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 BDOSN BDOSO BEGIN BIOSN BIOSO 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 LIST LITERAL LIT LOAD LOCK LOOP LOW-DP LOW-EM LSHIFT M* M/MOD MAX MESSAGE MIN MOD MOVE MS NAME NEGATE NOOP NUMBER Number_1 Number_2 OFFSET OK ONLY OPEN-FILE OPTIONS 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 SHELL SIGN SKIP SM/REM SOURCE SPACES SPACE SRC STALEST STATE SUPPLIER SWAP SYSTEM TASK 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] [ \ ] _ m_s_fetch ~MATCH
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
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.
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.
SEE ALSO: BLOCKS BLOCK THRU LOAD LOCK
STACKEFFECT: n---
DESCRIPTION:
Interpret n as the status of a disk i/o call and signal an error if it contains an error condition.
SEE ALSO: BLOCKS BLOCK-FILE BLOCK-HANDLE BLOCK-INIT BLOCK-EXIT
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.
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.
SEE ALSO: BLOCKS BLOCK LIST LOAD DISK-ERROR WARNING
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 30 characters long. The default name is forth.lab . This name may be changed and is used by the BLOCK-INIT command.
SEE ALSO: BLOCKS BLOCK-HANDLE BLOCK-INIT BLOCK-EXIT
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.
SEE ALSO: BLOCKS BLOCK-FILE BLOCK-INIT BLOCK-EXIT
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.
SEE ALSO: BLOCKS BLOCK LIST LOAD BLOCK-EXIT OPEN-FILE
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.
SEE ALSO: BLOCKS (BUFFER) R\W OFFSET UPDATE FLUSH LOAD
STACKEFFECT: --- addr
DESCRIPTION:
Leave the address addr of a variable containing information about the latest disk error in opening, using or closing the block file. One means an error and and zero means okay. Beware that if error messages are loaded from disk, this may clear DISK-ERROR .
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.
SEE ALSO: BLOCKS FLUSH BLOCK SCREEN UPDATE
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.
SEE ALSO: BLOCKS BLOCK DISK-ERROR
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.
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.
SEE ALSO: BLOCKS~ BLOCK STALEST PREV #BUFF LOCK UNLOCK
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.
STACKEFFECT: --- n
DESCRIPTION:
A constant that leaves the address of the first (lowest) block buffer.
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.
SEE ALSO: BLOCKS~ EMPTY-BUFFERS BLOCK SCREEN
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.
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.
SEE ALSO: BLOCKS~ BLOCK MESSAGE
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.
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.
SEE ALSO: BLOCKS~ RESTORE SAVE-INPUT
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.
SEE ALSO: BLOCKS~ RESTORE-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.
SEE ALSO: BLOCKS~ RESTORE RESTORE-INPUT
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.
SEE ALSO: BLOCKS~ RESTORE SAVE-INPUT
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.
SEE ALSO: BLOCKS~ BLOCK LIST LOAD
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.
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.
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.
SEE ALSO: COMPILING LITERAL LIT
STACKEFFECT: n --- n (executing) n --- (compiling)
DESCRIPTION:
If compiling, then compile the stack value n as a 16 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.
SEE ALSO: COMPILING LIT LITERAL
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.
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.
STACKEFFECT: --- n
DESCRIPTION:
Within a colon-definition, LIT is compiled followed by a 16 bit literal number given during compilation. Later execution of LIT causes the contents of this next dictionary cell to be pushed to the stack.
SEE ALSO: COMPILING~ LITERAL
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.
SEE ALSO: COMPILING~ SLITERAL DLITERAL
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.
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.
SEE ALSO: CONTROL
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.
SEE ALSO: CONTROL DO I LOOP +LOOP LEAVE
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.
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.
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 .
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.
SEE ALSO: CONTROL I LOOP +LOOP LEAVE
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 .
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.
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.
STACKEFFECT: --- n
DESCRIPTION:
Used within a do-loop to copy the loop index to the stack.
SEE ALSO: CONTROL DO LOOP +LOOP
STACKEFFECT: --- n
DESCRIPTION:
Used within a nested do-loop to copy the loop index of the outer do-loop to the stack.
SEE ALSO: CONTROL DO LOOP +LOOP
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 .
SEE ALSO: CONTROL
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.
STACKEFFECT: (varies)
DESCRIPTION:
Do a recursive call of the definition being compiled.
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.
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.
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.
SEE ALSO: CONTROL FORWARD) IF ELSE
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.
SEE ALSO: CONTROL DO LOOP +LOOP (BACK (FORWARD EXIT
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.
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.
SEE ALSO: CONTROL (FORWARD BEGIN
STACKEFFECT: n ---
DESCRIPTION:
The run-time proceedure compiled by +LOOP, which increments the loop index by n and tests for loop completion.
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.
STACKEFFECT:
DESCRIPTION:
The run-time proceedure compiled by ?DO which prepares the return stack, where the looping bookkeeping is kept.
STACKEFFECT: --- addr
DESCRIPTION:
Start a backward branch by leaving the target address HERE into addr. Usage is (BACK .. POSTPONE BRANCH BACK)
SEE ALSO: CONTROL~ BACK) BEGIN DO
STACKEFFECT:
DESCRIPTION:
The run-time proceedure compiled by DO which prepares the return stack, where the looping bookkeeping is kept.
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)
STACKEFFECT:
DESCRIPTION:
The run-time proceedure compiled by LOOP which increments the loop index and tests for loop completion.
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 .
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)
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 .
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)
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.
SEE ALSO: DEFINING
STACKEFFECT:
DESCRIPTION:
Terminate a colon-definition and stop further compilation. Compiles the run-time EXIT .
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.
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.
SEE ALSO: DEFINING DOES> ;CODE ALLOT , C,
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.
SEE ALSO: DEFINING
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.
SEE ALSO: DEFINING VARIABLE +ORIGIN CONTEXT >DFA
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.
SEE ALSO: DEFINING USER CONSTANT
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 8 word list 's in the search order, the oldest one gets lost. The vocabularies generated are IMMEDIATE words.
SEE ALSO: DEFINING VOC-LINK DEFINITIONS
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.
SEE ALSO: DEFINING~ (CREATE) ;CODE
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.
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'' .
SEE ALSO: DEFINING~ (;CODE) LOAD :
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.
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.
SEE ALSO: DENOTATIONS
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.
SEE ALSO: DENOTATIONS ^
STACKEFFECT: --- s/d
DESCRIPTION:
Implements NUMBER for numbers that start with + .
SEE ALSO: DENOTATIONS
STACKEFFECT: --- s/d
DESCRIPTION:
Implements NUMBER for numbers that start with - .
SEE ALSO: DENOTATIONS
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.
SEE ALSO: DENOTATIONS B 7
STACKEFFECT: --- s/d
DESCRIPTION:
Implements NUMBER for numbers that start with 7 . Similar words are present for all decimal and hex digits.
SEE ALSO: DENOTATIONS 0 B
STACKEFFECT: --- s/d
DESCRIPTION:
Implements NUMBER for numbers that start with B . Similar words are present for all decimal and hex digits.
SEE ALSO: DENOTATIONS 0 7
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.
SEE ALSO: DENOTATIONS &
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.
SEE ALSO: DENOTATIONS CONTEXT ['] PRESENT >CFA >DFA >FFA >LFA >NFA >SFA
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.
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.
SEE ALSO: DICTIONARY DP C,
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.
SEE ALSO: DICTIONARY ' >CFA >DFA >PHA BODY>
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.
SEE ALSO: DICTIONARY CELL+
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.
SEE ALSO: DICTIONARY ' >BODY
STACKEFFECT: b ---
DESCRIPTION:
Store 8 bits of b into the next available dictionary byte, advancing the dictionary pointer.
SEE ALSO: DICTIONARY 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 .
SEE ALSO: DICTIONARY
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.
SEE ALSO: DICTIONARY CONTEXT PRESENT (FIND)
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.
SEE ALSO: DICTIONARY FENCE FORGET-VOC
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.
SEE ALSO: DICTIONARY PRESENT CONTEXT FIND (FIND) VOCABULARY
STACKEFFECT: --- addr
DESCRIPTION:
Leave the address addr of the next available dictionary location.
SEE ALSO: DICTIONARY DP
STACKEFFECT: dea ---
DESCRIPTION:
Print a definition's name from its dictionary entry address. For dummy entries print nothing.
SEE ALSO: DICTIONARY ' >FFA >NFA
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 .
SEE ALSO: DICTIONARY
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.
SEE ALSO: DICTIONARY
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.
SEE ALSO: DICTIONARY IMMEDIATE
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.
SEE ALSO: DICTIONARY FOUND CONTEXT FIND (FIND) VOCABULARY
STACKEFFECT:
DESCRIPTION:
List the names of the definitions in the topmost word list of the search order.
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.
SEE ALSO: DICTIONARY FOUND ' EXECUTE
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.
SEE ALSO: DICTIONARY~ ~MATCH FIND PRESENT >WID
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.
SEE ALSO: DICTIONARY~ ' CFA> >DFA >FFA >LFA >NFA >SFA >PHA
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 .
SEE ALSO: DICTIONARY~ ' >BODY >CFA >FFA >LFA >NFA >SFA >PHA
STACKEFFECT: dea --- addr
DESCRIPTION:
Given a dictionary entry addres return its flag field address addr .
SEE ALSO: DICTIONARY~ ' >CFA >DFA >LFA >NFA
STACKEFFECT: dea --- addr
DESCRIPTION:
Given a dictionary entry addres return its link field address addr. It contains the DEA of the previous word.
SEE ALSO: DICTIONARY~ ' >CFA >DFA >FFA >NFA >PHA >SFA
STACKEFFECT: dea --- nfa
DESCRIPTION:
Given a dictionary entry addres return the name field address.
SEE ALSO: DICTIONARY~ ' >CFA >DFA >FFA >LFA >SFA
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.
SEE ALSO: DICTIONARY~ ' >CFA >BODY
STACKEFFECT: dea --- addr
DESCRIPTION:
Given a dictionary entry addres return the source field address addr .
SEE ALSO: DICTIONARY~ ' >CFA >DFA >FFA >LFA >NFA
STACKEFFECT: dea --- cfa
DESCRIPTION:
Given the dictionary entry addres of a vocabulary return the address of the link to the next vocabulary.
SEE ALSO: DICTIONARY~ VOCABULARY >CFA >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.
SEE ALSO: DICTIONARY~ VOCABULARY >CFA (FIND)
STACKEFFECT: cfa --- dea
DESCRIPTION:
Convert the code field address of a definition to its dictionary entry address dea.
SEE ALSO: DICTIONARY~ ' >CFA
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 .
SEE ALSO: DICTIONARY~
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
SEE ALSO: DICTIONARY~ FOR-WORDS EXECUTE
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.
SEE ALSO: DICTIONARY~ FOR-VOCS EXECUTE
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.
SEE ALSO: DICTIONARY~ FORGET
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.
SEE ALSO: DICTIONARY~ IMMEDIATE RECURSE
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.
SEE ALSO: DICTIONARY~ FIND CORA
OVERVIEW:
The wordset DOUBLE contains words that manipulate double's.
STACKEFFECT: d1 d2 --- dsum
DESCRIPTION:
Leave the double number dsum: the sum of two double numbers d1 and d2 .
STACKEFFECT: d --- ud
DESCRIPTION:
Leave the absolute value ud of a double number d .
STACKEFFECT: d1 --- d2
DESCRIPTION:
d2 is the negation of d1.
STACKEFFECT: n --- d
DESCRIPTION:
Sign extend a single number to form a double number.
SEE ALSO: DOUBLE
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.
STACKEFFECT: --- ff
DESCRIPTION:
An environment query whether the CORE wordset is present.
SEE ALSO: ENVIRONMENTS ENVIRONMENT?
STACKEFFECT: --- d
DESCRIPTION:
An environment query returning the cpu-type to be printed as a base-36 number.
SEE ALSO: ENVIRONMENTS 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.
SEE ALSO: ENVIRONMENTS VOCABULARY
STACKEFFECT: --- sc
DESCRIPTION:
An environment query giving the name of this Forth as a string constant.
SEE ALSO: ENVIRONMENTS ENVIRONMENT?
STACKEFFECT: --- sc
DESCRIPTION:
An environment query giving the SUPPLIER of this Forth as a string constant.
SEE ALSO: ENVIRONMENTS ENVIRONMENT?
STACKEFFECT: --- sc
DESCRIPTION:
An environment query giving the version of this Forth as a string constant.
SEE ALSO: ENVIRONMENTS ENVIRONMENT?
OVERVIEW:
The wordset ERRORS contains words to handle errors and exceptions.
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.
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 .
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.
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.
SEE ALSO: ERRORS THROW QUIT HANDLER
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.
SEE ALSO: ERRORS ?ERROR WARNING
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.
STACKEFFECT: n ---
DESCRIPTION:
MESSAGE is generally used to print error and warning messages. Print on the output device 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 BDOS 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.
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.
SEE ALSO: ERRORS CATCH QUIT HANDLER ?ERROR ERROR
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.
SEE ALSO: ERRORS MESSAGE ERROR ERRSCR
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.
STACKEFFECT: f ---
DESCRIPTION:
The run time action of ABORT" .
SEE ALSO: ERRORS~
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 .
OVERVIEW:
The wordset FILES contains words to input and output to files, or load words from files. They are underlying the BLOCKS facilities.
STACKEFFECT: fileid --- ior
DESCRIPTION:
Close the file with file handle in fileid. Return a result code into ior. The latter is the MSDOS error code negated, to be inspected using MESSAGE.
SEE ALSO: FILES OPEN-FILE READ-FILE WRITE-FILE CREATE-FILE DELETE-FILE
STACKEFFECT: sc u --- fileid ior
DESCRIPTION:
Create a file with name sc and properties u, for normal files this is just 0. The meaning is to be found in the MSDOS programmers manual at INT 21h function 3Ch "Create file with handle". 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 MSDOS negated, to be inspected using MESSAGE . The handle is open for READ_WRITE.
SEE ALSO: FILES OPEN-FILE READ-FILE WRITE-FILE CREATE-FILE DELETE-FILE
STACKEFFECT: sc --- ior
DESCRIPTION:
Delete the file with name sc. Return a result code into ior. The latter is the MSDOS negated, to be inspected using MESSAGE .
SEE ALSO: FILES OPEN-FILE READ-FILE WRITE-FILE CREATE-FILE DELETE-FILE
STACKEFFECT: sc1 --- sc2
DESCRIPTION:
Get the content of the file with name sc1; leave it as a string sc2. Any errors are thrown.
SEE ALSO: FILES PUT-FILE OPEN-FILE THROW
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.
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 MSDOS error code negated, to be inspected using MESSAGE. fam is one of 0=READ_ONLY, 1=WRITE_ONLY, 2=READ_WRITE.
SEE ALSO: FILES OPEN-FILE READ-FILE WRITE-FILE CREATE-FILE DELETE-FILE
STACKEFFECT: sc1 sc2 ---
DESCRIPTION:
Save the string constant sc2 to a file with the name sc1. Any errors are thrown.
SEE ALSO: FILES GET-FILE OPEN-FILE THROW
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 the MSDOS error code negated, to be inspected using MESSAGE.
SEE ALSO: FILES OPEN-FILE WRITE-FILE REPOSITION-FILE R\W
STACKEFFECT: ud fd --- ior
DESCRIPTION:
Position the file that is open at fd at position ud. ior is 0 for success, or otherwise the MSDOS error code negated . Information about error codes can be found by MESSAGE.
SEE ALSO: FILES OPEN-FILE READ-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 the MSDOS error code negated, to be inspected using MESSAGE.
SEE ALSO: FILES OPEN-FILE READ-FILE REPOSITION-FILE R\W
STACKEFFECT: --- addr
DESCRIPTION:
A constant that leaves the address of a disk buffer used by file i/o words.It is primarily used for building up a zero ended string, such as not to burden pad.
SEE ALSO: FILES~ READ-FILE OPEN-FILE
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 .
SEE ALSO: FORMATTING <#
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 #>.
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 #>.
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 .
SEE ALSO: FORMATTING DPL HLD HOLD FLD
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 .
SEE ALSO: FORMATTING NUMBER DIGIT
STACKEFFECT: --- addr
DESCRIPTION:
A user variable containing the current number base used for input and output conversion.
SEE ALSO: FORMATTING DECIMAL HEX <#
STACKEFFECT:
DESCRIPTION:
Set the numeric conversion BASE for decimal input-output.
SEE ALSO: FORMATTING HEX
STACKEFFECT:
DESCRIPTION:
Set the numeric conversion BASE for hexadecimal (base 16) input-output.
SEE ALSO: FORMATTING DECIMAL
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 .
SEE ALSO: FORMATTING # DIGIT
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 #> .
SEE ALSO: FORMATTING HOLD
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.
SEE ALSO: FORMATTING~ NUMBER ?BLANK
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.
SEE ALSO: FORMATTING~
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.
SEE ALSO: FORMATTING~ <# FLD HLD
STACKEFFECT: --- addr
DESCRIPTION:
A user variable for control of number output field width. Unused in the kernel of ciforth.
SEE ALSO: FORMATTING~
STACKEFFECT: --- addr
DESCRIPTION:
A user variable that holds the address of the latest character of text during numeric output conversion.
SEE ALSO: FORMATTING~ <# DPL FLD
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.
SEE ALSO: FORMATTING~ BASE (NUMBER)
OVERVIEW:
The wordset INIT contains words to initialise, reinitialise or configure Forth.
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.
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.
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.
SEE ALSO: INIT WARM BLOCK LIST
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.
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.
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.
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.
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.
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 a trailing LF. But possibly a trailing RET (0x0D). The editing functions are the same as with ACCEPT . This is lighter on the system and sometimes easier to use than ACCEPT. Text is probably present in the buffer address contained in TIB @, but not necessarily at the beginning.
SEE ALSO: INPUT KEY KEY? ACCEPT
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.
STACKEFFECT: addr count --- n
DESCRIPTION:
Transfer at most count characters from the terminal to address, until a RET is received. The backspace key on the standard PC keyboard layout is used to delete characters, without involvement of Forth, so changing RUBOUT has no effect. Other editing keys such as F3 and cursor keys probably work as usual with a console application. Note that excess characters after count are ignored. The number of characters not including the RET is returned into n.
SEE ALSO: INPUT (ACCEPT) KEY KEY? (ACCEPT)
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 .
SEE ALSO: INPUT >IN WORD (WORD) NUMBER (PARSE) IN[]
STACKEFFECT: --- f
DESCRIPTION:
Perform a test of the terminal keyboard for a break request. Any key pressed is interpreted as such and the key is not consumed. A non-zero flag indicates actuation.
STACKEFFECT: --- c
DESCRIPTION:
Leave the ASCII value of the next terminal key struck.
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.
STACKEFFECT: --- addr
DESCRIPTION:
A user variable containing the address of the terminal input buffer.
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 .
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.
SEE ALSO: INPUT~ ACCEPT (ACCEPT)
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@ .
SEE ALSO: INPUT~ REFILL-TIB
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.
STACKEFFECT: n1 n2 ---
DESCRIPTION:
Drop the topmost two numbers (or one double number) from the stack.
STACKEFFECT: d --- d d
DESCRIPTION:
Duplicate the double number on the stack.
STACKEFFECT: d1 d2 --- d1 d2 d1
DESCRIPTION:
Copy the second stack double, placing it as the new top.
STACKEFFECT: d1 d2 --- d2 d1
DESCRIPTION:
Exchange the top doubles on the stack.
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.
STACKEFFECT: n ---
DESCRIPTION:
Drop the number from the stack.
STACKEFFECT: n --- n n
DESCRIPTION:
Duplicate the value on the stack.
STACKEFFECT: nl n2 --- nl n2 n1
DESCRIPTION:
Copy the second stack value, placing it as the new top.
STACKEFFECT: nl n2 n3 --- n2 n3 nl
DESCRIPTION:
Rotate the top three values on the stack, bringing the third to the top.
STACKEFFECT: n1 n2 --- n2 n1
DESCRIPTION:
Exchange the top two values on the stack.
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 16 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.
STACKEFFECT: n --- ff
DESCRIPTION:
Leave a true flag if the number is less than zero (negative), otherwise leave a false flag.
STACKEFFECT: n --- ff
DESCRIPTION:
Leave a true flag ff is the number n is equal to zero, otherwise leave a false flag.
STACKEFFECT: n1 n2 --- ff
DESCRIPTION:
Leave a true flag if n1 is not equal than n2 ; otherwise leave a false flag.
STACKEFFECT: n1 n2 --- ff
DESCRIPTION:
Leave a true flag if n1 is less than n2 ; otherwise leave a false flag.
STACKEFFECT: n1 n2 --- ff
DESCRIPTION:
Leave a true flag if n1=n2 ; otherwise leave a false flag.
STACKEFFECT: n1 n2 --- ff
DESCRIPTION:
Leave a true flag if n1 is greater than n2 ; otherwise leave a false flag.
STACKEFFECT: n1 n2 --- n3
DESCRIPTION:
Leave the bitwise logical and of n1 and n2 as n3 .
STACKEFFECT: n1 --- n2
DESCRIPTION:
Invert all bits of n1 leaving n2 . For pure flags (0 or -1) this is the logical not operator.
STACKEFFECT: n1 n2 --- n3
DESCRIPTION:
Leave the bit-wise logical or of two 16-bit values.
STACKEFFECT: u1 u2 --- ff
DESCRIPTION:
Leave a true flag if u1 is less than u2 ; otherwise leave a false flag.(Interpreted as unsigned numbers).
STACKEFFECT: nl n2 --- n3
DESCRIPTION:
Leave the bitwise logical exclusive or of two 16-bit values.
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 16 bits of n at addr .
SEE ALSO: MEMORY @ C! 2! L! P! PC!
STACKEFFECT: n addr ---
DESCRIPTION:
Add n to the value addr.
STACKEFFECT: addr--- x1 x2
DESCRIPTION:
Store a pair of 16 bits values x1 x2 to consecutive cells at addr . x2 is stored at the lowest address.
STACKEFFECT: addr--- x1 x2
DESCRIPTION:
Leave a pair of 16 bits values x1 x2 from consequitive cells at addr . x2 is fetched from the lowest address.
STACKEFFECT: addr --- n
DESCRIPTION:
Leave the 16 bit contents n of addr .
SEE ALSO: MEMORY ! C@ 2@ P@ PC@ L@
STACKEFFECT: addr1 --- addr2
DESCRIPTION:
Make sure that addr1 is aligned by advancing it if necessary to addr2. In this ciforth this is a NOOP.
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. In this ciforth this is a NOOP.
STACKEFFECT: addr count ---
DESCRIPTION:
This is shorthand for ``BL FILL''.
SEE ALSO: MEMORY
STACKEFFECT: ---- addr
DESCRIPTION:
A constant leaving the address of the lowest memory in use by Forth.
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.
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.
STACKEFFECT: n1 --- n2
DESCRIPTION:
Advance the memory pointer n1 by one (in this case 16 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.
SEE ALSO: MEMORY
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.
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.
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.
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.
SEE ALSO: MEMORY
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.
SEE ALSO: MEMORY
STACKEFFECT: ---- addr
DESCRIPTION:
A constant leaving the address just above the highest memory in use by Forth.
STACKEFFECT: addr n ---
DESCRIPTION:
This is shorthand for 0 FILL.
STACKEFFECT: faraddr1 faraddr2 count ---
DESCRIPTION:
Move count bytes beginning at faraddr1 to faraddr2. Segments that are zero are replaced by defaults: data segment descriptor for source, extra segment descriptor 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.
STACKEFFECT: addr u b ---
DESCRIPTION:
If u is not zero, store b in each of u consecutive bytes of memory beginning at addr .
STACKEFFECT: n faraddr ---
DESCRIPTION:
Store 16 bits of n at segment address pair faraddr.
STACKEFFECT: faraddr --- n
DESCRIPTION:
Leave the 16 bit contents of segment address pair faraddr.
STACKEFFECT: ---- addr
DESCRIPTION:
A user variable leaving the lowest address that is free in the lowest 1 Mbyte of physical memory. This variable can be swapped with DP to compile into this area. This takes care to skip those areas below 1M that are used, for GDT, real time stack and such.
STACKEFFECT: ---- addr
DESCRIPTION:
A user variable leaving the address just above the highest memory usable in the lowest 1 Mbyte of physical memory. This area can be used to compile buffers into that must be accessed from real mode.
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.
SEE ALSO: MEMORY
STACKEFFECT: n port ---
DESCRIPTION:
Store the 16 bit data n to the port address port. In practice on a IBM PC architecture a port address is 10 bits.
STACKEFFECT: port --- n
DESCRIPTION:
Fetch the 16 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.
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.
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.
STACKEFFECT: addr b ---
DESCRIPTION:
Complement the contents of addr by the bit pattern b .
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<
OVERVIEW:
The wordset MISC contains words that defy categorisation.
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.
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.)
STACKEFFECT:
DESCRIPTION:
Do nothing. Primarily useful as a placeholder.
SEE ALSO: MISC
STACKEFFECT:
DESCRIPTION:
A no-operation word which marks the boundary between the forth system and applications.
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.
STACKEFFECT: --- x
DESCRIPTION:
Leave an undefined value x. Presumably it is to be dropped at some time, or it is a place holder.
SEE ALSO: MISC
OVERVIEW:
The 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. . 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.
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.
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.
SEE ALSO: MULTIPLYING */MOD /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.
SEE ALSO: MULTIPLYING SM/REM M/MOD / 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 .
SEE ALSO: MULTIPLYING M/MOD SM/REM *
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.
SEE ALSO: MULTIPLYING UM/MOD SM/REM M*
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.
SEE ALSO: MULTIPLYING M/MOD / M*
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 .
SEE ALSO: MULTIPLYING UM/MOD M* *
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 .
SEE ALSO: MULTIPLYING UM* SM/REM /
OVERVIEW:
The wordset OPERATINGSYSTEM contains words that call the underlying operating system or functions available in the BIOS-rom.
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 contains the real segment descriptor of the ``environment-block''_HOSTED_DPMI_({,which is real hard to come by in protected mode}). _VERBOSE_({{The arguments passed to the program, ``command tail'' is available as a }forthdefi({brain damaged string}){ at address 0x80.}})
SEE ALSO: OPERATINGSYSTEM SYSTEM
STACKEFFECT: d c b a ---ar fl
DESCRIPTION:
Do a call of ``BDOS'' interrupt (0x21) with d c b a in registers DX CX BX AX . Return as a result the content of register AX into ar. fl contains the flag register. If the carry flag is set, it is presumably a failed operation. For other conventions you have to resort to BIOSO . So 0 indicates no error, 1 indicates an error, probably with more information present in ar . This draws upon all facilities made available by MSDOS. This is intended to replace the obsolescent BDOSO , that has the parameters backwards, and returns too many useless parameters.
SEE ALSO: OPERATINGSYSTEM BIOSN BDOSO
STACKEFFECT: a b c d---ar br cr dr fl
DESCRIPTION:
Do a call of ``BDOS'' interrupt (0x21) with a b c d in registers AX BX CX DX. Upon return those registers contains ar br cr dr and fl is the content of the processors flag register. This draws upon all facilities made available by MSDOS. This is obsolescent, use BDOSN .
SEE ALSO: OPERATINGSYSTEM BIOSO BDOSN
STACKEFFECT: d c b a i---ar fl
DESCRIPTION:
Do a call of ``BIOS'' interrupt i with a b c d in registers AX BX CX DX. Return as a result the content of register AX into ar. fl contains the flag register. If the carry flag is set, it is presumably a failed operation. For other conventions you have to resort to BIOSO . In general ar then contains some error code.
SEE ALSO: OPERATINGSYSTEM BDOSN
STACKEFFECT: a b c d i---ar br cr dr fl
DESCRIPTION:
Do a call of ``BIOS'' interrupt i with a b c d in registers AX BX CX DX. Upon return those registers contain ar br cr dr and fl is the content of the processors flag register. 1 AND leaves a zero if the call was successful.
SEE ALSO: OPERATINGSYSTEM BDOSO
STACKEFFECT: ---
DESCRIPTION:
Return to the host environment MSDOS , OS/2, Windows.
SEE ALSO: OPERATINGSYSTEM COLD 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. MSDOS allows only single byte return codes.
SEE ALSO: OPERATINGSYSTEM BYE
STACKEFFECT: n ---
DESCRIPTION:
Wait for n milliseconds.
SEE ALSO: OPERATINGSYSTEM KEY? MS@
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 30 characters long. The default name is C:\COMMAND.COM . 256 bytes after SHELL) are reserved for a start up stack.
SEE ALSO: OPERATINGSYSTEM SYSTEM
STACKEFFECT: sc ---
DESCRIPTION:
Have the operating system execute the command contained in the string sc. The environment is passed to the command, but not the changes made after ciforth started.
SEE ALSO: OPERATINGSYSTEM BLOCK ?ERROR ?ERRUR
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 .
SEE ALSO: OPERATINGSYSTEM OPEN-FILE BIOSN BDOSN
STACKEFFECT: --- n
DESCRIPTION:
Return a counter that is increase by 1 for each millisecond. On this ciforth it wraps after 100 seconds, and has a resolution on 10 mS.
SEE ALSO: OPERATINGSYSTEM MS
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). Having a mere 30000 for the number range can easily lead to overflow in intermediate results during scaling: a multiplication followed by a division. For example : ADD10% 110 * 100 / _C. There are special operators to get around that. See also MULTIPLYING.
STACKEFFECT: n1 n2 --- n3
DESCRIPTION:
Leave the signed product n3 of two signed numbers n1 and n2 .
STACKEFFECT: n1 n2 --- sum
DESCRIPTION:
Leave the sum of n1 and n2 .
STACKEFFECT: n1 n2 --- diff
DESCRIPTION:
Leave the difference of n1 and n2 .
SEE ALSO: OPERATOR NEGATE + * / 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).
SEE ALSO: OPERATOR */MOD */ SM/REM
STACKEFFECT: n1 n2 --- quot
DESCRIPTION:
Leave the signed quotient of n1 and n2 . (using symmetric division).
SEE ALSO: OPERATOR + - * MOD */MOD
STACKEFFECT: n --- u
DESCRIPTION:
Leave the absolute value of n as u .
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}}}}.
STACKEFFECT: n1 n2 --- max
DESCRIPTION:
Leave the greater of two numbers.
STACKEFFECT: n1 n2 --- min
DESCRIPTION:
Leave the smaller of two numbers.
STACKEFFECT: n1 n2 --- mod
DESCRIPTION:
Leave the remainder of n1 divided by n2 , with the same sign as n1 (i.e. symmetric division).
SEE ALSO: OPERATOR + - * / MOD */MOD
STACKEFFECT: n1 --- n2
DESCRIPTION:
Leave the two's complement of a number, i.e. n2 is -n1
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}}}}.
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.
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.
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. )
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.
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.
STACKEFFECT: n ---
DESCRIPTION:
Print the number n1 observing the current BASE, followed by a blank.
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.
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.
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.
STACKEFFECT: d ---
DESCRIPTION:
Print the signed double number d, observing the current BASE, followed by a blank.
SEE ALSO: OUTPUT OUT . D.R (D.R)
STACKEFFECT: c ---
DESCRIPTION:
Transmit ASCII character c to the output device. OUT is incremented for each character output and reset by a LF. .
STACKEFFECT: addr count ---
DESCRIPTION:
This behaves identical to TYPE . However it is used for all error message, so via this word error output can be redirected, by revectoring it.
SEE ALSO: OUTPUT
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.
STACKEFFECT: n ---
DESCRIPTION:
If n is greater or equal to zero, display as much spaces.
STACKEFFECT:
DESCRIPTION:
Transmit an ASCII blank to the output device.
STACKEFFECT: addr count ---
DESCRIPTION:
Transmit count characters from addr to the output device. All terminal I/O goes through this word, so terminal I/O can be redirected, by revectoring it. In this ciforth the string must not contain embedded LF's. OUT is incremented for each character output.
STACKEFFECT: u ---
DESCRIPTION:
Print the unsigned number u observing the current BASE, followed by a blank.
SEE ALSO: OUTPUT OUT . .R D.R D. (D.R)
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.
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.
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.
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.}}
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.
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.
SEE ALSO: PARSING Prefix_& [CHAR] '
STACKEFFECT: sc --- ??
DESCRIPTION:
Interpret the content of sc. Afterwards return to the current input source .
SEE ALSO: PARSING LOAD INCLUDE SET-SRC
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. )
SEE ALSO: PARSING WORD NUMBER BLK DPL
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.
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.
SEE ALSO: PARSING EVALUATE INTERPRET
STACKEFFECT: --- addr n1
DESCRIPTION:
Return the address and length of the current input source .
SEE ALSO: PARSING SRC SOURCE-ID
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 .
SEE ALSO: PARSING BLK SOURCE-ID
STACKEFFECT: --- addr
DESCRIPTION:
A user variable containing the compilation state. A non-zero value indicates compilation.
SEE ALSO: PARSING
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.
SEE ALSO: PARSING (WORD) (PARSE) BLK IN
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.
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 ]
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.
STACKEFFECT:
DESCRIPTION:
Resume compilation, to the completion of a colon-definition.
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.
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).
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.
SEE ALSO: SCREEN LOCK CATCH LOAD
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.
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.
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.
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.
SEE ALSO: SCREEN BLOCK #BUFF THRU QUIT EXIT --> LIST
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.
SEE ALSO: SCREEN BLOCK UNLOCK #BUFF
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.
SEE ALSO: SCREEN
STACKEFFECT: --- addr
DESCRIPTION:
A user variable containing the screen number most recently reference by LIST .
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.
SEE ALSO: SCREEN #BUFF BLOCK LOAD QUIT EXIT -->
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.
SEE ALSO: SCREEN MESSAGE ERRSCR
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.
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.
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.
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.
STACKEFFECT:
DESCRIPTION:
Save the stack position in CSP. Used as part of the compiler security.
SEE ALSO: SECURITY
STACKEFFECT:
DESCRIPTION:
Issue error message if not compiling.
STACKEFFECT:
DESCRIPTION:
Issue error message if stack position differs from value saved in CSP .
SEE ALSO: SECURITY
STACKEFFECT:
DESCRIPTION:
Parse a character and issue error message if it is not a blank delimiter.
SEE ALSO: SECURITY
STACKEFFECT:
DESCRIPTION:
Issue an error message if not executing.
STACKEFFECT:
DESCRIPTION:
Issue an error message if not loading
STACKEFFECT: n1 n2 ---
DESCRIPTION:
Issue an error message if n1 does not equal n2 . The message indicates that compiled conditionals do not match.
STACKEFFECT:
DESCRIPTION:
Issue an error message if the stack is out of bounds.
STACKEFFECT: ---- addr
DESCRIPTION:
A user variable temporarily storing the stack pointer position, for compilation error checking.
SEE ALSO: SECURITY
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.
STACKEFFECT: from to ---
DESCRIPTION:
Print the stack, in the current base.
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.
STACKEFFECT: --- n1
DESCRIPTION:
Leave into n1 the number of items on the data stack, before n1 was pushed.
STACKEFFECT: addr ---
DESCRIPTION:
Initialize the data stack pointer with addr .
STACKEFFECT: --- addr
DESCRIPTION:
Return the address addr of the data stack position, as it was before DSP@ was executed.
STACKEFFECT: --- addr
DESCRIPTION:
A user variable containing the initial location of the return stack.
STACKEFFECT: --- n
DESCRIPTION:
Remove the top value from the return stack and leave it on the data stack .
STACKEFFECT: --- n
DESCRIPTION:
Copy the top of the return stack to the data stack.
STACKEFFECT: ---
DESCRIPTION:
Remove the top value from the return stack.
STACKEFFECT: addr ---
DESCRIPTION:
Initialize the return stack pointer with addr.
STACKEFFECT: --- addr
DESCRIPTION:
Return the address addr of the current return stack position, i.e. pointing the current topmost value.
STACKEFFECT: --- addr
DESCRIPTION:
A user variable that contains the initial value for the data stack pointer.
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).
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?)
STACKEFFECT: sc addr ---
DESCRIPTION:
Store a string constant sc in the string variable at address addr.
STACKEFFECT: sc addr ---
DESCRIPTION:
Append a string constant sc to the string variable at address addr.
STACKEFFECT: sc --- addr
DESCRIPTION:
Allocate and store a string constant sc in the dictionary and leave its address addr.
STACKEFFECT: addr --- sc
DESCRIPTION:
From address addr fetch a string constant sc .
SEE ALSO: STRING $@ $! $+! $C+
STACKEFFECT: c addr ---
DESCRIPTION:
Append a char c to the string variable at address addr.
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.
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 .
STACKEFFECT: sc1 --- sc2
DESCRIPTION:
Trim the string constant sc1 so as not to contain trailing blank space and leave it as sc2 .
STACKEFFECT: --- c
DESCRIPTION:
A constant that leaves the ASCII value for "blank".
SEE ALSO: STRING
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 .
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.
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.
STACKEFFECT: --- 0
DESCRIPTION:
Leave the number 0.
SEE ALSO: SUPERFLUOUS CONSTANT
STACKEFFECT: n1 --- n2
DESCRIPTION:
This is shorthand for ``1 +''.
SEE ALSO: SUPERFLUOUS CELL+ 1-
STACKEFFECT: n1 --- n2
DESCRIPTION:
This is shorthand for 1 -.
SEE ALSO: SUPERFLUOUS 1+
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.
SEE ALSO: SUPERFLUOUS 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.
SEE ALSO: SUPERFLUOUS 2*
STACKEFFECT: --- 1
DESCRIPTION:
Leave the number 1.
SEE ALSO: SUPERFLUOUS CONSTANT
STACKEFFECT: --- 2
DESCRIPTION:
Leave the number 2.
SEE ALSO: SUPERFLUOUS CONSTANT
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.
STACKEFFECT:
DESCRIPTION:
Duplicate the topmost WID in the search order stack. If there were already 8 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.
SEE ALSO: WORDLISTS CONTEXT VOCABULARY
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'' .
SEE ALSO: WORDLISTS VOCABULARY LOAD
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 8 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+8 and up.
SEE ALSO: WORDLISTS PRESENT VOCABULARY CURRENT USER
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.
SEE ALSO: WORDLISTS VOCABULARY CONTEXT
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 .
SEE ALSO: WORDLISTS CONTEXT VOCABULARY
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.
SEE ALSO: WORDLISTS VOCABULARY
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.
SEE ALSO: WORDLISTS CONTEXT VOCABULARY
STACKEFFECT: --- addr
DESCRIPTION:
Leave the dictionary entry address addr of the topmost word in the CURRENT word list.
SEE ALSO: WORDLISTS VOCABULARY
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.
STACKEFFECT:
DESCRIPTION:
Pop the topmost WID from the search order stack. If empty still the ONLY search order is left.
SEE ALSO: WORDLISTS CONTEXT VOCABULARY
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.
SEE ALSO: WORDLISTS~ VOCABULARY