Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Oct 4, 2015, 9:12:21 PM (9 years ago)
Author:
landauf
Message:

merged branch core7 back to trunk

Location:
code/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • code/trunk

  • code/trunk/src/libraries/core/command/ConsoleCommand.h

    r9983 r10624  
    2828
    2929/**
    30     @defgroup ConsoleCommand Console commands
    31     @ingroup Command
    32 */
    33 
    34 /**
    3530    @file
    3631    @ingroup Command ConsoleCommand
    37     @brief Declaration of the orxonox::ConsoleCommand class and the SetConsoleCommand() macro.
    38 
    39     @anchor ConsoleCommandExample
    40 
    41     Console commands can be used to write scripts, use key-bindings or simply to be
    42     entered into the shell by the user. Instances of orxonox::ConsoleCommand define
    43     the function of a command, and also more information like, for example, if it is
    44     active, default values, and possible arguments.
    45 
    46     Commands need to be registered to the system statically on startup by using the
    47     SetConsoleCommand() or DeclareConsoleCommand() macros outside of a function.
    48     This ensures that commands are known to the system at any time, so they can be
    49     evaluated (see orxonox::CommandExecutor::evaluate()), for example for key-bindings.
    50 
    51     Example:
    52     @code
    53     void myCoutFunction(const std::string& text)        // Define a static function
    54     {
    55         orxout() << "Text: " << text << endl;           // Print the text to the console
    56     }
    57 
    58     SetConsoleCommand("cout", &myCoutFunction);         // Register the function as command with name "cout"
    59     @endcode
    60 
    61     Now you can open the shell and execute the command:
    62     @code
    63     $ cout Hello World
    64     @endcode
    65 
    66     Internally this command is now passed to orxonox::CommandExecutor::execute():
    67     @code
    68     CommandExecutor::execute("cout HelloWorld");
    69     @endcode
    70 
    71     CommandExecutor searches for a command with name "cout" and passes the arguments
    72     "Hello World" to it. Because we registered myCoutFunction() with this command,
    73     as a result the following text will be printed to the console:
    74     @code
    75     Text: Hello World
    76     @endcode
    77 
    78     You can add more attributes to the ConsoleCommand, by using the command-chain feature
    79     of SetConsoleCommand(). For example like this:
    80     @code
    81     SetConsoleCommand("cout", &myCoutFunction)
    82         .addGroup("output", "text")
    83         .accessLevel(AccessLevel::Offline)
    84         .defaultValues("no text");
    85     @endcode
    86 
    87     Open the shell again and try it:
    88     @code
    89     $ cout Hello World
    90     Text: Hello World
    91     $ output text Hello World
    92     Text: Hello World
    93     $ cout
    94     Text: no text
    95     @endcode
    96 
    97     If you execute it online (note: the access level is "Offline"), you will see the
    98     following (or something similar):
    99     @code
    100     $ cout Hello World
    101     Error: Can't execute command "cout", access denied.
    102     @endcode
    103 
    104     If a command is executed, the arguments are passed to an underlying function,
    105     whitch is wrapped by an orxonox::Functor which again is wrapped by an orxonox::Executor.
    106     The Functor contains the function-pointer, as well as the object-pointer in
    107     case of a non-static member-function. The executor stores possible default-values
    108     for each argument of the function.
    109 
    110     The function of a command can be changed at any time. It's possible to just exchange
    111     the function-pointer of the underlying Functor if the headers of the functions are
    112     exactly the same. But you can also exchange the Functor itself or even completely
    113     replace the Executor. Also the other attributes of a ConsoleCommand can be modified
    114     during the game, for example it can be activated or deactivated.
    115 
    116     To do so, the function ModifyConsoleCommand() has to be used. It returns an instance
    117     of orxonox::ConsoleCommand::ConsoleCommandManipulator which has an interface similar to
    118     orxonox::ConsoleCommand, but with slight differences. You can use it the same way like
    119     SetConsoleCommand(), meaning you can use command-chains to change different attributes at
    120     the same time. ModifyConsoleCommand() must not be executed statically, but rather in a
    121     function at some point of the execution of the program.
    122 
    123     Example:
    124     @code
    125     void myOtherCoutFunction(const std::string& text)                       // Define a new static function
    126     {
    127         orxout() << "Uppercase: " << getUppercase(text) << endl;            // Print the text in uppercase to the console
    128     }
    129 
    130     {
    131         // ...                                                              // somewhere in the code
    132 
    133         ModifyConsoleCommand("cout").setFunction(&myOtherCoutFunction);     // Modify the underlying function of the command
    134 
    135         // ...
    136     }
    137     @endcode
    138 
    139     If you now enter the command into the shell, you'll see a different behavior:
    140     @code
    141     $ cout Hello World
    142     Uppercase: HELLO WORLD
    143     $ cout
    144     Uppercase: NO TEXT
    145     @endcode
    146 
    147     A few important notes about changing functions:
    148 
    149     Instead of changing the function with setFunction(), you can also create a command-stack
    150     by using pushFunction() and popFunction(). It's important to note a few things about that,
    151     because the underlying structure of Executor and Functor has a few pitfalls:
    152      - If you push a new function-pointer, the same executor as before will be used (and, if
    153        the headers match, even the same functor can be used, which is very fast)
    154      - If you push a new Functor, the same executor as before will be used
    155      - If you push a new Executor, everything is changed
    156 
    157     Note that the executor contains the @b default @b values, so if you just exchange the
    158     Functor, the default values remain the same. However if you decide to change the default
    159     values at any point of the stack, <b>this will also change the default values on all
    160     other stack-levels</b> that share the same executor. If you don't like this behavior,
    161     you have to explicitly push a new executor before changing the default values, either by
    162     calling pushFunction(executor) or by calling pushFunction(void) which pushes a copy of
    163     the current executor to the stack.
    164 
    165     Another important point are object pointers in case of non-static member-functions.
    166     Whenever you set or push a new function, <b>you must add the object pointer again</b>
    167     because objects are stored in the Functor which is usually exchanged if you change
    168     the function.
    169 
    170     You can also use a stack for objects, but note that this <b>object-stack is different for each
    171     function</b> - so if you set a new function, the object-stack will be cleared. If you push
    172     a new function, the old object-stack is stored in the stack, so it can be restored if
    173     you pop the function.
    174 
    175     %DeclareConsoleCommand():
    176 
    177     Appart from SetConsoleCommand() you can also call DeclareConsoleCommand(). In contrast
    178     to SetConsoleCommand(), this doesn't assign a function to the command. Indeed you have
    179     to pass a function-pointer to DeclareConsoleCommand(), but it is only used to determine
    180     the header of the future command-function. This allows to declare a command statically,
    181     thus it's possible to evaluate key-bindings of this command, but the actual function
    182     can be assigned at a later point.
    183 
    184     Example:
    185     @code
    186     DeclareConsoleCommand("cout", &prototype::void__string);
    187     @endcode
    188 
    189     If you try to execute the command now, you see the following (or something similar):
    190     @code
    191     $ cout Hello World
    192     Error: Can't execute command "cout", command is not active.
    193     @endcode
    194 
    195     You first have to assign a function to use the command:
    196     @code
    197     {
    198         // ...
    199 
    200         ModifyConsoleCommand("cout").setFunction(&myCoutFunction);
    201 
    202         // ...
    203     }
    204     @endcode
    205 
    206     Now you can use it:
    207     @code
    208     $ cout Hello World
    209     Text: Hello World
    210     @endcode
    211 
    212     Note that the initial function prototype::void__string is defined in the namespace
    213     orxonox::prototype. If there's no function with the desired header, you can extend
    214     the collection of functions or simply use another function that has the same header.
     32    @brief Declaration of the orxonox::ConsoleCommand class.
    21533*/
    21634
    … …  
    22341#include <vector>
    22442
    225 #include "util/VA_NARGS.h"
    22643#include "ArgumentCompletionFunctions.h"
    22744#include "Executor.h"
    228 
    229 
    230 /**
    231     @brief Defines a console command. The macro is overloaded for 2-4 parameters.
    232 
    233     This is an overloaded macro. Depending on the number of arguments a different
    234     overloaded implementation of the macro will be chosen.
    235 
    236     Console commands created with SetConsoleCommand() become active immediately and
    237     the given function-pointer (and optionally the object) will be used to execute
    238     the command.
    239 */
    240 #define SetConsoleCommand(...) \
    241     BOOST_PP_EXPAND(BOOST_PP_CAT(SetConsoleCommand, ORXONOX_VA_NARGS(__VA_ARGS__))(__VA_ARGS__))
    242 /**
    243     @brief This macro is executed if you call SetConsoleCommand() with 2 arguments.
    244     @param name The name (string) of the console command
    245     @param functionpointer The function-pointer of the corresponding command-function
    246 */
    247 #define SetConsoleCommand2(name, functionpointer) \
    248     SetConsoleCommandGeneric("", name, orxonox::createFunctor(functionpointer))
    249 /**
    250     @brief This macro is executed if you call SetConsoleCommand() with 3 arguments.
    251     @param group The group (string) of the console command
    252     @param name The name (string) of the console command
    253     @param functionpointer The function-pointer of the corresponding command-function
    254 */
    255 #define SetConsoleCommand3(group, name, functionpointer) \
    256     SetConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer))
    257 /**
    258     @brief This macro is executed if you call SetConsoleCommand() with 4 arguments.
    259     @param group The group (string) of the console command
    260     @param name The name (string) of the console command
    261     @param functionpointer The function-pointer of the corresponding command-function
    262     @param object The object that will be assigned to the command. Used for member-functions.
    263 */
    264 #define SetConsoleCommand4(group, name, functionpointer, object) \
    265     SetConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer, object))
    266 
    267 /// Internal macro
    268 #define SetConsoleCommandGeneric(group, name, functor) \
    269     static orxonox::ConsoleCommand& BOOST_PP_CAT(__consolecommand_, __UNIQUE_NUMBER__) = (*orxonox::createConsoleCommand(group, name, orxonox::createExecutor(functor)))
    270 
    271 
    272 /**
    273     @brief Declares a console command. The macro is overloaded for 2-3 parameters.
    274 
    275     This is an overloaded macro. Depending on the number of arguments a different
    276     overloaded implementation of the macro will be chosen.
    277 
    278     Console commands created with DeclareConsoleCommand() don't use the the given
    279     function-pointer to execute the command, it is only used to define the header
    280     of the future command-function. The command is inactive until you manually
    281     set a function with orxonox::ModifyConsoleCommand(). You can use a different
    282     function-pointer than in the final command, as long as it has the same header.
    283 */
    284 #define DeclareConsoleCommand(...) \
    285     BOOST_PP_EXPAND(BOOST_PP_CAT(DeclareConsoleCommand, ORXONOX_VA_NARGS(__VA_ARGS__))(__VA_ARGS__))
    286 /**
    287     @brief This macro is executed if you call DeclareConsoleCommand() with 2 arguments.
    288     @param name The name (string) of the console command
    289     @param functionpointer The function-pointer of an arbitrary function that has the same header as the final function
    290 */
    291 #define DeclareConsoleCommand2(name, functionpointer) \
    292     DeclareConsoleCommandGeneric("", name, orxonox::createFunctor(functionpointer))
    293 /**
    294     @brief This macro is executed if you call DeclareConsoleCommand() with 3 arguments.
    295     @param group The group (string) of the console command
    296     @param name The name (string) of the console command
    297     @param functionpointer The function-pointer of an arbitrary function that has the same header as the final function
    298 */
    299 #define DeclareConsoleCommand3(group, name, functionpointer) \
    300     DeclareConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer))
    301 
    302 /// Internal macro
    303 #define DeclareConsoleCommandGeneric(group, name, functor) \
    304     static orxonox::ConsoleCommand& BOOST_PP_CAT(__consolecommand_, __UNIQUE_NUMBER__) = (*orxonox::createConsoleCommand(group, name, orxonox::createExecutor(functor), false))
    305 
    30645
    30746namespace orxonox
    … …  
    365104
    366105        public:
     106            /**
     107             * @brief Defines the name of a command, consisting of an optional group ("" means no group) and the name itself.
     108             */
     109            struct CommandName
     110            {
     111                CommandName(const std::string& group, const std::string& name) : group_(group), name_(name) {}
     112                std::string group_;
     113                std::string name_;
     114            };
     115
    367116            /**
    368117                @brief Helper class that is used to manipulate console commands.
    … …  
    522271
    523272        public:
     273            ConsoleCommand(const std::string& name, const ExecutorPtr& executor, bool bInitialized = true);
    524274            ConsoleCommand(const std::string& group, const std::string& name, const ExecutorPtr& executor, bool bInitialized = true);
    525275            ~ConsoleCommand();
    … …  
    620370                { return this; }
    621371
     372            inline const std::vector<CommandName>& getNames()
     373                { return this->names_; }
     374
    622375        private:
     376            void init(const std::string& group, const std::string& name, const ExecutorPtr& executor, bool bInitialized);
     377
    623378            bool headersMatch(const FunctorPtr& functor);
    624379            bool headersMatch(const ExecutorPtr& executor);
    … …  
    641396            AccessLevel::Enum accessLevel_;                                 ///< The access level (the state of the game in which you can access the command)
    642397            std::string baseName_;                                          ///< The name that was first assigned to the command
     398            std::vector<CommandName> names_;                                ///< All names and aliases of this command
    643399            FunctorPtr baseFunctor_;                                        ///< The functor that defines the header of the command-function
    644400
    … …  
    655411            LanguageEntryLabel descriptionReturnvalue_;                     ///< A description of the return-value
    656412            LanguageEntryLabel descriptionParam_[MAX_FUNCTOR_ARGUMENTS];    ///< A description for each argument
    657 
    658         public:
    659             /// Returns the map with all groups and commands.
    660             static inline const std::map<std::string, std::map<std::string, ConsoleCommand*> >& getCommands()
    661                 { return ConsoleCommand::getCommandMap(); }
    662             /// Returns the map with all groups and commands in lowercase.
    663             static inline const std::map<std::string, std::map<std::string, ConsoleCommand*> >& getCommandsLC()
    664                 { return ConsoleCommand::getCommandMapLC(); }
    665 
    666             /// Returns a command (shortcut) with given name. @param name The name of the command shortcut @param bPrintError If true, an error is printed if the command doesn't exist
    667             static inline ConsoleCommand* getCommand(const std::string& name, bool bPrintError = false)
    668                 { return ConsoleCommand::getCommand("", name, bPrintError); }
    669             /// Returns a command (shortcut) with given name in lowercase. @param name The lowercase name of the command shortcut @param bPrintError If true, an error is printed if the command doesn't exist
    670             static inline ConsoleCommand* getCommandLC(const std::string& name, bool bPrintError = false)
    671                 { return ConsoleCommand::getCommandLC("", name, bPrintError); }
    672 
    673             static ConsoleCommand* getCommand(const std::string& group, const std::string& name, bool bPrintError = false);
    674             static ConsoleCommand* getCommandLC(const std::string& group, const std::string& name, bool bPrintError = false);
    675 
    676             static void destroyAll();
    677 
    678         private:
    679             static std::map<std::string, std::map<std::string, ConsoleCommand*> >& getCommandMap();
    680             static std::map<std::string, std::map<std::string, ConsoleCommand*> >& getCommandMapLC();
    681 
    682             static void registerCommand(const std::string& group, const std::string& name, ConsoleCommand* command);
    683             static void unregisterCommand(ConsoleCommand* command);
    684413    };
    685 
    686     /**
    687         @brief Creates a new ConsoleCommand.
    688         @param name The name of the command
    689         @param executor The executor of the command
    690         @param bInitialized If true, the command is ready to be executed, otherwise it has to be activated first.
    691     */
    692     inline ConsoleCommand* createConsoleCommand(const std::string& name, const ExecutorPtr& executor, bool bInitialized = true)
    693         { return new ConsoleCommand("", name, executor, bInitialized); }
    694     /**
    695         @brief Creates a new ConsoleCommand.
    696         @param group The group of the command
    697         @param name The name of the command
    698         @param executor The executor of the command
    699         @param bInitialized If true, the command is ready to be executed, otherwise it has to be activated first.
    700     */
    701     inline ConsoleCommand* createConsoleCommand(const std::string& group, const std::string& name, const ExecutorPtr& executor, bool bInitialized = true)
    702         { return new ConsoleCommand(group, name, executor, bInitialized); }
    703 
    704 
    705     /**
    706         @brief Returns a manipulator for a command with the given name.
    707 
    708         @note If the command doesn't exist, the manipulator contains a NULL pointer to the command,
    709         but it can still be used without checks, because all functions of ConsoleCommandManipulator
    710         check internally if the command exists.
    711     */
    712     inline ConsoleCommand::ConsoleCommandManipulator ModifyConsoleCommand(const std::string& name)
    713         { return ConsoleCommand::getCommand(name, true); }
    714     /**
    715         @brief Returns a manipulator for a command with the given group and name.
    716 
    717         @note If the command doesn't exist, the manipulator contains a NULL pointer to the command,
    718         but it can still be used without checks, because all functions of ConsoleCommandManipulator
    719         check internally if the command exists.
    720     */
    721     inline ConsoleCommand::ConsoleCommandManipulator ModifyConsoleCommand(const std::string& group, const std::string& name)
    722         { return ConsoleCommand::getCommand(group, name, true); }
    723414}
    724415
Note: See TracChangeset for help on using the changeset viewer.