Extracting Data from User Input

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

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)
const char *const *	xBSP430cliHelperStringsExtract (const struct sBSP430cliCompletionHelperStrings *chsp, const char **argstrp, size_t *argstr_lenp)
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	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)

Detailed Description

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

These functions provide a unified mechanism to extract command tokens, quoted strings, and integer values from a text sequence obtained through a command line interface, whether interactive or batch.

The interface assumes that command input is immutable; consequently the tokens are identified by a pointer into the original input, and a length identifying how many subsequent characters comprise the complete token.

In addition to routines that extract data from the input, there are implementations for sBSP430cliCommand::handler that support storing integer values directly into addresses, removing the need for custom code to process the command.

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

Function Documentation

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

Handler to store a signed 16-bit integer expressed in text.

See iBSP430cliHandlerFunction() and iBSP430cliStoreI().

Parameters

chain	Pointer to the end of the command chain. chain->cmd->param.ptr is expected to be a int * value.
param	unused
argstr	text representation of a signed 16-bit integer, normally decimal but optionally in hexadecimal (with leading 0x) or octal (with leading 0).
argstr_len	length of the argstr text

Examples:

utility/cli/main.c.

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

Handler to store a signed 32-bit integer expressed in text.

See iBSP430cliHandlerFunction() and iBSP430cliStoreL().

Parameters

chain	Pointer to the end of the command chain. chain->cmd->param.ptr is expected to be a long * value.
param	unused
argstr	text representation of a signed 32-bit integer, normally decimal but optionally in hexadecimal (with leading 0x) or octal (with leading 0).
argstr_len	length of the argstr text

Examples:

utility/cli/main.c.

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

Handler to store an unsigned 16-bit integer expressed in text.

See iBSP430cliHandlerFunction() and iBSP430cliStoreUI().

Parameters

chain	Pointer to the end of the command chain. chain->cmd->param.ptr is expected to be a unsigned int * value.
param	unused
argstr	text representation of an unsigned 16-bit integer, normally decimal but optionally in hexadecimal (with leading 0x) or octal (with leading 0).
argstr_len	length of the argstr text

Examples:

utility/cli/main.c.

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

Handler to store an unsigned 32-bit integer expressed in text.

See iBSP430cliHandlerFunction() and iBSP430cliStoreUL().

Parameters

chain	Pointer to the end of the command chain. chain->cmd->param.ptr is expected to be a unsigned long * value.
param	unused
argstr	text representation of an unsigned 32-bit integer, normally decimal but optionally in hexadecimal (with leading 0x) or octal (with leading 0).
argstr_len	length of the argstr text

Examples:

utility/cli/main.c.

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

Utility to extract and store a signed 16-bit integer expressed in text.

Parameters

argstrp	pointer to a pointer to the text representation of a signed 16-bit integer, normally decimal but optionally in hexadecimal (with leading 0x) or octal (with leading 0). On success *argstrp is updated to point past the consumed integer token.
argstr_lenp	pointer to the length of the *argstrp text. On success the *argstr_lenp is updated to hold the remaining length of the string.
destp	pointer to where the extracted and converted value should be stored.

Returns

0 if a valid value can be extracted and converted from the head of *argstr; a negative value if the string has no token or the conversion was unsuccessful.

Examples:

rf/cc3000/cli/main.c, and utility/cli/main.c.

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

Utility to extract and store a signed 32-bit integer expressed in text.

Parameters

argstrp	pointer to a pointer to the text representation of a signed 32-bit integer, normally decimal but optionally in hexadecimal (with leading 0x) or octal (with leading 0). On success *argstrp is updated to point past the consumed integer token.
argstr_lenp	pointer to the length of the *argstrp text. On success the *argstr_lenp is updated to hold the remaining length of the string.
destp	pointer to where the extracted and converted value should be stored.

Returns

0 if a valid value can be extracted and converted from the head of *argstr; a negative value if the string has no token or the conversion was unsuccessful.

Examples:

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

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

Utility to extract and store an unsigned 16-bit integer expressed in text.

Parameters

argstrp	pointer to a pointer to the text representation of a signed 16-bit integer, normally decimal but optionally in hexadecimal (with leading 0x) or octal (with leading 0). On success *argstrp is updated to point past the consumed integer token.
argstr_lenp	pointer to the length of the *argstrp text. On success the *argstr_lenp is updated to hold the remaining length of the string.
destp	pointer to where the extracted and converted value should be stored.

Returns

0 if a valid value can be extracted and converted from the head of *argstr; a negative value if the string has no token or the conversion was unsuccessful.

Examples:

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

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

Utility to extract and store an unsigned 32-bit integer expressed in text.

Parameters

argstrp	pointer to a pointer to the text representation of an unsigned 32-bit integer, normally decimal but optionally in hexadecimal (with leading 0x) or octal (with leading 0). On success *argstrp is updated to point past the consumed integer token.
argstr_lenp	pointer to the length of the *argstrp text. On success the *argstr_lenp is updated to hold the remaining length of the string.
destp	pointer to where the extracted and converted value should be stored.

Returns

0 if a valid value can be extracted and converted from the head of *argstr; a negative value if the string has no token or the conversion was unsuccessful.

Examples:

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

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

Utility function for user code to use sBSP430cliCompletionHelperStrings.

This function searches for a unique match in the sBSP430cliCompletionHelperStrings::strings array using the first argstr_len chars of argstr. If successfully found, a pointer to the element in sBSP430cliCompletionHelperStrings::strings that matches is returned. This in turn can be used to determine the ordinal position of the match within the array, or to determine the string that was matched.

If *argstrp does not provide a unique prefix among the candidates, a null pointer is returned, and neither *argstrp nor *argstr_lenp are updated.

Parameters

chsp	the record containing the list of acceptable tokens
argstrp	pointer to a pointer to the text used for input. On success, *argstrp is updated to point past the consumed token.
argstr_lenp	pointer to the length of input available at *argstrp. On success, *argstr_lenp is updated to the length of the unconsumed input.

Returns

a pointer to an offset within chsp->strings, or NULL

Examples:

utility/cli/main.c.

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

Get the next token or quoted token in the command string.

Exactly the same as xBSP430cliNextToken() except that if the first non-whitespace character is a single or double quote, all characters to a following single or double quote are taken as the value to be returned. The opening and closing quotes are outside the returned token.

The function delegates to xBSP430cliNextToken() on these conditions:

• the first character is not a quote;
• if there is no matching end quote;
• if the matching end quote is followed by a non-space character

Parameters

commandp	as with xBSP430cliNextToken()
remainingp	as with xBSP430cliNextToken()
lenp	as with xBSP430cliNextToken(). If a quoted token is identified, the length excludes the opening and closing quotes. The pointer may be null if the length of the returned token is not of interest.

Returns

as with xBSP430cliNextToken(). If a quoted token is identified, the return value begins after the opening quote.

Examples:

rf/cc3000/cli/main.c, and utility/cli/main.c.

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

Get the next token in the command string.

Parameters

commandp	pointer to a pointer into an immutable buffer containing a sequence of whitespace-separated tokens. On return it is updated to point to the first whitespace character following the recognized token.
remainingp	pointer to the length of the sequence beginning at *commandp. On return the value has been updated to account for any adjustment to *commandp.
lenp	pointer to the length of the returned token. On return the value is set to the number of valid characters in the token beginning at the returned pointer. The pointer may be null if the length of the returned token is not of interest.

Returns

A pointer to the first character of the first token in *command. If there are no such characters, the pointer is just past the end of *commandp and both *remainingp and *lenp are updated to have value zero.

Examples:

periph/timer/alarm/main.c.