/*******************************************************************************
***  This file is part of QtArgs.                                            ***
***                                                                          ***
***  Copyright (C) 2011, 2012, 2014                                          ***
***  CodeGNU Solutions <Licensing _AT_ CodeGNU _DOT_ com>                    ***
***                                                                          ***
***  This program is free software: you can redistribute it and/or modify    ***
***  it under the terms of the GNU Lesser General Public License as          ***
***  published by the Free Software Foundation, either version 3 of the      ***
***  License, or (at your option) any later version.                         ***
***                                                                          ***
***  This program is distributed in the hope that it will be useful, but     ***
***  WITHOUT ANY WARRANTY; without even the implied warranty of              ***
***  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    ***
***  See the GNU Lesser General Public License for more details.             ***
***                                                                          ***
***  You should have received a copy of the GNU Lesser General Public        ***
***  License along with this program. If not, see                            ***
***  <http://www.gnu.org/licenses/>.                                         ***
*******************************************************************************/
#ifndef QARGS_H_
#define QARGS_H_
/**
 * @file qargs.h
 * @brief Argument Processing
 * @details Declartions for procsssing the command-line arguments.
 */

#include <QObject>
#include <QList>
#include <QtDebug>
#include <QStringList>

#include "qargs_global.h"

class QChar;
class QString;
template < class KeyType, class ValueType >
class QMap;


/**
 * @brief Value Type Converter
 * @details Converts the supplied string into the type of the expected value.
 *
 * @param[in] value         The value to be converted.
 * @param[out] converted    The location to place the converted value.
 *
 * @return True when the conversion is successful, false else-wise.
 */
template< typename Expected >
bool convertToValueType(const QString& value, Expected& converted);

/**
 * @brief Manage Command-line Arguments
 * @details Provides the means to process arguments passed from the command-line
 *  in a type safe manner. The command-line arguments are supported in an
 *  Operating System specific manner: the slash '/' for Windows and a
 *  dash '-' for Unix based systems. A short named option starts with the
 *  argument marker followed immediately a single character then a space and
 *  the value for the argument. A long named option starts the same as the
 *  short named option character, but the marker character is repeated twice for
 *  Unicies and only once for Windows. The long named option is then followed by
 *  a word that describes the option or dash seperated list of words. For the
 *  Unicies the long named option is followed by the option long separator, by
 *  default the equal('=') sign. In Windows, the long option name is followed by
 *  a space. When procressing the arguments, the short named argument is
 *  regarded as having an higher precidence than the long named argument.
 *  Command-line help for all options is automatically generated, and available
 *  to the user in an operating system specific manner, i.e. Windows users can
 *  access help by using a question('?') mark and Unix based systems can access
 *  using 'h'. In addition to single value arguments, there is support for
 *  arguments which take more than one value. These arguments are start in the
 *  same maner as both short and long named options; however, they do not have
 *  a long option seperator, instead they are followed by the values with each
 *  value seperated by a space(' ').
 */
class QTARGS_SHARED_EXPORT QArgs: public QObject
{
    Q_OBJECT

signals:
    //{ Argument Value Retrieved Signals
    /**
	* @brief Provided Flag Argument
	* @details The signal that is fired for an argument flag.
	*
	* @param[in] argument  The short name option that was provided.
	*/
    void argumentValue(const QChar& argument) const;
    /**
	* @brief Provided Boolean Argument Value
	* @details The signal that is fired when an argument is provided by a user
	*  with a boolean value.
	*
	* @param[in] argument  The short name option that was provided.
	* @param[in] value     The contents supplied by the user, else the default
	*                       value is used.
	*/
    void argumentValue(const QChar& argument, bool value) const;
    /**
	* @brief Provided Double Precision Argument Value
	* @details The signal that is fired when an argument is provided by a user
	*  with a single or double precision value.
	*
	* @param[in] argument  The short name option that was provided.
	* @param[in] value     The contents supplied by the user, else the default
	*                       value is used.
	*/
    void argumentValue(const QChar& argument, qreal value) const;
    /**
	* @brief Provided Signed 8-bit Argument Value
	* @details The signal that is fired when an argument is provided by a user
	*  with an 8-bit integer value.
	*
	* @param[in] argument  The short name option that was provided.
	* @param[in] value     The contents supplied by the user, else the default
	*                       value is used.
	*/
    void argumentValue(const QChar& argument, qint8 value) const;
    /**
	* @brief Provided Signed 16-bit Argument Value
	* @details The signal that is fired when an argument is provided by a user
	*  with a 16-bit integer value.
	*
	* @param[in] argument  The short name option that was provided.
	* @param[in] value     The contents supplied by the user, else the default
	*                       value is used.
	*/
    void argumentValue(const QChar& argument, qint16 value) const;
    /**
	* @brief Provided Signed 32-bit Argument Value
	* @details The signal that is fired when an argument is provided by a user
	*  with a 32-bit integer value.
	*
	* @param[in] argument  The short name option that was provided.
	* @param[in] value     The contents supplied by the user, else the default
	*                       value is used.
	*/
    void argumentValue(const QChar& argument, qint32 value) const;
    /**
	* @brief Provided Signed 64-bit Argument Value
	* @details The signal that is fired when an argument is provided by a user
	*  with a 64-bit integer value.
	*
	* @param[in] argument  The short name option that was provided.
	* @param[in] value     The contents supplied by the user, else the default
	*                       value is used.
	*/
    void argumentValue(const QChar& argument, qint64 value) const;
    /**
	* @brief Provided Unsigned 8-bit Argument Value
	* @details The signal that is fired when an argument is provided by a user
	*  with an unsigned 8-bit integer value.
	*
	* @param[in] argument  The short name option that was provided.
	* @param[in] value     The contents supplied by the user, else the default
	*                       value is used.
	*/
    void argumentValue(const QChar& argument, quint8 value) const;
    /**
	* @brief Provided Unsigned 16-bit Argument Value
	* @details The signal that is fired when an argument is provided by a user
	*  with an unsigned 16-bit integer value.
	*
	* @param[in] argument  The short name option that was provided.
	* @param[in] value     The contents supplied by the user, else the default
	*                       value is used.
	*/
    void argumentValue(const QChar& argument, quint16 value) const;
    /**
	* @brief Provided Unsigned 32-bit Argument Value
	* @details The signal that is fired when an argument is provided by a user
	*  with an unsigned 32-bit integer value.
	*
	* @param[in] argument  The short name option that was provided.
	* @param[in] value     The contents supplied by the user, else the default
	*                       value is used.
	*/
    void argumentValue(const QChar& argument, quint32 value) const;
    /**
	* @brief Provided Unsigned 64-bit Argument Value
	* @details The signal that is fired when an argument is provided by a user
	*  with an unsigned 64-bit integer value.
	*
	* @param[in] argument  The short name option that was provided.
	* @param[in] value     The contents supplied by the user, else the default
	*                       value is used.
	*/
    void argumentValue(const QChar& argument, quint64 value) const;
    /**
	* @brief Provided Character Argument Value
	* @details The signal that is fired when an argument is provided by a user
	*  with a character value.
	*
	* @param[in] argument  The short name option that was provided.
	* @param[in] value     The contents supplied by the user, else the default
	*                       value is used.
	*/
    void argumentValue(const QChar& argument, const QChar& value) const;
    /**
	* @brief Provided String Argument Value
	* @details The signal that is fired when an argument is provided by a user
	*  with a string value.
	*
	* @param[in] argument  The short name option that was provided.
	* @param[in] value     The contents supplied by the user, else the default
	*                       value is used.
	*/
    void argumentValue(const QChar& argument, const QString& value) const;
    //}


    //{ User Flag Request Signals
    /**
	* @brief Argument Help Message
	* @details The signal that is fired when the user flagged a request for
	*  the usage help of the application supported arguments.
	*
	* @param[in] text  The full help message.
	*/
    void help(const QString& text) const;
    /**
	* @brief Legal Information
	* @details The signal that is fired when the user flagged a request for
	*  information regarding the legal information of the library.
	*
	* @param[in] text  The full legal information message.
	*/
    void about(const QString& text) const;
    //}

public:
    /**
	* @brief Short Name Caseing Options
	* @details The possible option's for the case-sensativity of a short name.
	*/
    enum Sensitivity
    {
	   /// The short name option is case-sensative.
	   CASE_SENSATIVE,
	   /// The short name option is not case-sensative.
	   CASE_INSENSATIVE
    };
    /**
	* @brief Supported Boolean Types
	* @details Determines the types of boolean keywords which are supported as
	*  an option. The different types of boolean keywords may be combined
	*  together to allow support for more than one type at a time.
	*/
    enum BooleanSupport
    {
	   /// Support boolean option values which may be "true" or "false".
	   TRUE_OR_FALSE = 0x1,
	   /// Support boolean option values which may be "yes" or "no".
	   YES_OR_NO = 0x2,
	   /// Support boolean option values which may be "on" or "off".
	   ON_OR_OFF = 0x4,
	   /// Support boolean option values which may be "t" or "f".
	   T_OR_F = 0x8,
	   /// Support boolean option values which may be "y" or "n".
	   Y_OR_N = 0x10,
	   /// Support boolean option values which may be "1" or "0".
	   ONE_OR_ZERO = 0x20,
	   /// Support all boolean option types.
	   ALL = 0xFF
    };

    /**
	* @brief Command-line Resource Processor
	* @details Handles the parsing and initialising of the options and values
	*  provided by the user from the command-line. The long named arguments the
	*  expected to have their values in the same array row as the long named
	*  argument for all Unicies but in the following row for Windows. The short
	*  named arguments are expected to always have their values in the
	*  following row.
	*
	* @param[in] argc      The number of arguments from the command-line.
	* @param[in] argv      The arguments from the command-line.
	* @param[in] caseing   Determines the case sensativity of the short named
	*                       options.
	*
	* @post All object members are initialised and ready for use. The object
	*  member for the argument properties contains a short named operating
	*  system specific help command line argument. The object member for
	*  locking is in the unlocked state. The object's argument list member is
	*  populated with a white-spaced trimmed list of the supplied values.
	*/
    QArgs(int argc, const char* argv[], Sensitivity caseing = CASE_SENSATIVE);
    /**
	* @brief Command-line Resource Processor
	* @details Handles the parsing and initialising of the options and values
	*  provided by the user from the command-line. The long named arguments the
	*  expected to have their values in the same array row as the long named
	*  argument for all Unicies but in the following row for Windows. The short
	*  named arguments are expected to always have their values in the
	*  following row.
	*
	* @param[in] argc      The number of arguments from the command-line.
	* @param[in] argv      The arguments from the command-line.
	* @param[in] caseing   Determines the case sensativity of the short named
	*                       options.
	*
	* @post All object members are initialised and ready for use. The object
	*  member for the argument properties contains a short named operating
	*  system specific help command line argument. The object member for
	*  locking is in the unlocked state. The object's argument list member is
	*  populated with a white-spaced trimmed list of the supplied values.
	*/
    QArgs(int argc, char* argv[], Sensitivity caseing = CASE_SENSATIVE);


    //{ Argument Functions
    /**
	* @brief Listing of Arguments
	* @details Provides a list of all arguments as they were provided at the
	*  time of initialisation.
	*
	* @return The argument list member.
	*/
    const QStringList& arguments() const;
    /**
	* @brief Argument Indicator Mark
	* @details Provides the indicator a user would use to identify an argument
	*  for his particular operating system.
	*
	* @return The marker for an argument prefix.
	*/
    const QChar& marker() const;
    /**
	* @brief Number of Arguments
	* @details The number of actual arguments provided by the user on the
	*  command line. The argument count does not include in the totalling the
	*  values supplied on the command line, nor the name of the application
	*  when supplied by the operating system.
	*
	* @return Number of short and long named argument count.
	*/
    qint32 count() const;
    /**
	* @brief Create Supported Argument
	* @details Provides the mechanism to indicate what options are supported by
	*  an application. The argument option's description is used to display the
	*  help information to the user. If the provided value is a null string,
	*  the argument will not appear in the help request to the user.
	*
	* @param[in] shortName     The short name of the option.
	* @param[in] longName      The long name of the option.
	* @param[in] description   The usage description for the option.
	* @param[in] takesValue    Flag indicating the option requires a value,
	*                           when true.
	* @param[in] required      A flag indicating the option is required by the
	*                           application to run when true.
	*
	* @throw domain_error  When the developer attempts to use either the sort
	*                       or long option names which are reserved for
	*                       requesting to display the help information.
	* @throw logic_error   When either the short or long option names are
	*                       empty.
	* @throw logic_error   When either the short or long option names were
	*                       already listed as supported.
	* @throw logic_error   When an attempt to add another argument option after
	*                       the developer locked the argument support list.
	* @throw runtime_error When an option is required by the user and the
	*                       user did not supply either the short or long
	*                       option.
	*
	* @post The object's supported argument list member contains the short-name
	*  argument and the associated expected properties.
	*/
    void addSupported(const QChar& shortName, const QString& longName,
		  const QString& description, bool takesValue = false,
		  bool required = false);
    /**
	* @brief Checks for Argument
	* @details Tests for the existence of a short or long named argument in
	*  the arguments supplied by the user from the command-line.
	*
	* @param[in] shortName The character which identifies the short-named
	*                       option.
	*
	* @return True if option is present either in short or long name form,
	*  false else-wise.
	*/
    bool hasArgument(const QChar& shortName) const;
    /**
	* @brief Lock-down Supported Arguments
	* @details Prevents adding further supported arguments to the list of
	*  supported arguements.
	*
	* @post The object member for locking supported arguments is enabled.
	*/
    void lock();
    //}


    //{ About & Help Functions
    /**
	* @brief Check Help Display Requested
	* @details Determines if the user provided the help argument request on the
	*  command-line. The argument help request option is determined by the
	*  Operating System running the application.
	*
	* @return True if either the short or long named for the help argument
	*  is in the command line, false else-wise.
	*/
    bool hasHelp() const;
    /**
	* @brief Display Help Information
	* @details Outputs all argument help information. Help information is
	*  written in the following format:\n
	* usage: APPLICATION_NAME [options]\n
	* Options: \n
	* ARGUMENT &lt;value&gt; \\t DESCRIPTION
	*
	* @pre Standard output buffer is open and ready to be written.
	*
	* @post The standard output buffer is populated with all the arguments
	*  whose description is not null. Once the help argument text is placed
	*  on the buffer, the object's signal for help requested is fired.
	*/
    void showHelp() const;
    /**
	* @brief About QtArgs
	* @details Output information regarding the copyright,
	*  license information, etc..
	*
	* @pre Standard output buffer is ready for write.
	*
	* @post Output buffer contains the copyright and license information.
	*/
    void about() const;
    //}


    //{ Option Value Retreival Functions
    /**
	* @brief Argument Option Boolean Value
	* @details Provides access to the value from a short or long named argument
	*  supplied by the user from the command-line. Once the value for the
	*  option is determined the signal for the argument value is fired. A
	*  command line option may be any of the supported boolean types or
	*  combinations thereof. In addition, all argument values provided by the
	*  user are verified for both being valid and required.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	* @param[in] types         The boolean group type supported for the option.
	*
	* @return The value supplied from the command-line which matches the short
	*  name or long name option and is a valid boolean group, else the default
	*  value is provided.
	*/
    bool value(const QChar& shortName, bool defaultValue,
			BooleanSupport types = TRUE_OR_FALSE) const;
    /**
	* @brief Option Double Precision Value
	* @details Provides access to the value from a short or long named argument
	*  supplied by the user from the command-line. Once the value for the
	*  option is determined the signal for the argument value is fired. In
	*  addition, all argument values provided by the user are verified for both
	*  being valid and required.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	*
	* @return Any value supplied from the command-line which matches the short
	*  name or long name option and is a valid single or double precision
	*  number, else the default value is provided.
	*/
    qreal value(const QChar& shortName, qreal defaultValue) const;
    /**
	* @brief Option Signed 8-bit Value
	* @details Provides access to the value from a short or long named argument
	*  supplied by the user from the command-line. Once the value for the
	*  option is determined the signal for the argument value is fired. In
	*  addition, all argument values provided by the user are verified for both
	*  being valid and required.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	*
	* @return Any value supplied from the command-line which matches the short
	*  name or long name option and is a valid signed 8-bit integer number,
	*  else the default value is provided.
	*/
    qint8 value(const QChar& shortName, qint8 defaultValue) const;
    /**
	* @brief Option Signed 16-bit Value
	* @details Provides access to the value from a short or long named argument
	*  supplied by the user from the command-line. Once the value for the
	*  option is determined the signal for the argument value is fired. In
	*  addition, all argument values provided by the user are verified for both
	*  being valid and required.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	*
	* @return Any value supplied from the command-line which matches the short
	*  name or long name option and is a valid signed 16-bit integer number,
	*  else the default value is provided.
	*/
    qint16 value(const QChar& shortName, qint16 defaultValue) const;
    /**
	* @brief Option Signed 32-bit Value
	* @details Provides access to the value from a short or long named argument
	*  supplied by the user from the command-line. Once the value for the
	*  option is determined the signal for the argument value is fired. In
	*  addition, all argument values provided by the user are verified for both
	*  being valid and required.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	*
	* @return Any value supplied from the command-line which matches the short
	*  name or long name option and is a valid signed 32-bit integer number,
	*  else the default value is provided.
	*/
    qint32 value(const QChar& shortName, qint32 defaultValue) const;
    /**
	* @brief Option Signed 64-bit Value
	* @details Provides access to the value from a short or long named argument
	*  supplied by the user from the command-line. Once the value for the
	*  option is determined the signal for the argument value is fired. In
	*  addition, all argument values provided by the user are verified for both
	*  being valid and required.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	*
	* @return Any value supplied from the command-line which matches the short
	*  name or long name option and is a valid signed 64-bit integer number,
	*  else the default value is provided.
	*/
    qint64 value(const QChar& shortName, qint64 defaultValue) const;
    /**
	* @brief Option Unsigned 8-bit Value
	* @details Provides access to the value from a short or long named argument
	*  supplied by the user from the command-line. Once the value for the
	*  option is determined the signal for the argument value is fired. In
	*  addition, all argument values provided by the user are verified for both
	*  being valid and required.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	*
	* @return Any value supplied from the command-line which matches the short
	*  name or long name option and is a valid unsigned 8-bit integer number,
	*  else the default value is provided.
	*/
    quint8 value(const QChar& shortName, quint8 defaultValue) const;
    /**
	* @brief Option Unsigned 16-bit Value
	* @details Provides access to the value from a short or long named argument
	*  supplied by the user from the command-line. Once the value for the
	*  option is determined the signal for the argument value is fired. In
	*  addition, all argument values provided by the user are verified for both
	*  being valid and required.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	*
	* @return Any value supplied from the command-line which matches the short
	*  name or long name option and is a valid unsigned 16-bit integer number,
	*  else the default value is provided.
	*/
    quint16 value(const QChar& shortName, quint16 defaultValue) const;
    /**
	* @brief Option Unsigned 32-bit Value
	* @details Provides access to the value from a short or long named argument
	*  supplied by the user from the command-line. Once the value for the
	*  option is determined the signal for the argument value is fired. In
	*  addition, all argument values provided by the user are verified for both
	*  being valid and required.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	*
	* @return Any value supplied from the command-line which matches the short
	*  name or long name option and is a valid unsigned 32-bit integer number,
	*  else the default value is provided.
	*/
    quint32 value(const QChar& shortName, quint32 defaultValue) const;
    /**
	* @brief Option Unsigned 64-bit Value
	* @details Provides access to the value from a short or long named argument
	*  supplied by the user from the command-line. Once the value for the
	*  option is determined the signal for the argument value is fired. In
	*  addition, all argument values provided by the user are verified for both
	*  being valid and required.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	*
	* @return Any value supplied from the command-line which matches the short
	*  name or long name option and is a valid unsigned 64-bit integer number,
	*  else the default value is provided.
	*/
    quint64 value(const QChar& shortName, quint64 defaultValue) const;
    /**
	* @brief Argument Option Character Value
	* @details Provides access to the value from a short or long named argument
	*  supplied by the user from the command-line. Once the value for the
	*  option is determined the signal for the argument value is fired. In
	*  addition, all argument values provided by the user are verified for both
	*  being valid and required.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	*
	* @return Any value supplied from the command-line which matches the short
	*  name or long name option and is a valid character, else the default
	*  value is provided.
	*/
    QChar value(const QChar& shortName, const QChar& defaultValue) const;
    /**
	* @brief Argument Option String Value
	* @details Provides access to the value from a short or long named argument
	*  supplied by the user from the command-line. Once the value for the
	*  option is determined the signal for the argument value is fired. In
	*  addition, all argument values provided by the user are verified for both
	*  being valid and required.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	*
	* @return Any value supplied from the command-line which matches the short
	*  name or long name option and is a valid string, else the default value
	*  is provided.
	*/
    QString value(const QChar& shortName, const QString& defaultValue) const;
    /**
	* @brief Argument Option Values
	* @details Provides access to the values from a short or long named
	*  argument supplied by the user from the command-line. In addition, all
	*  argument values provided by the user are verified for both being valid
	*  and required. The default support for the expected types are: signed
	*  integers, unsigned integers, single precision, double precision,
	*  characters, and strings.
	*
	* @param[in] shortName     The short-name of the argument option.
	* @param[in] defaultValue  The value to use when an argument is not
	*                           supplied by the user from the command-line.
	*
	* @post Any errors with a specific supplied value is written to the
	*  standard error buffer.
	*
	* @return All values supplied from the command-line which match the short
	*  name or long name option and are valid, else only the default value
	*  is provided.
	*/
    template <typename Expected>
    QList< Expected > values(const QChar& shortName,
					    const Expected& defaultValue) const;
    //}

private:
    //{ Members
    /**
	* @brief Argument Option Information
	* @details Represents the characteristics an argument posses.
	*/
    struct Properties
    {
	   /// The value used to identify an option by a short name.
	   QChar shortName;
	   /// The value used to identify an option by a long name.
	   QString longName;
	   /// Short sentence that describes the purpose of an option.
	   QString description;
	   /// A flag which indicates the option takes a value. When the value is
	   ///  true, the option takes a value.
	   bool needsValue;
	   /// A flag which indicates the option is required to be supplied by the
	   ///  user for the application to function properly. When the value is
	   ///  true, the option is required.
	   bool required;
    };
    /// Used to easily map the properties of an argument with it's short name.
    typedef QMap< QChar, Properties > PropertyArguments;

    /// Holder for all the options supplied by the user from the command-line.
    QStringList mArguments;
    /// Holder for all the arguments and their properties that are supported
    ///  by an application.
    PropertyArguments mSupported;
    /// Flag which when true indicates that short names are case sensative.
    bool mIsCaseSensative;
    /// Flag which when true indicates no further options are allowed.
    bool mIsLocked;
    /// Flag which when true indicates the arguments were already verified.
    mutable bool mAreArgumentsVerified;


    /// The marker used on the command-line to identify an option. The marker
    ///  is specific to the host operating system, where a stroke ('/') is
    ///  supported for Windows systems and dash ('-') for Unix systems.
    static const QChar& ARGUMENT_MARKER;
    /// The marker used on the command-line to identify the separation of the
    ///  option value from the long name. This is traditionally the
    ///  equal ('=') sign. This is only used for Unicies.
    static const QChar& ARGUMENT_LONG_ASSIGNMENT;
    /// The Operating System specific marker used on the command-line by the
    ///  user to request the help information for all the arguments supported.
    ///  For Windows it is a question mark ('?'). For Unix systems it is a
    ///  the character 'h'.
    static const QChar& SHORT_HELP;
    /// The other Operating System specific marker used on the command-line
    ///  by the user to request the help information for all the arguments
    ///  supported. For Windows it is the character 'h'. For Unix systems it
    ///  is a question mark ('?').
    static const QChar& OTHER_OS_SHORT_HELP;
    /// The specific word used on the command-line by the user to request
    ///  the help information for all the arguments supported. By default this
    ///  is the word "help".
    static const QString& LONG_HELP;
    /// The minimum number number of characters for a valid long option.
    static const qint8 MINIMUM_LONG_OPTION;
    //}

    //{ Member functions
    /**
	* @brief Verifies All Arguments
	* @details All arguments provided by the user and which are supported by
	*  the developer are validated. This guarantees each of the options
	*  provided by the user are supported by the developer. After the initial
	*  call, all subsequent calls do not result in validation.
	*
	* @throw logic_error   When verification is performed before any arguments
	*                       are registered as being supported.
	* @throw runtime_error When an argument is provided by the user that is
	*                       not registered as being supported by the developer.
	*/
    void verifySupport() const;
    /**
	* @brief Index Of Argument
	* @details Provides the index in the argument list of the argument provided
	*  by the user from the command-line.
	*
	* @pre All supported arguments must be established.
	*
	* @param[in] name  The short-name option to locate.
	*
	* @return If the short-name argument is found, the index starting from zero
	*  is given, else-wise negative one (-1) is given.
	*/
    int shortNameIndex(const QChar& name) const;
    /**
	* @brief Index Of Argument
	* @details Provides the index in the argument list of the argument provided
	*  by the user from the command-line.
	*
	* @pre All supported arguments must be established.
	*
	* @param[in] name  The short-name option to locate.
	*
	* @return If the long-name argument is found, the index starting from zero
	*  is given, else-wise negative one (-1) is given.
	*/
    int longNameIndex(const QChar& name) const;
    //}

    // Only automatically allow unit testing in the debug mode.
#ifndef QT_NO_DEBUG_OUTPUT
    /// Allows the unit tests to make zero assumptions while running.
    friend class QArgsUT;
#endif
};

template< typename Expected >
QList< Expected > QArgs::values(const QChar& shortName,
						  const Expected& defaultValue) const
{
    qDebug() << "QArgs::values(const QChar&, const Expected&)" << shortName
		   << defaultValue;
    QList< Expected > values;
    int shortIndex(shortNameIndex(shortName)), index,
		  longIndex(longNameIndex(shortName));

    verifySupport();

    if (-1 != shortIndex)
	   index = shortIndex + 1;
    else if (-1 != longIndex)
	   index = longIndex + 1;
    else
	   index = -1;

    Expected testValue;
    do
    {
	   if (convertToValueType(this->mArguments.at(index), testValue))
		  values.append(testValue);
	   else
		  qWarning() << "Failed to convert " << this->mArguments.at(index)
				   << "into expected value type.";
	  ++index;
    }
    while ((index < this->mArguments.size())
		 && (ARGUMENT_MARKER != this->mArguments.at(index).at(0)));

    if (values.isEmpty())
	   values.append(defaultValue);

    return values;
}

#endif