Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/418.lha/ctoh_v1.02/ctoh.doc

Text File | 1990-09-08 | 6KB | 183 lines

.heCTOH -- A C-language parser, and header file generator (Rev 1.02)

Contents:

    1.0 Scope

    2.0 Description

    3.0 Requirements

    4.0 Operation
        4.1 Quiet Option
        4.2 Verbose Option
        4.3 Save and Forget

    5.0 User Support



1.0     Scope

    This document describes the CTOH utility program, its usage
and requirements.  This program, and its documentation are both
Copyright 1990 by Kevin Smathers.  Permission is granted for
non-profit publication and distribution of these items.

2.0     Description

    The CTOH utility was written to eliminate the need for
maintaining seperate header files for each of your C sources. In
the past it has been neccessary to keep seperate track of all of
your function prototypes in a C header file.  When the C source
code was modified, and the header file was forgotten strange and
difficult to find bugs were introduced.  The CTOH utility was
written to automate the process of creating a header file so that
there would be no need to update the files by hand.

    Program source code which conforms to the new ANSI standards
is automatically converted into noncode-generating prototypes and
external declarations.  Preprocessor commands are generally left
alone or deleted.  Pre-ANSI function declarations are not handled
correctly.

3.0     Requirements

    The CTOH utility will run on any Amiga system capable of
supporting a C compiler.  To install CTOH copy the 'ctoh' program
to your 'c:' directory.

4.0     Operation

    CTOH can be run on a list of files specified at the command
line.  Filenames should not include any extension.  The extension
'.C' will be added to find the source file, and the '.H' extension
will be added to create the header file.  If a header file already
exists by that name, CTOH will query before continuing.
___________________________________________________________________
Example 1: Creating Header files

1.src:manx> ndir
test.c      readstr.c   sets.c      pat.c       conio.c     conio.h
conio.o     test.doc    test.bak

1.src:manx> ctoh test readstr sets pat conio
Created 'test.h' from 'test.c'
Created 'readstr.h' from 'readstr.c'
Created 'sets.h' from 'sets.c'
Created 'pat.h' from 'pat.c'
File 'conio.h' already exists!
Overwrite (Y/N)? Y
Created 'conio.h' from 'conio.c'

1.src:manx>
___________________________________________________________________

4.1     Quiet Option

    CTOH can be made to run without operator intervention by using
the quiet option.  Options can be interspersed with filenames so
that the options are only valid for the filenames which follow them.
    If the '-q' option is used on the command line, file names
listed after the option will continue processing as though the user
had typed 'Y'.
___________________________________________________________________
Example 2: Using CTOH option switches

1.src:manx> ndir
test.c      readstr.c   sets.c      pat.c       conio.c     conio.h
conio.o     test.doc    test.bak    test.h      readstr.h   sets.h
pat.h

1.src:manx> ctoh -q test -v readstr
File 'test.h' already exists!
Created 'test.h' from 'test.c'
File 'readstr.h' already exists!
Overwrite (Y/N)? Y
Created 'readstr.h' from 'readstr.c'

1.src:manx>
___________________________________________________________________

4.2     Verbose Option

    To enable user interaction if it has been disabled with the '-q'
option, use the verbose option '-v'.  Example 2 shows how both the
Quiet and Verbose options can be used.

4.3     Save and Forget

    The header files required for a specific source file can be
split into two categories. Some of them are used to define types or
structures for global declarations and function parameters.  Other
header files define subroutines prototypes, or other declarations
which are only used in the body of the code.
    Generally you would like '#include' statements in the first
category to be saved, while ones in the second category should be
dismissed.  Since the C-language doesn't distinguish between these
types, two special comments should be inserted into your code so
that ctoh can identify them.
___________________________________________________________________
Example 3: Using Save and Forget

1.src:manx> type test.c
/*  Test.c -- V0.01
.he Test.c -- V0.01
*
* Simple test program
*/

/* SAVE */
#include "exttype.h"
/* FORGET */
#include "readstr.h"

byte readbyte(int width)
{
    char s[20];
    return (byte) atoi(readstr(s,width));
}

1.src:manx> type test.h
#include "exttype.h"
byte readbyte(int width);

1.src:manx>
___________________________________________________________________

    In the example above, the SAVE comment is used to keep the
include for exttype.h which defines the type 'byte'.
    Although the test source code also uses another include file
to define the prototype for 'readstr()', that line is removed from
the header file since it follows a FORGET comment.


5.0     User Support

    Since I use CTOH primarily for my own code (although there are
a few other users) there may be legal ANSI constructions that are
not handled correctly by CTOH.  Bugs which are introduced by
unusual constructions will be fixed at the earliest opportunity by
writing me at one of the following addresses:

    USENET:
        [e-mail]                     -or-
        sun!portal!cup.portal.com!sullivan_-_segall

    BIX:
        radagast

    US-SNAIL:
        Kevin Smathers
        10341 Leola Ct #1
        Cupertino, CA 95014

        Include SASE and Floppy disk (US-SNAIL only)

    Source code will not be made available.  (It is far too ugly
for me ever to show anyone anyway.)


    ...to boldly kludge, where no man has kludged before...