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 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.
appThread | pointer to the (complete, type thr_data_t) thread structure |
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.
threadF | the user CLI thread function to register |
userCommands | flash array of flash strings of user commands (+ explanations). The (non NULL) array must end with NULL entry. |
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.
thread | the thread structure to initialise |
file | The streams to be used for output / reply; NULL is OK when all command may be executed (or even fail) silently |
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
.
cliThread | pointer to the CLI thread to interpret line |
line | the command line (pointer to 0-terminated RAM string) |
length | line's length |
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.
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.
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.
cliThread | pointer to the CLI (and hence the thread busy to execute actual "command -wrongOpt) |
struct appCLIreg_t appCLIreg |
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).