---

/cmdline.h

/*! \file cmdline.c \brief Command-Line Interface Library. */
//*****************************************************************************
//
// File Name    : 'cmdline.c'
// 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
//
// Description  :
//      This Command-Line interface library is meant to provide a reusable
//  terminal-like user interface much like a DOS command line or UNIX terminal.
//
//  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

---