cmdline.h

Go to the documentation of this file.

/*! \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
//@}

---