clo++ Users Manual

Peter Jones

    pjones@pmade.org

Copyright  2001, 2002 by Peter Jones

This is the manual for clo++. It describes how to use clo++ and the format
of the XML input file.

Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML,
HTML, PDF, PostScript, RTF and so forth) with or without modification, are
permitted provided that the following conditions are met:

 1. Redistributions of source code (SGML DocBook) must retain the above
    copyright notice, this list of conditions and the following disclaimer
    as the first lines of this file unmodified.
   
 2. Redistributions in compiled form (transformed to other DTDs, converted
    to PDF, PostScript, RTF and other formats) must reproduce the above
    copyright notice, this list of conditions and the following disclaimer
    in the documentation and/or other materials provided with the
    distribution.
   
    Important: THIS DOCUMENTATION IS PROVIDED BY THE AUTHORS "AS IS" AND
    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION
    PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   
---------------------------------------------------------------------------

Table of Contents
1. Introduction
   
    1.1. What is clo++?
    1.2. Features
    1.3. Supported Option Types
    1.4. Option Modifiers
    1.5. Option Grouping
   
2. Quick Start
   
    2.1. Building and Installing
    2.2. Writing Your First clo++ XML File
    2.3. Running clo++
   
A. Requirements
   
    A.1. Software Dependencies
    A.2. Supported Platforms
   
3. Revision History
   
    3.1. Version 0.5.0
    3.2. Version 0.4.0
    3.3. Version 0.3.0
   
B. To Do List
   
    B.1. Feature To Do List
    B.2. Milestone 0.6.0
    B.3. Milestone 0.7.0
    B.4. Milestone 0.8.0
    B.5. Milestone 0.9.0
    B.6. Milestone 1.0.0
   
C. Credits
   
    C.1. Continued Contributions
    C.2. Contributions to Version 0.3.0
   
---------------------------------------------------------------------------

Chapter 1. Introduction

1.1. What is clo++?

clo++ is a command line option parser generator. Given an XML file that
contains a description of your program an its options, clo++ can generate
code to parse your command line.

Although C++ is currently the only supported output format, clo++ was
written using a template system and should be easy to extend to other
languages and uses. The next feature on the schedule is man page
generation.

---------------------------------------------------------------------------

1.2. Features

clo++ tries to provide enough features to parse most forms of command line
options without going overboard. In most cases, if clo++ does not support a
specific feature you are looking for, you can use an existing feature and
customize it in your application.

The following list is just a quick overview of the feature list for clo++.

  * Option description is done using a simple XML dialect instead of a
    complex proprietary language.
   
  * The users of your application do not have to have clo++ installed. Just
    include the output from clo++ with your software packages. The clo++
    output does not have any license or restrictions.
   
  * Automatic generation of help messages.
   
  * Single character options start with a dash ('-') and multi-character
    options start with a double dash ('--');
   
  * Support for multiple sub-commands that take their own options. (Similar
    to cvs commit, cvs add, etc.)
   
  * Multi-character options and commands can be abbreviated depending on a
    configuration setting in the XML file.
   
  * Single character options can be bundled. (-aeiou).
   
  * Multi-character options can include their argument in the option name
    or it can be separate. (--option=one --option two).
   
  * Options can have default values. You can see if the value of an option
    is the result of its default value or its presence on the command line
    by checking its location value.
   
  * Options can be hidden. That is, they can be used on the command line
    but will not be shown in the help message or man page.
   
  * Options and Groups can be mandatory. This means that the option/group
    is required to be used.
   
  * Options can be strict. This means that the option can not be used on
    the command line more than once. If an option is not strict, it will be
    allowed on the command line more than once and the last time it is used
    it the final value of the option.
   
  * The clo++ source code is released under a BSD license. There are very
    few restrictions on its use.
   
---------------------------------------------------------------------------

1.3. Supported Option Types

clo++ supports the following option types.

  * flag - This option takes no arguments and simply sets a boolean value
    to indicate its presence on the command line.
   
  * bool - This option takes an argument that is parsed as a boolean value.
    You can define words that you consider true and false in your XML file.
   
  * enum - This option takes an argument that must be in a list of allowed
    words. The parser then converts the argument into an enum member for
    you.
   
  * int - This option takes an argument that must be completely convertible
    to an integer. You may also specify a minimum and/or a maximum value in
    your XML file.
   
  * double - This option takes an argument that must be completely
    convertible to a real number. You may also specify a minimum and/or a
    maximum value in your XML file.
   
  * string - This option takes an argument that is not parsed and is just
    stored as a raw character string.
   
---------------------------------------------------------------------------

1.4. Option Modifiers

All options except the flag option can have modifiers. Here is a quick
overview of the modifier types.

  * vector - Each time the option is repeated on the command line its value
    is pushed into a vector.
   
  * map - The option can take key=value pairs where the key is a string and
    the value is the value type for the option. This also implies that the
    option can be repeated.
   
---------------------------------------------------------------------------

1.5. Option Grouping

clo++ also supports option grouping. There are three types of groups that
an option can be part of. Here is a quick description of them.

  * and - This group allows you to enforce the presence of all contained
    options if one of the options in the group is used.
   
  * or - This group is used to say that at least one option in the the
    group must be given, but more than one is acceptable.
   
  * xor - This group is used when you want to ensure that a group of
    options can not be used at the same time.
   
---------------------------------------------------------------------------

Chapter 2. Quick Start

We start off with a quick start guide. This is just a fast overview to get
you working with clo++ as soon as possible.

---------------------------------------------------------------------------

2.1. Building and Installing

You build clo++ using the configure.pl perl script that comes in the
tarball. If you have the xml2-config script that comes with libxml2 in your
path you can just run configure.pl.

If xml2-config is not in your path, you can use the --xml2-config option to
configure.pl.

After you run configure.pl you are ready to run make. Then, after
everything compiles, you can run make install.

---------------------------------------------------------------------------

2.2. Writing Your First clo++ XML File

Before you can run clo++, you should have an XML file ready. The XML file
should describe the command line options that you wish to parse.

A good place to start is the examples directory. There are some example XML
files and C++ code that uses the generated C++ code. You may also want to
look at the DTD, it is in the dtd directory.

---------------------------------------------------------------------------

2.3. Running clo++

After you have an XML file all ready to go, you can run clo++. I assume
that you want to generate C++ code, so we are going to use the -o c++
option to clo++.

If your XML file is called options.xml then this is the command that you
would run to generate the C++ header file and source file.

    clo++ -o c++ options.xml



To learn about the other command line options that clo++ can take, try
running clo++ -h.

---------------------------------------------------------------------------

Appendix A. Requirements

clo++ should compile on any platform that has a working ISO 14882-1998
compliant compiler. Okay, so there is no such thing, but your compiler
should be pretty close.

No platform specific code is used anywhere in clo++, including the code
that it generates. All code is pure C++.

    Warning clo++ will not compile if you are using any version of GCC
    prior to version 3.0. Furthermore, it will not operate correctly if
    compiled under GCC versions prior to 3.0.3 (due to bugs with
    exceptions).
   
    The code that clo++ generates will also not work on GCC version prior
    to version 3.0. Although it is unlikely that clo++ will ever compile
    under versions of GCC < 3.0, we will be working on clo++ so that the
    code it generates can compile with these compilers.
   
---------------------------------------------------------------------------

A.1. Software Dependencies

clo++ has dependencies on the following software.

  * Perl 5 - Only needed to configure clo++. Perl is not used any other
    time.
   
  * libxml2 - The XML parser that clo++ uses. Other parsers will be
    supported in the future.
   
---------------------------------------------------------------------------

A.2. Supported Platforms

clo++ is supported on the following platforms with the given compilers. If
you successfully compile clo++ on a platform that is not listed here,
please drop us a note.

  * FreeBSD 4.5 (-RELEASE and -STABLE) using GCC versions 3.0.3 - 3.0.4.
   
  * Sun Solaris 2.7 using GCC version 3.0.4.
   
---------------------------------------------------------------------------

Chapter 3. Revision History

3.1. Version 0.5.0

Version 0.5.0 was a complete rewrite.

---------------------------------------------------------------------------

3.2. Version 0.4.0

Version 0.4.0 was never released to the public.

---------------------------------------------------------------------------

3.3. Version 0.3.0

First public version.

---------------------------------------------------------------------------

Appendix B. To Do List

B.1. Feature To Do List

  * Allow automap to automaticly place non-options that look like a key=
    value pair into the given map.
   
  * Allow autovector to place non-options into the given vector instead of
    the default non-options vector.
   
  * Allow commands to be hidden similar to hiding options.
   
  * Add a new option type, count. This type is similar to flag but gets
    incremented each time it is present on the command line.
   
  * Add an option to allow a '+' to start a long option.
   
  * Find some way to skip unknown options in a safe way. Stuff like
    '-display' for GTK+ programs.
   
---------------------------------------------------------------------------

B.2. Milestone 0.6.0

  * Generate man pages.
   
  * Generate man page for clo++.
   
  * Write clo++ 0.3.0 XML format to 0.5.0 XSLT.
   
  * Write XSLT for DocBook.
   
  * Fix any bugs.
   
---------------------------------------------------------------------------

B.3. Milestone 0.7.0

  * Finish users manual (XML format and C++ API)
   
  * Fix any bugs.
   
  * Implement any requested features.
   
---------------------------------------------------------------------------

B.4. Milestone 0.8.0

  * Finish template manual so others can write templates.
   
  * Fix any bugs.
   
  * Implement any requested features.
   
---------------------------------------------------------------------------

B.5. Milestone 0.9.0

  * Code freeze. Make stable.
   
---------------------------------------------------------------------------

B.6. Milestone 1.0.0

  * First stable release.
   
---------------------------------------------------------------------------

Appendix C. Credits

This section is dedicated to those people who contributed in some way to
clo++. If I have forgotten you, please forgive me and drop me a note.

---------------------------------------------------------------------------

C.1. Continued Contributions

The following people make on-going contributions to clo++

  * Isaac Foraker - author of the template system that clo++ uses.
   
  * Peter Jones - Main developer.
   
---------------------------------------------------------------------------

C.2. Contributions to Version 0.3.0

The following people either contributed patches or suggestions to clo++
version 0.3.0. Since version 0.3.0 was not supported, their hard work was
never applied to the source code.

Although their contributions where not used in clo++, these are the people
that inspired clo++ version 0.5.0.

  * Matthias Berse
   
  * Christophe de Vienne
   
  * Diab Jerius
   
---------------------------------------------------------------------------
