home *** CD-ROM | disk | FTP | other *** search
/ MacGames Sampler / PHT MacGames Bundle.iso / MacSource Folder / Samples from the CD / C and C++ / CTools ƒ / CTools Docs < prev    next >
Encoding:
Text File  |  1989-02-05  |  11.3 KB  |  243 lines  |  [TEXT/QED1]
  1. /*----------------------------------------------------------------------------
  2. --
  3. --        Docs for CTOOLS
  4. --
  5. --        A Collection of C Programming File Utilities for the Macintosh
  6. --
  7. --                by G. Haddock
  8. --
  9. ------------------------------------------------------------------------------*/
  10.  
  11. Copyright 1988, 1989 by G. Haddock.
  12. Portions of this program are copyright by Think Technologies.
  13.  
  14. In the spirit of the public domain source of the original source code for
  15. most of the "C" tools, this program is released for personal, non-commercial
  16. use as a productivity tool.
  17.  
  18.  
  19.  
  20.  
  21. General:
  22.     This program is a collection of C file tools and utilities that are useful
  23. for formatting and reading C source files, particularly some of the stuff
  24. that you obtain from the public domain sources.  These tools and utilities
  25. have been wrapped inside a Macintosh(TM) shell that includes a rudimentary 
  26. editor function.  The editor is not intended for major programming
  27. activities, but it is useful for viewing and making small modifications to
  28. files.
  29.  
  30.     Since the editor uses TextEdit, the files are limited in size to 32K after
  31. tab expansion.  (This is about 20 printed pages of source code.)  If you
  32. attempt to read a file into the application which is longer, you will receive
  33. an Error message.  Of course, you are never supposed to let your C source files
  34. get that long anyway.  If you find one longer than that somewhere, you may have 
  35. to break it into smaller segments using a different text editor before 
  36. processing.
  37.  
  38.     Because TextEdit does not handle tabs, an input filter expands out any tabs
  39. to the appropriate number of spaces upon reading the file, or entering text, and
  40. will re-convert any spaces (which are not inside " or ' quotes) back into tabs 
  41. upon saving the file back to disk.    This will generally clean up files where 
  42. spaces and tabs were originally used interchangeably.  The tabs settings in 
  43. this version are FIXED at an equal separation of 4 spaces.
  44.  
  45.     In the interests of encouraging the user to not overwrite the original
  46. unprocessed source file until you are sure that you have what you want, the
  47. program will not do a simple "SAVE" command upon closing a file, but will
  48. always force the user back through the "SAVE AS" procedure, which will ask
  49. permission before overwriting any pre-existing files.
  50.  
  51.  
  52.  
  53.  
  54. Source Formatter:
  55.     A  "C" Source Formatter or "Pretty Printer" which operates on files.  This
  56. utility will operate on any file which ends in the suffix ".c".  It will
  57. re-indent a file according to the nesting level of the segments of the program.
  58. Multiple statements per line will be reformatted to have one statement per line.
  59. The logic flow of a program (as viewed by a C compiler) should not be disturbed,
  60. but you will generally find the program much easier to read if it was not
  61. originally indented according to nesting levels.
  62.  
  63. Modified to run in a Macintosh shell environment from public domain source 
  64. obtained from the C Users Group.  Numerous changes were made to improve 
  65. handling of "if()" statements which are nested without brackets.
  66. Original author credit:    W. C. Colley, III  and J. W. Kindschi, Jr.
  67.  
  68.  
  69.  
  70.  
  71. CFLOW:
  72.     Abstracts C function calls and declarations from a C source file and 
  73. produces a listing of the program's calling hierarchy.  This utility will 
  74. operate on any file which ends in the suffix ".c".  It will generate a new file 
  75. with the original file name plus the suffix ".flw" which contains a sequential 
  76. indented list of all functions called from each function declaration.  
  77.  
  78. It is a useful utility for understanding the overall flow and calling 
  79. structure of a program, particularly one that has insufficient or no
  80. documentation or commenting.
  81.  
  82. Modified to run in a Macintosh shell environment, plus multiple minor bugs 
  83. fixed, from public domain source obtained from the C Users Group.  
  84. Original author credit:    W. C. Colley, III and Mark Ellington.
  85.  
  86.  
  87.  
  88.  
  89. CCHECK:
  90.     A program to find and report all badly matched openers and closers plus
  91. assignment/equality confusions in a C source file.  This utility will operate
  92. on any file which ends in the suffix ".c".  It will generate a new file with
  93. the original file name plus the suffix ".check" which contains the output
  94. comments from the utility.  It specifically comments on unbalanced openings
  95. and closings of brackets, braces, etc., and specifically looks for the use
  96. of "=" rather than "==" inside decision statements.  If the "Verbose" option is
  97. selected, the utility will comment on the placement of opening and closing
  98. braces which are not vertically aligned in the source code.
  99.  
  100. Modified to run in a Macintosh shell environment from public domain source
  101. dated March 1987.  Original author credit: Steve Draper, expanding on "cnest" 
  102. by Tom Anderson.
  103.  
  104.  
  105.  
  106.  
  107. Cross Reference:
  108.     This is a concordance or cross-reference utility for 'C' programs.  This
  109. utility will operate on any file which ends in the suffix ".c".  It will
  110. generate a new file with the original file name plus the suffix ".xref" which
  111. contains the cross referenced output from the utility.  It will generate a list
  112. of all variable and function names in the source code, along with the line
  113. number in which they appear.  In accordance with the operation of 
  114. Think/Lightspeed C (TM), this program does not recognise nested comments, but it 
  115. will properly deal with comments or quoted items which are inside single 
  116. or double quotes.
  117.  
  118. Options support the following features:
  119.     - Cross-referencing of Think/Lightspeed C reserved words.
  120.     - Generation of line numbered listing only.
  121.     - Generation of cross-reference only.
  122.  
  123. If the file is large, that is, over 20K bytes, and swells in size when you try
  124. to save both the line numbered listing and cross reference listing inside
  125. the same .xref file such that it swells beyond 32K, you may have to break up
  126. the file or save the numbered listing and cross-reference listing in separate
  127. files.  If you have a programmer's editor like QUED (TM), then you really won't
  128. need the numbered listing anyway.
  129.  
  130. Modified to run in a Macintosh shell environment from public domain source 
  131. provided by the C Users Group.  Keywords, reserved words, and comment
  132. processing were aligned with Think/Lightspeed C usage.  The program will now 
  133. only deal with a single level of comments, not comments nested within comments.
  134. Original author credit: Phillip N. Hisley, W. H. Rauser, W. C. Colley, III.
  135.  
  136.  
  137.  
  138.  
  139. Strip File:
  140.     This tool is useful for cleaning up and converting files that you have
  141. imported from other sources such as IBM-PC based files, or Unix systems.
  142.  
  143.     Text files obtained from IBM-PC based sources as viewed on a Macintosh
  144. usually have a row of "boxes" down the left edge of the screen, and a
  145. horizontal row of boxes at the bottom of the file.  These are actually control
  146. characters which are present in the file, but are not used by the Macintosh.
  147. To convert and clean up this kind of file, just click "OK" at the Stripper
  148. dialog, which will remove all control characters not recognized by the 
  149. Macintosh, as well as any characters with values above $7F.
  150.  
  151.     If the file does not appear to have any carriage returns, and the file just
  152. wraps around and around with little "boxes" where you think the start of each
  153. line should be, then the file is probably a Unix type file, and the additional
  154. "Convert Unix File" option should also be checked.  Unix type text files use
  155. "LineFeed" ($0A) rather than "CarriageReturn" ($0D) as the Mac does to mark
  156. a new line.  The "Convert Unix File" option will substitute a CarriageReturn
  157. for each LineFeed before stripping.  If you check this box on an IBM-PC type
  158. file, then you will end up with everything double spaced, but no other harm done.
  159.  
  160.     Although most Macintosh programs will not recognise them, there are some
  161. text editors like QUED which will respond to imbedded "Form Feeds" for
  162. page break control.  If these exist in the program, and you want to save
  163. them, activate the "Save FormFeed" option.
  164.  
  165.  
  166.  
  167.  
  168. Pascal to C:
  169.     This utility will translate Pascal keywords and operators to their
  170. C equivalent.  This utility will operate on any file which DOES NOT end in the
  171. suffix ".c".  It will generate a new file with the original file name plus
  172. the suffix ".P2.c" which contains the translated output from the utility.
  173.  
  174.     This program is an aid in translating a Pascal program to C.  It will do
  175. much of the repetitive mechanical conversion.  HOWEVER, the programmer will 
  176. need a working knowledge of both Pascal and C to manually convert some Pascal 
  177. features which this program can not handle, or for which there is no direct 
  178. C equivalent.
  179.  
  180.             MASSAGING OF THE OUTPUT BY A PROGRAMMER WILL BE NEEDED.  
  181.  
  182.     The output will generally not be legal C code.  This program provides a 
  183. simple mechanical translation of those Pascal keywords and structures that have 
  184. a direct equivalent in "C".  Structures such as "WITH" in Pascal which have no 
  185. direct equivalent in C will have to be manually re-coded.  In particular, 
  186. beware of the differences between Pascal and C in the way that the languages 
  187. pass variables as parameters to procedures.  Pascal passes a pointer to a 
  188. variable, such that operations inside a procedure will change the original 
  189. variable.  In C, a copy of the parameter is passed, (even when the name is the 
  190. same), and any operations on the parameter only occur on the copy, and not the 
  191. original, so that there can be significant differences in the logic of a 
  192. program, even if they appear "identical" in both Pascal and "C".  If you are 
  193. translating a Pascal program into "C", this utility will save you significant 
  194. time by doing the majority of the translation for you.
  195.  
  196.     The Pascal source can be in upper, lower, or mixed case.  Case is preserved
  197. during translation.  Structures translated properly include simple assignment
  198. and comparison statments, variable, type, and label declarations, enumerated
  199. types, and procedure and function declarations and instances.
  200.  
  201.     Structures NOT always completely translated properly include sets, 
  202. constant declarations, variant records, files, subrange types, VAR parameters, 
  203. CASE, FOR, UNTIL, WITH, READ, and WRITE statements, and nested procedures.
  204. The translator will generally provides hints or warnings about untranslatable 
  205. regions by inserting UPPERCASE messages enclosed with /* and */ into the 
  206. translated source.  Error messages are of the form /***# Expected ... ***/.
  207.  
  208.     Error recovery is poor- the first error in translation may result in a
  209. very long stream of error messages.  If a particular area of the Pascal
  210. program is creating errors, it may be prudent to just comment it out, and
  211. translate it manually after the program translates the rest of the file.
  212.  
  213.     The translated source can be cleaned up considerably by running it 
  214. through the "Source Formatter" after translation.
  215.  
  216. Public domain source modified to run in a Macintosh shell environment with 
  217. keyword translation aligned with Think/Lightspeed C reserved words.
  218. This program was reportedly inspired by a program in February 1985 Byte 
  219. Magazine which did a C TO PASCAL conversion.
  220. Original author credit for this version's source: James A. Mullens and 
  221. Dan Kegel.
  222.  
  223.  
  224.  
  225.  
  226. Prototype Generator:
  227.     This utility will generate C type prototypes from a C source file.
  228. This utility will operate on any file which ends in the suffix ".c".  It will
  229. generate a new file with the original file name plus the suffix ".pr" which
  230. contains the list of prototypes output by the utility.
  231.  
  232.  
  233.  
  234.  
  235. Any correspondence may be directed to Graham Haddock on    
  236.     GEnie:      G.HADDOCK
  237.     CompuServe: 70611,1530
  238.  
  239.  
  240.  
  241. G. Haddock                                                    February 4, 1989.
  242.  
  243.