library

/*! \file cmdline.h \brief Command-Line Interface Library. */
//*****************************************************************************
//
// File Name    : 'cmdline.h'
// Title                : Command-Line Interface Library
// Author               : Pascal Stang - Copyright (C) 2003
// Created              : 2003.07.16
// Revised              : 2003.07.16
// Version              : 0.1
// Target MCU   : Atmel AVR Series
// Editor Tabs  : 4
//
///     \ingroup general
/// \defgroup cmdline Command-line Implementation (cmdline.c)
/// \code #include "cmdline.h" \endcode
/// \par Overview
///             This Command-Line interface library is meant to provide a reusable
///     terminal-like user interface much like a DOS command line or UNIX terminal.
///     A terminal with VT100 support is assumed on the user's end.  Common
///     line-editing is supported, including backspace, arrow keys, and even a
/// small command-history buffer.
///
///     \note One can imagine more efficient ways to implement the command and 
///             function database contained in this library, however, this is a decent
///             and functional first cut.  I may someday get around to making some
///             improvements.
///
/// \par Operation
///     The cmdline library does the following things for you:
///             - Prints command prompts
///             - Gathers a command string from the user (with editing features)
///             - Parses the command string when the user presses [ENTER]
///             - Compares the entered command to the command database
///               -- Executes the corresponding function if a match is found
///               -- Reports an error if no match is found
///             -Provides functions to retrieve the command arguments:
///               --as strings
///               --as decimal integers
///               --as hex integers
///
///     Supported editing features include:
///             - Backspace support
///             - Mid-line editing, inserting and deleting (left/right-arrows)
///             - Command History (up-arrow) (currently only one command deep)
///
///     To use the cmdline system, you will need to associate command strings
///     (commands the user will be typing) with your function that you wish to have
///     called when the user enters that command.  This is done by using the
///     cmdlineAddCommand() function.
///
///     To setup the cmdline system, you must do these things:
///             - Initialize it: cmdlineInit()
///             - Add one or more commands to the database: cmdlineAddCommand()
///             - Set an output function for your terminal: cmdlineSetOutputFunc()
///
///     To operate the cmdline system, you must do these things repeatedly:
///             - Pass user input from the terminal to: cmdlineSetOutputFunc()
///             - Call cmdlineMainLoop() from your program's main loop
///
///     The cmdline library does not assume an input or output device, but can be
///     configured to use any user function for output using cmdlineSetOutputFunc()
///     and accepts input by calling cmdlineInputFunc().  This means the cmdline
///     library can operate over any interface including UART (serial port),
///     I2c, ethernet, etc.
///
///     ***** FOR MORE INFORMATION ABOUT USING cmdline SEE THE AVRLIB EXAMPLE *****
///     ***** CODE IN THE avrlib/examples DIRECTORY                           *****
//
// NOTE: This code is currently below version 1.0, and therefore is considered
// to be lacking in some functionality or documentation, or may not be fully
// tested.  Nonetheless, you can expect most functions to work.
//
// This code is distributed under the GNU Public License
//              which can be found at http://www.gnu.org/licenses/gpl.txt
//
//*****************************************************************************
//@{

#ifndef CMDLINE_H
#define CMDLINE_H

#include "global.h"

// constants/macros/typdefs
typedef void (*CmdlineFuncPtrType)(void);

// functions

//! initalize the command line system
void cmdlineInit(void);

//! add a new command to the database of known commands
// newCmdString should be a null-terminated command string with no whitespace
// newCmdFuncPtr should be a pointer to the function to execute when
//   the user enters the corresponding command tring
void cmdlineAddCommand(u08* newCmdString, CmdlineFuncPtrType newCmdFuncPtr);

//! sets the function used for sending characters to the user terminal
void cmdlineSetOutputFunc(void (*output_func)(unsigned char c));

//! call this function to pass input charaters from the user terminal
void cmdlineInputFunc(unsigned char c);

//! call this function in your program's main loop
void cmdlineMainLoop(void);

// internal commands
void cmdlineRepaint(void);
void cmdlineDoHistory(u08 action);
void cmdlineProcessInputString(void);
void cmdlinePrintPrompt(void);
void cmdlinePrintError(void);

// argument retrieval commands
//! returns a string pointer to argument number [argnum] on the command line
u08* cmdlineGetArgStr(u08 argnum);
//! returns the decimal integer interpretation of argument number [argnum]
long cmdlineGetArgInt(u08 argnum);
//! returns the hex integer interpretation of argument number [argnum]
long cmdlineGetArgHex(u08 argnum);

#endif
//@}