home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / forth / compiler / fpc / doc / chapter9.txt < prev    next >
Text File  |  1989-10-29  |  23KB  |  529 lines

  1. CHAPTER 9.   ADVANCED UTILITIES
  2.  
  3.  
  4.  
  5.  
  6.  
  7. 9.1.    REBUILDING THE SYSTEM
  8.  
  9.  
  10. If you need to change a parameter or function in the F-PC system, you
  11. will need to re-compile F- PC and/or KERNEL.  This is simply done with
  12. the provided batch files as follows:
  13.  
  14.         C> FMETA <enter>        Re-compiles KERNEL.COM
  15.         C> EXTEND <enter>       Re-extends to create F-PC.EXE
  16.  
  17. Either of these may be performed from the keyboard while in DOS.  FMETA
  18. invokes F-PC, loads the meta compiler, and recompiles the kernel.  The
  19. resulting new kernel is stored back as KERNEL.COM.  Utilities and
  20. applications are then compiled on the top of KERNEL by EXTEND to generate
  21. a new F-PC system.
  22.  
  23. To extend the F-PC system with your application, edit the F-PC.SEQ file
  24. to include FLOAD instructions to load your application files.  You may
  25. want to change the name of the EXE file finally saved.  This can be done
  26. by editing the filename after the SAVE-EXE statement in F- PC.SEQ file.
  27.  
  28. Meta compilation the the darkest art in Forth.  Do not be fooled by the
  29. above simple discussions to think that meta compilation can be practiced
  30. easily.  You have to understand F-PC completely to made modifications in
  31. the kernel files to rebuild a Forth to your own liking.  Only Tom Zimmer
  32. is entrusted to make modification to F-PC.  Nevertheless, you have all
  33. the source code and the tools to roll your own Forth in F-PC.
  34.  
  35.  
  36. 9.2.    TURNKEY SYSTEMS
  37.  
  38.  
  39. The word TURNKEY and some associated words are included in the file
  40. SAVESYS.SEQ. TURNKEY is used as follows:
  41.  
  42.         ' MYAPPL IS DEFAULT TURNKEY MYAPP <enter>
  43.  
  44. After completing an application compile, the word MYAPPL is defined to be
  45. performed by the program name MYAPP.COM.  TUNRKEY automatically sets up
  46. the proper memory management to allocate 64k for your program, but does
  47. not save the heads.  Minimum initialization is performed.  A file
  48. specified on the command line will be opened, and you can use BL WORD to
  49. pick up additional parameters from the command line.  You will of course
  50. not be able to interpret, since heads are not saved, and your application
  51. will need to handle all errors and return to DOS when the program
  52. completes.
  53.  
  54. Before attempting to build an application, you will need to make a copy
  55. of F-PC.SEQ, for customization.  Many of the later files in F-PC.SEQ are
  56. utilities, and will not be needed in your application. Start by writing
  57. your program and compiling it on F-PC.EXE.  Work in this environment
  58. until you are sure your program works.  Now insert your program filename
  59. into the copy of F-PC.SEQ you made, about half way down, and try to
  60. compile the copy of F-PC.SEQ.  If it compiles then you can move your
  61. application file lower, until you have determined what utilities are
  62. needed by your application. Strip out all files above your application
  63. file, and load the file SAVESYS.SEQ.  Use TURNKEY as previously described
  64. to make an executable .EXE file.
  65.  
  66. TURNKEY allow you to customize F-PC to build an independent application,
  67. which may not allow the user to see the internal of the application.  If
  68. you are not so protective, a more convenient way to generate an
  69. application is to use FSAVE, which saves the core image of F-PC after you
  70. have loaded your application.  F-PC is included inside your application
  71. and the user have access to the entire system.  This is a useful tool as
  72. you can make a snapshot of your current system, save it to the disk, and
  73. have it available the next time you resume your work.  The commands are:
  74.  
  75.         FSAVE  MYSYSTEM <return>
  76.  
  77. A file MYSYSTEM.EXE is saved in your current directory which contains
  78. everything you compiled so far.  Next time when you execute MYSYSTEM
  79. under DOS, your current system will be loaded and F-PC will be at your
  80. service.
  81.  
  82.  
  83. 9.3.    MACROS IN F-PC AND SED
  84.  
  85.  
  86. A file called MACROS.SEQ is provided,.  This file implements keyboard
  87. macros in Forth at the level of KEY.  These macros can therefore be used
  88. in the editor also.  The macros are used as follows: (the sequence
  89. "Alt-M" means hold down the "Alternate" key and press the "M" key.)
  90.  
  91.         Alt-M           Start defining a macro.
  92.         Alt-1           We are defining the Alt-1 macro.
  93.  
  94. Enter any keys you want in the macro, up to 128 keys. 
  95.  
  96.         Alt-M           Complete the definition of the Alt-1 macro.
  97.  
  98. Any keys available on the keyboard except Alt-m, and Alt-1 to Alt-5 can
  99. be included within a macro.  To execute a macro, simply type its key
  100. name:
  101.  
  102.         Alt-1           Execute the macro key sequence for the Alt-1 key.
  103.  
  104. Currently macros may be only 127 characters in length, although this can
  105. be changed by modifying the constant MAXMAC and recompiling the system.
  106. See the example in Appendix B-3.
  107.  
  108.  
  109. 9.4.    F-PC PREFERENCES
  110.  
  111.  
  112. While F-PC may seem like a nebulous glob of stuff, some things about it
  113. can be adjusted fairly simply.  The install process, for example, allows
  114. you to tell F-PC where its source file will be located, whether you want
  115. to have backup copies made of your edited files, and what you want to
  116. call your installed version of F-PC.  There are however a number of other
  117. things you might like to adjust to your personal way of doing things.
  118. Here is a list:
  119.  
  120. The status line display may be turned on/off.
  121.  
  122.         STATON          Enable status line display at top of screen.
  123.         STATOFF         Disable status line display.
  124.  
  125. The decompile display during debugging may be turned on/off.
  126.  
  127.         SRCON           Source display enabled during debug.
  128.         SRCOFF          Source display disabled during debug.
  129.  
  130. The default file extension for the system and the file specification
  131. string for the popup window file selector may be changed.
  132.  
  133.         DEFEXT          Default file extension string.
  134.         HIDDEN DIRSPEC$ Directory specification for popup window.
  135.  
  136. The format of date printing can be adjusted to one of the three supported
  137. formats, or you can add your own.
  138.  
  139.         M/D/Y           Month/Day/Year (default format)
  140.         Y-M-D           Year-Month-Day
  141.         D.M.Y           Day.Month.Year
  142.  
  143. You can manually turn editor backups on or off without going through the
  144. install process.
  145.  
  146.         BACKUPOFF       Disables the editor from making backup files.
  147.         BACKUPON        Enables the keeping of editor backup files.
  148.  
  149. F-PC will automatically save any changes you made to a file you are
  150. editing, if you stop touching the keyboard for 10 minutes.
  151.  
  152.         AUTOSAVEON      Turn on auto save.
  153.         AUTOSAVEOFF     Stop auto save.
  154.         AUTOSAVE-MINUTES  Value of minutes to wait before saving.
  155.                         Default is 10.
  156.  
  157. Screen display output can be switched between DOS and Direct Video output
  158. for all screen text display.
  159.  
  160.         FAST            Direct video screen write for all displayed text.
  161.         SLOW            Use DOS for all screen display.
  162.  
  163. F-PC defaults to automatically entering the editor when an error is
  164. encountered during a file load. You can control this with the following
  165. words.
  166.  
  167.         AUTOEDITON      Automatically enter editor on load error.
  168.         AUTOEDITOFF     Don't enter editor on load error.
  169.  
  170. When an error occurs, the base for number conversions will be change back
  171. to DECIMAL.  This feature can be turn off so that the base is not affect
  172. by errors.
  173.  
  174.         DECIMALBASE     Change to DECIMAL after an error.
  175.         HEXBASE         Change to HEX after an error.
  176.         NOBASE          Do not change base on error.
  177.         DEFBASE         A value to restore base.  0 for NOBASE, 10 for
  178.                         DECIMAL and 16 for HEXBASE.  User can choose his
  179.                         default base here.
  180.  
  181. If you are using a CGA (Color Graphics Adapter) type of video display
  182. board, you will probably want to use BLANKON to reduce the amount of snow
  183. or sparkle on your screen.  This word causes the screen to be blanked
  184. while text is being written to the display to reduce this effect. These
  185. words have no effect on monochrome display adapters. Use BLANKOFF for an
  186. EGA or VGA adapter.
  187.  
  188.         BLANKON         Enable screen blanking during text output.
  189.         BLANKOFF        Disable screen blanking during text output.
  190.  
  191. Most green or amber monochrome monitors display light characters on a
  192. dark background.  If you have a color monitor or true white on black
  193. monitor you may want to reverse foreground and background, giving a page
  194. white look with dark characters on a white background.  I have found this
  195. to be more comfortable for my own use.  You might also try the
  196. BLACK-ON-WHITE mode with an Liquid Crystal or Florescent display.
  197.  
  198.         WHITE-ON-BLACK          Normal, light chars on dark background.
  199.         BLACK-ON-WHITE          Invert the screen to dark on light.
  200.  
  201. With a color monitor, F-PC can display different classes of words in
  202. different color.  It is a very interesting demonstration to impress
  203. novice programmers when executing WORDS, SEE, or DBG.  It is probably not
  204. very useful in normal programming because you cannot see very well words
  205. in blue and light grey.
  206.  
  207.         COLORIZEON      Turn on colors in word list.
  208.         COLORIZOFF      Go back to work
  209.  
  210. The number of screen F-PC will save on its screen stack if adjustable
  211. within the range 1 to 14. SVSIZE bytes (~4000) are allocated for each
  212. screen stacked. F-PC needs SVMAX to be at least three (3) for all of the
  213. existing utilities to function properly.
  214.  
  215. SVMAX is a "VALUE" that can be changed with "=:". You will only need to
  216. do this if you write a program that needs to stack screens more than the
  217. default number of screen deep.
  218.  
  219.         5 =: SVMAX      \ increase number of buffers to 5
  220.         FSAVE F <enter> \ resave the system
  221.         BYE             \ leave after changing and saving
  222.         F <enter>       \ now the screen stack is 5 deep.
  223.  
  224. Your preferences can be edited into the configuration file F-PC.CFG.
  225. This file is executed by F- PC immediately after it is loaded into
  226. memory.  Only a few of the preferences were included into the
  227. configuration file during the installation/configuration process, and
  228. most preferences were set to default choices.  In the hypertext root
  229. screen, a link item 'Preferences' is available for you to see all the
  230. possible choices on-line.
  231.  
  232.  
  233. 9.5.    TASK CHAINING
  234.  
  235.  
  236. Tom Zimmer developed a very powerful technique by which more functions
  237. can be added to a word as the needs grow.  He called it background task
  238. chaining.  The idea is to use a DEFERred word as a basis.  Some time
  239. later this deferred word is resolved to do one task.  We can add some
  240. more tasks to this word by defining a new word and compiling the contents
  241. of the deferred word into the new word with other functions.  The
  242. deferred word is then re-vectored to the new definition.  When the
  243. deferred word is executed, new functions are added to the old task.  This
  244. task chain can thus be extended to your heart's desire.  The words
  245. involved in task chaining are:
  246.  
  247.         DEFER  <name>
  248.  
  249. to define a deferred word whose function can be changed by re-vectoring,
  250. and
  251.  
  252.         DEFERS  <name>
  253.  
  254. an immediate compiler word which compiles the contents of the next
  255. deferred word in a colon definition.  It allows many functions to be
  256. added to the deferred word.
  257.  
  258.  
  259. In F-PC, KEY is a user deferred word.  We have to use DEFERS to extend
  260. its function. BGSTUFF is a regular deferred word to extend functions like
  261. the status line display.  BYESTUFF is used to extend the cleaning up task
  262. before F-PC exits to DOS.  Let's use BGSTUFF as an example:
  263.  
  264.         DEFER BGSTUFF
  265.         ' NOOP IS BGSTUFF
  266.         : (KEY?)
  267.                 DEFERS BGSTUFF
  268.                 { the words to do (KEY?) }
  269.                 ;
  270.  
  271.         ' (KEY?) IS BGSTUFF             \ BGSTUFF = (KEY?)
  272.         : TIME
  273.                 DEFERS BGSTUFF
  274.                 #OUT @   #LINE @        \ save cursor position
  275.                 64 0 AT .TIME           \ print time at upper-right corner
  276.                 AT                      \ restore cursor
  277.                 ;
  278.         ' TIME IS BGSTUFF               \ BGSTUFF = (KEY?) + .TIME
  279.  
  280. This technique allows you to dynamically change the behavior of a
  281. deferred word while keeping most of its old functionality.  As the system
  282. grows, it is easier to add new functions to an existing word than to
  283. define new words and mess up the existing environment.
  284.  
  285.  
  286. 9.6.    CONTROL STRUCTURE ENHANCEMENTS
  287.  
  288.  
  289. Bill Muench contributed a modified set of control structures.  The
  290. changes are very very minor, but result in a significant increase in
  291. versatility.  The change is effectively to move a 2SWAP from the
  292. beginning of REPEAT and put it at the end of UNTIL.  Some additional
  293. words have also been added to take advantage of the increased
  294. versatility.  The changes have been added to the system, the meta
  295. compiler, and the assembler.
  296.  
  297. Some possible combinations of the structures are shown in the following
  298. cases.  However, the possible combinations are only limited by your
  299. imagination.
  300.  
  301. WHILE can be used to exit a DO...LOOP conditionally.  The WHILE structure
  302. can be nested.
  303.  
  304.         DO ...
  305.                 WHILE ...
  306.                         WHILE ...
  307.         LOOP ...
  308.                         ELSE UNDO ...   \ drop or use index and limit
  309.                         THEN ...
  310.                 ELSE UNDO ...           \ drop or use index and limit
  311.                 THEN
  312.  
  313. A normal BEGIN..WHILE..REPEAT loop behaves like it always did:
  314.  
  315.         BEGIN ...
  316.         WHILE ...                       \ normal structure
  317.         REPEAT
  318.  
  319. CONTINUE allows a conditional branch back to BEGIN:
  320.  
  321.         BEGIN ...
  322.                 IF ...
  323.                 CONTINUE ...            \ now branch back to begin
  324.         UNTIL                           \ otherwise, conditionally branch
  325.  
  326.  
  327. WHILE can also leave a BEGIN..UNTIL loop conditionally.
  328.  
  329.         BEGIN ...
  330.                 WHILE ...               \ multiple exit tests
  331.         UNTIL ...
  332.                 ELSE ...                \ and possibly different action
  333.                 THEN
  334.  
  335. WHILE can also be nested in a BEGIN..UNTIL loop.
  336.  
  337.         BEGIN ...
  338.                 WHILE ...               \ multiple exit tests
  339.                         WHILE ...       \ multiple exit tests
  340.         UNTIL ...
  341.                         ELSE ..         \ and possibly different action
  342.                         THEN ...
  343.                 ELSE ...                \ and possibly different action
  344.                 THEN
  345.  
  346. AFT..THEN structure can be nested inside BEGIN..WHILE..REPEAT loop.  The
  347. clause inside AFT..THEN is executed only once in the first looping.
  348.  
  349.         BEGIN ...
  350.                 AFT ...                 \ executed only once
  351.                 THEN ..                 \ ignored afterwards
  352.         WHILE ...
  353.         REPEAT
  354.  
  355. The FOR...NEXT structure was proposed by Chuck Moore in the cmForth for
  356. the Novix NC4000 Forth chip.  FOR takes a count from the data stack and
  357. pushes it onto the return stack.  NEXT decrements the count on the return
  358. stack.  If the count becomes zero after being decremented, the loop is
  359. terminated; otherwise, the loop is repeated.
  360.  
  361. The FOR...NEXT loop can also use WHILE to exit conditionally:
  362.  
  363.         FOR ...
  364.                 WHILE ...               \ in effect an immediate ?leave
  365.         NEXT ...
  366.                 ELSE ... R> ( DROP )    \ drop or use the loop index
  367.                 THEN
  368.  
  369. AFT..THEN structure can also be nested in a FOR..NEXT loop.
  370.  
  371.         FOR ...
  372.                 AFT ...                 \ this is only executed the first
  373.                                         \ time through the loop
  374.                 THEN ...                \ this is executed every time
  375.         NEXT
  376.  
  377. Another way to exclude the n=0 case and also have the loop execute n
  378. times, but is longer and slower specifically on a FORTH machine like the
  379. NC4000 or Harris RTX.
  380.  
  381.         ( n ) ?DUP IF 1- FOR ... NEXT ... THEN
  382.  
  383. BREAK allows the construction of a case structure in a colon definition:
  384.  
  385.         ... IF ... BREAK                \ case like structure
  386.         ... IF ... BREAK                \ break compiles an exit
  387.         ... IF ... EXIT THEN            \ same as break
  388.  
  389.  
  390. 9.7.    HEADLESS WORDS
  391.  
  392.  
  393. This is a neat utility from George T. Hawkins to allow the extraction and
  394. removal of the unwanted heads in the Forth system and any application you
  395. may write in F-PC.
  396.  
  397. Any words to be later beheaded are identified with a "HEADERLESS"
  398. keyword.  This is followed by the colon definitions or code words
  399. themselves.  You re-establish standard words (i.e., words with headers)
  400. with the keyword "HEADERS".
  401.  
  402. When you have finished your use/referencing of headerless words, you then
  403. use the keyword: "BEHEAD".  This will completely remove the definition of
  404. any headerless words from the directory.
  405.  
  406. Once headerless words are BEHEADed they are lost forever; i.e., their
  407. code and list space is not lost - but they are unknown so far as the
  408. dictionary is concerned.  Note that you cannot ever reference a
  409. HEADERLESS word once it is BEHEADed.  So the logic to using HEADERLESS
  410. words is as follows:
  411.  
  412.         ONLY FORTH ALSO EDITOR ALSO HIDDEN \ set up search order as needed
  413.         HEADERLESS
  414.         ...                                \ put headerless words here
  415.         HEADERS
  416.         ...                                \ put words which reference
  417.                                            \ the previous group of
  418.                                            \ headerless words here
  419.         EDITOR DEFINITIONS                 \ switch to EDITOR vocabulary
  420.                                            \ but don't change order.
  421.                 \ repeat above sequence of:
  422.                 HEADERLESS              \ Turn off heads in editor vocabulary
  423.                         ... <words> ...
  424.                 HEADERS                 \ Turn heads back on
  425.                         ... <words> ...
  426.         HIDDEN DEFINITIONS              \ switch to HIDDEN vocabulary but don't
  427.                                         \ change order.
  428.                 \ as desired
  429.         BEHEAD
  430.  
  431. Although the use of headerless words can save you head space, their main
  432. advantage is in the software engineering they provide.  That is, the
  433. definitions/names are *completely lost* not just stashed away in some
  434. obscure vocabulary.  (If you attempt to "see" or "debug" headerless words
  435. through regular words you get a garbage ID.)
  436.  
  437. In general you should set up your {HEADERLESS/HEADERS}/ BEHEAD
  438. definitions as described above, but precede it with a single "HWORDS-".
  439. HWORDS- will cause HEADERLESS, HEADERS, and BEHEAD to be treated as
  440. noops.  Once you've finished debugging and are ready to go to production,
  441. then change "HWORDS-" to "HWORDS+".  This will give the HEADERLESS,
  442. HEADERS, and BEHEAD words their standard meaning.  If you ever need to
  443. debug the code again, and want to see the names, then change HWORDS+ to
  444. HWORDS-.
  445.  
  446. As can be seen in the above example, you should setup your vocabulary
  447. search order prior to starting a sequence of definitions in which some
  448. words will be headerless.  After setting the search order, you can still
  449. select different vocabularies in which you place definitions, but you
  450. MUST NOT change the search order, that is you MUST NOT use "ONLY" or
  451. "ALSO".  Also the current vocabulary should not be changed while in
  452. HEADERLESS mode.
  453.  
  454.  
  455. 9.8.    SAVE AND RESTORE
  456.  
  457.  
  458. At times one needs to change various global attributes of the Forth
  459. system while preserving their value to be later restored. An example of
  460. this might be changing CAPS to ON, while saving its current value to
  461. restore later.  Here is a typical code segment to save CAPS, turn it on,
  462. and restore it at later in a definition:
  463.  
  464.         : DEF1  ( --- )
  465.                 CAPS @ >R CAPS ON               \ Save CAPS and turn ON
  466.                 ...
  467.                 use SEARCH for something ...
  468.                 ...
  469.                 R> CAPS !                               \ restore CAPS
  470.                 ;
  471.  
  472. While this is an acceptable way to save and restore a variable, it is
  473. difficult to read, and not particularly efficient in terms of
  474. performance.  A new mechanism has been introduced which enhances
  475. readability, and improves performance at the same time.  Here is an
  476. example of SAVE!> and RESTORE>:
  477.  
  478.         : DEF1  ( --- )
  479.                 TRUE SAVE!> CAPS                \ save and set CAPS
  480.                 ...
  481.                 use SEARCH for something ...
  482.                 ...
  483.                 RESTORE> CAPS                   \ restore CAPS
  484.                 ;
  485.  
  486. These words allow a VARIABLE or VALUE to be saved for later, and set to a
  487. new value for temporary use.  Another word included in the set allows
  488. saving a VARIABLE or VALUE without changing it, for later restoration:
  489.  
  490.         : DEF1  ( --- )
  491.                 SAVE> CAPS                      \ save CAPS
  492.                 ...
  493.                 do something that may change CAPS...
  494.                 ...
  495.                 RESTORE> CAPS                   \ restore CAPS
  496.                 ;
  497.  
  498. The only problem with these words is they cannot be use with user
  499. variables, as they are fairly dumb and fast.  They simply work with the
  500. contents of the body of the definition following.
  501.  
  502.  
  503. 9.9     LINE EDITOR
  504.  
  505.  
  506. F-PC provides a very nice general purpose line editor for use in your
  507. application programs.  It allows you to request a line of input from the
  508. user, while allows him to edit the text before pressing <return> to send
  509. it to the program.  The word to invoke it is LINEEDITOR.  Its usage is as
  510. follows:
  511.  
  512.         20  8  MYBUF   22 LINEEDITOR  ( -- f )
  513.  
  514. In this example, the text buffer will start at column 20 of row 8.
  515. Editing will be performed on the counted string in MYBUF, and the maximum
  516. length allowed is 22 characters.  The line editor is terminated by either
  517. <return> or ESC key.  If the ESC key is pressed than a false boolean flag
  518. is returned; otherwise, a true flag is returned.  A mouse can be used to
  519. position the cursor within the edit line.
  520.  
  521. If the editing is completed with <return>, then the edit string is placed
  522. back into MYBUF.  If the editing is terminated with ESC, then MYBUF will
  523. contain the original string unmodified by any edit operations performed
  524. during the editing session.
  525.  
  526. During editing, you can use the Right arrow, Left arrow, Home, End, and
  527. Delete keys to position the cursor to edit the string.
  528.  
  529.