The CommandProcessor is the interface to install a run-time menu into an embedded system.
Dependents: A_CANAdapter USB2I2C
CommandProcessor.h@11:4a3cd3f2183b, 2011-04-23 (annotated)
- Committer:
- WiredHome
- Date:
- Sat Apr 23 14:15:10 2011 +0000
- Revision:
- 11:4a3cd3f2183b
- Parent:
- 10:9e52bd1a4a71
- Child:
- 12:a8c56bf811b9
Minor documentation update
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
WiredHome | 0:198f53da1bc8 | 1 | /// @file CommandProcessor.h defined the interface to the CommandProcessor |
WiredHome | 0:198f53da1bc8 | 2 | /// |
WiredHome | 10:9e52bd1a4a71 | 3 | /// @mainpage The CommandProcessor |
WiredHome | 10:9e52bd1a4a71 | 4 | /// |
WiredHome | 0:198f53da1bc8 | 5 | /// The CommandProcessor is the interface to install a run-time menu into an embedded system. |
WiredHome | 0:198f53da1bc8 | 6 | /// This contains the complete interface to the CommandProcessor. |
WiredHome | 0:198f53da1bc8 | 7 | /// |
WiredHome | 10:9e52bd1a4a71 | 8 | /// @version 1.01 |
WiredHome | 0:198f53da1bc8 | 9 | /// |
WiredHome | 0:198f53da1bc8 | 10 | /// @note The CommandProcessor is text-based, because it is intended to interact with a |
WiredHome | 0:198f53da1bc8 | 11 | /// user. |
WiredHome | 0:198f53da1bc8 | 12 | /// |
WiredHome | 0:198f53da1bc8 | 13 | /// The menu is designed to be interactively accessed, perhaps via a console interface |
WiredHome | 0:198f53da1bc8 | 14 | /// or a serial port. The actual interface to the user is provided by the application |
WiredHome | 0:198f53da1bc8 | 15 | /// during initialization, so it can be connected to a serial port, or it could |
WiredHome | 0:198f53da1bc8 | 16 | /// be interface to CAN, telnet, or by some other method. |
WiredHome | 0:198f53da1bc8 | 17 | /// |
WiredHome | 0:198f53da1bc8 | 18 | /// The CommandProcessor has a few special features: |
WiredHome | 0:198f53da1bc8 | 19 | /// \li If the minimum number of characters of a command have been entered, the |
WiredHome | 0:198f53da1bc8 | 20 | /// user does not have to type the entire command. (e.g. 'He' will execute |
WiredHome | 0:198f53da1bc8 | 21 | /// the command for 'Help', if no other command beings with 'He'). |
WiredHome | 0:198f53da1bc8 | 22 | /// \li If the user does not type the entire set of characters, the command |
WiredHome | 0:198f53da1bc8 | 23 | /// will be rewritten to the output device with the entire command word. |
WiredHome | 0:198f53da1bc8 | 24 | /// \li The user is not permitted to enter an incorrect command (e.g. If 'Help' |
WiredHome | 0:198f53da1bc8 | 25 | /// is the only command started with 'Hel', the user cannot enter 'Heu'. |
WiredHome | 0:198f53da1bc8 | 26 | /// The CommandProcessor will trap the 'u' and issue a beep). |
WiredHome | 0:198f53da1bc8 | 27 | /// \li Simple editing of parameters to commands is permitted with \<bs\> to |
WiredHome | 0:198f53da1bc8 | 28 | /// erase incorrect text. |
WiredHome | 0:198f53da1bc8 | 29 | /// \li Tab completion of a command is available - so long as the user has |
WiredHome | 4:283e35536097 | 30 | /// typed at least the minimum number of unique characters. (e.g. 'He\<tab\>' |
WiredHome | 0:198f53da1bc8 | 31 | /// will be replaced with 'Help') |
WiredHome | 4:283e35536097 | 32 | /// \li Command cancellation is available - just enter the \<esc\> key and |
WiredHome | 0:198f53da1bc8 | 33 | /// the buffer is erased. |
WiredHome | 0:198f53da1bc8 | 34 | /// \li The user is not permitted to enter text longer than the defined buffer, |
WiredHome | 0:198f53da1bc8 | 35 | /// to avoid buffer overrun and the possible memory damaging results. |
WiredHome | 0:198f53da1bc8 | 36 | /// |
WiredHome | 0:198f53da1bc8 | 37 | /// The CommandProcessor is designed as a set of C functions, which makes it |
WiredHome | 0:198f53da1bc8 | 38 | /// reusable in more systems (as C++ compilers are not always available for |
WiredHome | 0:198f53da1bc8 | 39 | /// all micros). |
WiredHome | 0:198f53da1bc8 | 40 | /// |
WiredHome | 0:198f53da1bc8 | 41 | /// Example: |
WiredHome | 0:198f53da1bc8 | 42 | /// @code |
WiredHome | 0:198f53da1bc8 | 43 | /// extern "C" { |
WiredHome | 0:198f53da1bc8 | 44 | /// #include "CommandProcessor.h" |
WiredHome | 0:198f53da1bc8 | 45 | /// } |
WiredHome | 0:198f53da1bc8 | 46 | /// |
WiredHome | 10:9e52bd1a4a71 | 47 | /// RUNRESULT_T SignOnBanner(char *p); |
WiredHome | 10:9e52bd1a4a71 | 48 | /// const CMD_T SignOnBannerCmd = { |
WiredHome | 10:9e52bd1a4a71 | 49 | /// "About", "About this program ('About ?' for more details)", |
WiredHome | 10:9e52bd1a4a71 | 50 | /// SignOnBanner, invisible}; |
WiredHome | 10:9e52bd1a4a71 | 51 | /// |
WiredHome | 0:198f53da1bc8 | 52 | /// RUNRESULT_T Who(char *p); |
WiredHome | 7:0f058d664b21 | 53 | /// const CMD_T WhoCmd = { |
WiredHome | 10:9e52bd1a4a71 | 54 | /// "who", "Shows who is logged on, or 'who id' for specifics", |
WiredHome | 10:9e52bd1a4a71 | 55 | /// Who, visible}; |
WiredHome | 10:9e52bd1a4a71 | 56 | /// |
WiredHome | 10:9e52bd1a4a71 | 57 | /// RUNRESULT_T SignOnBanner(char *p) |
WiredHome | 10:9e52bd1a4a71 | 58 | /// { |
WiredHome | 10:9e52bd1a4a71 | 59 | /// puts("\r\nThis great program was built " __DATE__ " " __TIME__ "."); |
WiredHome | 10:9e52bd1a4a71 | 60 | /// if (*p == '?') |
WiredHome | 10:9e52bd1a4a71 | 61 | /// puts("\r\nMore details shown here.\r\n"); |
WiredHome | 10:9e52bd1a4a71 | 62 | /// return runok; |
WiredHome | 10:9e52bd1a4a71 | 63 | /// } |
WiredHome | 0:198f53da1bc8 | 64 | /// RUNRESULT_T Who(char *p) |
WiredHome | 0:198f53da1bc8 | 65 | /// { |
WiredHome | 4:283e35536097 | 66 | /// printf("\r\nwho...\r\n"); |
WiredHome | 4:283e35536097 | 67 | /// if (*p) |
WiredHome | 4:283e35536097 | 68 | /// printf(" Sorry, no help for [%s]\r\n", p); |
WiredHome | 4:283e35536097 | 69 | /// return runok; |
WiredHome | 0:198f53da1bc8 | 70 | /// } |
WiredHome | 0:198f53da1bc8 | 71 | /// |
WiredHome | 0:198f53da1bc8 | 72 | /// int main(int argc, char* argv[]) |
WiredHome | 0:198f53da1bc8 | 73 | /// { |
WiredHome | 4:283e35536097 | 74 | /// CMDP_T * cp = GetCommandProcessor(); |
WiredHome | 10:9e52bd1a4a71 | 75 | /// cp->Init(&SignOnBanner, |
WiredHome | 10:9e52bd1a4a71 | 76 | /// CFG_ENABLE_TERMINATE | CFG_ENABLE_SYSTEM, |
WiredHome | 10:9e52bd1a4a71 | 77 | /// 50, _kbhit, _getch, _putch, printf); |
WiredHome | 4:283e35536097 | 78 | /// cp->Add(&WhoCmd); |
WiredHome | 0:198f53da1bc8 | 79 | /// |
WiredHome | 4:283e35536097 | 80 | /// while (cp->Run()) |
WiredHome | 4:283e35536097 | 81 | /// { |
WiredHome | 4:283e35536097 | 82 | /// ; |
WiredHome | 4:283e35536097 | 83 | /// } |
WiredHome | 4:283e35536097 | 84 | /// cp->End(); |
WiredHome | 4:283e35536097 | 85 | /// return 0; |
WiredHome | 0:198f53da1bc8 | 86 | /// } |
WiredHome | 0:198f53da1bc8 | 87 | /// @endcode |
WiredHome | 0:198f53da1bc8 | 88 | /// |
WiredHome | 0:198f53da1bc8 | 89 | /// @note Copyright © 2011 by Smartware Computing, all rights reserved. |
WiredHome | 0:198f53da1bc8 | 90 | /// This program may be used by others as long as this copyright notice |
WiredHome | 0:198f53da1bc8 | 91 | /// remains intact. |
WiredHome | 0:198f53da1bc8 | 92 | /// @author David Smart |
WiredHome | 0:198f53da1bc8 | 93 | /// |
WiredHome | 10:9e52bd1a4a71 | 94 | /// @note |
WiredHome | 10:9e52bd1a4a71 | 95 | /// History |
WiredHome | 10:9e52bd1a4a71 | 96 | /// v1.01 22 April 2011 |
WiredHome | 10:9e52bd1a4a71 | 97 | /// \li Moving 'About' content into the extended help, |
WiredHome | 10:9e52bd1a4a71 | 98 | /// to free 'About' for application code that uses this library. |
WiredHome | 10:9e52bd1a4a71 | 99 | /// \li Altered the _init api to permit a signon banner of the users choice |
WiredHome | 10:9e52bd1a4a71 | 100 | /// and a config parameter for other features. |
WiredHome | 10:9e52bd1a4a71 | 101 | /// |
WiredHome | 10:9e52bd1a4a71 | 102 | /// v1.0 March 2011 |
WiredHome | 10:9e52bd1a4a71 | 103 | /// \li Initial version |
WiredHome | 10:9e52bd1a4a71 | 104 | /// |
WiredHome | 0:198f53da1bc8 | 105 | #ifndef COMMANDPROCESSOR_H |
WiredHome | 0:198f53da1bc8 | 106 | #define COMMANDPROCESSOR_H |
WiredHome | 0:198f53da1bc8 | 107 | |
WiredHome | 0:198f53da1bc8 | 108 | #ifndef TRUE |
WiredHome | 4:283e35536097 | 109 | #define TRUE 1 ///< Definition for TRUE, if not already provided |
WiredHome | 4:283e35536097 | 110 | #define FALSE 0 ///< Definition for FALSE, if not already provided |
WiredHome | 0:198f53da1bc8 | 111 | #endif |
WiredHome | 0:198f53da1bc8 | 112 | |
WiredHome | 0:198f53da1bc8 | 113 | /// @brief This type determines if menu items are visible to the Help system, or hidden. |
WiredHome | 0:198f53da1bc8 | 114 | /// @details This is used in the definition of the menu item. |
WiredHome | 0:198f53da1bc8 | 115 | typedef enum |
WiredHome | 0:198f53da1bc8 | 116 | { |
WiredHome | 4:283e35536097 | 117 | invisible, ///< use this value to have invisible (hidden) a menu in the Help |
WiredHome | 4:283e35536097 | 118 | visible ///< use this value to have visible a menu in the Help |
WiredHome | 4:283e35536097 | 119 | } VISIBLE_T; ///< This determines if menu items are made visible in the Help system. |
WiredHome | 0:198f53da1bc8 | 120 | |
WiredHome | 0:198f53da1bc8 | 121 | /// Callbacks that are executed return a value to indicate if the menu |
WiredHome | 0:198f53da1bc8 | 122 | /// should remain active |
WiredHome | 0:198f53da1bc8 | 123 | typedef enum |
WiredHome | 0:198f53da1bc8 | 124 | { |
WiredHome | 4:283e35536097 | 125 | runexit, ///< use this return value to cause the menu (perhaps the program) to exit |
WiredHome | 4:283e35536097 | 126 | runok ///< use this return value to keep the menu running |
WiredHome | 0:198f53da1bc8 | 127 | } RUNRESULT_T; |
WiredHome | 0:198f53da1bc8 | 128 | |
WiredHome | 0:198f53da1bc8 | 129 | /// Adding items to the menu can succeed, or fail. |
WiredHome | 0:198f53da1bc8 | 130 | typedef enum |
WiredHome | 0:198f53da1bc8 | 131 | { |
WiredHome | 4:283e35536097 | 132 | addfailed, ///< this indicates the menu was not added (usually failure to allocate memory) |
WiredHome | 4:283e35536097 | 133 | addok ///< this indicates the menu was successfully added |
WiredHome | 0:198f53da1bc8 | 134 | } ADDRESULT_T; |
WiredHome | 0:198f53da1bc8 | 135 | |
WiredHome | 0:198f53da1bc8 | 136 | /// Initialization can succeed, or fail. |
WiredHome | 0:198f53da1bc8 | 137 | typedef enum |
WiredHome | 0:198f53da1bc8 | 138 | { |
WiredHome | 4:283e35536097 | 139 | initfailed, ///< this indicates that the menu system was not initialized (usually failure to allocate memory) |
WiredHome | 4:283e35536097 | 140 | initok ///< this indicates that the menu system was successfully initialized |
WiredHome | 0:198f53da1bc8 | 141 | } INITRESULT_T; |
WiredHome | 0:198f53da1bc8 | 142 | |
WiredHome | 11:4a3cd3f2183b | 143 | /// Configuration options to control startup and some runtime behavior |
WiredHome | 11:4a3cd3f2183b | 144 | /// |
WiredHome | 11:4a3cd3f2183b | 145 | /// Permissible values are created by combining |
WiredHome | 11:4a3cd3f2183b | 146 | /// \li CFG_ENABLE_TERMINATE |
WiredHome | 11:4a3cd3f2183b | 147 | /// \li CFG_ENABLE_SYSTEM |
WiredHome | 11:4a3cd3f2183b | 148 | /// \li CFG_ECHO_ON |
WiredHome | 11:4a3cd3f2183b | 149 | /// \li CFG_CASE_INSENSITIVE |
WiredHome | 10:9e52bd1a4a71 | 150 | typedef unsigned long CONFIG_T; |
WiredHome | 10:9e52bd1a4a71 | 151 | |
WiredHome | 11:4a3cd3f2183b | 152 | #define CFG_ENABLE_TERMINATE 0x0001 ///<- Enable the exit option |
WiredHome | 11:4a3cd3f2183b | 153 | #define CFG_ENABLE_SYSTEM 0x0002 ///<- Enable various system options (help, etc) |
WiredHome | 11:4a3cd3f2183b | 154 | #define CFG_ECHO_ON 0x2000 ///<- Initialize with command prompt Echo on |
WiredHome | 11:4a3cd3f2183b | 155 | #define CFG_CASE_INSENSITIVE 0x4000 ///<- Enable case insensitive command entry |
WiredHome | 10:9e52bd1a4a71 | 156 | |
WiredHome | 10:9e52bd1a4a71 | 157 | |
WiredHome | 0:198f53da1bc8 | 158 | /// This is the type for the basic callback, when a menu pick is activated. |
WiredHome | 0:198f53da1bc8 | 159 | /// |
WiredHome | 0:198f53da1bc8 | 160 | /// The callback function is executed when a command is entered on the menu and \<enter\> |
WiredHome | 0:198f53da1bc8 | 161 | /// is signaled. If there is any additional text entered on the commandline, it is |
WiredHome | 0:198f53da1bc8 | 162 | /// passed to the callback. |
WiredHome | 0:198f53da1bc8 | 163 | /// |
WiredHome | 0:198f53da1bc8 | 164 | /// example: |
WiredHome | 4:283e35536097 | 165 | /// "Test1 ab c 123 567" |
WiredHome | 0:198f53da1bc8 | 166 | /// If "Test1" is a valid command, the corresponding function would be called |
WiredHome | 4:283e35536097 | 167 | /// passing to that function the string "ab c 123 567". Note that the delimiter space |
WiredHome | 10:9e52bd1a4a71 | 168 | /// was removed. |
WiredHome | 0:198f53da1bc8 | 169 | /// |
WiredHome | 10:9e52bd1a4a71 | 170 | /// @param p is a pointer to a character string |
WiredHome | 10:9e52bd1a4a71 | 171 | /// @returns RUNRESULT_T to indicate if the CommandProcessor should continue |
WiredHome | 0:198f53da1bc8 | 172 | /// |
WiredHome | 0:198f53da1bc8 | 173 | typedef RUNRESULT_T (*MENU_CALLBACK)(char *p); |
WiredHome | 0:198f53da1bc8 | 174 | |
WiredHome | 0:198f53da1bc8 | 175 | /// This defines the type for a single item to be added to the CommandProcessor menu. |
WiredHome | 0:198f53da1bc8 | 176 | /// |
WiredHome | 0:198f53da1bc8 | 177 | /// This is defined in the application code, and a pointer to this item is passed to the |
WiredHome | 0:198f53da1bc8 | 178 | /// CommandProcessor to add this item to the menu system. |
WiredHome | 0:198f53da1bc8 | 179 | /// |
WiredHome | 0:198f53da1bc8 | 180 | /// example: |
WiredHome | 10:9e52bd1a4a71 | 181 | /// @code |
WiredHome | 0:198f53da1bc8 | 182 | /// const CMD_T WhoCmd = {"who", "Shows who is logged on, or 'who id' for specifics", Who, visible}; |
WiredHome | 0:198f53da1bc8 | 183 | /// @endcode |
WiredHome | 0:198f53da1bc8 | 184 | /// |
WiredHome | 0:198f53da1bc8 | 185 | typedef const struct |
WiredHome | 0:198f53da1bc8 | 186 | { |
WiredHome | 4:283e35536097 | 187 | char * command; ///< a pointer to the command to match (e.g. 'Help') |
WiredHome | 4:283e35536097 | 188 | char * helptext; ///< a pointer to some text to show when user types 'Help' |
WiredHome | 4:283e35536097 | 189 | MENU_CALLBACK callback; ///< the function to call when user enters this command |
WiredHome | 4:283e35536097 | 190 | VISIBLE_T visible; ///< a flag that determines if this command is visible in Help. |
WiredHome | 0:198f53da1bc8 | 191 | } CMD_T; |
WiredHome | 0:198f53da1bc8 | 192 | |
WiredHome | 0:198f53da1bc8 | 193 | /// This is the CommandProcessor interface from the user application. |
WiredHome | 0:198f53da1bc8 | 194 | /// |
WiredHome | 10:9e52bd1a4a71 | 195 | /// The user aquires a handle to this set of functions with the GetCommandProcessor command. |
WiredHome | 0:198f53da1bc8 | 196 | /// After this, the user may then initialize the CommandProcessor, add items to the menu, |
WiredHome | 0:198f53da1bc8 | 197 | /// cause the CommandProcessor to run periodically, and if need be the application can end |
WiredHome | 0:198f53da1bc8 | 198 | /// the CommandProcessor. |
WiredHome | 0:198f53da1bc8 | 199 | /// |
WiredHome | 0:198f53da1bc8 | 200 | typedef const struct |
WiredHome | 0:198f53da1bc8 | 201 | { |
WiredHome | 4:283e35536097 | 202 | /// Init is the first function to call to configure the CommandProcessor. |
WiredHome | 4:283e35536097 | 203 | /// |
WiredHome | 4:283e35536097 | 204 | /// This function has a number of parameters, which make the CommandProcessor quite flexible. |
WiredHome | 4:283e35536097 | 205 | /// |
WiredHome | 10:9e52bd1a4a71 | 206 | /// @param SignOnBanner function, which is used as a signon banner |
WiredHome | 10:9e52bd1a4a71 | 207 | /// @param config enables various default menu items, based on the bit values, combine the following: |
WiredHome | 10:9e52bd1a4a71 | 208 | /// \li CFG_ENABLE_TERMINATE - enables the Exit command |
WiredHome | 10:9e52bd1a4a71 | 209 | /// \li CFG_ENABLE_SYSTEM - enables system commands Echo, Help, etc. |
WiredHome | 10:9e52bd1a4a71 | 210 | /// \li CFG_ECHO_ON - initialize with echo on |
WiredHome | 10:9e52bd1a4a71 | 211 | /// \li CFG_CASE_INSENSITIVE - Command Parser is case insensitive |
WiredHome | 10:9e52bd1a4a71 | 212 | /// @param maxCmdLen sizes the buffer, and is the maximum number of characters in a single |
WiredHome | 10:9e52bd1a4a71 | 213 | /// command, including all command arguments |
WiredHome | 10:9e52bd1a4a71 | 214 | /// @param kbhit is a user provided function to detect if a character is available for the CommandProcessor, |
WiredHome | 10:9e52bd1a4a71 | 215 | /// and when using standard io, you can typically use kbhit, or _kbhit as your system provides. |
WiredHome | 10:9e52bd1a4a71 | 216 | /// @param getch is a user provided function that provides a single character to the CommandProcessor |
WiredHome | 10:9e52bd1a4a71 | 217 | /// @param putch is a user provided function that permits the CommandProcessor to output a character |
WiredHome | 10:9e52bd1a4a71 | 218 | /// @param puts is a user provided function that permits the CommandProcessor to output a string |
WiredHome | 4:283e35536097 | 219 | /// to which is automatically appended a \\n |
WiredHome | 4:283e35536097 | 220 | /// @returns INITRESULT_T to indicate if the init was successful or failed |
WiredHome | 10:9e52bd1a4a71 | 221 | /// |
WiredHome | 4:283e35536097 | 222 | INITRESULT_T (*Init)( |
WiredHome | 10:9e52bd1a4a71 | 223 | CMD_T *SignOnBanner, |
WiredHome | 10:9e52bd1a4a71 | 224 | CONFIG_T config, |
WiredHome | 6:1a0512faa75d | 225 | int maxCmdLen, |
WiredHome | 4:283e35536097 | 226 | int (*kbhit)(void), |
WiredHome | 4:283e35536097 | 227 | int (*getch)(void), |
WiredHome | 4:283e35536097 | 228 | int (*putch)(int ch), |
WiredHome | 4:283e35536097 | 229 | int (*puts)(const char * s) |
WiredHome | 4:283e35536097 | 230 | ); |
WiredHome | 0:198f53da1bc8 | 231 | |
WiredHome | 4:283e35536097 | 232 | /// Add is called to add an item to the CommandProcessor menu |
WiredHome | 4:283e35536097 | 233 | /// |
WiredHome | 4:283e35536097 | 234 | /// This passes in a reference to a user provided CMD_T item, which is |
WiredHome | 4:283e35536097 | 235 | /// added to the menu system. |
WiredHome | 4:283e35536097 | 236 | /// |
WiredHome | 6:1a0512faa75d | 237 | /// @param m is a pointer to the user provided menu |
WiredHome | 6:1a0512faa75d | 238 | /// @returns ADDRESULT_T to indicate if the add was successful or failed |
WiredHome | 4:283e35536097 | 239 | /// |
WiredHome | 4:283e35536097 | 240 | ADDRESULT_T (*Add)(CMD_T * m); |
WiredHome | 0:198f53da1bc8 | 241 | |
WiredHome | 4:283e35536097 | 242 | /// Run is the primary runtime entry point for the CommandProcessor. |
WiredHome | 4:283e35536097 | 243 | /// |
WiredHome | 4:283e35536097 | 244 | /// This function should be called periodically - fast enough not to miss user input. |
WiredHome | 4:283e35536097 | 245 | /// This function always returns, so if not character is available for the CommandProcessor |
WiredHome | 4:283e35536097 | 246 | /// it will return very fast. If there is a character (as detected by the kbhit callback), |
WiredHome | 4:283e35536097 | 247 | /// then it will process that character and determine what to do. It may then execute one |
WiredHome | 4:283e35536097 | 248 | /// of the menu functions. In this case, CPU cycles spent are based on the function |
WiredHome | 4:283e35536097 | 249 | /// being executed. |
WiredHome | 4:283e35536097 | 250 | /// |
WiredHome | 4:283e35536097 | 251 | /// @returns RUNRESULT_T to indicate if the CommandProcessor should remain active or if the |
WiredHome | 4:283e35536097 | 252 | /// command that was executed is requesting the CommandProcessor to exit. |
WiredHome | 4:283e35536097 | 253 | /// |
WiredHome | 4:283e35536097 | 254 | RUNRESULT_T (*Run)(void); |
WiredHome | 6:1a0512faa75d | 255 | |
WiredHome | 6:1a0512faa75d | 256 | /// Echo command permits turning the echo on and off |
WiredHome | 6:1a0512faa75d | 257 | /// |
WiredHome | 6:1a0512faa75d | 258 | /// When interactive with the user, it is best to have echo on, so they can see |
WiredHome | 6:1a0512faa75d | 259 | /// the prompt, but if this is simply slaved to another program, then the echo |
WiredHome | 6:1a0512faa75d | 260 | /// might need to be off to best manage the stream. |
WiredHome | 6:1a0512faa75d | 261 | /// |
WiredHome | 6:1a0512faa75d | 262 | /// @param echo turns the echo on (non-zero) or off (zero) |
WiredHome | 6:1a0512faa75d | 263 | /// @returns RUNRESULT_T to indicate if the CommandProcessor should remain active or if the |
WiredHome | 6:1a0512faa75d | 264 | /// command that was executed is requesting the CommandProcessor to exit. |
WiredHome | 6:1a0512faa75d | 265 | /// |
WiredHome | 6:1a0512faa75d | 266 | RUNRESULT_T (*Echo)(int echo); |
WiredHome | 0:198f53da1bc8 | 267 | |
WiredHome | 4:283e35536097 | 268 | /// End if the function to be called when you want to gracefully end the CommandProcessor. |
WiredHome | 4:283e35536097 | 269 | /// |
WiredHome | 4:283e35536097 | 270 | /// Calling this function causes the CommandProcessor to free any memory that was previously |
WiredHome | 4:283e35536097 | 271 | /// allocated by the Init and Add functions. |
WiredHome | 4:283e35536097 | 272 | RUNRESULT_T (*End)(void); ///< Called to shutdown the processor |
WiredHome | 0:198f53da1bc8 | 273 | } CMDP_T; |
WiredHome | 0:198f53da1bc8 | 274 | |
WiredHome | 3:7c9993cac92b | 275 | |
WiredHome | 3:7c9993cac92b | 276 | /// The CommandProcessor is the interface to install a run-time menu into an embedded system. |
WiredHome | 3:7c9993cac92b | 277 | /// This contains the complete interface to the CommandProcessor. |
WiredHome | 3:7c9993cac92b | 278 | /// |
WiredHome | 3:7c9993cac92b | 279 | /// @version 1.0 |
WiredHome | 3:7c9993cac92b | 280 | /// |
WiredHome | 3:7c9993cac92b | 281 | /// @note The CommandProcessor is text-based, because it is intended to interact with a |
WiredHome | 3:7c9993cac92b | 282 | /// user. |
WiredHome | 3:7c9993cac92b | 283 | /// |
WiredHome | 3:7c9993cac92b | 284 | /// The menu is designed to be interactively accessed, perhaps via a console interface |
WiredHome | 3:7c9993cac92b | 285 | /// or a serial port. The actual interface to the user is provided by the application |
WiredHome | 3:7c9993cac92b | 286 | /// during initialization, so it can be connected to a serial port, or it could |
WiredHome | 3:7c9993cac92b | 287 | /// be interface to CAN, telnet, or by some other method. |
WiredHome | 3:7c9993cac92b | 288 | /// |
WiredHome | 3:7c9993cac92b | 289 | /// The CommandProcessor has a few special features: |
WiredHome | 3:7c9993cac92b | 290 | /// \li If the minimum number of characters of a command have been entered, the |
WiredHome | 3:7c9993cac92b | 291 | /// user does not have to type the entire command. (e.g. 'He' will execute |
WiredHome | 3:7c9993cac92b | 292 | /// the command for 'Help', if no other command beings with 'He'). |
WiredHome | 3:7c9993cac92b | 293 | /// \li If the user does not type the entire set of characters, the command |
WiredHome | 3:7c9993cac92b | 294 | /// will be rewritten to the output device with the entire command word. |
WiredHome | 3:7c9993cac92b | 295 | /// \li The user is not permitted to enter an incorrect command (e.g. If 'Help' |
WiredHome | 3:7c9993cac92b | 296 | /// is the only command started with 'Hel', the user cannot enter 'Heu'. |
WiredHome | 3:7c9993cac92b | 297 | /// The CommandProcessor will trap the 'u' and issue a beep). |
WiredHome | 3:7c9993cac92b | 298 | /// \li Simple editing of parameters to commands is permitted with \<bs\> to |
WiredHome | 3:7c9993cac92b | 299 | /// erase incorrect text. |
WiredHome | 3:7c9993cac92b | 300 | /// \li Tab completion of a command is available - so long as the user has |
WiredHome | 4:283e35536097 | 301 | /// typed at least the minimum number of unique characters. (e.g. 'He\<tab\>' |
WiredHome | 3:7c9993cac92b | 302 | /// will be replaced with 'Help') |
WiredHome | 4:283e35536097 | 303 | /// \li Command cancellation is available - just enter the \<esc\> key and |
WiredHome | 3:7c9993cac92b | 304 | /// the buffer is erased. |
WiredHome | 3:7c9993cac92b | 305 | /// \li The user is not permitted to enter text longer than the defined buffer, |
WiredHome | 3:7c9993cac92b | 306 | /// to avoid buffer overrun and the possible memory damaging results. |
WiredHome | 3:7c9993cac92b | 307 | /// |
WiredHome | 3:7c9993cac92b | 308 | /// The CommandProcessor is designed as a set of C functions, which makes it |
WiredHome | 3:7c9993cac92b | 309 | /// reusable in more systems (as C++ compilers are not always available for |
WiredHome | 3:7c9993cac92b | 310 | /// all micros). |
WiredHome | 3:7c9993cac92b | 311 | /// |
WiredHome | 3:7c9993cac92b | 312 | /// Example: |
WiredHome | 3:7c9993cac92b | 313 | /// @code |
WiredHome | 3:7c9993cac92b | 314 | /// extern "C" { |
WiredHome | 3:7c9993cac92b | 315 | /// #include "CommandProcessor.h" |
WiredHome | 3:7c9993cac92b | 316 | /// } |
WiredHome | 3:7c9993cac92b | 317 | /// |
WiredHome | 10:9e52bd1a4a71 | 318 | /// RUNRESULT_T About(char *p); |
WiredHome | 10:9e52bd1a4a71 | 319 | /// const CMD_T AboutCmd = {"About", "About this program", About, invisible}; |
WiredHome | 3:7c9993cac92b | 320 | /// RUNRESULT_T Who(char *p); |
WiredHome | 3:7c9993cac92b | 321 | /// const CMD_T WhoCmd = {"who", "Shows who is logged on, or 'who id' for specifics", Who, visible}; |
WiredHome | 3:7c9993cac92b | 322 | /// |
WiredHome | 10:9e52bd1a4a71 | 323 | /// RUNRESULT_T About(char *p) |
WiredHome | 10:9e52bd1a4a71 | 324 | /// { |
WiredHome | 10:9e52bd1a4a71 | 325 | /// (void)p; |
WiredHome | 10:9e52bd1a4a71 | 326 | /// puts("\r\nThis program does really good things for the user.\r\n"); |
WiredHome | 10:9e52bd1a4a71 | 327 | /// } |
WiredHome | 10:9e52bd1a4a71 | 328 | /// |
WiredHome | 3:7c9993cac92b | 329 | /// RUNRESULT_T Who(char *p) |
WiredHome | 3:7c9993cac92b | 330 | /// { |
WiredHome | 4:283e35536097 | 331 | /// printf("\r\nwho...\r\n"); |
WiredHome | 4:283e35536097 | 332 | /// if (*p) |
WiredHome | 4:283e35536097 | 333 | /// printf(" Sorry, no help for [%s]\r\n", p); |
WiredHome | 4:283e35536097 | 334 | /// return runok; |
WiredHome | 3:7c9993cac92b | 335 | /// } |
WiredHome | 3:7c9993cac92b | 336 | /// |
WiredHome | 3:7c9993cac92b | 337 | /// int main(int argc, char* argv[]) |
WiredHome | 3:7c9993cac92b | 338 | /// { |
WiredHome | 4:283e35536097 | 339 | /// CMDP_T * cp = GetCommandProcessor(); |
WiredHome | 10:9e52bd1a4a71 | 340 | /// cp->Init(AboutCmd, CFG_ENABLE_TERMINATE | CFG_ENABLE_SYSTEM | CFG_SIGNON_BANNER, |
WiredHome | 10:9e52bd1a4a71 | 341 | /// 50, |
WiredHome | 10:9e52bd1a4a71 | 342 | /// _kbhit, _getch, _putch, printf); |
WiredHome | 4:283e35536097 | 343 | /// cp->Add(&WhoCmd); |
WiredHome | 3:7c9993cac92b | 344 | /// |
WiredHome | 4:283e35536097 | 345 | /// while (cp->Run()) |
WiredHome | 4:283e35536097 | 346 | /// { |
WiredHome | 4:283e35536097 | 347 | /// ; |
WiredHome | 4:283e35536097 | 348 | /// } |
WiredHome | 4:283e35536097 | 349 | /// cp->End(); |
WiredHome | 4:283e35536097 | 350 | /// return 0; |
WiredHome | 3:7c9993cac92b | 351 | /// } |
WiredHome | 3:7c9993cac92b | 352 | /// @endcode |
WiredHome | 3:7c9993cac92b | 353 | /// |
WiredHome | 3:7c9993cac92b | 354 | /// @note Copyright © 2011 by Smartware Computing, all rights reserved. |
WiredHome | 3:7c9993cac92b | 355 | /// This program may be used by others as long as this copyright notice |
WiredHome | 3:7c9993cac92b | 356 | /// remains intact. |
WiredHome | 3:7c9993cac92b | 357 | /// @author David Smart |
WiredHome | 3:7c9993cac92b | 358 | /// |
WiredHome | 0:198f53da1bc8 | 359 | /// GetCommandProcessor is called to get a handle to the CommandProcessor itself. |
WiredHome | 0:198f53da1bc8 | 360 | /// |
WiredHome | 0:198f53da1bc8 | 361 | /// Call this function to get a handle to the CommandProcessor. After this is done, then |
WiredHome | 0:198f53da1bc8 | 362 | /// you can use that handle to activate the CommandProcessor methods. |
WiredHome | 0:198f53da1bc8 | 363 | /// |
WiredHome | 0:198f53da1bc8 | 364 | /// example: |
WiredHome | 0:198f53da1bc8 | 365 | /// @code |
WiredHome | 4:283e35536097 | 366 | /// CMDP_T * cp = GetCommandProcessor(); |
WiredHome | 10:9e52bd1a4a71 | 367 | /// cp->Init(AboutCmd, CFG_ENABLE_TERMINATE | CFG_ENABLE_SYSTEM | CFG_SIGNON_BANNER, |
WiredHome | 10:9e52bd1a4a71 | 368 | /// 50, |
WiredHome | 10:9e52bd1a4a71 | 369 | /// _kbhit, _getch, _putch, printf); |
WiredHome | 0:198f53da1bc8 | 370 | /// @endcode |
WiredHome | 0:198f53da1bc8 | 371 | /// |
WiredHome | 1:1c81feb2f8bd | 372 | /// @returns CMDP_T a handle to the CommandProcessor |
WiredHome | 0:198f53da1bc8 | 373 | /// |
WiredHome | 0:198f53da1bc8 | 374 | #ifdef WIN32 |
WiredHome | 0:198f53da1bc8 | 375 | CMDP_T * GetCommandProcessor(void); |
WiredHome | 0:198f53da1bc8 | 376 | #else // This is necessary for the mbed - not sure why. |
WiredHome | 0:198f53da1bc8 | 377 | extern "C" CMDP_T * GetCommandProcessor(void); |
WiredHome | 0:198f53da1bc8 | 378 | #endif |
WiredHome | 0:198f53da1bc8 | 379 | |
WiredHome | 4:283e35536097 | 380 | |
WiredHome | 4:283e35536097 | 381 | |
WiredHome | 8:25581f24f7f9 | 382 | //int mystrnicmp(const char *l, const char *r, size_t n); |
WiredHome | 1:1c81feb2f8bd | 383 | #endif // COMMANDPROCESSOR_H |