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

# Command-line Implementation (cmdline.c)
[General Libraries]

## Detailed Description

     #include "cmdline.h"

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.

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 *****

## Typedefs
typedef void(* | CmdlineFuncPtrType )(void)
## Functions
void | cmdlineInit (void)
| initalize the command line system
void | cmdlineAddCommand (u08 *newCmdString, CmdlineFuncPtrType newCmdFuncPtr)
| add a new command to the database of known commands
void | cmdlineSetOutputFunc (void(*output_func)(unsigned char c))
| sets the function used for sending characters to the user terminal
void | cmdlineInputFunc (unsigned char c)
| call this function to pass input charaters from the user terminal
void | cmdlineMainLoop (void)
| call this function in your program's main loop
void | cmdlineRepaint (void)
void | cmdlineDoHistory (u08 action)
void | cmdlineProcessInputString (void)
void | cmdlinePrintPrompt (void)
void | cmdlinePrintError (void)
u08 * | cmdlineGetArgStr (u08 argnum)
| returns a string pointer to argument number [argnum] on the command line
long | cmdlineGetArgInt (u08 argnum)
| returns the decimal integer interpretation of argument number [argnum]
long | cmdlineGetArgHex (u08 argnum)
| returns the hex integer interpretation of argument number [argnum]