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/Executor.cc

    r7284 r7352  
    2727 *   Inspiration: Executor by Benjamin Grauer
    2828 */
     29
     30/**
     31    @file
     32    @brief Implementation of orxonox::Executor
     33*/
    2934
    3035#include "Executor.h"
     
    4045namespace orxonox
    4146{
     47    /**
     48        @brief Constructor: Creates an executor.
     49        @param functor The wrapped functor
     50        @param name The name of the executor (optional, used mostly for debug output)
     51    */
    4252    Executor::Executor(const FunctorPtr& functor, const std::string& name)
    4353    {
     
    4656    }
    4757
     58    /**
     59        @brief Copy-constructor: Creates a new executor with the same values and a clone of the wrapped Functor.
     60    */
    4861    Executor::Executor(const Executor& other) : name_(other.name_)
    4962    {
     
    5366    }
    5467
     68    /**
     69        @brief Destructor
     70    */
    5571    Executor::~Executor()
    5672    {
    5773    }
    5874
     75    /**
     76        @brief Calls the wrapped function with arguments that are passed in a string.
     77        @param arguments The arguments that should be passed to the function, separated by @a delimiter
     78        @param error A pointer to a variable (or NULL) that is used to store the error code (see @ref CommandExecutorErrorCodes "CommandExecutor error codes")
     79        @param delimiter The delimiter that is used to separate the arguments in the string @a arguments
     80        @param bPrintError If true, errors are printed to the console if the function couldn't be executed with the given arguments
     81        @return Returns the return value of the function (or MT_Type::Null if there is no return value)
     82    */
    5983    MultiType Executor::parse(const std::string& arguments, int* error, const std::string& delimiter, bool bPrintError) const
    6084    {
     
    6286    }
    6387
     88    /**
     89        @brief Calls the wrapped function with arguments that are passed as tokens in a SubString
     90        @param arguments The arguments that should be passed to the function
     91        @param error A pointer to a variable (or NULL) that is used to store the error code (see @ref CommandExecutorErrorCodes "CommandExecutor error codes")
     92        @param delimiter The delimiter that was used to separate the arguments in the SubString @a arguments (used to join the surplus arguments)
     93        @param bPrintError If true, errors are printed to the console if the function couldn't be executed with the given arguments
     94        @return Returns the return value of the function (or MT_Type::Null if there is no return value)
     95    */
    6496    MultiType Executor::parse(const SubString& arguments, int* error, const std::string& delimiter, bool bPrintError) const
    6597    {
    66         MultiType param[MAX_FUNCTOR_ARGUMENTS];
    67         unsigned int paramCount = this->evaluateParams(arguments, param, error, delimiter);
    68 
     98        // evaluate the arguments
     99        MultiType arg[MAX_FUNCTOR_ARGUMENTS];
     100        unsigned int argCount = this->evaluateArguments(arguments, arg, error, delimiter);
     101
     102        // check if an error occurred
    69103        if (error && *error)
    70104        {
    71105            if (bPrintError)
    72                 COUT(2) << "Warning: Can't call executor " << this->name_ << " through parser: Not enough parameters or default values given (input: " << arguments.join() << ")." << std::endl;
     106                COUT(2) << "Warning: Can't call executor " << this->name_ << " through parser: Not enough arguments or default values given (input: " << arguments.join() << ")." << std::endl;
    73107            return MT_Type::Null;
    74108        }
    75109
    76         COUT(5) << "Executor::parse: \"" << arguments.join(delimiter) << "\" -> " << paramCount << " params: " << param[0] << " / " << param[1] << " / " << param[2] << " / " << param[3] << " / " << param[4] << std::endl;
    77 
    78         switch (paramCount)
     110        COUT(5) << "Executor::parse: \"" << arguments.join(delimiter) << "\" -> " << argCount << " arguments: " << arg[0] << " / " << arg[1] << " / " << arg[2] << " / " << arg[3] << " / " << arg[4] << std::endl;
     111
     112        // execute the function with the evaluated arguments (the default values of the executor are also included in these arguments)
     113        switch (argCount)
    79114        {
    80115            case 0:  return (*this->functor_)();
    81             case 1:  return (*this->functor_)(param[0]);
    82             case 2:  return (*this->functor_)(param[0], param[1]);
    83             case 3:  return (*this->functor_)(param[0], param[1], param[2]);
    84             case 4:  return (*this->functor_)(param[0], param[1], param[2], param[3]);
     116            case 1:  return (*this->functor_)(arg[0]);
     117            case 2:  return (*this->functor_)(arg[0], arg[1]);
     118            case 3:  return (*this->functor_)(arg[0], arg[1], arg[2]);
     119            case 4:  return (*this->functor_)(arg[0], arg[1], arg[2], arg[3]);
    85120            case 5:
    86             default: return (*this->functor_)(param[0], param[1], param[2], param[3], param[4]);
     121            default: return (*this->functor_)(arg[0], arg[1], arg[2], arg[3], arg[4]);
    87122        }
    88123    }
    89124
    90     int Executor::evaluateParams(const SubString& arguments, MultiType param[MAX_FUNCTOR_ARGUMENTS], int* error, const std::string& delimiter) const
     125    /**
     126        @brief Converts the arguments in a SubString to the right type, so they can be used to execute the function without further conversions.
     127        @param arguments The arguments that should be converted
     128        @param arg An array of MultiType where the converted arguments will be stored
     129        @param error A pointer to a variable (or NULL) that is used to store the error code (see @ref CommandExecutorErrorCodes "CommandExecutor error codes")
     130        @param delimiter The delimiter that was used to separate the arguments in the SubString @a arguments (used to join the surplus arguments)
     131        @return Returns the number of evaluated arguments
     132    */
     133    int Executor::evaluateArguments(const SubString& arguments, MultiType arg[MAX_FUNCTOR_ARGUMENTS], int* error, const std::string& delimiter) const
    91134    {
    92135        unsigned int paramCount = this->functor_->getParamCount();
     
    106149        // assign all given arguments to the multitypes
    107150        for (unsigned int i = 0; i < std::min(std::min(argumentCount, paramCount), MAX_FUNCTOR_ARGUMENTS); i++)
    108             param[i] = arguments[i];
     151            arg[i] = arguments[i];
    109152
    110153        // fill the remaining multitypes with default values
    111154        for (unsigned int i = argumentCount; i < std::min(paramCount, MAX_FUNCTOR_ARGUMENTS); i++)
    112             param[i] = this->defaultValue_[i];
     155            arg[i] = this->defaultValue_[i];
    113156
    114157        // assign the remaining arguments all to the last parameter if it is a string
    115158        if ((paramCount <= MAX_FUNCTOR_ARGUMENTS) &&(argumentCount > paramCount) && (paramCount == 1 || this->functor_->getTypenameParam(paramCount - 1) == "string"))
    116             param[paramCount - 1] = arguments.subSet(paramCount - 1).join(delimiter);
    117 
    118         // evaluate the param types through the functor
     159            arg[paramCount - 1] = arguments.subSet(paramCount - 1).join(delimiter);
     160
     161        // evaluate the parameter types through the functor
    119162        for (unsigned int i = 0; i < std::min(paramCount, MAX_FUNCTOR_ARGUMENTS); i++)
    120             this->functor_->evaluateParam(i, param[i]);
     163            this->functor_->evaluateArgument(i, arg[i]);
    121164
    122165        if (error)
     
    125168    }
    126169
    127     void Executor::setDefaultValues(const MultiType& param1)
    128     {
    129         this->defaultValue_[0] = param1;
    130     }
    131 
    132     void Executor::setDefaultValues(const MultiType& param1, const MultiType& param2)
    133     {
    134         this->defaultValue_[0] = param1;
    135         this->defaultValue_[1] = param2;
    136     }
    137 
    138     void Executor::setDefaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3)
    139     {
    140         this->defaultValue_[0] = param1;
    141         this->defaultValue_[1] = param2;
    142         this->defaultValue_[2] = param3;
    143     }
    144 
    145     void Executor::setDefaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4)
    146     {
    147         this->defaultValue_[0] = param1;
    148         this->defaultValue_[1] = param2;
    149         this->defaultValue_[2] = param3;
    150         this->defaultValue_[3] = param4;
    151     }
    152 
    153     void Executor::setDefaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5)
    154     {
    155         this->defaultValue_[0] = param1;
    156         this->defaultValue_[1] = param2;
    157         this->defaultValue_[2] = param3;
    158         this->defaultValue_[3] = param4;
    159         this->defaultValue_[4] = param5;
    160     }
    161 
    162     void Executor::setDefaultValue(unsigned int index, const MultiType& param)
     170    /// Defines the default value for the first parameter.
     171    void Executor::setDefaultValues(const MultiType& arg1)
     172    {
     173        this->defaultValue_[0] = arg1;
     174    }
     175
     176    /// Defines the default value for the first two parameters.
     177    void Executor::setDefaultValues(const MultiType& arg1, const MultiType& arg2)
     178    {
     179        this->defaultValue_[0] = arg1;
     180        this->defaultValue_[1] = arg2;
     181    }
     182
     183    /// Defines the default value for the first three parameters.
     184    void Executor::setDefaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3)
     185    {
     186        this->defaultValue_[0] = arg1;
     187        this->defaultValue_[1] = arg2;
     188        this->defaultValue_[2] = arg3;
     189    }
     190
     191    /// Defines the default value for the first four parameters.
     192    void Executor::setDefaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4)
     193    {
     194        this->defaultValue_[0] = arg1;
     195        this->defaultValue_[1] = arg2;
     196        this->defaultValue_[2] = arg3;
     197        this->defaultValue_[3] = arg4;
     198    }
     199
     200    /// Defines the default value for the first five parameters.
     201    void Executor::setDefaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4, const MultiType& arg5)
     202    {
     203        this->defaultValue_[0] = arg1;
     204        this->defaultValue_[1] = arg2;
     205        this->defaultValue_[2] = arg3;
     206        this->defaultValue_[3] = arg4;
     207        this->defaultValue_[4] = arg5;
     208    }
     209
     210    /// Defines the default value for a parameter with given index (the first parameter has index 0).
     211    void Executor::setDefaultValue(unsigned int index, const MultiType& arg)
    163212    {
    164213        if (index < MAX_FUNCTOR_ARGUMENTS)
    165             this->defaultValue_[index] = param;
    166     }
    167 
     214            this->defaultValue_[index] = arg;
     215    }
     216
     217    /// Returns true if the executor has a default value for each parameter of the wrapped function, so it can be called without passing additional arguments.
    168218    bool Executor::allDefaultValuesSet() const
    169219    {
Note: See TracChangeset for help on using the changeset viewer.