Introduction.
This module provides simple yet powerful implementation of a Command Line Interface. A command line interface is represented by the CLIConsole object. CLIConsole object should be associated with an IODevice, through which it communicates with the user.
CLI module provides two types of input:
- in key press mode, the console reacts on every single key
- in command line mode, the console buffers the incoming characters until end-of-line character (ENTER) is received, and then it reacts The user can switch between both operating modes by pressing the '~' character.
Configuration
To enable CLI module the HAL_ENABLE_CLI declaration should be set to 1 in HAL configuration file.
The default command line length is 127 characters. To override it, declare new value using CLI_COMMAND_BUF_SIZE definition in HAL configuration file.
Declaring CLIConsole objects.
Usually, an application requires only one command line interface - thus only one CLIConsole object is needed. To declare it, use convenient macro CLI_DECLARE like this:
CLI_DECLARE(mycli, USART1, mycommandprocessor,
static);
This declares CLIConsole object with name 'mycli', working on IODevice named USART1, with a command handler function named commandProcessor. Additionally, the 'mycli' object will be declared as static (you can leave the last parameter blank for no additional attributes).
Running the console.
To run the console, the CLI_ProcessConsole function should be executed periodically, with an interval short enough to provide good user experience (responsiveness). Usually, before running the main console screen is displayed:
Parsing the commands.
When run in command line mode, the console buffers all incomming characters until end-of-line (ENTER) character is received. After that the console executes a special user-defined command line processing function, that handles the command. The CLI module defines the format and behaviour of that function as well as provides tools for making the job of command processing easier.
The command processor function should have the following declaration:
The function takes the cli console handle as a parameter. Let's look at a simplest implementation of a command processor function.
{
char item[32];
if (0 == strcmp((char*)item,"help")) {
return;
}
return;
}
|
CLIConsole | CLI_Create (IODevice iodevice) |
|
void | CLI_Destroy (CLIConsole cli) |
|
void | CLI_DisplayMainScreen (CLIConsole cli) |
|
CLIConsoleAction | CLI_ProcessConsole (CLIConsole cli) |
|
void | CLI_SetCommandProcessor (CLIConsole cli, void(*cmd_proc)(CLIConsole cli)) |
|
void | CLI_ForceCommandMode (CLIConsole cli) |
|
void | CLI_CursorSave (CLIConsole cli) |
|
void | CLI_CursorRestore (CLIConsole cli) |
|
void | CLI_CursorRest (CLIConsole cli) |
|
bool | CLI_GetCommand (CLIConsole cli, char *dst, size_t dst_size) |
|
bool | CLI_IsNextArg (CLIConsole cli) |
|
bool | CLI_GetNextArg (CLIConsole cli, char *arg) |
|
bool | CLI_GetNextArgAndConvertToLowerCase (CLIConsole cli, char *arg, size_t argMaxSize) |
|
bool | CLI_GetNextArgINT32 (CLIConsole cli, int32_t *arg) |
|
bool | CLI_GetNextArgUINT32 (CLIConsole cli, uint32_t *arg) |
|
bool | CLI_GetNextArgINT64 (CLIConsole cli, int64_t *arg) |
|
bool | CLI_GetNextArgUINT64 (CLIConsole cli, uint64_t *arg) |
|
void | CLI_GetBack (CLIConsole cli, int argc) |
|
#define CLI_DECLARE |
( |
|
name, |
|
|
|
iodevice, |
|
|
|
command_processor, |
|
|
|
attribute |
|
) |
| |
Value:
void(* command_processor)(CLIConsole clic)
external command processor handle
Definition: hal_cli.h:151
Command Line Interface Console descriptor.
Definition: hal_cli.h:139
IODevice iodevice
IODevice object associated with console.
Definition: hal_cli.h:141
Macro that declares a CLIConsole object.
Declares a CLIConsole object in a convenient manner.
- Parameters
-
name | name of the new CLIConsole |
iodevice | an IODevice that will be associated with the console |
command_processor | a function that will act as a command handler for CLIConsole |
attribute | additional attributes for the CLIConsole variable such as 'static' or 'volatile' etc. |
#define CLI_HaltConsoleInput |
( |
|
cli | ) |
do { cli->state.busy = 1; } while (0) |
Disables input grabbing.
Disables input grabbing. No data will be read from IODevice object.
- Parameters
-
#define CLI_EnableConsoleInput |
( |
|
cli | ) |
do { cli->state.busy = 0; } while (0) |
#define CLI_GetIODevice |
( |
|
cli | ) |
(cli->iodevice) |
Gets IODevice associated with console.
Returns the currently associated IODevice object on top of which the console operates.
- Parameters
-
- Returns
- IODevice object associated with console.
#define CLI_SetIODevice |
( |
|
cli, |
|
|
|
device |
|
) |
| (cli->iodevice=device) |
Set IODevice associated with console.
- Parameters
-
cli | console handle |
device | IODevice object to associate with console. |
- Returns
- IODevice object associated with console.
Type denoting action taken by the CLI_ProcessConsole function.
Enumerator |
---|
CLI_NO_ACTION |
No action was taken.
|
CLI_DEFAULT_ACTION |
A default action was taken (could not resolve which option call)
|
CLI_USER_ACTION |
User supplied function was called.
|
CLI_BUSY |
Console is busy.
|
Creates the console object and associates it with a given IODevice object. Uses HEAP module for memory allocation. To delete the object created use CLI_Destroy.
- Parameters
-
iodevice | IODevice on top of which the console operates |
- Returns
- handle of the console, which in fact is a pointer to console's description structure
Deletes the previously created console object. Uses HEAP module to free the memory allocated by a call to complementary CLI_Create.
- Parameters
-
Displays main screen on the console.
- Parameters
-
CLI core processor function. It reads data from the IODevice object associated with console and processes it. If necessary, it calls the user supplied functions according to the recognized commands. It handles both hot-key and command line modes. In command line mode, external, user supplied command processor function is called (see CLI_SetCommandProcessor).
- Parameters
-
Sets the command processor function for command-line mode of operation.
- Parameters
-
cli | console handle |
cmd_proc | command processor function |
Forces the console to go into command mode.
- Parameters
-
Causes the console to save the cursor position. The position can be restored by CLI_CursorRestore
- Parameters
-
Causes the console to restore the cursor position, previously stored by CLI_CursorSave
- Parameters
-
Causes the on-screen cursor to move to the rest position.
- Parameters
-
bool CLI_GetCommand |
( |
CLIConsole |
cli, |
|
|
char * |
dst, |
|
|
size_t |
dst_size |
|
) |
| |
Extracts and copies first item from the source command line to a destination buffer. This function initializes further processing of arguments on the provided command line. To sequentially get additional command line arguments use CLI_GetNextArg, CLI_GetNextArgINT32, CLI_GetNextArgUINT32, CLI_GetNextArgINT64 or CLI_GetNextArgUINT64.
- Parameters
-
cli | console handle |
dst | destination buffer |
dst_size | size of the destination buffer (maximum nuber of characters it can store) |
Checks if there is another argument on the command line.
- Parameters
-
- Returns
- false if there are no more arguments or true if there are some more
bool CLI_GetNextArg |
( |
CLIConsole |
cli, |
|
|
char * |
arg |
|
) |
| |
Extracts next argument from the command line as a string.
- Parameters
-
cli | console handle |
arg | destination buffer |
bool CLI_GetNextArgAndConvertToLowerCase |
( |
CLIConsole |
cli, |
|
|
char * |
arg, |
|
|
size_t |
argMaxSize |
|
) |
| |
Extracts next argument from the command line as a string. In addition converts all upper-case characters to lower-case.
- Parameters
-
cli | console handle |
arg | destination buffer |
argMaxSize | maximum number of bytes that the destination buffer can store |
bool CLI_GetNextArgINT32 |
( |
CLIConsole |
cli, |
|
|
int32_t * |
arg |
|
) |
| |
Extracts next argument from the command line as a 32bit signed integer.
- Parameters
-
cli | console handle |
arg | pointer to destination variable where the argument value will be stored |
- Returns
- true if operation succeeded, false if failed
bool CLI_GetNextArgUINT32 |
( |
CLIConsole |
cli, |
|
|
uint32_t * |
arg |
|
) |
| |
Extracts next argument from the command line as a 32bit unsigned integer.
- Parameters
-
cli | console handle |
arg | pointer to destination variable where the argument value will be stored |
- Returns
- true if operation succeeded, false if failed
bool CLI_GetNextArgINT64 |
( |
CLIConsole |
cli, |
|
|
int64_t * |
arg |
|
) |
| |
Extracts next argument from the command line as a 64bit signed integer.
- Parameters
-
cli | console handle |
arg | pointer to destination variable where the argument value will be stored |
- Returns
- true if operation succeeded, false if failed
bool CLI_GetNextArgUINT64 |
( |
CLIConsole |
cli, |
|
|
uint64_t * |
arg |
|
) |
| |
Extracts next argument from the command line as a 64bit unsigned integer.
- Parameters
-
cli | console handle |
arg | pointer to destination variable where the argument value will be stored |
- Returns
- true if operation succeeded, false if failed
Moves back argc arguments in the command line.
- Parameters
-
cli | console handle |
argc | number of arguments |