David Smart / CommandProcessor

The CommandProcessor is the interface to install a run-time menu into an embedded system.

Dependents:   A_CANAdapter USB2I2C

Embed: (wiki syntax)

« Back to documentation index

CommandProcessor.c File Reference
Typedefs | Functions

CommandProcessor.c File Reference

is a simple interface to an interactive command set of user defined commands. More...

Go to the source code of this file.

Typedefs

typedef struct CMDLINK_T CMDLINK_T
 This holds the single linked list of commands.

Functions

static INITRESULT_T CommandProcessor_Init (CMD_T(*SignOnBanner), CONFIG_T config, int maxCmdLen, int numInHistory, int(*kbhit)(void), int(*getch)(void), int(*putch)(int ch), int(*puts)(const char *s))
 Init is the first function to call to configure the CommandProcessor.
static ADDRESULT_T CommandProcessor_Add (CMD_T *menu)
 Add a command to the CommandProcessor.
static RUNRESULT_T CommandProcessor_Run (void)
 Run the CommandProcessor.
static RUNRESULT_T CommandProcessor_End (void)
 End the CommandProcessor by freeing all the memory that was allocated.
static int myisprint (int c)
 myisprint exists because not all compiler libraries have this function
static void mystrcat (char *dst, char *src)
 mystrcat exists because not all compiler libraries have this function
static char mytolower (char a)
 mytolower exists because not all compiler libraries have this function
static int mystrnicmp (const char *l, const char *r, size_t n)
 mystrnicmp exists because not all compiler libraries have this function.
static RUNRESULT_T History (char *p)
 History shows the command history.
static RUNRESULT_T Echo (char *p)
 Turns command prompt echo on and off.
CMDP_T * GetCommandProcessor (void)
 Gets a handle to the CommandProcessor.
static int CommandMatches (char *buffer, int exec, CMD_T **menu, char **params)
 CommandMatches is the function that determines if the user is entering a valid command.

Detailed Description

is a simple interface to an interactive command set of user defined commands.

With this, you can create functions that are exposed to a console interface. Each command may have 0 or more parameters. Typing the command, or at least the set of characters that make it unique from all other commands is enough to activate the command.

Even though it is a c interface, it is somewhat object oriented.

Note:
Copyright 2011 by Smartware Computing, all rights reserved. Individuals may use this application for evaluation or non-commercial purposes. Within this restriction, changes may be made to this application as long as this copyright notice is retained. The user shall make clear that their work is a derived work, and not the original. Users of this application and sources accept this application "as is" and shall hold harmless Smartware Computing, for any undesired results while using this application - whether real or imagined.
Author:
David Smart, Smartware Computing

Definition in file CommandProcessor.c.

Typedef Documentation

typedef struct CMDLINK_T CMDLINK_T

This holds the single linked list of commands. 

/// +-- Head->next
/// v
/// +-- p       +-- n
/// v           v
/// |menu|-------------------------------->|"Command"  |
/// |next|->0   |menu|---->|"Help"         |"Help"     |
///             |next|->0  |"..."          |*(callback)|
///                        |*(callback)    |visible    |
///                        |visible
///

Function Documentation

static int CommandMatches ( char *  buffer,
int  exec,
CMD_T **  menu,
char **  params 
) [static]

CommandMatches is the function that determines if the user is entering a valid command.

This function gets called whenever the user types a printable character or when they press <enter>. The buffer of user input is evaluated to determine if the command is legitimate. It also determines if they want to execute the command, or simply evaluate it. Finally, it identifies writes to user provided pointers, the menu item that matches and a pointer to any parameters that the user entered.

Parameters:
bufferis the buffer that the user has entered commands into
execindicates the intention to execute the command, if found
menuis a pointer to a pointer to a menu structure, which is updated based on the command
paramsis a pointer to a pointer to the user entered parameters
Returns:
the number of menu picks that match the user entered command

Definition at line 239 of file CommandProcessor.c.

ADDRESULT_T CommandProcessor_Add ( CMD_T *  menu ) [static]

Add a command to the CommandProcessor.

This adds a command to the CommandProcessor. A command has several components to it, including the command name, a brief description, the function to activate when the command is entered, and a flag indicating if the command should show up in the built-in help.

Parameters:
menuis the menu to add to the CommandProcessor
Returns:
addok if the command was added
addfail if the command could not be added (failure to allocate memory for the linked list)

Definition at line 381 of file CommandProcessor.c.

RUNRESULT_T CommandProcessor_End ( void   ) [static]

End the CommandProcessor by freeing all the memory that was allocated.

Returns:
runok

Definition at line 642 of file CommandProcessor.c.

INITRESULT_T CommandProcessor_Init ( CMD_T *  SignOnBanner,
CONFIG_T  config,
int  maxCmdLen,
int  numInHistory,
int(*)(void)  kbhit,
int(*)(void)  getch,
int(*)(int ch)  putch,
int(*)(const char *s)  puts 
) [static]

Init is the first function to call to configure the CommandProcessor.

This function has a number of parameters, which make the CommandProcessor quite flexible.

Parameters:
SignOnBannerfunction, which is used as a signon banner
configenables various default menu items, based on the bit values, combine the following:

  • CFG_ENABLE_TERMINATE - enables the Exit command
  • CFG_ENABLE_SYSTEM - enables system commands Echo, Help, etc.
  • CFG_ECHO_ON - initialize with echo on
  • CFG_CASE_INSENSITIVE - Command Parser is case insensitive
maxCmdLensizes the buffer, and is the maximum number of characters in a single command, including all command arguments
kbhitis a user provided function to detect if a character is available for the CommandProcessor, and when using standard io, you can typically use kbhit, or _kbhit as your system provides.
getchis a user provided function that provides a single character to the CommandProcessor
putchis a user provided function that permits the CommandProcessor to output a character
putsis a user provided function that permits the CommandProcessor to output a string to which is automatically appended a \n
Returns:
INITRESULT_T to indicate if the init was successful or failed

Definition at line 326 of file CommandProcessor.c.

RUNRESULT_T CommandProcessor_Run ( void   ) [static]

Run the CommandProcessor.

This will peek to see if there is a keystroke ready. It will pull that into a buffer if it is part of a valid command in the command set. You may then enter arguments to the command to be run.

Primitive editing is permitted with <bs>.

When you press <enter> it will evaluate the command and execute the command passing it the parameter string.

Returns:
runok if the command that was run allows continuation of the CommandProcessor
runfail if the command that was run is asking the CommandProcessor to exit

Definition at line 609 of file CommandProcessor.c.

static RUNRESULT_T Echo ( char *  p ) [static]

Turns command prompt echo on and off.

This command is used to turn the command prompt on and off. When running in an interactive mode, it is best to have this one. When driven by another program, off may be the best choice.

This command also displays the current state of the echo mode.

Parameters:
pis a pointer to a string "on" | "1" | "off" | "0"
Returns:
runok

Definition at line 164 of file CommandProcessor.c.

CMDP_T * GetCommandProcessor ( void   )

Gets a handle to the CommandProcessor.

The CommandProcessor is the interface to install a run-time menu into an embedded system.

This returns a handle to the CommandProcessor, which then permits access to the CommandProcessor functions.

Returns:
handle to the CommandProcessor

Definition at line 129 of file CommandProcessor.c.

static RUNRESULT_T History ( char *  p ) [static]

History shows the command history.

Parameters:
pis a pointer to a string that is ignored
Returns:
runok

Definition at line 139 of file CommandProcessor.c.

static int myisprint ( int  c ) [static]

myisprint exists because not all compiler libraries have this function

This function tests a character to see if it is printable (a member of the standard ASCII set).

Parameters:
cis the character to test
Returns:
TRUE if the character is printable
FALSE if the character is not printable

Definition at line 732 of file CommandProcessor.c.

static void mystrcat ( char *  dst,
char *  src 
) [static]

mystrcat exists because not all compiler libraries have this function

This function concatinates one string onto another. It is generally considered unsafe, because of the potential for buffer overflow. Some libraries offer a strcat_s as the safe version, and others may have _strcat. Because this is needed only internal to the CommandProcessor, this version was created.

Parameters:
dstis a pointer to the destination string
srcis a pointer to the source string
Returns:
nothing

Definition at line 715 of file CommandProcessor.c.

static int mystrnicmp ( const char *  l,
const char *  r,
size_t  n 
) [static]

mystrnicmp exists because not all compiler libraries have this function.

Some have strnicmp, others _strnicmp, and others have C++ methods, which is outside the scope of this C-portable set of functions.

Parameters:
lis a pointer to the string on the left
ris a pointer to the string on the right
nis the number of characters to compare
Returns:
-1 if l < r
0 if l == r
+1 if l > r

Definition at line 688 of file CommandProcessor.c.

static char mytolower ( char  a ) [static]

mytolower exists because not all compiler libraries have this function

This takes a character and if it is upper-case, it converts it to lower-case and returns it.

Parameters:
ais the character to convert
Returns:
the lower case equivalent to a

Definition at line 669 of file CommandProcessor.c.

Generated on Wed Jul 13 2022 14:17:53 by  doxygen 1.7.2