diff options
Diffstat (limited to 'doc/gperf.texi')
| -rw-r--r-- | doc/gperf.texi | 89 |
1 files changed, 84 insertions, 5 deletions
diff --git a/doc/gperf.texi b/doc/gperf.texi index 0dc1fbe..51282e9 100644 --- a/doc/gperf.texi +++ b/doc/gperf.texi @@ -17,7 +17,7 @@ @c some day we should @include version.texi instead of defining @c these values at hand. -@set UPDATED 20 December 2009 +@set UPDATED 11 January 2011 @set EDITION 3.1 @set VERSION 3.1 @c --------------------- @@ -40,7 +40,7 @@ This file documents the features of the GNU Perfect Hash Function Generator @value{VERSION}. -Copyright @copyright{} 1989-2009 Free Software Foundation, Inc. +Copyright @copyright{} 1989-2011 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -78,7 +78,7 @@ Software Foundation instead of in the original English. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1989-2009 Free Software Foundation, Inc. +Copyright @copyright{} 1989-2011 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of @@ -133,6 +133,7 @@ High-Level Description of GNU @code{gperf} * Input Format:: Input Format to @code{gperf} * Output Format:: Output Format for Generated C Code with @code{gperf} * Binary Strings:: Use of NUL bytes +* Controlling Identifiers:: Avoiding collisions of identifiers * Output Copyright:: The Copyright of the Output. Input Format to @code{gperf} @@ -291,6 +292,7 @@ efficiently identify their respective reserved keywords. * Input Format:: Input Format to @code{gperf} * Output Format:: Output Format for Generated C Code with @code{gperf} * Binary Strings:: Use of NUL bytes +* Controlling Identifiers:: Avoiding collisions of identifiers * Output Copyright:: The Copyright of the Output. @end menu @@ -618,6 +620,15 @@ This reduces the startup time of programs using a shared library containing the generated code (but not as much as the declaration @samp{%pic}), at the expense of one more test-and-branch instruction at run time. +@item %define constants-prefix @var{prefix} +@cindex @samp{%define constants-prefix} +Allows you to specify a prefix for the constants @code{TOTAL_KEYWORDS}, +@code{MIN_WORD_LENGTH}, @code{MAX_WORD_LENGTH}, and so on. This option +permits the use of two hash tables in the same file, even when the option +@samp{-E} (or, equivalently, the @samp{%enum} declaration) is not given or +the option @samp{-G} (or, equivalently, the @samp{%global-table} declaration) +is given. + @item %define word-array-name @var{name} @cindex @samp{%define word-array-name} Allows you to specify the name for the generated array containing the @@ -846,7 +857,7 @@ 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 Binary Strings, Output Copyright, Output Format, Description +@node Binary Strings, Controlling Identifiers, Output Format, Description @section Use of NUL bytes @cindex NUL @@ -871,7 +882,65 @@ generated by @code{gperf} will treat NUL like any other byte. Also, in this case the @samp{-c} option (or, equivalently, the @samp{%compare-strncmp} declaration) is ignored. -@node Output Copyright, , Binary Strings, Description +@node Controlling Identifiers, Output Copyright, Binary Strings, Description +@section Controlling Identifiers + +The identifiers of the functions, tables, and constants defined by the code +generated by @code{gperf} can be controlled through @code{gperf} declarations +or the equivalent command-line options. This is useful for three purposes: + +@itemize +@item +Esthetics of the generated code. + +For this purpose, just use the available declarations or options at will. + +@item +Controlling the exported identifiers of a library. + +Assume you include code generated by @code{gperf} in a library, and to +avoid collisions with other libraries, you want to ensure that all exported +identifiers of this library start with a certain prefix. + +By default, the only exported identifier is the lookup function. You can +therefore use the option @samp{-N} (or, equivalently, the +@samp{%define lookup-function-name} declaration). + +When you use the option @samp{-L C++} (or, equivalently, the +@samp{%language=C++} declaration), the only exported entity is a class. +You control its name through the option @samp{-Z} (or, equivalently, the +@samp{%define class-name} declaration). + +@item +Allowing multiple @code{gperf} generated codes in a single compilation unit. + +Assume you invoke @code{gperf} multiple times, with different input files, +and want the generated code to included from the same source file. In this +case, you have to customize not only the exported identifiers, but also the +names of functions with @samp{static} scope, types, and constants. + +By default, you will have to deal with the lookup function, the hash +function, and the constants. You should therefore use the option @samp{-N} +(or, equivalently, the @samp{%define lookup-function-name} declaration), +the option @samp{-H} (or, equivalently, the +@samp{%define hash-function-name} declaration), and the option +@samp{--constants-prefix} (or, equivalently, the +@samp{%define constants-prefix} declaration). + +If you use the option @samp{-G} (or, equivalently, the @samp{%global-table} +declaration), you will also have to deal with the word array, the length +table if present, and the string pool if present. This means: You should +use the option @samp{-W} (or, equivalently, the +@samp{%define word-array-name} declaration). If you use the option +@samp{-l} (or, equivalently, the @samp{%compare-lengths} declaration), you +should use the option @samp{--length-table-name} (or, equivalently, the +@samp{%define length-table-name} declaration). If you use the option +@samp{-P} (or, equivalently, the @samp{%pic} declaration), you should use +the option @samp{-Q} (or, equivalently, the @samp{%define string-pool-name} +declaration). +@end itemize + +@node Output Copyright, , Controlling Identifiers, Description @section The Copyright of the Output @cindex Copyright @@ -1078,6 +1147,7 @@ by putting the tables in readonly memory. @item -E @itemx --enum +@cindex Constants definition 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{<jjc@@ai.mit.edu>}. @@ -1120,6 +1190,15 @@ This reduces the startup time of programs using a shared library containing the generated code (but not as much as option @samp{-P}), at the expense of one more test-and-branch instruction at run time. +@itemx --constants-prefix=@var{prefix} +@cindex Constants prefix +Allows you to specify a prefix for the constants @code{TOTAL_KEYWORDS}, +@code{MIN_WORD_LENGTH}, @code{MAX_WORD_LENGTH}, and so on. This option +permits the use of two hash tables in the same file, even when the option +@samp{-E} (or, equivalently, the @samp{%enum} declaration) is not given or +the option @samp{-G} (or, equivalently, the @samp{%global-table} declaration) +is given. + @item -W @var{hash-table-array-name} @itemx --word-array-name=@var{hash-table-array-name} @cindex Array name |