Context-Sensitive Completion of User Input

bsp430/utility/cli.h data structures and functions for auto-completion of user input. More...

Data Structures
struct	sBSP430cliCompletionHelper
struct	sBSP430cliCompletionHelperStrings
struct	sBSP430cliCompletionData

Macros
#define	configBSP430_CLI_COMMAND_COMPLETION   0
#define	configBSP430_CLI_COMMAND_COMPLETION_HELPER   0
#define	BSP430_CLI_CONSOLE_BUFFER_MAX_COMPLETIONS   5

Typedefs
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 struct sBSP430cliCompletionData	sBSP430cliCompletionData

Functions
void	vBSP430cliCompletionHelperStrings (const struct sBSP430cliCompletionHelper *self, const char *argstr, size_t argstr_len, struct sBSP430cliCompletionData *cdp)
void	vBSP430cliCompletionHelperCallback (sBSP430cliCompletionData *cdp, const char *candidate)
int	iBSP430cliCommandCompletion (sBSP430cliCompletionData *cdp)
int	iBSP430cliConsoleBufferCompletion (const sBSP430cliCommand *command_set, const char **commandp)

Detailed Description

bsp430/utility/cli.h data structures and functions for auto-completion of user input.

The core command-line interface of BSP430 is useful, but frustrating when whole commands must be remembered and typed exactly. The features in this group reference the standard data structures that describe commands and use them to complete commands given the first few letters, or (when a unique command is not selected) provide hints about acceptable input in context.

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

Macro Definition Documentation

#define BSP430_CLI_CONSOLE_BUFFER_MAX_COMPLETIONS   5

The maximum number of candidate completions returned by iBSP430cliConsoleBufferCompletion().

The value must be at least 1.

Defaulted:

The value here is superseded by previously encountered definitions.

#define configBSP430_CLI_COMMAND_COMPLETION   0

Define to a true value to request that command completion be enabled.

When command completion is enabled, a horizontal tab in command input causes a flag to be returned to the caller indicating a need to auto-fill the command buffer.

C Preprocessor Only:

This macro may have a value that restricts its use to C preprocessor conditional directives.

Defaulted:

The value here is superseded by previously encountered definitions.

#define configBSP430_CLI_COMMAND_COMPLETION_HELPER   0

Define to a true value to support customized completion.

Default command completion will identify candidates using keys in a chain of subcommands registered as a child of a command. In some contexts, the set of valid completions may not be a command; for example, a command may accept a set of peripheral register names. Because support for these cases incurs overhead in all command structures and is uncommon, it must be explicitly enabled.

Setting this to a true value causes the sBSP430cliCommand::completion_helper field to be declared within the structure. That in turn may be set to an instance of the sBSP430cliCompletionHelper structure, which in turn will be invoked to provide completion services in preference to using subcommands.

C Preprocessor Only:

This macro may have a value that restricts its use to C preprocessor conditional directives.

Defaulted:

The value here is superseded by previously encountered definitions.

Dependency:

configBSP430_CLI_COMMAND_COMPLETION

Typedef Documentation

typedef struct sBSP430cliCompletionData sBSP430cliCompletionData

Data structure used to communicate between user applications and the command completion infrastructure.

This is a parameter to iBSP430cliCommandCompletion().

typedef struct sBSP430cliCompletionHelper sBSP430cliCompletionHelper

Structure encoding information to identify candidate completions.

When configBSP430_CLI_COMMAND_COMPLETION_HELPER is true sBSP430cliCommand::completion_helper is present in every command definition to support customized completion for commands that do not have subcommands.

This base structure contains only the pointer to the function that implements the completion. A pointer to the structure instance is passed to the function, and the techniques of Providing Extended Information to the Callback may be used to provide additional information. See sBSP430cliCompletionHelperStrings.

typedef struct sBSP430cliCompletionHelperStrings sBSP430cliCompletionHelperStrings

Structure supporting completion based on a static list of acceptable strings.

One of the most common cases for non-command completion is selection among a set of permitted tokens. This structure encodes the necessary information to convey those tokens to vBSP430cliCompletionHelperStrings, which itself should be stored as completion_helper.helper.

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

A function that implements customized completion.

This is invoked by iBSP430cliCommandCompletion() when completion is required for a command that has a registered completion helper. It in turn should invoke vBSP430cliCompletionHelperCallback() to register acceptable tokens with the completion infrastructure.

Parameters

self	the helper object registered within the command. The techniques of Providing Extended Information to the Callback may be used to provide command-specific context.
argstr	the text, including leading spaces, that comprise the remainder of the input. One or more tokens from this should be used to effect completion.
argstr_len	the number of valid characters in argstr
cdp	the aggregation of completion data

Dependency:

configBSP430_CLI_COMMAND_COMPLETION_HELPER

Function Documentation

int iBSP430cliCommandCompletion

(

sBSP430cliCompletionData *

cdp

)

Interface to command completion.

This function traverses the command in cdp->command in the context of cdp->command_set and identifies text that would unambiguously extend the command, or where ambiguity is present a set of candidate text that could complete the next step of the command.

This version simply does the calculations. For an example, or to use this within a standard CLI console environment, see iBSP430cliConsoleBufferCompletion().

Parameters

cdp	Pointer to the structure used to pass in and return information about the completion. On entry, the command, command_set, returned_candidates, and max_returned_candidates fields must be set. All others are set in the process of executing this function.

Returns

a bitset of flags indicating caller update responsibilities, potentially including eBSP430cliConsole_COMPLETE_SPACE, eBSP430cliConsole_REPAINT, and eBSP430cliConsole_REPAINT_BEL.

Dependency:

configBSP430_CLI_COMMAND_COMPLETION

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

Complete the command currently in the console buffer

This is a wrapper around iBSP430cliCommandCompletion() which applies the results from that function. If the completion can be uniquely identified, the text is added to the command buffer; the text is also printed to the console unless the returned flags indicate the caller is for repainting. If alternatives are available, a prompt will be emitted showing available completions.

Parameters

command_set	the set of commands acceptable at the top level of the command interpreter.
commandp	a pointer to storage for a command pointer. On input, this should be NULL or pre-initialized with the return value from xBSP430cliConsoleBuffer(). On exit, it will be updated to the new return value from xBSP430cliConsoleBuffer().

Returns

a bitset of flags indicating caller update responsibilities, potentially including eBSP430cliConsole_REPAINT, and eBSP430cliConsole_REPAINT_BEL.

Dependency:

BSP430_CONSOLE

Dependency:

BSP430_CLI_CONSOLE_BUFFER_SIZE

Dependency:

configBSP430_CLI_COMMAND_COMPLETION

Examples:

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

void vBSP430cliCompletionHelperCallback	(	sBSP430cliCompletionData *	cdp,
		const char *	candidate
	)

Register an acceptable candidate for command completion.

This function calculates the new common prefix and updates the list of candidate completions to include the provided new candidate. It is invoked by iBSP430cliCommandCompletion() indirectly through the use of internal and external sBSP430cliCompletionHelper instances.

Parameters

cdp	the aggregation of completion data
candidate	a token that would be acceptable at the current point of processing

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

A function that provides completion where a fixed set of tokens is permitted.

Specifically, this extracts the first token of argstr and compares it against each string in the sBSP430cliCompletionHelperStrings structure of which self is the first member. Each string for which argstr is a prefix is registered as an acceptable completion in cdp.

See sBSP430cliCompletionHelperStrings.

Parameters

self	as in vBSP430cliCompletionHelper
argstr	as in vBSP430cliCompletionHelper
argstr_len	as in vBSP430cliCompletionHelper
cdp	as in vBSP430cliCompletionHelper

Dependency:

configBSP430_CLI_COMMAND_COMPLETION_HELPER

Examples:

utility/cli/main.c.