                   _________________________________

                    NAMED CONSTANT GENERATOR README

                           Johannes Willkomm
                   _________________________________


Table of Contents
_________________

1 About
2 Installing Named Constant Generator
3 Using Named Constant Generator
.. 3.1 Defining named constants
.. 3.2 Generating the C code
.. 3.3 Using the generated code in your program
4 About this file





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 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 GENNC_HOME 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
  `----


3 Using Named Constant Generator
================================

3.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.


3.2 Generating the C code
~~~~~~~~~~~~~~~~~~~~~~~~~

  Generate the corresponding C files by invoking gennc on the definition
  file:

  ,----
  | gennc example.ncd.xml
  `----

  The following files are generated:

  - [./example.ncd.enum.hh]
  Contains the enum definition
  - [./example.ncd.hh]
  Contains the declarations of generated functions.
  - [./example.ncd.cc]
  Contains the generated functions


3.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.


4 About this file
=================

  This file is part of Named Constant Generator. Copyright (C) 2013
  Johannes Willkomm. See the file gennc for copying conditions.
