home *** CD-ROM | disk | FTP | other *** search
/ ftp.uni-stuttgart.de/pub/systems/acorn/ / Acorn.tar / Acorn / acornet / dev / forth / forthdemo.tar.Z / forthdemo.tar / _files / info < prev    next >
Text File  |  1991-04-23  |  40KB  |  1,429 lines
  1. ARMFORTH (c) Davidsoft 1991
  2.  
  3. Based upon the language FORTH
  4.  
  5. Version 1.10
  6.  
  7. David Redman
  8. 33 Manor Road,
  9. Potters Bar,
  10. Herts.
  11. EN6 1DQ
  12.  
  13. INTRODUCTION
  14.  
  15.         ARMFORTH is a FORTH like language, making extensive use of RPN
  16.         notation and stacks.  many of the commands contained in the
  17.         language are identical to their FORTH counterparts.  However
  18.         there are some differences. 
  19.  
  20. What ARMFORTH offers :
  21.         -       Multitasking :  - 8 separate processes.
  22.                 Each task has its own data, and return stacks.
  23.         -       Dynamic memory allocation words.
  24.                 ( malloc and free ).
  25.         -       File handling
  26.         -       An inbuilt editor written in ARMFORTH.
  27.         -       A WIMP version ( not internally multitasking)
  28.                 for rapid program development and testing in
  29.                 the DESKTOP environment.
  30.         -       32 bit stack and data manipulation
  31.         -       An assembler ( SOON )
  32.  
  33.     ARMFORTH is small, only 10K ( unsqueezed ) for the NON WIMP
  34.         version and 11K for the WIMP.  It is also fast, typically 6
  35.         times faster than BASIC, as an example:
  36.  
  37.         Language                empty loop to 1 million
  38.         ARMFORTH:               6 
  39.         BASIC:                  14 ( integer X%)
  40.                                 38 ( using x )
  41.         'C'                     2 (using integer)
  42.         
  43.         However the size of the code is also important, for the 'C' a
  44.         mere 48K, for BASIC about 40bytes ( 40K counting ROM ) for
  45.         ARMFORTH, 24 bytes ( 10K including KERNEL ). 
  46.  
  47. DATA TYPES
  48.  
  49.   ARMFORTH has only has two real data types, bytes and words, any others
  50. are created as they are needed and may be accessed by combining the two
  51. supported types. 
  52.  
  53.   All stack entries are 32 bits wide and may be used in any fashion the
  54. user requires, the only condition is that EVERY stack entry be WORD
  55. aligned after any created structure has been pushed onto it.  There are
  56. built in string printing support and compile commands but string
  57. manipulation routines such as strcpy are not, they are provided in the
  58. stringlib file though, and any additional special structure handling
  59. routines would have to be written.  The format of an ARMFORTH string is
  60. a length as the top stack entry with the string contained on the stack
  61. in 4 byte chunks starting with the first letter. 
  62.  
  63. FILE HANDLING
  64.  
  65.   ARMFORTH has RISCOS file handling and uses commands that are very
  66. similar to BASIC.  These are LOAD, OPEN, CLOSE, PTR, EXT, EXT#, EOF and
  67. CLOSE ( These commands are covered in more detail later on in this
  68. manual ). 
  69.  
  70.   ARMFORTH filing commands ( open and load ) expect a string on the
  71. stack when they execute, the remainder expect a file handle. 
  72.  
  73.   ARMFORTH has a file stack that may be nested 7 deep, this means that
  74. when loading a file it could be split into functional libraries ( like
  75. the editor with stringlib ).  If more than 7 files are opened at one
  76. time ARMFORTH will abort and it is a good idea to restart and reduce the
  77. file depth. 
  78.  
  79.  
  80. MULTITASKING
  81.  
  82.   It is import to appreciate that when multitasking the tasks have
  83. separate data and stack spaces they share the same dictionary space. 
  84. This means that any task which modified the dictionary could crash the
  85. other tasks. 
  86.  
  87.   This is not an unacceptable risk because the advantages far surpass
  88. this problem, for example multiple copies of the same code could be
  89. running, with different data.  Processes may communicate with each other
  90. via common data in the dictionary ( semiphores may be implemented ),
  91. obviously the system could be abused by forking a process that would
  92. compile a file into the background with disastrous results. 
  93.  
  94.   Finally all tasks have equal priority and are run in a round robin
  95. type task queue and are swapped every 10ms ( or as close to that
  96. interval as possible ) - It should be noted that assember code will NOT
  97. multitask in forth until it exits back into the ARMFORTH kernel ( this
  98. is how semaphores may be implemented ). 
  99.  
  100.  
  101. FLOW CONTROL
  102.  
  103.   This section will detail all the flow control commands used in
  104. ARMFORTH.  In the examples a brief description of what the example will
  105. do will be given and then the actual code.  Type exactly what you see
  106. written, a <RETURN> means press the RETURN key, everything after the
  107. <RETURN> up to the OK shows what ARMFORTH will produce, unless
  108. surrounded by [[ ]] which means type the contents. 
  109.  
  110. BEGIN..END
  111.   This is the fastest and most primitive of ARMFORTH loop constructs. 
  112. The code between the BEGIN and the END will be executed if the top stack
  113. entry is zero when the END is reached, at which point program execution
  114. will continue with the code following the END.  Example: wait for the
  115. user to press space then print DONE. 
  116.                 :wait begin get aspace = END [ DONE ] ;
  117.                 wait <RETURN> [[A B C <SPACE> ]] OK
  118.  
  119. DO ... LOOP
  120.   The most basic of ARMFORTH loop commands.  It takes 2 stack
  121. entries and starting at the top stack entry count up to the second stack
  122. entry.  The loop will always execute at least once.  The is no real loop
  123. variable but a loop variable may be accessed by the index i,j or k
  124. depending upon the depth of nesting ( i is first ).  The addition is
  125. made BEFORE comparison of the terminating condition.  Example: to count
  126. from 0 to 9 displaying each number
  127.                 : test cr 10 0 do i . loop ;
  128.                 test <RETURN>
  129.                 0 1 2 3 4 5 6 7 8 9 OK
  130.  
  131.  
  132. DO ... +LOOP
  133.   similar to DO..LOOP but the stack entry before the execution of +LOOP
  134. is the increment.
  135. Example: to count from 0 to 8 in 2's
  136.                 : test cr 10 0 do i . 2 +loop ;
  137.                 test <RETURN>
  138.                 0  2  4  6  8  OK
  139.  
  140. LEAVE
  141.   This command will cause the currently executing do..loop or
  142. do..+loop to terminate ( it set the current count to be the finishing
  143. value ).  It will not prevent a loop from executing less than once. 
  144.  
  145. IF..THEN
  146.   Provides a simple way to conditionally execute code, if the top stack
  147. entry is NON zero when the if evaluates then the code between the IF and
  148. THEN is executed, if the stack entry was zero then execution skips to
  149. the code following the then.
  150. Example: print BEEP if a 1 is the top
  151. stack entry. 
  152.                 : bleep if [ BEEP ] then ;
  153.                 0 bleep <RETURN> OK
  154.                 1 bleep <RETURN> BEEP OK
  155.  
  156. IF..ELSE..THEN
  157.   Provides facilities for executing one section of code OR
  158. another.  If the top stack entry is true the code between the IF and
  159. ELSE is executed otherwise the code between the ELSE and the THEN will
  160. be executed.  Program execution will continue with the code following
  161. the THEN in both cases. 
  162. Example: if top stack entry is 1 print TRUE else print FALSE. 
  163.                 : test if [ TRUE ] else [ FALSE ] then ;
  164.                 1 test <RETURN> TRUE OK
  165.                 0 test <RETURN> FALSE OK
  166.  
  167. BEGIN..IF..WHILE
  168.   Provides a form of WHILE loop in ARMFORTH, the code between BEGIN and
  169. IF will be repeated while the top stack entry upon execution of the IF
  170. is NON zero, if it is true then the code between the IF and WHILE will
  171. be executed and a branch made back to the code following BEGIN.  If the
  172. stack contained a zero when the IF evaluated the code following the
  173. WHILE while be executed.
  174. Example: print keys while <space> is not pressed. 
  175.                 : test begin get dup 32 <> if vdu while [ DONE ] ;
  176.                 test [[a]]a[[b]]b[[<SPACE>]] DONE OK
  177.  
  178. BEGIN..IF..ELSE..WHILE
  179.   This loop construct is essentially the opposite of the loop above.  It
  180. executes the code between the BEGIN and THE IF while the top stack entry
  181. is false and terminates when it is true.
  182. Example:
  183.                 : test begin get dup 32 = if [ Done ] else vdu while ;
  184.                 test [[a]]a[[b]]b[[<SPACE>]] DONE OK
  185.  
  186.  
  187. FORTH command list 
  188.  
  189. Some Syntax: 
  190.  
  191.   <...> means item must be present / or will be created
  192.   [   ] means optionally created. 
  193.  
  194. About this list: 
  195.  
  196. Command   : name of command
  197. Type      : variable / command / compiling command
  198. Arguments : <entry1> <entry2> <entry3> .. <nth entry>
  199. Returns   : <entry1> <entry2> <entry3> .. <nth entry> 
  200. Description
  201. A brief description of what the command does at compile or execute
  202. time depending upon its function.
  203.  
  204. Command : editv
  205. Type    : system variable
  206. Arguments :
  207. Returns   : address of edit vector
  208. Description used
  209. if a replacement 'inline' input routine is written the address of the
  210. routine is put into this variable. 
  211.  
  212. Command   : base
  213. Type      : system variable 
  214. Arguments : 
  215. Returns   : address of system base 
  216. Description
  217. used to change the current number entry mode base
  218. Example: 16 mode ! - sets hex numeric entry
  219.  
  220. Command   : compiler
  221. Type      : system variable 
  222. Arguments :  
  223. Returns   :  <entry>
  224. Description
  225. Pushes the address of the compiler variable which points to the last
  226. entry in the COMPILER vocabulary
  227.  
  228. Command : context
  229. Type    : system variable 
  230. Arguments       :  
  231. Returns :  <entry>
  232. Description
  233. Pushes the address of the system CONTEXT variable to the stack. 
  234.  
  235. Command : current
  236. Type    : system variable 
  237. Arguments       :  
  238. Returns :  <entry>
  239. Description
  240. Pushes the address of the current vocabulary variable.
  241.  
  242. Command : dp
  243. Type    : system variable 
  244. Arguments       :  
  245. Returns : address of dictionary pointer variable 
  246. Description
  247. used to locate the current dp value
  248.  
  249.  
  250. Command: himem
  251. Type    : system variable 
  252. Arguments       :  
  253. Returns :  address of himem variable
  254. Description
  255. the word at this address is the value of the highest address that the
  256. dictionary pointer could increase towards before corrupting the stack space. 
  257.  
  258. Command : lbp
  259. Type    : system variable 
  260. Arguments       :  
  261. Returns : address of line buffer pointer 
  262. Description
  263. used by inline and token for character entry and tokenisation
  264.  
  265. Command : mode
  266. Type    : system variable 
  267. Arguments       :  
  268. Returns : address of mode variable 
  269. Description
  270. indicates if system is in compile ( 1 ) or execute mode ( 0 )
  271.  
  272. Command : state
  273. Type    : system variable 
  274. Arguments       :  
  275. Returns : address of state variable 
  276. Description
  277. used with mode to decide if a word is compiled or executed
  278.  
  279. Command : core
  280. Type    : system variable 
  281. Arguments       :  
  282. Returns :  
  283. Description
  284. Invokes the CORE vocabulary.
  285.  
  286. Command : quit
  287. Type    : command 
  288. Arguments       :  
  289. Returns :  
  290. Description
  291. exits from the forth environment.
  292.  
  293. Command : singletask
  294. Type    : command 
  295. Arguments       :  
  296. Returns :  
  297. Description
  298. stop multitasking
  299.  
  300. Command : multitask
  301. Type    : command 
  302. Arguments       :  
  303. Returns :  
  304. Description
  305. start multitasking
  306.  
  307.  
  308. Command : fork
  309. Type    : command 
  310. Arguments       : address of routine to fork 
  311. Returns : 
  312. Description
  313. takes address of routine from stack and starts the task when the next quantam elapses.
  314. Example: ' test fork - will run test as a background task
  315.  
  316. Command : taskblock
  317. Type    : command 
  318. Arguments       :  
  319. Returns :  
  320. Description
  321.  
  322. Command : quantam
  323. Type    : system variable 
  324. Arguments       :  
  325. Returns : address of multitask data block 
  326. Description
  327. used by multitasking code to get access to task queues and status. enables utilities to be written to examine task status etc. DO NOT MODIFY THE DATA BLOCK THIS POINTS TO.
  328.  
  329. Command : token
  330. Type    : command 
  331. Arguments       : <separator> 
  332. Returns :  
  333. Description
  334. tokenises the next 'word' separated by <separator> into the dictionary space
  335. Example : aspace token - tokenises next word in input buffer
  336.  
  337. Command : search
  338. Type    : command 
  339. Arguments       : <address> 
  340. Returns : <status> [<address>] 
  341. Description
  342. used to locate a key word code address.  The dictionary pointed to be
  343. <address> will be searched.  if the token is found then status will be 0
  344. and the address of the routine will be pushed to the stack, otherwise a
  345. 1 will be pushed. 
  346.  
  347. Command : 0
  348. Type    : command / arithmetic
  349. Arguments       :  
  350. Returns : 0 
  351. Description
  352. pushes a zero onto the data stack
  353.  
  354. Command : 1
  355. Type    : command / arithmetic
  356. Arguments       :  
  357. Returns : 1 
  358. Description
  359. pushes a 1 onto data stack
  360.  
  361. Command : -1 
  362. Type    : command / arithmetic
  363. Arguments       :  
  364. Returns : -1 
  365. Description
  366. pushes -1 onto the data stack
  367.  
  368.  
  369. Command : 1+ 
  370. Type    : command / arithmetic
  371. Arguments       : <entry1> 
  372. Returns : <entry1>+1 
  373. Description
  374. adds 1 to top stack entry
  375.  
  376. Command : 1- 
  377. Type    : command / arithmetic
  378. Arguments       : <entry1> 
  379. Returns : <entry1>-1 
  380. Description
  381. subtracts 1 from the top stack entry
  382.  
  383. Command : 2+ 
  384. Type    : command / arithmetic
  385. Arguments       : <entry1> 
  386. Returns : <entry1>+2 
  387. Description
  388. adds 2 to top stack entry
  389.  
  390. Command : 2- 
  391. Type    : command / arithmetic
  392. Arguments       : <entry1> 
  393. Returns : <entry1>-2 
  394. Description
  395. subtracts 2 from the top stack entry
  396.  
  397. Command : 2* 
  398. Type    : command / arithmetic
  399. Arguments       : <entry1> 
  400. Returns : <entry1>*2 
  401. Description
  402. multiplies top stack entry by 2
  403. Command : 2/ 
  404. Type    : command / arithmetic
  405. Arguments       : <entry1> 
  406. Returns : <entry1> DIV 2 
  407. Description
  408. divides to stack entry by 2
  409.  
  410. Command : 4+ 
  411. Type    : command / arithmetic
  412. Arguments       : <entry1> 
  413. Returns:         <entry1>+4 
  414. Description
  415. adds 4 to top stack entry
  416.  
  417. Command : 4- 
  418. Type    : command / arithmetic
  419. Arguments       : <entry1> 
  420. Returns : <entry1>-4 
  421. Description
  422. subtracts 4 from the top stack entry
  423.  
  424. Command : 4* 
  425. Type    : command / arithmetic
  426. Arguments       : <entry1> 
  427. Returns : <entry1>*4 
  428. Description
  429. multiplies to stack entry by 4
  430.  
  431. Command : 4/ 
  432. Type    : command / arithmetic
  433. Arguments       : <entry1> 
  434. Returns : <entry1> DIV 4 
  435. Description
  436. divides top stack entry by 4
  437. Command : +
  438. Type    : command / arithmetic
  439. Arguments       : <entry1> <entry2> 
  440. Returns : <entry1>+<entry2> 
  441. Description
  442. adds top 2 stack entries and pushes the result
  443.  
  444. Command : -
  445. Type    : command / arithmetic
  446. Arguments       : <entry1> <entry2> 
  447. Returns : <entry2>-<entry1>  
  448. Description
  449. subtracts top 2 stack entries and pushes result
  450.  
  451. Command : *
  452. Type    : command / arithmetic
  453. Arguments       : <entry1> <entry2> 
  454. Returns : <entry2>*<entry1>  
  455. Description
  456. multiply produces a 32 bit result
  457.  
  458. Command : /
  459. Type    : command / arithmetic
  460. Arguments       : <entry1> <entry2> 
  461. Returns : <entry2>DIV<entry1> <entry2>MOD<entry1>  
  462. Description
  463. divides 2nd entry by first and leaves DIV and MOD on stack
  464.  
  465. Command : abs
  466. Type    : command / arithmetic
  467. Arguments       : <entry1> 
  468. Returns : <entry1> 
  469. Description
  470. if negative makes entry positive
  471. Command : minus
  472. Type    : command / arithmetic
  473. Arguments       : <entry1> 
  474. Returns : -<entry1> 
  475. Description
  476. changes sign of top stack entry
  477.  
  478. Command : min
  479. Type    : command / arithmetic
  480. Arguments       : <entry1> <entry2> 
  481. Returns : <entry> 
  482. Description
  483. leaves the smaller of the 2 top entries on the stack
  484.  
  485. Command : max
  486. Type    : command / arithmetic
  487. Arguments       : <entry1> <entry2> 
  488. Returns : <entry> 
  489. Description
  490. leaves the larger of the 2 top entries on the stack
  491.  
  492. Command : <<
  493. Type    : command / arithmetic
  494. Arguments       : <entry1> <entry2> 
  495. Returns : <entry> 
  496. Description
  497. leaves <entry2> left shifted by <entry1> bits on the stack
  498.  
  499. Command : >>
  500. Type    : command / arithmetic
  501. Arguments       : <entry1> <entry2> 
  502. Returns : <entry> 
  503. Description
  504. leaves <entry2> right shifted by <entry1> bits on the stack 
  505. Command : not
  506. Type    : command / logic
  507. Arguments       : <entry> 
  508. Returns : <entry> 
  509. Description
  510. if top stack entry is not zero then push 1 else push 0
  511.  
  512. Command : and
  513. Type    : command / logic
  514. Arguments       : <entry1> <entry2> 
  515. Returns : <entry> 
  516. Description
  517. replaces the top 2 stack entries by the bitwise AND of them.
  518.  
  519. Command : eor
  520. Type    : command / logic
  521. Arguments       : <entry1> <entry2> 
  522. Returns : <entry> 
  523. Description
  524. replaces the top 2 stack entries by the bitwise EOR of them
  525.  
  526. Command : or
  527. Type    : command / logic
  528. Arguments       : <entry1> <entry2> 
  529. Returns : <entry> 
  530. Description
  531. replaces the top 2 stack entries by the bitwise OR of them
  532.  
  533. Command : bic
  534. Type    : command / logic
  535. Arguments       : <entry1> <entry2> 
  536. Returns : <entry> 
  537. Description
  538. clears bits in entry2 that are set in entry 1
  539. Command : tst
  540. Type    : command / logic
  541. Arguments       : <entry1> <entry2> 
  542. Returns : <entry> 
  543. Description
  544. if bit number <entry1> in entry2 is set then push 1 else push 0
  545.  
  546. Command : ror
  547. Type    : command / logic
  548. Arguments       :  <entry1> <entry2>
  549. Returns :  <entry>
  550. Description
  551. rotate <entry2> by <entry1> bits right and push result onto stack.
  552.  
  553. Command : >
  554. Type    : command / control
  555. Arguments       : <entry1> <entry2> 
  556. Returns : <entry> 
  557. Description
  558. if entry2 > entry1 then push 1 else push 0
  559.  
  560. Command: >=
  561. Type    : command / control
  562. Arguments       : <entry1> <entry2> 
  563. Returns : <entry> 
  564. Description
  565. if entry2 >= entry1 then push 1 else push 0
  566.  
  567. Command : <
  568. Type    : command / control
  569. Arguments       : <entry1> <entry2> 
  570. Returns : <entry> 
  571. Description
  572. if entry2 < entry1 then push 1 else push 0
  573.  
  574. Command : <=
  575. Type    : command / control 
  576. Arguments       : <entry1> <entry2> 
  577. Returns : <entry> 
  578. Description
  579. if entry2 <= entry1 then push 1 else push 0
  580.  
  581. Command : =
  582. Type    : command / control
  583. Arguments       : <entry1> <entry2> 
  584. Returns : <entry> 
  585. Description
  586. if entry2 = entry1 then push 1 else push 0
  587.  
  588. Command : <>
  589. Type    : command / control
  590. Arguments       : <entry1> <entry2> 
  591. Returns : <entry> 
  592. Description
  593. if entry2 <> entry1 then push 1 else push 0
  594.  
  595. Command : 0=
  596. Type    : command / control
  597. Arguments       : <entry1> 
  598. Returns : <entry> 
  599. Description
  600. if entry1 = 0 then push 1 else push 0
  601. Command : 0<
  602. Type    : command / control
  603. Arguments       : <entry1> 
  604. Returns : <entry> 
  605. Description
  606. if entry1 < 0 then push 1 else push 0
  607.  
  608. Command : 0>
  609. Type    : command / control
  610. Arguments       : <entry1> 
  611. Returns : <entry> 
  612. Description
  613. if entry1 > 0 then push 1 else push 0
  614.  
  615. Command : execute
  616. Type    : command
  617. Arguments       :  <entry>
  618. Returns :  
  619. Description
  620. pops the top stack entry and will execute the ARMFORTH code at that address.
  621.  
  622. Command : abort 
  623. Type    : system control
  624. Arguments       :  
  625. Returns :  
  626. Description
  627. restarts the interpreter after a fault
  628.  
  629. Command : bin
  630. Type    : command
  631. Arguments       :  
  632. Returns :  
  633. Description
  634. selects binary display mode
  635.  
  636. Command : oct
  637. Type    : command 
  638. Arguments       : 
  639. Returns :  
  640. Description
  641. selects octal display mode
  642.  
  643. Command : dec
  644. Type    : command 
  645. Arguments       :  
  646. Returns :  
  647. Description
  648. selects decimal display mode
  649.  
  650. Command : hex
  651. Type    : command 
  652. Arguments       :  
  653. Returns :  
  654. Description
  655. selects hex display mode
  656.  
  657. Command : entry
  658. Type    : command 
  659. Arguments       :  
  660. Returns : <entry>
  661. Description
  662. pushes the address of the first header word in the latest entry in the
  663. CURRENT vocabulary. 
  664.  
  665. Command : here 
  666. Type    : command
  667. Arguments       : 
  668. Returns :  <entry>
  669. Description
  670. pushes the address of the next free dictionary location onto the data stack.
  671.  
  672. Command : ca! 
  673. Type    : command
  674. Arguments       :  <entry>
  675. Returns :  
  676. Description
  677. Stores the top stack entry in the word address location of the latest
  678. entry in the CURRENT vocabulary. 
  679.  
  680. Command : aspace
  681. Type    : command 
  682. Arguments       :  
  683. Returns : 32 
  684. Description
  685. pushes the ascii value of a space ( 32 ) onto the data stack.
  686.  
  687. Command : ,
  688. Type    : command 
  689. Arguments       : <entry> 
  690. Returns :  
  691. Description
  692. encloses the top data stack entry in the dictionary and advances the
  693. dictionary pointer by 1 word. 
  694.  
  695. Command : c,
  696. Type    : command 
  697. Arguments       : <entry> 
  698. Returns :  
  699. Description
  700. encloses the lowest byte of the top data stack entry in the dictionary
  701. and moves the dictionary pointer forward by 1.  CARE IS RECOMMENDED !!!
  702.  
  703. Command : buffer
  704. Type    : system variable 
  705. Arguments       :  
  706. Returns : <address of the input buffer> 
  707. Description
  708. used to get characters from the input buffer
  709.  
  710. Command : !
  711. Type    : command / memory 
  712. Arguments       : <entry1> <entry2> 
  713. Returns :  
  714. Description
  715. puts the word entry2 in the address entry1
  716.  
  717. Command : c!
  718. Type    : command / memory 
  719. Arguments       : <entry1> <entry2> 
  720. Returns :  
  721. Description
  722. puts the lsb of the word entry2 into the address entry1
  723.  
  724. Command : +!
  725. Type    : command / memory 
  726. Arguments       : <entry1> <entry2> 
  727. Returns :  
  728. Description
  729. adds entry2 to the value at address entry1
  730.  
  731. Command : c+!
  732. Type    : command / memory 
  733. Arguments       : <entry1> <entry2> 
  734. Returns :  
  735. Description
  736. adds the lsb of entry2 to the byte at address entry1
  737.  
  738. Command : 0set
  739. Type    : command / memory 
  740. Arguments       : <entry1> 
  741. Returns :  
  742. Description
  743. zeros the word at address entry1
  744.  
  745. Command : 1set
  746. Type    : command / memory 
  747. Arguments       : <entry1> 
  748. Returns :  
  749. Description
  750. sets the word at address entry1 to 1
  751. Command : c0set
  752. Type    : command / memory 
  753. Arguments       : <entry1> 
  754. Returns :  
  755. Description
  756. sets the byte at address entry1 to zero
  757.  
  758. Command : c1set
  759. Type    : command / memory 
  760. Arguments       : <entry1> 
  761. Returns :  
  762. Description
  763. sets the byte at address entry1 to 1
  764.  
  765. Command : @
  766. Type    : command / memory 
  767. Arguments       : <entry1> 
  768. Returns : <entry> 
  769. Description
  770. pushes the word at address entry1 onto the data stack
  771.  
  772. Command : c@
  773. Type    : command / memory 
  774. Arguments       : <entry1> 
  775. Returns : <entry> 
  776. Description
  777. pushes the byte ( expanded to 32 bits ) at address entry1 onto the data stack
  778.  
  779. Command : align
  780. Type    : command / memory 
  781. Arguments       : <entry1> 
  782. Returns : <entry> 
  783. Description
  784. replaces entry1 with the nearest value rounded up to a word boundary
  785. Example : dec 5 align . - would display 8
  786.  
  787. Command : over
  788. Type    : command / stack 
  789. Arguments       : <entry1> <entry2> 
  790. Returns : <entry2> <entry1> <entry2> 
  791. Description
  792. over pushes the second stack entry onto the data stack
  793.  
  794. Command : 2over
  795. Type    : command / stack 
  796. Arguments       : <entry1> <entry2> <entry3> 
  797. Returns : <entry3> <entry1> <entry2> <entry3> 
  798. Description
  799. 2over pushes the third stack entry onto the data stack.
  800.  
  801. Command : swap
  802. Type    : command / stack 
  803. Arguments       : <entry1> <entry2> 
  804. Returns : <entry2> <entry1> 
  805. Description
  806. swaps the top 2 stack entries
  807.  
  808. Command : 2swap
  809. Type    : command / stack 
  810. Arguments       : <entry1> <entry2> <entry3> 
  811. Returns : <entry3> <entry2> <entry1> 
  812. Description
  813. swaps the first and third stack entries.
  814.  
  815. Command : dup
  816. Type    : command / stack 
  817. Arguments       :
  818. Returns : <entry1> <entry1> 
  819. Description
  820. pushes the top stack entry onto the stack.
  821.  
  822. Command : drop
  823. Type    : command / stack 
  824. Arguments               : <entry1> <entry2> 
  825. Returns : <entry2> 
  826. Description
  827. pops the top stack entry.
  828.  
  829. Command:         2dup
  830. Type    : command / stack 
  831. Arguments       : <entry1> 
  832. Returns : <entry1> <entry1> <entry1> 
  833. Description
  834. duplicates the top stack entry twice.
  835.  
  836. Command : ?rs 
  837. Type    : command / stack
  838. Arguments       :  
  839. Returns :  <entry>
  840. Description
  841. pushes the value of the current return stack pointer,
  842.  
  843. Command : ?sp
  844. Type    : command / stack
  845. Arguments       :  
  846. Returns :  <entry>
  847. Description
  848. pushes the value of the data stack pointer prior to the push onto that
  849. data stack. 
  850.  
  851. Command : i 
  852. Type    : compile / loop index
  853. Arguments       :  
  854. Returns :  <entry>
  855. Description
  856. pushes the value of the inner most loop index onto the data stack.
  857.  
  858. Command : j 
  859. Type    : compile / loop index
  860. Arguments       :  
  861. Returns :  <entry>
  862. Description
  863. pushes the value of the 2nd inner most loop index onto the data stack.
  864.  
  865. Command : k 
  866. Type    : compile / loop
  867. Arguments       :  
  868. Returns :  <entry>
  869. Description
  870. pushes the value of the 3rd inner most loop index onto the data stack.
  871.  
  872. Command : -sp
  873. Type    : command / stack 
  874. Arguments       : <     entry1> 
  875. Returns :  
  876. Description
  877. this command will reduce the depth of the stack by <entry1> bytes.  CARE
  878. is recommended....  always leave SP on a word boundary.  YOU HAVE BEEN
  879. WARNED
  880.  
  881. Command : +sp
  882. Type    : command / stack 
  883. Arguments       : <entry1> 
  884. Returns :  
  885. Description
  886. this command will effectively push <entry1> bytes onto the stack
  887. although no actual valid data will be present.  Used mainly for
  888. reserving stack space.  CARE: always ensure that the stack remains on a
  889. word boundary when you have finished.  YOU HAVE BEEN WARNED. 
  890.  
  891. Command : rrot 
  892. Type    : command / stack
  893. Arguments       :  <entry1> <entry2> <entry3>
  894. Returns :  <entry2> <entry3> <entry1>
  895. Description
  896. rotates the top three stack entries once to the right.
  897. Example : 1 2 3 rrot . . . gives 2 1 3
  898.  
  899.  
  900. Command : lrot 
  901. Type    : command / stack
  902. Arguments       :  <entry1> <entry2> <entry3>
  903. Returns :  <entry3> <entry1> <entry2>
  904. Description
  905. rotates the top 3 stack entries to the left by one slot.
  906. Example :  1 2 3 lrot . . . gives 1 3  2
  907.  
  908. Command : rs>ds
  909. Type    : command / inter-stack 
  910. Arguments       :  
  911. Returns : <top entry from return stack> 
  912. Description
  913. pops the top entry from the return stack and pushes it onto the data
  914. stack.  CARE is recommended as popping a return address without careful
  915. consideration will result in the forth interpreter crashing.  YOU HAVE
  916. BEEN WARNED
  917.  
  918. Command : ds>rs
  919. Type    : command / inter-stack 
  920. Arguments: <entry> 
  921. Returns :  
  922. Description
  923. pops <entry> from the data stack and pushes it onto the return stack. 
  924. CARE is recommended here as a ds>rs without an rs>ds will destroy the
  925. return stack and could kill forth.  YOU HAVE BEEN WARNED
  926.  
  927. Command : .
  928. Type    : command / IO 
  929. Arguments       : <entry1> 
  930. Returns :  
  931. Description
  932. displays the top stack entry in the currently selected base.
  933.  
  934. Command : .r
  935. Type    : command / IO 
  936. Arguments        <entry1> <entry2> 
  937. Returns :  
  938. Description
  939. displays the <entry2> in a field width of <entry1>
  940.  
  941. Command : cr
  942. Type    : command / IO 
  943. Arguments       :  
  944. Returns :  
  945. Description
  946. echoes a CR/LF to the screen.
  947.  
  948. Command : inkey
  949. Type    : command / IO 
  950. Arguments       :  
  951. Returns : <status> [<key number>] 
  952. Description
  953. inkey waits .01 of a second for a key to be pressed, if no key is
  954. pressed it pushes a 0 otherwise it pushes the key and 1. 
  955.  
  956. Command : get
  957. Type    : command / IO 
  958. Arguments       :  
  959. Returns : <char> 
  960. Description
  961. get waits indefinitely until a key is pressed and then it pushes the
  962. ascii value of the key onto the stack. 
  963.  
  964.  
  965. Command : space
  966. Type    : command / IO 
  967. Arguments       :  
  968. Returns :  
  969. Description
  970. prints a space to the screen.
  971.  
  972. Command : echo
  973. Type    : command / IO 
  974. Arguments       : <ascii code> 
  975. Returns :  
  976. Description
  977. pops the stack and echoes the lsb of the word to the display.
  978.  
  979. Command : cls
  980. Type    : command / IO 
  981. Arguments       :  
  982. Returns :  
  983. Description
  984. clears the screen. It is a more efficient version of 12 echo.
  985.  
  986. Command : pos
  987. Type    : command / IO 
  988. Arguments       :  
  989. Returns : <ypos> <xpos> 
  990. Description
  991. pushes the current position (x,y) of the text cursor onto the stack.
  992.  
  993. Command : tab
  994. Type    : command / IO 
  995. Arguments       : <ypos> <xpos> 
  996. Returns :  
  997. Description
  998. moves the text cursor to position (xpos,ypos) on the screen.
  999.  
  1000. Command : malloc
  1001. Type    : command / memory 
  1002. Arguments       : <size> 
  1003. Returns : <status> [ <address> ] 
  1004. Description
  1005. malloc will try to allocate a space of <size> bytes, if unsuccessful
  1006. <status> will be 0 else <status> will be 1 and <address> will be the
  1007. address of the allocated block. 
  1008.  
  1009. Command : free
  1010. Type    : command / memory 
  1011. Arguments       : <address> 
  1012. Returns :  
  1013. Description
  1014. free will deallocate the block pointed to be <address>.  No error will
  1015. be reported if it is unsuccessful. 
  1016.  
  1017. Command : ?
  1018. Type    : command / IO 
  1019. Arguments       : <entry> 
  1020. Returns :  
  1021. Description
  1022. this command will display the word at the address pointed to by <entry>
  1023. in the current number base on the display. 
  1024.  
  1025. Command : c?
  1026. Type    : command / IO 
  1027. Arguments       : 
  1028. Returns :  
  1029. Description
  1030. this command will display the byte at the address pointed to by <entry>
  1031. in the current number base on the display. 
  1032.  
  1033. Command : forget 
  1034. Type    : dictionary management
  1035. Arguments       :  
  1036. Returns :  
  1037. Description
  1038. Searches the current vocabulary for the keyword following the forget and
  1039. will remove all keyword from that point forwards.  It is to forget
  1040. priority to completely erase the ARMFORTH dictionary. 
  1041.  
  1042. Command : ' 
  1043. Type    : command / vocabulary
  1044. Arguments       :  
  1045. Returns :  [<entry>] 
  1046. Description
  1047. scans the token following the tick in the input buffer and searches the
  1048. CURRENT and CONTEXT vocabularies.  If the word is found its execution
  1049. address is pushed to the stack otherwise the keyword followed by a
  1050. question mark will be displayed. 
  1051.  
  1052. Command : definitions 
  1053. Type    : command / vocabulary
  1054. Arguments       :  
  1055. Returns :  
  1056. Description
  1057. sets the system variable CURRENT to the value in CONTEXT.
  1058.  
  1059. Command : create 
  1060. Type    : defining word
  1061. Arguments       :  
  1062. Returns :  
  1063. Description
  1064. creates a dictionary header for the primitive keyword whose name follows
  1065. create and links it to the vocabulary. 
  1066.  
  1067. Command : : 
  1068. Type    : compiling word
  1069. Arguments       :  
  1070. Returns :  
  1071. Description
  1072. creates a token for the keyword following the : in the buffer, links it
  1073. to the current vocabulary and sets the system in compile mode. 
  1074.  
  1075. Command : next
  1076. Type    : compiling word
  1077. Arguments       :  
  1078. Returns :  
  1079. Description
  1080. encloses a jump to the inner interpreter NEXT routine in the dictionary.
  1081.  
  1082. Command : constant
  1083. Type    : defining word
  1084. Arguments       :  <entry>
  1085. Returns :  
  1086. Description
  1087. creates a word length constant dictionary entry whose value is the top
  1088. stack entry and whose name follows the constant keyword.  When the
  1089. keyword name is executed the value of the constant will be pushed to the
  1090. data stack. 
  1091.  
  1092. Command : variable 
  1093. Arguments       :  <entry>
  1094. Returns :  
  1095. Description
  1096. creates a word length variable entry whose value is the top stack entry
  1097. and whose name follows the constant keyword.  When the keyword name is
  1098. executed the address of the keyword is pushed to the stack. 
  1099.  
  1100. Command : immediate 
  1101. Type    : vocabulary management
  1102. Arguments       :  
  1103. Returns :  
  1104. Description
  1105. delinks the last keyword from the CURRENT vocabulary and links it to the
  1106. COMPILER vocabulary.  Adds keywords to the compiler vocabulary. 
  1107.  
  1108. Command : <builds 
  1109. Type    : defining word
  1110. Arguments       :  
  1111. Returns :  
  1112. Description
  1113. creates a CONSTANT keyword definition with an initial value of 0.  The
  1114. name is the token following <builds in the input buffer.  MUST be
  1115. terminated by a DOES> keyword. 
  1116.  
  1117. Command : does> 
  1118. Type    : program control
  1119. Arguments       :  <return stack entry1> <return stack entry2>
  1120. Returns :  
  1121. Description
  1122. replaces the first word in the code body of the latest entry in the
  1123. vocabulary with the top return stack entry and replaces the code address
  1124. with the second return stack entry. 
  1125.  
  1126. Command : vocabulary 
  1127. Type    : defining word
  1128. Arguments       :  
  1129. Returns :  
  1130. Description
  1131. creates a keyword whose name follows it , with an initial link to the
  1132. latest entry in the CURRENT vocabulary.  When executed it sets CURRENT
  1133. to the link address.  Used for defining new vocabularies. 
  1134.  
  1135. Command : (
  1136. Type    : command / string operator 
  1137. Arguments       :  
  1138. Returns : loads of stuff - see description
  1139. Description
  1140. This command will copy the string that is enclosed by the brackets () to
  1141. the data stack.  it will then push the length of the string onto the
  1142. data stack.  The string will be terminated by a 0 byte starting at the
  1143. address after the length word has been popped. 
  1144.  
  1145. Command :  type
  1146. Type    : command / string display 
  1147. Arguments       : <length> <loads of words marking string> 
  1148. Returns :  
  1149. Description
  1150. this command will print the next <length> bytes from the top of the data
  1151. stack.  after completion the stack has the string removed as is aligned
  1152. to a word boundary. 
  1153.  
  1154. Command : close               DISABLED ON DEMO VERSION
  1155. Type    : command / Filing 
  1156. Arguments       : <file handle> 
  1157. Returns :  
  1158. Description
  1159. this command will close the file that has a file handle <file handle>. 
  1160. a zero value for <file handle> will close ALL system files - this could
  1161. be dangerous. 
  1162.  
  1163. Command : load
  1164. Type    : command / filing 
  1165. Arguments       : <length> <string> 
  1166. Returns :  
  1167. Description
  1168. this command will load the forth file identified by the string that is
  1169. on the top of the stack ( see the '(' entry earlier ). 
  1170.  
  1171. Command : open                 DISABLED ON DEMO VERSION
  1172. Type    : command / filing 
  1173. Arguments       : <string>
  1174. Returns : <status> [<handle>] 
  1175. Description
  1176. open takes a filename string ( in type format ) from the stack and tries
  1177. to open the file with read/write or create access.  This means if the
  1178. file exists it may be modified, and if not it will be created.  If an
  1179. error occurs then a zero will be pushed to the stack otherwise a 1 and
  1180. the handle are pushed to the stack. 
  1181.  
  1182. Command : ptr#                  DISABLED ON DEMO VERSION
  1183. Type    : command / filing
  1184. Arguments       : <offset> <handle>
  1185. Returns :
  1186. Description
  1187. ptr# will move the filepointer of the file <handle> up to position
  1188. <offset> in the file, extending the file if need be.  If 0 is used as
  1189. the offset the file may be read from the start. 
  1190.  
  1191. Command : #ptr                  DISABLED ON DEMO VERSION
  1192. Type    : command / filing
  1193. Arguments       : <handle>
  1194. Returns : <offset>
  1195. Description
  1196. #ptr will return the current position of the file pointer within the
  1197. file selected by <handle> and push it onto the data stack. 
  1198.  
  1199. Command : putc                  DISABLED ON DEMO VERSION
  1200. Arguments       :  <data> <handle>
  1201. Returns :  
  1202. Description
  1203. putc will write a lsb of <data> into the file selected by <handle>. 
  1204. Care should be taken as all files are opened read/write and may be
  1205. modified. 
  1206.  
  1207. Command : getc                  DISABLED ON DEMO VERSION
  1208. Type    : command / filing
  1209. Arguments : <handle>
  1210. Returns : <data> Description getc will read one
  1211. byte from the selected file, expand it up to 32 bits and push it onto
  1212. the stack. 
  1213.  
  1214. Command : putw                  DISABLED ON DEMO VERSION
  1215. Type    : command / filing
  1216. Arguments       :  <data> <handle>
  1217. Returns :  
  1218. Description
  1219. putw will write <data> as a 32 bit word into the file selected by
  1220. <handle>, it is written lsb first. 
  1221.  
  1222.  
  1223. Command : getw                  DISABLED ON DEMO VERSION
  1224. Type    : command / filing
  1225. Arguments       :  <handle>
  1226. Returns :  <data>
  1227. Description
  1228. getw will read 4 bytes from the file selected by <handle> and push them
  1229. onto the stack as a 32 bit word.  The bytes are read lsb first. 
  1230.  
  1231. Command : eof                   DISABLED ON DEMO VERSION
  1232. Arguments       : <handle>
  1233. Returns : <status>
  1234. Description
  1235. returns 1 if end of file <handle> has been reached, -1 if a read has
  1236. occurred past the end of file and 0 otherwise. 
  1237.  
  1238. Command : save                  DISABLED ON DEMO VERSION
  1239. Type    : command / HOST image dump 
  1240. Arguments       :  
  1241. Returns :  
  1242. Description
  1243. This command creates a file called image in the current directory that
  1244. is a mirror image of the state of the forth machine when the command was
  1245. typed.  This does not include stacks or multitasking status - just the
  1246. dictionary. 
  1247.  
  1248. Command : oscli                 DISABLED ON DEMO VERSION
  1249. Type    : command / HOST 
  1250. Arguments       : <string> 
  1251. Returns :  
  1252. Description
  1253. <string> is in '(' format and is passed unmodified to the operating
  1254. system. 
  1255.  
  1256. Command : vdu
  1257. Type    : command / IO / graphics 
  1258. Arguments       : <code> 
  1259. Returns :  
  1260. Description
  1261. The <code> will be sent to the vdu drivers - this command is similar to
  1262. echo. 
  1263.  
  1264. Command : plot
  1265. Type    : command / IO / graphics 
  1266. Arguments       : <code> <x> <y> 
  1267. Returns :  
  1268. Description
  1269. This command will pass the stack entries to the vdu drivers, it assumes
  1270. that the correct number of stack entries is present.  If not then the
  1271. stack will underflow and indeterminate data will be passed to the
  1272. drivers. 
  1273.  
  1274. Command : colour
  1275. Type    : command / IO / graphics 
  1276. Arguments       : <colour> 
  1277. Returns :  
  1278. Description
  1279. passes the following control codes to the vdu drivers.  17 <colour> to
  1280. select the text colour.  vdu could be used but is less efficient. 
  1281.  
  1282. Command : gcol
  1283. Type    : command / IO / graphics 
  1284. Arguments       :  <effect> <colour>
  1285. Returns :  
  1286. Description
  1287. used to select the type of plotting performed by the graphics commands.
  1288.  
  1289. Command : ;
  1290. Type    :  compile mode terminator
  1291. Arguments       :  
  1292. Returns :  
  1293. Description
  1294. semi-colon is used to terminate the definition of a new word, it exits
  1295. from compile mode and enters execution mode.  It writes the address of
  1296. the interpreter routine semi into the dictionary and advance the pointer
  1297. by 4. 
  1298.  
  1299. Command : ;code 
  1300. Type    : compile mode terminator
  1301. Arguments       :  
  1302. Returns :  
  1303. Description
  1304. semi-colon-code is used to terminate a forth word definition and
  1305. encloses the address of the hidden routine scode in the dictionary. 
  1306. Machine code or assembler follows the statement and will be executed
  1307. when the defined keyword is invoked. 
  1308.  
  1309. Command : end 
  1310. Type    : compiler directive / flow control
  1311. Arguments       : <entry>
  1312. Returns :  
  1313. Description
  1314. End is used to terminate a begin end construct.  The address on the
  1315. stack was the value of the dictionary pointer when begin was executed. 
  1316.  
  1317. Command : end, 
  1318. Type    : compiler / definitions
  1319. Arguments       :  <entry> <entry>
  1320. Returns :  
  1321. Description
  1322. encloses the address of the program control directive in the dictionary,
  1323. computes the relative jump value and writes it in the dictionary.  Used
  1324. in defining new compiler keywords. 
  1325.  
  1326. Command : else 
  1327. Type    : compiler / flow control
  1328. Arguments       :  <entry>
  1329. Returns :  <entry>
  1330. Description
  1331. else encloses the address of the control directive in the dictionary,
  1332. calculates the value of the relative jump and saves the current value of
  1333. the dictionary on the stack.  Used as part of an if..else..then clause. 
  1334.  
  1335. Command : then 
  1336. Arguments       :  <entry>
  1337. Returns :  
  1338. Description
  1339. pops the stack, computes the difference between the address and the
  1340. current values of the dictionary pointer and store the value in the
  1341. dictionary. 
  1342.  
  1343. Command : do 
  1344. Arguments       :  <start> <end>
  1345. Returns :  
  1346. Description
  1347. encloses the address of the control direct in the dictionary and pops
  1348. the top two entries from the data stack and pushes them onto the return
  1349. stack. 
  1350.  
  1351. Command : do, 
  1352. Type    : compiler / flow control
  1353. Arguments       : <entry>
  1354. Returns :  <entry>
  1355. Description
  1356. stores the top stack entry in the dictionary and pushes the new value of
  1357. the dictionary pointer to the stack. 
  1358.  
  1359. Command : if 
  1360. Type    : compiler / flow control
  1361. Arguments       :  
  1362. Returns :  <entry>
  1363. Description
  1364. stores the address of the control directive in the dictionary, reserves
  1365. the next word in the dictionary and pushes its address to the stack. 
  1366.  
  1367. Command : while 
  1368. Type    : compiler / flow control
  1369. Arguments       :  <entry> <entry>
  1370. Returns :  
  1371. Description
  1372. encloses the address of the control directive in the dictionary, the
  1373. difference between the second stack entry and the dictionary pointer is
  1374. calculated and enclosed as the jump offset, it also writes this offset
  1375. into the address pointed to by the top stack entry. 
  1376.  
  1377.  
  1378. Command : loop 
  1379. Type    : compiler / flow control
  1380. Arguments       :  <entry>
  1381. Returns :  
  1382. Description
  1383. encloses the address of the control directive in the dictionary and
  1384. calculates the difference between <entry> and the current dictionary
  1385. pointer.  It then encloses this offset in the dictionary as the jump
  1386. offset. 
  1387.  
  1388. Command : +loop 
  1389. Type    : compiler / flow control
  1390. Arguments       :  <entry>
  1391. Returns :  
  1392. Description
  1393. encloses the address of the +loop control directive in the dictionary,
  1394. and then does the same as loop. 
  1395.  
  1396. Command : leave 
  1397. Type    : compiler / flow control
  1398. Arguments       :  
  1399. Returns :  
  1400. Description
  1401. encloses the address of the control directive in the dictionary.
  1402.  
  1403. Command : begin 
  1404. Type    : compiler / flow control
  1405. Arguments       :  
  1406. Returns :  <entry>
  1407. Description
  1408. pushes the address of the next dictionary location to the stack.
  1409.  
  1410. Command : [ 
  1411. Type    : compiler / string output
  1412. Arguments       : 
  1413. Returns :  
  1414. Description
  1415. encloses the address of the control directive in the dictionary and then
  1416. tokenises the characters up to the next ] into the dictionary space. 
  1417. When the [ is executed the string between the left and right brackets []
  1418. will be echo directly to the screen. 
  1419.  
  1420. Command : { 
  1421. Type    : compiler / string output
  1422. Arguments       :  
  1423. Returns :  <string>
  1424. Description
  1425. encloses the address of the control directive in the dictionary and
  1426. tokenises the buffer up to the next } into the dictionary space.  When
  1427. then { is executed it will push the string between the left and right
  1428. brackets {} onto the stack ( similar to the () in execute mode ). 
  1429.