= ArgumentCompletionFunctions =
[[TracNav(TracNav/TOC_Development)]]

== Description ==
An ArgumentCompletionFunction returns an [wiki:ArgumentCompletionList] used by the [wiki:CommandExecutor] to complete arguments of a [wiki:ConsoleCommand]. To bind an ArgumentCompletionFunction to an argument, an [wiki: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: -
}}}