ProgOptions.cpp

Go to the documentation of this file.

#include <iostream>
#include <sstream>
#include <iomanip>
#include <cstdlib>
#include <list>
#include <limits>
#include <set>
#include <algorithm>

#include <cassert>
#include <cstring>

#include "moab/MOABConfig.h"
#include "moab/ProgOptions.hpp"
#ifdef MOAB_HAVE_MPI
#include "moab_mpi.h"
#endif

enum OptType
{
    FLAG = 0,
    INT,
    REAL,
    STRING,
    INT_VECT
};

template < typename T >
inline static OptType get_opt_type();

template <>
OptType get_opt_type< void >()
{
    return FLAG;
}
template <>
OptType get_opt_type< int >()
{
    return INT;
}
template <>
OptType get_opt_type< double >()
{
    return REAL;
}
template <>
OptType get_opt_type< std::string >()
{
    return STRING;
}
template <>
OptType get_opt_type< std::vector< int > >()
{
    return INT_VECT;
}

class ProgOpt
{

    std::string shortname, longname;
    std::vector< std::string > args;
    OptType type;
    void* storage;
    int flags;
    ProgOpt* cancel_opt;

    const char* get_argstring() const
    {
        switch( type )
        {
            case INT:
                return "int";
            case INT_VECT:
                return "ints";
            case REAL:
                return "val";
            case FLAG:
                return "";
            default:
                return "arg";
        }
    }

  public:
    ProgOpt( const std::string& longname_p, const std::string& shortname_p, int flags_p, OptType t = FLAG )
        : shortname( shortname_p ), longname( longname_p ), type( t ), storage( NULL ), flags( flags_p ),
          cancel_opt( NULL )
    {
    }

    friend class ProgOptions;
};

ProgOptions::ProgOptions( const std::string& helpstring, const std::string& briefhelp )
    : expect_optional_args( false ), optional_args_position( 0 ), max_optional_args( 0 )
{
    brief_help = briefhelp;
    if( !helpstring.empty() ) main_help.push_back( helpstring );
    addOpt< void >( "help,h", "Show full help text", help_flag );
}

ProgOptions::~ProgOptions()
{
    for( std::vector< help_line >::iterator i = option_help_strings.begin(); i != option_help_strings.end(); ++i )
    {
        if( ( *i ).first )
        {
            delete( *i ).first;
        }
    }

    for( std::vector< help_line >::iterator i = arg_help_strings.begin(); i != arg_help_strings.end(); ++i )
    {
        delete( *i ).first;
    }
}

void ProgOptions::get_namestrings( const std::string& namestring, std::string* longname, std::string* shortname )
{
    *shortname = "";
    *longname  = namestring;

    size_t idx = namestring.find_first_of( ',' );
    if( idx != namestring.npos )
    {
        *longname  = namestring.substr( 0, idx );
        *shortname = namestring.substr( idx + 1, namestring.npos );
    }
}

void ProgOptions::setVersion( const std::string& version_string, bool addFlag )
{
    progversion = version_string;
    if( addFlag )
    {
        addOpt< void >( "version", "Print version number and exit", version_flag );
    }
}

template < typename T >
void ProgOptions::addOpt( const std::string& namestring, const std::string& helpstring, T* value, int flags )
{

    std::string shortname, longname;
    get_namestrings( namestring, &longname, &shortname );

    if( flags & int_flag )
    {  // short name is implicit for this flag
        if( !shortname.empty() ) error( "Requested short name with int_flag option" );
        if( get_opt_type< T >() != INT ) error( "Requested int_flag for non-integer option" );
        if( !number_option_name.empty() ) error( "Requested int_flag for multiple options" );
        number_option_name = longname;
    }

    ProgOpt* opt = new ProgOpt( longname, shortname, flags, get_opt_type< T >() );
    if( value ) opt->storage = value;

    if( longname.length() ) long_names[longname] = opt;
    if( shortname.length() ) short_names[shortname] = opt;

    help_line help = std::make_pair( opt, helpstring );
    option_help_strings.push_back( help );

    if( flags & add_cancel_opt )
    {
        std::string flag    = "no-" + ( longname.length() ? longname : shortname );
        ProgOpt* cancel_opt = new ProgOpt( flag, "", flags ^ ProgOptions::store_false, FLAG );
        if( value ) cancel_opt->storage = value;

        cancel_opt->cancel_opt       = opt;
        long_names[flag]             = cancel_opt;
        std::string clear_helpstring = "Clear previous " + flag.substr( 3, flag.npos ) + " flag";
        help                         = std::make_pair( cancel_opt, clear_helpstring );
        option_help_strings.push_back( help );
    }
}

template < typename T >
void ProgOptions::addRequiredArg( const std::string& helpname, const std::string& helpstring, T* value, int flags )
{

    OptType type = get_opt_type< T >();

    ProgOpt* opt = new ProgOpt( helpname, "", flags, type );
    if( value ) opt->storage = value;
    help_line help = std::make_pair( opt, helpstring );
    arg_help_strings.push_back( help );
    required_args[helpname] = opt;
}

template < typename T >
void ProgOptions::addOptionalArgs( unsigned max_count,
                                   const std::string& helpname,
                                   const std::string& helpstring,
                                   int flags )
{
    // If there was a previous one, we need to remove it
    // because there can be only one.  If we didn't remove
    // the old one then it would be treated as a required arg.
    if( expect_optional_args )
    {
        std::map< std::string, ProgOpt* >::iterator iter;
        iter = required_args.find( arg_help_strings[optional_args_position].second );
        assert( iter != required_args.end() );
        delete iter->second;
        required_args.erase( iter );
        arg_help_strings.erase( arg_help_strings.begin() + optional_args_position );
    }

    expect_optional_args   = true;
    optional_args_position = arg_help_strings.size();
    max_optional_args      = max_count;
    addRequiredArg< T >( helpname, helpstring, 0, flags );
}

void ProgOptions::addOptionHelpHeading( const std::string& s )
{
    option_help_strings.push_back( std::make_pair( (ProgOpt*)NULL, s ) );
}

void ProgOptions::printVersion( std::ostream& out )
{
    out << progversion << std::endl;
}

void ProgOptions::printHelp( std::ostream& out )
{

    /* Print introductory help text */
    if( !brief_help.empty() ) out << brief_help << std::endl;
    for( std::vector< std::string >::iterator i = main_help.begin(); i != main_help.end(); ++i )
    {
        if( ( *i ).length() )
        {
            out << std::endl << *i << std::endl;
        }
    }

    printUsage( out );

    // max number of characters to pad argument/option names with
    // options with long names may exceed this, but will appear out of alignment in help text
    const int max_padding = 20;

    /* List required arguments, with help text */
    if( arg_help_strings.size() > 0 )
    {

        int max_arg_namelen = 0;

        for( std::vector< help_line >::iterator i = arg_help_strings.begin(); i != arg_help_strings.end(); ++i )
        {
            max_arg_namelen = std::max( max_arg_namelen, (int)( ( *i ).first->longname.length() ) );
        }

        max_arg_namelen = std::min( max_arg_namelen + 3, max_padding );

        out << "Arguments: " << std::endl;

        for( std::vector< help_line >::iterator i = arg_help_strings.begin(); i != arg_help_strings.end(); ++i )
        {
            ProgOpt* option   = ( *i ).first;
            std::string& info = ( *i ).second;

            std::stringstream s;
            s << "  " << option->longname;
            out << std::setw( max_arg_namelen ) << std::left << s.str();
            out << ": " << info << std::endl;
        }
    }

    /* List options, with help text */
    out << "Options: " << std::endl;
    int max_option_prefix_len = 0;

    for( std::vector< help_line >::iterator i = option_help_strings.begin(); i != option_help_strings.end(); ++i )
    {
        ProgOpt* option   = ( *i ).first;
        std::string& info = ( *i ).second;

        if( option )
        {

            if( max_option_prefix_len == 0 )
            {
                // iterate ahead in the option list to determine whitespace padding
                // stop if (*j).first is NULL, which indicates a help header message
                for( std::vector< help_line >::iterator j = i; j != option_help_strings.end() && ( *j ).first; ++j )
                {
                    int len               = get_option_usage_prefix( *( ( *j ).first ) ).length();
                    max_option_prefix_len = std::max( max_option_prefix_len, len );
                }
            }
            max_option_prefix_len     = std::min( max_option_prefix_len, max_padding );
            std::string option_prefix = get_option_usage_prefix( *option );

            out << std::setw( max_option_prefix_len ) << std::left << option_prefix;
            out << ": ";
        }
        else
        {
            // no option: this is a help header.  Reset max name length.
            max_option_prefix_len = 0;
        }
        out << info << std::endl;
    }
}

std::string ProgOptions::get_option_usage_prefix( const ProgOpt& option )
{
    bool has_shortname = option.shortname.length() > 0;
    bool has_longname  = option.longname.length() > 0;
    std::string argstr = option.get_argstring();

    std::stringstream s;
    s << "  ";
    if( has_shortname )
    {

        s << "-" << option.shortname;
        if( has_longname )
        {
            s << " ";
        }
    }
    else if( option.flags & int_flag )
    {

        s << "-<n>";
        if( has_longname )
        {
            s << " ";
        }
    }
    if( has_longname )
    {

        if( has_shortname ) s << "[";
        s << "--" << option.longname;
        if( has_shortname ) s << "]";
    }

    if( argstr.length() ) s << " <" << argstr << ">";
    return s.str();
}

void ProgOptions::printUsage( std::ostream& out )
{

    out << "Usage: " << progname << " --help | [options] ";

    for( size_t i = 0; i < arg_help_strings.size(); ++i )
    {
        if( !expect_optional_args || i != optional_args_position )
            out << '<' << arg_help_strings[i].first->longname << "> ";
        else if( 0 == max_optional_args || max_optional_args > 3 )
            out << "[<" << arg_help_strings[i].first->longname << "> ...] ";
        else if( 1 == max_optional_args )
            out << "[" << arg_help_strings[i].first->longname << "] ";
        else
            for( unsigned j = 0; j < max_optional_args; ++j )
                out << "[" << arg_help_strings[i].first->longname << ( j + 1 ) << "] ";
    }

    out << std::endl;
}

ProgOpt* ProgOptions::lookup( const std::map< std::string, ProgOpt* >& table, const std::string& arg )
{
    std::map< std::string, ProgOpt* >::const_iterator it = table.find( arg );
    if( it != table.end() )
        return it->second;
    else if( &table == &short_names && arg.size() == 1 && isdigit( arg[0] ) && !number_option_name.empty() &&
             ( it = long_names.find( number_option_name ) ) != long_names.end() )
        return it->second;
    else
        return 0;
}

ProgOpt* ProgOptions::lookup_option( const std::string& namestring )
{
    std::string longname, shortname;
    get_namestrings( namestring, &longname, &shortname );

    ProgOpt* opt = lookup( long_names, longname );
    if( !opt ) opt = lookup( short_names, shortname );

    if( !opt )
    {
        error( "Invalid option: " + namestring );
    }

    return opt;
}

void ProgOptions::error( const std::string& err )
{
    std::cerr << "Error: " << err << "\n" << std::endl;
    ;
    printUsage( std::cerr );
    std::cerr << std::endl;
    if( getenv( "MOAB_PROG_OPT_ABORT" ) ) abort();
    std::exit( EXIT_FAILURE );
}

// Copied from convert.cpp
// Parse list of integer ranges
// e.g. 1,2,5-10,12
static bool parse_int_list( const char* string, std::vector< int >& results )
{
    bool okay   = true;
    char* mystr = strdup( string );
    for( const char* ptr = strtok( mystr, ", \t" ); ptr; ptr = strtok( 0, ", \t" ) )
    {
        char* endptr;
        long val = strtol( ptr, &endptr, 0 );
        if( endptr == ptr )
        {
            std::cerr << "Not an integer: \"" << ptr << '"' << std::endl;
            okay = false;
            break;
        }

        long val2 = val;
        if( *endptr == '-' )
        {
            const char* sptr = endptr + 1;
            val2             = strtol( sptr, &endptr, 0 );
            if( endptr == sptr )
            {
                std::cerr << "Not an integer: \"" << sptr << '"' << std::endl;
                okay = false;
                break;
            }
            if( val2 < val )
            {
                std::cerr << "Invalid id range: \"" << ptr << '"' << std::endl;
                okay = false;
                break;
            }
        }

        if( *endptr )
        {
            okay = false;
            break;
        }

        for( ; val <= val2; ++val )
            results.push_back( (int)val );
    }

    free( mystr );
    return okay;
}

// Copied from convert.cpp
// Replace '%' with MPI rank iff compiled with MPI
static std::string do_rank_subst( const std::string& s )
{
#ifndef MOAB_HAVE_MPI
    return s;
#else
    int rank, size;
    if( MPI_SUCCESS != MPI_Comm_rank( MPI_COMM_WORLD, &rank ) || MPI_SUCCESS != MPI_Comm_size( MPI_COMM_WORLD, &size ) )
        return s;
    int width = 1;
    while( size > 10 )
    {
        size /= 10;
        width++;
    }

    size_t j = s.find( '%' );
    if( j == std::string::npos ) return s;

    std::ostringstream st;
    st << std::setfill( '0' );
    st << s.substr( 0, j );
    st << rank;

    size_t i;
    while( ( i = s.find( '%', j + 1 ) ) != std::string::npos )
    {
        st << s.substr( j, i - j );
        st << std::setw( width ) << rank;
        j = i;
    }
    st << s.substr( j + 1 );
    return st.str();
#endif
}

/**
 * Check the input to a given option for correctness, converting it to its expected type (e.g. int)
 * and storing the result to target, if target is non-NULL.
 * @param option Used only in error messages to state which option could not be successfully
 * converted
 * @param arg_idx If non-NULL, evaluate the (*arg_idx)'th item in opt's args list
 */
bool ProgOptions::evaluate( const ProgOpt& opt, void* target, const std::string& option, unsigned* arg_idx )
{

    unsigned idx = arg_idx ? *arg_idx : opt.args.size() - 1;

    switch( opt.type )
    {
        case FLAG:
            error( "Cannot evaluate a flag" );
            break;
        case INT: {
            int temp;
            int* i = target ? reinterpret_cast< int* >( target ) : &temp;
            if( opt.args.size() < 1 )
            {
                error( "Missing argument to " + option + " option" );
            }
            const char* arg = opt.args.at( idx ).c_str();
            char* p;
            *i = std::strtol( arg, &p, 0 );
            if( *p != '\0' )
            {
                error( "Bad integer argument '" + opt.args.at( idx ) + "' to " + option + " option." );
            }
            return true;
        }
        case REAL: {
            double temp;
            double* i = target ? reinterpret_cast< double* >( target ) : &temp;
            if( opt.args.size() < 1 )
            {
                error( "Missing argument to " + option + " option" );
            }
            const char* arg = opt.args.at( idx ).c_str();
            char* p;
            *i = std::strtod( arg, &p );
            if( *p != '\0' )
            {
                error( "Bad real argument '" + opt.args.at( idx ) + "' to " + option + " option." );
            }
            return true;
        }

        case STRING: {
            std::string temp;
            std::string* i = target ? reinterpret_cast< std::string* >( target ) : &temp;
            if( opt.args.size() < 1 )
            {
                error( "Missing argument to " + option + " option" );
            }
            if( opt.flags & rank_subst )
                *i = do_rank_subst( opt.args.at( idx ) );
            else
                *i = opt.args.at( idx );
            return true;
        }

        case INT_VECT: {
            std::vector< int > temp;
            std::vector< int >* i = target ? reinterpret_cast< std::vector< int >* >( target ) : &temp;
            if( !parse_int_list( opt.args.at( idx ).c_str(), *i ) )
                error( "Bad integer list '" + opt.args.at( idx ) + "' to " + option + " option." );
            return true;
        }
    }

    return false;
}

template < typename T >
bool ProgOptions::getOpt( const std::string& namestring, T* t )
{

    ProgOpt* opt = lookup_option( namestring );

    if( get_opt_type< T >() != opt->type )
    {
        error( "Option '" + namestring + "' looked up with incompatible type" );
    }

    // This call to evaluate is inefficient, because opt was already evaluated when it was parsed.
    if( opt->args.size() )
    {
        if( t ) evaluate( *opt, t, "" );
        return true;
    }
    else
        return false;
}

template < typename T >
void ProgOptions::getOptAllArgs( const std::string& namestring, std::vector< T >& values )
{
    ProgOpt* opt = lookup_option( namestring );

    // special case: if user asks for list of int, but argument
    // was INT_VECT, concatenate all lists
    if( get_opt_type< T >() == INT && opt->type == INT_VECT )
    {
        for( unsigned i = 0; i < opt->args.size(); ++i )
            evaluate( *opt, &values, "", &i );
        return;
    }

    if( get_opt_type< T >() != opt->type )
    {
        error( "Option '" + namestring + "' looked up with incompatible type" );
    }

    values.resize( opt->args.size() );

    // These calls to evaluate are inefficient, because the arguments were evaluated when they were
    // parsed
    for( unsigned i = 0; i < opt->args.size(); ++i )
    {
        evaluate( *opt, &( values[i] ), "", &i );
    }
}

int ProgOptions::numOptSet( const std::string& namestring )
{
    std::string longname, shortname;
    get_namestrings( namestring, &longname, &shortname );

    ProgOpt* opt = lookup( long_names, longname );
    if( !opt ) opt = lookup( short_names, shortname );

    if( !opt )
    {
        error( "Could not look up option: " + namestring );
    }

    return opt->args.size();
}

template < typename T >
T ProgOptions::getReqArg( const std::string& namestring )
{

    ProgOpt* opt = lookup( required_args, namestring );

    if( !opt )
    {
        error( "Could not look up required arg: " + namestring );
    }

    // if parseProgramOptions succeeded, we can assume each required arg has a value,
    // so calling evaluate is valid
    T value;
    evaluate( *opt, &value, "" );
    return value;
}

template < typename T >
void ProgOptions::getArgs( const std::string& namestring, std::vector< T >& values )
{
    ProgOpt* opt = lookup( required_args, namestring );

    if( !opt )
    {
        error( "Could not look up required arg: " + namestring );
    }

    if( get_opt_type< T >() != opt->type )
    {
        error( "Option '" + namestring + "' looked up with incompatible type" );
    }

    values.resize( opt->args.size() );

    // These calls to evaluate are inefficient, because the arguments were evaluated when they were
    // parsed
    for( unsigned i = 0; i < opt->args.size(); ++i )
    {
        evaluate( *opt, &( values[i] ), "", &i );
    }
}

// Process parsed option.
// Returns true if value is still expected
// Should never return true if optional value is passed
// \param arg Used for error messages only
bool ProgOptions::process_option( ProgOpt* opt, std::string arg, const char* value )
{
    if( !opt )
    {
        if( arg == "--manpage" )
        {
            write_man_page( std::cout );
            exit( 0 );
        }

        error( "Unknown option: " + arg );
    }

    if( opt->flags & help_flag )
    {
        printHelp( std::cout );
        exit( EXIT_SUCCESS );
    }

    if( opt->flags & version_flag )
    {
        printVersion( std::cout );
        exit( EXIT_SUCCESS );
    }

    if( opt->type != FLAG )
    {
        if( !value ) return true;

        opt->args.push_back( value );
        evaluate( *opt, opt->storage, arg );
    }
    else
    {
        if( value )
        {
            error( "Unexpected value for flag: " + arg );
        }

        // do flag operations
        if( opt->cancel_opt )
        {
            opt->cancel_opt->args.clear();
        }
        if( opt->storage )
        {
            *static_cast< bool* >( opt->storage ) = ( opt->flags & store_false ) ? false : true;
        }
        opt->args.push_back( "" );
    }

    return false;
}

void ProgOptions::parseCommandLine( int argc, char* argv[] )
{
    const char* name = strrchr( argv[0], '/' );
    if( name )
        this->progname = ++name;
    else
        this->progname = argv[0];

    std::vector< const char* > args;
    std::list< ProgOpt* > expected_vals;
    bool no_more_flags = false;

    // Loop over all command line arguments
    for( int i = 1; i < argc; ++i )
    {
        std::string arg( argv[i] );
        if( arg.empty() ) continue;

        if( !expected_vals.empty() )
        {
            ProgOpt* opt = expected_vals.front();
            expected_vals.pop_front();
            assert( opt->type != FLAG );
            opt->args.push_back( arg );
            evaluate( *opt, opt->storage, arg );
        }
        else if( !no_more_flags && arg[0] == '-' )
        {
            if( arg.length() > 2 && arg[1] == '-' )
            {  // long opt
                size_t eq = arg.find_first_of( '=' );
                if( eq != std::string::npos )
                {
                    ProgOpt* opt = lookup( long_names, arg.substr( 2, eq - 2 ) );
                    process_option( opt, arg, arg.substr( eq + 1 ).c_str() );
                }
                else
                {
                    ProgOpt* opt = lookup( long_names, arg.substr( 2 ) );
                    if( process_option( opt, arg ) ) expected_vals.push_back( opt );
                }
            }
            else if( arg == "--" )
            {  // --
                no_more_flags = true;
            }
            else
                for( size_t f = 1; f < arg.length(); ++f )
                {  // for each short opt
                    ProgOpt* opt = lookup( short_names, std::string( 1, arg[f] ) );
                    if( opt && ( opt->flags & int_flag ) )
                    {
                        const char val[] = { arg[f], 0 };
                        process_option( opt, std::string( 1, arg[f] ), val );
                    }
                    else if( process_option( opt, std::string( 1, arg[f] ) ) )
                        expected_vals.push_back( opt );
                }
        }
        else
        {
            /* arguments */
            args.push_back( argv[i] );
        }
    } /* End loop over inputs */

    // Print error if any missing values
    if( !expected_vals.empty() )
    {
        error( "Missing value for option: -" + expected_vals.front()->shortname + ",--" +
               expected_vals.front()->longname );
    }

    // Process non-option arguments
    std::vector< help_line >::iterator arg_help_pos  = arg_help_strings.begin();
    std::vector< const char* >::iterator arg_val_pos = args.begin();
    std::vector< help_line >::iterator opt_args_pos  = arg_help_strings.end();
    size_t min_required_args                         = required_args.size();
    size_t max_required_args                         = required_args.size();
    if( expect_optional_args )
    {
        min_required_args--;
        if( max_optional_args )
            max_required_args += max_optional_args;
        else
            max_required_args = std::numeric_limits< int >::max();
        opt_args_pos = arg_help_pos + optional_args_position;
    }
    // check valid number of non-flag arguments
    if( args.size() < min_required_args )
    {
        size_t missing_pos = args.size();
        if( expect_optional_args && missing_pos >= optional_args_position ) ++missing_pos;

        const std::string& missed_arg = arg_help_strings[missing_pos].first->longname;
        error( "Did not find required positional argument: " + missed_arg );
    }
    else if( args.size() > max_required_args )
    {
        error( "Unexpected argument: " + std::string( args[max_required_args] ) );
    }

    // proccess arguments up to the first optional argument
    // (or all arguments if no optional args)
    while( arg_help_pos != opt_args_pos )
    {
        ProgOpt* opt = arg_help_pos->first;
        ++arg_help_pos;
        opt->args.push_back( *arg_val_pos );
        evaluate( *opt, opt->storage, *arg_val_pos );
        ++arg_val_pos;
    }
    // process any optional args
    if( arg_help_pos != arg_help_strings.end() )
    {
        assert( arg_help_pos == opt_args_pos );
        size_t num_opt_args = args.size() + 1 - required_args.size();
        ProgOpt* opt        = arg_help_pos->first;
        ++arg_help_pos;
        while( num_opt_args-- )
        {
            opt->args.push_back( *arg_val_pos );
            evaluate( *opt, opt->storage, *arg_val_pos );
            ++arg_val_pos;
        }
    }
    // process any remaining args
    while( arg_help_pos != arg_help_strings.end() )
    {
        assert( arg_val_pos != args.end() );
        ProgOpt* opt = arg_help_pos->first;
        ++arg_help_pos;
        opt->args.push_back( *arg_val_pos );
        evaluate( *opt, opt->storage, *arg_val_pos );
        ++arg_val_pos;
    }
    assert( arg_val_pos == args.end() );
}

void ProgOptions::write_man_page( std::ostream& s )
{
    // a leading '.' is a control character.  strip it if present.
    std::string lprogname;
    if( progname.empty() || progname[0] != '.' )
        lprogname = progname;
    else
    {
        lprogname = progname.substr( 1 );
    }

    // Manpage controls:
    // .TH title
    // .SH section
    // .SS subsection
    // .P  paragraph
    // .HP hanging paragraph
    // .B  bold
    // .I  italic
    // .B  bold
    // .I  italic
    // .RS begin indent
    // .RE end indent
    // .RB alternating roman and blold
    // .BR alternating bold and roman

    std::vector< help_line >::iterator it;
    std::set< ProgOpt* > skip_list;

    // start man page
    s << std::endl << ".TH " << lprogname << " 1" << std::endl;

    // write NAME section
    s << std::endl << ".SH NAME" << std::endl << ".P " << std::endl << lprogname << " \\- ";
    if( brief_help.empty() && !main_help.empty() )
        s << main_help.front();
    else
        s << brief_help;
    s << std::endl << std::endl;

    // write SYNOPSIS section
    s << std::endl << ".SH SYNOPSIS" << std::endl << ".HP" << std::endl << ".B \"" << lprogname << '"' << std::endl;
    for( it = option_help_strings.begin(); it != option_help_strings.end(); ++it )
    {
        if( !it->first || skip_list.find( it->first ) != skip_list.end() || it->first->longname == "help" ) continue;

        if( it->first->type == FLAG )
        {
            char c = '[';
            s << ".RB";
            if( !it->first->shortname.empty() )
            {
                s << ' ' << c << " \"-" << it->first->shortname << '"';
                c = '|';
            }
            if( !it->first->longname.empty() )
            {
                s << ' ' << c << " \"--" << it->first->longname << '"';
            }
            if( it->first->cancel_opt )
            {
                skip_list.insert( it->first->cancel_opt );
                if( !it->first->cancel_opt->shortname.empty() )
                    s << " | \"-" << it->first->cancel_opt->shortname << '"';
                if( !it->first->cancel_opt->longname.empty() ) s << " | \"--" << it->first->cancel_opt->longname << '"';
            }
            s << " ]" << std::endl;
        }
        else if( it->first->flags & int_flag )
        {
            s << ".RB [ - <n>| \"--" << it->first->longname << "\" \"=" << it->first->get_argstring() << "]\""
              << std::endl;
        }
        else
        {
            s << ".RB [ ";
            if( !it->first->shortname.empty() )
                s << "\"-" << it->first->shortname << "\" \"\\ " << it->first->get_argstring();
            if( !it->first->shortname.empty() && !it->first->longname.empty() ) s << "|\" ";
            if( !it->first->longname.empty() )
                s << "\"--" << it->first->longname << "\" \"=" << it->first->get_argstring();
            s << "]\"" << std::endl;
        }
    }
    for( it = arg_help_strings.begin(); it != arg_help_strings.end(); ++it )
    {
        if( !it->first ) continue;

        if( !expect_optional_args || (unsigned)( it - arg_help_strings.begin() ) != optional_args_position )
            s << it->first->longname << ' ';
        else if( 1 == max_optional_args )
            s << '[' << it->first->longname << "] ";
        else
            s << '[' << it->first->longname << " ...] ";
    }
    s << std::endl;
    s << ".HP" << std::endl << ".B \"" << lprogname << " -h|--help\"" << std::endl;

    // write DESCRIPTION section
    s << std::endl << ".SH DESCRIPTION" << std::endl;
    if( main_help.empty() ) s << brief_help << std::endl;
    for( size_t i = 0; i < main_help.size(); ++i )
    {
        const std::string::size_type n = main_help[i].size();
        std::string::size_type j       = 0, k;
        s << std::endl << ".P" << std::endl;
        while( j != n )
        {
            if( main_help[i][j] == '\n' )
            {
                s << std::endl << ".P" << std::endl;
                ++j;
                continue;
            }
            k = main_help[i].find( "\n", j );
            if( k == std::string::npos ) k = n;
            if( main_help[i][j] == '.' ) s << '\\';
            s << main_help[i].substr( j, k - j );
            j = k;
        }
    }

    // write OPTIONS section
    s << std::endl << ".SH OPTIONS" << std::endl;
    for( it = arg_help_strings.begin(); it != arg_help_strings.end(); ++it )
    {
        if( it->first )
            s << ".IP \"" << it->first->longname << '"' << std::endl << it->second << std::endl;
        else
            s << ".SS " << it->first->longname << std::endl;
    }
    for( it = option_help_strings.begin(); it != option_help_strings.end(); ++it )
    {
        if( !it->first )
        {
            s << ".SS " << it->second << std::endl;
            continue;
        }

        s << ".IP \"";
        if( it->first->longname.empty() )
            s << "-" << it->first->shortname;
        else if( it->first->shortname.empty() )
            s << "--" << it->first->longname;
        else
            s << "-" << it->first->shortname << ", --" << it->first->longname;
        s << '"' << std::endl << it->second << std::endl;
    }
    s << std::endl;
}

/* Ensure g++ instantiates the template types we expect to use */

#define DECLARE_OPTION_TYPE( T )                                                               \
    template void ProgOptions::addOpt< T >( const std::string&, const std::string&, T*, int ); \
    template bool ProgOptions::getOpt< T >( const std::string&, T* );

#define DECLARE_VALUED_OPTION_TYPE( T )                                                                       \
    DECLARE_OPTION_TYPE( T )                                                                                  \
    template void ProgOptions::getOptAllArgs< T >( const std::string&, std::vector< T >& );                   \
    template void ProgOptions::addRequiredArg< T >( const std::string&, const std::string&, T*, int );        \
    template void ProgOptions::addOptionalArgs< T >( unsigned, const std::string&, const std::string&, int ); \
    template T ProgOptions::getReqArg< T >( const std::string& );                                             \
    template void ProgOptions::getArgs< T >( const std::string&, std::vector< T >& );

DECLARE_OPTION_TYPE( void )
DECLARE_VALUED_OPTION_TYPE( int )
DECLARE_VALUED_OPTION_TYPE( double )
DECLARE_VALUED_OPTION_TYPE( std::string )
DECLARE_VALUED_OPTION_TYPE( std::vector< int > )