ArgumentCompletionFunctions

TracNav(TracNav/TOC_Development)?

Description

An ArgumentCompletionFunction returns an ArgumentCompletionList used by the CommandExecutor to complete arguments of a ConsoleCommand. To bind an ArgumentCompletionFunction to an argument, an ArgumentCompleter is use.

Arguments

An ArgumentCompletionFunction may take several parameters. The first parameter is the currently given argument fragment, the second parameter is the last finished argument, the third parameter is the second last finished argument etc.

Example:

There are currently 3 finished arguments and one fragment. The user wants a list of the possible arguments for the fourth argument:

> command-name argument1 argument2 argument3 fragment

Then the ArgumentCompletionFunction of the fourth argument gets called the following way:

ac_function(fragment, argument3, argument2, argument1);

Of course the function doesn't necessarily has to take all arguments, it's possible to just use the fragment or to use no arguments at all.

Usage

Defining a new ArgumentCompletionFunction

In core/ArgumentCompletionFunctions.h write:

ARGUMENT_COMPLETION_FUNCTION_DECLARATION(functionname)  \
                         (const std::string& fragment,  \
                          const std::string& argument1, \
                          const std::string& argument2, \
                          ...);

Implementing a new ArgumentCompletionFunction

In core/ArgumentCompletionFunctions.cc write:

ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(functionname)  \
                            (const std::string& fragment,  \
                             const std::string& argument1, \
                             const std::string& argument2, \
                          ...);
{
    ArgumentCompletionList myList;

    for (some_condition)
    {
        std::string argument, lowercase, display;

        argument  = some_logic1();
        lowercase = some_logic2();
        display   = some_logic3();

        ArgumentCompletionListElement element(argument, lowercase, display)
        myList.push_back(element);
    }

    return myList;
}

Note: lowercase and display in the constructor of ArgumentCompletionListElement are optional. If not specified, the first string (argument) is used.

Example

The following example implements an ArgumentCompletionList returning a set of possible names for girls or boys:

In core/ArgumentCompletionFunctions.h:

ARGUMENT_COMPLETION_FUNCTION_DECLARATION(children_names) \
    (const std::string& fragment, const std::string& gender);

In core/ArgumentCompletionFunctions.cc:

ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(children_names) \
    (const std::string& fragment, const std::string& gender)
{
    ArgumentCompletionList myList;

    if (gender == "boy")
    {
        myList.push_back(ArgumentCompletionListElement("Bob", "bob"));
        myList.push_back(ArgumentCompletionListElement("John", "john"));
        myList.push_back(ArgumentCompletionListElement("Elton", "elton"));
        myList.push_back(ArgumentCompletionListElement("Bruce", "bruce"));
    }
    else if (gender == "girl")
    {
        myList.push_back(ArgumentCompletionListElement("Jessica", "jessica"));
        myList.push_back(ArgumentCompletionListElement("Amanda", "amanda"));
        myList.push_back(ArgumentCompletionListElement("Kate", "kate"));
        myList.push_back(ArgumentCompletionListElement("Angelina", "angelina"));
    }

    return myList;
}

Now it's possible to complete names:

> command-name boy
Possible arguments: Bob, Bruce, Elton, John

> command-name boy b
Possible arguments: Bob, Bruce

> command-name boy bo
Possible arguments: Bob

> command-name girl je
Possible arguments: Jessica

> command-name girl jennif
Possible arguments: -