Basic support for command line processing. More...

#include <bsp430/core.h>

Data Structures
struct	sBSP430cliCommandLink

struct	sBSP430cliCompletionHelper

struct	sBSP430cliCompletionHelperStrings

struct	sBSP430cliCommand

union	sBSP430cliCommand::uParam

struct	sBSP430cliMatchCallback

struct	sBSP430cliCompletionData

Macros
#define	configBSP430_CLI_COMMAND_COMPLETION 0

#define	configBSP430_CLI_COMMAND_COMPLETION_HELPER 0

#define	BSP430_CLI_CONSOLE_BUFFER_SIZE 0

#define	BSP430_CLI_CONSOLE_BUFFER_MAX_COMPLETIONS 5

Typedefs
typedef struct sBSP430cliCommandLink	sBSP430cliCommandLink

typedef void(*	vBSP430cliCompletionHelper) (const struct sBSP430cliCompletionHelper self, const char argstr, size_t argstr_len, struct sBSP430cliCompletionData *cdp)

typedef struct sBSP430cliCompletionHelper	sBSP430cliCompletionHelper

typedef struct sBSP430cliCompletionHelperStrings	sBSP430cliCompletionHelperStrings

typedef int(*	iBSP430cliHandlerFunction) (struct sBSP430cliCommandLink chain, void param, const char *argstr, size_t argstr_len)

typedef int(*	iBSP430cliSimpleHandler) (const char *argstr)

typedef struct sBSP430cliCommand	sBSP430cliCommand

typedef struct sBSP430cliMatchCallback	sBSP430cliMatchCallback

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

typedef enum eBSP430cliConsole	eBSP430cliConsole

typedef struct sBSP430cliCompletionData	sBSP430cliCompletionData

Enumerations
enum	eBSP430cliErrorType { eBSP430_CLI_ERR_NONE, eBSP430_CLI_ERR_Config, eBSP430_CLI_ERR_Missing, eBSP430_CLI_ERR_Unrecognized, eBSP430_CLI_ERR_MultiMatch, eBSP430_CLI_ERR_Invalid, eBSP430_CLIERRORTYPES }

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
const char *	xBSP430cliNextToken (const char *commandp, size_t remainingp, size_t *lenp)

const char *	xBSP430cliNextQToken (const char *commandp, size_t remainingp, size_t *lenp)

void	vBSP430cliCompletionHelperStrings (const struct sBSP430cliCompletionHelper self, const char argstr, size_t argstr_len, struct sBSP430cliCompletionData *cdp)

const char const	xBSP430cliHelperStringsExtract (const struct sBSP430cliCompletionHelperStrings chsp, const char argstrp, size_t argstr_lenp)

int	iBSP430cliMatchCommand (const sBSP430cliCommand cmds, const char command, size_t command_len, const sBSP430cliCommand *matchp, sBSP430cliMatchCallback match_callback, const char *argstrp, size_t argstr_lenp)

int	iBSP430cliExecuteCommand (const sBSP430cliCommand cmds, void param, const char *command)

int	iBSP430cliParseCommand (const sBSP430cliCommand cmds, void param, const char *command, iBSP430cliHandlerFunction chain_handler, iBSP430cliHandlerFunction handler)

int	iBSP430cliStoreExtractedI (const char *argstrp, size_t argstr_lenp, int *destp)

int	iBSP430cliStoreExtractedUI (const char *argstrp, size_t argstr_lenp, unsigned int *destp)

int	iBSP430cliStoreExtractedL (const char *argstrp, size_t argstr_lenp, long *destp)

int	iBSP430cliStoreExtractedUL (const char *argstrp, size_t argstr_lenp, unsigned long *destp)

int	iBSP430cliHandlerSimple (sBSP430cliCommandLink chain, void param, const char *argstr, size_t argstr_len)

int	iBSP430cliHandlerStoreI (struct sBSP430cliCommandLink chain, void param, const char *argstr, size_t argstr_len)

int	iBSP430cliHandlerStoreUI (struct sBSP430cliCommandLink chain, void param, const char *argstr, size_t argstr_len)

int	iBSP430cliHandlerStoreL (struct sBSP430cliCommandLink chain, void param, const char *argstr, size_t argstr_len)

int	iBSP430cliHandlerStoreUL (struct sBSP430cliCommandLink chain, void param, const char *argstr, size_t argstr_len)

void	vBSP430cliSetDiagnosticFunction (iBSP430cliDiagnosticFunction diagnostic_function)

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

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)

sBSP430cliCommandLink *	xBSP430cliReverseChain (sBSP430cliCommandLink *chain)

void	vBSP430cliCompletionHelperCallback (sBSP430cliCompletionData cdp, const char candidate)

const char *	xBSP430cliConsoleBuffer (void)

void	vBSP430cliConsoleBufferClear (void)

int	iBSP430cliConsoleBufferExtend (const char *text, size_t len)

int	iBSP430cliConsoleBufferProcessInput (void)

int	iBSP430cliConsoleBufferConsumeEscape (int flags)

int	iBSP430cliCommandCompletion (sBSP430cliCompletionData *cdp)

int	iBSP430cliConsoleBufferCompletion (const sBSP430cliCommand command_set, const char *commandp)

Detailed Description

Basic support for command line processing.

This module provides several major features. This page documents the fundamental structures used by applications to register and search among available commands. The core structure is sBSP430cliCommand, which associates a command name (e.g., config) with a handler function, optional descriptive text, and links to sibling and child commands to support a hierarchy of application-specific capabilities.

Given a string command line, other functions parse the command to identify a specific function and invoke it with the unparsed remainder as function-specific arguments. The application can also register a diagnostic function to handle errors discovered during command parsing.

Supporting facilities also provided by this module are documented in these pages:

Console-based Command Line User Interface

Extracting Data from User Input

Context-Sensitive Completion of 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

Typedef Documentation

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

Type for a function that reports errors processing commands.

The command processing infrastructure can be customized to diagnose errors by implementing a function meeting this interface and registering it with the infrastructure through vBSP430cliSetDiagnosticFunction().

Parameters

chain	the chain of command links that did not produce an error
errtype	the type of error discovered
argstr	the remainder of the command string at the point of error
argstr_len	the length of `argstr`

Returns: the value of -(int)errtype

typedef int(* iBSP430cliHandlerFunction) (struct sBSP430cliCommandLink *chain, void *param, const char *argstr, size_t argstr_len)

Type for a function that implements a command.

Parameters

cmd	a pointer to the command structure that is being executed
argstr	any additional arguments remaining unprocessed after reaching this command
argstr_len	the length of `argstr` in characters.

Returns: a context-specific value.

typedef int(* iBSP430cliSimpleHandler) (const char *argstr)

Type for a command handler that needs only the remainder of the command string.

When the sBSP430cliCommand::handler field is set to this handler, the corresponding sBSP430cliCommand::uParam::simple_handler field should be the address of a conforming function which will be invoked.

Parameters

argstr the remainder of the command string

typedef struct sBSP430cliCommand sBSP430cliCommand

The definition of a command, including the token that identifies it, optional help, subordinate and sibling command structures, and the handler that implements the operation given user input.

typedef struct sBSP430cliCommandLink sBSP430cliCommandLink

Link in a command chain.

When a command is executed from a string representation, each initial token that can be uniquely identified as a command is extracted. If the identified command definition has child commands and the command string has additional tokens, the interpreter creates a link structure on the stack referencing the command definition and recurses on the remainder of the command string. These link structures create a chain that can be used by the final operation to extract information from higher layers of the command.

typedef struct sBSP430cliMatchCallback sBSP430cliMatchCallback

Callback support for iBSP430cliMatchCommand(). In addition to providing a place to store the function that is called, this structure may be followed in memory by application-specific memory, using the techniques in Providing Extended Information to the Callback.

Enumeration Type Documentation

enum eBSP430cliErrorType

A set of values identifying errors that are detected by the command parsing infrastructure. Generally an error detected in parsing is reflected by a negative return value, where the positive value is the integral value of one of these enumeration tags.

Enumerator
eBSP430_CLI_ERR_NONE	An unused tag with value zero.
eBSP430_CLI_ERR_Config	A mis-configured command structure has been found. Examples include a handler that needs to store a value extracted from the command but was not told where to place it.
eBSP430_CLI_ERR_Missing	Returned when a (sub-)command is required, but the command string has no more tokens.
eBSP430_CLI_ERR_Unrecognized	Returned when a token in the command string is required to identify a (sub-)command, but is not a prefix of any acceptable command.
eBSP430_CLI_ERR_MultiMatch	Returned when a token does not uniquely identify a command among the set of acceptable commands.
eBSP430_CLI_ERR_Invalid	Returned when a token in the command string is rejected by the processing command.
eBSP430_CLIERRORTYPES	A sentinal value strictly greater than any valid enumeration tag

Function Documentation

int iBSP430cliConsoleBufferConsumeEscape ( int flags )

Consume any pending escape sequences recorded in flags.

This utility function allows applications that perform console input but do not support escape sequences to discard them without having to implement the escape state machine or incorrectly processing the tail of an escape sequence as text.

If flags on entry already has no set bits in eBSP430cliConsole_ANY_ESCAPE then flags is returned without change or delay. Otherwise this function will block until the remainder of the escape sequence has been entered and consumed.

The escape sequence is not returned to the caller.

Parameters

flags A value returned by iBSP430cliConsoleBufferProcessInput_ni()

Returns: flags with eBSP430cliConsole_ANY_ESCAPE zero after consuming the necessary characters to complete the escape sequence.

Warning: This function may enable interrupts and sleep until its completion conditions are met.

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

int iBSP430cliExecuteCommand	(	const sBSP430cliCommand *	cmds,
		void *	param,
		const char *	command
	)

Entrypoint to command execution.

Parameters

cmds	the first in a sequence of sibling commands that may appear at the beginning of the parsed command string.
param	A user-provided parameter passed to the handler of the recognized command.
command	A nul-terminated text representation of a command comprising whitespace-separated tokens. The first token is extracted and used to identify a unique command within the siblings of `cmds`. If a unique command is identified, its sBSP430cliCommand::handler function is invoked, providing a sBSP430cliCommandLink reference identifying the command itself, the provided `param` argument, and the remainder of the `command` string after having stripped off the initial token.

Returns: a negative error code if a unique command is not identifiable from the first token in command, otherwise the value returned by the sBSP430cliCommand::handler.

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

int iBSP430cliHandlerSimple	(	sBSP430cliCommandLink *	chain,
		void *	param,
		const char *	argstr,
		size_t	argstr_len
	)

Handler to invoke a simple command

The chain->cmd->param.simple_handler field should be the iBSP430cliSimpleHandler that is to be invoked.

See iBSP430cliHandlerFunction().

Parameters

chain	ignored
param	ignored
argstr	passed to iBSP430cliSimpleHandler
argstr_len	ignored

Returns: value returned by simple handler.

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

int iBSP430cliMatchCommand	(	const sBSP430cliCommand *	cmds,
		const char *	command,
		size_t	command_len,
		const sBSP430cliCommand **	matchp,
		sBSP430cliMatchCallback *	match_callback,
		const char **	argstrp,
		size_t *	argstr_lenp
	)

A utility function to extract the next command in the parsed string.

The goal here is to extract a non-empty token from the beginning of the provided command (after any leading whitespace), and match it as a prefix of a uniquely identified command in cmds. If this succeeds, we can go on to process the remainder of the command line, which is returned.

Parameters

cmds	the first in a sequence of sibling commands that may appear at the beginning of the remainder of the command string. This must not be a null pointer.
command	the unprocessed remainder of the command string. If there is no non-empty token in what remains, `match_cb` (if provided) is invoked on all commands in `cmds`, and the number of available commands is returned as a negative number.
command_len	the number of characters in `command`, possibly including leading and trailing whitespace.
matchp	an optional pointer to where the uniquely identified next command should be stored. If `matchp` is null, no action is taken; otherwise if a unique command could be identified the pointer to that command is stored in `matchp`; otherwise a null pointer is stored in `matchp`.
match_callback	an optional callback that is invoked on each matching command. If null, no action is taken; otherwise when the key of a command in `cmds` has the first token of `command` as a prefix `match_callback()` is invoked on that command. The primary use of this parameter is to determine the potential matching commands for the purposes of diagnostics or command completion.
argstrp	if null no action is taken, otherwise the pointer to the remainder of `command` after the initial token has been removed is stored in `*argstrp`.
argstr_lenp	if null no action is taken, otherwise the length of the string (that would be) stored in `argstrp` is stored in `argstr_lenp`.

Returns: the number of commands in cmds for which the first token of command was a prefix, or a negative number if command is empty (disregarding whitespace) so no prefix could be identified.

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

A diagnostic function that returns the error code.

See iBSP430cliDiagnosticFunction.

int iBSP430cliParseCommand	(	const sBSP430cliCommand *	cmds,
		void *	param,
		const char *	command,
		iBSP430cliHandlerFunction	chain_handler,
		iBSP430cliHandlerFunction	handler
	)

Entrypoint to command parsing.

This is like iBSP430cliExecuteCommand(), except that instead of executing the handlers in the command definitions, the chain of parent commands is constructed and when no further subcommands are identified the caller-provided function is invoked on the results.

Parameters

cmds	as with iBSP430cliExecuteCommand()
param	as with iBSP430cliExecuteCommand()
command	as with iBSP430cliExecuteCommand()
chain_handler	optional handler function to invoke on an interior chain node command chain and remaining arguments prior to continuing the chain on a child command set
handler	the handler function to execute on the fully-resolved command chain and remaining arguments

Returns: the value returned by the handler function

Examples:: utility/cli/main.c.

void vBSP430cliSetDiagnosticFunction ( iBSP430cliDiagnosticFunction diagnostic_function )

Register a diagnostic function.

The command processing infrastructure will detect parsing errors and return an error code to the user application, but the context of those errors will have been lost. Application code may register a function like iBSP430cliConsoleDiagnostic() which will display useful information to allow the user to correct the command and resubmit it.

Parameters

diagnostic_function the function to be registered. If a null pointer is provided, iBSP430cliNullDiagnostic will be used.

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

sBSP430cliCommandLink* xBSP430cliReverseChain ( sBSP430cliCommandLink * chain )

Reverse a command chain.

The chain constructed during command parsing leads from the deepest command to the outermost command. In some situations, such as displaying a diagnostic or the canonical representation of the command, it is helpful to walk it in outer-to-inner order.

Unless the caller knows the chain is not to be consulted again, it is advisable to re-invoke this function after the forward walk, so the links are restored to their original direction.

Parameters

chain A chain from the end of a command up to its beginning.

Returns: The reversed chain

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation