Console-based Command Line User Interface

bsp430/utility/cli.h features for interactive user input. More...

Macros
#define	BSP430_CLI_CONSOLE_BUFFER_SIZE   0

Typedefs
typedef enum eBSP430cliConsole	eBSP430cliConsole

Enumerations
enum	eBSP430cliConsole {   eBSP430cliConsole_READY = 0x01, eBSP430cliConsole_REPAINT = 0x02, eBSP430cliConsole_DO_COMPLETION = 0x04, eBSP430cliConsole_PROCESS_ESCAPE = 0x08,   eBSP430cliConsole_IN_ESCAPE = 0x10, eBSP430cliConsole_ANY_ESCAPE = eBSP430cliConsole_PROCESS_ESCAPE | eBSP430cliConsole_IN_ESCAPE, eBSP430cliConsole_REPAINT_BEL = 0x100, eBSP430cliConsole_COMPLETE_SPACE = 0x200 }

Functions
int	iBSP430cliConsoleDiagnostic (sBSP430cliCommandLink *chain, enum eBSP430cliErrorType errtype, const char *argstr, size_t argstr_len)
void	vBSP430cliConsoleDisplayChain (struct sBSP430cliCommandLink *chain, const char *argstr)
void	vBSP430cliConsoleDisplayHelp (const sBSP430cliCommand *cmd)
const char *	xBSP430cliConsoleBuffer (void)
void	vBSP430cliConsoleBufferClear (void)
int	iBSP430cliConsoleBufferExtend (const char *text, size_t len)
int	iBSP430cliConsoleBufferProcessInput (void)

Detailed Description

bsp430/utility/cli.h features for interactive user input.

These features use bsp430/utility/console.h, generally with input buffers enabled, to accept user input at a command line interface. Certain keystrokes including backspace are recognized, allowing primitive editing to be done. Escape sequences are passed back to the application for processing. Display capabilities, including repainting the screen and displaying the accumulated input are the responsibility of the application, but are assisted with functions to provide help on available commands and diagnostics when the infrastructure detects an error in user input.

See Utilities: Command Line Interface for a detailed example demonstrating most capabilities of this module.

Homepage

http://github.com/pabigot/bsp430

Copyright

Copyright 2012-2014, Peter A. Bigot. Licensed under BSD-3-Clause

bsp430/utility/cli.h functions for processing user-provided text.

Macro Definition Documentation

#define BSP430_CLI_CONSOLE_BUFFER_SIZE   0

Specify the size of an internal command buffer for editing.

A non-zero setting for this parameter allocates an internal buffer that is used by iBSP430cliConsoleBufferProcessInput() to aggregate keystrokes and produce a command string.

If the value of this is zero, iBSP430cliConsoleBufferProcessInput() will not be available.

Typedef Documentation

typedef enum eBSP430cliConsole eBSP430cliConsole

Enumeration of bit values returned from iBSP430cliConsoleBufferProcessInput().

Enumeration Type Documentation

enum eBSP430cliConsole

Enumeration of bit values returned from iBSP430cliConsoleBufferProcessInput().

Enumerator
eBSP430cliConsole_READY	Bit set in response if console buffer now holds a completed command. The application should retrieve it using xBSP430cliConsoleBuffer(), process it, then reset the buffer using vBSP430cliConsoleBufferClear(). Note If this bit is set, there may be additional input that has not been processed. After processing the command that is ready the caller should re-invoke iBSP430cliConsoleBufferProcessInput() to complete reading pending input.
eBSP430cliConsole_REPAINT	Bit set in response if caller should repaint the screen in response to keystrokes
eBSP430cliConsole_DO_COMPLETION	Bit set in response if caller should invoke the completion infrastructure based on the current buffer contents.
eBSP430cliConsole_PROCESS_ESCAPE	Bit set in response if an escape character (ESC) has been consumed. The caller should process the remaining input to consume the escape sequence. If the sequence is an ANSI sequence, there are two cases the processing code must recognize: If the character after the ESC is a left bracket (comprising a Control Sequence Introducer, or CSI), the sequence is terminated by an ASCII character in the range 64 to 126. See eBSP430cliConsole_IN_ESCAPE. Otherwise, the consumed ESC is expected to be followed by a single ASCII character in the range 64 to 95. If the caller is uninterested in escape sequences but wishes to be robust if the user generates one, use iBSP430cliConsoleBufferConsumeEscape() to filter them without misinterpreting partial escape sequences as valid input. See also http://en.wikipedia.org/wiki/ANSI_escape_code.
eBSP430cliConsole_IN_ESCAPE	Bit set in flags if system is processing an escape sequence. This flag is not produced by the infrastructure, but is available for use in applications which preserve the console state while processing. Suggested practice is to read the first character after eBSP430cliConsole_PROCESS_ESCAPE has been set, and if that character is recognized as completing a control sequence introducer the application should clear eBSP430cliConsole_PROCESS_ESCAPE, set eBSP430cliConsole_IN_ESCAPE, and continue in escape-processing mode until the entire sequence has been consumed (i.e., a character in the range 64 to 126 is recognized). See also Utilities: Command Line Interface.
eBSP430cliConsole_ANY_ESCAPE	Bit mask for flags indicating that some escape-sequence processing is in effect.
eBSP430cliConsole_REPAINT_BEL	Bit set to signal that the repaint should be followed by a BEL or other indicator. This is normally used to warn the user that the screen content includes changes not directly entered by the user, e.g. completion has been performed.
eBSP430cliConsole_COMPLETE_SPACE	Bit set in response from completion if the application should add a space after whatever text was suggested. (This is a distinct flag because suggested text from the completion infrastructure comes from immutable strings that do not include trailing spaces.)

Function Documentation

int iBSP430cliConsoleBufferExtend	(	const char *	text,
		size_t	len
	)

Append characters to the current console buffer contents.

Characters are taken from src until an end-of-string is encountered or len characters have been appended.

Parameters

text	pointer to the text to be appended
len	number of characters to be appended. To append everything to the end of text, use -1 or another large value.

Returns

the number of characters actually appended, which may be less than len if the console buffer is too small, or text has a NUL before the length is reached.

Dependency:

BSP430_CONSOLE

Dependency:

BSP430_CLI_CONSOLE_BUFFER_SIZE

int iBSP430cliConsoleBufferProcessInput

(

void

)

Process pending console input and produce completed commands.

This function reads data over the console, and stores the characters into an internal buffer allocated when BSP430_CLI_CONSOLE_BUFFER_SIZE is nonzero. Certain keystrokes are recognized as editing commands, as described below.

Keystroke	Function
Backspace (BS)	Erase previous character (if any)
C-l (FF)	Return eBSP430cliConsole_REPAINT
Enter (CR)	Return eBSP430cliConsole_READY
C-u (NAK)	Kill command (resets buffer)
C-w (ETB)	Kill previous word (erases back to space)
Escape (ESC)	Return eBSP430cliConsole_PROCESS_ESCAPE
Tab (HT)	Auto-complete based on legal commands (if enabled)

Note that auto-completion is enabled by configBSP430_CLI_COMMAND_COMPLETION.

When carriage return is pressed, a complete command is recognized, and the function returns even if there is additional data to be consumed.

Returns

zero if all pending input was consumed and no actions are required. A positive result encodes bits from eBSP430cliConsole indicating available commands or other actions that are required.

Dependency:

BSP430_CONSOLE

Dependency:

BSP430_CLI_CONSOLE_BUFFER_SIZE

Examples:

periph/timer/alarm/main.c, rf/cc3000/cli/main.c, and utility/cli/main.c.

int iBSP430cliConsoleDiagnostic	(	sBSP430cliCommandLink *	chain,
		enum eBSP430cliErrorType	errtype,
		const char *	argstr,
		size_t	argstr_len
	)

A diagnostic function that displays on the console.

Normal practice would be to install this using iBSP430cliSetDiagnosticFunction() after configuring the console but before accepting any user input; see Utilities: Command Line Interface.

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

Dependency:

BSP430_CONSOLE

Examples:

periph/timer/alarm/main.c, rf/cc3000/cli/main.c, and utility/cli/main.c.

void vBSP430cliConsoleBufferClear

(

void

)

Clear any current console buffer contents.

Invoke this after having processed a command that was returned by iBSP430cliConsoleBufferProcessInput() so subsequent input begins a new command.

Dependency:

BSP430_CONSOLE

Dependency:

BSP430_CLI_CONSOLE_BUFFER_SIZE

Examples:

periph/timer/alarm/main.c, rf/cc3000/cli/main.c, and utility/cli/main.c.

void vBSP430cliConsoleDisplayChain	(	struct sBSP430cliCommandLink *	chain,
		const char *	argstr
	)

Display the reconstructed command string on the console.

This function is usually invoked in the context of diagnostics to indicate where in the input an error was detected. It prints on the console the sequence of prefix commands encoded within chain, then displays the remaining argument string. (Note that to do this it reverses the chain, then restores it to its original direction before returning.)

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

Parameters

chain	the chain of commands from the innermost to the outermost
argstr	the unprocessed remainder of the original command string

Examples:

utility/cli/main.c.

void vBSP430cliConsoleDisplayHelp

(

const sBSP430cliCommand *

cmd

)

Display the deep command structure on the console.

Nested commands are displayed indented from their parent command.

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

Parameters

cmd	pointer to the first in a sequence of sibling commands

Dependency:

BSP430_CONSOLE

Examples:

periph/timer/alarm/main.c, rf/cc3000/cli/main.c, and utility/cli/main.c.

const char* xBSP430cliConsoleBuffer

(

void

)

Return a pointer to the internal console buffer.

Note

Although the value returned from this function is a constant throughout the life of the program, it is the call to this function that stores the NUL character terminating the command based on data received.

Returns

pointer to the NUL-terminated current contents of the internal command buffer, or NULL if BSP430_CLI_CONSOLE_BUFFER_SIZE is zero.

Examples:

periph/timer/alarm/main.c, rf/cc3000/cli/main.c, and utility/cli/main.c.