== libcli.a and libcli2.a ==

The cli in libcli stands for Command Line Interpreter.  Just as the shell script level [wiki:GraspSwDemoScripts demo scripts] get their parsing support for the common [wiki:GraspSwCommandSyntax command syntax used throughout STARGRASP] from [wiki:GraspSwDemoFunctions functions], all software written in C including command line utilities, servers, and the embedded C in the controller use '''libcli''' functions to parse user command line strings and text based communication protocol messages.

Newer code generally uses '''libcli2.'''  A few older programs such as the [wiki:GraspExtrasOperationsStatserv status server] still use '''libcli.'''  The primary difference is in the definition of '''Function'''.  When writing a program that uses libcli, a C function of this type must be created for each command that the program should handle.  A '''Function''' must return the enumerated type '''PASSFAIL''' (provided by libcli) which can either be a value '''PASS''' or '''FAIL'''.  No further error code returns are supported by libcli.  The newer '''libcli2''' defines the arguments for '''Function''' in the same way as a C program's main:

{{{
typedef PASSFAIL Function (int argc, const char* argv[]);
}}}

with the name of the command which invokes Function as argv[0].  The older '''libcli''' does not pass the command name itself to Function.  Instead, it passes any and all arguments to the command as a single string:

{{{
typedef PASSFAIL Function (const char* args);
}}}

The above describes libcli's primary function: looking up a command in a table of defined "Function"s and invoking the correct one.  The library has other functions, such as parsing the arguments for a function and matching up and assigning values to variables in the C code for each argument.  The library can also be used to pass a command line over a pipe or network socket to a program called '''Director''' which is a customized shell for multiplexing several separate command line interpreters together.  Each of those command line interpreters are called "Agents" and libcli contains functions to facilitate building an Agent process.

The functions within libcli are described within the [http://software.cfht.hawaii.edu/director/director-man.html Director/Agent documentation]:

http://software.cfht.hawaii.edu/director/3_Agent_Programmers_Guide.html#SECTION00051000000000000000