Adwaith-Rajesh/gperf
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/gperf.git synced 2025-12-02 21:19:24 +00:00
Code Activity

regenerated

Browse Source
This commit is contained in:
Brendan Kehoe
2009-02-01 12:23:37 +00:00
parent c9bd4009aa
commit cfbb6bdc79
16 changed files with 7636 additions and 5495 deletions
Download Patch File Download Diff File Expand all files Collapse all files

264
doc/gperf_5.html
View File

@@ -1,22 +1,23 @@
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.51
from gperf.texi on 31 March 2007 -->
<!-- This HTML file has been created by texi2html 1.52b
from gperf.texi on 1 February 2009 -->
<TITLE>Perfect Hash Function Generator - 3 High-Level Description of GNU gperf</TITLE>
<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
<TITLE>Perfect Hash Function Generator - 4 High-Level Description of GNU gperf</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="gperf_1.html">first</A>, <A HREF="gperf_4.html">previous</A>, <A HREF="gperf_6.html">next</A>, <A HREF="gperf_10.html">last</A> section, <A HREF="gperf_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC7" HREF="gperf_toc.html#TOC7">3 High-Level Description of GNU <CODE>gperf</CODE></A></H1>
<H1><A NAME="SEC5" HREF="gperf_toc.html#TOC5">4 High-Level Description of GNU <CODE>gperf</CODE></A></H1>
<P>
The perfect hash function generator <CODE>gperf</CODE> reads a set of
"keywords" from an input file (or from the standard input by
“keywords” from an input file (or from the standard input by
default). It attempts to derive a perfect hashing function that
recognizes a member of the <STRONG>static keyword set</STRONG> with at most a
recognizes a member of the <EM>static keyword set</EM> with at most a
single probe into the lookup table. If <CODE>gperf</CODE> succeeds in
generating such a function it produces a pair of C source code routines
that perform hashing and table lookup recognition. All generated C code
@@ -46,14 +47,14 @@ Experimentation is the key to getting the most from <CODE>gperf</CODE>.
</P>
<H2><A NAME="SEC8" HREF="gperf_toc.html#TOC8">3.1 Input Format to <CODE>gperf</CODE></A></H2>
<H2><A NAME="SEC6" HREF="gperf_toc.html#TOC6">4.1 Input Format to <CODE>gperf</CODE></A></H2>
<P>
<A NAME="IDX4"></A>
<A NAME="IDX5"></A>
<A NAME="IDX6"></A>
<A NAME="IDX7"></A>
You can control the input file format by varying certain command-line
arguments, in particular the <SAMP>`-t'</SAMP> option. The input's appearance
arguments, in particular the <SAMP>&lsquo;-t&rsquo;</SAMP> option. The input's appearance
is similar to GNU utilities <CODE>flex</CODE> and <CODE>bison</CODE> (or UNIX
utilities <CODE>lex</CODE> and <CODE>yacc</CODE>). Here's an outline of the general
format:
@@ -76,7 +77,7 @@ input format for each section.
</P>
<P>
It is possible to omit the declaration section entirely, if the <SAMP>`-t'</SAMP>
It is possible to omit the declaration section entirely, if the <SAMP>&lsquo;-t&rsquo;</SAMP>
option is not given. In this case the input file begins directly with the
first keyword line, e.g.:
@@ -92,7 +93,7 @@ april
<H3><A NAME="SEC9" HREF="gperf_toc.html#TOC9">3.1.1 Declarations</A></H3>
<H3><A NAME="SEC7" HREF="gperf_toc.html#TOC7">4.1.1 Declarations</A></H3>
<P>
The keyword input file optionally contains a section for including
@@ -104,18 +105,18 @@ act like command-line options, as well as for providing a user-supplied
<H4><A NAME="SEC10" HREF="gperf_toc.html#TOC10">3.1.1.1 User-supplied <CODE>struct</CODE></A></H4>
<H4><A NAME="SEC8" HREF="gperf_toc.html#TOC8">4.1.1.1 User-supplied <CODE>struct</CODE></A></H4>
<P>
If the <SAMP>`-t'</SAMP> option (or, equivalently, the <SAMP>`%struct-type'</SAMP> declaration)
If the <SAMP>&lsquo;-t&rsquo;</SAMP> option (or, equivalently, the <SAMP>&lsquo;%struct-type&rsquo;</SAMP> declaration)
<EM>is</EM> enabled, you <EM>must</EM> provide a C <CODE>struct</CODE> as the last
component in the declaration section from the input file. The first
field in this struct must be of type <CODE>char *</CODE> or <CODE>const char *</CODE>
if the <SAMP>`-P'</SAMP> option is not given, or of type <CODE>int</CODE> if the option
<SAMP>`-P'</SAMP> (or, equivalently, the <SAMP>`%pic'</SAMP> declaration) is enabled.
This first field must be called <SAMP>`name'</SAMP>, although it is possible to modify
its name with the <SAMP>`-K'</SAMP> option (or, equivalently, the
<SAMP>`%define slot-name'</SAMP> declaration) described below.
if the <SAMP>&lsquo;-P&rsquo;</SAMP> option is not given, or of type <CODE>int</CODE> if the option
<SAMP>&lsquo;-P&rsquo;</SAMP> (or, equivalently, the <SAMP>&lsquo;%pic&rsquo;</SAMP> declaration) is enabled.
This first field must be called <SAMP>&lsquo;name&rsquo;</SAMP>, although it is possible to modify
its name with the <SAMP>&lsquo;-K&rsquo;</SAMP> option (or, equivalently, the
<SAMP>&lsquo;%define slot-name&rsquo;</SAMP> declaration) described below.
</P>
<P>
@@ -144,7 +145,7 @@ december, 12, 31, 31
<P>
<A NAME="IDX8"></A>
Separating the <CODE>struct</CODE> declaration from the list of keywords and
other fields are a pair of consecutive percent signs, <SAMP>`%%'</SAMP>,
other fields are a pair of consecutive percent signs, <SAMP>&lsquo;%%&rsquo;</SAMP>,
appearing left justified in the first column, as in the UNIX utility
<CODE>lex</CODE>.
@@ -164,7 +165,7 @@ january, 1, 31, 31
<H4><A NAME="SEC11" HREF="gperf_toc.html#TOC11">3.1.1.2 Gperf Declarations</A></H4>
<H4><A NAME="SEC9" HREF="gperf_toc.html#TOC9">4.1.1.2 Gperf Declarations</A></H4>
<P>
The declaration section can contain <CODE>gperf</CODE> declarations. They
@@ -177,16 +178,16 @@ There are three forms of declarations:
<OL>
<LI>
Declarations without argument, like <SAMP>`%compare-lengths'</SAMP>.
Declarations without argument, like <SAMP>&lsquo;%compare-lengths&rsquo;</SAMP>.
<LI>
Declarations with an argument, like <SAMP>`%switch=<VAR>count</VAR>'</SAMP>.
Declarations with an argument, like <SAMP>&lsquo;%switch=<VAR>count</VAR>&rsquo;</SAMP>.
<LI>
Declarations of names of entities in the output file, like
<SAMP>`%define lookup-function-name <VAR>name</VAR>'</SAMP>.
<SAMP>&lsquo;%define lookup-function-name <VAR>name</VAR>&rsquo;</SAMP>.
</OL>
<P>
@@ -200,7 +201,7 @@ The following <CODE>gperf</CODE> declarations are available.
</P>
<DL COMPACT>
<DT><SAMP>`%delimiters=<VAR>delimiter-list</VAR>'</SAMP>
<DT><SAMP>&lsquo;%delimiters=<VAR>delimiter-list</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX9"></A>
Allows you to provide a string containing delimiters used to
@@ -208,20 +209,20 @@ separate keywords from their attributes. The default is ",". This
option is essential if you want to use keywords that have embedded
commas or newlines.
<DT><SAMP>`%struct-type'</SAMP>
<DT><SAMP>&lsquo;%struct-type&rsquo;</SAMP>
<DD>
<A NAME="IDX10"></A>
Allows you to include a <CODE>struct</CODE> type declaration for generated
code; see above for an example.
<DT><SAMP>`%ignore-case'</SAMP>
<DT><SAMP>&lsquo;%ignore-case&rsquo;</SAMP>
<DD>
<A NAME="IDX11"></A>
Consider upper and lower case ASCII characters as equivalent. The string
comparison will use a case insignificant character comparison. Note that
locale dependent case mappings are ignored.
<DT><SAMP>`%language=<VAR>language-name</VAR>'</SAMP>
<DT><SAMP>&lsquo;%language=<VAR>language-name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX12"></A>
Instructs <CODE>gperf</CODE> to generate code in the language specified by the
@@ -229,72 +230,73 @@ option's argument. Languages handled are currently:
<DL COMPACT>
<DT><SAMP>`KR-C'</SAMP>
<DT><SAMP>&lsquo;KR-C&rsquo;</SAMP>
<DD>
Old-style K&#38;R C. This language is understood by old-style C compilers and
ANSI C compilers, but ANSI C compilers may flag warnings (or even errors)
because of lacking <SAMP>`const'</SAMP>.
because of lacking <SAMP>&lsquo;const&rsquo;</SAMP>.
<DT><SAMP>`C'</SAMP>
<DT><SAMP>&lsquo;C&rsquo;</SAMP>
<DD>
Common C. This language is understood by ANSI C compilers, and also by
old-style C compilers, provided that you <CODE>#define const</CODE> to empty
for compilers which don't know about this keyword.
<DT><SAMP>`ANSI-C'</SAMP>
<DT><SAMP>&lsquo;ANSI-C&rsquo;</SAMP>
<DD>
ANSI C. This language is understood by ANSI C compilers and C++ compilers.
ANSI C. This language is understood by ANSI C (C89, ISO C90) compilers,
ISO C99 compilers, and C++ compilers.
<DT><SAMP>`C++'</SAMP>
<DT><SAMP>&lsquo;C++&rsquo;</SAMP>
<DD>
C++. This language is understood by C++ compilers.
</DL>
The default is C.
<DT><SAMP>`%define slot-name <VAR>name</VAR>'</SAMP>
<DT><SAMP>&lsquo;%define slot-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX13"></A>
This declaration is only useful when option <SAMP>`-t'</SAMP> (or, equivalently, the
<SAMP>`%struct-type'</SAMP> declaration) has been given.
This declaration is only useful when option <SAMP>&lsquo;-t&rsquo;</SAMP> (or, equivalently, the
<SAMP>&lsquo;%struct-type&rsquo;</SAMP> declaration) has been given.
By default, the program assumes the structure component identifier for
the keyword is <SAMP>`name'</SAMP>. This option allows an arbitrary choice of
the keyword is <SAMP>&lsquo;name&rsquo;</SAMP>. This option allows an arbitrary choice of
identifier for this component, although it still must occur as the first
field in your supplied <CODE>struct</CODE>.
<DT><SAMP>`%define initializer-suffix <VAR>initializers</VAR>'</SAMP>
<DT><SAMP>&lsquo;%define initializer-suffix <VAR>initializers</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX14"></A>
This declaration is only useful when option <SAMP>`-t'</SAMP> (or, equivalently, the
<SAMP>`%struct-type'</SAMP> declaration) has been given.
This declaration is only useful when option <SAMP>&lsquo;-t&rsquo;</SAMP> (or, equivalently, the
<SAMP>&lsquo;%struct-type&rsquo;</SAMP> declaration) has been given.
It permits to specify initializers for the structure members following
<VAR>slot-name</VAR> in empty hash table entries. The list of initializers
should start with a comma. By default, the emitted code will
zero-initialize structure members following <VAR>slot-name</VAR>.
<DT><SAMP>`%define hash-function-name <VAR>name</VAR>'</SAMP>
<DT><SAMP>&lsquo;%define hash-function-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX15"></A>
Allows you to specify the name for the generated hash function. Default
name is <SAMP>`hash'</SAMP>. This option permits the use of two hash tables in
name is <SAMP>&lsquo;hash&rsquo;</SAMP>. This option permits the use of two hash tables in
the same file.
<DT><SAMP>`%define lookup-function-name <VAR>name</VAR>'</SAMP>
<DT><SAMP>&lsquo;%define lookup-function-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX16"></A>
Allows you to specify the name for the generated lookup function.
Default name is <SAMP>`in_word_set'</SAMP>. This option permits multiple
Default name is <SAMP>&lsquo;in_word_set&rsquo;</SAMP>. This option permits multiple
generated hash functions to be used in the same application.
<DT><SAMP>`%define class-name <VAR>name</VAR>'</SAMP>
<DT><SAMP>&lsquo;%define class-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX17"></A>
This option is only useful when option <SAMP>`-L C++'</SAMP> (or, equivalently,
the <SAMP>`%language=C++'</SAMP> declaration) has been given. It
This option is only useful when option <SAMP>&lsquo;-L C++&rsquo;</SAMP> (or, equivalently,
the <SAMP>&lsquo;%language=C++&rsquo;</SAMP> declaration) has been given. It
allows you to specify the name of generated C++ class. Default name is
<CODE>Perfect_Hash</CODE>.
<DT><SAMP>`%7bit'</SAMP>
<DT><SAMP>&lsquo;%7bit&rsquo;</SAMP>
<DD>
<A NAME="IDX18"></A>
This option specifies that all strings that will be passed as arguments
@@ -302,102 +304,102 @@ to the generated hash function and the generated lookup function will
solely consist of 7-bit ASCII characters (bytes in the range 0..127).
(Note that the ANSI C functions <CODE>isalnum</CODE> and <CODE>isgraph</CODE> do
<EM>not</EM> guarantee that a byte is in this range. Only an explicit
test like <SAMP>`c &#62;= 'A' &#38;&#38; c &#60;= 'Z''</SAMP> guarantees this.)
test like <SAMP>&lsquo;c &#62;= 'A' &#38;&#38; c &#60;= 'Z'&rsquo;</SAMP> guarantees this.)
<DT><SAMP>`%compare-lengths'</SAMP>
<DT><SAMP>&lsquo;%compare-lengths&rsquo;</SAMP>
<DD>
<A NAME="IDX19"></A>
Compare keyword lengths before trying a string comparison. This option
is mandatory for binary comparisons (see section <A HREF="gperf_5.html#SEC17">3.3 Use of NUL bytes</A>). It also might
is mandatory for binary comparisons (see section <A HREF="gperf_5.html#SEC15">4.3 Use of NUL bytes</A>). It also might
cut down on the number of string comparisons made during the lookup, since
keywords with different lengths are never compared via <CODE>strcmp</CODE>.
However, using <SAMP>`%compare-lengths'</SAMP> might greatly increase the size of the
However, using <SAMP>&lsquo;%compare-lengths&rsquo;</SAMP> might greatly increase the size of the
generated C code if the lookup table range is large (which implies that
the switch option <SAMP>`-S'</SAMP> or <SAMP>`%switch'</SAMP> is not enabled), since the length
the switch option <SAMP>&lsquo;-S&rsquo;</SAMP> or <SAMP>&lsquo;%switch&rsquo;</SAMP> is not enabled), since the length
table contains as many elements as there are entries in the lookup table.
<DT><SAMP>`%compare-strncmp'</SAMP>
<DT><SAMP>&lsquo;%compare-strncmp&rsquo;</SAMP>
<DD>
<A NAME="IDX20"></A>
Generates C code that uses the <CODE>strncmp</CODE> function to perform
string comparisons. The default action is to use <CODE>strcmp</CODE>.
<DT><SAMP>`%readonly-tables'</SAMP>
<DT><SAMP>&lsquo;%readonly-tables&rsquo;</SAMP>
<DD>
<A NAME="IDX21"></A>
Makes the contents of all generated lookup tables constant, i.e.,
"readonly". Many compilers can generate more efficient code for this
“readonly”. Many compilers can generate more efficient code for this
by putting the tables in readonly memory.
<DT><SAMP>`%enum'</SAMP>
<DT><SAMP>&lsquo;%enum&rsquo;</SAMP>
<DD>
<A NAME="IDX22"></A>
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 <CODE>&#60;jjc@ai.mit.edu&#62;</CODE>.
<DT><SAMP>`%includes'</SAMP>
<DT><SAMP>&lsquo;%includes&rsquo;</SAMP>
<DD>
<A NAME="IDX23"></A>
Include the necessary system include file, <CODE>&#60;string.h&#62;</CODE>, at the
beginning of the code. By default, this is not done; the user must
include this header file himself to allow compilation of the code.
<DT><SAMP>`%global-table'</SAMP>
<DT><SAMP>&lsquo;%global-table&rsquo;</SAMP>
<DD>
<A NAME="IDX24"></A>
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).
<DT><SAMP>`%pic'</SAMP>
<DT><SAMP>&lsquo;%pic&rsquo;</SAMP>
<DD>
<A NAME="IDX25"></A>
Optimize the generated table for inclusion in shared libraries. This
reduces the startup time of programs using a shared library containing
the generated code. If the <SAMP>`%struct-type'</SAMP> declaration (or,
equivalently, the option <SAMP>`-t'</SAMP>) is also given, the first field of the
user-defined struct must be of type <SAMP>`int'</SAMP>, not <SAMP>`char *'</SAMP>, because
the generated code. If the <SAMP>&lsquo;%struct-type&rsquo;</SAMP> declaration (or,
equivalently, the option <SAMP>&lsquo;-t&rsquo;</SAMP>) is also given, the first field of the
user-defined struct must be of type <SAMP>&lsquo;int&rsquo;</SAMP>, not <SAMP>&lsquo;char *&rsquo;</SAMP>, because
it will contain offsets into the string pool instead of actual strings.
To convert such an offset to a string, you can use the expression
<SAMP>`stringpool + <VAR>o</VAR>'</SAMP>, where <VAR>o</VAR> is the offset. The string pool
name can be changed through the <SAMP>`%define string-pool-name'</SAMP> declaration.
<SAMP>&lsquo;stringpool + <VAR>o</VAR>&rsquo;</SAMP>, where <VAR>o</VAR> is the offset. The string pool
name can be changed through the <SAMP>&lsquo;%define string-pool-name&rsquo;</SAMP> declaration.
<DT><SAMP>`%define string-pool-name <VAR>name</VAR>'</SAMP>
<DT><SAMP>&lsquo;%define string-pool-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX26"></A>
Allows you to specify the name of the generated string pool created by
the declaration <SAMP>`%pic'</SAMP> (or, equivalently, the option <SAMP>`-P'</SAMP>).
The default name is <SAMP>`stringpool'</SAMP>. This declaration permits the use of
two hash tables in the same file, with <SAMP>`%pic'</SAMP> and even when the
<SAMP>`%global-table'</SAMP> declaration (or, equivalently, the option <SAMP>`-G'</SAMP>)
the declaration <SAMP>&lsquo;%pic&rsquo;</SAMP> (or, equivalently, the option <SAMP>&lsquo;-P&rsquo;</SAMP>).
The default name is <SAMP>&lsquo;stringpool&rsquo;</SAMP>. This declaration permits the use of
two hash tables in the same file, with <SAMP>&lsquo;%pic&rsquo;</SAMP> and even when the
<SAMP>&lsquo;%global-table&rsquo;</SAMP> declaration (or, equivalently, the option <SAMP>&lsquo;-G&rsquo;</SAMP>)
is given.
<DT><SAMP>`%null-strings'</SAMP>
<DT><SAMP>&lsquo;%null-strings&rsquo;</SAMP>
<DD>
<A NAME="IDX27"></A>
Use NULL strings instead of empty strings for empty keyword table entries.
This reduces the startup time of programs using a shared library containing
the generated code (but not as much as the declaration <SAMP>`%pic'</SAMP>), at the
the generated code (but not as much as the declaration <SAMP>&lsquo;%pic&rsquo;</SAMP>), at the
expense of one more test-and-branch instruction at run time.
<DT><SAMP>`%define word-array-name <VAR>name</VAR>'</SAMP>
<DT><SAMP>&lsquo;%define word-array-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX28"></A>
Allows you to specify the name for the generated array containing the
hash table. Default name is <SAMP>`wordlist'</SAMP>. This option permits the
use of two hash tables in the same file, even when the option <SAMP>`-G'</SAMP>
(or, equivalently, the <SAMP>`%global-table'</SAMP> declaration) is given.
hash table. Default name is <SAMP>&lsquo;wordlist&rsquo;</SAMP>. This option permits the
use of two hash tables in the same file, even when the option <SAMP>&lsquo;-G&rsquo;</SAMP>
(or, equivalently, the <SAMP>&lsquo;%global-table&rsquo;</SAMP> declaration) is given.
<DT><SAMP>`%define length-table-name <VAR>name</VAR>'</SAMP>
<DT><SAMP>&lsquo;%define length-table-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX29"></A>
Allows you to specify the name for the generated array containing the
length table. Default name is <SAMP>`lengthtable'</SAMP>. This option permits the
use of two length tables in the same file, even when the option <SAMP>`-G'</SAMP>
(or, equivalently, the <SAMP>`%global-table'</SAMP> declaration) is given.
length table. Default name is <SAMP>&lsquo;lengthtable&rsquo;</SAMP>. This option permits the
use of two length tables in the same file, even when the option <SAMP>&lsquo;-G&rsquo;</SAMP>
(or, equivalently, the <SAMP>&lsquo;%global-table&rsquo;</SAMP> declaration) is given.
<DT><SAMP>`%switch=<VAR>count</VAR>'</SAMP>
<DT><SAMP>&lsquo;%switch=<VAR>count</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX30"></A>
Causes the generated C code to use a <CODE>switch</CODE> statement scheme,
@@ -410,7 +412,7 @@ value of 2 generates 2 tables with 1/2 the elements in each
correctly generate code for large <CODE>switch</CODE> statements. This option
was inspired in part by Keith Bostic's original C program.
<DT><SAMP>`%omit-struct-type'</SAMP>
<DT><SAMP>&lsquo;%omit-struct-type&rsquo;</SAMP>
<DD>
<A NAME="IDX31"></A>
Prevents the transfer of the type declaration to the output file. Use
@@ -419,7 +421,7 @@ this option if the type is already defined elsewhere.
<H4><A NAME="SEC12" HREF="gperf_toc.html#TOC12">3.1.1.3 C Code Inclusion</A></H4>
<H4><A NAME="SEC10" HREF="gperf_toc.html#TOC10">4.1.1.3 C Code Inclusion</A></H4>
<P>
<A NAME="IDX32"></A>
@@ -427,7 +429,7 @@ this option if the type is already defined elsewhere.
Using a syntax similar to GNU utilities <CODE>flex</CODE> and <CODE>bison</CODE>, 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 <SAMP>`%{'</SAMP>, <SAMP>`%}'</SAMP> pairs. Here is
inside left-justified surrounding <SAMP>&lsquo;%{&rsquo;</SAMP>, <SAMP>&lsquo;%}&rsquo;</SAMP> pairs. Here is
an input fragment based on the previous example that illustrates this
feature:
@@ -449,14 +451,14 @@ march, 3, 31, 31
<H3><A NAME="SEC13" HREF="gperf_toc.html#TOC13">3.1.2 Format for Keyword Entries</A></H3>
<H3><A NAME="SEC11" HREF="gperf_toc.html#TOC11">4.1.2 Format for Keyword Entries</A></H3>
<P>
The second input file format section contains lines of keywords and any
associated attributes you might supply. A line beginning with <SAMP>`#'</SAMP>
associated attributes you might supply. A line beginning with <SAMP>&lsquo;#&rsquo;</SAMP>
in the first column is considered a comment. Everything following the
<SAMP>`#'</SAMP> is ignored, up to and including the following newline. A line
beginning with <SAMP>`%'</SAMP> in the first column is an option declaration and
<SAMP>&lsquo;#&rsquo;</SAMP> is ignored, up to and including the following newline. A line
beginning with <SAMP>&lsquo;%&rsquo;</SAMP> in the first column is an option declaration and
must not occur within the keywords section.
</P>
@@ -467,7 +469,7 @@ string quotation marks, or as a string enclosed in double-quotes, in
C syntax, possibly with backslash escapes like <CODE>\"</CODE> or <CODE>\234</CODE>
or <CODE>\xa8</CODE>. In either case, it must start right at the beginning
of the line, without leading whitespace.
In this context, a "field" is considered to extend up to, but
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:
@@ -488,7 +490,7 @@ return
</PRE>
<P>
Note that unlike <CODE>flex</CODE> or <CODE>bison</CODE> the first <SAMP>`%%'</SAMP> marker
Note that unlike <CODE>flex</CODE> or <CODE>bison</CODE> the first <SAMP>&lsquo;%%&rsquo;</SAMP> marker
may be elided if the declaration section is empty.
</P>
@@ -497,20 +499,20 @@ 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</CODE> provided by you in the
declaration section. If the <SAMP>`-t'</SAMP> option (or, equivalently, the
<SAMP>`%struct-type'</SAMP> declaration) is <EM>not</EM> enabled
declaration section. If the <SAMP>&lsquo;-t&rsquo;</SAMP> option (or, equivalently, the
<SAMP>&lsquo;%struct-type&rsquo;</SAMP> declaration) is <EM>not</EM> enabled
these fields are simply ignored. All previous examples except the last
one contain keyword attributes.
</P>
<H3><A NAME="SEC14" HREF="gperf_toc.html#TOC14">3.1.3 Including Additional C Functions</A></H3>
<H3><A NAME="SEC12" HREF="gperf_toc.html#TOC12">4.1.3 Including Additional C Functions</A></H3>
<P>
The optional third section also corresponds closely with conventions
found in <CODE>flex</CODE> and <CODE>bison</CODE>. All text in this section,
starting at the final <SAMP>`%%'</SAMP> and extending to the end of the input
starting at the final <SAMP>&lsquo;%%&rsquo;</SAMP> 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.
@@ -518,12 +520,12 @@ section is valid C.
</P>
<H3><A NAME="SEC15" HREF="gperf_toc.html#TOC15">3.1.4 Where to place directives for GNU <CODE>indent</CODE>.</A></H3>
<H3><A NAME="SEC13" HREF="gperf_toc.html#TOC13">4.1.4 Where to place directives for GNU <CODE>indent</CODE>.</A></H3>
<P>
If you want to invoke GNU <CODE>indent</CODE> on a <CODE>gperf</CODE> input file,
you will see that GNU <CODE>indent</CODE> doesn't understand the <SAMP>`%%'</SAMP>,
<SAMP>`%{'</SAMP> and <SAMP>`%}'</SAMP> directives that control <CODE>gperf</CODE>'s
you will see that GNU <CODE>indent</CODE> doesn't understand the <SAMP>&lsquo;%%&rsquo;</SAMP>,
<SAMP>&lsquo;%{&rsquo;</SAMP> and <SAMP>&lsquo;%}&rsquo;</SAMP> directives that control <CODE>gperf</CODE>'s
interpretation of the input file. Therefore you have to insert some
directives for GNU <CODE>indent</CODE>. More precisely, assuming the most
general input file structure
@@ -543,7 +545,7 @@ functions
</PRE>
<P>
you would insert <SAMP>`*INDENT-OFF*'</SAMP> and <SAMP>`*INDENT-ON*'</SAMP> comments
you would insert <SAMP>&lsquo;*INDENT-OFF*&rsquo;</SAMP> and <SAMP>&lsquo;*INDENT-ON*&rsquo;</SAMP> comments
as follows:
</P>
@@ -566,7 +568,7 @@ functions
<H2><A NAME="SEC16" HREF="gperf_toc.html#TOC16">3.2 Output Format for Generated C Code with <CODE>gperf</CODE></A></H2>
<H2><A NAME="SEC14" HREF="gperf_toc.html#TOC14">4.2 Output Format for Generated C Code with <CODE>gperf</CODE></A></H2>
<P>
<A NAME="IDX34"></A>
@@ -586,12 +588,12 @@ function prototypes are as follows:
<DD><A NAME="IDX35"></A>
By default, the generated <CODE>hash</CODE> function returns an integer value
created by adding <VAR>len</VAR> to several user-specified <VAR>str</VAR> byte
positions indexed into an <STRONG>associated values</STRONG> table stored in a
positions indexed into an <EM>associated values</EM> table stored in a
local static array. The associated values table is constructed
internally by <CODE>gperf</CODE> and later output as a static local C array
called <SAMP>`hash_table'</SAMP>. The relevant selected positions (i.e. indices
into <VAR>str</VAR>) are specified via the <SAMP>`-k'</SAMP> option when running
<CODE>gperf</CODE>, as detailed in the <EM>Options</EM> section below (see section <A HREF="gperf_6.html#SEC18">4 Invoking <CODE>gperf</CODE></A>).
called <SAMP>&lsquo;hash_table&rsquo;</SAMP>. The relevant selected positions (i.e. indices
into <VAR>str</VAR>) are specified via the <SAMP>&lsquo;-k&rsquo;</SAMP> option when running
<CODE>gperf</CODE>, as detailed in the <EM>Options</EM> section below (see section <A HREF="gperf_6.html#SEC17">5 Invoking <CODE>gperf</CODE></A>).
</DL>
</P>
@@ -600,18 +602,18 @@ into <VAR>str</VAR>) are specified via the <SAMP>`-k'</SAMP> option when running
<DT><U>Function:</U> <B>in_word_set</B> <I>(const char * <VAR>str</VAR>, unsigned int <VAR>len</VAR>)</I>
<DD><A NAME="IDX36"></A>
If <VAR>str</VAR> is in the keyword set, returns a pointer to that
keyword. More exactly, if the option <SAMP>`-t'</SAMP> (or, equivalently, the
<SAMP>`%struct-type'</SAMP> declaration) was given, it returns
keyword. More exactly, if the option <SAMP>&lsquo;-t&rsquo;</SAMP> (or, equivalently, the
<SAMP>&lsquo;%struct-type&rsquo;</SAMP> declaration) was given, it returns
a pointer to the matching keyword's structure. Otherwise it returns
<CODE>NULL</CODE>.
</DL>
</P>
<P>
If the option <SAMP>`-c'</SAMP> (or, equivalently, the <SAMP>`%compare-strncmp'</SAMP>
If the option <SAMP>&lsquo;-c&rsquo;</SAMP> (or, equivalently, the <SAMP>&lsquo;%compare-strncmp&rsquo;</SAMP>
declaration) is not used, <VAR>str</VAR> must be a NUL terminated
string of exactly length <VAR>len</VAR>. If <SAMP>`-c'</SAMP> (or, equivalently, the
<SAMP>`%compare-strncmp'</SAMP> declaration) is used, <VAR>str</VAR> must
string of exactly length <VAR>len</VAR>. If <SAMP>&lsquo;-c&rsquo;</SAMP> (or, equivalently, the
<SAMP>&lsquo;%compare-strncmp&rsquo;</SAMP> declaration) is used, <VAR>str</VAR> must
simply be an array of <VAR>len</VAR> bytes and does not need to be NUL
terminated.
@@ -623,15 +625,15 @@ options:
</P>
<DL COMPACT>
<DT><SAMP>`-t'</SAMP>
<DT><SAMP>&lsquo;-t&rsquo;</SAMP>
<DD>
<DT><SAMP>`--struct-type'</SAMP>
<DT><SAMP>&lsquo;--struct-type&rsquo;</SAMP>
<DD>
Make use of the user-defined <CODE>struct</CODE>.
<DT><SAMP>`-S <VAR>total-switch-statements</VAR>'</SAMP>
<DT><SAMP>&lsquo;-S <VAR>total-switch-statements</VAR>&rsquo;</SAMP>
<DD>
<DT><SAMP>`--switch=<VAR>total-switch-statements</VAR>'</SAMP>
<DT><SAMP>&lsquo;--switch=<VAR>total-switch-statements</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX37"></A>
Generate 1 or more C <CODE>switch</CODE> statement rather than use a large,
@@ -642,8 +644,8 @@ code.
</DL>
<P>
If the <SAMP>`-t'</SAMP> and <SAMP>`-S'</SAMP> options (or, equivalently, the
<SAMP>`%struct-type'</SAMP> and <SAMP>`%switch'</SAMP> declarations) are omitted, the default
If the <SAMP>&lsquo;-t&rsquo;</SAMP> and <SAMP>&lsquo;-S&rsquo;</SAMP> options (or, equivalently, the
<SAMP>&lsquo;%struct-type&rsquo;</SAMP> and <SAMP>&lsquo;%switch&rsquo;</SAMP> declarations) are omitted, the default
action
is to generate a <CODE>char *</CODE> array containing the keywords, together with
additional empty strings used for padding the array. By experimenting
@@ -654,7 +656,7 @@ set characteristics.
</P>
<H2><A NAME="SEC17" HREF="gperf_toc.html#TOC17">3.3 Use of NUL bytes</A></H2>
<H2><A NAME="SEC15" HREF="gperf_toc.html#TOC15">4.3 Use of NUL bytes</A></H2>
<P>
<A NAME="IDX38"></A>
@@ -668,7 +670,7 @@ must be NUL terminated and have exactly length <VAR>len</VAR>.
</P>
<P>
If option <SAMP>`-c'</SAMP> (or, equivalently, the <SAMP>`%compare-strncmp'</SAMP>
If option <SAMP>&lsquo;-c&rsquo;</SAMP> (or, equivalently, the <SAMP>&lsquo;%compare-strncmp&rsquo;</SAMP>
declaration) is used, then the <VAR>str</VAR> argument does not need
to be NUL terminated. The code generated by <CODE>gperf</CODE> will only
access the first <VAR>len</VAR>, not <VAR>len+1</VAR>, bytes starting at <VAR>str</VAR>.
@@ -677,13 +679,39 @@ bytes.
</P>
<P>
If option <SAMP>`-l'</SAMP> (or, equivalently, the <SAMP>`%compare-lengths'</SAMP>
If option <SAMP>&lsquo;-l&rsquo;</SAMP> (or, equivalently, the <SAMP>&lsquo;%compare-lengths&rsquo;</SAMP>
declaration) is used, then the hash table performs binary
comparison. The keywords in the input file may contain NUL bytes,
written in string syntax as <CODE>\000</CODE> or <CODE>\x00</CODE>, and the code
generated by <CODE>gperf</CODE> will treat NUL like any other byte.
Also, in this case the <SAMP>`-c'</SAMP> option (or, equivalently, the
<SAMP>`%compare-strncmp'</SAMP> declaration) is ignored.
Also, in this case the <SAMP>&lsquo;-c&rsquo;</SAMP> option (or, equivalently, the
<SAMP>&lsquo;%compare-strncmp&rsquo;</SAMP> declaration) is ignored.
</P>
<H2><A NAME="SEC16" HREF="gperf_toc.html#TOC16">4.4 The Copyright of the Output</A></H2>
<P>
<A NAME="IDX39"></A>
</P>
<P>
<CODE>gperf</CODE> is under GPL, but that does not cause the output produced
by <CODE>gperf</CODE> to be under GPL. The reason is that the output contains
only small pieces of text that come directly from <CODE>gperf</CODE>'s source
code -- only about 7 lines long, too small for being significant --, and
therefore the output is not a “work based on <CODE>gperf</CODE>” (in the
sense of the GPL version 3).
</P>
<P>
On the other hand, the output produced by <CODE>gperf</CODE> contains
essentially all of the input file. Therefore the output is a
“derivative work” of the input (in the sense of U.S. copyright law);
and its copyright status depends on the copyright of the input. For most
software licenses, the result is that the the output is under the same
license, with the same copyright holder, as the input that was passed to
<CODE>gperf</CODE>.
</P>
<P><HR><P>