@need 3200

@node Naming Conventions in the Hackerlab C Library
@appendix Naming Conventions in the Hackerlab C Library

This appendix describes the naming conventions used in the Hackerlab
C library.

@menu
* C Identifiers and Macros::
* Header Files::
@end menu

@need 3200

@node C Identifiers and Macros
@section C Identifiers and Macros

C identifiers and macro names are divided into categories related by
functionality.  For each category, a unique @geindex category stub
@dfn{category stub} is chosen
which is an alphanumeric string.  If a category has the stub @code{STUB},
most names in that category begin with the string @code{STUB_}.  In some
cases, the name @code{STUB} is used as an identifier by itself.  If @code{STUB}
is the name of a data structure, there may be functions named
@code{make_STUB} and @code{free_STUB}.  For some data types, a @code{sizeof_STUB}
macro is defined.  Case distinctions do not matter: a stub may be
used with any combination of upper and lowercase letters.


If a name is publicly visible, but is not intended to be used outside
of the implementation of the Hackerlab C Library, it is given a prefix
of the form @code{STUB__}.


The stubs currently in use are:

@example
@group
        ar              dynamically sized arrays
        bits            shared bitset trees
        bits_tree       bitset trees
        bitset          flat bitsets
        char            manipulating 8-bit characters
@end group
@group
        cvt             number/string conversions
        errno           manipulating error codes
        file_name       manipulating file names
        hash            computing hash values
        hashtree        the hashtree data structure
@end group
@group
        invariant       testing invariants
        lim             limited allocation
        mem             manipulating arrays of bytes
        MACHINE         machine-specific parameters
        must            errorless allocation
@end group
@group
        opt             command line option processing
        panic           aborting programs
        path            manipulating directory search paths
        piw             the Program Instrumentation Workbench
        pow2_array      power-or-two sized sparse arrays
@end group
@group
        printfmt        formatted I/O
        reserv          reserved file descriptors
        rx              regexp pattern matching
        safe            errorless I/O functions
        str             manipulating ISO 8859-1 strings
@end group
@group
        t               fundamental typedefs (e.g. `t_uint8')
        uni             foundational Unicode support
@end group
@group
        unidata         the Unicode character database
        url             url-based virtual file systems
        vfdbuf          descriptor-based buffered I/O
        vu              virtual descriptor-based i/o
        xml             XML utilities
@end group
@group
@end group
@end example

There are also some exceptions.  Some versions of the library
export the Posix.2 interface for regexp pattern matching (@code{regcomp},
@code{regexec} etc.).  Some versions of the library export standard
interfaces for memory allocation (@code{malloc}, @code{free}, etc.).




@need 3200

@node Header Files
@section Header Files

Hackerlab C Library header files are always named by two directories
and a file name, as in this example:

@example
@group
        <hackerlab/machine/types.h>
@end group
@group
@end group
@end example

Every public header file can be included by itself -- without having
to include any other header file first.  Some Hackerlab header files
have the effect of including other Hackerlab header files.


Every Hackerlab header file may be safely included more than once.
A CPP macro beginning with @code{INCLUDE__} is used to protect the contents
of each header file from being interpreted more than once.  For
example, the header @code{<hackerlab/machine/types.h>} contains:

@example
@group
        #ifndef INCLUDE__MACHINE__TYPES_H
        #define INCLUDE__MACHINE__TYPES_H
        ...
        #endif  /* INCLUDE__MACHINE__TYPES_H */
@end group
@group
@end group
@end example






