Named Constant Generator README
Table of Contents
1 About
Named Constant Generator (GenNC) is a utility to define and maintain sets of named constants (enumerations) in C and C++ software. Named constants are defined by a XML documents in a simple format. The program gennc generates code from this definition that not only contains an enum definition corresponding to the input, but also a set of utility functions. These offer the following functionality:
- Convert from constant values (integers) to names
- Convert names (case insensitive) to constant values (integers)
- Inquire number of constant values
- Enumerate constant values
These function allow the use of user friendly names instead of numbers in option processing. Since the conversion functions are generated, they are guaranteed to be consistent. A common prefix can be defined for the enumeration names, which is not considered by the name to value conversion, allowing both save programming and easy usage. The functions can generated as plain C functions of as static class methods.
2 Obtaining
Named Constant Generator is kindly hosted at the Savannah site Savannah.nongnu.org. The main project site is https://savannah.nongnu.org/projects/named-constant/ and the project homepage is http://www.nongnu.org/named-constant/.
Download the latest version in source from http://download.savannah.gnu.org/releases/named-constant/. You also find there .deb packages for the Debian and Ubuntu distributions.
3 Installing Named Constant Generator
On the command line, type:
make install prefix=/usr/local/named-constant
To install to directory /usr/local/named-constant. The default directory is /usr.
When installed to a directory other then /usr, set the environment variable GENNCHOME to the installation directory:
export GENNC_HOME=/usr/local/named-constant
Also add the bin subdirectory to the PATH:
export PATH=$PATH:$GENNC_HOME/bin
4 Using Named Constant Generator
4.1 Defining named constants
Define your named constants using an XML file. As an example refer to ./example.ncd.xml:
<ncdef name="demo" c-prefix="CONSTANT_">
<c val="0" name="A">
<comment>Constant A</comment>
</c>
<c val="1" name="B">
<comment>Constant B</comment>
</c>
<c val="2" name="C">
<comment>Constant C</comment>
</c>
<c name="D">
<comment>Constant D</comment>
</c>
<c val="4" name="E">
<comment>Constant E</comment>
</c>
</ncdef>
The val and c-prefix attributes are optional.
4.2 Generating the C code
Generate the corresponding C files by invoking gennc on the definition file, in this case using the "function mode", which means that plain C++ functions are generated:
gennc -f example.ncd.xml
The following files are generated:
Contains the enum definition
Contains the declarations of generated functions.
Contains the generated functions
4.3 Using the generated code in your program
Possibly the easiest way is to include all three generated function at appropriate locations in your C or C++ project. Just make sure that the .ncd.cc file is included only in one compilation unit, for example in the file containing the main function.
5 About this file
This file is part of Named Constant Generator. Copyright (C) 2013 Johannes Willkomm. See the file gennc for copying conditions.