Changeset 1664 for code/branches/gui/src/core/CommandLine.h

Timestamp:

Aug 21, 2008, 9:23:11 PM (17 years ago)

Author:

rgrieder

Message:

• Finished CommandLineArgument completely. You can also use SetCommandLineSwitch to define boolean switches.
• Added StaticConversion to Covert.h (compile time type conversion checking)
• Fixed a bug in Exception
• Added getAllStrings() to SubString

File:

• code/branches/gui/src/core/CommandLine.h (modified) (8 diffs)

code/branches/gui/src/core/CommandLine.h

@@ -36 +36 @@
 #include "Exception.h"
 
-
 #define SetCommandLineArgument(name, defaultValue) \
     BaseCommandLineArgument& CmdArgumentDummyBoolVar##name \
     = orxonox::CommandLine::addCommandLineArgument(#name, defaultValue)
+#define SetCommandLineSwitch(name) \
+    BaseCommandLineArgument& CmdArgumentDummyBoolVar##name \
+    = orxonox::CommandLine::addCommandLineArgument(#name, false)
+
 
 namespace orxonox
 {
+    /**
+    @brief
+        Template struct which creates a distinct type for every integer constant.
+    @note
+        This allows to select a different function depending on a boolean value
+        when creating a new CommandLineArgument.
+        From 'Modern C++ Design' (Alexandrescu 2001).
+    */
+    template <int v>
+    struct Int2Type
+    {
+        enum { value = v };
+    };
+
+    /**
+    @brief
+        Base class for CommandLineArguments.
+    */
     class _CoreExport BaseCommandLineArgument
     {
@@ -48 +69 @@
 
     public:
+        //! Tells whether the value has been changed by the command line.
         bool hasDefaultValue() const { return bHasDefaultValue_; }
+        //! Returns the name of the argument.
         const std::string& getName() const { return name_; }
+
+        //! Returns the shortcut (example: "-p 22" for "--port 22") of the argument.
+        //! Evaluates to "" if none there is none.
         const std::string& getShortcut() const { return shortcut_; }
+        //! Sets the shortcut for the argument
         BaseCommandLineArgument& setShortcut(const std::string& shortcut)
         { this->shortcut_ = shortcut; return *this; }
+
+        //! Returns the usage information
+        const std::string& getInformation() const { return this->usageInformation_; }
+        //! Sets the option information when displaying orxonox usage.
+        BaseCommandLineArgument& setInformation(const std::string& usage)
+        { this->usageInformation_ = usage; return *this; }
 
     protected:
@@ -60 +93 @@
         { }
 
+        //! Undefined copy constructor
         BaseCommandLineArgument(const BaseCommandLineArgument& instance);
         virtual ~BaseCommandLineArgument() { }
 
+        //! Parses the value string of a command line argument.
         virtual void parse(const std::string& value) = 0;
 
+        //! Tells whether the value has been changed by the command line.
         bool bHasDefaultValue_;
 
     private:
-        std::string name_;
-        std::string shortcut_;
+        std::string name_;             //!< Name of the argument
+        std::string shortcut_;         //!< Shortcut of the argument. @see getShortcut().
+        std::string usageInformation_; //!< Tells about the usage of this parameter
     };
 
 
+    /**
+    @brief
+        Container class for a command line argument of type T.
+        
+        Whenever you want to have an option specified by a command line switch,
+        you need to first define it with SetCommandLineArgument(name, defaultValue).
+        It is then added to a map and possibly changed when the command line is being parsed.
+        If the option was not given, you can detect this by asking hasDefaultValue().
+        
+        There is a possibility to define a short cut so you can write "-p 20" instead of "--port 20".
+        Note the difference between "-" and "--"!
+        Also, there is no restriction to the number of strings you add after --name.
+        So "--startVector (2, 4, 5)" is perfectly legal.
+
+        Retrieving an argument is possible with the getCommandLineArgument function of the
+        CommandLine class. It is a Singleton, but the public interface is static.
+    */
     template <class T>
     class CommandLineArgument : public BaseCommandLineArgument
     {
+        // Only let CommandLine change the value.
         friend class CommandLine;
 
     public:
+        //! Returns the actual value of the argument. Can be equal to default value.
         T getValue() const { return value_; }
+        //! Returns the given default value as type T.
         T getDefaultValue() const { return defaultValue_; }
 
     private:
+        //! Constructor initialises both value_ and defaultValue_ with defaultValue.
         CommandLineArgument(const std::string& name, const T& defaultValue)
             : BaseCommandLineArgument(name)
@@ -91 +149 @@
         virtual void parse(const std::string& value);
 
-        T value_;
-        T defaultValue_;
+        T value_;            //!< The actual value
+        T defaultValue_;     //!< Default value. Should not be changed.
     };
 
+    /**
+    @brief
+        Parses a value string for a command line argument.
+        It simply uses convertValue(Output, Input) to do that.
+    */
     template <class T>
     void CommandLineArgument<T>::parse(const std::string& value)
@@ -108 +171 @@
     }
 
-
+    /**
+    @brief
+        Parses a value string for a command line argument.
+        It simply uses convertValue(Output, Input) to do that.
+        This is a template specialisation for bool type. That is necessary
+        so that you can have simple command line switches.
+    */
+    template <>
+    inline void CommandLineArgument<bool>::parse(const std::string& value)
+    {
+        if (convertValue(&this->value_, value))
+        {
+            this->bHasDefaultValue_ = false;
+        }
+        else if (value == "")
+        {
+            this->bHasDefaultValue_ = false;
+            this->value_ = true;
+        }
+        else
+        {
+            ThrowException(Argument, "Could not read command line argument '" + getName() + "'.");
+        }
+    }
+
+
+    /**
+    @brief
+        Global interface to command line options.
+        Allows to add and retrieve command line arguments. Also does the parsing.
+    @note
+        Internally it is a Singleton, but the public interface is static.
+    @see
+        CommandLineArgument
+    */
     class _CoreExport CommandLine
     {
     public:
 
-        static void parse(int argc, char** argv) { _getInstance()._parse(argc, argv); }
+        //! Parse redirection to internal member method.
+        static void parse(const std::vector<std::string>& arguments) { _getInstance()._parse(arguments); }
+
+        static std::string getUsageInformation();
 
         template <class T>
         static const CommandLineArgument<T>* getCommandLineArgument(const std::string& name);
-        template <class T>
-        static BaseCommandLineArgument& addCommandLineArgument(const std::string& name,
-            const T& defaultValue);
+        //! Writes the argument value in the given parameter.
+        template <class T>
+        static void getCommandLineValue(const std::string& name, T* value)
+        { *value = getCommandLineArgument<T>(name)->getValue(); }
+        template <class T>
+        static BaseCommandLineArgument& addCommandLineArgument(const std::string& name, T defaultValue);
 
     private:
+        //! Constructor initialises bFirstTimeParse_ with true.
         CommandLine() : bFirstTimeParse_(true) { }
+        //! Undefined copy constructor
         CommandLine(const CommandLine& instance);
         ~CommandLine();
@@ -128 +233 @@
         static CommandLine& _getInstance();
 
-        void _parse(int argc, char** argv);
+        void _parse(const std::vector<std::string>& arguments);
         void checkFullArgument(const std::string& name, const std::string& value);
         void checkShortcut(const std::string& shortcut, const std::string& value);
 
+        template <class T>
+        BaseCommandLineArgument* createArg(const std::string& name, T defaultValue, Int2Type<0> isString);
+        template <class T>
+        BaseCommandLineArgument* createArg(const std::string& name, T defaultValue, Int2Type<1> isString);
+
+        /**
+            Tells whether we parse the first expression. The CommmandLineArguments are added before main().
+            So when we call parse() the first time, we need to create a map with all shortcuts since these
+            get added after addCommandLineArgument().
+        */
         bool bFirstTimeParse_;
 
+        //! Holds all pointers to the arguments and serves as a search map by name.
         std::map<std::string, BaseCommandLineArgument*> cmdLineArgs_;
+        //! Search map by chortcut for the arguments.
         std::map<std::string, BaseCommandLineArgument*> cmdLineArgsShortcut_;
     };
 
 
+    /**
+    @brief
+        Retrieves a CommandLineArgument.
+        The method throws an exception if 'name' was not found or the value could not be converted.
+    @note
+        You shold of course not call this method before the command line has been parsed.
+    */
     template <class T>
     const CommandLineArgument<T>* CommandLine::getCommandLineArgument(const std::string& name)
@@ -162 +286 @@
     }
 
-    template <class T>
-    BaseCommandLineArgument& CommandLine::addCommandLineArgument(const std::string& name,
-                                             const T& defaultValue)
+    /**
+    @brief
+        Adds a new CommandLineArgument to the internal map.
+        Note that only such arguments are actually valid.
+    @param name
+        Name of the argument. Shortcut can be added later.
+    @param defaultValue
+        Default value that is used when argument was not given.
+    @note
+        In order to store char* strings as std::string too, there's
+        little bit of template programming involved:
+        StaticConversions::exists determines whether T converts to std::string.
+        Int2Type<int> is then used to call the right function. One returns
+        a CommandLineArgument<T> and the other CommandLineArgument<std::string>.
+    */
+    template <class T>
+    BaseCommandLineArgument& CommandLine::addCommandLineArgument(const std::string& name, T defaultValue)
     {
         std::map<std::string, BaseCommandLineArgument*>::const_iterator it = _getInstance().cmdLineArgs_.find(name);
@@ -170 +308 @@
             "Cannot add a command line argument with name '" + name + "' twice.");
 
-        return *(_getInstance().cmdLineArgs_[name] = new CommandLineArgument<T>(name, defaultValue));
+        return *(_getInstance().cmdLineArgs_[name] = 
+            _getInstance().createArg(name, defaultValue, Int2Type<StaticConversion<T, std::string>::exists>()));
+    }
+
+    /**
+        Returns a new CommandLineArgument<T>.
+    */
+    template <class T>
+    BaseCommandLineArgument* CommandLine::createArg(const std::string& name, T defaultValue, Int2Type<0> isPrime)
+    {
+        return new CommandLineArgument<T>(name, defaultValue);
+    }
+
+    /**
+        Returns a new CommandLineArgument<std::string>.
+    */
+    template <class T>
+    BaseCommandLineArgument* CommandLine::createArg(const std::string& name, T defaultValue, Int2Type<1> isPrime)
+    {
+        return new CommandLineArgument<std::string>(name, defaultValue);
     }
 }