| 0,0 → 1,143 |
|---|
| // -*- tab-width: 4; Mode: C++; c-basic-offset: 4; indent-tabs-mode: t -*- |
| |
| /// @file menu.h |
| /// @brief Simple commandline menu subsystem. |
| /// @discussion |
| /// The Menu class implements a simple CLI that accepts commands typed by |
| /// the user, and passes the arguments to those commands to a function |
| /// defined as handing the command. |
| /// |
| /// Commands are defined in an array of Menu::command structures passed |
| /// to the constructor. Each entry in the array defines one command. |
| /// |
| /// Arguments passed to the handler function are pre-converted to both |
| /// long and float for convenience. |
| |
| #ifndef __AP_COMMON_MENU_H |
| #define __AP_COMMON_MENU_H |
| |
| #include <inttypes.h> |
| |
| #define MENU_COMMANDLINE_MAX 32 ///< maximum input line length |
| #define MENU_ARGS_MAX 4 ///< maximum number of arguments |
| #define MENU_COMMAND_MAX 14 ///< maximum size of a command name |
| |
| /// Class defining and handling one menu tree |
| class Menu { |
| public: |
| /// argument passed to a menu function |
| /// |
| /// Space-delimited arguments are parsed from the commandline and |
| /// separated into these structures. |
| /// |
| /// If the argument cannot be parsed as a float or a long, the value |
| /// of f or i respectively is undefined. You should range-check |
| /// the inputs to your function. |
| /// |
| struct arg { |
| const char *str; ///< string form of the argument |
| long i; ///< integer form of the argument (if a number) |
| float f; ///< floating point form of the argument (if a number) |
| }; |
| |
| /// menu command function |
| /// |
| /// Functions called by menu array entries are expected to be of this |
| /// type. |
| /// |
| /// @param argc The number of valid arguments, including the |
| /// name of the command in argv[0]. Will never be |
| /// more than MENU_ARGS_MAX. |
| /// @param argv Pointer to an array of Menu::arg structures |
| /// detailing any optional arguments given to the |
| /// command. argv[0] is always the name of the |
| /// command, so that the same function can be used |
| /// to handle more than one command. |
| /// |
| typedef int8_t (*func)(uint8_t argc, const struct arg *argv); |
| |
| /// menu pre-prompt function |
| /// |
| /// Called immediately before waiting for the user to type a command; can be |
| /// used to display help text or status, for example. |
| /// |
| /// If this function returns false, the menu exits. |
| /// |
| typedef bool (*preprompt)(void); |
| |
| /// menu command description |
| /// |
| struct command { |
| /// Name of the command, as typed or received. |
| /// Command names are limited in size to keep this structure compact. |
| /// |
| const char command[MENU_COMMAND_MAX]; |
| |
| /// The function to call when the command is received. |
| /// |
| /// The argc argument will be at least 1, and no more than |
| /// MENU_ARGS_MAX. The argv array will be populated with |
| /// arguments typed/received up to MENU_ARGS_MAX. The command |
| /// name will always be in argv[0]. |
| /// |
| /// Commands may return -2 to cause the menu itself to exit. |
| /// The "?", "help" and "exit" commands are always defined, but |
| /// can be overridden by explicit entries in the command array. |
| /// |
| int8_t (*func)(uint8_t argc, const struct arg *argv); ///< callback function |
| }; |
| |
| /// constructor |
| /// |
| /// Note that you should normally not call the constructor directly. Use |
| /// the MENU and MENU2 macros defined below. |
| /// |
| /// @param prompt The prompt to be displayed with this menu. |
| /// @param commands An array of ::command structures in program memory (PROGMEM). |
| /// @param entries The number of entries in the menu. |
| /// |
| Menu(const char *prompt, const struct command *commands, uint8_t entries, preprompt ppfunc = 0); |
| |
| /// menu runner |
| void run(void); |
| |
| private: |
| /// Implements the default 'help' command. |
| /// |
| void _help(void); ///< implements the 'help' command |
| |
| /// calls the function for the n'th menu item |
| /// |
| /// @param n Index for the menu item to call |
| /// @param argc Number of arguments prepared for the menu item |
| /// |
| int8_t _call(uint8_t n, uint8_t argc); |
| |
| const char *_prompt; ///< prompt to display |
| const command *_commands; ///< array of commands |
| const uint8_t _entries; ///< size of the menu |
| const preprompt _ppfunc; ///< optional pre-prompt action |
| |
| static char _inbuf[MENU_COMMANDLINE_MAX]; ///< input buffer |
| static arg _argv[MENU_ARGS_MAX + 1]; ///< arguments |
| }; |
| |
| /// Macros used to define a menu. |
| /// |
| /// The commands argument should be an arary of Menu::command structures, one |
| /// per command name. The array does not need to be terminated with any special |
| /// record. |
| /// |
| /// Use name.run() to run the menu. |
| /// |
| /// The MENU2 macro supports the optional pre-prompt printing function. |
| /// |
| #define MENU(name, prompt, commands) \ |
| static const char __menu_name__ ##name[] PROGMEM = prompt; \ |
| static Menu name(__menu_name__ ##name, commands, sizeof(commands) / sizeof(commands[0])) |
| |
| #define MENU2(name, prompt, commands, preprompt) \ |
| static const char __menu_name__ ##name[] PROGMEM = prompt; \ |
| static Menu name(__menu_name__ ##name, commands, sizeof(commands) / sizeof(commands[0]), preprompt) |
| |
| #endif |