CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / simtel / cpmug / cpmug023.ark / STOIC.DOC < prev next >

Wrap

Text File | 1984-04-29 | 45.2 KB | 1,696 lines

*************************************************************************** ** COPYRIGHT (C) MASSACHUSETTS INSTITUTE OF TECHNOLOGY AND HARVARD ** ** UNIVERSITY, BIOMEDICAL ENGINEERING CENTER 1977. ALL RIGHTS RESERVED. ** *************************************************************************** STOIC (STACK ORIENTED INTERACTIVE COMPILER) J. SACHS 2/14/77 STOIC IS A GENERAL PURPOSE INTERACTIVE PROGRAM WHICH INCORPORATES THE CAPABILITIES OF A COMPILER, EDITOR ASSEMBLER, DEBUGGER, LOADER, AND OPERATING SYSTEM WITHIN A SINGLE CONSISTENT ARCHITECTURE. IT IS CORE-EFFICIENT WHILE RETAINING HIGH RUNNING SPEEDS. IN ADDITION, THE LANGUAGE IS EXTREMELY FLEXIBLE, PERMITTING THE USER TO DEVELOP A WORKING VOCABULARY OF SUBROUTINES TAILORED TO HIS SPECIFIC APPLICATION. THE SINGLE MOST PROMINENT FEATURE OF STOIC IS ITS PRINCIPAL DATA STRUCTURE, CALLED THE DICTIONARY. THE DICTIONARY IS AN ORDERED LIST OF ENTRIES CALLED WORDS. ASSOSCIATED WITH THE DICTIONARY ENTRY FOR EACH WORD IS A NAME; A LEGAL NAME FOR A WORD IS ANY STRING OF UP TO 127 ASCII CHARACTERS. PUNCTUATION, NUMERICS, AND MOST OTHER SPECIAL CHARACTERS MAY BE FREELY USED WITHIN A NAME. TWO NAMES ARE EQUIVALENT IF AND ONLY IF THEIR FIRST FIVE CHARACTERS ARE THE SAME AND THEY HAVE EXACTLY THE SAME LENGTH. ILLEGAL CHARACTERS WITHIN A NAME ARE: SPACE TAB CARRIAGE RETURN FORM FEED LINE FEED RUBOUT NULL EXAMPLES: ABCDE IS NOT EQUIVALENT TO ABCDEF (HEAD1) IS EQUIVALENT TO (HEAD2) A LITERAL IS A SEQUENCE OF CHARACTERS WHICH DESCRIBES A CONSTANT. THE BASIC STOIC SUPPORTS TWO TYPES OF LITERAL; 16-BIT INTEGER AND STRING. THE LANGUAGE MAY BE EXTENDED TO INCLUDE OTHER DATA TYPES SUCH AS FLOATING POINT OR DOUBLE PRECISION INTEGER. AN INTEGER LITERAL IS A SEQUENCE OF DIGITS OPTIONALLY PRECEDED BY A PLUS OR MINUS SIGN. ALL DIGITS MUST BE LESS THAN THE CURRENT RADIX. NO SPACES MAY BE EMBEDDED WITHIN THE LITERAL. INTEGER LITERAL MUST BE IN THE RANGE OF -32768 TO 32767 IS SIGNED OR 0 TO 65535 IF UNSIGNED. EXAMPLES: -1234 IS A LEGAL LITERAL +-100 IS NOT A LEGAL LITERAL -AFC0 IS A LEGAL LITERAL IF RADIX IS HEXADECIMAL STRING LITERALS MAY TAKE ONE OF THREE FORMS: 1) A STRING ENCLOSED IN DOUBLE QUOTES: "STRING" 2) A STRING ENCLOSED IN BACKSLASHES: \STRING\ 3) A STRING PRECEDED BY SINGLE QUOTE AND TERMINATED BY SPACE OR TAB: 'STRING IN ANY OF THE ABOVE TYPES OF STRING LITERAL, THE END OF THE LINE (RETURN OR FORM FEED) MAY SERVE AS A TERMINATOR. SPECIAL CHARACTERS SUCH AS RETURN, RUBOUT, ETC. MAY BE INCLUDED IN A STRING LITERAL BY ENCLOSING THE CORRESPONDING OCTAL ASCII CODE BETWEEN TWO AMPERSANDS (&). EXAMPLES: "THIS IS A STRING LITERAL" \THIS LITERAL CONTAINS A RETURN &15&\ '&177&&15& STOIC SYNTAX IS QUITE SIMPLE. A LEGAL COMMAND LINE CONSISTS OF A SEQUENCE OF LITERALS AND/OR NAMES OF WORDS SEPARATED BY SPACES OR TABS, AND TERMINATED BY CARRIAGE RETURN OR FORM FEED. PROGRAMMING IN STOIC CONSISTS PRIMARILY OF DEFINING A SET OF NEW WORDS BASED ON WORDS WHICH HAVE ALREADY BEEN DEFINED. AN INITIAL VOCABULARY OF ABOUT ONE HUNDRED WORDS CALLED THE KERNEL ENABLES THE USER TO GET STARTED. THE PRINCIPAL VEHICLE FOR COMMUNICATION BETWEEN WORDS IS THE PARAMETER STACK, FREQUENTLY CALLED "THE STACK". TYPICALLY, THE PARAMETERS UPON WHICH A WORD WILL OPERATE ARE PUSHED ON THE STACK, THE WORD POPS ITS PARAMETERS FROM THE STACK AND PUSHES ITS RESULTS ON THE STACK. COMMUNICATION THROUGH VARIABLES IN FIXED LOCATIONS IS ALSO USED. STOIC USES REVERSE POLISH NOTATION FOR ALL OPERATIONS. THIS MEANS THAT ALL OPERANDS PRECEDE THEIR OPERATORS; PARENTHESES ARE NEVER NECESSARY. EXAMPLES: 1 1 + 2 * IN ALGEBRAIC NOTATION IS (1+1)*2 1 2 3 * - IN ALGEBRAIC NOTATION IS 1-(2*3) UNLIKE MOST OTHER HIGER LEVEL LANGUAGES, STOIC ENABLES THE USER TO MANIPULATE ADDRESSES AS WELL AS DATA. IT IS VERY IMPORTANT HOWEVER FOR THE USER TO REMAIN AWARE OF THE DISTINCTION BETWEEN AN ADDRESS AND ITS CONTENTS. THERE ARE THREE COMMON TYPES OF WORDS WHICH PUSH NUMBERS ON THE STACK; LITERALS, CONSTANTS, AND VARIABLES. A REFERENCE TO A LITERAL OR A CONSTANT CAUSES ITS VALUE TO BE PUSHED ON THE STACK. A REFERENCE TO A VARIABLE CAUSES ITS ADDRESS TO BE PUSHED ON THE STACK. THE TWO OPERATORS "@" AND "!" ARE USED TO OBTAIN AND MODIFY THE VALUE OF A VARIABLE. THEY ARE DEFINED AS FOLLOWS: @ REPLACE THE ADDRESS ON THE TOP OF THE STACK BY THE CONTENTS OF THAT ADDRESS. THIS WORD IS USED TO LOAD THE CONTENTS OF A MEMORY LOCATION ONTO THE STACK. ! STORE AT THE ADDRESS ON THE TOP OF THE STACK THE NUMBER NEXT TO TOP OF THE STACK. BOTH NUMBERS ARE REMOVED FROM THE STACK. EXAMPLES: IN THE FOLLOWING EXAMPLES, X, Y, AND Z ARE VARIABLES, WHILE A, B, AND C ARE CONSTANTS. 100 X ! SET VALUE OF X TO 100. X 100 ! STORE THE ADDRESS OF X IN LOCATION 100 (UNDER NORMAL CIRCUMSTANCES, THIS WOULD BE A VERY SERIOUS ERROR). X @ Y ! SET THE VALUE OF Y TO THE VALUE OF X X Y ! SET THE VALUE OF Y TO THE ADDRESS OF X X @ Y @ + Z ! ADD THE VALUES OF X AND Y AND STORE THE RESULT IN Z. X A + Y ! STORE (ADDRESS OF X)+A IN Y. X A B + + @ Y ! SET VALUE OF Y TO THE CONTENTS OF LOCATION X+A+B. STOIC PROVIDES THE USER WITH AN UNUSUALLY LARGE NUMBER OF FIXED POINT OPERATORS FROM WHICH THE FOLLOWING MORE COMMON EXAMLES HAVE BEEN EXTRACTED. UNLESS OTHERWISE SPECIFIED, ALL NUMBERS ARE 16-BIT INTEGERS. UNARY OPERATORS THE FOLLOWING OPERATORS REPLACE THE TOP OF THE STACK WITH THEIR RESULT. THE NUMBER ON THE TOP OF THE STACK IS CALLED "A". MINUS -A ABS ABSOLUTE VALUE OF A NOT LOGICAL COMPLEMENT OF A 2* A*2 2/ A/2 (SIGNED) U2/ A/2 (UNSIGNED) 1+ A+1 1- A-1 EQZ -1 IF A EQUAL TO 0 0 OTHERWISE NEZ -1 IF A NOT EQUAL TO 0 0 OTHERWISE LTZ -1 IF A LESS THAN 0 0 OTHERWISE LEZ -1 IF A LESS OR EQUAL TO 0 0 OTHERWISE GEZ -1 IF A GREATER OR EQUAL TO 0 0 OTHERWISE GTZ -1 IF A GREATER THAN 0 0 OTHERWISE BINARY OPERATORS THE FOLLOWING OPERATORS REPLACE THE TOP TWO NUMBERS ON THE STACK WITH THEIR RESULT. THE NUMBER ON THE TOP OF THE STACK IS CALLED "A", THE NEXT TO TOP IS CALLED "B". + B+A - B-A * B*A / B/A MAX MAXIMUM (B,A) (SIGNED) MIN MINIMUM (B,A) (SIGNED) AND LOGICAL AND OF B,A OR LOGICAL OR OF B,A XOR LOGICAL EXCLUSIVE OR OF B,A EQ -1 IF B EQUAL TO A 0 OTHERWISE NE -1 IF B NOT EQUAL TO A 0 OTHERWISE LT -1 IF B LESS THAN A 0 OTHERWISE LE -1 IF B LESS OR EQUAL TO A 0 OTHERWISE GE -1 IF B GREATER OR EQUAL TO A 0 OTHERWISE GT -1 IF B GREATER THAN A 0 OTHERWISE A NUMBER OF OPERATORS ARE ALSO PROVIDED WHOSE SOLE FUNCTION IS TO REORGANIZE THE ELEMENTS OF THE STACK: STACK STACK NAME BEFORE AFTER DESCRIPTION DUP A A DUPLICATES TOP OF STACK A OVER A B DUPLICATES TOP - 1 B A B 2OVER A C DUPLICATES TOP - 2 B A C B C 3OVER A D DUPLICATES TOP - 3 B A C B D C D UNDER A A STORES TOP AT TOP - 1 B 2UNDER A B STORES TOP AT TOP - 2 B A C 3UNDER A B STORES TOP AT TOP - 3 B C C A D DROP A B DISCARDS TOP B 2DROP A C DISCARDS TOP 2 STACK ENTRIES B C 3DROP A D DISCARDS TOP 3 STACK ENTRIES B C D SWAP A B EXCHANGES TOP AND TOP - 1 B A 2SWAP A A EXCHANGES TOP - 1 AND TOP - 2 B C C B FLIP A C EXCHANGES TOP AND TOP - 2 B B C A +ROT A B ROLL TOP 3 STACK ENTRIES UP B C C A -ROT A C ROLL TOP 3 STACK ENTRIES DOWN B A C B DDUP A A DUPLICATE THE TOP 2 STACK ENTRIES B B A B I/O WORDS "N" IS THE NUMBER ON THE TOP OF THE STACK. COLUMN VARIABLE CONTAINING THE CURRENT COLUMN NUMBER TYO OUTPUT THE ASCII CHARACTER IN THE RIGHTMOST 8 BITS OF N. COLUMN IS INCREMENTED UNLESS THE CHARACTER OUTPUT IS A RETURN IN WHICH CASE IT IS ZEROED. CR OUTPUT A RETURN FOLLOWED BY A LINE FEED. COLUMN IS ZEROED. IFCR OUTPUTS A RETURN, LINE FEED IF COLUMN IS NON-ZERO. SPACE OUTPUT A SPACE. SPACES OUTPUT N SPACES. TAB TAB TO COLUMN N. IF ALREADY AT OR BEYOND COLUMN N, NOTHING IS OUTPUT. TYI INPUT A CHARACTER. = OUTPUT N IN THE CURRENT RADIX FOLLOWED BY SPACE. ? OUTPUT THE CONTENTS OF THE LOCATION ADDRESSED BY N FOLLOWED BY SPACE. TYPE OUTPUT N CHARACTERS STARTING AT BYTE POINTER AT TOP - 1. WORDS WHICH CHANGE THE CURRENT RADIX OCTAL SET CURRENT RADIX TO OCTAL DECIMAL SET CURRENT RADIX TO DECIMAL HEX SET CURRENT RADIX TO HEXADECIMAL WORDS USED TO REFERENCE MEMORY LOCATIONS A REPRESENTS THE TOP OF THE STACK, B REPRESENTS THE NEXT TO TOP. <- STORE A AT LOCATION B (SAME AS "!" EXCEPT ARGUMENTS ARE REVERSED). 0<- STORE 0 AT LOCATION A -1<- STORE -1 AT LOCATION A +! ADD B TO THE CONTENTS OF LOCATION A 1+! INCREMENT LOCATION A 1-! DECREMENT LOCATION A MOVE COPY THE CONTENTS OF THE LOCATION ADDRESSED BY B TO THE LOCATION ADDRESSED BY A. XCHG EXCHANGE THE CONTENTS OF LOCATIONS A AND B. MVBYTES COPIES BYTES SEQUENTIALLY FROM ONE AREA TO ANOTHER BYTE COUNT AT TOP, SOURCE BYTE ADDRESS AT TOP - 2, DESTINATION BYTE ADDRESS AT TOP - 1. EXAMPLES: 0> 1 MINUS = -1 0> -1 ABS = 1 0> -1 EQZ = 0 0> 0 EQZ = -1 0> 1 1 + = 2 0> 1 1 1 + + = 3 0> 1 2 3 = = = 3 2 1 0> 1 2 SWAP = = 1 2 0> 1 2 DUP = = = 2 2 1 0> 1 2 1 - EQ = -1 0> 100 X ! X ? 100 0> -1 5 MAX = 5 0> -1 5 MIN = -1 COLON DEFINITIONS STOIC PROVIDES THE CAPABILITY OF DEFINING A NEW WORD IN TERMS OF PREVIOUSLY DEFINED WORDS BY MEANS OF THE COLON DEFINITION. ITS SYNTAX IS AS FOLLOWS: 'NEWWORD : WORD1 WORD2 ... WORDN ; THIS CREATES A NEW DICTIONARY ENTRY CALLED NEWWORD WHICH, WHEN EXECUTED, WILL IN TURN EXECUTE WORD1, WORD2, ... IN SEQUENCE. AFTER EXECUTING WORDN, IT WILL RETURN. EACH OF THE WORDS WORD1, WORD2, ... MUST ALREADY EXIST AS ENTRIES IN THE DICTIONARY. IF NOT, A FATAL ERROR MESSAGE OF THE FOLLOWING FORM WILL BE GENERATED: UNDEFINED (NAME OF UNDEFINED WORD) A WORD MAY BE REDEFINED AT ANY TIME. IN THIS CASE, ALL PRIOR DEFINITIONS WHICH REFERENCED THAT WORD WILL STILL EXECUTE THE OLD VERSION. ALL SUBSEQUENT DEFINITIONS HOWEVER WILL EXECUTE THE MOST RECENTLY DEFINED VERSION. REDEFINING A WORD WILL GENERATE THE FOLLOWING WARNING MESSAGE: REDEFINING (NAME OF WORD) EXAMPLES: 'AVERAGE : + 2/ ; THIS DEFINES THE WORD AVERAGE WHICH COMPUTES THE AVERAGE OF THE TOP 2 NUMBERS ON THE STACK. 0> 2 4 AVERAGE = 3 'SPACE : 40 TYO ; THIS DEFINES THE WORD "SPACE" WHICH TYPES A SPACE. (THE ASCII CODE FOR SPACE IS 40 OCTAL). IF THE NAME OF A WORD BEING REDEFINED APPEARS WITHIN THE NEW DEFINITION, ITS OLD MEANING WILL BE USED. THE PROCEDURE FOR MAKING RECURSIVE CALLS IS DESCRIBED BELOW UNDER "RECURSION". ITERATION STOIC PROVIDES FIVE MEANS FOR ITERATIVE EXECUTION OF A SEQUENCE OF WORDS, NAMELY: N ( ... ) EXECUTE THE WORDS INCLUDED IN PARENTHESES N TIMES. BEGIN ... END EXECUTE WORDS BETWEEN "BEGIN" AND "END" UNTIL A CONDITION IS SATISFIED. BEGIN ... IF ... REPEAT SIMILAR TO BEGIN ... END EXCEPT THE CONDITION IS TESTED AT THE BEGINNING OF THE LOOP. DO ... LOOP EXECUTE THE WORDS BETWEEN "DO" AND "LOOP", RUNNING AN INDEX FROM A LOWER TO AN UPPER LIMIT, INCREMENTING BY 1 EACH TIME. DO ... N +LOOP EXECUTE THE WORDS BETWEEN "DO" AND "+LOOP", RUNNING AN INDEX FROM A LOWER TO AN UPPER LIMIT, INCREMENTING BY N EACH TIME. ITERATIONS MAY BE NESTED SUBJECT TO THE NORMAL RESTRICTIONS ON OVERLAPPING RANGES, I.E. ANY ITERATION WHICH IS INITIATED WITHIN THE RANGE OF ANOTHER ITERATION MUST BE TERMINATED WITHIN THAT SAME RANGE. ( ... ) A SEQUENCE OF WORDS MAY BE EXECUTED REPETITIVELY USING THE FOLLOWING SYNTAX: N ( WORD1 WORD2 ... WORDN ) THIS CAUSES THE SEQUENCE WORD1, WORD2, ... TO BE EXECUTED N TIMES WHERE N IS THE NUMBER ON THE TOP OF THE STACK. IF N IS ZERO OR NEGATIVE, THE SEQUENCE OF WORDS IS NOT EXECUTED AT ALL AND CONTROL PASSES TO THE WORD FOLLOWING THE ")". EXAMPLE: 'DINGDING : 2 ( DING ) ; THIS DEFINITION IS FUNCTIONALLY EQUIVALENT TO: 'DINGDING : DING DING ; IN EITHER CASE, EXECUTING "DINGDING" CAUSES THE WORD "DING" TO BE EXECUTED TWICE. 'SPACES : ( SPACE ) ; THIS IS A DEFINITION OF THE WORD "SPACES". THUS "20 SPACES" CAUSES "SPACE" TO BE EXECUTED 20 TIMES. AN UNSIGNED VERSION OF PARENTHESIS ITERATION IS USED WHERE THE ITERATION COUNT IS BETWEEN 32767 AND 65535: N U( ... ) BEGIN ... END THE BEGIN ... END SYNTAX PERMITS THE USER TO EXECUTE A SEQUENCE OF WORDS AND THEN, DEPENDING ON A COMPUTED LOGICAL VARIABLE, EITHER LOOP BACK OR CONTINUE ON: BEGIN WORD1 WORD2 ... WORDN END THE SEQUENCE WORD1, WORD2, ... IS EXECUTED ONCE. WHEN THE "END" IS REACHED, THE TOP OF THE STACK IS POPPED AND TESTED. IF IT IS TRUE (NON-ZERO) THEN CONTROL PASSES TO THE WORD FOLLOWING "END". IF IT IS FALSE (ZERO) CONTROL PASSES BACK TO THE WORD FOLLOWING "BEGIN". EXAMPLE: 'EXAMPLE : BEGIN 1- DUP DUP = EQZ END DROP ; THIS DEFINES THE WORD "EXAMPLE" WHICH MIGHT BE CALLED AS FOLLOWS: 0> 5 EXAMPLE 4 3 2 1 0 EACH TIME THROGH THE LOOP, THE TOP OF THE STACK (INITIALLY THE NUMBER 5) IS DECREMENTED, PRINTED, AND COMPARED TO ZERO. IF IT IS NOT ZERO, THE LOOP IS REPEATED, WHEN IT BECOMES ZERO, THE LOOP TERMINATES. BEGIN ... IF ... REPEAT BEGIN ... IF ... REPEAT IS SIMILAR TO BEGIN ... END EXCEPT THAT THE TEST IS MADE AT THE BEGINNING OF THE LOOP RATHER THAN AT THE END. THE WORDS FROM "BEGIN" TO "IF" ARE EXECUTED. IF THE TOP OF THE STACK IS TRUE (NON-ZERO) THE WORDS BETWEEN "IF" AND "REPEAT" ARE EXECUTED AND CONTROL THEN PASSES BACK TO THE WORD FOLLOWING "BEGIN". IF THE TOP OF THE STACK IS FALSE (ZERO), CONTROL PASSES TO THE WORD FOLLOWING "REPEAT". EXAMPLE: BEGIN EOF NOT IF READ-RECORD REPEAT THIS EXAMPLE MIGHT BE USED TO READ THE CONTENTS OF A FILE. "EOF" RETURNS A -1 IF END OF FILE HAS BEEN ENCOUNTERED; A 0 OTHERWISE. "READ-RECORD" READS THE NEXT ENTRY IN THE FILE. BY TESTING FOR EOF AT THE BEGINNING OF THE LOOP, THE CASE OF A ZERO-LENGTH FILE IS PROPERLY HANDLED. DO LOOPS A DO LOOP FACILITY IS PROVIDED BY STOIC FOR INDEXING THROUGH A SEQUENCE OF WORDS. THERE ARE TWO FORMS OF DO LOOP: HIGH LOW DO WORD1 WORD2 ... WORDN LOOP HIGH LOW DO WORD1 WORD2 ... WORDN INCR +LOOP THE LIMITS "HIGH" AND "LOW" (THE TOP TWO STACK ENTRIES) ARE COMPARED. IF "HIGH" IS LESS THAN OR EQUAL TO "LOW", CONTROL PASSES TO THE WORD FOLLOWING "LOOP" OR "+LOOP". OTHERWISE, THE SEQUENCE WORD1, WORD2, ... IS EXECUTED. "LOOP" CAUSES THE LOWER LIMIT ("LOW") TO BE INCREMENTED BY 1 AND COMPARED TO THE UPPER LIMIT ("HIGH"). IF "LOW" IS EQUAL TO OR GREATER THAN "HIGH", THE LOOP IS TERMINATED. OTHERWISE ANOTHER ITERATION IS PERFORMED. "+LOOP" IS IDENTICAL TO "LOOP" WITH THE EXCEPTION THAT "LOW" IS INCREMENTED BY THE WORD ON THE TOP OF THE STACK ("INCR"). "INCR" IS NORMALLY A POSITIVE NUMBER. WITHIN THE RANGE OF THE LOOP, THE CURRENT VALUE OF THE LOOP INDEX IS AVAILABLE BY USING THE WORD "I". IF DO LOOPS ARE NESTED, "I" ALWAYS CONTAINS THE VALUE OF THE INNERMOST INDEX. THE NEXT OUTER INDICES ARE AVAILABLE USING THE WORDS "J" AND "K". THE WORD "I'" IS USED TO OBTAIN THE VALUE OF "HIGH"+"LOW"-I-1. THIS IS USED TO RUN AN INDEX BACKWARDS FROM "HIGH"-1 TO "LOW". THE WORDS "J'" AND "K'" ARE SIMILARLY DEFINED. WHEN PARENTHESES ARE NESTED WITH "DO" LOOPS, THEY COUNT AS ONE LEVEL OF INDEXING. "I" USED WITHIN THE RANGE OF A PARENTHESIS ITERATION WILL RETURN THE CURRENT VALUE OF THE ITERATION COUNT (WHICH RUNS FROM ITS INITIAL VALUE DOWNWARDS TO ONE). THE WORD "EXIT", CAUSES THE INNERMOST LOOP IN WHICH IT IS EMBEDDED TO UNCONDITIONALLY TERMINATE ON THE NEXT CYCLE, WHETHER A DO LOOP OR A PARENTHESIS LOOP. EXAMPLES: 5 0 DO I = LOOP THIS CUASES THE NUMBERS FROM 0 TO 4 INCLUSIVE TO BE TYPED OUT. 5 0 DO 5 0 DO J 5 * I + = LOOP CR LOOP THIS TYPES OUT THE NUMBERS FROM 0 TO 24 INCLUSIVE AS 5 LINES OF 5 NUMBERS EACH. 5 0 DO I' = LOOP THIS TYPES OUT THE NUMBERS FROM 4 TO 0 INCLUSIVE. 0 21 1 DO I + DUP = 2 +LOOP DROP THIS TYPES OUT THE FIRST 10 PERFECT SQUARES STARTING WITH 1. WHEN USING "I'" (OR "J'" OR "K'") IN CONJUNCTION WITH "+LOOP", "HIGH" SHOULD BE REPLACED BY "HIGH"-"INCR"+1, IF IT IS DESIRED TO PRODUCE THE SAME SET OF INDICES AS WITH "I". FOR EXAMPLE: 0> 24 0 DO I = 4 +LOOP 0 4 8 12 16 20 0> 24 0 DO I' = 4 +LOOP 23 19 15 11 7 3 1 0> 24 4 - 1 + 0 DO I' = 4 +LOOP 20 16 12 8 4 0 AN UNSIGNED DO LOOP IS USED WHERE THE LIMITS MUST BE CONSIDERED AS UNSIGNED NUMBERS; E.G. WHERE THE LIMITS ARE BYTE ADDRESSES IN THE UPPER 32K BYTES OF MEMORY: HIGH LOW UDO ... ULOOP HIGH LOW UDO ... INCR U+LOOP CONDITIONALS STOIC HAS A POWERFUL IF ... ELSE ... THEN CONSTRUCTION WHICH ALLOWS COMPLICATED LOGICAL TESTS TO BE PERFORMED. CONDITIONALS MAY BE NESTED, WITH THE SAME RESTRICTIONS THAT APPLY TO ITERATIONS. FOR THE PURPOSES OF THE CONDITIONAL, "TRUE" IS CONSIDERED TO BE ANY NON-ZERO VALUE; "FALSE" IS ANY ZERO VALUE. N IF T1 T2 ... TN THEN THE TOP OF THE STACK, "N" IS TESTED. IF TRUE (NON-ZERO) THE WORDS T1, T2, ... TN ARE EXECUTED. IF FALSE (ZERO) CONTROL PASSES TO THE WORD FOLLOWING "THEN". N IF T1 T2 ... TN ELSE F1 F2 ... FN THEN THE TOP OF THE STACK, "N" IS TESTED. IF TRUE (NON-ZERO) THE WORDS T1, T2, ... TN ARE EXECUTED; CONTROL THEN PASSES TO THE WORD FOLLOWING "THEN". IF FALSE (ZERO) CONTROL PASSES TO THE WORD FOLLOWING "ELSE". THE WORDS F1, F2, ... FN ARE EXECUTED. EXAMPLES: 'ABS : DUP LTZ IF MINUS THEN ; THIS DEFINES THE WORD "ABS" WHICH REPLACES THE TOP OF THE STACK WITH ITS ABSOLUTE VALUE. 'MAX : DDUP GT IF DROP ELSE UNDER THEN ; THIS DEFINES THE WORD "MAX" WHICH COMPARES THE TOP TWO STACK ENTRIES AND LEAVES THE LARGER OF THE TWO. COMMENTS THE WORD "%" APPEARING ON A LINE CAUSES THE REMAINDER OF THAT LINE TO BE IGNORED. NOTE THAT THE "%", TO BE RECOGNIZED AS A WORD, MUST BE PRECEDED AND FOLLOWED BY SPACE OR TAB. EXAMPLES: X @ Y ! % THIS IS A COMMENT %THIS IS NOT A COMMENT USING STOIC FROM THE KEYBOARD WHEN TYPING IN A COMMAND FROM THE KEYBOARD, THE RUBOUT KEY MAY BE USED TO DELETE THE LAST CHARACTER; TYPING A NULL DELETES THE ENTIRE COMMAND LINE. WHEN ACTIVATED, STOIC TYPES A PROMPT MESSAGE CONSISTING OF THE CURRENT NESTING DEPTH (SEE BELOW) FOLLOWED BY "> " TO INDICATE THAT IT IS AWAITING KEYBOARD INPUT. AT THIS POINT THE OPERATOR TYPES IN A COMMAND LINE. AS SOON AS RETURN OR FORM FEED IS TYPED, STOIC COMPILES THE COMMAND LINE AND, IN THE ABSENCE OF COMPILATION ERRORS, EXECUTES IT. UPON COMPLETION OF COMMAND EXECUTION, THE COMPILED CODE FROM THE LAST COMMAND IS DISCARDED AND STOIC AGAIN TYPES ITS PROMPT MESSAGE AND WAITS FOR THE NEXT COMMAND LINE. NESTING DEPTH AND CONTINUATION LINES STOIC MAINTAINS A NESTING DEPTH WHICH IS USED FOR SYNTAX CHECKING AND TO DETERMINE WHEN A MULTI-LINE COMMAND HAS BEEN COMPLETED AND IS READY TO EXECUTE. INITIALLY, THE NESTING DEPTH IS SET TO ZERO; IT IS INCREMENTED WHENEVER ANY OF THE FOLLOWING WORDS ARE ENCOUNTERED DURING COMPILATION: IF ELSE ( U( BEGIN DO : UDO THE NESTING DEPTH IS DECREMENTED BY THE FOLLOWING WORDS: THEN ELSE ) END LOOP +LOOP ; ULOOP U+LOOP REPEAT (DECREMENTS NESTING DEPTH BY 2) IF THE NESTING DEPTH EVER BECOMES NEGATIVE, THE FATAL ERROR "SYNTAX ERROR" IS GIVEN. A "SYNTAX ERROR" IS ALSO GENERATED IF THE NESTING DEPTH IS NON-ZERO EITHER AT THE BEGINNING OR AT THE END OF A COLON DEFINITION. AFTER COMPILING A LINE, STOIC CHECKS THE NESTING DEPTH; IF IT IS ZERO, THE LINE IS EXECUTED, IF NON-ZERO, IT CONTINUES COMPILATION ON THE NEXT LINE. FOR EXAMPLE: 0> 3 0 DO 1> 2 0 DO 2> I = 2> LOOP 1> CR 1> LOOP 0 1 0 1 0 1 0> THUS, THE EXECUTION OF THE DO LOOP IS AUTOMATICALLY POSTPONED UNTIL THE NESTING DEPTH RETURNS TO ZERO, I.E. WHEN THE "LOOP" MATCHING THE FIRST "DO" IS ENCOUNTERED. SIMILARLY, A MULTI-LINE COLON DEFINITION IS EXTENDED TO INCLUDE ALL WORDS UP TO THE MATCHING ";". EXECUTION OF COMPILED CODE MAY BE POSTPONED EVEN IF THE NESTING DEPTH IS ZERO BY USING THE WORD "^". IF "^" IS USED ANYWHERE ON A LINE, COMPILATION WILL UNCONDITIONALLY CONTINUE ON TO THE NEXT LINE. THIS FEATURE MAY BE USED AS FOLLOWS: 0> 5 0 DO I = LOOP ^ 0> 5 0 DO I = LOOP 0 1 2 3 4 0 1 2 3 4 0> A MORE REASONABLE APPLICATION OF "^" INVOLVES THE USE OF STRING LITERALS. SINCE COMPILED CODE OUTSIDE OF A COLON DEFINITION IS DISCARDED AFTER EXECUTION, STRING LITERALS TYPED IN ON ONE LINE ARE NOT ACCESIBLE TO SUBSEQUENT LINES UNLESS "^" IS USED TO FORCE THE COMPILED STRING LITERAL TO BE SAVED. FOR EXAMPLE: 0> \THIS IS A LONG MESSAGE WHICH USES THE ENTIRE LINE\ ^ 0> MSG THIS IS A LONG MESSAGE WHICH USES THE ENTIRE LINE 0> REPEATING THE LAST COMMAND LINE TYPING A LINE FEED CAUSES STOIC TO RECOMPILE AND RE-EXECUTE THE LAST COMMAND LINE EXECUTED. FOR EXAMPLE: 0> 2 2 + = 4 0> (LINE FEED TYPED) 4 0> (LINE FEED TYPED) 4 ERROR HANDLING THE FOLLOWING TWO WORDS ARE USED TO HANDLE FATAL ERRORS IN STOIC: ABORT CLEARS THE PARAMETER, RETURN, AND LOOP STACKS, RESETS THE NESTING DEPTH TO ZERO, AND FORCES CONTROL TO RETURN TO THE KEYBOARD. "ABORT" IS INVOKED BY CONTROL A. ERR TYPES THE STRING AT THE TOP OF THE STACK FOLLOWED BY THE NAME OF THE WORD LAST SCANNED FROM THE INPUT STREAM, AND, IF INPUT IS NOT COMING FROM THE KEYBOARD, THE LINE LAST COMPILED FROM THE INPUT FILE. "ABORT" IS THEN INVOKED TO RESET STOIC. DEFINING CONSTANTS, VARIABLES, AND ARRAYS CONSTANTS A CONSTANT IS A DICTIONARY ENTRY WHICH CAUSES A 16-BIT INTEGER TO BE PUSHED ON THE PARAMETER STACK. TO DEFINE A CONSTANT, THE WORD "CONSTANT" IS USED: VALUE 'NAME CONSTANT HERE, "VALUE" IS THE NUMBER ON THE TOP OF THE STACK AND "NAME" IS THE NAME TO BE ASSIGNED TO THE CONSTANT. EXAMPLE: 5 'NPTS CONSTANT THIS SETS UP A DICTIONARY ENTRY WITH NAME "NPTS". EXECUTING THE WORD "NPTS" WILL CAUSE A 5 TO BE PUSHED ON THE STACK. VARIABLES A VARIABLE IS A DICTIONARY ENTRY WHICH CONTAINS A 16-BIT INTEGER AS ITS VALUE. WHEN EXECUTED, IT CAUSES THE ADDRESS OF ITS VALUE TO BE PUSHED ON THE PARAMETER STACK. VARIABLES ARE DEFINED AS FOLLOWS: VALUE 'NAME VARIABLE "VALUE" IS THE NUMBER ON THE TOP OF THE STACK AND "NAME" IS THE NAME TO BE ASSIGNED TO THE VARIABLE. "VALUE" IS USED TO SET THE INITIAL VALUE OF THE VARIABLE. EXAMPLE: 100 'X VARIABLE THIS DEFINES A VARIABLE "X" WITH AN INITIAL VALUE OF 100. ARRAYS WHILE STOIC DOES NOT HAVE A BUILT-IN ARRAY HANDLING FACILITY, ITS ABILITY TO PERFORM ADDRESS ARITHMETIC MAKES SUBSCRIPTING POSSIBLE. THERE ARE SEVERAL METHODS FOR SETTING ASIDE STORAGE FOR AN ARRAY. THE SIMPLEST IS TO USE THE WORD "ARRAY": LENGTH 'NAME ARRAY THIS DEFINES AND ZEROS AN ARRAY WHOSE LENGTH (IN 16-BIT WORDS) AND NAME ARE SPECIFIED. THE ARRAY IS JUST A VARIABLE WITH EXTRA STORAGE LOCATIONS RESERVED. REFERENCING AN ARRAY THUS CAUSES THE ADDRESS OF THE ZEROTH ELEMENT TO BE PUSHED. EXAMPLE: 100 'BUFFER ARRAY THIS DEFINES AND ZEROES A 100-WORD ARRAY NAMED "BUFFER". AN EXAMPLE OF A CONVENIENT TECHNIQUE FOR DEFINING SMALL ARRAYS IS : 0 '3VEC VARIABLE 1 , 2 , THIS DEFINITION SETS UP A 3-VECTOR CALLED "3VEC" WHOSE INITIAL VALUE IS (0,1,2). THE WORD "," TAKES A NUMBER FROM THE TOP OF THE STACK AND APPENDS IT TO THE END OF THE DICTIONARY, AUTOMATICALLY EXTENDING THE LENGTH OF THE MOST RECENT DEFINITION. THIS SERVES THE DUAL FUNCTIONS OF RESERVING SPACE IN THE DICTIONARY AND INITIALIZING THE ARRAY. THE CONTENTS OF AN ARRAY MAY BE INITIALIZED TO ZERO OR ANY CONSTANT VALUE USING THE FOLLOWING WORDS: FILL FILLS AN ARRAY WHOSE ADDRESS IS AT TOP-2 AND HAS LENGTH (IN WORDS) AT TOP-1 WITH THE CONSTANT VALUE AT TOP. 0FILL ZERO FILLS AN ARRAY WHOSE ADDRESS IS AT TOP-1 AND HAS LENGTH (IN WORDS) AT TOP. EXAMPLE: 100 'X ARRAY X 100 -1 FILL THIS DEFINES A 100-WORD ARRAY "X" WHICH IS THEN FILLED WITH -1'S. EQUIVALENTLY, THE SAME ACTION IS PERFORMED BY: -1 'X VARIABLE 99 ( -1 , ) REFERENCING ARRAY ELEMENTS TO REFERENCE AN ELEMENT OF AN ARRAY, ALL THAT IS NECESSARY IS TO ADD AN APPROPRIATE OFFSET TO THE ADDRESS OF THE ZEROTH ELEMENT. NOTE THAT SINCE THE FIRST ELEMENT HAS OFFSET ZERO, THE NTH ELEMENT HAS OFFSET N-1. EXAMPLE: 10 'X ARRAY 10 0 DO I X I 2* + ! LOOP THE ABOVE CODE DEFINES A 10 ELEMENT ARRAY "X" AND FILLS IT WITH THE NUMBERS 0 TO 9. NOTE THAT SINCE ADDRESSES ARE IN BYTES, THE INDEX MUST BE MULTIPLIED BY 2. MULTIDIMENSIONAL SUBSCRIPTING IS HANDLED IN A SIMILAR FASHION. EXAMPLE: 100 'X ARRAY 10 0 DO 10 0 DO I J + J 10 * I + 2* X + ! LOOP LOOP THIS EXAMPLE SETS UP A 100 ELEMENT ARRAY "X" WHICH IS TREATED AS A 10 BY 10 MATRIX AND THEN STORES I+J IN THE ELEMENT (I,J). THE DICTIONARY THE DICTIONARY STARTS IN LOW CORE AND GROWS UPWARD TOWARD THE TOP OF MEMORY. EACH DEFINITION, AS IT IS MADE, IS APPENDED TO THE END OF THE DICTIONARY. THE VARIABLE ".D" IS A POINTER TO THE FIRST FREE WORD FOLLOWING THE END OF THE DICTIONARY. THE WORD "." PUSHES THE VALUE OF THE DICTIONARY POINTER (".D") AND IS EQUIVALENT TO TYPING ".D @". THE ADDRESS OF A DICTIONARY ENTRY MAY BE OBTAINED BY INVOKING THE FOLLOWING WORD: () NAME PUSHES ON THE STACK THE ADDRESS OF THE PARAMETER FIELD OF THE NAMED WORD. THIS WORD MAKES IT POSSIBLE TO MODIFY THE VALUE OF A CONSTANT. FOR EXAMPLE: 100 'N CONSTANT 200 () N ! THE FIRST LINE DEFINES A CONSTANT "N" WHOSE VALUE IS 100. THE NEXT LINE RESETS THE VALUE TO 200. THIS FEATURE SHOULD NOT BE USED IN ANY PROGRAM WHICH WILL SUBSEQUENTLY BE COMMITTED TO READ- ONLY MEMORY. THE FOLLOWING WORD IS USED TO OBTAIN THE ADDRESS OF A WORD IN THE DICTIONARY GIVEN ITS NAME: ADDRESS TAKES A STRING ARGUMENT ON THE STACK WHICH IS LOOKED UP IN THE DICTIONARY. IF NOT FOUND, AN ERROR MESSSAGE IS TYPED. IF FOUND, THE ADDRESS OF THE PARAMETER FIELD OF THE WORD IS RETURNED ON THE STACK. EXAMPLE: 'NEWVAL : ADDRESS 200 SWAP ! ; THIS DEFINES A WORD "NEWVAL" WHICH SETS THE PARAMETER FIELD OF ITS ARGUMENT TO 200. THUS, 'N NEWVAL IS EQUIVALENT TO THE PREVIOUS EXAMPLE. EXECUTING PROGRAMS STOIC PROGRAMS ARE STORED AS ASCII SOURCE FILES. EXECUTING A FILE CAUSES STOIC TO ACCEPT ITS COMMANDS FROM THE FILE INSTEAD OF THE KEYBOARD. FILE EXECUTION IS CONTROLLED BY THE FOLLOWING WORDS: LOAD EXECUTE A PROGRAM; ADDRESS OF NAME IS ON TOP OF STACK. ;F TERMINATES EXECUTION OF THE CURRENT FILE AND RETURNS CONTROL TO THE CALLING INPUT FILE OR TO THE SYSTEM KEYBOARD. SINCE STOIC USES THE LOOP STACK TO SAVE CERTAIN INTERPRETER VARIABLES WHEN EXECUTING "LOAD", NO EXECUTED FILE MAY PUSH ANYTHING ON THE LOOP STACK THAT IS NOT REMOVED WITHIN THAT SAME FILE. "LOAD" WORKS BY MODIFYING THE STOIC READ- NEXT-LINE ROUTINE SO THAT IT ACCEPTS INPUT FROM THE SPECIFIED FILE INSTEAD OF THE KEYBOARD. THUS, "LOAD" DOES NOT CAUSE THE CONTENTS OF THE FILE TO BE EXECUTED UNTIL THE CURRENT LINE HAS BEEN EXECUTED. EXAMPLES: 'DEFS LOAD THIS EXECUTES A FILE CALLED "DEFS" 'LDDEFS : . = 'DEFS LOAD ; THIS DEFINES "LDDEFS" WHICH TYPES OUT THE CURRENT VALUE OF THE DICTIONARY POINTER AND EXECUTES "DEFS". 'A LOAD 'B LOAD 'C LOAD THIS COMMAND LINE CAUSES ONLY THE CONTENTS OF FILE "C" TO BE EXECUTED AND LEAVES SEVERAL EXTRANEOUS NUMBERS ON THE LOOP STACK. MULTIPLE LOADS MAY NOT BE EXECUTED FROM THE SAME COMMAND LINE; THEY MUST BE SEPARATED BY CARRIAGE RETURNS. THUS, THE CORRECT WAY TO LOAD THE THREE FILES IS: 'A LOAD 'B LOAD 'C LOAD STOIC FILE SYSTEM THE STOIC FILE SYSTEM SUPPORTS CONTIGUOUS FILES WHICH ARE REFERENCED BY SIX-LETTER NAMES. THESE NAMES AND THE LOCATIONS OF THE FILES ON THE STORAGE MEDIUM ARE STORED IN A DIRECTORY WHICH OCCUPIES BLOCK ZERO. NEW FILES ARE ALWAYS ADDED AT THE END OF THE MEDIUM. THE BLOCKS TAKEN UP BY A FILE WHICH HAS BEEN DELETED ARE NOT AVAILABLE UNTIL THE WORD "SQUASH" HAS BEEN EXECUTED. "SQUASH" SLIDES ALL THE FILES DOWN AND RESTRUCTURES THE DIRECTORY TO ELIMINATE ALL GAPS. THE FOLLOWING WORDS CONTROL DIRECTORY MAINTENANCE AND FILE ACCESS: ZERO-DIRECTORY INITIALIZES THE DIRECTORY. THE PREVIOUS CONTENTS OF THE DIRECTORY ARE LOST. LIST-DIRECTORY TYPES A DIRECTORY LISTING IN TWO COLUMNS. LEFT RETURNS ON THE STACK THE NUMBER OF UNUSED BLOCKS ON THE STORAGE MEDIUM. CCONT CREATES A CONTIGUOUS FILE WHOSE LENGTH (IN BLOCKS) IS AT THE TOP OF THE STACK, THE NAME IS AT TOP - 1. DELETE DELETES THE FILE WHOSE NAME IS AT TOP OF STACK. RENAME RENAMES FILE WHOSE NAME IS AT TOP - 1 TO NAME AT TOP. FILE CREATES A 3-WORD FILE CONTROL TABLE WHOSE NAME IS AT TOP. WHEN REFERENCED, THE ADDRESS OF THE FILE CONTROL TABLE IS STORED IN THE VARIABLE "FCT". THIS CAUSES THE FILE CONTROL TABLE TO BECOME THE CURRENT FILE CONTROL TABLE. OPEN OPENS THE FILE WHOSE NAME IS AT TOP USING THE CURRENT FILE CONTROL TABLE. THE NUMBER OF THE FIRST BLOCK OF THE FILE IS STORED IN THE FIRST WORD OF THE FILE CONTROL TABLE AND THE OTHER TWO WORDS ARE ZEROED. WOPEN OPENS A FILE FOR WRITING; FILE NAME AT TOP OF STACK. ANY PREVIOUS VERSION OF THE FILE IS DELETED, A NEW VERSION IS CREATED WHOSE LENGTH IS EQUAL TO THE ENTIRE REMAINING FREE SPACE, AND THE FILE IS OPENED USING THE CURRENT FILE CONTROL TABLE. IF MORE THAN ONE OUTPUT FILE IS ACTIVE AT A TIME, ALL BUT ONE OF THEM MUST BE CREATED WITH "CCONT" AND OPENED WITH "OPEN", GIVING THE FILE LENGTH IN ADVANCE. THE LAST ONE MAY BE VARIABLE LENGTH AND OPENED WITH "WOPEN". SHRINK USING THE CURRENT FILE CONTROL TABLE, THE END OF THE DIRECTORY IS MOVED DOWN TO THE FIRST FREE BLOCK FOLLOWING THE CURRENT FILE. THIS WORD IS USED ONLY WITH FILES WHICH HAVE BEEN OPENED USING "WOPEN" TO RELEASE WHATEVER STORAGE IS NOT USED BY THE OUTPUT FILE. CLOSE ZEROES THE FIRST WORD OF THE CURRENT FILE CONTROL TABLE, SIGNALLING IT AS INACTIVE. GETBYTE USING THE CURRENT FILE CONTROL TABLE, RETURNS THE NEXT BYTE FROM THE FILE. GETBYTES USING THE CURRENT FILE CONTROL TABLE, AND TAKING A BYTE COUNT AT TOP AND A BUFFER ADDRESS AT TOP - 1, THE SPECIFIED NUMBER OF BYTES ARE READ FROM THE FILE INTO THE BUFFER. PUTBYTE USING THE CURRENT FILE CONTROL TABLE, STORES BYTE AT TOP IN NEXT BYTE OF FILE. PUTBYTES USING THE CURRENT FILE CONTROL TABLE, AND TAKING A BYTE COUNT AT TOP AND A BUFFER ADDRESS AT TOP - 1, THE SPECIFIED NUMBER OF BYTES ARE WRITTEN INTO THE FILE FROM THE BUFFER. GPOS USING THE CURRENT FILE CONTROL TABLE, RETURNS A DOUBLE PRECISION INTEGER FILE POSITION AT TOP AND TOP - 1. (MOST SIGNIFICANT WORD AT TOP). SPOS USING THE CURRENT FILE CONTROL TABLE SETS THE FILE POSITION TO THE DOUBLE PRECISION INTEGER VALUE AND TOP AND TOP - 1. EXIST SEARCHES THE DIRECTORY FOR THE NAME AT TOP. IF FOUND, THE ADDRESS OF THE DIRECTORY ENTRY IS LEFT AT TOP. IF NOT FOUND, THE ERROR "FILE DOES NOT EXIST" IS GIVEN. NOT-EXIST SEARCHES THE DIRECTORY FOR THE NAME AT TOP. IF FOUND, THE ERROR "FILE ALREADY EXISTS" IS GIVEN. OPEN? GIVES THE MESSAGE "FILE NOT OPEN" IF THE CURRENT FILE CONTROL TABLE IS NOT OPEN. FSQUASH REMOVES DELETED ENTRIES FROM THE END OF THE DIRECTORY. DELETED ENTRIES WITHIN THE DIRECTORY ARE NOT AFFECTED. FSQUASH IS CALLED AUTOMATICALLY AFTER A "DELETE". SQUASH REMOVES ALL DELETED ENTRIES FROM THE DIRECTORY. THE REMAINING FILES ARE MOVED DOWN TO FILL UP THE EMPTY SPACE. SEARCH SEARCHES THE DIRECTORY FOR THE NAME AT TOP. IF FOUND, A -1 IS RETURNED AT TOP AND A POINTER TO THE DIRECTORY ENTRY AT TOP - 1. IF NOT FOUND, A ZERO IS LEFT AT TOP. DIRECTORY RETURNS ON THE TOP OF THE STACK THE ADDRESS OF THE FIRST BYTE OF A BUFFER CONTAINING THE DIRECTORY. SLOT RETURNS THE ADDRESS OF THE END-OF DIRECOTRY ENTRY IN THE DIRECTORY BUFFER. SBLK GIVEN THE ADDRESS OF A DIRECTORY ENTRY AT TOP, RETURNS THE STARTING BLOCK NUMBER FOR THE FILE. PRINT TYPES OUT ON THE SYSTEM CONSOLE THE CONTENTS OF THE FILE WHOSE NAME IS AT TOP. COPY COPIES THE FILE WHOSE NAME IS AT TOP - 1 TO A FILE WHOSE NAME IS AT TOP. THE DESTINATION FILE IS CREATED AT THE END OF THE DIRECTORY; ANY PREVIOUS VERSION IS DELETED. DIRECTORY ENTRY FORMAT: WORD CONTENTS 0 1ST WORD OF NAME (= -1 IF DELETED) (= 0 IF END OF DIRECTORY) 1 2ND WORD OF NAME 2 3RD WORD OF NAME 3 NUMBER OF FIRST BLOCK OF FILE (NUMBER OF FIRST FREE BLOCK IF 1ST WORD = 0) FILE CONTROL TABLE FORMAT: WORD CONTENTS 0 NUMBER OF FIRST BLOCK OF FILE (= 0 IF NOT OPEN) 1 CURRENT RELATIVE BLOCK NUMBER 2 CURRENT RELATIVE BYTE NUMBER WITHIN CURRENT BLOCK BASIC BLOCK I/O WORDS THE FILE SYSTEM IS BUILT ON A SET OF LOWER LEVEL WORDS WHICH MAY BE USED DIRECTLY BY THE USER TO PERFORM OPERATIONS ON BLOCKS OF STORAGE: L M N RDBLKS READS N BLOCKS STARTING AT BLOCK M INTO MEMORY STARTING AT LOCATION L. L M N WRBLKS WRITES N BLOCKS STARTING AT BLOCK M FROM MEMORY STARTING AT LOCATION L. BUFFER HANDLING WOWRS STOIC MAINTAINS A POOL OF SYSTEM BUFFERS WHICH ARE USED TO HOLD BLOCKS FROM THE STORAGE MEDIUM IN MEMORY. THEY ARE ALLOCATED USING A "LEAST RECENTLY USED" ALGORITHM. RBLOCK RETURNS THE ADDRESS OF A BUFFER CONTAINING THE BLOCK WHOSE NUMBER IS AT TOP. WHEN A BLOCK IS REQUESTED USING "RBLOCK", IF THE SPECIFIED BLOCK IS ALREADY IN MEMORY, ITS ADDRESS IS IMMEDIATELY RETURNED. IF IT IS NOT IN MEMORY, THE LEAST RECENTLY USED BUFFER IS FREED (I.E. WRITTEN OUT IF MODIFIED), AND THE BLOCK IS READ IN. WBLOCK RETURNS THE ADDRESS OF A BUFFER CONTAINING THE BLOCK WHOSE NUMBER IS AT TOP. THE BUFFER IS FLAGGED AS MODIFIED. IF THE BLOCK IS NOT ALREADY IN MEMORY, IT IS NOT READ IN. FLUSH WRITES OUT ALL MODIFIED BUFFERS. THIS WORD MUST BE EXECUTED BEFORE SHUTTING DOWN THE SYSTEM OR CHANGING MEDIA TO ENSURE THAT THE INFORMATION ON THE STORAGE MEDIUM IS CURRENT. EBUF FLAGS ALL BUFFERS AS EMPTY. THIS WORD MUST BE USED WHEN CHANGING MEDIA. UPDATE FLAGS THE MOST RECENTLY ACCESSED BUFFER AS MODIFIED. WHENEVER THE VALUE OF ANY WORD WITHIN AN I/O BUFFER IS MODIFIED, THIS WORD MUST BE CALLED, OTHERWISE THE MODIFIED VERSION WILL NOT BE WRITTEN BACK ON THE STORAGE MEDIUM. SAVING AND RESTORING CORE IMAGES TWO WORDS ARE PROVIDED WITHIN THE KERNEL WHICH ENABLE THE USER TO SAVE A "SNAPSHOT" OF THE DICTIONARY AND ALL STOIC VARIABLES IN A FILE AND, AT A LATER TIME, TO RESTORE THE SAVED STATE OF MACHINE AND RESUME EXECUTION. THEIR USE IS OUTLINED BELOW: 'FILE WRCI WRITE A CORE IMAGE INTO THE NAMED FILE 'FILE RDCI READ A CORE IMAGE FROM THE NAMED FILE THE CONTENTS OF THE I/O BUFFERS ARE NOT SAVED AS PART OF THE CORE IMAGE FILE, BUT ALL OTHER VARIABLES USED BY THE KERNEL, THE CONTENTS OF ALL STACKS, THE INTERRUPT DISPATCH TABLE, AND ALL USER DEFINITIONS ARE TRANSFERRED. CORE IMAGE FILES MUST BE REGENERATED WHENEVER A NEW VERSION OF THE KERNEL IS USED SINCE THE NEW USER DEFINITIONS REFERENCE ABSOLUTE LOCATIONS WITHIN THE KERNEL. TO GENERATE A BOOTSTRAPPABLE FILE CONTAINING THE STOIC KERNEL PLUS ALL CURRENT USER DEFINITIONS, THE FOLLOWING COMMAND IS USED: 'FILE WRITE-BOOT WRITES A BOOTSTRAP FILE. THE BOOTSTRAP FILE CAN THEN BE LOADED DIRECTLY BY THE BOOTSTRAP BY RESPONDING WITH THE FILENAME TO THE INITIAL PROMPT. STRING HANDLING STOIC STRINGS ARE STORED IN MEMORY IN THE FOLLOWING FORMAT: <LENGTH>STRING<0> THE LENGTH BYTE DOES NOT INCLUDE THE TERMINATING NULL. THE STRING MAY INCLUDE NULLS BEFORE THE FINAL ONE. THE LENGTH FIELD MUST BE LESS THAN 128 DECIMAL. EXAMPLE: <4>ABCD<0> THIS IS THE INTERNAL REPRESENTATION OF THE STRING "ABCD". EXECUTING A STRING LITERAL CAUSES A POINTER TO THE FIRST BYTE OF THE STRING TO BE PUSHED ON THE STACK. THIS POINTER MAY BE CONVERTED INTO BYTE-POINTER, BYTE-COUNT FORM BY USING THE WORD "COUNT" DESCRIBED BELOW. COUNT "COUNT" TAKES A POINTER TO A STRING AS INPUT ON THE STACK AND LEAVES THE LENGTH OF THE STRING ON THE TOP OF THE STACK, AND A BYTE POINTER TO THE FIRST CHARACTER FOLLOWING THE LENGTH BYTE AT TOP - 1. MSG THE WORD "MSG" IS EQUIVALENT TO "COUNT TYPE". GIVEN A POINTER TO A STRING AT TOP, IT CAUSES THE STRING TO BE TYPED. S, "S," TAKES A STRING ARGUMENT ON THE TOP OF THE STACK AND COPIES THE STRING ONTO THE END OF THE DICTIONARY. THE END OF THE DICTIONARY IS EXTENDED TO PERMANENTLY INCLUDE THE STRING. EXAMPLES: 'LARK : 'NONSENSE MSG ; EXECUTING "LARK" CAUSES "NONSENSE" TO BE TYPED. NUMBER OUTPUT CONVERSION STOIC PREFORMS NUMBER CONVERSION USING A SMALL BUT POWERFUL SET OF WORDS WHICH PERMIT A WIDE VARIETY OF OUTPUT FORMATS TO BE GENERATED. NUMBER CONVERSION PROCEEDS FROM RIGHT TO LEFT, CONVERTING ONE DIGIT AT A TIME. THE CONVERSION TAKES PLACE IN THE CURRENT RADIX. DIGITS ARE STORED IN A TEMPORARY AREA AT THE END OF THE DICTIONARY SET UP BY "<#". RADIX VARIABLE WHICH CONTAINS CURRENT INPUT AND OUTPUT RADIX. <# INITIATE NUMBER CONVERSION. #PUT OUTPUT A CHARACTER FROM TOP OF STACK. #A CONVERT THE NUMBER ON THE TOP OF THE STACK TO AN ASCII DIGIT. # COMPUTE THE NEXT DIGIT AND OUTPUT IT. AN INTEGER IS INPUT FROM THE TOP OF THE STACK AND DIVIDED BY "RADIX". THE REMAINDER IS CONVERTED TO A DIGIT AND OUTPUT; THE QUOTIENT REMAINS ON THE STACK. #S COMPUTE DIGITS AND OUTPUT THEM UNTIL THE REMAINING NUMBER IS ZERO. "#S" ALWAYS OUTPUTS AT LEAST ONE DIGIT. #> TERMINATE THE NUMBER CONVERSION, LEAVING A BYTE COUNT ON TOP OF STACK, A BYTE POINTER AT TOP - 1. HIGHER LEVEL WORDS ARE USED TO PROVIDE NUMBER OUTPUT IN A DEFAULT FORMAT: U<#> CONVERT THE UNSIGNED NUMBER ON THE TOP OF THE STACK AND LEAVE BYTE COUNT AND BYTE POINTER ON THE STACK. "U<#>" IS DEFINED AS: 'U<#> : <# #S #> ; <#> CONVERT THE SIGNED NUMBER ON THE TOP OF THE STACK AND LEAVE BYTE COUNT AND BYTE POINTER ON THE STACK. "<#>" IS DEFINED AS: '<#> : DUP <L <# #S L> LTZ IF 55 #PUT THEN #> ; U= CONVERT AND OUTPUT THE NUMBER ON THE TOP OF THE STACK. (UNSIGNED) = CONVERT AND OUTPUT THE NUMBER ON THE TOP OF THE STACK. (SIGNED) U? CONVERT AND OUTPUT THE NUMBER ADDRESSED BY THE TOP OF THE STACK. (UNSIGNED) ? CONVERT AND OUTPUT THE NUMBER ADDRESSED BY THE TOP OF THE STACK. (SIGNED) EXAMPLE: '$= : <# # # 56 #PUT #S 44 #PUT #> TYPE ; (RADIX IS ASSUMED TO BE OCTAL) 0> 100 $= $1.00 0> 1000 $= $10.00 "$=" TYPES THE TOP OF THE STACK IN AN UNSIGNED DOLLAR AND CENTS FORMAT. NUMBER CONVERSION IS INITIATED BY "<#", THE CENTS ARE OUTPUT BY THE TWO "#"'S, A PERIOD IS OUTPUT BY "56 #PUT", THE REMAINING DOLLARS ARE OUTPUT BY "#S", AND THE DOLLAR SIGN IS OUTPUT BY "44 #PUT". "<# TERMINATES THE CONVERSION PROCESS AND LEAVES A BYTE POINTER AND BYTE COUNT FOR THE RESULTANT STRING ON THE STACK AS INPUT TO "TYPE" WHICH OUTPUTS THE STRING. JUSTIFICATION OF NUMERIC OUTPUT MAY BE ACHIEVED AS FOLLOWS: '4= : <#> 4 OVER - SPACES TYPE ; THE WORD "4=" WILL TYPE OUT NUMBERS RIGHT JUSTIFIED IN A FOUR COLUMN FIELD BY TYPING A VARIABLE NUMBER OF SPACES PRECEDING THE NUMBER. TYI AND TYO "TYI" AND "TYO" PROVIDE A GENERALIZED CHARACTER ORIENTED INPUT AND OUTPUT FACILITY. "TYI" INPUTS A CHARACTER BY EXECUTING THE WORD WHOSE ADDRESS IS CONTAINED IN THE VARIABLE "IN". "TYO", SIMILARLY EXECUTES THE CONTENTS OF "OUT". "IN" AND "OUT" ARE INITIALIZED TO POINT TO "<TTI>", AND "<TTO>", WHICH ARE TELETYPE INPUT AND OUTPUT WORDS. ANY WORD WHICH USES "TYO" FOR OUTPUT MAY BE MODIFIED TO OUTPUT ON ANOTHER DEVICE OR PERHAPS INTO A CORE BUFFER BY CHANGING "OUT". SIMILARLY, CHANGING "IN" WILL MODIFY THE INPUT OF ANY WORD USING "TYI". "TYPE", "MSG" AND ALL THE NUMBER CONVERSION ROUTINES USE "TYO" TO PERFORM OUTPUT. RECURSION SINCE STOIC IS A STACK ORIENTED LANGUAGE, RECURSION IS HANDLED QUITE EASILY. THE WORD "EXEC" TAKES AS AN ARGUMENT ON THE STACK THE ADDRESS OF A WORD TO BE EXECUTED AND CALLS IT. BY PLACING THE ADDRESS OF THE CALLING ROUTINE ITSELF ON THE STACK, A RECURSIVE CALL IS GENERATED. EXAMPLE: 0 'SELF VARIABLE 'FACTORIAL : DUP 1 NE IF DUP 1- SELF @ EXEC * THEN ; () FACTORIAL SELF ! THIS DEFINES A RECURSIVE FACTORIAL ROUTINE. VOCABULARIES IN ADDITION TO THE PARAMETER STACK, STOIC USES ANOTHER STACK CALLED THE VOCABULARY STACK. THIS STACK IS USED TO CONTROL DICTIONARY LOOKUP OPERATIONS. WHEN STOIC LOOKS UP A WORD IN THE DICTIONARY, IT STARTS ITS SEARCH AT A LOCATION WHOSE ADDRESS IN STORED ON THE TOP OF THE VOCABULARY STACK. IF THE SEARCH FAILS, IT SEARCHES AGAIN USING THE NEXT TO TOP OF THE VOCABULARY STACK, ETC. UNTIL THE BOTTOM OF THE VOCABULARY STACK IS REACHED. IF THE NAME IS STILL NOT FOUND, THE SEARCH FAILS. THE DICTIONARY MAY HAVE ANY NUMBER OF BRANCHES. DIFFERENT WORDS HAVING EXACTLY THE SAME NAMES MAY BE RESOLVED IF THEY ARE ON SEPARATE BRANCHES OF THE DICTIONARY. A BRANCH OF THE DICTIONARY IS CALLED A VOCABULARY. WHEN STOIC DEFINES A NEW WORD, THE DICTIONARY ENTRY IS APPENDED TO THE BRANCH POINTED TO BY THE VARIABLE "CURRENT". THE KERNEL HAS TWO VOCABULARIES, CALLED "STOIC<", AND "ASSEMBLER<". INITIALLY, THE VOCABULARY STACK CONTAINS ONLY THE ADDRESS OF "STOIC<". "ASSEMBLER<" IS USED WHEN MAKING CODE DEFINITIONS AND CONTAINS SPECIAL WORDS USED ONLY BY THE STOIC ASSEMBLER. "STOIC<" IS THE MAIN BRANCH OF THE DICTIONARY, AND "ASSEMBLER<" IS A SIDE-BRANCH. A NEW BRANCH OF THE DICTIONARY IS CREATED AS FOLLOWS: 'NAME BRANCH REFERENCING A VOCABULARY CAUSES ITS ADDRESS TO BE PUSHED ON THE VOCABULARY STACK. THE NEW BRANCH IS ATTACHED AT THE END OF THE EXISTING BRANCH POINTED TO BY "CURRENT". > DISCARDS THE TOP OF THE VOCABULARY STACK ATTEMPTING TO POP THE LAST ENTRY OFF THE BOTTOM OF THE VOCABULARY STACK CAUSES THE ERROR: "VOCABULARY STACK EMPTY". TO SET "CURRENT" TO POINT TO A NEW VOCABULARY, THE FOLLOWING WORD IS USED: DEFINITIONS SETS "CURRENT" TO LINK NEW DEFINITIONS ONTO THE SAME BRANCH OF THE DICTIONARY AS IS POINTED TO BY THE TOP OF THE VOCABULARY STACK. THE NORMAL PROCEDURE WHEN SETTING UP A NEW VOCABULARY IS AS FOLLOWS: 1) DEFINE THE VOCABULARY USING "BRANCH" 2) PUSH THE ADDRESS OF THE VOCABULARY ON THE VOCABULARY STACK BY REFERENCING THE VOCABULARY. 3) SET "CURRENT" USING "DEFINITIONS". 4) DEFINE ALL THE WORDS IN THE VOCABULARY. 5) POP THE VOCABULARY STACK USING ">". 6) RESET "CURRENT" EXAMPLE: 'VOCAB< BRANCH VOCAB< DEFINITIONS . . . > DEFINITIONS THIS DEFINES A NEW BRANCH OF THE DICTIONARY CALLED "VOCAB". ENTIRE SECTIONS OF THE DICTIONARY MAY BE DELETED BY USING THE FOLLOWING WORD: 'NAME FORGET DISCARDS THE NAMED DICTIONARY ENTRY AND ALL SUBSEQUENT ENTRIES. FORGET IS USEFUL WHEN TRYING OUT DEFINITIONS FROM THE KEYBOARD. THE USUAL PROCEDURE IS TO FIRST MAKE A DUMMY DEFINITION: 'TEST : ; NEXT, TEST DEFINITIONS ARE MADE (TYPICALLY BY LOADING A PROGRAM). IF THEY ARE UNSUCCESSFUL, "'TEST FORGET" WILL DELETE THEM FROM THE DICTIONARY, AND THE PROCESS IS REPEATED. FOR CONVENIENCE, THE DUMMY DEFINITION MAY BE PLACED AT THE BEGINNING OF THE PROGRAM. "FORGET" MAY ALSO BE USED TO PROVIDE AN OVERLAY FACILITY. SAY THAT A PROGRAM HAS BEEN LOADED. IT MAY THEN BE DELETED BY FORGETTING THE FIRST DEFINITION OF THE PROGRAM AND THE DICTIONARY SPACE IS THEN FREE TO LOAD ANOTHER PROGRAM. DEBUGGING TECHNIQUES THE FOLLOWING ARE TECHNIQUES WHICH MAY PROVE USEFUL IN DEBUGGING NEW DEFINITIONS: 1) IT IS USUALLY MORE EFFICIENT TO MAKE A NEW DEFINITION IN A FILE USING THE EDITOR RATHER THAN FROM THE KEYBOARD IF IT IS MORE THAN ONE LINE LONG. "FORGET" IS THEN USED TO REMOVE THE LAST VERSION OF THE DEFINITION BEFORE TRYING AGAIN. 2) TO TEST A WORD, MERELY FEED IN ARGUMENTS ON THE STACK, EXECUTE THE WORD, AND EXAMINE THE RESULTS USING "=" AND "?". 3) IF A WORD FAILS, TYPE IN THE WORDS WHICH MAKE IT UP, ONE AT A TIME, EXAMINING THE STACK AS YOU GO ALONG AND RESTORING IT BY TYPING THE PARAMETERS BACK IN, IN REVERSE ORDER. 4) AFTER EXECUTING A WORD AND EXAMINING THE RESULTS ON THE STACK, TYPE AN EXTRA "=" TO MAKE SURE THE STACK IS EMPTY. YOU SHOULD GET THE MESSAGE "STACK EMPTY". SIMILARLY, THE LOOP STACK SHOULD BE CHECKED BY TYPING "L>"; THIS SHOULD GENERATE THE MESSAGE "LOOP STACK EMPTY". 5) KEEP TRACK OF THE RADIX YOU ARE USING. THIS IS THE SOURCE OF FREQUENT ERRORS. WITHIN A FILE BEING EXECUTED, SAVE THE RADIX, SET IT TO THE VALUE THE PROGRAM EXPECTS, AND WHEN DONE, RESTORE THE SAVED VALUE. FOR EXAMPLE: RADIX @ DECIMAL . . . RADIX ! ;F THIS SAVES THE CURRENT RADIX ON THE STACK, AND SETS THE RADIX TO DECIMAL. UPON TERMINATION, THE OLD RADIX IS RESTORED (ASSUMING THE STACK HAS NOT BEEN DISTURBED). 6) THE PROPER SELECTION OF LOWER LEVEL WORDS HAS AN ENORMOUS EFFECT ON ALL SUBSEQUENT HIGHER LEVEL DEFINITIONS. THUS IT PAYS TO DESIGN THE LOWER LEVEL WORDS VERY CAREFULLY. 7) WHEN DEBUGGING A PROGRAM, TEST ALL LOWER LEVEL WORDS THOROUGHLY BEFORE TESTING THE WORDS WHICH CALL THEM. 8) BE ESPECIALLY CAREFUL WITH ANY WORD WHICH MODIFIES MEMORY; MAKE SURE THE WORD IS MODIFYING ONLY THOSE LOCATIONS YOU INTEND, AND NOT PART OF THE PROGRAM. ***EOF***