The CommandProcessor is the interface to install a run-time menu into an embedded system.
Dependents: A_CANAdapter USB2I2C
Diff: CommandProcessor.h
- Revision:
- 10:9e52bd1a4a71
- Parent:
- 8:25581f24f7f9
- Child:
- 11:4a3cd3f2183b
--- a/CommandProcessor.h Sun Apr 10 21:04:49 2011 +0000 +++ b/CommandProcessor.h Sat Apr 23 14:04:19 2011 +0000 @@ -1,10 +1,11 @@ /// @file CommandProcessor.h defined the interface to the CommandProcessor /// -/// @mainpage +/// @mainpage The CommandProcessor +/// /// 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 +/// @version 1.01 /// /// @note The CommandProcessor is text-based, because it is intended to interact with a /// user. @@ -43,13 +44,23 @@ /// #include "CommandProcessor.h" /// } /// +/// RUNRESULT_T SignOnBanner(char *p); +/// const CMD_T SignOnBannerCmd = { +/// "About", "About this program ('About ?' for more details)", +/// SignOnBanner, invisible}; +/// /// RUNRESULT_T Who(char *p); /// const CMD_T WhoCmd = { -/// "who", -/// "Shows who is logged on, or 'who id' for specifics", -/// Who, -/// visible}; -/// +/// "who", "Shows who is logged on, or 'who id' for specifics", +/// Who, visible}; +/// +/// RUNRESULT_T SignOnBanner(char *p) +/// { +/// puts("\r\nThis great program was built " __DATE__ " " __TIME__ "."); +/// if (*p == '?') +/// puts("\r\nMore details shown here.\r\n"); +/// return runok; +/// } /// RUNRESULT_T Who(char *p) /// { /// printf("\r\nwho...\r\n"); @@ -61,7 +72,9 @@ /// int main(int argc, char* argv[]) /// { /// CMDP_T * cp = GetCommandProcessor(); -/// cp->Init(7, TRUE, 50, _kbhit, _getch, _putch, printf); +/// cp->Init(&SignOnBanner, +/// CFG_ENABLE_TERMINATE | CFG_ENABLE_SYSTEM, +/// 50, _kbhit, _getch, _putch, printf); /// cp->Add(&WhoCmd); /// /// while (cp->Run()) @@ -78,6 +91,17 @@ /// remains intact. /// @author David Smart /// +/// @note +/// History +/// v1.01 22 April 2011 +/// \li Moving 'About' content into the extended help, +/// to free 'About' for application code that uses this library. +/// \li Altered the _init api to permit a signon banner of the users choice +/// and a config parameter for other features. +/// +/// v1.0 March 2011 +/// \li Initial version +/// #ifndef COMMANDPROCESSOR_H #define COMMANDPROCESSOR_H @@ -116,6 +140,15 @@ initok ///< this indicates that the menu system was successfully initialized } INITRESULT_T; +/// Configuration options +typedef unsigned long CONFIG_T; + +#define CFG_ENABLE_TERMINATE 0x0001 +#define CFG_ENABLE_SYSTEM 0x0002 +#define CFG_ECHO_ON 0x2000 +#define CFG_CASE_INSENSITIVE 0x4000 + + /// 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\> @@ -126,10 +159,10 @@ /// "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. +/// was removed. /// -/// @param p is a pointer to a character string -/// @returns RUNRESULT_T to indicate if the CommandProcessor should continue +/// @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); @@ -139,7 +172,7 @@ /// CommandProcessor to add this item to the menu system. /// /// example: -/// @code +/// @code /// const CMD_T WhoCmd = {"who", "Shows who is logged on, or 'who id' for specifics", Who, visible}; /// @endcode /// @@ -153,7 +186,7 @@ /// This is the CommandProcessor interface from the user application. /// -/// The user aquires a handle to this set of functions with the GetCommandProcessor command. +/// 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. @@ -163,28 +196,26 @@ /// 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 + /// @param SignOnBanner function, which is used as a signon banner + /// @param config enables various default menu items, based on the bit values, combine the following: + /// \li CFG_ENABLE_TERMINATE - enables the Exit command + /// \li CFG_ENABLE_SYSTEM - enables system commands Echo, Help, etc. + /// \li CFG_ECHO_ON - initialize with echo on + /// \li CFG_CASE_INSENSITIVE - Command Parser is case insensitive + /// @param maxCmdLen sizes the buffer, and is the maximum number of characters in a single + /// command, including all command arguments + /// @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, + CMD_T *SignOnBanner, + CONFIG_T config, int maxCmdLen, int (*kbhit)(void), int (*getch)(void), @@ -278,9 +309,17 @@ /// #include "CommandProcessor.h" /// } /// +/// RUNRESULT_T About(char *p); +/// const CMD_T AboutCmd = {"About", "About this program", About, invisible}; /// RUNRESULT_T Who(char *p); /// const CMD_T WhoCmd = {"who", "Shows who is logged on, or 'who id' for specifics", Who, visible}; /// +/// RUNRESULT_T About(char *p) +/// { +/// (void)p; +/// puts("\r\nThis program does really good things for the user.\r\n"); +/// } +/// /// RUNRESULT_T Who(char *p) /// { /// printf("\r\nwho...\r\n"); @@ -292,7 +331,9 @@ /// int main(int argc, char* argv[]) /// { /// CMDP_T * cp = GetCommandProcessor(); -/// cp->Init(7, TRUE, 50, _kbhit, _getch, _putch, printf); +/// cp->Init(AboutCmd, CFG_ENABLE_TERMINATE | CFG_ENABLE_SYSTEM | CFG_SIGNON_BANNER, +/// 50, +/// _kbhit, _getch, _putch, printf); /// cp->Add(&WhoCmd); /// /// while (cp->Run()) @@ -317,7 +358,9 @@ /// example: /// @code /// CMDP_T * cp = GetCommandProcessor(); -/// cp->Init(7, TRUE, 50, _kbhit, _getch, _putch, printf); +/// cp->Init(AboutCmd, CFG_ENABLE_TERMINATE | CFG_ENABLE_SYSTEM | CFG_SIGNON_BANNER, +/// 50, +/// _kbhit, _getch, _putch, printf); /// @endcode /// /// @returns CMDP_T a handle to the CommandProcessor