Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 4, 2010, 11:33:02 PM (15 years ago)
Author:
landauf
Message:

added documentation

also some small naming and readability changes in the code.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • code/branches/doc/src/libraries/core/command/CommandExecutor.h

    r7284 r7352  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Command CommandExecEval
     32    @brief Declaration of the orxonox::CommandExecutor class which is used to execute and evaluate @ref orxonox::ConsoleCommand "console commands".
     33
     34    @anchor CommandExecutorExample
     35
     36    orxonox::CommandExecutor can be used to execute console commands (see orxonox::ConsoleCommand).
     37    Commands are strings that can be entered by the user in the shell or they can be part of a
     38    script.
     39
     40    A command can be passed to orxonox::CommandExecutor::execute() which will execute them - eiter
     41    directly, or - if requested - passes it to Tcl. See orxonox::TclBind for more information.
     42    Appart from execute() the command can also be passed to orxonox::CommandExecutor::query() which
     43    behaves the same except for that it returns the return value of the command.
     44
     45    If you don't want to execute the command, but rather gather more information about it, pass it
     46    to orxonox::CommandExecutor::evaluate(). This function returns an instance of
     47    orxonox::CommandEvaluation. This class provides more information about the command, for example
     48    the evaluated instance of orxonox::ConsoleCommand. Its also possible to gather hints about the
     49    command or to complete the command-string by using argument completion functions. More than that
     50    the command evaluation can also evaluate the arguments, which allows faster execution of the
     51    command.
     52
     53    Example:
     54    @code
     55    CommandExecutor::execute("log test");               // writes "test" to the console
     56    CommandExecutor::execute("log [expr 1+1]");         // writes "2" to the console - expr is a Tcl command
     57
     58    CommandExecutor::query("expr 1+1");                 // returns "2"
     59    CommandExecutor::queryMT("expr 1+1");               // returns 2
     60    @endcode
     61
     62    And another example about how to use evaluate():
     63    @code
     64    CommandEvaluation evaluation;
     65    evaluation = CommandExecutor::evaluate("log test"); // returns an evaluation of "log test"
     66
     67    evaluation.execute();                               // writes "test" to the console
     68    evaluation.hint();                                  // returns "log: {string}"
     69    @endcode
     70
     71    @anchor CommandExecutorErrorCodes
     72
     73    @b Error @b codes:
     74
     75    orxonox::CommandExecutor defines a number of error codes that are returned
     76    by different functions that operate with commands:
     77
     78     - CommandExecutor::Success: No error
     79     - CommandExecutor::Error: The command doesn't exist
     80     - CommandExecutor::Incomplete: The command needs more arguments
     81     - CommandExecutor::Deactivated: The command is not active
     82     - CommandExecutor::Denied: The command needs a different @ref orxonox::AccessLevel "access level"
     83*/
     84
    2985#ifndef _CommandExecutor_H__
    3086#define _CommandExecutor_H__
    … …  
    4298namespace orxonox
    4399{
     100    /**
     101        @brief This class is used to execute and evaluate command-strings.
     102
     103        CommandExecutor executes command-strings and returns evaluated commands. It's
     104        also possible to execute Tcl commands if the corresponding argument of execute()
     105        is true.
     106
     107        @see See @ref CommandExecutorExample "this description" for more information and some examples.
     108    */
    44109    class _CoreExport CommandExecutor
    45110    {
    … …  
    53118            static CommandEvaluation evaluate(const std::string& command);
    54119
    55             static const int Success = 0;
    56             static const int Error = 1;
    57             static const int Incomplete = 2;
    58             static const int Deactivated = 3;
    59             static const int Denied = 4;
     120            static const int Success = 0;       ///< Error code for "success" (or no error)
     121            static const int Error = 1;         ///< Error code if the command doesn't exist
     122            static const int Incomplete = 2;    ///< Error code if the command needs more arguments
     123            static const int Deactivated = 3;   ///< Error code if the command is not active
     124            static const int Denied = 4;        ///< Error code if the command needs a different access level
    60125
    61126            static MultiType unhide(const std::string& command);
    62127            static void alias(const std::string& alias, const std::string& command);
    63             static void _autocomplete(const std::string& group, const std::string& name) {}
     128            static void _autocomplete(const std::string& group, const std::string& name) {} ///< Pseudo console command used whenever no real command is available. In these cases this command provides auto-completion for console commands and groups.
    64129
    65130        private:
    66             CommandExecutor() {}
    67             CommandExecutor(const CommandExecutor& other);
    68             ~CommandExecutor() {}
     131            CommandExecutor() {}                            ///< Empty constructor
     132            CommandExecutor(const CommandExecutor& other);  ///< Not implemented copy-constructor
     133            ~CommandExecutor() {}                           ///< Empty destructor
    69134
    70135            static CommandExecutor& getInstance();
    … …  
    73138            void cache(const std::string& command, const CommandEvaluation& evaluation);
    74139
     140            /// Helper struct, used to store cached entries
    75141            struct CacheEntry
    76142            {
    77                 CommandEvaluation evaluation_;
    78                 std::list<std::string>::iterator iterator_;
     143                CommandEvaluation evaluation_;                  ///< The command evaluation which is stored in the cache
     144                std::list<std::string>::iterator iterator_;     ///< The iterator of the corresponding element in cachelist_, used for faster access
    79145            };
    80146
    81             std::map<std::string, CacheEntry> cache_;
    82             std::list<std::string> cachelist_;
     147            std::map<std::string, CacheEntry> cache_;   ///< A map that connects command strings and evaluated commands in the cache
     148            std::list<std::string> cachelist_;          ///< A list used to sort the elements in the cache by their age
    83149    }; // tolua_export
    84150} // tolua_export
Note: See TracChangeset for help on using the changeset viewer.