// ****************************************************************************
// ^FILE: options.c - implement the functions defined in <options.h>
//
// ^HISTORY:
//    01/16/92	Brad Appleton	<bradapp@enteract.com>	Created
//
//    03/23/93	Brad Appleton	<bradapp@enteract.com>
//    - Added OptIstreamIter class
//
//    10/08/93	Brad Appleton	<bradapp@enteract.com>
//    - Added "hidden" options
//
//    02/08/94	Brad Appleton	<bradapp@enteract.com>
//    - Added "OptionSpec" class
//    - Permitted use of stdio instead of iostreams via #ifdef USE_STDIO
//
//    03/08/94	Brad Appleton	<bradapp@enteract.com>
//    - completed support for USE_STDIO
//    - added #ifdef NO_USAGE for people who always want to print their own
//    - Fixed stupid NULL pointer error in OptionsSpec class
//
//    07/31/97	Brad Appleton	<bradapp@enteract.com>
//    - Added PARSE_POS control flag and POSITIONAL return value.
// ^^**************************************************************************

// #include <stdlib.h>
#include <ctype.h>
#include <string.h>

#include "options.h"

using namespace std;

extern "C" {
void exit(int);
}

static const char ident[] = "@(#)Options  1.05";

// I need a portable version of "tolower" that does NOT modify
// non-uppercase characters.
//
#define TOLOWER(c) (isupper(c) ? tolower(c) : c)

// Use this to shut the compiler up about NULL strings
#define NULLSTR (char *) NULL

// ******************************************************** insertion operators

// If you are using <stdio.h> then you need this stuff!
// If you are using <iostream.h> then #ifdef this stuff out
//

#ifdef USE_STDIO

// Implement just enough of ostream to get this file to compile
//

static const char endl = '\n';

class ostream
{
public:
    ostream(FILE *fileptr)
        : fp(fileptr)
    {
    }

    ostream &operator<<(char ch);

    ostream &operator<<(const char *str);

    ostream &write(const char *buf, unsigned bufsize);

private:
    FILE *fp;
};

ostream &ostream::operator<<(char ch)
{
    fputc(ch, fp);
    return *this;
}

ostream &ostream::operator<<(const char *str)
{
    fputs(str, fp);
    return *this;
}

ostream &ostream::write(const char *buf, unsigned)
{
    fputs(buf, fp);
    return *this;
}

static ostream cerr(stderr);
static ostream cout(stdout);

#endif /* USE_STDIO */

// ************************************************************** OptIter

OptIter::~OptIter(void)
{
}

const char *OptIter::operator()(void)
{
    const char *elt = curr();
    (void)next();
    return elt;
}

// ************************************************************** OptIterRwd

OptIterRwd::OptIterRwd(void)
{
}

OptIterRwd::~OptIterRwd(void)
{
}

// ************************************************************** OptArgvIter

OptArgvIter::~OptArgvIter(void)
{
}

const char *OptArgvIter::curr(void)
{
    return ((ndx == ac) || (av[ndx] == NULL)) ? NULLSTR : av[ndx];
}

void OptArgvIter::next(void)
{
    if ((ndx != ac) && av[ndx])
        ++ndx;
}

const char *OptArgvIter::operator()(void)
{
    return ((ndx == ac) || (av[ndx] == NULL)) ? NULLSTR : av[ndx++];
}

void OptArgvIter::rewind(void)
{
    ndx = 0;
}

// ************************************************************** OptStrTokIter

static const char WHITESPACE[] = " \t\n\r\v\f";
const char *OptStrTokIter::default_delims = WHITESPACE;

OptStrTokIter::OptStrTokIter(const char *tokens, const char *delimiters)
    : len(unsigned(strlen(tokens)))
    , str(tokens)
    , seps(delimiters)
    , cur(NULLSTR)
    , tokstr(NULLSTR)
{
    if (seps == NULL)
        seps = default_delims;
    tokstr = new char[len + 1];
    (void)::strcpy(tokstr, str);
    cur = ::strtok(tokstr, seps);
}

OptStrTokIter::~OptStrTokIter(void)
{
    delete[] tokstr;
}

const char *OptStrTokIter::curr(void)
{
    return cur;
}

void OptStrTokIter::next(void)
{
    if (cur)
        cur = ::strtok(NULL, seps);
}

const char *OptStrTokIter::operator()(void)
{
    const char *elt = cur;
    if (cur)
        cur = ::strtok(NULL, seps);
    return elt;
}

void OptStrTokIter::rewind(void)
{
    (void)::strcpy(tokstr, str);
    cur = ::strtok(tokstr, seps);
}

// ************************************************************* OptIstreamIter

#ifdef vms
enum
{
    c_COMMENT = '!'
};
#else
enum
{
    c_COMMENT = '#'
};
#endif

const unsigned OptIstreamIter::MAX_LINE_LEN = 1024;

// Constructor
OptIstreamIter::OptIstreamIter(istream &input)
    : is(input)
    , tok_iter(NULL)
{
#ifdef USE_STDIO
    fprintf(stderr, "%s: Can't use OptIstreamIter class:\n", "OptIstreamIter::OptIstreamIter");
    fprintf(stderr, "\tOptions(3C++) was compiled with USE_STDIO #defined.\n");
    exit(-1);
#endif /* USE_STDIO */
}

// Destructor
OptIstreamIter::~OptIstreamIter(void)
{
    delete tok_iter;
}

const char *OptIstreamIter::curr(void)
{
#ifdef USE_STDIO
    return NULLSTR;
#else
    const char *result = NULLSTR;
    if (tok_iter)
        result = tok_iter->curr();
    if (result)
        return result;
    fill();
    return (!is) ? NULLSTR : tok_iter->curr();
#endif /* USE_STDIO */
}

void OptIstreamIter::next(void)
{
#ifdef USE_STDIO
    return;
#else
    const char *result = NULLSTR;
    if (tok_iter)
        result = tok_iter->operator()();
    if (result)
        return;
    fill();
    if (!is)
        tok_iter->next();
#endif /* USE_STDIO */
}

const char *OptIstreamIter::operator()(void)
{
#ifdef USE_STDIO
    return NULLSTR;
#else
    const char *result = NULLSTR;
    if (tok_iter)
        result = tok_iter->operator()();
    if (result)
        return result;
    fill();
    return (!is) ? NULLSTR : tok_iter->operator()();
#endif /* USE_STDIO */
}

// What we do is this: for each line of text in the istream, we use
// a OptStrTokIter to iterate over each token on the line.
//
// If the first non-white character on a line is c_COMMENT, then we
// consider the line to be a comment and we ignore it.
//
void OptIstreamIter::fill(void)
{
#ifdef USE_STDIO
    return;
#else
    char buf[OptIstreamIter::MAX_LINE_LEN];
    do
    {
        *buf = '\0';
        is.getline(buf, sizeof(buf));
        char *ptr = buf;
        while (isspace(*ptr))
            ++ptr;
        if (*ptr && (*ptr != c_COMMENT))
        {
            delete tok_iter;
            tok_iter = new OptStrTokIter(ptr);
            return;
        }
    } while (is);
#endif /* USE_STDIO */
}

// **************************************************** Options class utilities

// Is this option-char null?
inline static int isNullOpt(char optchar)
{
    return ((!optchar) || isspace(optchar) || (!isprint(optchar)));
}

// Check for explicit "end-of-options"
inline static int isEndOpts(const char *token)
{
    return ((token == NULL) || (!::strcmp(token, "--")));
}

// See if an argument is an option
inline static int isOption(unsigned flags, const char *arg)
{
    return (((*arg != '\0') || (arg[1] != '\0')) && ((*arg == '-') || ((flags & Options::PLUS) && (*arg == '+'))));
}

// See if we should be parsing only options or if we also need to
// parse positional arguments
inline static int isOptsOnly(unsigned flags)
{
    return (flags & Options::PARSE_POS) ? 0 : 1;
}

// return values for a keyword matching function
enum kwdmatch_t
{
    NO_MATCH,
    PARTIAL_MATCH,
    EXACT_MATCH
};

// ---------------------------------------------------------------------------
// ^FUNCTION: kwdmatch - match a keyword
//
// ^SYNOPSIS:
//    static kwdmatch_t kwdmatch(src, attempt, len)
//
// ^PARAMETERS:
//    char * src -- the actual keyword to match
//    char * attempt -- the possible keyword to compare against "src"
//    int len -- number of character of "attempt" to consider
//               (if 0 then we should use all of "attempt")
//
// ^DESCRIPTION:
//    See if "attempt" matches some prefix of "src" (case insensitive).
//
// ^REQUIREMENTS:
//    - attempt should be non-NULL and non-empty
//
// ^SIDE-EFFECTS:
//    None.
//
// ^RETURN-VALUE:
//    An enumeration value of type kwdmatch_t corresponding to whether
//    We had an exact match, a partial match, or no match.
//
// ^ALGORITHM:
//    Trivial
// ^^-------------------------------------------------------------------------
static kwdmatch_t kwdmatch(const char *src, const char *attempt, int len = 0)
{
    int i;

    if (src == attempt)
        return EXACT_MATCH;
    if ((src == NULL) || (attempt == NULL))
        return NO_MATCH;
    if ((!*src) && (!*attempt))
        return EXACT_MATCH;
    if ((!*src) || (!*attempt))
        return NO_MATCH;

    for (i = 0; ((i < len) || (len == 0)) && (attempt[i]) && (attempt[i] != ' '); i++)
    {
        if (TOLOWER(src[i]) != TOLOWER(attempt[i]))
            return NO_MATCH;
    }

    return (src[i]) ? PARTIAL_MATCH : EXACT_MATCH;
}

// **************************************************************** OptionSpec

// Class that represents an option-specification
//    *NOTE*:: Assumes that the char-ptr given to the constructor points
//             to storage that will NOT be modified and whose lifetime will
//             be as least as long as the OptionSpec object we construct.
//
class OptionSpec
{
public:
    OptionSpec(const char *decl = NULLSTR)
        : hidden(0)
        , spec(decl)
    {
        if (spec == NULL)
            spec = NULL_spec;
        CheckHidden();
    }

    OptionSpec(const OptionSpec &cp)
        : hidden(cp.hidden)
        , spec(cp.spec)
    {
    }

    // NOTE: use default destructor!

    // Assign to another OptionSpec
    OptionSpec &operator=(const OptionSpec &cp)
    {
        if (this != &cp)
        {
            spec = cp.spec;
            hidden = cp.hidden;
        }
        return *this;
    }

    // Assign to a string
    OptionSpec &operator=(const char *decl)
    {
        if (spec != decl)
        {
            spec = decl;
            hidden = 0;
            CheckHidden();
        }
        return *this;
    }

    // Convert to char-ptr by returning the original declaration-string
    operator const char *() { return isHiddenOpt() ? (spec - 1) : spec; }
    // Is this option NULL?
    int isNULL(void) const { return ((spec == NULL) || (spec == NULL_spec)); }
    // Is this options incorrectly specified?
    int isSyntaxError(const char *name) const;

    // See if this is a Hidden option
    int isHiddenOpt(void) const { return hidden; }
    // Get the corresponding option-character
    char OptChar(void) const { return *spec; }
    // Get the corresponding long-option string
    const char *LongOpt(void) const { return (spec[1] && spec[2] && (!isspace(spec[2]))) ? (spec + 2) : NULLSTR; }
    // Does this option require an argument?
    int isValRequired(void) const { return ((spec[1] == ':') || (spec[1] == '+')); }
    // Does this option take an optional argument?
    int isValOptional(void) const { return ((spec[1] == '?') || (spec[1] == '*')); }
    // Does this option take no arguments?
    int isNoArg(void) const { return ((spec[1] == '|') || (!spec[1])); }
    // Can this option take more than one argument?
    int isList(void) const { return ((spec[1] == '+') || (spec[1] == '*')); }
    // Does this option take any arguments?
    int isValTaken(void) const { return (isValRequired() || isValOptional()); }
    // Format this option in the given buffer
    unsigned Format(char *buf, unsigned optctrls) const;

private:
    void CheckHidden(void)
    {
        if ((!hidden) && (*spec == '-'))
        {
            ++hidden;
            ++spec;
        }
    }

    unsigned hidden : 1; // hidden-flag
    const char *spec;    // string specification

    static const char NULL_spec[];
};

const char OptionSpec::NULL_spec[] = "\0\0\0";

int OptionSpec::isSyntaxError(const char *name) const
{
    int error = 0;
    if ((!spec) || (!*spec))
    {
        cerr << name << ": empty option specifier." << endl;
        cerr << "\tmust be at least 1 character long." << endl;
        ++error;
    }
    else if (spec[1] && (strchr("|?:*+", spec[1]) == NULL))
    {
        cerr << name << ": bad option specifier \"" << spec << "\"." << endl;
        cerr << "\t2nd character must be in the set \"|?:*+\"." << endl;
        ++error;
    }
    return error;
}

// ---------------------------------------------------------------------------
// ^FUNCTION: OptionSpec::Format - format an option-spec for a usage message
//
// ^SYNOPSIS:
//    unsigned OptionSpec::Format(buf, optctrls) const
//
// ^PARAMETERS:
//    char * buf -- where to print the formatted option
//    unsigned  optctrls -- option-parsing configuration flags
//
// ^DESCRIPTION:
//    Self-explanatory.
//
// ^REQUIREMENTS:
//    - buf must be large enough to hold the result
//
// ^SIDE-EFFECTS:
//    - writes to buf.
//
// ^RETURN-VALUE:
//    Number of characters written to buf.
//
// ^ALGORITHM:
//    Follow along in the source - it's not hard but it is tedious!
// ^^-------------------------------------------------------------------------
unsigned OptionSpec::Format(char *buf, unsigned optctrls) const
{
#ifdef NO_USAGE
    return (*buf = '\0');
#else
    static char default_value[] = "<value>";
    if (isHiddenOpt())
        return (unsigned)(*buf = '\0');
    char optchar = OptChar();
    const char *longopt = LongOpt();
    char *p = buf;

    const char *value = NULLSTR;
    int longopt_len = 0;
    int value_len = 0;

    if (longopt)
    {
        value = ::strchr(longopt, ' ');
        longopt_len = (value) ? (value - longopt) : ::strlen(longopt);
    }
    else
    {
        value = ::strchr(spec + 1, ' ');
    }
    while (value && (*value == ' '))
        ++value;
    if (value && *value)
    {
        value_len = ::strlen(value);
    }
    else
    {
        value = default_value;
        value_len = sizeof(default_value) - 1;
    }

    if ((optctrls & Options::SHORT_ONLY) && ((!isNullOpt(optchar)) || (optctrls & Options::NOGUESSING)))
    {
        longopt = NULLSTR;
    }
    if ((optctrls & Options::LONG_ONLY) && (longopt || (optctrls & Options::NOGUESSING)))
    {
        optchar = '\0';
    }
    if (isNullOpt(optchar) && (longopt == NULL))
    {
        *buf = '\0';
        return 0;
    }

    *(p++) = '[';

    // print the single character option
    if (!isNullOpt(optchar))
    {
        *(p++) = '-';
        *(p++) = optchar;
    }

    if ((!isNullOpt(optchar)) && (longopt))
        *(p++) = '|';

    // print the long option
    if (longopt)
    {
        *(p++) = '-';
        if (!(optctrls & (Options::LONG_ONLY | Options::SHORT_ONLY)))
        {
            *(p++) = '-';
        }
        strncpy(p, longopt, longopt_len);
        p += longopt_len;
    }

    // print any argument the option takes
    if (isValTaken())
    {
        *(p++) = ' ';
        if (isValOptional())
            *(p++) = '[';
        strcpy(p, value);
        p += value_len;
        if (isList())
        {
            strcpy(p, " ...");
            p += 4;
        }
        if (isValOptional())
            *(p++) = ']';
    }

    *(p++) = ']';
    *p = '\0';

    return (unsigned)strlen(buf);
#endif /* USE_STDIO */
}

// ******************************************************************* Options

#if (defined(MSWIN) || defined(OS2) || defined(MSDOS))
#define DIR_SEP_CHAR '\\'
#else
#define DIR_SEP_CHAR '/'
#endif

Options::Options(const char *name, const char *const optv[])
    : cmdname(name)
    , optvec(optv)
    , explicit_end(0)
    , optctrls(DEFAULT)
    , nextchar(NULLSTR)
    , listopt(NULLSTR)
{
    const char *basename = ::strrchr(cmdname, DIR_SEP_CHAR);
    if (basename)
        cmdname = basename + 1;
    check_syntax();
}

Options::~Options(void)
{
}

// Make sure each option-specifier has correct syntax.
//
// If there is even one invalid specifier, then exit ungracefully!
//
void Options::check_syntax(void) const
{
    int errors = 0;
    if ((optvec == NULL) || (!*optvec))
        return;

    for (const char *const *optv = optvec; *optv; optv++)
    {
        OptionSpec optspec = *optv;
        errors += optspec.isSyntaxError(cmdname);
    }
    if (errors)
        exit(127);
}

// ---------------------------------------------------------------------------
// ^FUNCTION: Options::match_opt - match an option
//
// ^SYNOPSIS:
//    const char * match_opt(opt, int  ignore_case) const
//
// ^PARAMETERS:
//    char opt -- the option-character to match
//    int  ignore_case -- should we ignore character-case?
//
// ^DESCRIPTION:
//    See if "opt" is found in "optvec"
//
// ^REQUIREMENTS:
//    - optvec should be non-NULL and terminated by a NULL pointer.
//
// ^SIDE-EFFECTS:
//    None.
//
// ^RETURN-VALUE:
//    NULL if no match is found,
//    otherwise a pointer to the matching option-spec.
//
// ^ALGORITHM:
//    foreach option-spec
//       - see if "opt" is a match, if so return option-spec
//    end-for
// ^^-------------------------------------------------------------------------
const char *Options::match_opt(char opt, int ignore_case) const
{
    if ((optvec == NULL) || (!*optvec))
        return NULLSTR;

    for (const char *const *optv = optvec; *optv; optv++)
    {
        OptionSpec optspec = *optv;
        char optchar = optspec.OptChar();
        if (isNullOpt(optchar))
            continue;
        if (opt == optchar)
        {
            return optspec;
        }
        else if (ignore_case && (TOLOWER(opt) == TOLOWER(optchar)))
        {
            return optspec;
        }
    }

    return NULLSTR; // not found
}

// ---------------------------------------------------------------------------
// ^FUNCTION: Options::match_longopt - match a long-option
//
// ^SYNOPSIS:
//   const char * Options::match_longopt(opt, len, ambiguous)
//
// ^PARAMETERS:
//    char * opt -- the long-option to match
//    int len -- the number of character of "opt" to match
//    int & ambiguous -- set by this routine before returning.
//
// ^DESCRIPTION:
//    Try to match "opt" against some unique prefix of a long-option
//    (case insensitive).
//
// ^REQUIREMENTS:
//    - optvec should be non-NULL and terminated by a NULL pointer.
//
// ^SIDE-EFFECTS:
//    - *ambiguous is set to '1' if "opt" matches >1 long-option
//      (otherwise it is set to 0).
//
// ^RETURN-VALUE:
//    NULL if no match is found,
//    otherwise a pointer to the matching option-spec.
//
// ^ALGORITHM:
//    ambiguous is FALSE
//    foreach option-spec
//       if we have an EXACT-MATCH, return the option-spec
//       if we have a partial-match then
//          if we already had a previous partial match then
//             set ambiguous = TRUE and return NULL
//          else
//             remember this options spec and continue matching
//          end-if
//       end-if
//    end-for
//    if we had exactly 1 partial match return it, else return NULL
// ^^-------------------------------------------------------------------------
const char *Options::match_longopt(const char *opt, int len, int &ambiguous) const
{
    kwdmatch_t result;
    const char *matched = NULLSTR;

    ambiguous = 0;
    if ((optvec == NULL) || (!*optvec))
        return NULLSTR;

    for (const char *const *optv = optvec; *optv; optv++)
    {
        OptionSpec optspec = *optv;
        const char *longopt = optspec.LongOpt();
        if (longopt == NULL)
            continue;
        result = kwdmatch(longopt, opt, len);
        if (result == EXACT_MATCH)
        {
            return optspec;
        }
        else if (result == PARTIAL_MATCH)
        {
            if (matched)
            {
                ++ambiguous;
                return NULLSTR;
            }
            else
            {
                matched = optspec;
            }
        }
    } // for

    return matched;
}

// ---------------------------------------------------------------------------
// ^FUNCTION: Options::parse_opt - parse an option
//
// ^SYNOPSIS:
//    int Options::parse_opt(iter, optarg)
//
// ^PARAMETERS:
//    OptIter & iter -- option iterator
//    const char * & optarg -- where to store any option-argument
//
// ^DESCRIPTION:
//    Parse the next option in iter (advancing as necessary).
//    Make sure we update the nextchar pointer along the way. Any option
//    we find should be returned and optarg should point to its argument.
//
// ^REQUIREMENTS:
//    - nextchar must point to the prospective option character
//
// ^SIDE-EFFECTS:
//    - iter is advanced when an argument completely parsed
//    - optarg is modified to point to any option argument
//    - if Options::QUIET is not set, error messages are printed on cerr
//
// ^RETURN-VALUE:
//    'c' if the -c option was matched (optarg points to its argument)
//    BADCHAR if the option is invalid (optarg points to the bad
//                                                   option-character).
//
// ^ALGORITHM:
//    It gets complicated -- follow the comments in the source.
// ^^-------------------------------------------------------------------------
int Options::parse_opt(OptIter &iter, const char *&optarg)
{
    listopt = NULLSTR; // reset the list pointer

    if ((optvec == NULL) || (!*optvec))
        return Options::ENDOPTS;

    // Try to match a known option
    OptionSpec optspec = match_opt(*(nextchar++), (optctrls & Options::ANYCASE));

    // Check for an unknown option
    if (optspec.isNULL())
    {
        // See if this was a long-option in disguise
        if (!(optctrls & Options::NOGUESSING))
        {
            unsigned save_ctrls = optctrls;
            const char *save_nextchar = nextchar;
            nextchar -= 1;
            optctrls |= (Options::QUIET | Options::NOGUESSING);
            int optchar = parse_longopt(iter, optarg);
            optctrls = save_ctrls;
            if (optchar > 0)
            {
                return optchar;
            }
            else
            {
                nextchar = save_nextchar;
            }
        }
        if (!(optctrls & Options::QUIET))
        {
            cerr << cmdname << ": unknown option -" << *(nextchar - 1) << "." << endl;
        }
        optarg = (nextchar - 1); // record the bad option in optarg
        return Options::BADCHAR;
    }

    // If no argument is taken, then leave now
    if (optspec.isNoArg())
    {
        optarg = NULLSTR;
        return optspec.OptChar();
    }

    // Check for argument in this arg
    if (*nextchar)
    {
        optarg = nextchar;  // the argument is right here
        nextchar = NULLSTR; // we've exhausted this arg
        if (optspec.isList())
            listopt = optspec; // save the list-spec
        return optspec.OptChar();
    }

    // Check for argument in next arg
    const char *nextarg = iter.curr();
    if ((nextarg != NULL) && (optspec.isValRequired() || (!isOption(optctrls, nextarg))))
    {
        optarg = nextarg; // the argument is here
        iter.next();      // end of arg - advance
        if (optspec.isList())
            listopt = optspec; // save the list-spec
        return optspec.OptChar();
    }

    // No argument given - if its required, thats an error
    optarg = NULLSTR;
    if (optspec.isValRequired() && !(optctrls & Options::QUIET))
    {
        cerr << cmdname << ": argument required for -" << optspec.OptChar() << " option." << endl;
    }
    return optspec.OptChar();
}

// ---------------------------------------------------------------------------
// ^FUNCTION: Options::parse_longopt - parse a long-option
//
// ^SYNOPSIS:
//    int Options::parse_longopt(iter, optarg)
//
// ^PARAMETERS:
//    OptIter & iter -- option iterator
//    const char * & optarg -- where to store any option-argument
//
// ^DESCRIPTION:
//    Parse the next long-option in iter (advancing as necessary).
//    Make sure we update the nextchar pointer along the way. Any option
//    we find should be returned and optarg should point to its argument.
//
// ^REQUIREMENTS:
//    - nextchar must point to the prospective option character
//
// ^SIDE-EFFECTS:
//    - iter is advanced when an argument completely parsed
//    - optarg is modified to point to any option argument
//    - if Options::QUIET is not set, error messages are printed on cerr
//
// ^RETURN-VALUE:
//    'c' if the the long-option corresponding to the -c option was matched
//         (optarg points to its argument)
//    BADKWD if the option is invalid (optarg points to the bad long-option
//                                                                     name).
//
// ^ALGORITHM:
//    It gets complicated -- follow the comments in the source.
// ^^-------------------------------------------------------------------------
int Options::parse_longopt(OptIter &iter, const char *&optarg)
{
    int len = 0, ambiguous = 0;

    listopt = NULLSTR; // reset the list-spec

    if ((optvec == NULL) || (!*optvec))
        return Options::ENDOPTS;

    // if a value is supplied in this argv element, get it now
    const char *val = strpbrk(nextchar, ":=");
    if (val)
    {
        len = val - nextchar;
        ++val;
    }

    // Try to match a known long-option
    OptionSpec optspec = match_longopt(nextchar, len, ambiguous);

    // Check for an unknown long-option
    if (optspec.isNULL())
    {
        // See if this was a short-option in disguise
        if ((!ambiguous) && (!(optctrls & Options::NOGUESSING)))
        {
            unsigned save_ctrls = optctrls;
            const char *save_nextchar = nextchar;
            optctrls |= (Options::QUIET | Options::NOGUESSING);
            int optchar = parse_opt(iter, optarg);
            optctrls = save_ctrls;
            if (optchar > 0)
            {
                return optchar;
            }
            else
            {
                nextchar = save_nextchar;
            }
        }
        if (!(optctrls & Options::QUIET))
        {
            cerr << cmdname << ": " << ((ambiguous) ? "ambiguous" : "unknown") << " option "
                 << ((optctrls & Options::LONG_ONLY) ? "-" : "--") << nextchar << "." << endl;
        }
        optarg = nextchar;  // record the bad option in optarg
        nextchar = NULLSTR; // we've exhausted this argument
        return (ambiguous) ? Options::AMBIGUOUS : Options::BADKWD;
    }

    // If no argument is taken, then leave now
    if (optspec.isNoArg())
    {
        if ((val) && !(optctrls & Options::QUIET))
        {
            cerr << cmdname << ": option " << ((optctrls & Options::LONG_ONLY) ? "-" : "--") << optspec.LongOpt()
                 << " does NOT take an argument." << endl;
        }
        optarg = val;       // record the unexpected argument
        nextchar = NULLSTR; // we've exhausted this argument
        return optspec.OptChar();
    }

    // Check for argument in this arg
    if (val)
    {
        optarg = val;       // the argument is right here
        nextchar = NULLSTR; // we exhausted the rest of this arg
        if (optspec.isList())
            listopt = optspec; // save the list-spec
        return optspec.OptChar();
    }

    // Check for argument in next arg
    const char *nextarg = iter.curr(); // find the next argument to parse
    if ((nextarg != NULL) && (optspec.isValRequired() || (!isOption(optctrls, nextarg))))
    {
        optarg = nextarg;   // the argument is right here
        iter.next();        // end of arg - advance
        nextchar = NULLSTR; // we exhausted the rest of this arg
        if (optspec.isList())
            listopt = optspec; // save the list-spec
        return optspec.OptChar();
    }

    // No argument given - if its required, thats an error
    optarg = NULLSTR;
    if (optspec.isValRequired() && !(optctrls & Options::QUIET))
    {
        const char *longopt = optspec.LongOpt();
        const char *spc = ::strchr(longopt, ' ');
        int longopt_len;
        if (spc)
        {
            longopt_len = spc - longopt;
        }
        else
        {
            longopt_len = ::strlen(longopt);
        }
        cerr << cmdname << ": argument required for " << ((optctrls & Options::LONG_ONLY) ? "-" : "--");
        cerr.write(longopt, longopt_len) << " option." << endl;
    }
    nextchar = NULLSTR; // we exhausted the rest of this arg
    return optspec.OptChar();
}

// ---------------------------------------------------------------------------
// ^FUNCTION: Options::usage - print usage
//
// ^SYNOPSIS:
//    void Options::usage(os, positionals)
//
// ^PARAMETERS:
//    ostream & os -- where to print the usage
//    char * positionals -- command-line syntax for any positional args
//
// ^DESCRIPTION:
//    Print command-usage (using either option or long-option syntax) on os.
//
// ^REQUIREMENTS:
//    os should correspond to an open output file.
//
// ^SIDE-EFFECTS:
//    Prints on os
//
// ^RETURN-VALUE:
//    None.
//
// ^ALGORITHM:
//    Print usage on os, wrapping long lines where necessary.
// ^^-------------------------------------------------------------------------
void Options::usage(ostream &os, const char *positionals) const
{
#ifdef NO_USAGE
    return;
#else
    const char *const *optv = optvec;
    unsigned cols = 79;
    int first, nloop;
    char buf[256];

    if ((optv == NULL) || (!*optv))
        return;

    // print first portion "usage: progname"
    os << "usage: " << cmdname;
    unsigned ll = strlen(cmdname) + 7;

    // save the current length so we know how much space to skip for
    // subsequent lines.
    //
    unsigned margin = ll + 1;

    // print the options and the positional arguments
    for (nloop = 0, first = 1; !nloop; optv++, first = 0)
    {
        unsigned len;
        OptionSpec optspec = *optv;

        // figure out how wide this parameter is (for printing)
        if (!*optv)
        {
            len = strlen(positionals);
            ++nloop; // terminate this loop
        }
        else
        {
            if (optspec.isHiddenOpt())
                continue;
            len = optspec.Format(buf, optctrls);
        }

        //  Will this fit?
        if ((ll + len + 1) > (cols - first))
        {
            os << '\n'; // No - start a new line;
#ifdef USE_STDIO
            for (int _i_ = 0; _i_ < margin; ++_i_)
                os << " ";
#else
            os.width(margin);
            os << "";
#endif
            ll = margin;
        }
        else
        {
            os << ' '; // Yes - just throw in a space
            ++ll;
        }
        ll += len;
        os << ((nloop) ? positionals : buf);
    } // for each ad

    os << endl;
#endif /* NO_USAGE */
}

// ---------------------------------------------------------------------------
// ^FUNCTION: Options::operator() - get options from the command-line
//
// ^SYNOPSIS:
//   int Options::operator()(iter, optarg)
//
// ^PARAMETERS:
//    OptIter & iter -- option iterator
//    const char * & optarg -- where to store any option-argument
//
// ^DESCRIPTION:
//    Parse the next option in iter (advancing as necessary).
//    Make sure we update the nextchar pointer along the way. Any option
//    we find should be returned and optarg should point to its argument.
//
// ^REQUIREMENTS:
//    None.
//
// ^SIDE-EFFECTS:
//    - iter is advanced when an argument is completely parsed
//    - optarg is modified to point to any option argument
//    - if Options::QUIET is not set, error messages are printed on cerr
//
// ^RETURN-VALUE:
//     0 if all options have been parsed.
//    'c' if the the option or long-option corresponding to the -c option was
//         matched (optarg points to its argument).
//    BADCHAR if the option is invalid (optarg points to the bad option char).
//    BADKWD if the option is invalid (optarg points to the bad long-opt name).
//    AMBIGUOUS if an ambiguous keyword name was given (optarg points to the
//         ambiguous keyword name).
//    POSITIONAL if PARSE_POS was set and the current argument is a positional
//         parameter (in which case optarg points to the positional argument).
//
// ^ALGORITHM:
//    It gets complicated -- follow the comments in the source.
// ^^-------------------------------------------------------------------------
int Options::operator()(OptIter &iter, const char *&optarg)
{
    int parse_opts_only = isOptsOnly(optctrls);
    if (parse_opts_only)
        explicit_end = 0;

    // See if we have an option left over from before ...
    if ((nextchar) && *nextchar)
    {
        return parse_opt(iter, optarg);
    }

    // Check for end-of-options ...
    const char *arg = NULLSTR;
    int get_next_arg = 0;
    do
    {
        arg = iter.curr();
        get_next_arg = 0;
        if (arg == NULL)
        {
            listopt = NULLSTR;
            return Options::ENDOPTS;
        }
        else if ((!explicit_end) && isEndOpts(arg))
        {
            iter.next(); // advance past end-of-options arg
            listopt = NULLSTR;
            explicit_end = 1;
            if (parse_opts_only)
                return Options::ENDOPTS;
            get_next_arg = 1; // make sure we look at the next argument.
        }
    } while (get_next_arg);

    // Do we have a positional arg?
    if (explicit_end || (!isOption(optctrls, arg)))
    {
        if (parse_opts_only)
        {
            return Options::ENDOPTS;
        }
        else
        {
            optarg = arg; // set optarg to the positional argument
            iter.next();  // advance iterator to the next argument
            return Options::POSITIONAL;
        }
    }

    iter.next(); // pass the argument that arg already points to

    // See if we have a long option ...
    if (!(optctrls & Options::SHORT_ONLY))
    {
        if ((*arg == '-') && (arg[1] == '-'))
        {
            nextchar = arg + 2;
            return parse_longopt(iter, optarg);
        }
        else if ((optctrls & Options::PLUS) && (*arg == '+'))
        {
            nextchar = arg + 1;
            return parse_longopt(iter, optarg);
        }
    }
    if (*arg == '-')
    {
        nextchar = arg + 1;
        if (optctrls & Options::LONG_ONLY)
        {
            return parse_longopt(iter, optarg);
        }
        else
        {
            return parse_opt(iter, optarg);
        }
    }

    // If we get here - it is because we have a list value
    OptionSpec optspec = listopt;
    optarg = arg; // record the list value
    return optspec.OptChar();
}