home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / x / xref10.zip / XREF.DOC < prev    next >
Text File  |  1992-05-06  |  7KB  |  183 lines
  1.  
  2.                               XREF 1.0
  3.                           (August 5, 1992)
  4.  
  5.        Simple program for cross-referencing the procedures
  6.              and functions in Turbo Pascal program.
  7.  
  8.  
  9.  
  10.                        by Jacques B.M. Guy
  11.  
  12.                   Telecom Research Laboratories
  13.                 PO Box 249 Clayton 3168 AUSTRALIA
  14.  
  15.  
  16. FIRST
  17. -----
  18.  
  19. For U.S. readers, legal matters first and foremost. You get the
  20. source code, what more do you want? All right, all right, so
  21. here: if compiling it causes your screen to implode, running it
  22. causes you to lose 18 Gigabytes of your accounting archives, your
  23. lifetime savings, and why not, your life, I am not to be held
  24. responsible. Further, if it brews a mean cup of coffee instead of
  25. producing a cross-referenced index as it promises to in the
  26. opening blurb, well, tough, podners, I ain't taking no lawyers'
  27. calls.
  28.  
  29.  
  30. SECOND: WHY DID I WRITE XREF?
  31. -----------------------------
  32.  
  33. Bitter experience has taught me that object-oriented programming
  34. is not the panacea some think it is. It will not magically keep
  35. you from writing messy code. All too often have I sat down to
  36. plan ahead objects, their methods, their descendents, only to
  37. find, a few hundred lines of TP 5.5 later, that the processes I
  38. had visualized in my mind's eye were not quite those I needed
  39. to solve the problems I had in mind, elegantly and as simply as
  40. possible.
  41.  
  42. At that stage, the temptation to tamper with what you have
  43. written so far, rather than starting afresh, is strong. Surrender
  44. to it, and you'll end up, more often than not, with an
  45. unmanageable mess. But if you resist it, and do start once again
  46. from scratch, only equipped with a better grasp of what your code
  47. *really* ought to do, there is little to help you, beyond pencil,
  48. paper, and patience.
  49.  
  50. I was rewriting from scratch an algorithm to compute the word and
  51. character entropy of texts, generate text randomly, and produce
  52. on-screen concordances, when, after 800 tightly packed lines, I
  53. now longer knew which procedure did precisely what and called
  54. upon which other procedures. The cross-referencing programs I
  55. downloaded from Timo Salmi's garbo, and the "oak" shadow site at
  56. archie did things I did not need, and did not do those things I
  57. wanted.
  58.  
  59. The first version of XREF, dated
  60.  
  61.  
  62. THIRD: WHAT DOES XREF DO?
  63. -------------------------
  64.  
  65. It produces an index of the functions and procedures in a Turbo
  66. Pascal program, provided that you did not use objects (OO-Pascal
  67. syntax will confuse XREF beyond your wildest dreams).
  68.  
  69. Let us look at an index, with some explanatory notes thrown in,
  70. produced from a real program, which you you probably recognize if
  71. you are a Turbo Pascal veteran.
  72.  
  73. FIRST-ED.PAS <--- the program name, the old TP Editor Toolbox
  74.  
  75. Advance PROCEDURE in CMD.ED (348..363)
  76.      EditRightWord in CMD.ED: 387 398 407
  77. (** Meaning:
  78.     procedure Advance is declared in file CMD.ED, from
  79.     lines 348 to 363, and called by
  80.     the procedure or function EditRightWord in files CMD.ED
  81.     on lines 387, 398, and 407 **)
  82.  
  83. Class FUNCTION in CMD.ED (717..725)
  84.      EditRightWord in CMD.ED: 397 398
  85.      EditDeleteRightWord in CMD.ED: 748 750
  86. (** Meaning:
  87.     function Class is declared in file CMD.ED, from lines 717 to
  88.     725, and called by EditRightWord in file CMD.ED, on lines
  89.     397 and 398, and by EditDeleteRightWord in file CMD.ED,
  90.     linese 748 and 750 ***)
  91.  
  92. EditBackground PROCEDURE in TASK.ED (41..57) forward in USER.ED (14)
  93.      EditAskfor in USER.ED: 205
  94.      EditSchedule in TASK.ED: 69
  95. (** Meaning:
  96.     procedure EditBackGround is declared in file TASK.ED, lines
  97.     41 to 57, and has forward declaration in USER.ED, line 14.
  98.     It is called by EditAskFor in USER.ED, line 205 and by
  99.     EditSchedule in TASK.ED, line 69 **)
  100.  
  101.  
  102.  
  103. ... and so on and so on.
  104.  
  105. Following Len Dorfman's naming conventions, the first substring
  106. in a procedure or function identifier to appear between
  107. underscores is interpreted as a class name.
  108.  
  109. The listing starts with classless functions and procedures,
  110. listed alphabetically, then continues with classes, again
  111. in alphabetical order.
  112.  
  113. Within each class, function and procedures are listed
  114. alphabetically, with the class part disregarded. That is why, in
  115. the example above, _Char_Generated appears in-between
  116. Find_Char_StringAt and Read_Char_CorpusFrom; they were
  117. alphabetized as if they read: FindStringAt, Generated, and
  118. ReadCorpusFrom. Why did I decide on that alphabetizing scheme?
  119. Because, if and when I rewrite that program in object-oriented
  120. Pascal, "FindStringAt", "Generated", "ReadCorpusFrom", etc.
  121. would be the identifiers I would normally choose for the methods
  122. of the object type "Character".
  123.  
  124.  
  125. NAMING CONVENTIONS
  126. ------------------
  127.  
  128. Len Dorfman proposes this syntax for variable and procedure or
  129. function identifiers:
  130.  
  131. <Action Message>_<Class Name>_<Behavior Modifier(s)>
  132.  
  133. <Action Message> is a null string or any valid identifier that
  134. does *not* contain an underscore (_)
  135.  
  136. <Behaviour Modifier(s)> is a null string or any valid identifier
  137. (which may or may not contain underscores).
  138.  
  139. I found that convention extremely clear and easy to use. Just
  140. consider these few macros, taken straight out of his book:
  141.  
  142. get_cursor_info
  143. set_cursor_info
  144. get_cursor_location
  145. get_cursor_shape
  146. set_cursor_shape
  147. set_cursor_up_one
  148. save_cursor_info
  149. restore_cursor_info
  150.  
  151. Those macro names read like plain English, and what they do is
  152. obvious. At the same time, it is quite transparent how they could
  153. be translated into an object-oriented high-level language: define
  154. an object type "Cursor" with methods "GetInfo", "SetInfo",
  155. "GetLocation", etc.
  156.  
  157.  
  158. LASTLY
  159. ------
  160.  
  161. How do you run XREF? If you are worried about viruses, compile the
  162. source code provided in XREF.PAS first. Then type: XREF and hit
  163. the much bashed RETURN key. You can also pass the names of the
  164. input program file and the output index file on the command line,
  165. like this:
  166.  
  167.    XREF MYPROG MYPROG.IDX
  168.  
  169. By default, XREF writes 70 columns per line, and puts in a form
  170. feed every 60 lines in the index file. You can change those
  171. defaults when you pass the file names on the command line, like
  172. this:
  173.  
  174.    XREF MYPROG MYPROG.IDX C80 L55
  175.  
  176. That makes it 80 columns per line, and 55 lines per page. To do
  177. away with form feeds, ask for 0 lines per page:
  178.  
  179.    XREF MYPROG MYPROG.IDX L0
  180.  
  181. And, as you have noticed, you need not type the .PAS extension.
  182.  
  183.