OptionBase Class Reference

#include <CommandLine.h>

Inheritance diagram for OptionBase:

Static Public Member Functions
static std::vector< std::string >	parseOptions (int argc, char *argv[], std::string description, std::string callFormat)

Protected Types
typedef std::pair< std::string, std::string >	PossibilityDescription
	Name/description pairs.
typedef std::vector< std::pair< std::string, std::string > >	PossibilityDescriptions
template<typename T >
using	OptionPossibility = std::tuple< T, std::string, std::string >

Protected Member Functions
	OptionBase (std::string name, std::string description)
	OptionBase (std::string name, std::string description, PossibilityDescriptions possibilityDescriptions)
virtual bool	parseAndSetValue (const std::string value)=0
	From a given string, set the value of this option.
virtual bool	isBool (void) const
virtual bool	isMultiple (void) const
	Whether this option is an OptionMultiple.
virtual bool	canSet (void) const =0
	Can this option be set?

Static Protected Member Functions
template<typename T >
static PossibilityDescriptions	extractPossibilityDescriptions (const std::vector< OptionPossibility< T > > possibilities)
static std::map< std::string, OptionBase * > &	getOptionsMap (void)

Protected Attributes
std::string	name
std::string	description
PossibilityDescriptions	possibilityDescriptions
	For when we have possibilities like in an OptionMap.

Static Private Member Functions
static std::string	buildUsage (const std::string description, const std::string argv0, const std::string callFormat)
static OptionBase *	getOption (const std::string optName)
	Find option based on name in options map. Returns nullptr if not found.
static void	usageAndExit (const std::string usage, bool error)
	Print usage and exit. If error is set, print to stderr and exits with code 1.
static bool	isHelpName (const std::string name)
	Returns whether name is one of the reserved help options.

Detailed Description

Definition at line 20 of file CommandLine.h.

Member Typedef Documentation

OptionPossibility

template<typename T >

using OptionBase::OptionPossibility = std::tuple<T, std::string, std::string>

protected

Value/name/description tuples. If [1] is the value on the commandline for an option, we'd set the value for the associated Option to [0].

Definition at line 30 of file CommandLine.h.

PossibilityDescription

typedef std::pair<std::string, std::string> OptionBase::PossibilityDescription

protected

Name/description pairs.

Definition at line 24 of file CommandLine.h.

PossibilityDescriptions

typedef std::vector<std::pair<std::string, std::string> > OptionBase::PossibilityDescriptions

protected

Definition at line 25 of file CommandLine.h.

Constructor & Destructor Documentation

OptionBase() [1/2]

OptionBase::OptionBase ( std::string  name, std::string  description  )

inlineprotected

Definition at line 33 of file CommandLine.h.

        : OptionBase(name, description, {})
    {
    }

OptionBase() [2/2]

OptionBase::OptionBase ( std::string  name, std::string  description, PossibilityDescriptions  possibilityDescriptions  )

inlineprotected

Definition at line 38 of file CommandLine.h.

        : name(name), description(description), possibilityDescriptions(possibilityDescriptions)
    {
        assert(name[0] != '-' && "OptionBase: name starts with '-'");
        assert(!isHelpName(name) && "OptionBase: reserved help name");
        assert(getOptionsMap().find(name) == getOptionsMap().end() && "OptionBase: duplicate option");
 
        // Types with empty names (i.e., OptionMultiple) can handle things themselves.
        if (!name.empty())
        {
            // Standard name=value option.
            getOptionsMap()[name] = this;
        }
    }

Member Function Documentation

buildUsage()

static std::string OptionBase::buildUsage ( const std::string  description, const std::string  argv0, const std::string  callFormat  )

inlinestaticprivate

Sets the usage member to a usage string, built from the static list of options. argv0 is argv[0] and callFormat is how the command should be used, minus the command name (e.g. "[options] <input-bitcode...>".

Definition at line 174 of file CommandLine.h.

    {
        // Determine longest option to split into two columns: options and descriptions.
        unsigned longest = 0;
        for (const std::pair<std::string, OptionBase *> nopt : getOptionsMap())
        {
            const std::string name = std::get<0>(nopt);
            const OptionBase *option = std::get<1>(nopt);
            if (option->isMultiple())
            {
                // For Multiple, description goes in left column.
                if (option->description.length() > longest) longest = option->description.length();
            }
            else
            {
                if (name.length() > longest) longest = name.length();
            }
 
            for (const PossibilityDescription &pd : option->possibilityDescriptions)
            {
                const std::string possibility = std::get<0>(pd);
                if (possibility.length() + 3 > longest) longest = possibility.length() + 3;
            }
        }
 
        std::stringstream ss;
 
        ss << description << std::endl << std::endl;
 
        ss << "USAGE:" << std::endl;
        ss << "  " << argv0 << " " << callFormat << std::endl;
        ss << std::endl;
 
        ss << "OPTIONS:" << std::endl;
 
        // Required as we have OptionMultiples doing a many-to-one in options.
        std::unordered_set<const OptionBase *> handled;
        for (const std::pair<std::string, OptionBase *> nopt : getOptionsMap())
        {
            const std::string name = std::get<0>(nopt);
            const OptionBase *option = std::get<1>(nopt);
            if (handled.find(option) != handled.end()) continue;
            handled.insert(option);
 
            if (option->isMultiple())
            {
                // description
                //   -name1      - description
                //   -name2      - description
                //   ...
                ss << "  " << option->description << std::endl;
                for (const PossibilityDescription &pd : option->possibilityDescriptions)
                {
                    const std::string possibility = std::get<0>(pd);
                    const std::string description = std::get<1>(pd);
                    ss << "    -" << possibility << std::string(longest - possibility.length() + 2, ' ');
                    ss << "- " << description << std::endl;
                }
            }
            else
            {
                // name  - description
                // or
                // name     - description
                //   =opt1    - description
                //   =opt2    - description
                //   ...
                ss << "  -" << name << std::string(longest - name.length() + 2, ' ');
                ss << "- " << option->description << std::endl;
                for (const PossibilityDescription &pd : option->possibilityDescriptions)
                {
                    const std::string possibility = std::get<0>(pd);
                    const std::string description = std::get<1>(pd);
                    ss << "    =" << possibility << std::string(longest - possibility.length() + 2, ' ');
                    ss << "- " << description << std::endl;
                }
            }
        }
 
        // Help message.
        ss << std::endl;
        ss << "  -help" << std::string(longest - 4 + 2, ' ') << "- show usage and exit" << std::endl;
        ss << "  -h" << std::string(longest - 1 + 2, ' ') << "- show usage and exit" << std::endl;
 
        // How to set boolean options.
        ss << std::endl;
        ss << "Note: for boolean options, -name true and -name false are invalid." << std::endl;
        ss << "      Use -name, -name=true, or -name=false." << std::endl;
 
        return ss.str();
    }

canSet()

virtual bool OptionBase::canSet ( void  ) const

protectedpure virtual

Can this option be set?

Implemented in Option< T >, Option< bool >, Option< std::string >, Option< u32_t >, OptionMap< T >, OptionMap< BVDataPTAImpl::PTBackingType >, OptionMap< enum PTAStat::ClockType >, OptionMap< PointsTo::Type >, OptionMap< SVF::NodeIDAllocator::Strategy >, OptionMap< u32_t >, OptionMultiple< T >, OptionMultiple< PointerAnalysis::PTATY >, and OptionMultiple< u32_t >.

extractPossibilityDescriptions()

template<typename T >

static PossibilityDescriptions OptionBase::extractPossibilityDescriptions ( const std::vector< OptionPossibility< T > >  possibilities )

inlinestaticprotected

Definition at line 294 of file CommandLine.h.

    {
        PossibilityDescriptions possibilityDescriptions;
        for (const OptionPossibility<T> &op : possibilities)
        {
            possibilityDescriptions.push_back(std::make_pair(std::get<1>(op), std::get<2>(op)));
        }
 
        return possibilityDescriptions;
    }

getOption()

static OptionBase * OptionBase::getOption ( const std::string  optName )

inlinestaticprivate

Find option based on name in options map. Returns nullptr if not found.

Definition at line 269 of file CommandLine.h.

    {
        auto optIt = getOptionsMap().find(optName);
        if (optIt == getOptionsMap().end()) return nullptr;
        else return optIt->second;
    }

getOptionsMap()

static std::map< std::string, OptionBase * > & OptionBase::getOptionsMap ( void  )

inlinestaticprotected

Not unordered map so we can have sorted names when building the usage string. Map of option names to their object.

Definition at line 307 of file CommandLine.h.

    {
        // Not static member to avoid initialisation order problems.
        static std::map<std::string, OptionBase *> options;
        return options;
    }

isBool()

virtual bool OptionBase::isBool ( void  ) const

inlineprotectedvirtual

Whether this option represents a boolean. Important as such arguments don't require a value.

Reimplemented in Option< T >, Option< bool >, Option< std::string >, and Option< u32_t >.

Definition at line 58 of file CommandLine.h.

    {
        return false;
    }

isHelpName()

static bool OptionBase::isHelpName ( const std::string  name )

inlinestaticprivate

Returns whether name is one of the reserved help options.

Definition at line 285 of file CommandLine.h.

    {
        static std::vector<std::string> helpNames = {"help", "h", "-help"};
        return std::find(helpNames.begin(), helpNames.end(), name) != helpNames.end();
    }

isMultiple()

virtual bool OptionBase::isMultiple ( void  ) const

inlineprotectedvirtual

Whether this option is an OptionMultiple.

Reimplemented in OptionMultiple< T >, OptionMultiple< PointerAnalysis::PTATY >, and OptionMultiple< u32_t >.

Definition at line 64 of file CommandLine.h.

    {
        return false;
    }

parseAndSetValue()

virtual bool OptionBase::parseAndSetValue ( const std::string  value )

protectedpure virtual

From a given string, set the value of this option.

Implemented in Option< T >, Option< bool >, Option< std::string >, Option< u32_t >, OptionMap< T >, OptionMap< BVDataPTAImpl::PTBackingType >, OptionMap< enum PTAStat::ClockType >, OptionMap< PointsTo::Type >, OptionMap< SVF::NodeIDAllocator::Strategy >, OptionMap< u32_t >, OptionMultiple< T >, OptionMultiple< PointerAnalysis::PTATY >, and OptionMultiple< u32_t >.

parseOptions()

static std::vector< std::string > OptionBase::parseOptions ( int  argc, char *  argv[], std::string  description, std::string  callFormat  )

inlinestatic

Parse all constructed OptionBase children, returning positional arguments in the order they appeared.

Definition at line 75 of file CommandLine.h.

    {
        const std::string usage = buildUsage(description, std::string(argv[0]), callFormat);
 
        std::vector<std::string> positionalArguments;
 
        for (int i = 1; i < argc; ++i)
        {
            std::string arg(argv[i]);
            if (arg.empty()) continue;
            if (arg[0] != '-')
            {
                // Positional argument. NOT a value to another argument because we
                // "skip" over evaluating those without the corresponding argument.
                positionalArguments.push_back(arg);
                continue;
            }
 
            // Chop off '-'.
            arg = arg.substr(1);
 
            std::string argName;
            std::string argValue;
            OptionBase *opt = nullptr;
 
            size_t equalsSign = arg.find('=');
            if (equalsSign != std::string::npos)
            {
                // Argument has an equal sign, i.e. argName=argValue
                argName = arg.substr(0, equalsSign);
                if (isHelpName(argName)) usageAndExit(usage, false);
 
                opt = getOption(argName);
                if (opt == nullptr)
                {
                    std::cerr << "Unknown option: " << argName << std::endl;
                    usageAndExit(usage, true);
                }
 
                argValue = arg.substr(equalsSign + 1);
            }
            else
            {
                argName = arg;
                if (isHelpName(argName)) usageAndExit(usage, false);
 
                opt = getOption(argName);
                if (opt == nullptr)
                {
                    std::cerr << "Unknown option: " << argName << std::endl;
                    usageAndExit(usage, true);
                }
 
                // No equals sign means we may need next argument.
                if (opt->isBool())
                {
                    // Booleans do not accept -arg true/-arg false.
                    // They must be -arg=true/-arg=false.
                    argValue = "true";
                }
                else if (opt->isMultiple())
                {
                    // Name is the value and will be converted to an enum.
                    argValue = argName;
                }
                else if (i + 1 < argc)
                {
                    // On iteration, we'll skip the value.
                    ++i;
                    argValue = std::string(argv[i]);
                }
                else
                {
                    std::cerr << "Expected value for: " << argName << std::endl;
                    usageAndExit(usage, true);
                }
            }
 
            if (!opt->canSet())
            {
                std::cerr << "Unable to set: " << argName << "; check for duplicates" << std::endl;
                usageAndExit(usage, true);
            }
 
            bool valueSet = opt->parseAndSetValue(argValue);
            if (!valueSet)
            {
                std::cerr << "Bad value for: " << argName << std::endl;
                usageAndExit(usage, true);
            }
        }
 
        return positionalArguments;
    }

usageAndExit()

static void OptionBase::usageAndExit ( const std::string  usage, bool  error  )

inlinestaticprivate

Print usage and exit. If error is set, print to stderr and exits with code 1.

Definition at line 277 of file CommandLine.h.

    {
        if (error) std::cerr << usage;
        else std::cout << usage;
        std::exit(error ? 1 : 0);
    }

Member Data Documentation

description

std::string OptionBase::description

protected

Definition at line 317 of file CommandLine.h.

name

std::string OptionBase::name

protected

Definition at line 316 of file CommandLine.h.

possibilityDescriptions

PossibilityDescriptions OptionBase::possibilityDescriptions

protected

For when we have possibilities like in an OptionMap.

Definition at line 319 of file CommandLine.h.

---

The documentation for this class was generated from the following file:

• /home/runner/work/SVF/SVF/svf/include/Util/CommandLine.h