The CommandProcessor is the interface to install a run-time menu into an embedded system.
Dependents: A_CANAdapter USB2I2C
CommandProcessor.h
- Committer:
- WiredHome
- Date:
- 2011-04-03
- Revision:
- 7:0f058d664b21
- Parent:
- 6:1a0512faa75d
- Child:
- 8:25581f24f7f9
File content as of revision 7:0f058d664b21:
/// @file CommandProcessor.h defined the interface to the CommandProcessor /// /// @mainpage /// The CommandProcessor is the interface to install a run-time menu into an embedded system. /// This contains the complete interface to the CommandProcessor. /// /// @version 1.0 /// /// @note The CommandProcessor is text-based, because it is intended to interact with a /// user. /// /// The menu is designed to be interactively accessed, perhaps via a console interface /// or a serial port. The actual interface to the user is provided by the application /// during initialization, so it can be connected to a serial port, or it could /// be interface to CAN, telnet, or by some other method. /// /// The CommandProcessor has a few special features: /// \li If the minimum number of characters of a command have been entered, the /// user does not have to type the entire command. (e.g. 'He' will execute /// the command for 'Help', if no other command beings with 'He'). /// \li If the user does not type the entire set of characters, the command /// will be rewritten to the output device with the entire command word. /// \li The user is not permitted to enter an incorrect command (e.g. If 'Help' /// is the only command started with 'Hel', the user cannot enter 'Heu'. /// The CommandProcessor will trap the 'u' and issue a beep). /// \li Simple editing of parameters to commands is permitted with \<bs\> to /// erase incorrect text. /// \li Tab completion of a command is available - so long as the user has /// typed at least the minimum number of unique characters. (e.g. 'He\<tab\>' /// will be replaced with 'Help') /// \li Command cancellation is available - just enter the \<esc\> key and /// the buffer is erased. /// \li The user is not permitted to enter text longer than the defined buffer, /// to avoid buffer overrun and the possible memory damaging results. /// /// The CommandProcessor is designed as a set of C functions, which makes it /// reusable in more systems (as C++ compilers are not always available for /// all micros). /// /// Example: /// @code /// extern "C" { /// #include "CommandProcessor.h" /// } /// /// RUNRESULT_T Who(char *p); /// const CMD_T WhoCmd = { /// "who", /// "Shows who is logged on, or 'who id' for specifics", /// Who, /// visible}; /// /// RUNRESULT_T Who(char *p) /// { /// printf("\r\nwho...\r\n"); /// if (*p) /// printf(" Sorry, no help for [%s]\r\n", p); /// return runok; /// } /// /// int main(int argc, char* argv[]) /// { /// CMDP_T * cp = GetCommandProcessor(); /// cp->Init(7, TRUE, 50, _kbhit, _getch, _putch, printf); /// cp->Add(&WhoCmd); /// /// while (cp->Run()) /// { /// ; /// } /// cp->End(); /// return 0; /// } /// @endcode /// /// @note Copyright © 2011 by Smartware Computing, all rights reserved. /// This program may be used by others as long as this copyright notice /// remains intact. /// @author David Smart /// #ifndef COMMANDPROCESSOR_H #define COMMANDPROCESSOR_H #ifndef TRUE #define TRUE 1 ///< Definition for TRUE, if not already provided #define FALSE 0 ///< Definition for FALSE, if not already provided #endif /// @brief This type determines if menu items are visible to the Help system, or hidden. /// @details This is used in the definition of the menu item. typedef enum { invisible, ///< use this value to have invisible (hidden) a menu in the Help visible ///< use this value to have visible a menu in the Help } VISIBLE_T; ///< This determines if menu items are made visible in the Help system. /// Callbacks that are executed return a value to indicate if the menu /// should remain active typedef enum { runexit, ///< use this return value to cause the menu (perhaps the program) to exit runok ///< use this return value to keep the menu running } RUNRESULT_T; /// Adding items to the menu can succeed, or fail. typedef enum { addfailed, ///< this indicates the menu was not added (usually failure to allocate memory) addok ///< this indicates the menu was successfully added } ADDRESULT_T; /// Initialization can succeed, or fail. typedef enum { initfailed, ///< this indicates that the menu system was not initialized (usually failure to allocate memory) initok ///< this indicates that the menu system was successfully initialized } INITRESULT_T; /// This is the type for the basic callback, when a menu pick is activated. /// /// The callback function is executed when a command is entered on the menu and \<enter\> /// is signaled. If there is any additional text entered on the commandline, it is /// passed to the callback. /// /// example: /// "Test1 ab c 123 567" /// If "Test1" is a valid command, the corresponding function would be called /// passing to that function the string "ab c 123 567". Note that the delimiter space /// was removed. /// /// @param p is a pointer to a character string /// @returns RUNRESULT_T to indicate if the CommandProcessor should continue /// typedef RUNRESULT_T (*MENU_CALLBACK)(char *p); /// This defines the type for a single item to be added to the CommandProcessor menu. /// /// This is defined in the application code, and a pointer to this item is passed to the /// CommandProcessor to add this item to the menu system. /// /// example: /// @code /// const CMD_T WhoCmd = {"who", "Shows who is logged on, or 'who id' for specifics", Who, visible}; /// @endcode /// typedef const struct { char * command; ///< a pointer to the command to match (e.g. 'Help') char * helptext; ///< a pointer to some text to show when user types 'Help' MENU_CALLBACK callback; ///< the function to call when user enters this command VISIBLE_T visible; ///< a flag that determines if this command is visible in Help. } CMD_T; /// This is the CommandProcessor interface from the user application. /// /// The user aquires a handle to this set of functions with the GetCommandProcessor command. /// After this, the user may then initialize the CommandProcessor, add items to the menu, /// cause the CommandProcessor to run periodically, and if need be the application can end /// the CommandProcessor. /// typedef const struct { /// Init is the first function to call to configure the CommandProcessor. /// /// This function has a number of parameters, which make the CommandProcessor quite flexible. /// The user can enable a default menu, which can consist of the following functions. /// Note that when the [bit] is set, that menu item is enabled. /// * [3] Help - which in turn will show all the menu items and their brief descriptions /// * [2] Echo - which adds the echo command help /// * [1] About - just a tiny statement about the CommandProcessor itself /// * [0] Exit - a method to permit a consistent means to exit the CommandProcessor /// /// @param defaultMenu enables various default menu items, based on the bit values. /// @param kbhit is 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. /// @param getch is a user provided function that provides a single character to the CommandProcessor /// @param putch is a user provided function that permits the CommandProcessor to output a character /// @param puts is a user provided function that permits the CommandProcessor to output a string /// to which is automatically appended a \\n /// @param caseinsensitive when TRUE, as the name implies, permits "help" and "HeLp" to function the same /// @param maxCmdLen sets the memory allocation for the command buffer. This should be sized /// to the maximum command, including any passed in text as parameters. /// @returns INITRESULT_T to indicate if the init was successful or failed INITRESULT_T (*Init)( int defaultMenu, int caseinsensitive, int echo, int maxCmdLen, int (*kbhit)(void), int (*getch)(void), int (*putch)(int ch), int (*puts)(const char * s) ); /// Add is called to add an item to the CommandProcessor menu /// /// This passes in a reference to a user provided CMD_T item, which is /// added to the menu system. /// /// @param m is a pointer to the user provided menu /// @returns ADDRESULT_T to indicate if the add was successful or failed /// ADDRESULT_T (*Add)(CMD_T * m); /// Run is the primary runtime entry point for the CommandProcessor. /// /// This function should be called periodically - fast enough not to miss user input. /// This function always returns, so if not character is available for the CommandProcessor /// it will return very fast. If there is a character (as detected by the kbhit callback), /// then it will process that character and determine what to do. It may then execute one /// of the menu functions. In this case, CPU cycles spent are based on the function /// being executed. /// /// @returns RUNRESULT_T to indicate if the CommandProcessor should remain active or if the /// command that was executed is requesting the CommandProcessor to exit. /// RUNRESULT_T (*Run)(void); /// Echo command permits turning the echo on and off /// /// When interactive with the user, it is best to have echo on, so they can see /// the prompt, but if this is simply slaved to another program, then the echo /// might need to be off to best manage the stream. /// /// @param echo turns the echo on (non-zero) or off (zero) /// @returns RUNRESULT_T to indicate if the CommandProcessor should remain active or if the /// command that was executed is requesting the CommandProcessor to exit. /// RUNRESULT_T (*Echo)(int echo); /// End if the function to be called when you want to gracefully end the CommandProcessor. /// /// Calling this function causes the CommandProcessor to free any memory that was previously /// allocated by the Init and Add functions. RUNRESULT_T (*End)(void); ///< Called to shutdown the processor } CMDP_T; /// The CommandProcessor is the interface to install a run-time menu into an embedded system. /// This contains the complete interface to the CommandProcessor. /// /// @version 1.0 /// /// @note The CommandProcessor is text-based, because it is intended to interact with a /// user. /// /// The menu is designed to be interactively accessed, perhaps via a console interface /// or a serial port. The actual interface to the user is provided by the application /// during initialization, so it can be connected to a serial port, or it could /// be interface to CAN, telnet, or by some other method. /// /// The CommandProcessor has a few special features: /// \li If the minimum number of characters of a command have been entered, the /// user does not have to type the entire command. (e.g. 'He' will execute /// the command for 'Help', if no other command beings with 'He'). /// \li If the user does not type the entire set of characters, the command /// will be rewritten to the output device with the entire command word. /// \li The user is not permitted to enter an incorrect command (e.g. If 'Help' /// is the only command started with 'Hel', the user cannot enter 'Heu'. /// The CommandProcessor will trap the 'u' and issue a beep). /// \li Simple editing of parameters to commands is permitted with \<bs\> to /// erase incorrect text. /// \li Tab completion of a command is available - so long as the user has /// typed at least the minimum number of unique characters. (e.g. 'He\<tab\>' /// will be replaced with 'Help') /// \li Command cancellation is available - just enter the \<esc\> key and /// the buffer is erased. /// \li The user is not permitted to enter text longer than the defined buffer, /// to avoid buffer overrun and the possible memory damaging results. /// /// The CommandProcessor is designed as a set of C functions, which makes it /// reusable in more systems (as C++ compilers are not always available for /// all micros). /// /// Example: /// @code /// extern "C" { /// #include "CommandProcessor.h" /// } /// /// RUNRESULT_T Who(char *p); /// const CMD_T WhoCmd = {"who", "Shows who is logged on, or 'who id' for specifics", Who, visible}; /// /// RUNRESULT_T Who(char *p) /// { /// printf("\r\nwho...\r\n"); /// if (*p) /// printf(" Sorry, no help for [%s]\r\n", p); /// return runok; /// } /// /// int main(int argc, char* argv[]) /// { /// CMDP_T * cp = GetCommandProcessor(); /// cp->Init(7, TRUE, 50, _kbhit, _getch, _putch, printf); /// cp->Add(&WhoCmd); /// /// while (cp->Run()) /// { /// ; /// } /// cp->End(); /// return 0; /// } /// @endcode /// /// @note Copyright © 2011 by Smartware Computing, all rights reserved. /// This program may be used by others as long as this copyright notice /// remains intact. /// @author David Smart /// /// GetCommandProcessor is called to get a handle to the CommandProcessor itself. /// /// Call this function to get a handle to the CommandProcessor. After this is done, then /// you can use that handle to activate the CommandProcessor methods. /// /// example: /// @code /// CMDP_T * cp = GetCommandProcessor(); /// cp->Init(7, TRUE, 50, _kbhit, _getch, _putch, printf); /// @endcode /// /// @returns CMDP_T a handle to the CommandProcessor /// #ifdef WIN32 CMDP_T * GetCommandProcessor(void); #else // This is necessary for the mbed - not sure why. extern "C" CMDP_T * GetCommandProcessor(void); #endif int mystrnicmp(const char *l, const char *r, size_t n); #endif // COMMANDPROCESSOR_H