Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 4, 2010, 11:33:02 PM (14 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.cc

    r7284 r7352  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of CommandExecutor
     32*/
     33
    2934#include "CommandExecutor.h"
    3035
    … …  
    4954        .argumentCompleter(1, autocompletion::command());
    5055
     56    /**
     57        @brief Returns a reference to the only instance of CommandExecutor.
     58    */
    5159    /* static */ CommandExecutor& CommandExecutor::getInstance()
    5260    {
    … …  
    5563    }
    5664
     65    /**
     66        @brief Executes a command.
     67        @param command A string containing the command
     68        @param useTcl If true, the command is passed to tcl (see TclBind)
     69        @return Returns the error-code (see @ref CommandExecutorErrorCodes "error codes")
     70    */
    5771    /* static */ int CommandExecutor::execute(const std::string& command, bool useTcl)
    5872    {
    … …  
    6276    }
    6377
     78    /**
     79        @brief Executes a command and returns its return-value.
     80        @param command A string containing the command
     81        @param error A pointer to a value (or NULL) where the error-code should be written to (see @ref CommandExecutorErrorCodes "error codes")
     82        @param useTcl If true, the command is passed to tcl (see TclBind)
     83        @return Returns the return-value of the command (if any - MT_Type::Null otherwise)
     84    */
    6485    /* static */ MultiType CommandExecutor::queryMT(const std::string& command, int* error, bool useTcl)
    6586    {
    6687        if (useTcl)
     88        {
     89            // pass the command to tcl
    6790            return TclBind::eval(command, error);
     91        }
    6892        else
    6993        {
    7094            CommandEvaluation evaluation;
     95
     96            // try to get the command evaluation from the cache
    7197            if (!CommandExecutor::getInstance().getCached(command, evaluation))
    7298            {
     99                // it wasn't in the cache - evaluate the command
    73100                evaluation = CommandExecutor::evaluate(command);
    74                 evaluation.evaluateParams();
     101
     102                // evaluate its arguments
     103                evaluation.evaluateArguments();
     104
     105                // write the evaluation to the cache
    75106                CommandExecutor::getInstance().cache(command, evaluation);
    76107            }
    77108
     109            // query the command and return its return-value
    78110            return evaluation.query(error);
    79111        }
    80112    }
    81113
     114    /**
     115        @brief Executes a command and returns its return-value as string.
     116        @param command A string containing the command
     117        @param error A pointer to a value (or NULL) where the error-code should be written to (see @ref CommandExecutorErrorCodes "error codes")
     118        @param useTcl If true, the command is passed to tcl (see TclBind)
     119        @return Returns the return-value of the command converted to a string (or "" if there's no return value)
     120    */
    82121    /* static */ std::string CommandExecutor::query(const std::string& command, int* error, bool useTcl)
    83122    {
    … …  
    85124    }
    86125
     126    /**
     127        @brief Evaluates the given command.
     128        @param command A string containing the command
     129        @return Returns an instance of CommandEvaluation, which contains the evaluated ConsoleCommand, if the command is valid.
     130
     131        Evaluates the given command string and returns an instance of CommandEvaluation.
     132        If the command is valid, this contains the evaluated ConsoleCommand. Otherwise it
     133        can still be used to print hints or complete the command.
     134
     135        @note Tcl commands can not be evaluated. You have to pass them to execute() or to
     136        TclBind directly.
     137    */
    87138    /* static */ CommandEvaluation CommandExecutor::evaluate(const std::string& command)
    88139    {
     140        // initialize the command evaluation
    89141        CommandEvaluation evaluation;
    90142        evaluation.initialize(command);
    91143
     144        // assign the fallback-command to get hints about the possible commands and groups
    92145        evaluation.hintCommand_ = ConsoleCommand::getCommand(__CC_CommandExecutor_name, __CC_autocomplete_name);
    93146
     147        // check if there's at least one argument
    94148        if (evaluation.getNumberOfArguments() >= 1)
    95149        {
     150            // try to get a command from the first token
    96151            evaluation.execCommand_ = ConsoleCommand::getCommandLC(evaluation.getToken(0));
    97152            if (evaluation.execCommand_)
    … …  
    99154            else if (evaluation.getNumberOfArguments() >= 2)
    100155            {
     156                // try to get a command from the first two tokens
    101157                evaluation.execCommand_ = ConsoleCommand::getCommandLC(evaluation.getToken(0), evaluation.getToken(1));
    102158                if (evaluation.execCommand_)
    … …  
    105161        }
    106162
     163        // if a valid command was found and the user is already entering arguments, overwrite hintCommand_ with execCommand_
    107164        if (evaluation.execCommand_ && evaluation.getNumberOfArguments() > evaluation.execArgumentsOffset_)
    108165        {
    … …  
    114171    }
    115172
     173    /**
     174        @brief Gets an evaluated command from the cache.
     175        @param command The command that should be looked up in the cache
     176        @param evaluation Reference to a CommandEvaluation that will be used to return the cached evaluation.
     177        @return Returns true if the command was found in the cache
     178    */
    116179    bool CommandExecutor::getCached(const std::string& command, CommandEvaluation& evaluation)
    117180    {
    … …  
    119182            return false;
    120183
     184        // check if the command is in the cache
    121185        std::map<std::string, CacheEntry>::iterator it = this->cache_.find(command);
    122186        if (it != this->cache_.end())
    … …  
    134198    }
    135199
     200    /**
     201        @brief Writes a command evaluation for a given command to the cache.
     202    */
    136203    void CommandExecutor::cache(const std::string& command, const CommandEvaluation& evaluation)
    137204    {
    … …  
    156223    }
    157224
     225    /**
     226        @brief This function is used as console command which executes commands that are usually hidden.
     227
     228        The argument completion function of this console commands is used to find
     229        and enter hidden commands and their arguments.
     230    */
    158231    /* static */ MultiType CommandExecutor::unhide(const std::string& command)
    159232    {
    … …  
    161234    }
    162235
     236    /**
     237        @brief This function is used as console command which saves a command and optionally also it's arguments as a new console command with a new name.
     238        @param alias The name of the new command alias
     239        @param command The existing command and (optionally) its arguments
     240    */
    163241    /* static */ void CommandExecutor::alias(const std::string& alias, const std::string& command)
    164242    {
     243        // first check if the given command is valid, else print an error
    165244        CommandEvaluation evaluation = CommandExecutor::evaluate(command);
    166245        if (evaluation.isValid())
    167246        {
     247            // it is valid - copy the executor of this command
    168248            ExecutorPtr executor = new Executor(*evaluation.getConsoleCommand()->getExecutor().get());
    169249
    170             if (!evaluation.evaluateParams())
     250            // evaluate the arguments and if this returns no error, store them as default values
     251            if (!evaluation.evaluateArguments())
    171252            {
    172253                for (size_t i = 0; i < MAX_FUNCTOR_ARGUMENTS; ++i)
    173                     executor->setDefaultValue(i, evaluation.getEvaluatedParameter(i));
    174             }
    175 
     254                    executor->setDefaultValue(i, evaluation.getEvaluatedArgument(i));
     255            }
     256
     257            // split the alias in tokens
    176258            SubString tokens(alias, " ");
    177259
     260            // check if the alias already exists - print an error and return if it does
    178261            if ((tokens.size() == 1 && ConsoleCommand::getCommand(tokens[0])) || (tokens.size() == 2 && ConsoleCommand::getCommand(tokens[0], tokens[1])))
    179262            {
    … …  
    182265            }
    183266
     267            // create a new console command with the given alias as its name
    184268            if (tokens.size() == 1)
    185269                createConsoleCommand(tokens[0], executor);
Note: See TracChangeset for help on using the changeset viewer.