home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / turbopas / t_ref.arc / T-REFCH3.DOC < prev    next >
Text File  |  1987-01-15  |  16KB  |  397 lines
  1.  
  2.  
  3.  
  4.                     Chapter III - The Cross Reference Lister
  5.  
  6.      This  chapter deals primarily with the Cross Reference  Listing  program.
  7. However,  before  getting  into the details of the Reference  Lister,  several
  8. important definitions need to be made to prevent any confusion. Once the terms
  9. used in this chapter are presented, we will present an in-depth description of
  10. the Cross Referencer and its print format.
  11.  
  12. System Identifiers:
  13.  
  14.      Like  most  compilers,  Turbo  Pascal has defined a  set  of  identifiers
  15. already declared under the IBM-PC version.   Often called Standard Identifiers
  16. or System Identifiers,  they include Constants (i.e.,  Blue and  Co80),  Types
  17. (i.e., Integer, Real, Byte, String, and Char), Variables (i.e., Mem and MemW),
  18. Procedures (i.e., Textcolor, Substr, and Window), and Functions (i.e., WhereX,
  19. Copy,  Cos,  and Random).  T-Ref has "pre-declared" the complete list of Turbo
  20. system  identifiers (up through Version 3.01) for referencing and they may  be
  21. included  in the cross reference listing if so desired.   Appendix A gives the
  22. entire list of system defined (standard) identifiers.
  23.  
  24. Data Types:
  25.  
  26.      There  are  three general catagories of data types  in  Pascal:  scalars,
  27. structured types,  and pointers.  Scalars include the standard scalar types as
  28. noted above (Integer,  Byte,  Real,  Boolean,  String,  and Char) and extended
  29. scalar  types  (Subranges  and User-Defined Scalars).   Structured  types  are
  30. arrays,  records,  sets,  and files.   Finally, pointers are address values to
  31. variables of the other data types.
  32.  
  33. Basic Types:
  34.  
  35.      Basic  types,  not to be confused with data types,  are the types of  the
  36. identifiers.   Basic types include Labels, Constants, Types, Variables, Proce-
  37. dures,  and  Functions.   The best way to prevent confusion between these  and
  38. data  types is by noting that most basic types have an associated  data  type.
  39. For example,  the basic type 'Function' may have a data type of Integer.   The
  40. basic  type 'Constant' may have a basic type of Char.   However,  basic  types
  41. Labels,  Procedures, and untyped formal parameters are the only ones that have
  42. an undefined data type.
  43.  
  44.      Labels  do  not necessarily have to be identifiers,  but may  be  integer
  45. numbers as well.  These are handled appropriately by T-Ref.
  46.  
  47.      User  defined  scalar  values are considered  constants  by  T-Ref.   For
  48. example, in the following declaration:
  49.  
  50.       TYPE DAY_OF_WEEK = (SUN,MON,TUE,WED,THU,FRI,SAT);
  51.  
  52. the identifiers SUN, MON, ..., SAT are considered of basic type Constant, even
  53. though the identifier DAY_OF_WEEK is of basic type Type.
  54.  
  55.      All  formal parameter identifiers are considered a special  extension  of
  56. the  basic type Variable.   Therefore,  when Variables are listed in the cross
  57. reference, formal parameter identifiers are included.
  58.  
  59.  
  60.  
  61.                                11
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      The program name,  when a program head is given,  does not actually  fall
  71. into  any  of  the basic types listed above;  however,  rather than  having  a
  72. separate field for a cross reference of the program name,  it is considered by
  73. T-Ref as a Procedure type with no references other than its declaration.
  74.  
  75. Now for the Cross Reference Lister:
  76.  
  77.      The Cross Reference Lister,  when activated ("ON"),  gives a cross refer-
  78. ence listing of the specified types of identifiers.   Selection of identifiers
  79. is determined by basic type in the following fashion:
  80.  
  81.      Each of the basic types have two fields on the screen:  a scope field and
  82. a  usage  field  (see Figure 1).   The scope field is used  to  determine  the
  83. selection  of  identifiers  based upon whether they are  declared  within  the
  84. system  (system defined or "SysDf") or within the program (program defined  or
  85. "PrgDf").   The  "All" setting is used to select all identifiers of that basic
  86. type.   The "None" setting tells the program to skip listing any identifier of
  87. that basic type.
  88.      The  usage field is used to determine the selection of identifiers  based
  89. upon  whether or not they have been referenced within the program (other  than
  90. in  their  declarations).   The  "Used" setting will select for  listing  only
  91. identifiers  of  that basic type that were actually used within  the  program.
  92. The  "Unused"  setting selects only those identifiers not referenced  anywhere
  93. within  its  scope.  The "All" setting selects  identifiers declared  of  that
  94. basic type irregardless of their use.
  95.  
  96.      The  Cross Reference Lister  is activated by positioning the cursor  over
  97. the  'Cross  Reference' field and striking the space bar until the  word  "On"
  98. appears within the cursor.   To deactivate the cross reference lister, hit the
  99. space bar again and the word "Off" will appear.   Note that the same procedure
  100. here  is used to activate the cross reference lister as in the  source  lister
  101. described in chapter II above.  Like the  source lister,  the nine fields that
  102. appear  on  the  screen directly below the 'Cross Reference' field  relate  to
  103. specific information about what identifiers are to be included or not included
  104. in the cross reference listing, as well as setting a header and paging.  These
  105. fields  are  updated in the same manner as those fields in the  source  lister
  106. area:  by  placing the block cursor over the field and striking the space  bar
  107. until the desired parameter appears within the cursor.
  108.      Since  we have already defined the parameters that appear in  the  fields
  109. 'Labels', 'Constants', 'Types', 'Variables', 'Procedures', and 'Functions', we
  110. will  not pursue this any further except to say that the 'Labels' field has  a
  111. restricted set of values for its scope field: "PrgDf" and "None".  This is due
  112. to  the fact that Turbo has no System Defined labels.   No other  restrictions
  113. apply to any of these fields.
  114.  
  115.      The  'Header' field operates in exactly the same fashion as the  'Header'
  116. field within the source lister area.   When it is activated ("On"), the header
  117. that  was created using the F4 function key will be printed at the top of each
  118. page of cross reference output.  The header can be from two to five lines long
  119. and  each  line can be up to 75 columns in length.   Again,  if  a  header  is
  120. printed, the program will automatically buffer 3 blank lines before the header
  121. and 2 blank lines after the header.
  122.  
  123.      The  'Page Numbering' field also operates like the field of the same name
  124. within the source lister area.   The number of lines per page is set by the F6
  125.  
  126.  
  127.                                12
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. function key and is the same value used for paging the source listing output.
  137.  
  138.      The  'Include File' field is used to tell the program whether or  not  to
  139. print  files  made  available to the Turbo compiler through the  include  file
  140. compiler directive.   When activated ("Yes"),  include files are automatically
  141. parsed  for cross referencing all identifiers within the  files  (declarations
  142. and uses).   The OPTIONAL setting ("Opt") allows you to selectively choose the
  143. files to be included in the cross referencing process.  If one of the 'Include
  144. File'  fields (either for the source lister or the cross reference lister)  is
  145. activated and the other is not,  the program will take the appropriate actions
  146. to perform only the operations on the include file needed.
  147.  
  148. Interpreting the Cross Reference listing:
  149.  
  150.      There are three parts to the cross reference listing: an identifier cross
  151. reference listing, a procedure/function map listing (table of contents), and a
  152. basic and data types count listing.
  153.  
  154. A.  Identifier Cross Reference Listing:
  155.  
  156.      Each  identifier cross referenced is listed in alphabetical order and has
  157. the following format.   The first two lines of a cross reference entry has the
  158. following format:
  159.  
  160. Name................         Basic-Type              Data-Type
  161.   Declared on line  LLLL:SSSS   within Procedure-Name...... (LVL)
  162.  
  163. where Name is the name of the identifier (20 characters long),  Basic-Type  is
  164. the basic type,  Data-Type is the data type, LLLL:SSSS is the line number (and
  165. possibly the include file's subline number) of the declaration, Procedure-Name
  166. is the procedure or function name that the identifier was declared within  (up
  167. to  20  characters  long),  and LVL is the lexical level of the  procedure  or
  168. function within the program.
  169.      If the identifier was not declared within the source code (as is the case
  170. when  cross referencing a portion of a program or a library or procedures that
  171. reference identifiers in other portions of the program),  then the second line
  172. rather reads:
  173.  
  174.   "Not declared within the scanned source."
  175.  
  176.      The basic type field will be one of the following:
  177.  
  178.      "Undefnd" - Signifies the  use of an undeclared identifier  found  during
  179.                  the parse.
  180. Labels:
  181.      "Label  " - Labels
  182.  
  183. Constants:
  184.      "Constnt" - Constants
  185.      "ScalVal" - Scalar Values
  186.      "Typed C" - Typed Constants
  187.  
  188. Types:
  189.      "Type   " - Types
  190.  
  191.  
  192.  
  193.                                13
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. Variables:
  203.      "Var    " - Variables
  204.      "FrmParm" - Formal Parameters (considered a Variable)
  205.      "VarParm" - Formal Variable Parameters (considered a Variable)
  206.      "Rec Fld" - Record Fields (considered a Variable)
  207.      "Rec Tag" - Record Fields declared as Record Tags (considered a Variable)
  208.  
  209. Procedures:
  210.      "Program" - Program name
  211.      "Procedr" - Procedures
  212.  
  213. Functions:
  214.      "Functn " - Functions
  215.  
  216. The data type field will be one of the following:
  217.  
  218.      "Undefnd"  - Signifies the use of an undeclared identifier  found  during
  219.                  the parse, or an Untyped Formal Parameter
  220.      "Integer" - Integer scalars
  221.      "Byte   " - Byte scalars
  222.      "Real   " - Real scalars
  223.      "Boolean" - Boolean scalars
  224.      "String " - String scalars
  225.      "Char   " - Character scalars
  226.      "Scalar " - User Defined Scalars
  227.      "Range  " - Subranges
  228.      "Record " - Structured Type Records
  229.  
  230. and  may  be  preceeded  by some combination of the  following  to  signify  a
  231. structured data type:
  232.  
  233.      "Absolute Addr" - The Variable is located at a specific address
  234.      "File of"       - The Type or Variable is of type File
  235.      "Set of"        - The Constant, Type, or Variable is of type Set
  236.      "Pointer to"    - The Type or Variable is of type Pointer
  237.  
  238. For  example,  "Absolute Addr Set of Scalar" means the data type of the ident-
  239. ifier is a set of type scalar and is at a specific address in memory.
  240.  
  241.      The  third  line of the reference,  if the identifier is  not  referenced
  242. within the scanned source code (other than its declaration), will be:
  243.  
  244.   "<<< Identifier not referenced. >>>"
  245.  
  246. If  the identifier has been referenced (other than its  declaration),  then  a
  247. sequence of references are printed.
  248.      First, a header for the references is printed describing the procedure or
  249. function the reference took place:
  250.  
  251.   "Referenced within" Procedure-Name......:
  252.  
  253. followed  by  an ordered list of the lines that identifier was referenced  on.
  254. The  numbering  is in the same format as the declaration line  number  format:
  255. LLLL:SSSS.
  256.      An  asterisk  ("*") just before the line number means the identifier  was
  257. explicitly set to a value on that line of code.  An ampersand ("&") means  the
  258.  
  259.  
  260.                                14
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. same thing, except that the identifier was set at a lexical (procedural) level
  269. BELOW the level of its declaration.
  270.      Here,  'explicitly  set' means that the variable or function was set with
  271. a  <variable> := <expression> statement,  and does not take into consideration
  272. setting  the  identifier  through the use of procedure or  function  parameter
  273. passing.
  274.  
  275.      In  addition,  the  referencer  analyzes the code to  provide  additional
  276. information:
  277.  
  278.      a.  For procedures and functions, a check is made to determine whether it
  279. is recursive.  If so, it is noted in the listing.
  280.      b.  Overlay and external procedures and functions are noted.
  281.      c.   For  functions  and variable formal parameters,  if they  are  never
  282. explicitly set in the code,  a warning to this effect is printed.   Note  this
  283. does  not  necessarily reflect an error,  since these identifiers may  be  set
  284. through other means.
  285.      d.   For  formal  parameters (not variable formal  parameters)  that  are
  286. explicitly set in the code,  a warning is printed.   This may be an indication
  287. that it should be a variable formal parameter.
  288.  
  289.      At  this  point,  it must be noted that record types and  variables  (and
  290. their  associated  record fields) are a special case and are not handled  pre-
  291. cisely the same as other data types.  This comes about primarily because it is
  292. possible to have (and is often the case,  rather than the exception) more than
  293. one  record variable with the same structure and therefore with precisely  the
  294. same  record field identifiers.   If a record field identifier were listed  as
  295. shown  above,  it  would be impossible without inspection to  determine  which
  296. record variable the reference was associated with.
  297.      Therefore,  references  to  a specific record field are printed  directly
  298. under  all record identifiers containing that field in its  structure.   Cross
  299. references to that field then only include those that pertain specifically  to
  300. the record identifier being listed.
  301.      For example, suppose a record structure type were created:
  302.  
  303.   TYPE
  304.     REC_STRUCT = RECORD
  305.      A,B : BYTE;
  306.     END;
  307.  
  308. and two different record variables were declared from this type:
  309.  
  310.   4  VAR
  311.   5    REC_A, REC_B : REC_STRUCT;
  312.  
  313. Now suppose the following code is implemented:
  314.  
  315.  35   WITH REC_A DO A := 1;
  316.  36   WITH REC_B DO A := 0;
  317.  
  318. where  35  and 36 refer to the line numbers.   Then,  a portion of  the  cross
  319. reference listing would look like this:
  320.  
  321.  
  322.  
  323.  
  324.  
  325.                                15
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. REC_A         Var              Record
  335.   Declared on line    5     within PROGRAM (1)
  336.   Referenced within PROGRAM:
  337.       35       *   35
  338.  
  339.      Record field: A                      Byte
  340.      Referenced within PROGRAM:
  341.   *   35
  342.  
  343.      Record field: B                      Byte
  344.      << Identifier not referenced. >>
  345.  
  346. REC_B         Var              Record
  347.   Declared on line    5     within PROGRAM (1)
  348.   Referenced within PROGRAM:
  349.       36       *   36
  350.  
  351.      Record field: A                      Byte
  352.      Referenced within PROGRAM:
  353.   *   36
  354.  
  355.      Record field: B                      Byte
  356.      << Identifier not referenced. >>
  357.  
  358. Here,  record  field A has been broken out into its individual references  and
  359. therefore, it can be seen which reference goes with which record variable.
  360.      Also note that  REC_A and  REC_B show two  references.  The first are the
  361. references  of the  identifiers  within the  WITH clauses; the  second are the
  362. references of record fields BELONGING to these identifiers.   The asterisk (*)
  363. shows where the identifiers were set to some value.
  364.  
  365. B.  Procedure/Function Mapping:
  366.  
  367.      The  second  part  of  the cross reference lister is a  printout  of  all
  368. procedures and functions declared within the parse, along with the line number
  369. of  the declaration.   The names are indented according to the lexical  (proc-
  370. edural) level,  and overlay and external procedures/functions are again noted.
  371. This portion of the listing is excellent for getting a general layout (a table
  372. of contents) of a program or library.
  373.  
  374. C.  Basic and Data Type Count Listing:
  375.  
  376.      Finally,  the  cross  reference lister prints a summation  of  the  total
  377. number of lines parsed,  the total number of identifiers cross referenced, and
  378. a  break-out of the identifier count by basic type and data  type.   Remember,
  379. "Undefnd"  basic  types are those identifiers parsed but were never  declared.
  380. (Also remember, untyped formal parameters, labels, procedures, and the program
  381. name have no data type associated with them and therefore will not be included
  382. in the data type totals.)
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.                                16
  392.  
  393.  
  394.  
  395.  
  396.  
  397.