HALFRED  0.4.0
Data Structures | Macros | Typedefs | Enumerations | Functions
CLI module

Detailed Description

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:

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:

// Clear console screen and display main menu
while (1) {
// Process the console
}

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:

void mycommandprocessor(CLIConsole cli);

The function takes the cli console handle as a parameter. Let's look at a simplest implementation of a command processor function.

void mycommandprocessor(CLIConsole cli)
{
IODevice iodevice;
char item[32];
// first, get the IODevice associated with console
iodevice = CLI_GetIODevice(cli);
// get command from command line (returns only the first word of a command)
CLI_GetCommand(cli, item);
// compare the command string against predefined commands
if (0 == strcmp((char*)item,"help")) {
// 'help' command
TXTDEV_WriteString(iodevice,"This is HELP.");
TXTDEV_WriteString(iodevice,"Use the ~ character to change CLI mode.");
TXTDEV_WriteNL(iodevice);
return;
}
TXTDEV_WriteString(iodevice,"Unknown command.");
return;
}

Data Structures

struct  CLIConsoleDesc
 Command Line Interface Console descriptor. More...
 

Macros

#define CLI_COMMAND_BUF_SIZE   127
 Default size of the command line buffer.
 
#define CLI_DECLARE(name, iodevice, command_processor, attribute)
 Macro that declares a CLIConsole object. More...
 
#define CLI_HaltConsoleInput(cli)   do { cli->state.busy = 1; } while (0)
 Disables input grabbing. More...
 
#define CLI_EnableConsoleInput(cli)   do { cli->state.busy = 0; } while (0)
 Enables input grabbing. More...
 
#define CLI_GetIODevice(cli)   (cli->iodevice)
 Gets IODevice associated with console. More...
 
#define CLI_SetIODevice(cli, device)   (cli->iodevice=device)
 Set IODevice associated with console. More...
 

Typedefs

typedef struct CLIConsoleDescCLIConsole
 

Enumerations

enum  CLIConsoleAction { CLI_NO_ACTION, CLI_DEFAULT_ACTION, CLI_USER_ACTION, CLI_BUSY }
 Type denoting action taken by the CLI_ProcessConsole function. More...
 

Functions

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)
 

Macro Definition Documentation

#define CLI_DECLARE (   name,
  iodevice,
  command_processor,
  attribute 
)
Value:
static struct CLIConsoleDesc name##_desc = {iodevice, {0,0,0}, command_processor, {0x00}, 0, 0 }; \
attribute CLIConsole name = &name##_desc
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
namename of the new CLIConsole
iodevicean IODevice that will be associated with the console
command_processora function that will act as a command handler for CLIConsole
attributeadditional 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
cliconsole handle
#define CLI_EnableConsoleInput (   cli)    do { cli->state.busy = 0; } while (0)

Enables input grabbing.

Re-enables input grabbing (see also CLI_HaltConsoleInput)

Parameters
cliconsole handle
#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
cliconsole handle
Returns
IODevice object associated with console.
#define CLI_SetIODevice (   cli,
  device 
)    (cli->iodevice=device)

Set IODevice associated with console.

Parameters
cliconsole handle
deviceIODevice object to associate with console.
Returns
IODevice object associated with console.

Typedef Documentation

typedef struct CLIConsoleDesc* CLIConsole

Handle of the CLIConsole object (pointer to CLIConsoleDesc structure)

Enumeration Type Documentation

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.

Function Documentation

CLIConsole CLI_Create ( IODevice  iodevice)

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
iodeviceIODevice on top of which the console operates
Returns
handle of the console, which in fact is a pointer to console's description structure
void CLI_Destroy ( CLIConsole  cli)

Deletes the previously created console object. Uses HEAP module to free the memory allocated by a call to complementary CLI_Create.

Parameters
cliconsole handle
void CLI_DisplayMainScreen ( CLIConsole  cli)

Displays main screen on the console.

Parameters
cliconsole handle
CLIConsoleAction CLI_ProcessConsole ( CLIConsole  cli)

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
cliconsole handle
void CLI_SetCommandProcessor ( CLIConsole  cli,
void(*)(CLIConsole cli)  cmd_proc 
)

Sets the command processor function for command-line mode of operation.

Parameters
cliconsole handle
cmd_proccommand processor function
void CLI_ForceCommandMode ( CLIConsole  cli)

Forces the console to go into command mode.

Parameters
cliconsole handle
void CLI_CursorSave ( CLIConsole  cli)

Causes the console to save the cursor position. The position can be restored by CLI_CursorRestore

Parameters
cliconsole handle
void CLI_CursorRestore ( CLIConsole  cli)

Causes the console to restore the cursor position, previously stored by CLI_CursorSave

Parameters
cliconsole handle
void CLI_CursorRest ( CLIConsole  cli)

Causes the on-screen cursor to move to the rest position.

Parameters
cliconsole handle
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
cliconsole handle
dstdestination buffer
dst_sizesize of the destination buffer (maximum nuber of characters it can store)
bool CLI_IsNextArg ( CLIConsole  cli)

Checks if there is another argument on the command line.

Parameters
cliconsole handle
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
cliconsole handle
argdestination 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
cliconsole handle
argdestination buffer
argMaxSizemaximum 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
cliconsole handle
argpointer 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
cliconsole handle
argpointer 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
cliconsole handle
argpointer 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
cliconsole handle
argpointer to destination variable where the argument value will be stored
Returns
true if operation succeeded, false if failed
void CLI_GetBack ( CLIConsole  cli,
int  argc 
)

Moves back argc arguments in the command line.

Parameters
cliconsole handle
argcnumber of arguments