Adding New Functions

Adding New Functions

The following information was found in the hnb distribution. I have copied it here for convenience and cleaned it up somewhat.

---

The command line interpreter (CLI) used was developed specifically for this application, but it is made not in any way dependant on any other thing than C.

The libcli directory contains the code for the CLI library.

Adding Commands and Variables

To add a command to the interpreter, issue the macro:

cli_add_command("commandname", callback, "description");

where callback is a function of the form:

int callback(char *params);

The description string should describe the parameters the callback function expects. The ? command line command displays this information with the command name.

The string passed to the callback function is the string remaining when the command is chopped off the command line.

Variables can be added with either of the following macros:

cli_add_int("variablename", &integer_variable, "description");
cli_add_string("variablename", &string_variable, "description");

You can also call the real add function:

cli_add_item("variablename", &integerdata, &stringdata, callback, "description");

In this case, the callback is called whenever the variable is set. A variable set using cli_add_item can have both integer and string values attached at the same time.

Running Commands

The function cli_docmd("commandline") parses the command line and runs the associated callback function. It returns the value returned by the callback function.

You can wrap this function in a macro, making it possible to use printf style formatting:

#define docmdf(args...) \
    do{ char buf[100];\
        snprintf (buf, 99, args);\
        cli_docmd(buf);\
    }while(0)

Command line Completion

The function:

char *cli_complete(const char *commandline);

Returns a completion of the given command line.

• The string returned is statically allocated
• If there is no match, a message is printed on the output
• If there are multiple possible matches, the interpreter lists them all and expands the command line is expanded to the common leading characters.

Customization

By default, the CLI outputs to standard output. When embedding it in another application, this may not be desired behavior. libcli includes several function pointers for changing the CLI output.

• cli_outfun: a void function, taking an output string as its only parameter.
• cli_width: an integer, defining the width in characters of the output device. (Default: 40)
• cli_precmd: (optional) a void function, taking the command line as a parameter to be executed before each command.
• cli_postcmd: (optional) a void function, taking the command line as a parameter to be executed after each command.

History

libcli also provides a simple history facility. If you call cli_history_add("commandline"); for every function you execute, the following commands page back and forward through the history.

char *cli_historyprev();
char *cli_historynext();