keyval2cc

Name

keyval2cc — Converts XML <keyval> files to a C++ configuration class.

Synopsis

configure [[ -n TEXT ] | [ --name TEXT ]] [[ --reloc-cfg FILENAME ]] [[ --namespace TEXT ]] [[ -t true|false ] | [ --templates true|false ]] [[ -l FILENAME ] | [ --log-file FILENAME ]] [[ --install-query TEXT ]]

Description

The keyval2cc treats a <keyval> file as a represention of configuration for a application. Using the entities defined in the <keyval> XML source file, it then creates the following:

NAME_config.hh: A C++ header file defining a class which one can use to work with the configuration.
NAME_config.cc: The C++ code necessary to implement the class defined in NAME_config.hh.
NAME_config.m4i: A file of m4 macros that can be used to document the configuration file used.
NAME_config.cfg: A sample (template) configuration file showing both the format and default values for the configurable parameters.

The general goal is to reduce the amount of work required by a developer to maintain consistency in way a applications configuration is handled. As both C++ code, documentation, and sample configuration files are all generated from a single XML source file, consistency is guaranteed.

A tutorial for using this script is available in the xml-keyval package document. It will take you through the steps in creating a C++ application.

Options

The following command line options are available:

[[ -n TEXT ] | [ --name TEXT ]]: This utility is designed to work with a set of files all having a root NAME. This option is used to specify the root NAME. This utility assumes that NAME_config.xml will be the source XML file. This utility can then generate NAME_config.hh, NAME_config.cc, NAME_config.m4i, and NAME_config.cfg. In addition, when templates have not been disabled, it will also generate a template NAME_config.xml if it doesn't yet exist.
[[ --reloc-cfg FILENAME ]]: By default, a template configuration file is produced in the current directory with the name of NAME_config.cfg. Use this option, if you would like the template configuration file relocated to a different file location. Specify the full file name you want it to be placed under. For example --reloc-cfg $APAHOME/src/package/sdsimu.cfg.
[[ --namespace TEXT ]]: Use this option if you need to specify a namespace value other than the default of lp. This would only be necessary when creating configuration definitions for code outside of the GAIapa package. The only well known namespace values at this time are lp and nlib.
[[ -t true|false ] | [ --templates true|false ]]: This utility will stub in a template file to get you off on the right foot. Unless you disable this feature, it will generate a template version of NAME_config.xml. However, this utility never replaces NAME_config.xml if it already exists.
[[ -l FILENAME ] | [ --log-file FILENAME ]]: If you are encountering errors when running keyval2cc, try using this option and examine the log file after running keyval2cc. It may provide useful clues as to what went wrong.
[[ --install-query TEXT ]]: This option allows a user to specify options like --install xsl to retrieve information about the package installation. This might be useful for making use of the package files outside of the packaged scripts. --install help will list all possible. The following choices are recognized: help - lists what choices are available. xsl - shows the directory the XSL files are stored under. public-id - displays the public ID of the keyval documents. public-url - displays the public URL of the keyval DTD. dtd - shows the location of the keyval DTD file. catalog - shows the location of the XML style catalog file. catalog-oasis - shows the location of the OASIS style catalog. docs - shows local directory where the documents can be found. url - shows the public URL where documenation can be found.

Files

/home/pkb/usr/share/vaisala/xml/keyval/dtd/keyval_1_0_0.dtd: Location of the DTD which is used to validate the <keyval> document.
/home/pkb/usr/share/vaisala/xml/keyval/xsl: The directory containing the XSL files used when translating <keyval> documents.
/web/vaisala/xml/keyval: The directory containing the package documentation (including a tutorial on using this utility).

Environment

XML_COMMON_JAVA: When translating XML documents with a XSL style sheet, the keyval2cc will make use of the XSLT processor found in the 1.4.2 version of the Java run time environment. If the java interpreter found in your path is not version 1.4.2 or later, you can use this environment variable to specify the location of the appropriate java interpreter. In addition, you can also use it to specify HTTP proxy information for your java environment. For example, a setting of /liz3/pkb/usr/j2re1.4.2_03/bin/java -DproxyHost=172.26.0.232 -DproxyPort=3128 would specify a path to a particular java interpreter and set the HTTP proxy settings.

Authors

Paul Blankenbaker created the initial script, XSL files, and build environment.