Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/trunk/src/libraries/core/command/ArgumentCompletionFunctions.h @ 9017

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

merged doc branch back to trunk

  • Property svn:eol-style set to native
File size: 9.6 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    @file
31    @ingroup Command ArgumentCompletion
32    @brief Declaration of all argument completion functions and macros used to define them.
33
34    @anchor ArgumentCompletionExample
35
36    Argument completion functions are used to create a list of possible arguments
37    for an orxonox::ConsoleCommand. These functions are usually wrapped by an instance
38    of orxonox::ArgumentCompleter.
39
40    Argument completion functions can be declared and implemented by using the macros
41    ARGUMENT_COMPLETION_FUNCTION_DECLARATION() and ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION()
42    respectively. They are necessary because they don't simply define the function, but they also
43    create a static helper function that returns an instance of orxonox::ArgumentCompleter which
44    wraps the defined function. This allows easier referencing of argument completion functions
45    by simply calling autocompletion::functionname().
46
47    Argument completion functions can take up to 5 arguments, all of type std::string.
48    The first argument is always the current argument which is being entered by the user
49    in the shell. The second argument is the argument before, so in fact arguments from
50    the shell are sent in reversed order to the argument completion function. This is
51    necessary because the number of arguments can be variable
52
53    Example: The user types the following into the shell:
54    @code
55    $ commandname argument1 argument2 argum
56    @endcode
57    Then he presses the @a tab key to print the possible arguments. Now the argument
58    completion function for the @a third argument of @a commandname will be called in
59    the following way:
60    @code
61    list = argcompfunction3("argum", "argument2", "argument1");
62    @endcode
63
64    Usually each argument is one word (without whitespaces in it), but some argument completion
65    functions need more than one word. This can be achieved by using ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI().
66    In this case all supernumerous words are passed to the first (!) argument.
67
68    An example to show how to declare, implement, and use an argument completion function:
69    @code
70    // ArgumentCompletionFunctions.h:
71    // ------------------------------
72
73    // Declaration of the function:
74    ARGUMENT_COMPLETION_FUNCTION_DECLARATION(month)(const std::string& fragment);
75
76    // ArgumentCompletionFunctions.cc:
77    // -------------------------------
78
79    // Implementation of the function
80    ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(month)(const std::string& fragment)
81    {
82        ArgumentCompletionList list;
83
84        // check if the first part of the argument is a number - if yes, the user likely wants to enter the month as a number
85        if (isNumber(fragment))
86        {
87            for (int month = 1; month <= 12; ++month)
88                list.push_back(ArgumentCompletionListElement(multi_cast<std::string>(month)));
89        }
90        else
91        {
92            list.push_back(ArgumentCompletionListElement("January",   "january"));
93            list.push_back(ArgumentCompletionListElement("February",  "february"));
94            list.push_back(ArgumentCompletionListElement("March",     "march"));
95            list.push_back(ArgumentCompletionListElement("April",     "april"));
96            list.push_back(ArgumentCompletionListElement("May",       "may"));
97            list.push_back(ArgumentCompletionListElement("June",      "june"));
98            list.push_back(ArgumentCompletionListElement("July",      "july"));
99            list.push_back(ArgumentCompletionListElement("August",    "august"));
100            list.push_back(ArgumentCompletionListElement("September", "september"));
101            list.push_back(ArgumentCompletionListElement("October",   "october"));
102            list.push_back(ArgumentCompletionListElement("November",  "november"));
103            list.push_back(ArgumentCompletionListElement("December",  "december"));
104        }
105
106        return list;
107    }
108
109    // SomeFile:
110    // ---------
111
112    // A class to manage the date:
113    class Date
114    {
115        public:
116            static void setDate(int day, const std::string& month, int year);
117    };
118
119    // Define a console command that needs a date. Add argument completion for the month:
120    SetConsoleCommand("setDate", &Date::setDate).argumentCompleter(1, autocompletion::month());
121    @endcode
122
123    This example defines an argument completion function that returns a list of possible
124    months. If the first part of the argument is a number, it returns the numbers 1-12,
125    otherwise the name of the months are returned. Note how the list is composed by
126    instances of orxonox::ArgumentCompletionListElement. For the name of the months,
127    two strings are provided, one in normal case and one in lower case. See the documentation
128    of orxonox::ArgumentCompletionListElement for more information about this.
129
130    Also note that the argument completion list is assigned to the console command by using
131    @ref orxonox::ConsoleCommand::argumentCompleter "argumentCompleter()". The first argument
132    is the index of the argument:
133     - 0 is the first argument (@a day)
134     - 1 is the second argument (@a month)
135     - 2 is the third argument (@a year)
136
137    @a day and @a year don't need an argument completion function as they are just integers.
138
139    The function @c autocompletion::month() is automatically created by the macros
140    ARGUMENT_COMPLETION_FUNCTION_DECLARATION() and ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION()
141    and returns an orxonox::ArgumentCompleter that wraps the defined argument completion function.
142
143    The implemented argument completion function uses only one argument, the fragment of the
144    currently entered argument. More complex functions can also use the previous arguments
145    to return different arguments depending on the other arguments (for example to list the
146    members of a class, where the class-name is the first argument and the member the second).
147*/
148
149#ifndef _ArgumentCompletionFunctions_H__
150#define _ArgumentCompletionFunctions_H__
151
152#include "core/CorePrereqs.h"
153#include "ArgumentCompleter.h"
154
155/**
156    @brief Used to declare an argument completion function with name @a functionname.
157    @param functionname The name of the function, will also be used for the implementation of the function.
158
159    The macro also defines a static function that returns an orxonox::ArgumentCompleter
160    which wraps the defined function. This can be accessed by calling autocompletion::functionname();
161*/
162#define ARGUMENT_COMPLETION_FUNCTION_DECLARATION(functionname) \
163    _CoreExport ArgumentCompleter* functionname(); \
164    _CoreExport ArgumentCompletionList acf_##functionname
165
166/**
167    @brief Used to implement an argument completion function.
168    @param functionname The name of the function
169*/
170#define ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(functionname) \
171    _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, false)
172
173/**
174    @brief Used to implement an argument completion function which allows multiple words.
175    @param functionname The name of the function
176*/
177#define ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI(functionname) \
178    _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, true)
179
180/// Internal macro
181#define _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, bUseMultipleWords) \
182    ArgumentCompleter* functionname() \
183    { \
184        static ArgumentCompleter completer = ArgumentCompleter(&acf_##functionname, bUseMultipleWords); \
185        return &completer; \
186    } \
187    \
188    ArgumentCompletionList acf_##functionname
189
190/// Calls an argument completion function. Used for functions that return the results of another argument completion function.
191#define ARGUMENT_COMPLETION_FUNCTION_CALL(functionname) acf_##functionname
192
193
194namespace orxonox
195{
196    namespace autocompletion
197    {
198        ARGUMENT_COMPLETION_FUNCTION_DECLARATION(fallback)();
199        ARGUMENT_COMPLETION_FUNCTION_DECLARATION(groupsandcommands)(const std::string& fragment);
200        ARGUMENT_COMPLETION_FUNCTION_DECLARATION(subcommands)(const std::string& fragment, const std::string& group);
201        ARGUMENT_COMPLETION_FUNCTION_DECLARATION(command)(const std::string& fragment);
202        ARGUMENT_COMPLETION_FUNCTION_DECLARATION(hiddencommand)(const std::string& fragment);
203        ARGUMENT_COMPLETION_FUNCTION_DECLARATION(files)(const std::string& fragment);
204        ARGUMENT_COMPLETION_FUNCTION_DECLARATION(settingssections)();
205        ARGUMENT_COMPLETION_FUNCTION_DECLARATION(settingsentries)(const std::string& fragment, const std::string& section);
206        ARGUMENT_COMPLETION_FUNCTION_DECLARATION(settingsvalue)(const std::string& fragment, const std::string& entry, const std::string& section);
207        ARGUMENT_COMPLETION_FUNCTION_DECLARATION(tclthreads)();
208    }
209}
210
211#endif /* _ArgumentCompletionFunctions_H__ */
Note: See TracBrowser for help on using the repository browser.