home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / pascal / interpre / vclang / vc.doc < prev    next >
Text File  |  1990-08-17  |  11KB  |  280 lines
  1.  
  2.            VisiCLANG  --  A Visible Compiler for CLANG
  3.            ===========================================
  4.            v1.00  (C)Copyright 1990, Univ. of Limerick
  5.  
  6. INTRODUCTION
  7. ------------
  8.  
  9. VisiCLANG is a tool to aid one in understanding the inner
  10. workings of a compiler. It does this by allowing the user to
  11. trace all aspects of a compiler's execution as it is compiling
  12. the user's own program(s). Assembly language code is generated by
  13. the compiler and then executed on an stack machine implemented in
  14. software. 
  15.  
  16. CLANG is a simple teaching language developed by P.D. Terry and
  17. described by him as a "superset of a subset of Pascal". It limits
  18. it's data types to integers and arrays of integers, but includes
  19. data abstraction and concurrency. The CLANG compiler uses straight-
  20. forward recursive-descent parsing implemented in "highly standard
  21. Pascal".
  22.  
  23. CLANG (and the stack machine) is developed and explained in the
  24. book "Programming Language Translation" by P.D. Terry (Addison-
  25. Wesley, 1986). Level 5 of CLANG is used in VisiCLANG, and the
  26. source code corresponds exactly with the listing given by Terry
  27. in his book (pp. 379-411 ... or it can be written to a file from
  28. within VisiCLANG). We recommend Terry's book for in-depth study
  29. of CLANG and/or the stack machine. See also SIGPLAN Notices V25
  30. #8, August 1990, for a general description of the compiler.
  31.  
  32. (A version of VisiCLANG for Level 2 of CLANG is also available;
  33. contact the authors for more information.)
  34.  
  35. MODES OF OPERATION
  36. ------------------
  37.  
  38. There are two distinct modes of operation for VisiCLANG: compile
  39. mode and execute mode. Compile mode allows the user to view a
  40. program being compiled and, if compilation is successful, to save
  41. the resultant code; execute mode allows the user to view the com-
  42. piled program being executed on the stack machine (SM). Both
  43. modes can be used independently of the other -- you need not
  44. execute your compiled program and you can execute previously
  45. saved SM code without re-compiling the source.
  46.  
  47. RUNNING VisiCLANG
  48. -----------------
  49.  
  50. Usage: vc [options]
  51.  where options are:
  52.    <file>     -- select compile mode and input CLANG file
  53.    /e[<file>] -- select execute mode and input SM code file
  54.    /h         -- help
  55.  
  56.  (anything delimited by [ ] denotes an optional part of a
  57.   command)
  58.  
  59. COMPILE MODE
  60. ------------
  61.  
  62. When first entering Compile Mode the user is prompted for the
  63. name of an input file. This is the CLANG program which is to be
  64. compiled, and it is used for all subsequent operations unless the
  65. user specifies otherwise.
  66.  
  67. There are six primary windows in compile mode. These are:
  68.  
  69.    CLANG     Shows CLANG compiler source code, with the line
  70.              about to be executed highlighted.
  71.  
  72.    Input     Shows the user's CLANG source code file as seen by
  73.              the compiler -- one line at a time is read into a
  74.              buffer and then an arrow in the window indicates
  75.              exactly where the lexical analyzer is scanning in
  76.              the buffer.
  77.  
  78.    Code      Shows the SM code as it is generated.
  79.  
  80.    Grammar   Shows the trace through the CLANG grammar as it's
  81.              compiling your code. A parse tree can be built by
  82.              following highlighted elements down through the
  83.              window. The meta-language used is slightly modified
  84.              EBNF:
  85.  
  86.               (1) The meta-symbols < > are used to denote non-
  87.                   terminals (exception: the relational 
  88.                   operators).
  89.               (2) The symbol ::= should be read "is defined as"
  90.               (3) The vertical bar | should be read "or"
  91.               (4) Curly braces { } are used to denote repetition
  92.                   of a string 0 or more times.
  93.               (5) Square brackets [ ] are used to denote an
  94.                   optional item.
  95.               (6) The meta-symbols << >> are used to denote
  96.                   certain terminals.
  97.               (7) Null productions are indicated by NULL.
  98.               (8) Symbols and words with none of the above punc- 
  99.                   tuation are terminals.
  100.  
  101.    Procedure
  102.    List      Traces the calls to procedures in the parser that
  103.              correspond to non-terminals in the grammar
  104.  
  105.    Variable  This is a pop-up window that allows the user to
  106.              watch any of the compiler's variables (with the
  107.              hopefully obvious restriction that you are current- 
  108.              ly executing within the scope of the variable you
  109.              wish to watch). 
  110.  
  111.  
  112. EXECUTE MODE
  113. ------------
  114.  
  115. If execute mode is entered immediately after a successful
  116. compilation, the code generated by the previous compilation will
  117. be executed. Otherwise the user is prompted for the name of a
  118. code file.
  119.  
  120.  Execute mode has seven main windows:
  121.  
  122.    CLANG    As with Compile mode, shows the CLANG source, with
  123.             the line about to execute highlighted.
  124.  
  125.    Input/
  126.    Output   I/O window for program currently executing.
  127.  
  128.    Code     The complete SM program listing, with the next
  129.             instruction to be executed highlighted.
  130.  
  131.    Stack    Shows the SM's stack (with the first column being the
  132.             address, column 2 the contents). The base and top-of-
  133.             stack "pointers" are indicated with appropriate
  134.             symbols.
  135.  
  136.    Display  CLANG uses a display to handle variable addressing;
  137.             this window shows the current state of this display.
  138.  
  139.    Source   Shows a traces through the CLANG source as the
  140.             program is being executed; this window is not active
  141.             if you are executing SM code that has been directly
  142.             loaded in from a file.
  143.  
  144.    Variable (Same as in compile mode)
  145.  
  146. COMMANDS
  147. --------
  148.  
  149. The following function keys can be used in either mode:
  150.  
  151.      F1  Help 
  152.      F2  Search (searches for a string in the CLANG compiler
  153.          source)
  154.      F3  Goto line (in the CLANG compiler source code)
  155.      F4  Goto start (begin compiling your CLANG or SM source
  156.          program; necessary only if you wish to re-start compila-
  157.          tion/execution)
  158.      F5  New source file (choose a different CLANG/SM source
  159.          program & begin compilation/execution)
  160.      F6  Variables window (selects the variables window; user
  161.          will be prompted to add a variable if none have yet been
  162.          chosen)
  163.      F7  Cycle windows (cycles through screen windows; a window
  164.          must be selected before it is modified, with double-line
  165.          borders indicating the currently selected window.)
  166.      F8  Modify window (allows you to modify (move,resize,etc.)
  167.          the currently selected window)
  168.      F9  Switch modes (switches between compile & execute modes)
  169.     F10  Main menu
  170.  
  171.  
  172. VisiCLANG allows you to watch different aspects of the compila-
  173. tion/execution process at different rates as you step through
  174. source code. The following keys can be used in this process:
  175.  
  176.             (CM -- compile mode; EM -- execute mode)
  177.  
  178. <space bar>   Single step through the CLANG compiler(CM) or
  179.               interpreter(EM) source code
  180.           B   Go until breakpoint; pressing B with no breakpoints
  181.               will cause VisiCLANG to attempt to compile(CM) or
  182.               execute(EM) your entire program
  183.           C   Go until code generated (CM) or executed(EM);
  184.               (CM -- compilation will continue until the next SM
  185.               instruction is generated; EM -- will single-step
  186.               you through the SM code)
  187.           G   Go until grammar change; compilation will continue
  188.               until the grammar window is updated (CM only)
  189.           T   Go until next token; compilation will continue
  190.               until the next token is returned by the lexical
  191.               analyzer (CM only)
  192.           P   CM -- Go until procedure end; compilation continues
  193.                     until you reach the end of the last procedure
  194.                     listed in the Procedure List window
  195.               EM -- Show process list (if applicable)
  196.  
  197.           >   Add breakpoint; places a breakpoint on the current
  198.               line (the one highlighted) in the CLANG com-
  199.               piler(CM) or interpreter(EM) source.
  200.           <   Clear breakpoint; removes the breakpoint on the
  201.               current line in the CLANG compiler(CM) or inter-
  202.               preter(EM) source.
  203.           A   Clear all breakpoints (in the CLANG compiler(CM) or
  204.               interpreter(EM) source)
  205.  
  206.      V or +  Add variable; prompts you for the name and then
  207.              adds a variable to the variable watch window
  208.           -  Delete variable; deletes highlighted variable from
  209.              the watch variable window; variables can be high-
  210.              lighted by first selecting the variable window (F6)
  211.              and then using the up/down arrow keys 
  212.           H  Hide variable window; "hides" or closes variable
  213.              window (note that F6 will re-open it)
  214.           Z  Zap variable window; removes all variables from
  215.              variable window
  216.           S  Show symbol table (CM only)
  217.  
  218.     <Ctrl>L  Repeat last search (initial search done with F2)
  219.           F  Trace CLANG toggle; when on, the next line to be
  220.              executed in the CLANG compiler(CM) or interpreter
  221.              (EM) will be highlighted (turning Trace off will
  222.              noticeable speed up VisiCLANG)
  223.           K  Pause on token toggle; when on, VisiCLANG will pause
  224.              whenever a token has been recognized (CM only)
  225.           D  Set Delay; allows you to control the speed at which
  226.              the compiler will run (delays are inserted after
  227.              each line of CLANG executed)
  228.  
  229.           Q  Quit VisiCLANG
  230.  
  231.  
  232. The following keys are available whenever a scrolling window has
  233. been selected:
  234.  
  235.   <up arrow>/<down arrow>  Scroll up/down one line
  236.   <PgUp>/<PgDn>            Scroll up/down one screen
  237.   <Home>/<End>             Scroll to start/end of window
  238.  
  239. Note that if a window is too small to show an entire line, the
  240. size of the window can be modified using F8.
  241.  
  242.  
  243. FILES ON DISK
  244. -------------
  245.  
  246. read.me    special instructions
  247. vc.exe     VisiCLANG executable
  248. vc.ov*     VisiCLANG overlay files (do not delete!)
  249. vc.cfg     VisiCLANG configuration file (stores status of
  250.            VisiCLANG upon exit from program; deletion or renaming
  251.            will cause VisiCLANG to begin with default set-up)
  252. vc.doc     this document
  253. *.cln      CLANG source code files
  254. *.cod      SM source code files
  255.  
  256.  
  257. TERMS AND CONDITIONS OF USE
  258. ---------------------------
  259.  
  260. YOU MAY FREELY COPY AND DISTRIBUTE VERBATIM COPIES OF VISICLANG
  261. AS LONG AS YOU ALSO DISTRIBUTE ALL COPYRIGHT NOTICES AND DIS-
  262. CLAIMERS OF WARRANTY. THE PROGRAM IS DISTRIBUTED "AS IS" WITHOUT
  263. WARRANTY OF ANY KIND -- THE ENTIRE RISK AS TO THE QUALITY AND
  264. PERFORMANCE OF THE SOFTWARE IS WITH THE USER. WHILE WE ENCOURAGE
  265. ANY FEEDBACK AND SUGGESTIONS, FUTURE SUPPORT OF THIS PRODUCT BY
  266. THE AUTHORS OR THE UNIVERSITY IS NOT GUARANTEED.
  267.  
  268.  
  269. Any comments/suggestions/gripes? Here's our address:
  270.  
  271. Dan Resler
  272. Keith O'Sullivan
  273. Dept. of Electronics & Computer Engineering,
  274. University of Limerick,
  275. Limerick, Ireland
  276.  
  277. email: reslerd@ul.ie
  278. phone: Ireland 061-333644
  279. fax  : Ireland 061-330316
  280.