Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/branches/ai/src/libraries/core/command/CommandEvaluation.h @ 7900

Last change on this file since 7900 was 7401, checked in by landauf, 14 years ago

merged doc branch back to trunk

  • Property svn:eol-style set to native
File size: 7.0 KB
Line 
1/*
2 *   ORXONOX - the hottest 3D action shooter ever to exist
3 *                    > www.orxonox.net <
4 *
5 *
6 *   License notice:
7 *
8 *   This program is free software; you can redistribute it and/or
9 *   modify it under the terms of the GNU General Public License
10 *   as published by the Free Software Foundation; either version 2
11 *   of the License, or (at your option) any later version.
12 *
13 *   This program is distributed in the hope that it will be useful,
14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 *   GNU General Public License for more details.
17 *
18 *   You should have received a copy of the GNU General Public License
19 *   along with this program; if not, write to the Free Software
20 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
21 *
22 *   Author:
23 *      Fabian 'x3n' Landau
24 *   Co-authors:
25 *      ...
26 *
27 */
28
29/**
30    @defgroup CommandExecEval Command execution and evaluation
31    @ingroup Command
32*/
33
34/**
35    @file
36    @ingroup Command CommandExecEval
37    @brief Declaration of the orxonox::CommandEvaluation class which is returned by orxonox::CommandExecutor::evaluate().
38
39    The orxonox::CommandEvaluation class gathers all information about a command-string. It is used
40    internally by orxonox::CommandExecutor and can also be returned by it to provide more information
41    about a command. It's also possible to evaluate the arguments of a command to execute it faster.
42
43    @see See @ref CommandExecutorExample "this description" for an example.
44*/
45
46#ifndef _CommandEvaluation_H__
47#define _CommandEvaluation_H__
48
49#include "core/CorePrereqs.h"
50
51#include <string>
52
53#include "util/SubString.h"
54#include "util/MultiType.h"
55#include "ArgumentCompletionListElement.h"
56#include "Functor.h"
57
58namespace orxonox
59{
60    /**
61        @brief CommandEvaluation is used to gather information about a command and to evaluate its arguments
62
63        This class provides several information about a command-string, for example the
64        evaluated ConsoleCommand, but also other information like hints if the command
65        is not yet finished.
66
67        @note You don't have to call evaluateArguments() manually, it's also done automatically
68        if you call the command the first time. However you can of course do it at any earlier
69        time, for example to return an error message if it doesn't work.
70
71        @remarks execCommand_ and hintCommand_ can be different in this case: There are multiple
72        commands avaliable, let's say "tcl", "tclexecute", and "tclquery". The user enters
73        "tcl", which is already a valid command. Now execCommand_ points to the "tcl"-command,
74        but hintCommand_ still points to the autocompletion command of CommandExecutor, because
75        the auto-completion list must still return the three possible commands, "tcl tclexecute tclquery"
76        because the user may want to execute "tclquery" and needs auto-completion.
77
78        @see See @ref CommandExecutorExample "this description" for an example.
79    */
80    class _CoreExport CommandEvaluation
81    {
82        friend class CommandExecutor;
83
84        public:
85            CommandEvaluation();
86
87            int execute();
88            MultiType query(int* error = 0);
89
90            std::string complete();
91            std::string hint();
92
93            std::string getCommandSuggestion() const;
94
95            int evaluateArguments(bool bPrintError = false);
96
97            /// Returns true if the command evaluation contains a valid command that can be executed.
98            inline bool isValid() const
99                { return (this->execCommand_ != 0); }
100
101            /// Returns the console command that was evaluated by this object.
102            inline const ConsoleCommand* getConsoleCommand() const
103                { return this->execCommand_; }
104
105            void setEvaluatedArgument(unsigned int index, const MultiType& arg);
106            MultiType getEvaluatedArgument(unsigned int index) const;
107
108            /**
109                @brief Returns a list of possible arguments for the given command.
110
111                Note that the command's arguments may not be complete yet, so in this case
112                this list returns the possibilities. They can then be used to display a list
113                of the possible arguments or to apply auto-completion.
114            */
115            const ArgumentCompletionList& getPossibleArguments() const
116                { return this->possibleArguments_; }
117
118            /// Returns the number of possible arguments. Empty ("") arguments are not counted.
119            size_t getPossibleArgumentsSize() const
120                { return CommandEvaluation::getSize(this->possibleArguments_); }
121
122        private:
123            void initialize(const std::string& command);
124
125            unsigned int getNumberOfArguments() const;
126            const std::string& getLastArgument() const;
127            const std::string& getToken(unsigned int i) const;
128
129            void retrievePossibleArguments();
130
131            static void strip(ArgumentCompletionList& list, const std::string& fragment);
132            static size_t getSize(const ArgumentCompletionList& list);
133
134            static std::string dump(const ArgumentCompletionList& list);
135            static std::string dump(const ConsoleCommand* command);
136
137            static std::string getCommonBegin(const ArgumentCompletionList& list);
138
139            const ConsoleCommand* execCommand_;             ///< The command that will be executed (can be NULL if the command is not valid)
140            const ConsoleCommand* hintCommand_;             ///< The command that is used to display hints and argument lists (can be different to execCommand_ in some cases)
141            SubString tokens_;                              ///< The single words of the command string, split into tokens
142            std::string string_;                            ///< The original command string, entered by the user in the shell
143            unsigned int execArgumentsOffset_;              ///< The index of the first argument in tokens_ used to execute the command
144            unsigned int hintArgumentsOffset_;              ///< The index of the first argument in tokens_ used to display hints and argument lists
145            bool bPossibleArgumentsRetrieved_;              ///< True if the list of possible arguments was already retrieved
146            ArgumentCompletionList possibleArguments_;      ///< List of possible arguments for the command in the current state
147
148            bool bEvaluatedArguments_;                      ///< True if the arguments of the command have been evaluated (and stored in arguments_)
149            bool bTriedToEvaluatedArguments_;               ///< True if an attempt was started to evaluate the arguments (but not necessarily successful)
150            unsigned int numberOfEvaluatedArguments_;       ///< The number of evaluated arguments (ranges from 0 to MAX_FUNCTOR_ARGUMENTS)
151            MultiType arguments_[MAX_FUNCTOR_ARGUMENTS];    ///< The evaluated arguments (the arguments from string_ or tokens_ converted to the right type)
152    };
153}
154
155#endif /* _CommandEvaluation_H__ */
Note: See TracBrowser for help on using the repository browser.