#include <Commander-API.hpp>

Collaboration diagram for Commander:

Classes
struct	API_t
	Structure for command data. More...

struct	systemVariableData_t

union	systemVariablePointer_t

Public Types
enum	debugLevel_t { DEBUG_OFF = 0 , DEBUG_ERROR = 1 , DEBUG_DEBUG = 2 , DEBUG_VERBOSE = 3 }

enum	systemVariableType_t { VARIABLE_FLOAT , VARIABLE_INT , VARIABLE_STRING }
	Enum for system variable type. More...

typedef struct Commander::API_t	API_t
	Structure for command data. More...

typedef CommanderDatabase< API_t >::dataRecord_t	systemCommand_t

typedef CommanderDatabase< systemVariableData_t >::dataRecord_t	systemVariable_t

Public Member Functions
void	attachTreeFunction (systemCommand_t *API_tree_p, uint32_t API_tree_size_p)
	Attach API-tree to the object. More...

bool	init ()
	Initializer. More...

bool	execute (const char cmd, Stream channel_p=NULL, CommandCaller *caller_p=NULL)
	Execution function for Stream response. More...

void	attachDebugChannel (Stream *resp)
	Attach a debug channel to the object. More...

void	printHelp (Stream *out, bool description, bool style=false)
	Print the help text to a specified Stream. More...

bool	enablePipeModuleFunc (char buffer, int bufferSize, commanderPipeChannel pipeChannel_p)
	Enable pipe functionality. More...

void	enableFormatting ()
	Enable formatting. More...

void	disableFormatting ()
	Disable formatting. More...

void	update (char buffer, int bufferSize, Stream channel_p)
	Create a very very simple command lime. More...

bool	commandExists (const char cmd, systemCommand_t *cmd_ptr=NULL)

int	generateHint (const char fraction, char buffer_p, int buffer_size_p)

const char *	getHint (int index, bool only_remaining_chars=false)

Static Public Member Functions
static void	attachVariablesFunction (systemVariable_t *variables_p, uint32_t variables_size_p)
	Attach system variables list to the object. More...

static systemVariable_t *	getSystemVariable (const char *name)
	Get the instance if a system variable by its name. More...

static void	printSystemVariable (Stream channel_p, const char name, int decimalPlaces=2)
	Print the value of a system variable. More...

static void	printSystemVariables (Stream *channel_p)
	Print all the available system variables. More...

static void	setDebugLevel (debugLevel_t debugLevel_p)

static void	printArgumentError (Stream *channel_p)
	Print 'Argument error!' to a specified Serial channel. More...

static bool	inString (const char *source, int index)
	Detect if character is in the string. More...

static int	floatToString (float number, char *buffer, int bufferSize)

Public Attributes
AutoComplete *	lastHint = NULL

const char *	lastCommandHint = NULL

int	lastCommandHintOffset = 0

Static Public Attributes
static const char *	version = COMMANDER_API_VERSION
	Library version string. More...

Private Member Functions
bool	executeCommand (const char *cmd)
	Command execution. More...

int	hasChar (const char *str, char c, bool ignoreString=true)
	Search for a character in a string. More...

int	hasChar (const char *str, char c, int number, bool ignoreString=true)
	Search for a character in a string. More...

void	printBrokenPipe ()

Private Attributes
CommanderDatabase< API_t >	regularCommands
	Starting address of the API-tree. More...

char	tempBuff [COMMANDER_MAX_COMMAND_SIZE+1]
	Internal command buffer. More...

const char *	originalCommandData
	This variable will store the address of the input data. More...

bool	formatting = false

Stream *	dbgResponse = NULL
	Pointer to response class. More...

commanderPipeChannel *	pipeChannel = NULL
	Channel for the internal piping. More...

char *	pipeArgBuffer = NULL
	If piping happens the output of the first command will be copied to this buffer. More...

int	pipeCounter
	This function tracks the current pipe in case of a piped command. More...

int	updateBufferCounter = 0
	This variable tracks the next free elements index in the update functions buffer. More...

CommandCaller	defaultCommandCaller

CommandCaller *	caller = NULL

Static Private Attributes
static CommanderDatabase< systemVariableData_t >	systemVariables = CommanderDatabase<systemVariableData_t>()

static debugLevel_t	debugLevel = Commander::DEBUG_OFF
	Flag to enable or disable debug messages. More...

static const char	empty_string = '\0'

Friends
class	CommanderUT
	For unit testing. More...

Detailed Description

Commander class.

This class can be used to create a command parser. Its job is to parse a command from a character array( string ) and find the matching function for that command from a database. This database consists an array of API_t-type elements, and these elements are store the relevant information for that specific command.

Definition at line 177 of file Commander-API.hpp.

Member Typedef Documentation

◆ API_t

typedef struct Commander::API_t Commander::API_t

Structure for command data.

Every command will get a structure like this. This structure is used to store your commands in a balanced binary tree.

◆ systemCommand_t

typedef CommanderDatabase<API_t>::dataRecord_t Commander::systemCommand_t

Definition at line 210 of file Commander-API.hpp.

◆ systemVariable_t

typedef CommanderDatabase<systemVariableData_t>::dataRecord_t Commander::systemVariable_t

Definition at line 232 of file Commander-API.hpp.

Member Enumeration Documentation

◆ debugLevel_t

enum Commander::debugLevel_t

Enumerator
DEBUG_OFF
DEBUG_ERROR
DEBUG_DEBUG
DEBUG_VERBOSE

Definition at line 184 of file Commander-API.hpp.

◆ systemVariableType_t

enum Commander::systemVariableType_t

Enum for system variable type.

Enumerator
VARIABLE_FLOAT	Used for float data.
VARIABLE_INT	Used for int data.
VARIABLE_STRING	Used for string data.

Definition at line 213 of file Commander-API.hpp.

Member Function Documentation

◆ attachDebugChannel()

void Commander::attachDebugChannel ( Stream * resp )

Attach a debug channel to the object.

This function attaches a Serial channel for debug messages. It also enables the debug functionality. It can be useful during the init phase.

Parameters

resp	Pointer to a Stream object. The output data will be printed to this Stream.

Note: If you call this function the debug messages will be enabled automatically.

Definition at line 434 of file Commander-API.cpp.

◆ attachTreeFunction()

void Commander::attachTreeFunction	(	Commander::systemCommand_t *	API_tree_p,
		uint32_t	API_tree_size_p
	)

Attach API-tree to the object.

With this function you can attach the API-tree structure array to the object. This array contains the data for each command.

Note: There is a macro to simplify this process. Please use the attachTree macro because it is safer!

Definition at line 43 of file Commander-API.cpp.

◆ attachVariablesFunction()

void Commander::attachVariablesFunction	(	systemVariable_t *	variables_p,
		uint32_t	variables_size_p
	)

static

Attach system variables list to the object.

With this function you can attach the system variables list to the object. This array contains the data for each variable.

Note: There is a macro to simplify this process. Please use the attachVariables macro because it is safer!

Definition at line 575 of file Commander-API.cpp.

◆ commandExists()

bool Commander::commandExists	(	const char *	cmd,
		Commander::systemCommand_t **	cmd_ptr = `NULL`
	)

Definition at line 899 of file Commander-API.cpp.

Here is the caller graph for this function:

◆ disableFormatting()

void Commander::disableFormatting ( )

Disable formatting.

You can disable formatting with this function.

Definition at line 558 of file Commander-API.cpp.

◆ enableFormatting()

void Commander::enableFormatting ( )

Enable formatting.

If you want to get fancy, you can enable coloring on the output text.

Note: It will only work with VT100 compatible host interface like PuTTY. On Arduino terminal monitor it will result some garbage text.; Sadly Arduino terminal monitor not support VT100 yet 😞

Definition at line 555 of file Commander-API.cpp.

◆ enablePipeModuleFunc()

bool Commander::enablePipeModuleFunc	(	char *	buffer,
		int	bufferSize,
		commanderPipeChannel *	pipeChannel_p
	)

Enable pipe functionality.

With this function you can enable piping. The syntax for piping is more less the same as with a Linux system. Sadly it is a bit resource hungry, because it requires a pipe buffer and a pipe Stream to make it work. For this reason the required amount buffer memory is at least three times as much as without the pipe module enabled.

Parameters

buffer	Pointer to a char buffer.
bufferSize	The size of the buffer.
pipeChannel_p	This is a pointer to a commanderPipeChannel object.

Returns: If the pipe module is enabled it will return true. Otherwise most probably the buffer size is not set correctly.

Warning: The buffer size has to be exactly COMMANDER_PIPE_BUFFER_SIZE!

Note: There is a macro to simplify this process. Please use the enablePipeModule macro because it is safer!

Definition at line 66 of file Commander-API.cpp.

◆ execute()

bool Commander::execute	(	const char *	cmd,
		Stream *	channel_p = `NULL`,
		CommandCaller *	caller_p = `NULL`
	)

Execution function for Stream response.

This function tries to execute a command. It uses the Stream response channel, so the messages from the command handler will be passed to the selected Stream object.

Parameters

cmd	This is a command string and it will be executed.
caller_p	This can be a pointer to anything. The reason why it is implemented, is because the Shellminator project needed a simple way to communicate with the caller terminal from the called command function. It is optional, the default value for it is NULL.

Definition at line 399 of file Commander-API.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ executeCommand()

bool Commander::executeCommand ( const char * cmd )

private

Command execution.

This function executes a command. Before calling this function, the response pointer and it's channel has to be configured correctly.

Definition at line 87 of file Commander-API.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ floatToString()

int Commander::floatToString	(	float	number,
		char *	buffer,
		int	bufferSize
	)

static

Definition at line 768 of file Commander-API.cpp.

Here is the caller graph for this function:

◆ generateHint()

int Commander::generateHint	(	const char *	fraction,
		char *	buffer_p,
		int	buffer_size_p
	)

Definition at line 928 of file Commander-API.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getHint()

const char * Commander::getHint	(	int	index,
		bool	only_remaining_chars = `false`
	)

Definition at line 914 of file Commander-API.cpp.

◆ getSystemVariable()

Commander::systemVariable_t * Commander::getSystemVariable ( const char * name )

static

Get the instance if a system variable by its name.

With this function you can get the address of a system variable structure element by the name if the system variable.

Parameters

name	The name of the system variable.

Returns: If the variable is found, it will return the address of the control structure. Otherwise it will return NULL.

Definition at line 585 of file Commander-API.cpp.

Here is the caller graph for this function:

◆ hasChar() [1/2]

int Commander::hasChar	(	const char *	str,
		char	c,
		bool	ignoreString = `true`
	)

private

Search for a character in a string.

Parameters

str	Pointer to a character array where the search will be.
c	This character will be searched in the string.
ignoreString	If this flag is set to true, the searched character within a string will be ignored. For example if the searched character is 'A' and the input str is 'dog "Apple" Arduino' 12 will be returned, which is the start of the Arduino word.

Returns: If the character found in the string, the position of the first occurrence will be returned. If it can not be found, a negative number will be returned.

Definition at line 495 of file Commander-API.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ hasChar() [2/2]

int Commander::hasChar	(	const char *	str,
		char	c,
		int	number,
		bool	ignoreString = `true`
	)

private

Search for a character in a string.

Parameters

str	Pointer to a character array where the search will be.
c	This character will be searched in the string.
number	Which occurrence of c is searched.
ignoreString	If this flag is set to true, the searched character within a string will be ignored. For example if the searched character is 'A' and the input str is 'dog "Apple" Arduino' 12 will be returned, which is the start of the Arduino word.

Returns: If the character found in the string in the number'th place, the position of the first occurrence will be returned. If it can not be found, a negative number will be returned.

Definition at line 527 of file Commander-API.cpp.

Here is the call graph for this function:

◆ init()

bool Commander::init ( )

Initializer.

This function initializes the object and its internal parts. Firstly it makes the API-tree alphabetically ordered, then creates a balanced binary tree from it. It is necessary to speed up the search process.

Definition at line 62 of file Commander-API.cpp.

◆ inString()

bool Commander::inString	(	const char *	source,
		int	index
	)

static

Detect if character is in the string.

You can detect if the index of a character is in a 'string' in a character array. For example if the source looks like this:

-p "hello" bello'

And the index is 3 it will return true, because the h character is within two " characters. If the index us 11 it will return false, because the b character is not in a string.

Parameters

source	Pointer to a source string. It has to be terminated!
index	The index of the investigated character.

Returns: As explained above.

Definition at line 666 of file Commander-API.cpp.

Here is the caller graph for this function:

◆ printArgumentError()

void Commander::printArgumentError ( Stream * channel_p )

static

Print 'Argument error!' to a specified Serial channel.

This is a relatively common message, when arguments are used in a command. To avoid duplication and save som precious memory, this function is dedicated to print this message.

Parameters

channel_p Pointer to the Stream object where the message will be printed.

Definition at line 562 of file Commander-API.cpp.

◆ printBrokenPipe()

void Commander::printBrokenPipe ( )

private

Definition at line 829 of file Commander-API.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ printHelp()

void Commander::printHelp	(	Stream *	out,
		bool	description,
		bool	style = `false`
	)

Print the help text to a specified Stream.

It prints all the available commands in alphabetical order. If the description argument is set to true, it also prints the description data for all commands.

Parameters

out	Pointer to a Stream object. The output data will be printed to this Stream.
description	If this flag is set to true, the description data will be printed as well.
style	If this flag is set to true, the output text will be colorized. It will use VT100 escape sequences, and because of it, the output data only will be pretty on VT100 compatible frontends.

Definition at line 442 of file Commander-API.cpp.

Here is the caller graph for this function:

◆ printSystemVariable()

void Commander::printSystemVariable	(	Stream *	channel_p,
		const char *	name,
		int	decimalPlaces = `2`
	)

static

Print the value of a system variable.

This function will print the value of a system variable to a specified Stream. The variable is accessed by its name.

Parameters

channel_p	Pointer to a Stream object. The data will be printed to this Stream.
name	The name of the system variable.
decimalPlaces	Optionally, you can specify how many how many decimal places will be needed in case of float data.

Definition at line 589 of file Commander-API.cpp.

Here is the call graph for this function:

◆ printSystemVariables()

void Commander::printSystemVariables ( Stream * channel_p )

static

Print all the available system variables.

This function will print all the available system variables to a specified Stream. The variable name and its value will be printed.

Parameters

channel_p Pointer to a Stream object. The data will be printed to this Stream.

Definition at line 622 of file Commander-API.cpp.

◆ setDebugLevel()

void Commander::setDebugLevel ( Commander::debugLevel_t debugLevel_p )

static

Definition at line 438 of file Commander-API.cpp.

◆ update()

void Commander::update	(	char *	buffer,
		int	bufferSize,
		Stream *	channel_p
	)

Create a very very simple command lime.

With this function you can create a very basic command line. A buffer is required to store the incoming characters somewhere. This function has to be called periodically to make it work.

Parameters

buffer	Pointer to a buffer.
bufferSize	The size of the buffer. I recommend at least 20 character long buffer.
channel_p	Pointer to a Stream object like Serial.

Definition at line 704 of file Commander-API.cpp.

Here is the call graph for this function:

Friends And Related Function Documentation

◆ CommanderUT

friend class CommanderUT

friend

For unit testing.

Definition at line 468 of file Commander-API.hpp.

Member Data Documentation

◆ caller

CommandCaller* Commander::caller = NULL

private

Definition at line 471 of file Commander-API.hpp.

◆ dbgResponse

Stream* Commander::dbgResponse = NULL

private

Pointer to response class.

By default it points to the default debug response handler.

Definition at line 418 of file Commander-API.hpp.

◆ debugLevel

Commander::debugLevel_t Commander::debugLevel = Commander::DEBUG_OFF

staticprivate

Flag to enable or disable debug messages.

Definition at line 414 of file Commander-API.hpp.

◆ defaultCommandCaller

CommandCaller Commander::defaultCommandCaller

private

Definition at line 470 of file Commander-API.hpp.

◆ empty_string

const char Commander::empty_string = '\0'

staticprivate

Definition at line 465 of file Commander-API.hpp.

◆ formatting

bool Commander::formatting = false

private

Definition at line 411 of file Commander-API.hpp.

◆ lastCommandHint

const char* Commander::lastCommandHint = NULL

Definition at line 383 of file Commander-API.hpp.

◆ lastCommandHintOffset

int Commander::lastCommandHintOffset = 0

Definition at line 384 of file Commander-API.hpp.

◆ lastHint

AutoComplete* Commander::lastHint = NULL

Definition at line 382 of file Commander-API.hpp.

◆ originalCommandData

const char* Commander::originalCommandData

private

This variable will store the address of the input data.

It is required to track back the original command in case of an error.

Definition at line 409 of file Commander-API.hpp.

◆ pipeArgBuffer

char* Commander::pipeArgBuffer = NULL

private

If piping happens the output of the first command will be copied to this buffer.

This way it can be passed to the second command and so on.

Note: If this variable points to a valid address, the piping module will be enabled in the executeCommand function.

Definition at line 456 of file Commander-API.hpp.

◆ pipeChannel

commanderPipeChannel* Commander::pipeChannel = NULL

private

Channel for the internal piping.

Definition at line 451 of file Commander-API.hpp.

◆ pipeCounter

int Commander::pipeCounter

private

This function tracks the current pipe in case of a piped command.

It can be used to backtrack a broken pipe position.

Definition at line 460 of file Commander-API.hpp.

◆ regularCommands

CommanderDatabase<API_t> Commander::regularCommands

private

Starting address of the API-tree.

CommanderDatabase<API_t>::dataRecord_t* API_tree = NULL; Number of elements in the API-tree. uint32_t API_tree_size = 0;

Definition at line 395 of file Commander-API.hpp.

◆ systemVariables

CommanderDatabase< Commander::systemVariableData_t > Commander::systemVariables = CommanderDatabase<systemVariableData_t>()

staticprivate

Definition at line 398 of file Commander-API.hpp.

◆ tempBuff

char Commander::tempBuff[COMMANDER_MAX_COMMAND_SIZE+1]

private

Internal command buffer.

The command data has to be copied to this buffer. It is necessary because the execute function has to modify the content of the command.

Definition at line 404 of file Commander-API.hpp.

◆ updateBufferCounter

int Commander::updateBufferCounter = 0

private

This variable tracks the next free elements index in the update functions buffer.

Definition at line 463 of file Commander-API.hpp.

◆ version

const char * Commander::version = COMMANDER_API_VERSION

static

Library version string.

Definition at line 182 of file Commander-API.hpp.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ API_t

◆ systemCommand_t

◆ systemVariable_t

Member Enumeration Documentation

◆ debugLevel_t

◆ systemVariableType_t

Member Function Documentation

◆ attachDebugChannel()

◆ attachTreeFunction()

◆ attachVariablesFunction()

◆ commandExists()

◆ disableFormatting()

◆ enableFormatting()

◆ enablePipeModuleFunc()

◆ execute()

◆ executeCommand()

◆ floatToString()

◆ generateHint()

◆ getHint()

◆ getSystemVariable()

◆ hasChar() [1/2]

◆ hasChar() [2/2]

◆ init()

◆ inString()

◆ printArgumentError()

◆ printBrokenPipe()

◆ printHelp()

◆ printSystemVariable()

◆ printSystemVariables()

◆ setDebugLevel()

◆ update()

Friends And Related Function Documentation

◆ CommanderUT

Member Data Documentation

◆ caller

◆ dbgResponse

◆ debugLevel

◆ defaultCommandCaller

◆ empty_string

◆ formatting

◆ lastCommandHint

◆ lastCommandHintOffset

◆ lastHint

◆ originalCommandData

◆ pipeArgBuffer

◆ pipeChannel

◆ pipeCounter

◆ regularCommands

◆ systemVariables

◆ tempBuff

◆ updateBufferCounter

◆ version