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

    r7284 r7352  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of the ConsoleCommand class.
     32*/
     33
    2934#include "ConsoleCommand.h"
    3035
    … …  
    3641namespace orxonox
    3742{
     43    /**
     44        @brief Constructor: Initializes all values and registers the command.
     45        @param group The group of the command
     46        @param name The name of the command
     47        @param executor The executor of the command
     48        @param bInitialized If true, the executor is used for both, the definition of the function-header AND to executute the command. If false, the command is inactive and needs to be assigned a function before it can be used.
     49    */
    3850    ConsoleCommand::ConsoleCommand(const std::string& group, const std::string& name, const ExecutorPtr& executor, bool bInitialized)
    3951    {
    … …  
    4557        this->baseFunctor_ = executor->getFunctor();
    4658
    47         this->argumentCompleter_[0] = 0;
    48         this->argumentCompleter_[1] = 0;
    49         this->argumentCompleter_[2] = 0;
    50         this->argumentCompleter_[3] = 0;
    51         this->argumentCompleter_[4] = 0;
     59        for (size_t i = 0; i < MAX_FUNCTOR_ARGUMENTS; ++i)
     60            this->argumentCompleter_[i] = 0;
    5261
    5362        this->keybindMode_ = KeybindMode::OnPress;
    … …  
    6069    }
    6170
     71    /**
     72        @brief Destructor: Unregisters the command.
     73    */
    6274    ConsoleCommand::~ConsoleCommand()
    6375    {
    … …  
    6577    }
    6678
     79    /**
     80        @brief Registers the command with the same name, but without group, as shortcut.
     81    */
    6782    ConsoleCommand& ConsoleCommand::addShortcut()
    6883    {
    … …  
    7186    }
    7287
     88    /**
     89        @brief Registers the command with an alias as shortcut.
     90    */
    7391    ConsoleCommand& ConsoleCommand::addShortcut(const std::string&  name)
    7492    {
    … …  
    7795    }
    7896
     97    /**
     98        @brief Registers the command in a different group but with the same name.
     99    */
    79100    ConsoleCommand& ConsoleCommand::addGroup(const std::string& group)
    80101    {
    … …  
    83104    }
    84105
     106    /**
     107        @brief Registers an alias of the command in a different group with a different name.
     108    */
    85109    ConsoleCommand& ConsoleCommand::addGroup(const std::string& group, const std::string&  name)
    86110    {
    … …  
    89113    }
    90114
     115    /**
     116        @brief Returns true if the command can be executed right now.
     117
     118        This returns only true, if the following conditions are met:
     119         - The command is active
     120         - The command has an executor
     121         - The executor has a functor
     122         - The functor is static or has an object
     123    */
    91124    bool ConsoleCommand::isActive() const
    92125    {
    … …  
    94127    }
    95128
     129    /**
     130        @brief Returns true if the current state of the game matches the required access level.
     131    */
    96132    bool ConsoleCommand::hasAccess() const
    97133    {
    … …  
    110146    }
    111147
     148    /**
     149        @brief Returns true if the headers of the given functor match the declaration of this command.
     150    */
    112151    bool ConsoleCommand::headersMatch(const FunctorPtr& functor)
    113152    {
     153        // get the minimum of the number of parameters of both commands
    114154        unsigned int minparams = std::min(this->baseFunctor_->getParamCount(), functor->getParamCount());
    115155
     156        // if the reduced headers don't match -> return false
    116157        if (this->baseFunctor_->getHeaderIdentifier(minparams) != functor->getHeaderIdentifier(minparams))
    117158            return false;
     159        // if the reduced headers match and the new functor has less or equal parameters -> return true
    118160        else if (functor->getParamCount() <= this->baseFunctor_->getParamCount())
    119161            return true;
     162        // the headers match but the new functor has more arguments and there is no executor with default-values -> return false
    120163        else if (!this->executor_)
    121164            return false;
     165        // the headers match but the new functor has more arguments, check if the executor has enough default-values
    122166        else
    123167        {
    … …  
    135179    }
    136180
     181    /**
     182        @brief Returns true if the headers of the given executor match the declaration of this command.
     183    */
    137184    bool ConsoleCommand::headersMatch(const ExecutorPtr& executor)
    138185    {
     186        // get the minimum of the number of parameters of both commands
    139187        unsigned int minparams = std::min(this->baseFunctor_->getParamCount(), executor->getParamCount());
    140188
     189        // if the reduced headers don't match -> return false
    141190        if (this->baseFunctor_->getHeaderIdentifier(minparams) != executor->getFunctor()->getHeaderIdentifier(minparams))
    142191            return false;
     192        // if the reduced headers match and the new functor has less or equal parameters -> return true
    143193        else if (executor->getParamCount() <= this->baseFunctor_->getParamCount())
    144194            return true;
     195        // the headers match but the new functor has more arguments, check if the new executor has enough default-values
    145196        else
    146197        {
    … …  
    158209    }
    159210
     211    /**
     212        @brief Changes the executor.
     213        @param executor The new executor
     214        @param bForce If true, the executor is always assigned, even if the headers don't match
     215        @return Returns true if the assignment was successful
     216    */
    160217    bool ConsoleCommand::setFunction(const ExecutorPtr& executor, bool bForce)
    161218    {
     219        // assign the executor if a) it's a null-pointer, b) its functor is a null-pointer, c) it's forced, d) the headers match
    162220        if (!executor || !executor->getFunctor() || bForce || this->headersMatch(executor))
    163221        {
     222            // assign the executor and clear the object stack (because it's also a new function)
    164223            this->executor_ = executor;
    165224            this->objectStack_.clear();
    … …  
    173232    }
    174233
     234    /**
     235        @brief Changes the functor of the current executor.
     236        @param functor The new functor
     237        @param bForce If true, the functor is always assigned, even if the headers don't match
     238        @return Returns true if the assignment was successful
     239    */
    175240    bool ConsoleCommand::setFunction(const FunctorPtr& functor, bool bForce)
    176241    {
     242        // assign the functor if a) it's a null-pointer, b) it's forced, c) the headers match
    177243        if (!functor || bForce || this->headersMatch(functor))
    178244        {
     245            // assign the functor (create a new executor if necessary) and clear the object stack
    179246            if (this->executor_)
    180247                this->executor_->setFunctor(functor);
    … …  
    192259    }
    193260
     261    /**
     262        @brief Pushes a new executor to the command-stack.
     263        @param executor The new executor
     264        @param bForce If true, the executor is always assigned, even if the headers don't match
     265    */
    194266    void ConsoleCommand::pushFunction(const ExecutorPtr& executor, bool bForce)
    195267    {
     268        // prepare the old function to be put on the stack
    196269        Command command;
    197270        command.executor_ = this->executor_;
    … …  
    200273        command.objectStack_ = this->objectStack_;
    201274
     275        // check if the new executor can be assigned and push the old function to the stack
    202276        if (this->setFunction(executor, bForce))
    203277            this->commandStack_.push(command);
    204278    }
    205279
     280    /**
     281        @brief Pushes a new functor to the command-stack.
     282        @param functor The new functor
     283        @param bForce If true, the functor is always assigned, even if the headers don't match
     284    */
    206285    void ConsoleCommand::pushFunction(const FunctorPtr& functor, bool bForce)
    207286    {
     287        // prepare the old function to be put on the stack
    208288        Command command;
    209289        command.executor_ = this->executor_;
    … …  
    212292        command.objectStack_ = this->objectStack_;
    213293
     294        // check if the new functor can be assigned and push the old function to the stack
    214295        if (this->setFunction(functor, bForce))
    215296            this->commandStack_.push(command);
    216297    }
    217298
     299    /**
     300        @brief Pushes a copy of the current executor and functor on the stack.
     301    */
    218302    void ConsoleCommand::pushFunction()
    219303    {
    … …  
    224308    }
    225309
     310    /**
     311        @brief Removes the current function from the stack and restores the old state.
     312    */
    226313    void ConsoleCommand::popFunction()
    227314    {
    228315        Command command;
     316
     317        // check if there's a function on the stack
    229318        if (!this->commandStack_.empty())
    230319        {
     320            // yes it is - assign it to command and remove it from the stack
    231321            command = this->commandStack_.top();
    232322            this->commandStack_.pop();
    233323        }
    234324
     325        // restore the old executor (and also restore its functor in case this was changed in the meantime)
    235326        this->executor_ = command.executor_;
    236327        if (command.executor_)
    … …  
    239330    }
    240331
     332    /**
     333        @brief Sets the functor to NULL (which also deactivates the command).
     334    */
    241335    void ConsoleCommand::resetFunction()
    242336    {
    … …  
    246340    }
    247341
     342    /**
     343        @brief Returns the current executor which can be used to execute the command.
     344    */
    248345    const ExecutorPtr& ConsoleCommand::getExecutor() const
    249346    {
    … …  
    251348    }
    252349
     350    /**
     351        @brief Changes the current object that is used to execute member-functions.
     352        @return Returns true if the object was successfully changed
     353    */
    253354    bool ConsoleCommand::setObject(void* object)
    254355    {
    255         if (this->executor_)
    256         {
     356        // check if there's an executor
     357        if (this->executor_)
     358        {
     359            // check if there's a functor
    257360            if (this->executor_->getFunctor())
    258361            {
     362                // change the object
    259363                this->executor_->getFunctor()->setRawObjectPointer(object);
    260364                return true;
    … …  
    269373    }
    270374
     375    /**
     376        @brief Push a new object to the object-stack.
     377    */
    271378    void ConsoleCommand::pushObject(void* object)
    272379    {
    … …  
    276383    }
    277384
     385    /**
     386        @brief Removes the current object from the stack an restores the old object.
     387    */
    278388    void ConsoleCommand::popObject()
    279389    {
    … …  
    287397    }
    288398
     399    /**
     400        @brief Returns the current object pointer that is used to execute member-functions.
     401    */
    289402    void* ConsoleCommand::getObject() const
    290403    {
    … …  
    295408    }
    296409
    297     ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& param1)
    298     {
    299         if (this->executor_)
    300             this->executor_->setDefaultValues(param1);
     410    /**
     411        @brief Changes the default values of the current executor.
     412    */
     413    ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& arg1)
     414    {
     415        if (this->executor_)
     416            this->executor_->setDefaultValues(arg1);
    301417        else
    302418            COUT(1) << "Error: Can't set default values in console command \"" << this->baseName_ << "\", no executor set." << std::endl;
    … …  
    305421    }
    306422
    307     ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& param1, const MultiType& param2)
    308     {
    309         if (this->executor_)
    310             this->executor_->setDefaultValues(param1, param2);
     423    /**
     424        @brief Changes the default values of the current executor.
     425    */
     426    ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& arg1, const MultiType& arg2)
     427    {
     428        if (this->executor_)
     429            this->executor_->setDefaultValues(arg1, arg2);
    311430        else
    312431            COUT(1) << "Error: Can't set default values in console command \"" << this->baseName_ << "\", no executor set." << std::endl;
    … …  
    315434    }
    316435
    317     ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3)
    318     {
    319         if (this->executor_)
    320             this->executor_->setDefaultValues(param1, param2, param3);
     436    /**
     437        @brief Changes the default values of the current executor.
     438    */
     439    ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3)
     440    {
     441        if (this->executor_)
     442            this->executor_->setDefaultValues(arg1, arg2, arg3);
    321443        else
    322444            COUT(1) << "Error: Can't set default values in console command \"" << this->baseName_ << "\", no executor set." << std::endl;
    … …  
    325447    }
    326448
    327     ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4)
    328     {
    329         if (this->executor_)
    330             this->executor_->setDefaultValues(param1, param2, param3, param4);
     449    /**
     450        @brief Changes the default values of the current executor.
     451    */
     452    ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4)
     453    {
     454        if (this->executor_)
     455            this->executor_->setDefaultValues(arg1, arg2, arg3, arg4);
    331456        else
    332457            COUT(1) << "Error: Can't set default values in console command \"" << this->baseName_ << "\", no executor set." << std::endl;
    … …  
    335460    }
    336461
    337     ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5)
    338     {
    339         if (this->executor_)
    340             this->executor_->setDefaultValues(param1, param2, param3, param4, param5);
     462    /**
     463        @brief Changes the default values of the current executor.
     464    */
     465    ConsoleCommand& ConsoleCommand::defaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4, const MultiType& arg5)
     466    {
     467        if (this->executor_)
     468            this->executor_->setDefaultValues(arg1, arg2, arg3, arg4, arg5);
    341469        else
    342470            COUT(1) << "Error: Can't set default values in console command \"" << this->baseName_ << "\", no executor set." << std::endl;
    … …  
    345473    }
    346474
    347     ConsoleCommand& ConsoleCommand::defaultValue(unsigned int index, const MultiType& param)
    348     {
    349         if (this->executor_)
    350             this->executor_->setDefaultValue(index, param);
     475    /**
     476        @brief Changes the default value of the argument with given index of the current executor.
     477        @param index The index of the argument (the first argument has index 0)
     478        @param arg The new default value
     479    */
     480    ConsoleCommand& ConsoleCommand::defaultValue(unsigned int index, const MultiType& arg)
     481    {
     482        if (this->executor_)
     483            this->executor_->setDefaultValue(index, arg);
    351484        else
    352485            COUT(1) << "Error: Can't set default values in console command \"" << this->baseName_ << "\", no executor set." << std::endl;
    … …  
    355488    }
    356489
    357     ConsoleCommand& ConsoleCommand::argumentCompleter(unsigned int param, ArgumentCompleter* completer)
    358     {
    359         if (param < 5)
    360             this->argumentCompleter_[param] = completer;
    361         else
    362             COUT(2) << "Warning: Couldn't add autocompletion-function for param " << param << " in console command \"" << this->baseName_ << "\": index out of bound." << std::endl;
    363 
    364         return *this;
    365     }
    366 
    367     ArgumentCompleter* ConsoleCommand::getArgumentCompleter(unsigned int param) const
    368     {
    369         if (param < 5)
    370             return this->argumentCompleter_[param];
     490    /**
     491        @brief Changes the argument completer for the given argument.
     492        @param index The index of the argument (the first argument has index 0)
     493        @param completer The new argument completer
     494    */
     495    ConsoleCommand& ConsoleCommand::argumentCompleter(unsigned int index, ArgumentCompleter* completer)
     496    {
     497        if (index < 5)
     498            this->argumentCompleter_[index] = completer;
     499        else
     500            COUT(2) << "Warning: Couldn't add autocompletion-function for index " << index << " in console command \"" << this->baseName_ << "\": index out of bound." << std::endl;
     501
     502        return *this;
     503    }
     504
     505    /**
     506        @brief Returns the argument completer for the argument with given index.
     507    */
     508    ArgumentCompleter* ConsoleCommand::getArgumentCompleter(unsigned int index) const
     509    {
     510        if (index < 5)
     511            return this->argumentCompleter_[index];
    371512        else
    372513            return 0;
    373514    }
    374515
     516    /**
     517        @brief Sets the description of this command.
     518    */
    375519    ConsoleCommand& ConsoleCommand::description(const std::string& description)
    376520    {
    … …  
    380524    }
    381525
     526    /**
     527        @brief Returns the description of this command.
     528    */
    382529    const std::string& ConsoleCommand::getDescription() const
    383530    {
    … …  
    385532    }
    386533
    387     ConsoleCommand& ConsoleCommand::descriptionParam(unsigned int param, const std::string& description)
    388     {
    389         if (param < MAX_FUNCTOR_ARGUMENTS)
    390         {
    391             this->descriptionParam_[param] = std::string("ConsoleCommandDescription::" + this->baseName_ + "::param" + multi_cast<std::string>(param));
    392             AddLanguageEntry(this->descriptionParam_[param], description);
    393         }
    394         return *this;
    395     }
    396 
    397     const std::string& ConsoleCommand::getDescriptionParam(unsigned int param) const
    398     {
    399         if (param < MAX_FUNCTOR_ARGUMENTS)
    400             return GetLocalisation_noerror(this->descriptionParam_[param]);
     534    /**
     535        @brief Sets the description for an argument with given index.
     536    */
     537    ConsoleCommand& ConsoleCommand::descriptionParam(unsigned int index, const std::string& description)
     538    {
     539        if (index < MAX_FUNCTOR_ARGUMENTS)
     540        {
     541            this->descriptionParam_[index] = std::string("ConsoleCommandDescription::" + this->baseName_ + "::param" + multi_cast<std::string>(index));
     542            AddLanguageEntry(this->descriptionParam_[index], description);
     543        }
     544        return *this;
     545    }
     546
     547    /**
     548        @brief Returns the description for the argument with given index.
     549    */
     550    const std::string& ConsoleCommand::getDescriptionParam(unsigned int index) const
     551    {
     552        if (index < MAX_FUNCTOR_ARGUMENTS)
     553            return GetLocalisation_noerror(this->descriptionParam_[index]);
    401554
    402555        return this->descriptionParam_[0];
    403556    }
    404557
     558    /**
     559        @brief Sets the description for the return-value.
     560    */
    405561    ConsoleCommand& ConsoleCommand::descriptionReturnvalue(const std::string& description)
    406562    {
    … …  
    410566    }
    411567
    412     const std::string& ConsoleCommand::getDescriptionReturnvalue(int param) const
     568    /**
     569        @brief Returns the description for the return-value.
     570    */
     571    const std::string& ConsoleCommand::getDescriptionReturnvalue(int index) const
    413572    {
    414573        return GetLocalisation_noerror(this->descriptionReturnvalue_);
    415574    }
    416575
     576    /**
     577        @brief Returns the command with given group an name.
     578        @param group The group of the requested command
     579        @param name The group of the requested command
     580        @param bPrintError If true, an error is printed if the command doesn't exist
     581    */
    417582    /* static */ const ConsoleCommand* ConsoleCommand::getCommand(const std::string& group, const std::string& name, bool bPrintError)
    418583    {
     584        // find the group
    419585        std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = ConsoleCommand::getCommandMap().find(group);
    420586        if (it_group != ConsoleCommand::getCommandMap().end())
    421587        {
     588            // find the name
    422589            std::map<std::string, ConsoleCommand*>::const_iterator it_name = it_group->second.find(name);
    423590            if (it_name != it_group->second.end())
    424591            {
     592                // return the pointer
    425593                return it_name->second;
    426594            }
    … …  
    436604    }
    437605
     606    /**
     607        @brief Returns the command with given group an name in lowercase.
     608        @param group The group of the requested command in lowercase
     609        @param name The group of the requested command in lowercase
     610        @param bPrintError If true, an error is printed if the command doesn't exist
     611    */
    438612    /* static */ const ConsoleCommand* ConsoleCommand::getCommandLC(const std::string& group, const std::string& name, bool bPrintError)
    439613    {
    … …  
    441615        std::string nameLC = getLowercase(name);
    442616
     617        // find the group
    443618        std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = ConsoleCommand::getCommandMapLC().find(groupLC);
    444619        if (it_group != ConsoleCommand::getCommandMapLC().end())
    445620        {
     621            // find the name
    446622            std::map<std::string, ConsoleCommand*>::const_iterator it_name = it_group->second.find(nameLC);
    447623            if (it_name != it_group->second.end())
    448624            {
     625                // return the pointer
    449626                return it_name->second;
    450627            }
    … …  
    460637    }
    461638
     639    /**
     640        @brief Returns the static map that stores all console commands.
     641    */
    462642    /* static */ std::map<std::string, std::map<std::string, ConsoleCommand*> >& ConsoleCommand::getCommandMap()
    463643    {
    … …  
    466646    }
    467647
     648    /**
     649        @brief Returns the static map that stores all console commands in lowercase.
     650    */
    468651    /* static */ std::map<std::string, std::map<std::string, ConsoleCommand*> >& ConsoleCommand::getCommandMapLC()
    469652    {
    … …  
    472655    }
    473656
     657    /**
     658        @brief Registers a new command with given group an name by adding it to the command map.
     659    */
    474660    /* static */ void ConsoleCommand::registerCommand(const std::string& group, const std::string& name, ConsoleCommand* command)
    475661    {
    … …  
    477663            return;
    478664
     665        // check if a command with this name already exists
    479666        if (ConsoleCommand::getCommand(group, name) != 0)
    480667        {
    … …  
    486673        else
    487674        {
     675            // add the command to the map
    488676            ConsoleCommand::getCommandMap()[group][name] = command;
    489677            ConsoleCommand::getCommandMapLC()[getLowercase(group)][getLowercase(name)] = command;
    … …  
    491679    }
    492680
     681    /**
     682        @brief Removes the command from the command map.
     683    */
    493684    /* static */ void ConsoleCommand::unregisterCommand(ConsoleCommand* command)
    494685    {
     686        // iterate through all groups
    495687        for (std::map<std::string, std::map<std::string, ConsoleCommand*> >::iterator it_group = ConsoleCommand::getCommandMap().begin(); it_group != ConsoleCommand::getCommandMap().end(); )
    496688        {
     689            // iterate through all commands of each group
    497690            for (std::map<std::string, ConsoleCommand*>::iterator it_name = it_group->second.begin(); it_name != it_group->second.end(); )
    498691            {
     692                // erase the command
    499693                if (it_name->second == command)
    500694                    it_group->second.erase(it_name++);
    … …  
    503697            }
    504698
     699            // erase the group if it is empty now
    505700            if (it_group->second.empty())
    506701                ConsoleCommand::getCommandMap().erase(it_group++);
    … …  
    509704        }
    510705
     706        // now the same for the lowercase-map:
     707
     708        // iterate through all groups
    511709        for (std::map<std::string, std::map<std::string, ConsoleCommand*> >::iterator it_group = ConsoleCommand::getCommandMapLC().begin(); it_group != ConsoleCommand::getCommandMapLC().end(); )
    512710        {
     711            // iterate through all commands of each group
    513712            for (std::map<std::string, ConsoleCommand*>::iterator it_name = it_group->second.begin(); it_name != it_group->second.end(); )
    514713            {
     714                // erase the command
    515715                if (it_name->second == command)
    516716                    it_group->second.erase(it_name++);
    … …  
    519719            }
    520720
     721            // erase the group if it is empty now
    521722            if (it_group->second.empty())
    522723                ConsoleCommand::getCommandMapLC().erase(it_group++);
    … …  
    526727    }
    527728
     729    /**
     730        @brief Deletes all commands
     731    */
    528732    /* static */ void ConsoleCommand::destroyAll()
    529733    {
     734        // delete entries until the map is empty
    530735        while (!ConsoleCommand::getCommandMap().empty() && !ConsoleCommand::getCommandMap().begin()->second.empty())
    531736            delete ConsoleCommand::getCommandMap().begin()->second.begin()->second;
Note: See TracChangeset for help on using the changeset viewer.