home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 418.lha / ctoh_v1.02 / ctoh.doc < prev    next >
Encoding:
Text File  |  1990-09-08  |  5.6 KB  |  183 lines
  1. .heCTOH -- A C-language parser, and header file generator (Rev 1.02)
  2.  
  3. Contents:
  4.  
  5.     1.0 Scope
  6.  
  7.     2.0 Description
  8.  
  9.     3.0 Requirements
  10.  
  11.     4.0 Operation
  12.         4.1 Quiet Option
  13.         4.2 Verbose Option
  14.         4.3 Save and Forget
  15.  
  16.     5.0 User Support
  17.  
  18.  
  19.  
  20. 1.0     Scope
  21.  
  22.     This document describes the CTOH utility program, its usage
  23. and requirements.  This program, and its documentation are both
  24. Copyright 1990 by Kevin Smathers.  Permission is granted for
  25. non-profit publication and distribution of these items.
  26.  
  27. 2.0     Description
  28.  
  29.     The CTOH utility was written to eliminate the need for
  30. maintaining seperate header files for each of your C sources. In
  31. the past it has been neccessary to keep seperate track of all of
  32. your function prototypes in a C header file.  When the C source
  33. code was modified, and the header file was forgotten strange and
  34. difficult to find bugs were introduced.  The CTOH utility was
  35. written to automate the process of creating a header file so that
  36. there would be no need to update the files by hand.
  37.  
  38.     Program source code which conforms to the new ANSI standards
  39. is automatically converted into noncode-generating prototypes and
  40. external declarations.  Preprocessor commands are generally left
  41. alone or deleted.  Pre-ANSI function declarations are not handled
  42. correctly.
  43.  
  44. 3.0     Requirements
  45.  
  46.     The CTOH utility will run on any Amiga system capable of
  47. supporting a C compiler.  To install CTOH copy the 'ctoh' program
  48. to your 'c:' directory.
  49.  
  50. 4.0     Operation
  51.  
  52.     CTOH can be run on a list of files specified at the command
  53. line.  Filenames should not include any extension.  The extension
  54. '.C' will be added to find the source file, and the '.H' extension
  55. will be added to create the header file.  If a header file already
  56. exists by that name, CTOH will query before continuing.
  57. ___________________________________________________________________
  58. Example 1: Creating Header files
  59.  
  60. 1.src:manx> ndir
  61. test.c      readstr.c   sets.c      pat.c       conio.c     conio.h
  62. conio.o     test.doc    test.bak
  63.  
  64. 1.src:manx> ctoh test readstr sets pat conio
  65. Created 'test.h' from 'test.c'
  66. Created 'readstr.h' from 'readstr.c'
  67. Created 'sets.h' from 'sets.c'
  68. Created 'pat.h' from 'pat.c'
  69. File 'conio.h' already exists!
  70. Overwrite (Y/N)? Y
  71. Created 'conio.h' from 'conio.c'
  72.  
  73. 1.src:manx>
  74. ___________________________________________________________________
  75.  
  76. 4.1     Quiet Option
  77.  
  78.     CTOH can be made to run without operator intervention by using
  79. the quiet option.  Options can be interspersed with filenames so
  80. that the options are only valid for the filenames which follow them.
  81.     If the '-q' option is used on the command line, file names
  82. listed after the option will continue processing as though the user
  83. had typed 'Y'.
  84. ___________________________________________________________________
  85. Example 2: Using CTOH option switches
  86.  
  87. 1.src:manx> ndir
  88. test.c      readstr.c   sets.c      pat.c       conio.c     conio.h
  89. conio.o     test.doc    test.bak    test.h      readstr.h   sets.h
  90. pat.h
  91.  
  92. 1.src:manx> ctoh -q test -v readstr
  93. File 'test.h' already exists!
  94. Created 'test.h' from 'test.c'
  95. File 'readstr.h' already exists!
  96. Overwrite (Y/N)? Y
  97. Created 'readstr.h' from 'readstr.c'
  98.  
  99. 1.src:manx>
  100. ___________________________________________________________________
  101.  
  102. 4.2     Verbose Option
  103.  
  104.     To enable user interaction if it has been disabled with the '-q'
  105. option, use the verbose option '-v'.  Example 2 shows how both the
  106. Quiet and Verbose options can be used.
  107.  
  108. 4.3     Save and Forget
  109.  
  110.     The header files required for a specific source file can be
  111. split into two categories. Some of them are used to define types or
  112. structures for global declarations and function parameters.  Other
  113. header files define subroutines prototypes, or other declarations
  114. which are only used in the body of the code.
  115.     Generally you would like '#include' statements in the first
  116. category to be saved, while ones in the second category should be
  117. dismissed.  Since the C-language doesn't distinguish between these
  118. types, two special comments should be inserted into your code so
  119. that ctoh can identify them.
  120. ___________________________________________________________________
  121. Example 3: Using Save and Forget
  122.  
  123. 1.src:manx> type test.c
  124. /*  Test.c -- V0.01
  125. .he Test.c -- V0.01
  126. *
  127. * Simple test program
  128. */
  129.  
  130. /* SAVE */
  131. #include "exttype.h"
  132. /* FORGET */
  133. #include "readstr.h"
  134.  
  135. byte readbyte(int width)
  136. {
  137.     char s[20];
  138.     return (byte) atoi(readstr(s,width));
  139. }
  140.  
  141. 1.src:manx> type test.h
  142. #include "exttype.h"
  143. byte readbyte(int width);
  144.  
  145. 1.src:manx>
  146. ___________________________________________________________________
  147.  
  148.     In the example above, the SAVE comment is used to keep the
  149. include for exttype.h which defines the type 'byte'.
  150.     Although the test source code also uses another include file
  151. to define the prototype for 'readstr()', that line is removed from
  152. the header file since it follows a FORGET comment.
  153.  
  154.  
  155. 5.0     User Support
  156.  
  157.     Since I use CTOH primarily for my own code (although there are
  158. a few other users) there may be legal ANSI constructions that are
  159. not handled correctly by CTOH.  Bugs which are introduced by
  160. unusual constructions will be fixed at the earliest opportunity by
  161. writing me at one of the following addresses:
  162.  
  163.     USENET:
  164.         radagast@cup.portal.com                     -or-
  165.         sun!portal!cup.portal.com!sullivan_-_segall
  166.  
  167.     BIX:
  168.         radagast
  169.  
  170.     US-SNAIL:
  171.         Kevin Smathers
  172.         10341 Leola Ct #1
  173.         Cupertino, CA 95014
  174.  
  175.         Include SASE and Floppy disk (US-SNAIL only)
  176.  
  177.     Source code will not be made available.  (It is far too ugly
  178. for me ever to show anyone anyway.)
  179.  
  180.  
  181.     ...to boldly kludge, where no man has kludged before...
  182.  
  183.