New option --constants-prefix.

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