Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

# cmdline.h

Go to the documentation of this file.

    00001 /*! \file cmdline.h \brief Command-Line Interface Library. */
    00002 //*****************************************************************************
    00003 //
    00004 // File Name    : 'cmdline.h'
    00005 // Title        : Command-Line Interface Library
    00006 // Author       : Pascal Stang - Copyright (C) 2003
    00007 // Created      : 2003.07.16
    00008 // Revised      : 2003.07.16
    00009 // Version      : 0.1
    00010 // Target MCU   : Atmel AVR Series
    00011 // Editor Tabs  : 4
    00012 //
    00013 /// \ingroup general
    00014 /// \defgroup cmdline Command-line Implementation (cmdline.c)
    00015 /// \code #include "cmdline.h" \endcode
    00016 /// \par Overview
    00017 ///     This Command-Line interface library is meant to provide a reusable
    00018 /// terminal-like user interface much like a DOS command line or UNIX terminal.
    00019 /// A terminal with VT100 support is assumed on the user's end.  Common
    00020 /// line-editing is supported, including backspace, arrow keys, and even a
    00021 /// small command-history buffer.
    00022 ///
    00023 /// \note One can imagine more efficient ways to implement the command and
    00024 ///     function database contained in this library, however, this is a decent
    00025 ///     and functional first cut.  I may someday get around to making some
    00026 ///     improvements.
    00027 ///
    00028 /// \par Operation
    00029 /// The cmdline library does the following things for you:
    00030 ///     - Prints command prompts
    00031 ///     - Gathers a command string from the user (with editing features)
    00032 ///     - Parses the command string when the user presses [ENTER]
    00033 ///     - Compares the entered command to the command database
    00034 ///       -- Executes the corresponding function if a match is found
    00035 ///       -- Reports an error if no match is found
    00036 ///     -Provides functions to retrieve the command arguments:
    00037 ///       --as strings
    00038 ///       --as decimal integers
    00039 ///       --as hex integers
    00040 ///
    00041 /// Supported editing features include:
    00042 ///     - Backspace support
    00043 ///     - Mid-line editing, inserting and deleting (left/right-arrows)
    00044 ///     - Command History (up-arrow) (currently only one command deep)
    00045 ///
    00046 /// To use the cmdline system, you will need to associate command strings
    00047 /// (commands the user will be typing) with your function that you wish to have
    00048 /// called when the user enters that command.  This is done by using the
    00049 /// cmdlineAddCommand() function.
    00050 ///
    00051 /// To setup the cmdline system, you must do these things:
    00052 ///     - Initialize it: cmdlineInit()
    00053 ///     - Add one or more commands to the database: cmdlineAddCommand()
    00054 ///     - Set an output function for your terminal: cmdlineSetOutputFunc()
    00055 ///
    00056 /// To operate the cmdline system, you must do these things repeatedly:
    00057 ///     - Pass user input from the terminal to: cmdlineSetOutputFunc()
    00058 ///     - Call cmdlineMainLoop() from your program's main loop
    00059 ///
    00060 /// The cmdline library does not assume an input or output device, but can be
    00061 /// configured to use any user function for output using cmdlineSetOutputFunc()
    00062 /// and accepts input by calling cmdlineInputFunc().  This means the cmdline
    00063 /// library can operate over any interface including UART (serial port),
    00064 /// I2c, ethernet, etc.
    00065 ///
    00066 /// ***** FOR MORE INFORMATION ABOUT USING cmdline SEE THE AVRLIB EXAMPLE *****
    00067 /// ***** CODE IN THE avrlib/examples DIRECTORY                           *****
    00068 //
    00069 // NOTE: This code is currently below version 1.0, and therefore is considered
    00070 // to be lacking in some functionality or documentation, or may not be fully
    00071 // tested.  Nonetheless, you can expect most functions to work.
    00072 //
    00073 // This code is distributed under the GNU Public License
    00074 //      which can be found at http://www.gnu.org/licenses/gpl.txt
    00075 //
    00076 //*****************************************************************************
    00077 //@{
    00078
    00079 #ifndef CMDLINE_H
    00080 #define CMDLINE_H
    00081
    00082 #include "global.h"
    00083
    00084 // constants/macros/typdefs
    00085 typedef void (*CmdlineFuncPtrType)(void);
    00086
    00087 // functions
    00088
    00089 //! initalize the command line system
    00090 void cmdlineInit(void);
    00091
    00092 //! add a new command to the database of known commands
    00093 // newCmdString should be a null-terminated command string with no whitespace
    00094 // newCmdFuncPtr should be a pointer to the function to execute when
    00095 //   the user enters the corresponding command tring
    00096 void cmdlineAddCommand(u08* newCmdString, CmdlineFuncPtrType newCmdFuncPtr);
    00097
    00098 //! sets the function used for sending characters to the user terminal
    00099 void cmdlineSetOutputFunc(void (*output_func)(unsigned char c));
    00100
    00101 //! call this function to pass input charaters from the user terminal
    00102 void cmdlineInputFunc(unsigned char c);
    00103
    00104 //! call this function in your program's main loop
    00105 void cmdlineMainLoop(void);
    00106
    00107 // internal commands
    00108 void cmdlineRepaint(void);
    00109 void cmdlineDoHistory(u08 action);
    00110 void cmdlineProcessInputString(void);
    00111 void cmdlinePrintPrompt(void);
    00112 void cmdlinePrintError(void);
    00113
    00114 // argument retrieval commands
    00115 //! returns a string pointer to argument number [argnum] on the command line
    00116 u08* cmdlineGetArgStr(u08 argnum);
    00117 //! returns the decimal integer interpretation of argument number [argnum]
    00118 long cmdlineGetArgInt(u08 argnum);
    00119 //! returns the hex integer interpretation of argument number [argnum]
    00120 long cmdlineGetArgHex(u08 argnum);
    00121
    00122 #endif
    00123 //@}