libcruft-util/options.hpp

/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * Copyright 2013-2014 Danny Robson <danny@nerdcruft.net>
 */


#ifndef __UTIL_OPTIONS_HPP
#define __UTIL_OPTIONS_HPP

#include <iostream>
#include <list>
#include <map>
#include <memory>
#include <sstream>
#include <stdexcept>


/**
 * Maximum length of an option, its value, and any supplementary characters
 * required for interpreting them. Ie, strlen("--foo=bar")
 */
const size_t MAX_CHUNK_LENGTH = 1023;

namespace util {
    /**
     * The generic base class for all options.
     *
     * Stores enough information to determine whether a short or long style option
     * has been specified. The `execute' methods performs an action if the option
     * is either present, or present with a value.
     *
     * By default they will throw an exception and can be relied upon to provide
     * some form of abort action.
     */
    class option {
            protected:
                    char              m_shortopt;
                    const std::string m_longopt;
                    const std::string m_description;
                    bool              m_required;
                    bool              m_found;

            public:
                    option (char        _letter,
                            const char *_name,
                            const char *_desc,
                            bool        _required);

                    virtual ~option() { ; }

                    virtual void execute (void) = 0;
                    virtual void execute (const std::string& _data) = 0;
                    virtual void finish  (void);

                    virtual bool is_required (void) const
                        { return m_required; }

                    virtual void reset(void)
                        { m_found = false; }

                    virtual char shortopt(void) const
                        { return m_shortopt; }
                    virtual const std::string& longopt(void) const
                        { return m_longopt; }
                    virtual const std::string& description(void) const
                        { return m_description; }
    };


    /**
     * Specifies a debugging or deprecated option.
     *
     * The option will be recognised but no action will be performed when
     * encountered. A description will still be visible when usage information is
     * printed.
     */
    class nulloption : public option {
        public:
            nulloption(char        _letter,
                    const char *_name,
                    const char *_desc,
                    bool        _required = false);

            virtual void execute(void)
                { m_found = true; }
            virtual void execute(const std::string&)
                { m_found = true; }
    };


    /**
     * Sets a boolean value to reflect if the option has been specified.
     *
     * A provided boolean pointer will be set to false if the option isn't
     * present, true if present.
     * Assumes that the user will not modify the value for the duration of option
     * processing.
     * Throws an exception if a value is specified for the option.
     */
    class presentoption : public option {
        protected:
            bool *m_data;

        public:
            presentoption(char        _letter,
                          const char *_name,
                          const char *_desc,
                          bool       *_data,
                          bool        _required = false);

            virtual void execute(void);
            virtual void execute(const std::string& data)
                { option::execute(data); }

            virtual void reset(void)
                { *m_data = false; }
    };


    /**
     * Parses a value given on the command line into a specified type.
     *
     * Given a value, return it to the user via the specified pointer. Uses the
     * istream operators to read the value, so it should be relatively generic.
     * If the value is malformed then an exception will be thrown.
     * If there is no value, then perform the default action.
     *
     * It is safe to assume that when no value has been extracted the data pointer
     * provided will not be overwritten. Useful for pre-loading with default
     * values.
     */
    template<typename T>
    class valueoption : public option {
        protected:
            T *m_data;

        public:
            valueoption(char        _letter,
                        const char *_name,
                        const char *_desc,
                        T          *_data,
                        bool        _required = false):
                option (_letter, _name, _desc, _required),
                m_data (_data)
            { ; }

            virtual void execute(void)
                { option::execute(); }
            virtual void execute(const std::string& data) {
                get_arg(data, m_data);
                m_found = true;
            }

        protected:
            // Retrieve string to value conversion
            static
            T& get_arg(const std::string &arg,
                       T                 *val);

            static
            T& get_arg(const std::string &_arg,
                       T                 *val,
                       const T           &defaultval) {
                try {
                    return get_arg(_arg, val);
                } catch(...) {
                    return *val = defaultval;
                }
            }

    };


    /**
     * Interpret a (possibly) numeric value as a data size.
     *
     * A developer specifies the default scale of the value and what base it is
     * to be interpreted in - when not otherwise explicitly stated in the
     * arguments.
     *
     * Recognises various postfixes and modifiers to a numeric value such as MiB.
     */
    class bytesoption : public valueoption<size_t> {
        public:
            /* Description of types available for parsing
            */
            enum bytestype {
                BYTES_SINGLE = 0,
                BYTES_KILO   = 1,
                BYTES_MEGA   = 2,
                BYTES_GIGA   = 3,
                BYTES_TERA   = 4,
                BYTES_PETA   = 5,
                BYTES_EXA    = 6,

                // Currently does not support yota or zeta as there can be
                // trouble converting them without loss into 64bit quantities.
                // That and they're fricking huge...
                //
                // BYTES_ZETA,
                // BYTES_YOTA,

                NUM_BYTESTYPE
            };

            enum bytesmodifier {
                BYTES_BASE2,
                BYTES_BASE10,

                NUM_BYTESMODIFIER
            };

        protected:
            bytestype m_type;
            bytesmodifier m_modifier;

            static bytestype type_from_character(char c);


        public:
            /* Constructors and methods
            */
            bytesoption(char           _letter,
                        const char    *_name,
                        const char    *_desc,
                        size_t        *_data,
                        bytestype      _type     = BYTES_SINGLE,
                        bytesmodifier  _modifier = BYTES_BASE2,
                        bool           _required = false);

            virtual void execute(const std::string &);
    };


    /**
     * High level handler for option registration, dispatch, and interpretation.
     *
     * The processor is the central point of operation on a program's arguments.
     * It contains a list of all options which will interpret and act upon any
     * arguments. These must be registered by the user prior to argument parsing,
     * each of which must be primed with data to act upon separately.
     *
     * parse_args will perform minimal interpretation of the arguments to allow
     * dispatch to registered options. No direct actions upon any input is
     * performed within this class, merely dispatch and tokenisation.
     */
    class processor {
        protected:
            std::map<char, option *> m_shortopt;
            std::map<std::string, option *> m_longopt;

            std::list<std::unique_ptr<option>> m_options;

            // The command to execute the application
            std::string m_command;

        protected:
            unsigned int parse_short(int pos, int argc, const char ** argv);
            unsigned int parse_long(int pos, int argc, const char ** argv);

        public:
            processor();
            ~processor();

            void print_usage(void);

            // TODO: Use function overloading here...
            void parse_args(int argc, const char ** argv);
            void parse_args(int argc, char ** argv)
                { parse_args(argc, const_cast<const char**>(argv)); }
            void parse_stream(std::istream & is);


            void add_option(std::unique_ptr<option>);

            std::unique_ptr<option> remove_option(char letter);
            std::unique_ptr<option> remove_option(const char * name);
            std::unique_ptr<option> remove_option(const std::string& name)
                { return remove_option (name.c_str()); }
            std::unique_ptr<option> remove_option(const option *opt)
                { return remove_option (opt->longopt ()); }
    };
}

#endif