David Smart / CommandProcessor

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

Dependents:   A_CANAdapter USB2I2C

CommandProcessor.h@17:abba63b079fb, 2012-11-08 (annotated)

Committer:
WiredHome
Date:
Thu Nov 08 12:49:56 2012 +0000
Revision:
17:abba63b079fb
Parent:
16:4ce4f55213ac 
Minor tweak for compatibility with mbed lib v43

Who changed what in which revision?

UserRevisionLine numberNew 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 15:5f30da93e3e2 8 /// @version 1.05
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 14:7971c8bd3f11 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 15:5f30da93e3e2 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 15:5f30da93e3e2 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 12:a8c56bf811b9 89 ///
WiredHome 12:a8c56bf811b9 90 /// @note Copyright &copr; 2011 by Smartware Computing, all rights reserved.
WiredHome 12:a8c56bf811b9 91 /// Individuals may use this application for evaluation or non-commercial
WiredHome 12:a8c56bf811b9 92 /// purposes. Within this restriction, changes may be made to this application
WiredHome 12:a8c56bf811b9 93 /// as long as this copyright notice is retained. The user shall make
WiredHome 12:a8c56bf811b9 94 /// clear that their work is a derived work, and not the original.
WiredHome 12:a8c56bf811b9 95 /// Users of this application and sources accept this application "as is" and
WiredHome 12:a8c56bf811b9 96 /// shall hold harmless Smartware Computing, for any undesired results while
WiredHome 12:a8c56bf811b9 97 /// using this application - whether real or imagined.
WiredHome 12:a8c56bf811b9 98 ///
WiredHome 12:a8c56bf811b9 99 /// @author David Smart, Smartware Computing
WiredHome 0:198f53da1bc8 100 ///
WiredHome 10:9e52bd1a4a71 101 /// @note
WiredHome 10:9e52bd1a4a71 102 /// History
WiredHome 15:5f30da93e3e2 103 /// v1.05 20111030
WiredHome 15:5f30da93e3e2 104 /// \li Added support for VT100 cursor code for up/down history access
WiredHome 16:4ce4f55213ac 105 /// \li Fixed a bug related to not entering any parameters - causing it to think
WiredHome 16:4ce4f55213ac 106 /// there were parameters anyway.
WiredHome 14:7971c8bd3f11 107 /// v1.04 1 October 2011
WiredHome 14:7971c8bd3f11 108 /// \li Added configurable command line history for easy recall of previous commands
WiredHome 14:7971c8bd3f11 109 /// \li Clean up dead-code
WiredHome 12:a8c56bf811b9 110 /// v1.03 29 May 2011
WiredHome 12:a8c56bf811b9 111 /// \li Slightly improved internal documentation. No external interfaces affected.
WiredHome 12:a8c56bf811b9 112 /// v1.02 2 May 2011
WiredHome 12:a8c56bf811b9 113 /// \li Track the longest command when added, so that the help printout
WiredHome 12:a8c56bf811b9 114 /// is more nicely formatted.
WiredHome 10:9e52bd1a4a71 115 /// v1.01 22 April 2011
WiredHome 10:9e52bd1a4a71 116 /// \li Moving 'About' content into the extended help,
WiredHome 10:9e52bd1a4a71 117 /// to free 'About' for application code that uses this library.
WiredHome 10:9e52bd1a4a71 118 /// \li Altered the _init api to permit a signon banner of the users choice
WiredHome 10:9e52bd1a4a71 119 /// and a config parameter for other features.
WiredHome 10:9e52bd1a4a71 120 ///
WiredHome 10:9e52bd1a4a71 121 /// v1.0 March 2011
WiredHome 10:9e52bd1a4a71 122 /// \li Initial version
WiredHome 10:9e52bd1a4a71 123 ///
WiredHome 0:198f53da1bc8 124 #ifndef COMMANDPROCESSOR_H
WiredHome 0:198f53da1bc8 125 #define COMMANDPROCESSOR_H
WiredHome 0:198f53da1bc8 126
WiredHome 15:5f30da93e3e2 127 #define VERSION "1.05"
WiredHome 15:5f30da93e3e2 128
WiredHome 0:198f53da1bc8 129 #ifndef TRUE
WiredHome 4:283e35536097 130 #define TRUE 1 ///< Definition for TRUE, if not already provided
WiredHome 4:283e35536097 131 #define FALSE 0 ///< Definition for FALSE, if not already provided
WiredHome 0:198f53da1bc8 132 #endif
WiredHome 0:198f53da1bc8 133
WiredHome 0:198f53da1bc8 134 /// @brief This type determines if menu items are visible to the Help system, or hidden.
WiredHome 0:198f53da1bc8 135 /// @details This is used in the definition of the menu item.
WiredHome 0:198f53da1bc8 136 typedef enum
WiredHome 0:198f53da1bc8 137 {
WiredHome 4:283e35536097 138 invisible, ///< use this value to have invisible (hidden) a menu in the Help
WiredHome 4:283e35536097 139 visible ///< use this value to have visible a menu in the Help
WiredHome 4:283e35536097 140 } VISIBLE_T; ///< This determines if menu items are made visible in the Help system.
WiredHome 0:198f53da1bc8 141
WiredHome 0:198f53da1bc8 142 /// Callbacks that are executed return a value to indicate if the menu
WiredHome 0:198f53da1bc8 143 /// should remain active
WiredHome 0:198f53da1bc8 144 typedef enum
WiredHome 0:198f53da1bc8 145 {
WiredHome 4:283e35536097 146 runexit, ///< use this return value to cause the menu (perhaps the program) to exit
WiredHome 4:283e35536097 147 runok ///< use this return value to keep the menu running
WiredHome 0:198f53da1bc8 148 } RUNRESULT_T;
WiredHome 0:198f53da1bc8 149
WiredHome 0:198f53da1bc8 150 /// Adding items to the menu can succeed, or fail.
WiredHome 0:198f53da1bc8 151 typedef enum
WiredHome 0:198f53da1bc8 152 {
WiredHome 4:283e35536097 153 addfailed, ///< this indicates the menu was not added (usually failure to allocate memory)
WiredHome 4:283e35536097 154 addok ///< this indicates the menu was successfully added
WiredHome 0:198f53da1bc8 155 } ADDRESULT_T;
WiredHome 0:198f53da1bc8 156
WiredHome 0:198f53da1bc8 157 /// Initialization can succeed, or fail.
WiredHome 0:198f53da1bc8 158 typedef enum
WiredHome 0:198f53da1bc8 159 {
WiredHome 4:283e35536097 160 initfailed, ///< this indicates that the menu system was not initialized (usually failure to allocate memory)
WiredHome 4:283e35536097 161 initok ///< this indicates that the menu system was successfully initialized
WiredHome 0:198f53da1bc8 162 } INITRESULT_T;
WiredHome 0:198f53da1bc8 163
WiredHome 11:4a3cd3f2183b 164 /// Configuration options to control startup and some runtime behavior
WiredHome 11:4a3cd3f2183b 165 ///
WiredHome 11:4a3cd3f2183b 166 /// Permissible values are created by combining
WiredHome 11:4a3cd3f2183b 167 /// \li CFG_ENABLE_TERMINATE
WiredHome 11:4a3cd3f2183b 168 /// \li CFG_ENABLE_SYSTEM
WiredHome 11:4a3cd3f2183b 169 /// \li CFG_ECHO_ON
WiredHome 11:4a3cd3f2183b 170 /// \li CFG_CASE_INSENSITIVE
WiredHome 10:9e52bd1a4a71 171 typedef unsigned long CONFIG_T;
WiredHome 10:9e52bd1a4a71 172
WiredHome 11:4a3cd3f2183b 173 #define CFG_ENABLE_TERMINATE 0x0001 ///<- Enable the exit option
WiredHome 11:4a3cd3f2183b 174 #define CFG_ENABLE_SYSTEM 0x0002 ///<- Enable various system options (help, etc)
WiredHome 11:4a3cd3f2183b 175 #define CFG_ECHO_ON 0x2000 ///<- Initialize with command prompt Echo on
WiredHome 11:4a3cd3f2183b 176 #define CFG_CASE_INSENSITIVE 0x4000 ///<- Enable case insensitive command entry
WiredHome 10:9e52bd1a4a71 177
WiredHome 10:9e52bd1a4a71 178
WiredHome 0:198f53da1bc8 179 /// This is the type for the basic callback, when a menu pick is activated.
WiredHome 0:198f53da1bc8 180 ///
WiredHome 0:198f53da1bc8 181 /// The callback function is executed when a command is entered on the menu and \<enter\>
WiredHome 0:198f53da1bc8 182 /// is signaled. If there is any additional text entered on the commandline, it is
WiredHome 0:198f53da1bc8 183 /// passed to the callback.
WiredHome 0:198f53da1bc8 184 ///
WiredHome 0:198f53da1bc8 185 /// example:
WiredHome 4:283e35536097 186 /// "Test1 ab c 123 567"
WiredHome 0:198f53da1bc8 187 /// If "Test1" is a valid command, the corresponding function would be called
WiredHome 4:283e35536097 188 /// passing to that function the string "ab c 123 567". Note that the delimiter space
WiredHome 10:9e52bd1a4a71 189 /// was removed.
WiredHome 0:198f53da1bc8 190 ///
WiredHome 10:9e52bd1a4a71 191 /// @param p is a pointer to a character string
WiredHome 10:9e52bd1a4a71 192 /// @returns RUNRESULT_T to indicate if the CommandProcessor should continue
WiredHome 0:198f53da1bc8 193 ///
WiredHome 0:198f53da1bc8 194 typedef RUNRESULT_T (*MENU_CALLBACK)(char *p);
WiredHome 0:198f53da1bc8 195
WiredHome 0:198f53da1bc8 196 /// This defines the type for a single item to be added to the CommandProcessor menu.
WiredHome 0:198f53da1bc8 197 ///
WiredHome 0:198f53da1bc8 198 /// This is defined in the application code, and a pointer to this item is passed to the
WiredHome 0:198f53da1bc8 199 /// CommandProcessor to add this item to the menu system.
WiredHome 0:198f53da1bc8 200 ///
WiredHome 0:198f53da1bc8 201 /// example:
WiredHome 10:9e52bd1a4a71 202 /// @code
WiredHome 0:198f53da1bc8 203 /// const CMD_T WhoCmd = {"who", "Shows who is logged on, or 'who id' for specifics", Who, visible};
WiredHome 0:198f53da1bc8 204 /// @endcode
WiredHome 0:198f53da1bc8 205 ///
WiredHome 0:198f53da1bc8 206 typedef const struct
WiredHome 0:198f53da1bc8 207 {
WiredHome 4:283e35536097 208 char * command; ///< a pointer to the command to match (e.g. 'Help')
WiredHome 4:283e35536097 209 char * helptext; ///< a pointer to some text to show when user types 'Help'
WiredHome 4:283e35536097 210 MENU_CALLBACK callback; ///< the function to call when user enters this command
WiredHome 4:283e35536097 211 VISIBLE_T visible; ///< a flag that determines if this command is visible in Help.
WiredHome 0:198f53da1bc8 212 } CMD_T;
WiredHome 0:198f53da1bc8 213
WiredHome 0:198f53da1bc8 214 /// This is the CommandProcessor interface from the user application.
WiredHome 0:198f53da1bc8 215 ///
WiredHome 10:9e52bd1a4a71 216 /// The user aquires a handle to this set of functions with the GetCommandProcessor command.
WiredHome 0:198f53da1bc8 217 /// After this, the user may then initialize the CommandProcessor, add items to the menu,
WiredHome 0:198f53da1bc8 218 /// cause the CommandProcessor to run periodically, and if need be the application can end
WiredHome 0:198f53da1bc8 219 /// the CommandProcessor.
WiredHome 0:198f53da1bc8 220 ///
WiredHome 0:198f53da1bc8 221 typedef const struct
WiredHome 0:198f53da1bc8 222 {
WiredHome 4:283e35536097 223 /// Init is the first function to call to configure the CommandProcessor.
WiredHome 4:283e35536097 224 ///
WiredHome 4:283e35536097 225 /// This function has a number of parameters, which make the CommandProcessor quite flexible.
WiredHome 4:283e35536097 226 ///
WiredHome 15:5f30da93e3e2 227 /// @param SignOnBanner function, which is used as a signon banner
WiredHome 10:9e52bd1a4a71 228 /// @param config enables various default menu items, based on the bit values, combine the following:
WiredHome 15:5f30da93e3e2 229 /// \li CFG_ENABLE_TERMINATE - enables the Exit command
WiredHome 15:5f30da93e3e2 230 /// \li CFG_ENABLE_SYSTEM - enables system commands Echo, Help, etc.
WiredHome 15:5f30da93e3e2 231 /// \li CFG_ECHO_ON - initialize with echo on
WiredHome 15:5f30da93e3e2 232 /// \li CFG_CASE_INSENSITIVE - Command Parser is case insensitive
WiredHome 15:5f30da93e3e2 233 /// @param maxCmdLen sizes the buffer, and is the maximum number of characters in a single
WiredHome 15:5f30da93e3e2 234 /// command, including all command arguments
WiredHome 15:5f30da93e3e2 235 /// @param historyLen sets the number of items that can be recalled from history
WiredHome 10:9e52bd1a4a71 236 /// @param kbhit is a user provided function to detect if a character is available for the CommandProcessor,
WiredHome 10:9e52bd1a4a71 237 /// and when using standard io, you can typically use kbhit, or _kbhit as your system provides.
WiredHome 10:9e52bd1a4a71 238 /// @param getch is a user provided function that provides a single character to the CommandProcessor
WiredHome 10:9e52bd1a4a71 239 /// @param putch is a user provided function that permits the CommandProcessor to output a character
WiredHome 10:9e52bd1a4a71 240 /// @param puts is a user provided function that permits the CommandProcessor to output a string
WiredHome 4:283e35536097 241 /// to which is automatically appended a \\n
WiredHome 4:283e35536097 242 /// @returns INITRESULT_T to indicate if the init was successful or failed
WiredHome 15:5f30da93e3e2 243 ///
WiredHome 4:283e35536097 244 INITRESULT_T (*Init)(
WiredHome 15:5f30da93e3e2 245 CMD_T *SignOnBanner,
WiredHome 10:9e52bd1a4a71 246 CONFIG_T config,
WiredHome 6:1a0512faa75d 247 int maxCmdLen,
WiredHome 15:5f30da93e3e2 248 int historyLen,
WiredHome 4:283e35536097 249 int (*kbhit)(void),
WiredHome 4:283e35536097 250 int (*getch)(void),
WiredHome 4:283e35536097 251 int (*putch)(int ch),
WiredHome 4:283e35536097 252 int (*puts)(const char * s)
WiredHome 4:283e35536097 253 );
WiredHome 0:198f53da1bc8 254
WiredHome 4:283e35536097 255 /// Add is called to add an item to the CommandProcessor menu
WiredHome 4:283e35536097 256 ///
WiredHome 4:283e35536097 257 /// This passes in a reference to a user provided CMD_T item, which is
WiredHome 4:283e35536097 258 /// added to the menu system.
WiredHome 4:283e35536097 259 ///
WiredHome 6:1a0512faa75d 260 /// @param m is a pointer to the user provided menu
WiredHome 6:1a0512faa75d 261 /// @returns ADDRESULT_T to indicate if the add was successful or failed
WiredHome 4:283e35536097 262 ///
WiredHome 4:283e35536097 263 ADDRESULT_T (*Add)(CMD_T * m);
WiredHome 0:198f53da1bc8 264
WiredHome 4:283e35536097 265 /// Run is the primary runtime entry point for the CommandProcessor.
WiredHome 4:283e35536097 266 ///
WiredHome 4:283e35536097 267 /// This function should be called periodically - fast enough not to miss user input.
WiredHome 4:283e35536097 268 /// This function always returns, so if not character is available for the CommandProcessor
WiredHome 4:283e35536097 269 /// it will return very fast. If there is a character (as detected by the kbhit callback),
WiredHome 4:283e35536097 270 /// then it will process that character and determine what to do. It may then execute one
WiredHome 4:283e35536097 271 /// of the menu functions. In this case, CPU cycles spent are based on the function
WiredHome 4:283e35536097 272 /// being executed.
WiredHome 4:283e35536097 273 ///
WiredHome 4:283e35536097 274 /// @returns RUNRESULT_T to indicate if the CommandProcessor should remain active or if the
WiredHome 4:283e35536097 275 /// command that was executed is requesting the CommandProcessor to exit.
WiredHome 4:283e35536097 276 ///
WiredHome 4:283e35536097 277 RUNRESULT_T (*Run)(void);
WiredHome 6:1a0512faa75d 278
WiredHome 6:1a0512faa75d 279 /// Echo command permits turning the echo on and off
WiredHome 6:1a0512faa75d 280 ///
WiredHome 6:1a0512faa75d 281 /// When interactive with the user, it is best to have echo on, so they can see
WiredHome 6:1a0512faa75d 282 /// the prompt, but if this is simply slaved to another program, then the echo
WiredHome 6:1a0512faa75d 283 /// might need to be off to best manage the stream.
WiredHome 6:1a0512faa75d 284 ///
WiredHome 6:1a0512faa75d 285 /// @param echo turns the echo on (non-zero) or off (zero)
WiredHome 6:1a0512faa75d 286 /// @returns RUNRESULT_T to indicate if the CommandProcessor should remain active or if the
WiredHome 6:1a0512faa75d 287 /// command that was executed is requesting the CommandProcessor to exit.
WiredHome 6:1a0512faa75d 288 ///
WiredHome 6:1a0512faa75d 289 RUNRESULT_T (*Echo)(int echo);
WiredHome 0:198f53da1bc8 290
WiredHome 4:283e35536097 291 /// End if the function to be called when you want to gracefully end the CommandProcessor.
WiredHome 4:283e35536097 292 ///
WiredHome 4:283e35536097 293 /// Calling this function causes the CommandProcessor to free any memory that was previously
WiredHome 4:283e35536097 294 /// allocated by the Init and Add functions.
WiredHome 4:283e35536097 295 RUNRESULT_T (*End)(void); ///< Called to shutdown the processor
WiredHome 0:198f53da1bc8 296 } CMDP_T;
WiredHome 0:198f53da1bc8 297
WiredHome 3:7c9993cac92b 298
WiredHome 3:7c9993cac92b 299 /// The CommandProcessor is the interface to install a run-time menu into an embedded system.
WiredHome 3:7c9993cac92b 300 /// This contains the complete interface to the CommandProcessor.
WiredHome 3:7c9993cac92b 301 ///
WiredHome 15:5f30da93e3e2 302 /// @version 1.05
WiredHome 3:7c9993cac92b 303 ///
WiredHome 3:7c9993cac92b 304 /// @note The CommandProcessor is text-based, because it is intended to interact with a
WiredHome 3:7c9993cac92b 305 /// user.
WiredHome 3:7c9993cac92b 306 ///
WiredHome 3:7c9993cac92b 307 /// The menu is designed to be interactively accessed, perhaps via a console interface
WiredHome 3:7c9993cac92b 308 /// or a serial port. The actual interface to the user is provided by the application
WiredHome 3:7c9993cac92b 309 /// during initialization, so it can be connected to a serial port, or it could
WiredHome 3:7c9993cac92b 310 /// be interface to CAN, telnet, or by some other method.
WiredHome 3:7c9993cac92b 311 ///
WiredHome 3:7c9993cac92b 312 /// The CommandProcessor has a few special features:
WiredHome 3:7c9993cac92b 313 /// \li If the minimum number of characters of a command have been entered, the
WiredHome 3:7c9993cac92b 314 /// user does not have to type the entire command. (e.g. 'He' will execute
WiredHome 3:7c9993cac92b 315 /// the command for 'Help', if no other command beings with 'He').
WiredHome 3:7c9993cac92b 316 /// \li If the user does not type the entire set of characters, the command
WiredHome 3:7c9993cac92b 317 /// will be rewritten to the output device with the entire command word.
WiredHome 3:7c9993cac92b 318 /// \li The user is not permitted to enter an incorrect command (e.g. If 'Help'
WiredHome 3:7c9993cac92b 319 /// is the only command started with 'Hel', the user cannot enter 'Heu'.
WiredHome 3:7c9993cac92b 320 /// The CommandProcessor will trap the 'u' and issue a beep).
WiredHome 3:7c9993cac92b 321 /// \li Simple editing of parameters to commands is permitted with \<bs\> to
WiredHome 3:7c9993cac92b 322 /// erase incorrect text.
WiredHome 3:7c9993cac92b 323 /// \li Tab completion of a command is available - so long as the user has
WiredHome 4:283e35536097 324 /// typed at least the minimum number of unique characters. (e.g. 'He\<tab\>'
WiredHome 3:7c9993cac92b 325 /// will be replaced with 'Help')
WiredHome 4:283e35536097 326 /// \li Command cancellation is available - just enter the \<esc\> key and
WiredHome 3:7c9993cac92b 327 /// the buffer is erased.
WiredHome 3:7c9993cac92b 328 /// \li The user is not permitted to enter text longer than the defined buffer,
WiredHome 3:7c9993cac92b 329 /// to avoid buffer overrun and the possible memory damaging results.
WiredHome 3:7c9993cac92b 330 ///
WiredHome 3:7c9993cac92b 331 /// The CommandProcessor is designed as a set of C functions, which makes it
WiredHome 3:7c9993cac92b 332 /// reusable in more systems (as C++ compilers are not always available for
WiredHome 3:7c9993cac92b 333 /// all micros).
WiredHome 3:7c9993cac92b 334 ///
WiredHome 3:7c9993cac92b 335 /// Example:
WiredHome 3:7c9993cac92b 336 /// @code
WiredHome 3:7c9993cac92b 337 /// extern "C" {
WiredHome 3:7c9993cac92b 338 /// #include "CommandProcessor.h"
WiredHome 3:7c9993cac92b 339 /// }
WiredHome 3:7c9993cac92b 340 ///
WiredHome 10:9e52bd1a4a71 341 /// RUNRESULT_T About(char *p);
WiredHome 10:9e52bd1a4a71 342 /// const CMD_T AboutCmd = {"About", "About this program", About, invisible};
WiredHome 3:7c9993cac92b 343 /// RUNRESULT_T Who(char *p);
WiredHome 3:7c9993cac92b 344 /// const CMD_T WhoCmd = {"who", "Shows who is logged on, or 'who id' for specifics", Who, visible};
WiredHome 3:7c9993cac92b 345 ///
WiredHome 10:9e52bd1a4a71 346 /// RUNRESULT_T About(char *p)
WiredHome 10:9e52bd1a4a71 347 /// {
WiredHome 10:9e52bd1a4a71 348 /// (void)p;
WiredHome 10:9e52bd1a4a71 349 /// puts("\r\nThis program does really good things for the user.\r\n");
WiredHome 10:9e52bd1a4a71 350 /// }
WiredHome 10:9e52bd1a4a71 351 ///
WiredHome 3:7c9993cac92b 352 /// RUNRESULT_T Who(char *p)
WiredHome 3:7c9993cac92b 353 /// {
WiredHome 4:283e35536097 354 /// printf("\r\nwho...\r\n");
WiredHome 4:283e35536097 355 /// if (*p)
WiredHome 4:283e35536097 356 /// printf(" Sorry, no help for [%s]\r\n", p);
WiredHome 4:283e35536097 357 /// return runok;
WiredHome 3:7c9993cac92b 358 /// }
WiredHome 3:7c9993cac92b 359 ///
WiredHome 3:7c9993cac92b 360 /// int main(int argc, char* argv[])
WiredHome 3:7c9993cac92b 361 /// {
WiredHome 4:283e35536097 362 /// CMDP_T * cp = GetCommandProcessor();
WiredHome 10:9e52bd1a4a71 363 /// cp->Init(AboutCmd, CFG_ENABLE_TERMINATE | CFG_ENABLE_SYSTEM | CFG_SIGNON_BANNER,
WiredHome 10:9e52bd1a4a71 364 /// 50,
WiredHome 10:9e52bd1a4a71 365 /// _kbhit, _getch, _putch, printf);
WiredHome 4:283e35536097 366 /// cp->Add(&WhoCmd);
WiredHome 3:7c9993cac92b 367 ///
WiredHome 4:283e35536097 368 /// while (cp->Run())
WiredHome 4:283e35536097 369 /// {
WiredHome 4:283e35536097 370 /// ;
WiredHome 4:283e35536097 371 /// }
WiredHome 4:283e35536097 372 /// cp->End();
WiredHome 4:283e35536097 373 /// return 0;
WiredHome 3:7c9993cac92b 374 /// }
WiredHome 3:7c9993cac92b 375 /// @endcode
WiredHome 3:7c9993cac92b 376 ///
WiredHome 3:7c9993cac92b 377 /// @note Copyright &copy; 2011 by Smartware Computing, all rights reserved.
WiredHome 3:7c9993cac92b 378 /// This program may be used by others as long as this copyright notice
WiredHome 3:7c9993cac92b 379 /// remains intact.
WiredHome 3:7c9993cac92b 380 /// @author David Smart
WiredHome 3:7c9993cac92b 381 ///
WiredHome 0:198f53da1bc8 382 /// GetCommandProcessor is called to get a handle to the CommandProcessor itself.
WiredHome 0:198f53da1bc8 383 ///
WiredHome 0:198f53da1bc8 384 /// Call this function to get a handle to the CommandProcessor. After this is done, then
WiredHome 0:198f53da1bc8 385 /// you can use that handle to activate the CommandProcessor methods.
WiredHome 0:198f53da1bc8 386 ///
WiredHome 0:198f53da1bc8 387 /// example:
WiredHome 0:198f53da1bc8 388 /// @code
WiredHome 4:283e35536097 389 /// CMDP_T * cp = GetCommandProcessor();
WiredHome 10:9e52bd1a4a71 390 /// cp->Init(AboutCmd, CFG_ENABLE_TERMINATE | CFG_ENABLE_SYSTEM | CFG_SIGNON_BANNER,
WiredHome 10:9e52bd1a4a71 391 /// 50,
WiredHome 10:9e52bd1a4a71 392 /// _kbhit, _getch, _putch, printf);
WiredHome 0:198f53da1bc8 393 /// @endcode
WiredHome 0:198f53da1bc8 394 ///
WiredHome 1:1c81feb2f8bd 395 /// @returns CMDP_T a handle to the CommandProcessor
WiredHome 0:198f53da1bc8 396 ///
WiredHome 0:198f53da1bc8 397 #ifdef WIN32
WiredHome 13:e1880be590c4 398 extern CMDP_T * GetCommandProcessor(void);
WiredHome 0:198f53da1bc8 399 #else // This is necessary for the mbed - not sure why.
WiredHome 17:abba63b079fb 400 extern CMDP_T * GetCommandProcessor(void);
WiredHome 0:198f53da1bc8 401 #endif
WiredHome 0:198f53da1bc8 402
WiredHome 1:1c81feb2f8bd 403 #endif // COMMANDPROCESSOR_H