home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / turbopas / t_ref.arc / T-REFCH1.DOC < prev    next >
Text File  |  1987-01-15  |  13KB  |  331 lines
  1.  
  2.  
  3.  
  4.                           Chapter I - About T-Ref
  5.  
  6.      T-Ref is actually two programs combined into a single package.  First, it
  7. is a Source Lister for Borland's Turbo  Pascal programs (versions 2.0 or 3.0).
  8. Of  course,  T-Ref's sophistication for listing the source files is far beyond
  9. just printing the source code.   For example,  along with the source  listing,
  10. you  can specify a line-by-line print-out of the lexical levels and the  block
  11. levels,  the  active procedure or function of that line,  and the line numbers
  12. along with the listing.   Chapter II of this document describes in detail  how
  13. to create a source listing to match your specific needs.
  14.      The  second part of T-Ref is the Cross Reference List,  which was  speci-
  15. fically designed to cross reference Borland's Turbo  Pascal programs.  It will
  16. give  a complete cross reference of all identifiers declared within a  program
  17. or  a  partial  listing (on requested basic types).   The listing  gives  each
  18. identifier's name,  its type, the code line declared on, all lines referencing
  19. the  names,  and the scope (the procedure or function name and level in  which
  20. the identifier was declared within).   Chapter III describes fully how to  get
  21. and interpret a cross reference listing.
  22.      These  two parts were designed to work in tandom:  a few key strokes will
  23. give you either a source listing,  a cross reference listing,  or both. Output
  24. can  be  routed to a specified output file or to the operating  system's  list
  25. device.
  26.  
  27.      T-Ref  is a parsing program,  or simply a parser.   A parser (the  actual
  28. heart of a compiler) performs associations between a program's source code and
  29. the  language's grammar.  This is to say that T-Ref understands  the  language
  30. structure  (or syntax) of Turbo Pascal.   It "scans" the input file for ident-
  31. ifiers  (first for their declarations and then for their uses) and stores  the
  32. references made to them.  However, T-Ref has one limitation in dealing with an
  33. input  program:  it is not designed to recover gracefully from  syntax  errors
  34. found  in the program and continue "scanning" the source.   Therefore,  during
  35. the  scanning process,  if   T-Ref comes across a symbol that does  not  agree
  36. with  any  of  the expected symbols legal for Pascal as defined  by  Borland's
  37. Turbo  Pascal syntax, the parsing process will stop, a cross reference listing
  38. of  the  program parsed up to the time of the error is printed (if  the  cross
  39. reference lister is activated),  the output file will be closed (if it is  not
  40. being  routed to the printer),  and an error message will be displayed on  the
  41. screen  describing the error discovered.   (Turbo does not recover from errors
  42. encountered either!)  It is for this reason that you should always follow
  43.  
  44. ******************************************************************************
  45. T-Ref Rule #1:
  46.  
  47.      Do  not use T-Ref on any program that has not been successfully  compiled
  48. first by Turbo  Pascal.
  49.  
  50. ******************************************************************************
  51.  
  52.      This  brings us to what T-Ref WILL parse.   T-Ref can successfully  parse
  53. any  complete  Turbo  Pascal program or declaration part  of  a  program.  The
  54. declaration  part  of a program may include a sequence of one or more  of  the
  55. following:  label  declarations,  constant  declarations,  type  declarations,
  56. variable  declarations,  procedure  declarations,  and function  declarations.
  57. (Like  Turbo  Pascal,  there is no restrictions on order or frequency of  each
  58. type  of declaration.)  Therefore,  it is possible to parser a set of  library
  59.  
  60.  
  61.                                 1
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. procedures  and  functions placed in a separate file (accessed from  the  main
  71. program  through the include file compiler directive) without having to  parse
  72. any of the possibly many main programs that may use that library.
  73.      If  you are familiar with Turbo  Pascal as well as with Standard  Pascal,
  74. you  are probably aware that Borland has modified their syntax to provide more
  75. flexibility  to Turbo users.   The extensions Turbo has placed on Pascal as  a
  76. language include, but are not necessarily limited to the following:
  77.  
  78.           String Types and String Expressions
  79.           Scalar Type Byte
  80.           Embedded Control Characters within Strings
  81.           Include File Compiler Directives
  82.           Optional Program Heading
  83.           Unrestrictive Ordering of Declaration Parts
  84.           Special Expression Operators (i.e., SHL)
  85.           Inline Statement
  86.           Else Clause Expansion to the Case Statement
  87.           Retype Facility
  88.           Identifier Labels
  89.           Typed Constants
  90.           Text Files
  91.           Untyped Files
  92.           I/O Checking
  93.           Untyped Formal Variable Parameters
  94.           Overlay System
  95.           Absolute Variables
  96.           External Subprograms
  97.  
  98. A cross reference program designed to handle Standard Pascal will not success-
  99. fully handle most of these extensions if the parsing technique is implemented.
  100. However, each of these extensions are handled by T-Ref.
  101.  
  102. The Main Screen:
  103.  
  104.      Almost  all  interactions  you will make with the program  will  be  done
  105. through the main screen which appears when T-Ref begins execution (see  Figure
  106. 1  below).   The  main screen is divided into four major areas:  the file  I/O
  107. fields,  the source lister fields,  the cross reference lister fields, and the
  108. message area (see Figure 2 below).
  109.  
  110.      A. File I/O Fields:
  111.  
  112.      The  File  I/O fields are used to specify the common directory  and  sub-
  113. directories names ("Active Directory"), the name of the file where the program
  114. to  be listed resides ("Active Input File"),  and the name of the output  file
  115. where the resulting listing is to be sent ("Active Output File").  The "Active
  116. Directory" field, when used, refers to the directory common to the input file,
  117. the output file,  and all include files referenced within the input file  (the
  118. program).   The exception to this case is when a file name begins with the "\"
  119. symbol.   This  is  interpreted to mean 'The specified file name includes  the
  120. directory and possible subdirectories for the file's location.'  For  example,
  121. in the following:
  122.  
  123.           Active Directory:   \UTILS
  124.           Active Input File:  WINDOWS.PAS
  125.           Active Output File: \PRINTER\WINDOWS.PRT
  126.  
  127.  
  128.                                 2
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. +============================================================================+
  137. |              T-Ref - Professional Turbo Cross Referencing Program          |
  138. +----------------------------------------------------------------------------+
  139. |     Active Directory:                                                      |
  140. |     Active Input File:                                                     |
  141. |     Active Output File:                                                    |
  142. +====================================+=======================================+
  143. |     Source Listing:        On      |      Cross Reference:     On          |
  144. +------------------------------------+---------------------------------------+
  145. |     Reserve Words:        Upper    |      Labels:             PrgDf   All  |
  146. |     Identifiers:          Lower    |      Constants:          PrgDf   All  |
  147. |     Line Numbers:          On      |      Types:              PrgDf   All  |
  148. |     Lexical Levels:        On      |      Variables:          PrgDf   All  |
  149. |     Block Levels:          On      |      Procedures:         PrgDf   All  |
  150. |     Active Procedures:     On      |      Functions:          PrgDf   All  |
  151. |     Header:                On      |      Header:              On          |
  152. |     Page Numbering:        On      |      Page Numbering:      On          |
  153. |     Include Files:         Yes     |      Include Files:       Yes         |
  154. +====================================+=======================================+
  155. |                                                                            |
  156. |                           Begin Parsing?  No                               |
  157. |                                                                            |
  158. +============================================================================+
  159. |    Primary Key Options ==>         <F1>  <Home>  <End>  <Esc>  _           |
  160. +============================================================================+
  161.  
  162.                          Figure 1. Main Screen
  163.  
  164.  
  165.  
  166.  
  167.      +-------------------------------------------------------+
  168.      |                        File I/O                       |
  169.      |                          Area                         |
  170.      +---------------------------+---------------------------+
  171.      |                           |                           |
  172.      |                           |                           |
  173.      |      Source Lister        |     Cross Reference       |
  174.      |         Area              |       Lister Area         |
  175.      |                           |                           |
  176.      |                           |                           |
  177.      |                           |                           |
  178.      |                           |                           |
  179.      +---------------------------+---------------------------+
  180.      |                        Message                        |
  181.      |                         Area                          |
  182.      +-------------------------------------------------------+
  183.  
  184.                          Figure 2. Screen Areas
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.                                 3
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. the  input  file  would be  '\UTILS\WINDOWS.PAS',   but  the  output  file  is
  203. '\PRINTER\WINDOWS.PRT'.  If, given these same fields, an include file compiler
  204. directive found within WINDOWS.PAS was '{$I SET.LIB}', then T-Ref would expect
  205. to  find the file under '\UTILS\SET.LIB'.   The 'Active Directory'  field  may
  206. also be headed by a disk drive to be used rather than the default drive.
  207.      The  input file and output file may also reference subdirectories  within
  208. the  directory  (and subdirectories) specified by the  directory  field.   For
  209. example:
  210.  
  211.           Active Directory:   C:\UTILS
  212.           Active Input File:  SPECPRGS\WINDOWS.PAS
  213.           Active Output File: \PRINTER\WINDOWS.PRT
  214.  
  215. would  reference the input file 'C:\UTILS\SPECPRGS\WINDOWS.PAS' and the output
  216. file '\PRINTER\WINDOWS.PRT' (on the default drive).  It is important to notice
  217. the difference between this and the following:
  218.  
  219.           Active Directory:   C:\UTILS\SPECPRGS
  220.           Active Input File:  WINDOWS.PAS
  221.           Active Output File: \PRINTER\WINDOWS.PRT
  222.  
  223. is  only  in the referencing of any include files located  within  the  source
  224. program (input file).
  225.      Finally,  if a file name extension (file type) is not given in the  input
  226. file  field  or  the output file field,  '.PAS' and  '.PRT'  are  respectively
  227. assumed.  Therefore, the previous example could be shortened to the following:
  228.  
  229.           Active Directory:   C:\UTILS\SPECPRGS
  230.           Active Input File:  WINDOWS
  231.           Active Output File: \PRINTER\WINDOWS
  232.  
  233. To send the output to the printer,  just blank the 'Active Output File' field.
  234. Position the block cursor at that field and strike the RETURN key.   The field
  235. will be replaced with "---> Printer" to signify the direction of output.
  236.  
  237.      B. Message Area:
  238.  
  239.      The  message area is used by the program to return information about  the
  240. progress  of the parsing.   As each line of the input file is parsed,  a  line
  241. counter  is updated to show the progress.   If an error is found in the syntax
  242. of the input program,  the message describing the error is printed within this
  243. area.   The message area is also used to display the Include File being parsed
  244. (if  any) and the number of identifiers cross referenced at the completion  of
  245. the parsing.
  246.  
  247.      The other two areas,  the source lister and cross reference  lister,  are
  248. covered completely in chapters II and III respectively.
  249.  
  250. The Pop-Up Help Windows:
  251.  
  252.      There  are only two keys to activate the program's help windows:   the F1
  253. and  the  F2 function keys.   The F1 key simply provides a  synopsis  of  what
  254. function  keys (F1 - F10) are used by the program.   The F2 key,  on the other
  255. hand,  is the help key for the fields displayed on the main  screen.   Through
  256. the use of 'Context Sensitive' help functions,  when the F2 key is struck, the
  257. help  window that appears on the screen will provide information  specifically
  258.  
  259.  
  260.                                 4
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. related  to the field selected by the block cursor.   As you  will  see,  this
  269. simplifies the learning process dramatically.
  270.  
  271.      The  other pop-up windows are used to create a 2 to 5 line header for the
  272. source  listing and the cross reference listing (F3 and F4  respectively),  to
  273. set  the input column length (F5),  to set the number of lines per page  (F6),
  274. and to save the existing field settings (F10).   More will be covered on these
  275. function keys in Chapter IV.
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.                                 5
  326.  
  327.  
  328.  
  329.  
  330.  
  331.