Here you can select the glossary entry of a word. All words in the basic set are documented. The following line should wrap in the W's for optimal readability. Smaller may work. H is too hard. In the O is a nono.
1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 W W W W W W W W W H H H H H H H H H O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O O
!CSP ! #> #BUFF #S # $!-BD $! $+! $, $/ $@ $C+ $^ <# <> < ' (+LOOP) (;) (;CODE) (>IN) (?DO) (ABORT") (ACCEPT) (BACK (BLK) (BUFFER) (CREATE) (D.R) (DO) (FIND) (FORWARD (LINE) (LOOP) (NUMBER) */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 >LFA >NFA >NUMBER >PHA >R >SFA >VFA >WID >XFA > ?BLANK ?COMP ?CSP ?DELIM ?DISK-ERROR ?DO ?DUP ?ERROR ?ERRUR ?EXEC ?LOADING ?PAIRS ?STACK ? @ ABORT" ABORT ABS ACCEPT AGAIN ALIGNED ALIGN ALLOT ALSO AND ARGS ASSEMBLER B/BUF BACK) BASE BEGIN BLANK BLK BLOCK-EXIT BLOCK-FILE BLOCK-HANDLE BLOCK-INIT BLOCK-READ BLOCK-SEEK BLOCK-WRITE BLOCK BL BM BODY> BRANCH BYE C! C, C/L C@ CATCH CELL+ CELLS CHAR+ CHARS CHAR CLOSE-FILE CLS CMOVE COLD CONSTANT CONTEXT CORA CORE COUNT CO CPU CREATE-FILE CREATE CR CSP CURRENT D+ D.R D. DABS 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 FAR! FAR@ FARMOVE FENCE FILL FIND FLD FLUSH FM/MOD FOR-VOCS FOR-WORDS FORGET-VOC FORGET FORTH FORWARD) FOUND GET-FILE HANDLER HEADER HERE HEX HIDDEN HLD HOLD ID. IF IMMEDIATE INCLUDED INDEX INIT INTERPRET INVERT I J KEY? KEY LATEST LEAVE LINK LIST LITERAL LIT LOAD LOCK LOOP LSHIFT L_>IN M* M/MOD MAX MESSAGE MIN MOD MOVE MS NAMESPACE NAME NAME NEGATE NIP NOOP NUMBER Number_1 Number_2 OFFSET OK ONLY OPEN-FILE OPTIONS OPT OR OUT OVER PAD PARSE PC! PC@ POSTPONE PP@@ PP PREFIX PRESENT PREVIOUS PUT-FILE PW! PW@ Prefix_" Prefix_& Prefix_+ Prefix_- Prefix_0 Prefix_7 Prefix_B Prefix_TICK Prefix_^ QUIT R# R0 R> R@ RDROP READ-FILE RECURSE REFILL-TIB REMAINDER REPEAT REPOSITION-FILE RESTORE-INPUT RESTORE ROT RSHIFT RSP! RSP@ RUBOUT RW-BUFFER S" S0 S>D SAVE-INPUT SAVE SCR SDLITERAL SET-SRC SET-TERM SHELL SIGN SKIP SM/REM SOURCE SPACES SPACE SRC STATE SUPPLIER SWAP SYSTEM TASK-SIZE TASK TERMIO THEN THROW THRU TIB TOGGLE TRIAD TYPE U< U. U0 UM* UM/MOD UNLOCK UNLOOP UNTIL UPDATE USER VARIABLE VERSION VOC-LINK WARM WARNING WHERE WHILE WITHIN WORDS WORD WRITE-FILE XOR XOS5 XOS ZEN ['] [CHAR] [COMPILE] [ \ ] _FIRST _LIMIT _PREV _left_parenthesis_ _ ~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 INITIALISATIONS INPUT JUGGLING LIBRARY 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:
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: BLOCKS LOCK CATCH LOAD
STACKEFFECT: n---
DESCRIPTION:
Interpret n as the status of a disk i/o call and signal an error if it contains an error condition. It is only used to signal errors related to accessing the BLOCK-FILE.
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 . All blocks are unlocked. Any changed blocks are written back to mass storage. 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 252 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 signals failure by a negative handle in BLOCK-HANDLE. You must activate mnemonic error messages explicitly by setting WARNING.
SEE ALSO: BLOCKS BLOCK LIST LOAD BLOCK-EXIT OPEN-FILE
STACKEFFECT: addr blk ---
DESCRIPTION:
The ciforth primitive for reading of blocks. addr specifies the destination block buffer, blk is the sequential number of the referenced physical block BLOCK-READ determines the location on mass storage, performs the read and throws an exception on errors.
SEE ALSO: BLOCKS BLOCK DISK-ERROR BLOCK-WRITE
STACKEFFECT: addr blk ---
DESCRIPTION:
The ciforth primitive for writing of blocks. addr specifies the source or destination block buffer, blk is the sequential number of the referenced physical block. BLOCK-WRITE determines the location on mass storage, performs the write and throws an exception on errors.
SEE ALSO: BLOCKS BLOCK DISK-ERROR BLOCK-READ
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) BLOCK-READ BLOCK-WRITE OFFSET UPDATE FLUSH LOAD
STACKEFFECT: --- addr
DESCRIPTION:
This variable is not used in thisforth, errors are thrown..
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:
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.
SEE ALSO: BLOCKS BLOCK EMPTY-BUFFERS
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, some non-locked buffer is freed. The contents of that buffer is written to the disc, if it was marked as updated. In ciforth this 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 this ciforth. If all buffers were locked, (BUFFER) throws exception 48.
SEE ALSO: BLOCKS~ BLOCK _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 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:
DESCRIPTION:
Make sure that the content of all UPDATE d block buffers has been transferred to disk. The buffers are no longer associated with a block and their content is no longer available. In ciforth no transfer takes place, because mass storage is updated automatically in the background.
SEE ALSO: BLOCKS~ EMPTY-BUFFERS BLOCK SCREEN
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 read or writing blocks.
SEE ALSO: BLOCKS~ BLOCK MESSAGE BLOCK-READ BLOCK-WRITE
STACKEFFECT: --- addr1
DESCRIPTION:
A constant that leaves the address of the first (lowest) block buffer.
SEE ALSO: BLOCKS~ BLOCK _LIMIT
STACKEFFECT: ---- addr1
DESCRIPTION:
A constant leaving the address just above the highest memory available for a disc buffer. Actually this is the highest system memory.
SEE ALSO: BLOCKS~ BLOCK _FIRST
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.
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 32 bit literal. The intended use is: : xxx [ calculate ] LITERAL ; Compilation is suspended for the compile time calculation of a value. Compilation is resumed and LITERAL compiles this value. Later execution of the definition containing the literal will push it to the stack. If executing in ciforth, the number will just remain on the stack.
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 the form:
: xxx ... [COMPILE] IF ... ;
[COMPILE] will force the compilation of an immediate definition, that would otherwise execute during compilation. The above example will perform IF when xxx executes, rather than introducing conditional code in xxx itself.
STACKEFFECT: --- n
DESCRIPTION:
Within a colon-definition, LIT is compiled followed by a 32 bit literal number given during compilation. Later execution of LIT causes the contents of this next dictionary cell to be pushed to the stack.
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 is less or equal to n2 the loop body is not executed. This is intended to suppress the unwanted behaviour of looping through the whole number range. ciforth deviates from ISO in that it also suppresses the unwanted behaviour of looping through almost the whole number range for an input of e.g.
1 2
.
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 to the caller, suspending interpretation of the current definition, such that when the caller exits, this definition is resumed. The return stack must not be engaged, such as between >R and R> , or DO and LOOP .
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:
Terminate a do-loop by branching to directly behind the end of a loop started by DO or ?DO , so after the corresponding LOOP or +LOOP .
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, then align. 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:
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 .
SEE ALSO: CONTROL~ BRANCH FORWARD BACK)
STACKEFFECT: addr ---
DESCRIPTION:
Complete a backward branch by compiling an offset from HERE to addr, left there by {{{(BACK}}} . Usage is (BACK .. POSTPONE BRANCH BACK)
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 .
SEE ALSO: CONTROL~ 0BRANCH FORWARD BACK)
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.
STACKEFFECT:
DESCRIPTION:
Terminate a colon-definition and stop further compilation. Compiles the run-time (;) .
STACKEFFECT: n ---
DESCRIPTION:
A defining word used in the form: n CONSTANT cccc to create word cccc , where the content of its data field address is n . When cccc is later executed, it will push the value of n to the stack.
SEE ALSO: DEFINING VARIABLE >DFA
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 >BODY DOES> ;CODE ALLOT ,
STACKEFFECT:
DESCRIPTION:
A word which is used in combination with CREATE to specify the run-time action within a high-level defining word. DOES> modifies the default behaviour of the created word so as to execute the sequence of compiled word addresses following DOES> . When the DOES> part executes it begins with the address of the data field of the word on the stack. This allows interpretation using this area or its contents. Typical uses include the Forth assembler, arrays and matrices, and compiler generation.
SEE ALSO: DEFINING
STACKEFFECT:
DESCRIPTION:
A defining word used in the form: NAMESPACE cccc to create a namespace definition cccc . It will create a word listin the ISO sense. Subsequent use of cccc will push this word list (the word list associated with cccc) to the top of the search order in CONTEXT. So it will be searched first by INTERPRET . A namespace 's data content field contains at first the dovoc pointer (like for any DOES> word) , then follows its body. The body contains the namespace ("vocabulary") link field address ( VLFA ). The VLFA points to the VLFA of the next namespace or a nil pointer for the end. Then follows a 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 namespace or a nil pointer if empty. Executing the namespace means pushing its WID on top of the CONTEXT order. In ciforth when there can be at most 16 word list 's in the search order, the oldest one gets lost. The vocabularies generated are IMMEDIATE words.
SEE ALSO: DEFINING VOC-LINK DEFINITIONS FOR-VOCS >WID
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 cell 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 this ciforth forthsamp({UP}) is coupled to the return stack. This means that with a switch of the return stack{,} forthsamp({UP}) is switched also automatically. CONTEXT is the last user variable at offset 37 , such that new user variables may be allocated using offsets of 37+16 and up.
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 whose data field address contains a pointer n to a data location. When cccc is later executed, this pointer n is left on the stack, so that a fetch or store may access this location.
SEE ALSO: DEFINING USER CONSTANT >DFA
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.
STACKEFFECT: sc ---
DESCRIPTION:
This is the basis for all defining words, including those which lack a data field in the ISO sense: : USER VARIABLE NAMESPACE CONSTANT. It creates a header with name sc in the dictionary and links it into the CURRENT word list.
SEE ALSO: DEFINING~ HEADER LINK CREATE
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) (CREATE)
STACKEFFECT: sc --- dea
DESCRIPTION:
Create a dictionary entry structure for the word sc and returns its address into dea. A pointer to each of its fields is called a "field address". In particular note that a data field address is not a data field' in the ISO sense. The code field addres and data field address addres contain a same pointer, to the area owned by this header, i.e. immediately following the completed header as appropriate for a low level (assembler) definition. The flag and link fields are initialised to zero , so not HIDDEN. The name sc is layed down in the dictionary before the header and filled in into the name field. The source field is filled in to best knowledge.
SEE ALSO: DEFINING~ (CREATE) LINK >CFA >DFA >FFA >LFA >NFA >SFA >XFA
STACKEFFECT: dea wid ---
DESCRIPTION:
Links the Forth word represented by dea into the wordlist represented by wid as the latest entry. Alternatively, consider wid as an other dea2. Link dea between the dea2 and its successor in the linked list.
SEE ALSO: DEFINING~ HEADER (CREATE)
OVERVIEW:
The wordset DENOTATIONS contains prefixes (mostly one letter words) that introduce a denotation, i.e. a generalisation of NUMBER . PREFIX turns the latest definition into a prefix, similar to IMMEDIATE. If a word starting with the prefix is looked up in the dictionary, the prefix is found and executed. Prefix words parse input and leave a constant (number, char or string) on the stack, or compile such constant, depending on STATE. For a kernel system it is guaranteed that they reside in the minimum search order wordlist, associated with the namespace ONLY. To make a distinction with the same words in other wordlists, the names of denotations are prepended with ``Prefix_'' in the documentation. Actual names consists of the one character following ``Prefix''. Apart from Prefix_0 , ONLY contains entries for all hex digits 1...9 and A...F. Like NUMBER always did, all denotations behave identical in interpret and compile mode and they are not supposed to be postponed.
STACKEFFECT: --- sc
DESCRIPTION:
Parse a " delimited string and leave it on the stack. A " can be embedded in a string by doubling it. The string is permanent and takes dictionary space. 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: --- 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 ' by a space, the ISO-conforming version of ' is found.
SEE ALSO: DENOTATIONS HEADER CONTEXT ['] PRESENT >CFA >DFA >FFA >LFA >NFA
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 &
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 HERE ,
STACKEFFECT: addr --- dea
DESCRIPTION:
Convert the data field addr of a definition created with a CREATE / DOES> construct (this is not a header data field address) 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. In ciforth the alternative FOUND is used, that uses a regular string.
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) PREFIX FIND
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 special compiling situations, rather than build them into the fundamental compiler. The user may force compilation of an immediate definition by preceding it with POSTPONE .
SEE ALSO: DICTIONARY
STACKEFFECT: --- addr
DESCRIPTION:
Leave the address of the text output buffer, which is a fixed offset above HERE. The area growing downward from PAD is used for numeric conversion.
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 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 PP@@ IMMEDIATE Prefix_0
STACKEFFECT: sc --- dea
DESCRIPTION:
If the string sc is present as a word name in the current search order, return its dea, else leave a nil pointer. For a denotation word, the name must match sc exactly.
SEE ALSO: DICTIONARY FOUND CONTEXT (FIND) NAMESPACE FIND
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 NAME and FOUND (or 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 namespace, fetched from CURRENT or an other wid in the search order . Leave the dictionary entry address dea of the first entry found, else leave a zero. Do not consume the string sc, as this is a repetitive action.
SEE ALSO: DICTIONARY~ ~MATCH FOUND 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~ Prefix_' HEADER
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~ Prefix_' >BODY HEADER
STACKEFFECT: dea --- addr
DESCRIPTION:
Given a dictionary entry addres return its flag field address addr .
SEE ALSO: DICTIONARY~ Prefix_' HEADER IMMEDIATE PREFIX
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~ Prefix_' HEADER
STACKEFFECT: dea --- nfa
DESCRIPTION:
Given a dictionary entry addres return the name field address.
SEE ALSO: DICTIONARY~ Prefix_' HEADER ID.
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~ Prefix_' HEADER >BODY
STACKEFFECT: dea --- addr
DESCRIPTION:
Given a dictionary entry addres return the source field address addr .
SEE ALSO: DICTIONARY~ Prefix_' HEADER
STACKEFFECT: dea --- cfa
DESCRIPTION:
Given the dictionary entry addres of a namespace return the address of the link to the next namespace. Traditionally this was called vocabulary, hence the V.
SEE ALSO: DICTIONARY~ NAMESPACE >CFA >WID
STACKEFFECT: dea --- wid
DESCRIPTION:
Given the dictionary entry addres dea of a namespace return its WID wid, a dummy DEA that serves as the start of a dictionary search.
SEE ALSO: DICTIONARY~ NAMESPACE >VFA (FIND)
STACKEFFECT: dea --- addr
DESCRIPTION:
Given a dictionary entry addres return the extra field address addr .
SEE ALSO: DICTIONARY~ Prefix_' HEADER
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 (which mostly means later defined) than addr from a wordlist given by wid . This works too if links have been redirected, such that some earlier words point back to later defined words. Leave addr (as FORGET-VOC is intended to be used with FOR-VOCS) . If any whole namespace is removed, the search order is reset to ONLY FORTH. The space freed is not recovered.
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 dea1
DESCRIPTION:
This is a vector in behalf of optimisation, that starts as a noop, and can be filled in if the extra field is used for optimisation. It must adhere to the following specification: Search down from the DEA dea for a word with name sc. Replace dea with dea1 if the dictionary part between both could not contain the name searched for. dea1 being a null pointer means that the dictionary doesn't contain the name.
SEE ALSO: DICTIONARY~ ~MATCH FIND >XFA
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~ FOUND CORA
OVERVIEW:
The wordset DOUBLE contains words that manipulate double's. In this 32 Forth you would hardly need doubles if it weren't for the NUMBER formatting wordset that uses them exclusively.
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 namespace 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 namespace and i*x is what is left by the word if executed.
SEE ALSO: ENVIRONMENTS NAMESPACE
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 signaled by the kernel go through this word.
SEE ALSO: ERRORS ERROR ?ERRUR THROW
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, clamped to the range [-256, 63]. This word is executed by THROW before restarting the interpreter and can be revectored to give more elaborate diagnostics.
SEE ALSO: ERRORS MESSAGE ?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 infeasible.
STACKEFFECT: n ---
DESCRIPTION:
MESSAGE is generally used to print error and warning messages. If WARNING is zero (disc unavailable), this is a noop. Print on the standard error channel the text of line n relative to screen ERRSCR . n may be positive or negative and beyond just screen ERRSCR. A certain range around 0 is reserved. The messages with small positive offset contain ciforth error messages. The messages with small negative offset contain the strings belonging to the return values for Linux system calls . 0 MESSAGE will print version information about the library file where the messages sit in.
SEE ALSO: ERRORS ERROR BLOCK-FILE
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 assumed to be open, and messages are fetched from it. If it is 0, error messages will be presented by number only.
SEE ALSO: ERRORS MESSAGE ERROR ERRSCR
STACKEFFECT: --- addr
DESCRIPTION:
A user variable pair which contains the start of the source and the position after the last character parsed when an error thrown by ?ERROR ,so not of exceptions thrown. The contents of WHERE is interpreted by ERROR if the corresponding exception was never caught.
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 Linux error code negated, usable as a throw code.
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 file access privileges u If the file already exists, it is truncated to zero length. Return a file handle into fileid and a result code into ior. The latter is the errno negated, to be inspected using MESSAGE . The handle is open for READ_WRITE.
SEE ALSO: FILES OPEN-FILE READ-FILE WRITE-FILE DELETE-FILE
STACKEFFECT: sc --- ior
DESCRIPTION:
Delete the file with name sc. Return a result code into ior. The latter is the errno negated, to be inspected using MESSAGE .
SEE ALSO: FILES OPEN-FILE READ-FILE WRITE-FILE CREATE-FILE
STACKEFFECT: sc1 --- sc2
DESCRIPTION:
Get the content of the file with name sc1; leave it as a string sc2. Any errors are thrown. The file is permanently stored at HERE .
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. The file is permanently stored in the dictionary.
STACKEFFECT: sc fam --- fileid ior
DESCRIPTION:
Open the file with name sc and file access method fam. Return a file handle into fileid and a result code into ior. The latter is the errno error code negated, usable as a throw code. fam is one of 0=READ_ONLY, 1=WRITE_ONLY, 2=READ_WRITE.
SEE ALSO: FILES READ-FILE WRITE-FILE CREATE-FILE DELETE-FILE CLOSE-FILE
STACKEFFECT: sc1 sc2 ---
DESCRIPTION:
Save the string constant sc1 to a file with the name sc2. 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 errno error code negated, usable as a throw code.
SEE ALSO: FILES OPEN-FILE WRITE-FILE REPOSITION-FILE BLOCK-READ
STACKEFFECT: ud fd --- ior
DESCRIPTION:
Position the file that is open at fd at position ud. ior is 0 for success, or otherwise errno negated . Information about error codes can be found by MESSAGE.
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 errno error code negated, usable as a throw code.
SEE ALSO: FILES OPEN-FILE READ-FILE REPOSITION-FILE BLOCK-WRITE
STACKEFFECT: --- addr
DESCRIPTION:
A constant that leaves the address of a disk buffer used by file i/o words.
SEE ALSO: FILES~ READ-FILE OPEN-FILE ZEN
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 DPL
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:
Add an ASCII minus-sign - inside a <# and #> construct to the beginning of a converted numeric output string in the text output buffer when n is negative. Must be used between <# and #> .
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 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. During output it is free to use, e.g. 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 (aliased as) single character denotation words, marked as PREFIX IMMEDIATE. Therefore it decrements the parse pointer to include this first character. Starting with this character, it converts characters from the current input source into a number, and compiles or executes this number, depending on STATE. If the string contains a decimal point it is a double else a single integer number. If numeric conversion is not possible, an error message will be given. Any comma's in the number are ignored, to help in structuring large numbers. Traditionally comma's also signified double precision numbers. Revectoring forthcode({NUMBER}) affects all applicable number prefixes. In this way floating point numbers can be accomodated.
SEE ALSO: FORMATTING~ BASE (NUMBER)
OVERVIEW:
The wordset INITIALISATIONS 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. This will affect the initialisation by COLD.
SEE ALSO: INITIALISATIONS USER
STACKEFFECT:
DESCRIPTION:
Restart the interpreter. In addition and before the actions of QUIT, clear also the data stack and reset the exception mechanism. This word is silent. This may be confusing at times, because you can't tell the difference between a word that is still busy or that has aborted.
SEE ALSO: INITIALISATIONS WARM INIT
STACKEFFECT:
DESCRIPTION:
Initialise all user variables to their boot up values values, i.a. the stacks and the dictionary pointer . Initialise the system as per INIT. Handle command line options, if any. Show signon message and 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: INITIALISATIONS WARM INIT OPTIONS
STACKEFFECT:
DESCRIPTION:
Initialise or reinitialise the system. Reset the data stack, the wordlists, the number base and the exception mechanism. Initialise the block mechanism. Any blocks that have not yet been written back to mass storage are discarded. Now open the file that contains the blocks, in read-only mode. After INIT we have the following situation. The search order contains the FORTH words, plus ONLY with i.a. number handling. Definitions are added to the FORTH namespace. The number base is decimal. .
SEE ALSO: INITIALISATIONS WARM COLD FORTH BLOCK-INIT BASE S0
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. It can be revectored to show debugging info or give a prompt.
SEE ALSO: INITIALISATIONS QUIT COLD
STACKEFFECT: ft --- f2
DESCRIPTION:
Handle command line option. If an option is passed during startup execute the screen corresponding to the option letter and return a false flag into f2, otherwise leave a true flag. During startup this flag decides whether the signon message is displayed. An option can always decide to execute .SIGNON. By redefining OPTIONS as DROP 0, the handling of options during cold boot is suppressed, useful for turnkey applications.
SEE ALSO: INITIALISATIONS COLD
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.
SEE ALSO: INITIALISATIONS TIB ABORT
STACKEFFECT:
DESCRIPTION:
Perform a so called "warm" start. Reinitialise the system as per INIT. Show the signon message and restart via ABORT .
SEE ALSO: INITIALISATIONS ABORT
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 any line ending, but the buffer still does and after 1+ the string ends in a LF. The editing functions are the same as with ACCEPT . This is lighter on the system and sometimes easier to use than ACCEPT This input remains valid until the next time that the console buffer is refilled.
SEE ALSO: INPUT KEY KEY? ACCEPT PP@@ REFILL-TIB
STACKEFFECT: addr count --- n
DESCRIPTION:
Transfer at most count characters from the terminal to address, until a RET is received. The simple tty editing functions of Linux are observed, i.e. the ``erase'' (delete a character) and ``kill'' (delete a line) characters. Typically these are the backspace key and ^U. Note that excess characters after count are ignored. The number of characters not including the RET is returned into n.
SEE ALSO: INPUT (ACCEPT) KEY KEY? (ACCEPT)
STACKEFFECT: --- ff
DESCRIPTION:
Return into ff whether a character is available. The next execution of KEY will return the character immediately.
SEE ALSO: INPUT KEY ACCEPT KEY?
STACKEFFECT: --- c
DESCRIPTION:
Leave the ASCII value of the next terminal key struck.
STACKEFFECT: --- addr
DESCRIPTION:
A user variable containing a pointer within the current input text buffer (terminal or disc) from which the next text will be accepted. All parsing words use and move the value of PP . This is different from how ISO >IN works, in the sense that clearing it doesn't reset the parse pointer to the start of the current line.
SEE ALSO: INPUT >IN WORD NAME NUMBER PARSE PP@@
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. Traditionally, this was used for file i/o too, but not so in ciforth.
STACKEFFECT: --- addr
DESCRIPTION:
After forthsample(WANT -legacy-) this is used by the word L_>IN, to store the offset from the start within the current input text buffer (terminal or disc) from which the next text will be accepted, to get a behaviour more in accordance with the standard. 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 NAME . The editing functions are those described by ACCEPT. Immediately, after REFILL-TIB REMAINDER 2@ defines the characters ready in the input buffer. All characters are retained including the RET. If the input is redirected (such that characters after a RET are available) 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
STACKEFFECT: len b ---
DESCRIPTION:
Set the terminal length to len and toggle the c_lflag field with b in the termio structure TERMIO . In particular toggling with 0x0A makes that the terminal doesn't wait for a RET. This word is invalid for pipes, and is replaced by a 2DROP in that case.
STACKEFFECT: --- addr
DESCRIPTION:
Leave the address of the terminal description, this has the layout of a c-structure termio .
OVERVIEW:
The wordset JUGGLING contains words that change order of data on the data stack . The necessity for this arise, because the data you want to feed to a Forth word is not directly accessible, i.e. on top of the stack. It is also possible that you need the same data twice, because you have to feed it to two different words. Design your word such that you need them as little as possible, because they are confusing.
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.
SEE ALSO: JUGGLING DUP SWAP OVER
STACKEFFECT: n --- n n
DESCRIPTION:
Duplicate the value on the stack.
SEE ALSO: JUGGLING OVER SWAP DROP
STACKEFFECT: n1 n2---n2
DESCRIPTION:
Drop the second number from the stack.
SEE ALSO: JUGGLING DUP DROP SWAP OVER
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 words described into library have nothing particular in common, except that they are available in the LAB and not the ciforth kernel. They are either words from the library that are sufficiently useful to merit being described here, or legacy words that were in the kernel in earlier versions. All of them can be loaded from the library by WANT LEGACY_WORD.
STACKEFFECT: --- addr
DESCRIPTION:
Hides and replaces the user variable PP. All parsing words use and move the value of that user variable. 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. The legacy >IN is not actually a variable: its content must be fetched immediately, and changing it has no effect.
OVERVIEW:
The wordset LOGIC contains logic operators and comparison operators. A comparison operator (such as = ) delivers a Forth flag, -1 for true, 0 for false, representing a condition (such as equality of two numbers). The number -1 has all bits set to one. The logical operators ( AND etc.) work on all 32 bits, one by one. In this way they are useful for mask operations, as well as for combining conditions represented as flag's. But beware that IF only cares whether the top of the stack is non-zero, such that - can mean non-equal to IF. Such conditions (often named just flag's) cannot be directly combined using logical operators, but 0= 0= can help.
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. It may be aliased to NOT , which inverts a 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 . For Forth flags (0 or -1) this is the logical and operator.
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 32-bit values. For Forth flags (0 or -1) this is the logical or operator.
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 32-bit values. For Forth flags (0 or -1) this is the logical xor operator.
OVERVIEW:
The wordset MEMORY contains words to fetch and store numbers from doubles, cells or bytes in memory. There are also words to copy blocks of memory or fill them, and words that fetch a cell, operate on it and store it back.
STACKEFFECT: n addr ---
DESCRIPTION:
Store all 32 bits of n at addr .
SEE ALSO: MEMORY @ C! 2! FAR! PW! PC!
STACKEFFECT: n addr ---
DESCRIPTION:
Add n to the value at addr.
STACKEFFECT: x1 x2 addr ---
DESCRIPTION:
Store a pair of 32 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 32 bits values x1 x2 from consecutive cells at addr . x2 is fetched from the lowest address.
STACKEFFECT: addr --- n
DESCRIPTION:
Leave the 32 bit contents n of addr .
SEE ALSO: MEMORY ! C@ 2@ PW@ PC@ FAR@
STACKEFFECT: addr1 --- addr2
DESCRIPTION:
Make sure that addr1 is aligned by advancing it if necessary to addr2.
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.
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 32 bits) cell to n2. This is invaluable for writing portable code. Much of the library code of ciforth runs on both 16 and 32 bits systems, thanks to this.
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 count quantity of characters beginning at address from to address to . The contents of address from is moved first proceeding toward high memory, such that memory propagation occurs. As the Intel 86-family is byte-addressing there are no restrictions in ciforth.
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: n faraddr ---
DESCRIPTION:
Store 32 bits of n at segment address pair faraddr.
STACKEFFECT: faraddr --- n
DESCRIPTION:
Leave the 32 bit contents n of segment address pair faraddr.
STACKEFFECT: faraddr1 faraddr2 count ---
DESCRIPTION:
Move count bytes beginning at faraddr1 to faraddr2. Segments that are zero are replaced by defaults: data segment selector for source, extra segment selector for destination. Copying is done from low to high offset, so there may be memory propagating. This is not easily seen from the selector 's, 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: from to count ---
DESCRIPTION:
Move count bytes beginning at address from to address to, such that the destination area contains what the source area contained, regardless of overlaps. As the Intel 86-family is byte-addressing there are no restrictions.
SEE ALSO: MEMORY
STACKEFFECT: b port ---
DESCRIPTION:
Store a byte b to the port address port. A port address is always 16 bits. In practice on a IBM PC architecture a port address is 10 bits. You can use ports only after asking permission (using e.g. ioperm ) and being super user.
STACKEFFECT: port --- b
DESCRIPTION:
Fetch a byte b from the port address port. A port address is always 16 bits. In practice on a IBM PC architecture a port address is 10 bits. You can use ports only after asking permission (using e.g. ioperm ) and being super user.
SEE ALSO: MEMORY PC! PW@ PW! @
STACKEFFECT: n port ---
DESCRIPTION:
Store the 16-bit data n to the 16-bits port address port. In practice on a IBM PC architecture a port address is 10 bits. You can use ports only after asking permission (using e.g. ioperm ) and being super user.
SEE ALSO: MEMORY PW@ PC! PC@ !
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. You can use ports only after asking permission (using e.g. ioperm ) and being super user.
SEE ALSO: MEMORY PW! PC@ PC! @
STACKEFFECT: ---- n
DESCRIPTION:
A constant leaving the size of the per task areas: data stack size, return stack size, terminal input buffer plus user area. The data stack of the main task runs down to HERE .
SEE ALSO: MEMORY DSP@ RSP@ TIB
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 original 16 bits Forth's have problems with overflow (See also OPERATOR). Operators with intermediate results of double precision, mostly scaling operators, solve this and are present in the MULTIPLYING wordset. In this 32 bit Forth you will have less need, but scaling remains tricky. Formatting is done with double's exclusively, and relies on this wordset. Operators with mixed precision and unsigned operators allow to build arbitrary precision operators from them in high level code.
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 points to an area with the argument count, followed by a null ended array of arguments strings, then by a null ended array of environment strings.
SEE ALSO: OPERATINGSYSTEM SYSTEM
STACKEFFECT: ---
DESCRIPTION:
Return to the host environment Linux.
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. Linux allows only single byte return codes.
SEE ALSO: OPERATINGSYSTEM BYE
STACKEFFECT: n ---
DESCRIPTION:
Wait for n milliseconds.
SEE ALSO: OPERATINGSYSTEM KEY?
STACKEFFECT: ---addr
DESCRIPTION:
Leave the address addr of a counted string, the name of a file that contains the command interpreter, or shell. This name may be changed an is used by the SYSTEM command. The name may contain a path and be at most 252 characters long. The default name is /bin/sh .
SEE ALSO: OPERATINGSYSTEM SYSTEM
STACKEFFECT: sc ---
DESCRIPTION:
Have the operating system execute the command contained in the string sc.
SEE ALSO: OPERATINGSYSTEM BLOCK ?ERROR ?ERRUR
STACKEFFECT: n1 n2 n3 n4 n5 n---ret
DESCRIPTION:
Do a traditional Unix type system call n (man 2) with parameters n1 n2 n3 n4 n5. ret is the return value of the call. If it is negative, it is mostly an error, such as known by errno . This makes available all facilities present in Linux.
SEE ALSO: OPERATINGSYSTEM ?ERRUR
STACKEFFECT: n1 n2 n3 n---ret
DESCRIPTION:
Do a traditional Unix type system call n (man 2) with parameters n1 n2 n3. ret is the return value of the call. If it is negative, it is mostly an error, such as known by errno . This makes available all facilities present in Linux, except those with 4 or 5 parameters that are handled by XOS5 .
SEE ALSO: OPERATINGSYSTEM ?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 XOS XOS5
OVERVIEW:
The wordset OPERATOR contains the familiar operators for addition, multiplication etc. The result of the operation is always an integer number, so division can't be precise. On ciforth all division operations are compatible with symmetric division. The ISO standard require a Forth to choose between floored or symmetric division for its standard operations. Divisions involving negative numbers have an interpretation problem. In any case we want the combination of / and MOD (remainder) to be such that you can get the original n back from the two values left by n m MOD and n m / by performing m * + . This is true for all Forth's. On ciforth the / is a symmetric division, i.e. -n m / give the same result as n m /, but negated. The foregoing rule now has the consequence that m MOD has 2|m|-1 possible outcomes instead of |m| . This is very worrisome for mathematicians, who stick to the rule that m MOD has |m| outcomes: 0 ... |m|-1, or -|m|+1 ... 0 for negative numbers. (floored division).
STACKEFFECT: n1 n2 --- n3
DESCRIPTION:
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. For this ciforth all terminal I/O goes through TYPE. In this ciforth EMIT maintains OUT.
STACKEFFECT: addr count ---
DESCRIPTION:
Transmit count characters from addr to the standard error device. It is high level so error output can be redirected, by revectoring it. Or you may use redirection by Linux. In this ciforth strings may contain embedded LF 's with the effect of a new line at that point in the output.
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. It is high level so terminal I/O can be redirected, by revectoring it and the usual redirection or tee-ing by _OS_. In this ciforth strings may contain embedded LF 's with the effect of a new line at that point in the output, however in that case OUT is not observed.
SEE ALSO: OUTPUT EMIT OUT ETYPE
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 --- 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. It can be either matched exactly, or it can match a prefix. A word that matches a prefix is called a denotation; mostly this is a number. Prefixes are present in ONLY which is the last wordlist in the search order, and the minimum search order. 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: --- 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: 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.
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: 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: PARSING SAVE 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: PARSING SET-SRC RESTORE-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: PARSING SAVE RESTORE-INPUT
STACKEFFECT: ---
DESCRIPTION:
Save the content of SRC on the return stack to prepare for changing the current input source. This must be balanced by a RESTORE in the same definition. CO can be used between the two.
SEE ALSO: PARSING SET-SRC SAVE-INPUT
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 preceeded by a call to forthcode({SAVE}) and followed by a call to INTERPRET.
SEE ALSO: PARSING SRC EVALUATE INTERPRET
STACKEFFECT: --- addr n1
DESCRIPTION:
Return the address and length of the current input source .
STACKEFFECT: addr ---
DESCRIPTION:
Return the address addr of the current input source specification, allocated in the user area. It consists of three cells: the lowest address of the parse area, and the non-inclusive highest address of the parse area and a pointer to the next character to be parsed. Changing SRC takes immediate effect, and must be atomic, by changing only the third cell or by e.g. using SET-SRC. The third cell has the alias IN . Words like >IN BLK SOURCE are secondary, and return their output by ``second-guessing'' SRC .
SEE ALSO: PARSING SAVE RESTORE BLK
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 NAME 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.
STACKEFFECT:
DESCRIPTION:
Used in the form: ( cccc). Ignore a comment that will be delimited by a right parenthesis that must be in the same input source, i.e. on the same line for terminal input, or in the same string, block or file, when that is the input. It is an immediate word. So colon definitions can be commented too. A blank after the word ( is required.
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: --- 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. For stack underflow print nothing.
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: i*x --
DESCRIPTION:
Clear the data stack
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: 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: addr --- sc
DESCRIPTION:
From address addr fetch a string constant sc .
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: 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 addr2 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 NIP. It is not the same as 2 / , nor is it the same as 1 RSHIFT.
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 NAMESPACE and filled by defining words while that namespace is CURRENT . They regulate how words are found; different vocabularies can have words with the same names. A word list in the ISO sense has no name, but a word list identifier or WID, which is inconvenient. We use namespace words created by the defining word NAMESPACE . They are used to manipulate the word list's that are associated with them. So 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 16 WID 's, ciforth looses the last one. This is not counting the ONLY search order. You seldomly want to use this word, because in ciforth by naming a namespace you add it to the order.
SEE ALSO: WORDLISTS CONTEXT NAMESPACE
STACKEFFECT:
DESCRIPTION:
The name of the namespace that contains machine code definitions. In ciforth execution it pushes the associated word list to the top of the CONTEXT stack. (For ISO-compliance it would replace the top.) ASSEMBLER is not immediate. 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 NAMESPACE 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 16 WID 's in this ciforth, while the ISO Search-Order wordset requires a capacity of at least 8.
SEE ALSO: WORDLISTS PRESENT NAMESPACE CURRENT USER
STACKEFFECT: --- addr
DESCRIPTION:
A user variable containing the WID of a namespace to which new words will be added. It is the compilation word list in the sense of the ISO standard. The WID has the structure of a dictionary entry. This allows to link in a new word between the link field of the WID and the next definition.
SEE ALSO: WORDLISTS NAMESPACE 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 namespace 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 NAMESPACE
STACKEFFECT:
DESCRIPTION:
The name of the ENVIRONMENT namespace. The associated word list contains environment queries. The names of words present in ENVIRONMENT are recognized by ENVIRONMENT?. This word list is not intended to be used as a CONTEXT word list; and only as a CURRENT whenever you want to add an environment query.
STACKEFFECT:
DESCRIPTION:
The name of the primary namespace. Execution pushes the FORTH WID to the top of the search order . (For ISO-compliance it would replace the top.) 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 NAMESPACE
STACKEFFECT: --- addr
DESCRIPTION:
Leave the dictionary entry address addr of the topmost word in the CURRENT word list.
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 NAMESPACE. 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 NAMESPACE
STACKEFFECT: --- addr
DESCRIPTION:
A user variable containing the dictionary entry address of the word most recently created by NAMESPACE . All namespace names are linked by these fields to allow FORGET to find all vocabularies.
SEE ALSO: WORDLISTS~ NAMESPACE