Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 4, 2010, 11:33:02 PM (15 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/ArgumentCompletionFunctions.h

    r7284 r7352  
    2727 */
    2828
     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
    29149#ifndef _ArgumentCompletionFunctions_H__
    30150#define _ArgumentCompletionFunctions_H__
    … …  
    33153#include "ArgumentCompleter.h"
    34154
    35 
     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*/
    36162#define ARGUMENT_COMPLETION_FUNCTION_DECLARATION(functionname) \
    37163    _CoreExport ArgumentCompleter* functionname(); \
    38164    _CoreExport ArgumentCompletionList acf_##functionname
    39165
     166/**
     167    @brief Used to implement an argument completion function.
     168    @param functionname The name of the function
     169*/
    40170#define ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(functionname) \
    41171    _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*/
    42177#define ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI(functionname) \
    43178    _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, true)
    44179
     180/// Internal macro
    45181#define _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, bUseMultipleWords) \
    46182    ArgumentCompleter* functionname() \
    … …  
    52188    ArgumentCompletionList acf_##functionname
    53189
     190/// Calls an argument completion function. Used for functions that return the results of another argument completion function.
    54191#define ARGUMENT_COMPLETION_FUNCTION_CALL(functionname) acf_##functionname
    55192
Note: See TracChangeset for help on using the changeset viewer.