option.h

This software aims to create an applet and panel tools to manage a wireless interface card, such as

//
// Option.h
//
// $Id: //poco/Main/Util/include/Util/Option.h#1 $
//
// Definition of the Option class.
//
// Copyright (c) 2004-2005, Guenter Obiltschnig/Applied Informatics.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//
// 3. Redistributions in any form must be accompanied by information on
//    how to obtain complete source code for this software and any
//    accompanying software that uses this software.  The source code
//    must either be included in the distribution or be available for no
//    more than the cost of distribution plus a nominal fee, and must be
//    freely redistributable under reasonable conditions.  For an
//    executable file, complete source code means the source code for all
//    modules it contains.  It does not include source code for modules or
//    files that typically accompany the major components of the operating
//    system on which the executable file runs.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
// COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
// ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
//


#ifndef Util_Option_INCLUDED
#define Util_Option_INCLUDED


#ifndef Util_Util_INCLUDED
#include "Util/Util.h"
#endif


Util_BEGIN


class Util_API Option
	/// This class represents and stores the properties
	/// of a command line option.
	///
	/// An option has a full name, an optional short name,
	/// a description (used for printing a usage statement),
	/// and an optional argument name.
	/// An option can be optional or required.
	/// An option can be repeatable, which means that it can
	/// be given more than once on the command line.
	///
	/// An option can be part of an option group. At most one
	/// option of each group may be specified on the command
	/// line.
	///
	/// Option instances are value objects.
	///
	/// Typcally, after construction, an Option object is immediately
	/// passed to an Options object.
	///
	/// An Option object can be created by chaining the constructor
	/// with any of the setter methods, as in the following example:
	///
	///     Option versionOpt("include", "I", "specify an include directory")
	///        .required(false)
	///        .repeatable(true)
	///        .argument("directory");
{
public:
	Option();
		/// Creates an empty Option.

	Option(const Option& option);
		/// Creates an option from another one.

	Option(const std::string& fullName, const std::string& shortName);
		/// Creates an option with the given properties.

	Option(const std::string& fullName, const std::string& shortName, const std::string& description, bool required = false);
		/// Creates an option with the given properties.

	Option(const std::string& fullName, const std::string& shortName, const std::string& description, bool required, const std::string& argName, bool argOptional = false);
		/// Creates an option with the given properties.

	~Option();
		/// Destroys the Option.

	Option& operator = (const Option& option);
		/// Assignment operator.
		
	Option& shortName(const std::string& name);
		/// Sets the short name of the option.
		
	Option& fullName(const std::string& name);
		/// Sets the full name of the option.
		
	Option& description(const std::string& text);
		/// Sets the description of the option.
		
	Option& required(bool flag);
		/// Sets whether the option is required (flag == true)
		/// or optional (flag == false).

	Option& repeatable(bool flag);
		/// Sets whether the option can be specified more than once
		/// (flag == true) or at most once (flag == false).
		
	Option& argument(const std::string& name, bool required = true);
		/// Specifies that the option takes an (optional or required)
		/// argument.
		
	Option& noArgument();
		/// Specifies that the option does not take an argument (default).

	Option& group(const std::string& group);
		/// Specifies the option group the option is part of.

	const std::string& shortName() const;
		/// Returns the short name of the option.
		
	const std::string& fullName() const;
		/// Returns the full name of the option.
		
	const std::string& description() const;
		/// Returns the description of the option.
		
	bool required() const;
		/// Returns true if the option is required, false if not.
	
	bool repeatable() const;
		/// Returns true if the option can be specified more than
		/// once, or false if at most once.
	
	bool takesArgument() const;
		/// Returns true if the options takes an (optional) argument.
		
	bool argumentRequired() const;
		/// Returns true if the argument is required.

	const std::string& argumentName() const;
		/// Returns the argument name, if specified.
		
	const std::string& group() const;
		/// Returns the option group the option is part of,
		/// or an empty string, if the option is not part of
		/// a group.
		
	bool matchesShort(const std::string& option) const;
		/// Returns true if the given option string matches the
		/// short name.
		///
		/// The first characters of the option string must match
		/// the short name of the option (case sensitive),
		/// or the option string must partially match the full
		/// name (case insensitive).

	bool matchesFull(const std::string& option) const;
		/// Returns true if the given option string matches the
		/// full name.
		///
		/// The option string must partially match the full
		/// name (case insensitive).
		
	void process(const std::string& option, std::string& arg) const;
		/// Verifies that the given option string matches the
		/// requirements of the option, and extracts the option argument,
		/// if present.
		///
		/// If the option string is okay and carries an argument,
		/// the argument is returned in arg.
		///
		/// Throws a MissingArgumentException if a required argument
		/// is missing. Throws an UnexpectedArgumentException if an
		/// argument has been found, but none is expected. 

private:
	std::string _shortName;
	std::string _fullName;
	std::string _description;
	bool        _required;
	bool        _repeatable;
	std::string _argName;
	bool        _argRequired;
	std::string _group;
};


//
// inlines
//


inline const std::string& Option::shortName() const
{
	return _shortName;
}

	
inline const std::string& Option::fullName() const
{
	return _fullName;
}

	
inline const std::string& Option::description() const
{
	return _description;
}

	
inline bool Option::required() const
{
	return _required;
}


inline bool Option::repeatable() const
{
	return _repeatable;
}

	
inline bool Option::takesArgument() const
{
	return !_argName.empty();
}

	
inline bool Option::argumentRequired() const
{
	return _argRequired;
}


inline const std::string& Option::argumentName() const
{
	return _argName;
}


inline const std::string& Option::group() const
{
	return _group;
}


Util_END


#endif // Util_Option_INCLUDED