Line No. | Rev | Author | Line |
---|---|---|---|
1 | 6 | kaklik | /*! \file cmdline.h \brief Command-Line Interface Library. */ |
2 | //***************************************************************************** |
||
3 | // |
||
4 | // File Name : 'cmdline.h' |
||
5 | // Title : Command-Line Interface Library |
||
6 | // Author : Pascal Stang - Copyright (C) 2003 |
||
7 | // Created : 2003.07.16 |
||
8 | // Revised : 2003.07.16 |
||
9 | // Version : 0.1 |
||
10 | // Target MCU : Atmel AVR Series |
||
11 | // Editor Tabs : 4 |
||
12 | // |
||
13 | /// \ingroup general |
||
14 | /// \defgroup cmdline Command-line Implementation (cmdline.c) |
||
15 | /// \code #include "cmdline.h" \endcode |
||
16 | /// \par Overview |
||
17 | /// This Command-Line interface library is meant to provide a reusable |
||
18 | /// terminal-like user interface much like a DOS command line or UNIX terminal. |
||
19 | /// A terminal with VT100 support is assumed on the user's end. Common |
||
20 | /// line-editing is supported, including backspace, arrow keys, and even a |
||
21 | /// small command-history buffer. |
||
22 | /// |
||
23 | /// \note One can imagine more efficient ways to implement the command and |
||
24 | /// function database contained in this library, however, this is a decent |
||
25 | /// and functional first cut. I may someday get around to making some |
||
26 | /// improvements. |
||
27 | /// |
||
28 | /// \par Operation |
||
29 | /// The cmdline library does the following things for you: |
||
30 | /// - Prints command prompts |
||
31 | /// - Gathers a command string from the user (with editing features) |
||
32 | /// - Parses the command string when the user presses [ENTER] |
||
33 | /// - Compares the entered command to the command database |
||
34 | /// -- Executes the corresponding function if a match is found |
||
35 | /// -- Reports an error if no match is found |
||
36 | /// -Provides functions to retrieve the command arguments: |
||
37 | /// --as strings |
||
38 | /// --as decimal integers |
||
39 | /// --as hex integers |
||
40 | /// |
||
41 | /// Supported editing features include: |
||
42 | /// - Backspace support |
||
43 | /// - Mid-line editing, inserting and deleting (left/right-arrows) |
||
44 | /// - Command History (up-arrow) (currently only one command deep) |
||
45 | /// |
||
46 | /// To use the cmdline system, you will need to associate command strings |
||
47 | /// (commands the user will be typing) with your function that you wish to have |
||
48 | /// called when the user enters that command. This is done by using the |
||
49 | /// cmdlineAddCommand() function. |
||
50 | /// |
||
51 | /// To setup the cmdline system, you must do these things: |
||
52 | /// - Initialize it: cmdlineInit() |
||
53 | /// - Add one or more commands to the database: cmdlineAddCommand() |
||
54 | /// - Set an output function for your terminal: cmdlineSetOutputFunc() |
||
55 | /// |
||
56 | /// To operate the cmdline system, you must do these things repeatedly: |
||
57 | /// - Pass user input from the terminal to: cmdlineSetOutputFunc() |
||
58 | /// - Call cmdlineMainLoop() from your program's main loop |
||
59 | /// |
||
60 | /// The cmdline library does not assume an input or output device, but can be |
||
61 | /// configured to use any user function for output using cmdlineSetOutputFunc() |
||
62 | /// and accepts input by calling cmdlineInputFunc(). This means the cmdline |
||
63 | /// library can operate over any interface including UART (serial port), |
||
64 | /// I2c, ethernet, etc. |
||
65 | /// |
||
66 | /// ***** FOR MORE INFORMATION ABOUT USING cmdline SEE THE AVRLIB EXAMPLE ***** |
||
67 | /// ***** CODE IN THE avrlib/examples DIRECTORY ***** |
||
68 | // |
||
69 | // NOTE: This code is currently below version 1.0, and therefore is considered |
||
70 | // to be lacking in some functionality or documentation, or may not be fully |
||
71 | // tested. Nonetheless, you can expect most functions to work. |
||
72 | // |
||
73 | // This code is distributed under the GNU Public License |
||
74 | // which can be found at http://www.gnu.org/licenses/gpl.txt |
||
75 | // |
||
76 | //***************************************************************************** |
||
77 | //@{ |
||
78 | |||
79 | #ifndef CMDLINE_H |
||
80 | #define CMDLINE_H |
||
81 | |||
82 | #include "global.h" |
||
83 | |||
84 | // constants/macros/typdefs |
||
85 | typedef void (*CmdlineFuncPtrType)(void); |
||
86 | |||
87 | // functions |
||
88 | |||
89 | //! initalize the command line system |
||
90 | void cmdlineInit(void); |
||
91 | |||
92 | //! add a new command to the database of known commands |
||
93 | // newCmdString should be a null-terminated command string with no whitespace |
||
94 | // newCmdFuncPtr should be a pointer to the function to execute when |
||
95 | // the user enters the corresponding command tring |
||
96 | void cmdlineAddCommand(u08* newCmdString, CmdlineFuncPtrType newCmdFuncPtr); |
||
97 | |||
98 | //! sets the function used for sending characters to the user terminal |
||
99 | void cmdlineSetOutputFunc(void (*output_func)(unsigned char c)); |
||
100 | |||
101 | //! call this function to pass input charaters from the user terminal |
||
102 | void cmdlineInputFunc(unsigned char c); |
||
103 | |||
104 | //! call this function in your program's main loop |
||
105 | void cmdlineMainLoop(void); |
||
106 | |||
107 | // internal commands |
||
108 | void cmdlineRepaint(void); |
||
109 | void cmdlineDoHistory(u08 action); |
||
110 | void cmdlineProcessInputString(void); |
||
111 | void cmdlinePrintPrompt(void); |
||
112 | void cmdlinePrintError(void); |
||
113 | |||
114 | // argument retrieval commands |
||
115 | //! returns a string pointer to argument number [argnum] on the command line |
||
116 | u08* cmdlineGetArgStr(u08 argnum); |
||
117 | //! returns the decimal integer interpretation of argument number [argnum] |
||
118 | long cmdlineGetArgInt(u08 argnum); |
||
119 | //! returns the hex integer interpretation of argument number [argnum] |
||
120 | long cmdlineGetArgHex(u08 argnum); |
||
121 | |||
122 | #endif |
||
123 | //@} |
Powered by WebSVN v2.8.3