weAut_01 / weAutSys    R 2.2.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Files | Data Structures | Defines | Functions | Variables
Command line interpreter (CLI)
+ + Application (layer) support + +

Overview

weAutSys has an command line interpreter (CLI or shell) that parses and executes some 30 system commands with a rich set of options.

User / application software may easily add (up to 100) user specific commands plus an own interpreter. It has to be registered with the weAutSys runtime. Then all user commands will be delegated to it — pre-parsed and prepared.

This CLI or shell may — by user software initialisation — be used with

in any combination and (quasi) parallel in multiple threads.


Files

file  cli.h
 

weAutSys' command line interpreter (CLI)


Data Structures

struct  appCLIreg_t
 The user / application CLI registration type. More...

Defines

#define YIELD_FOR_BUSY_CLI(appThread)
 Wait (yielding) for command execution to end.

Functions

ptfnct_t appCliThreadF (struct cliThr_data_t *cliThread)
 The user / application specific command line interpreter thread.
void initAsCLIthread (struct thr_data_t *thread, FILE *file)
 Initialise a thread (structure) as command line interpreter (CLI) thread.
void registerAppCli (p2ptFunA threadF, char const *const userCommands[])
 Register a user / application command line interpreter (CLI)
uint8_t setCliLine (struct cliThr_data_t *const cliThread, char *const line, uint16_t length)
 Set a command line in the command line interpreter (CLI) thread data.
ptfnct_t sysCliThreadF (struct cliThr_data_t *cliThread)
 The system command line interpreter thread.
void unimplOptionReport (struct cliThr_data_t *cliThread)
 Report the use of an un-implemented option for a command.

Variables

struct appCLIreg_t appCLIreg
 The user / application command line interpreter (CLI) registration.

Define Documentation

#define YIELD_FOR_BUSY_CLI (   appThread)

Wait (yielding) for command execution to end.

This macro waits yielding the main (input, application) thread for all command interpretation to end. It is a helper for a user defined serial input thread.

Parameters:
appThreadpointer to the (complete, type thr_data_t) thread structure
Examples:
main.c.

Function Documentation

void registerAppCli ( p2ptFunA  threadF,
char const *const  userCommands[] 
)

Register a user / application command line interpreter (CLI)

The user CLI thread function and the user commands description will be registered.

To de-register call with at least one parameter NULL.

Parameters:
threadFthe user CLI thread function to register
userCommandsflash array of flash strings of user commands (+ explanations). The (non NULL) array must end with NULL entry.
See also:
appCliThreadF
appInitThreadF
Examples:
main.c.
void initAsCLIthread ( struct thr_data_t thread,
FILE *  file 
)

Initialise a thread (structure) as command line interpreter (CLI) thread.

This function initialises the common (union) part of the structure supplied as a command line interpreter (CLI) thread for the usage of a stream (file) for output and the registered application command line interpreter (CLI) thread function.

The (CLI) thread state will completely be forced to empty initial state with no command and line set.

Parameters:
threadthe thread structure to initialise
fileThe streams to be used for output / reply; NULL is OK when all command may be executed (or even fail) silently
See also:
appCliThreadF
appInitThreadF
Examples:
main.c.
uint8_t setCliLine ( struct cliThr_data_t *const  cliThread,
char *const  line,
uint16_t  length 
)

Set a command line in the command line interpreter (CLI) thread data.

The given line will be set in the cliThread, the command (i.e. the first) token will be determined and the system and user CLI thread state will be forced to empty initial state.

Do not call this function while system or user CLI threads are active.

The line (buffer) is copied to have it as thread state. The copying and extra memory usage is avoided if the parameter line is prepared in and supplied as cliThread->cliThrData.line .

Parameters:
cliThreadpointer to the CLI thread to interpret line
linethe command line (pointer to 0-terminated RAM string)
lengthline's length
Returns:
the command number
See also:
appCliThreadF
appInitThreadF
Examples:
main.c.
ptfnct_t appCliThreadF ( struct cliThr_data_t cliThread)

The user / application specific command line interpreter thread.

If something is to be done in the user / application software for (human readable) command lines (set by setCliLine()) a command line interpreter protothread thread function must be provided therefore.

This has to be done (according to this declaration) in an application specific source file and that thread function has to be registered.

This thread function will be scheduled automatically if and as long as a user command is pending. If an output stream belongs to the calling context the standard streams will have been switched to it space for 40 characters is guaranteed. So this user thread function's implementation will not have to worry about those house keeping tasks.

This thread function will be re-scheduled on a pending user command as long as the command (cliThread->commNumb ) is not set to 0 or this function does not ends or exits.

See also:
initAsCLIthread
appInitThreadF
sysCliThreadF
ptfnct_t sysCliThreadF ( struct cliThr_data_t cliThread)

The system command line interpreter thread.

If a (human readable) command line has been set by setCliLine() this thread might be scheduled (until end / exit) to execute a parsed system command.

If user commands and a user CLI thread (function) are registered this thread will also be scheduled if a user command was parsed. This thread function will delegate all user command execution to the registered user user CLI thread (function)

If no (unambiguous) command was found a report will be made if allowed so in the cliThread structure.

See also:
initAsCLIthread
appInitThreadF
appCliThreadF
Returns:
PT_YIELDED if waiting for conditions that may become automatically true; PT_WAITING if blocked by conditions that other's action may set true; PT_EXITED if stopped by conditions that never will become true (sorry, not all work done and never will; PT_ENDED if ready with all work
void unimplOptionReport ( struct cliThr_data_t cliThread)

Report the use of an un-implemented option for a command.

This is a helper function for the implementation on CLIs (command line processors) only. This function requires stdout connected to CLI streams and enough output space available in the respective stream.

Parameters:
cliThreadpointer to the CLI (and hence the thread busy to execute actual "command -wrongOpt)

Variable Documentation

The user / application command line interpreter (CLI) registration.

Command line interpretation can occur in multiple contexts like UART link, multiple connections to Telnet server etc. And it can occur "simultaneously" in in any of said contexts.

Nevertheless the application CLI (if any) is registered here for once. This structure with this registration may and will be copied to the state / structure of said usages / connections.

It may take some time and (disconnect / connect) events for a changed application CLI registration to take effect. Or, in other words dynamic changes of an application CLI aren't supported yet. It is strongly recommended for the user software to have zero or one application CLI implementation and register it at reset start-up (phase 4).