Diff: CommandProcessor.h

Revision:

10:9e52bd1a4a71

Parent:

8:25581f24f7f9

Child:

11:4a3cd3f2183b

diff -r 41046d2fd8e7 -r 9e52bd1a4a71 CommandProcessor.h
--- 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