gperf.texinfo

早期freebsd实现

The keyword input file optionally contains a section for including
arbitrary C declarations and definitions, as well as provisions for
providing a user-supplied @code{struct}.  If the @samp{-t} option
@emph{is} enabled, you @emph{must} provide a C @code{struct} as the last
component in the declaration section from the keyfile file.  The first
field in this struct must be a @code{char *} identifier called ``name,''
although it is possible to modify this field's name with the @samp{-K}
option described below.

Here is simple example, using months of the year and their attributes as
input:

@group
@example
struct months @{ char *name; int number; int days; int leap_days; @};
%%
january,   1, 31, 31
february,  2, 28, 29
march,     3, 31, 31
april,     4, 30, 30
may,       5, 31, 31
june,      6, 30, 30
july,      7, 31, 31
august,    8, 31, 31
september, 9, 30, 30
october,  10, 31, 31
november, 11, 30, 30
december, 12, 31, 31
@end example
@end group

Separating the @code{struct} declaration from the list of key words and
other fields are a pair of consecutive percent signs, @code{%%},
appearing left justified in the first column, as in the UNIX utility
@code{lex}.

Using a syntax similar to GNU utilities @code{flex} and @code{bison}, it
is possible to directly include C source text and comments verbatim into
the generated output file.  This is accomplished by enclosing the region
inside left-justified surrounding @code{%@{}, @code{%@}} pairs.  Here is
an input fragment based on the previous example that illustrates this
feature:

@group
@example
%@{
#include <assert.h>
/* This section of code is inserted directly into the output. */
int return_month_days (struct months *months, int is_leap_year);
%@}
struct months @{ char *name; int number; int days; int leap_days; @};
%%
january,   1, 31, 31
february,  2, 28, 29
march,     3, 31, 31
...
@end example
@end group

It is possible to omit the declaration section entirely.  In this case
the keyfile begins directly with the first keyword line, @emph{e.g.}:

@group
@example
january,   1, 31, 31
february,  2, 28, 29
march,     3, 31, 31
april,     4, 30, 30
...
@end example
@end group

@node Keywords, Functions, Declarations, Input Format
@subsection Format for Keyword Entries

The second keyfile format section contains lines of keywords and any
associated attributes you might supply.  A line beginning with @samp{#}
in the first column is considered a comment.  Everything following the
@samp{#} is ignored, up to and including the following newline.

The first field of each non-comment line is always the key itself.  It
should be given as a simple name, @emph{i.e.}, without surrounding
string quotation marks, and be left-justified flush against the first
column.  In this context, a ``field'' is considered to extend up to, but
not include, the first blank, comma, or newline.  Here is a simple
example taken from a partial list of C reserved words:

@group
@example
# These are a few C reserved words, see the c.@code{gperf} file 
# for a complete list of ANSI C reserved words.
unsigned
sizeof
switch
signed
if
default
for
while
return
@end example
@end group

Note that unlike @code{flex} or @code{bison} the first @code{%%} marker
may be elided if the declaration section is empty.

Additional fields may optionally follow the leading keyword.  Fields
should be separated by commas, and terminate at the end of line.  What
these fields mean is entirely up to you; they are used to initialize the
elements of the user-defined @code{struct} provided by you in the
declaration section.  If the @samp{-t} option is @emph{not} enabled
these fields are simply ignored.  All previous examples except the last
one contain keyword attributes.

@node Functions,  , Keywords, Input Format
@subsection Including Additional C Functions

The optional third section also corresponds closely with conventions
found in @code{flex} and @code{bison}.  All text in this section,
starting at the final @code{%%} and extending to the end of the input
file, is included verbatim into the generated output file.  Naturally,
it is your responsibility to ensure that the code contained in this
section is valid C.

@node Output Format,  , Input Format, Description
@section Output Format for Generated C Code with @code{gperf}

Several options control how the generated C code appears on the standard
output.  Two C function are generated.  They are called @code{hash} and
@code{in_word_set}, although you may modify the name for
@code{in_word_set} with a command-line option.  Both functions require
two arguments, a string, @code{char *} @var{str}, and a length
parameter, @code{int} @var{len}.  Their default function prototypes are
as follows:

@group
@example
static int hash (char *str, int len);
int in_word_set (char *str, int len);
@end example
@end group

By default, the generated @code{hash} function returns an integer value
created by adding @var{len} to several user-specified @var{str} key
positions indexed into an @dfn{associated values} table stored in a
local static array.  The associated values table is constructed
internally by @code{gperf} and later output as a static local C array called
@var{hash_table}; its meaning and properties are described below.
@xref{Implementation}. The relevant key positions are specified via the
@samp{-k} option when running @code{gperf}, as detailed in the @emph{Options}
section below. @xref{Options}.

Two options, @samp{-g} (assume you are compiling with GNU C and its
@code{inline} feature) and @samp{-a} (assume ANSI C-style function
prototypes), alter the content of both the generated @code{hash} and
@code{in_word_set} routines.  However, function @code{in_word_set} may
be modified more extensively, in response to your option settings.  The
options that affect the @code{in_word_set} structure are:

@itemize @bullet
@table @samp
@item -p
Have function @code{in_word_set} return a pointer rather than a boolean.

@item -t
Make use of the user-defined @code{struct}.

@item -S @var{total switch statements}
Generate 1 or more C @code{switch} statement rather than use a large,
(and potentially sparse) static array.  Although the exact time and
space savings of this approach vary according to your C compiler's
degree of optimization, this method often results in smaller and faster
code.
@end table
@end itemize

If the @samp{-t}, @samp{-S}, and @samp{-p} options are omitted the
default action is to generate a @code{char *} array containing the keys,
together with additional null strings used for padding the array.  By
experimenting with the various input and output options, and timing the
resulting C code, you can determine the best option choices for
different keyword set characteristics.

@node Options, Bugs, Description, Top
@chapter Options to the @code{gperf} Utility

There are @emph{many} options to @code{gperf}.  They were added to make
the program more convenient for use with real applications.  ``On-line''
help is readily available via the @samp{-h} option.  Other options
include:

@itemize @bullet
@table @samp
@item -a
Generate ANSI Standard C code using function prototypes.  The default is
to use ``classic'' K&R C function declaration syntax.

@item -c
Generates C code that uses the @code{strncmp} function to perform
string comparisons.  The default action is to use @code{strcmp}.

@item -C
Makes the contents of all generated lookup tables constant, @emph{i.e.},
``readonly.''  Many compilers can generate more efficient code for this
by putting the tables in readonly memory.

@item -d
Enables the debugging option.  This produces verbose diagnostics to
``standard error'' when @code{gperf} is executing.  It is useful both for
maintaining the program and for determining whether a given set of
options is actually speeding up the search for a solution.  Some useful
information is dumped at the end of the program when the @samp{-d}
option is enabled.

@item -D
Handle keywords whose key position sets hash to duplicate values.
Duplicate hash values occur for two reasons:

@itemize @bullet
@item
Since @code{gperf} does not backtrack it is possible for it to process
all your input keywords without finding a unique mapping for each word.
However, frequently only a very small number of duplicates occur, and 
the majority of keys still require one probe into the table.
@item
Sometimes a set of keys may have the same names, but possess different
attributes.  With the -D option @code{gperf} treats all these keys as part of
an equivalence class and generates a perfect hash function with multiple
comparisons for duplicate keys.  It is up to you to completely
disambiguate the keywords by modifying the generated C code.  However,
@code{gperf} helps you out by organizing the output.
@end itemize

Option @samp{-D} is extremely useful for certain large or highly
redundant keyword sets, @emph{i.e.}, assembler instruction opcodes.
Using this option usually means that the generated hash function is no
longer perfect.  On the other hand, it permits @code{gperf} to work on
keyword sets that it otherwise could not handle.

@item -e @var{keyword delimiter list}
Allows the user to provide a string containing delimiters used to
separate keywords from their attributes.  The default is ",\n".  This
option is essential if you want to use keywords that have embedded
commas or newlines.  One useful trick is to use -e'TAB', where TAB is
the literal tab character.

@item -E
Define constant values using an enum local to the lookup function rather
than with #defines.  This also means that different lookup functions can
reside in the same file.  Thanks to James Clark (jjc at ai.mit.edu).

@item -f @var{iteration amount}
Generate the perfect hash function ``fast.''  This decreases @code{gperf}'s
running time at the cost of minimizing generated table-size.  The
iteration amount represents the number of times to iterate when
resolving a collision.  `0' means `iterate by the number of keywords.
This option is probably most useful when used in conjunction with options
@samp{-D} and/or @samp{-S} for @emph{large} keyword sets.

@item -g
Assume a GNU compiler, @emph{e.g.}, @code{g++} or @code{gcc}.  This
makes all generated routines use the ``inline'' keyword to remove the
cost of function calls.  Note that @samp{-g} does @emph{not} imply
@samp{-a}, since other non-ANSI C compilers may have provisions for a
function @code{inline} feature.

@item -G
Generate the static table of keywords as a static global variable,
rather than hiding it inside of the lookup function (which is the
default behavior).

@item -h
Prints a short summary on the meaning of each program option.  Aborts
further program execution.

@item -H @var{hash function name}
Allows you to specify the name for the generated hash function.  Default
name is `hash.'  This option permits the use of two hash tables in the
same file.

@item -i @var{initial value}
Provides an initial @var{value} for the associate values array.  Default
is 0.  Increasing the initial value helps inflate the final table size,
possibly leading to more time efficient keyword lookups.  Note that this
option is not particularly useful when @samp{-S} is used.  Also,
@samp{-i} is overriden when the @samp{-r} option is used.

@item -j @var{jump value}
Affects the ``jump value,'' @emph{i.e.}, how far to advance the
associated character value upon collisions.  @var{Jump value} is rounded
up to an odd number, the default is 5.  If the @var{jump value} is 0 @code{gper
f}
jumps by random amounts.

@item -k @var{keys}
Allows selection of the character key positions used in the keywords'
hash function. The allowable choices range between 1-126, inclusive.