Commander-API  V2.1.0
Simple Command Parser
Loading...
Searching...
No Matches
Commander Class Reference

Commander class. More...

#include <Commander-API.hpp>

Collaboration diagram for Commander:
[legend]

Classes

struct  API_t
 Structure for command data. More...
 

Public Types

enum  memoryType_t { MEMORY_REGULAR , MEMORY_PROGMEM }
 
typedef struct Commander::API_t API_t
 Structure for command data. More...
 

Public Member Functions

void attachTreeFunction (API_t *API_tree_p, uint32_t API_tree_size_p)
 Attach API-tree to the object. More...
 
void init ()
 Initializer. More...
 
API_toperator[] (int i)
 Array index operator overload for int type. More...
 
API_toperator[] (char *name)
 Array index operator overload for char array( string ). More...
 
API_toperator[] (const char *name)
 Array index operator overload for const char array( string ). More...
 
void execute (char *cmd)
 Default execution function. More...
 
void execute (const char *cmd)
 Default execution function. More...
 
void execute (char *cmd, Stream *resp)
 Execution function for Serial response. More...
 
void execute (const char *cmd, Stream *resp)
 Execution function for Serial response. More...
 
void attachDebugChannel (Stream *resp)
 Debug channel for Serial. More...
 
void enableDebug ()
 Enables debug messages. More...
 
void disableDebug ()
 Disables debug messages. More...
 
void printHelp (Stream *out)
 Prints out the help string to the specified Stream. More...
 

Public Attributes

memoryType_t memoryType = MEMORY_REGULAR
 Flag for memory type. More...
 

Static Public Attributes

static const char * version = COMMANDER_API_VERSION
 Library version string. More...
 

Private Member Functions

int commander_strcmp_progmem (API_t *element1, API_t *element2)
 Compare two API-tree element's name. More...
 
int commander_strcmp_tree_ram_progmem (API_t *element1, char *element2)
 Compare an API-tree element's name with a regular string. More...
 
int commander_strcmp_regular (API_t *element1, API_t *element2)
 Compare two API-tree element's name. More...
 
int commander_strcmp_tree_ram_regular (API_t *element1, char *element2)
 Compare an API-tree element's name with a regular string. More...
 
uint16_t find_api_index_by_place (uint16_t place)
 Find an API element in the tree by alphabetical place. More...
 
void swap_api_elements (uint16_t index, uint16_t place)
 Swap two API elements in the tree. More...
 
void optimize_api_tree ()
 Optimizes the tree to make it balanced. More...
 
void recursive_optimizer (int32_t start_index, int32_t stop_index)
 Recursive function optimize a section in the tree. More...
 
void executeCommand (char *cmd)
 Command execution. More...
 
void helpFunction (bool description=false)
 Help function. More...
 
void helpFunction (bool description, Stream *out, bool style=false)
 Help function. More...
 
int32_t hasChar (char *str, char c)
 Search for a character in a string. More...
 

Private Attributes

API_tAPI_tree = NULL
 Starting address of the API-tree. More...
 
uint32_t API_tree_size = 0
 Number of elements in the API-tree. More...
 
uint32_t elementCounter
 Internal variable for counting purpose. More...
 
char tempBuff [COMMANDER_MAX_COMMAND_SIZE]
 Internal command buffer. More...
 
char progmemBuffer [COMMANDER_MAX_COMMAND_SIZE]
 With the PROGMEM implementation we need to copy the data from the PROGMEM area to a buffer for compersation. More...
 
int(Commander::* commander_strcmp )(API_t *element1, API_t *element2) = &Commander::commander_strcmp_regular
 Function pointer to an internal strcmp like function. More...
 
int(Commander::* commander_strcmp_tree_ram )(API_t *element1, char *element2) = &Commander::commander_strcmp_tree_ram_regular
 Function pointer to an internal strcmp like function. More...
 
commandResponse defaultResponse
 Default response handler class. More...
 
Stream * response = &defaultResponse
 Pointer to response class. More...
 
bool debugEnabled = false
 Flag to enable or disable debug messages. More...
 
commandResponse defaultDebugResponse
 Default response handler for debug messages. More...
 
Stream * dbgResponse = &defaultDebugResponse
 Pointer to response class. More...
 
commanderPipeChannel pipeChannel
 Channel for the internal piping. More...
 
char pipeArgBuffer [COMMANDER_MAX_COMMAND_SIZE]
 If piping happenes the output of the first command will be copied to this buffer. 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 97 of file Commander-API.hpp.

Member Typedef Documentation

◆ 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.

Member Enumeration Documentation

◆ memoryType_t

Enumerator
MEMORY_REGULAR 

Regular memory implementation.

MEMORY_PROGMEM 

Progmem memory implementation.

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

Member Function Documentation

◆ attachDebugChannel()

void Commander::attachDebugChannel ( Stream *  resp)

Debug channel for Serial.

This function attaches a Serial channel for debug messages. It also enables the debug functionality.

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

◆ attachTreeFunction()

void Commander::attachTreeFunction ( API_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( attachTree ) to simplify this process.

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

◆ commander_strcmp_progmem()

int Commander::commander_strcmp_progmem ( API_t element1,
API_t element2 
)
private

Compare two API-tree element's name.

It compares two API-tree element's name like a regular strcmp. It compares the names stored in the name_P variable. This names are stored in PROGMEM space.

Parameters
element1Pointer to an API-tree element.
element2Pointer to an API-tree element.
Returns
Returns an int value indicating the relationship between the strings.

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

Here is the caller graph for this function:

◆ commander_strcmp_regular()

int Commander::commander_strcmp_regular ( API_t element1,
API_t element2 
)
private

Compare two API-tree element's name.

It compares two API-tree element's name like a regular strcmp. variable. This names are stored in PROGMEM space.

Parameters
element1Pointer to an API-tree element.
element2Pointer to an API-tree element.
Returns
Returns an int value indicating the relationship between the strings.

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

◆ commander_strcmp_tree_ram_progmem()

int Commander::commander_strcmp_tree_ram_progmem ( API_t element1,
char *  element2 
)
private

Compare an API-tree element's name with a regular string.

It compares an API-tree element's name with a regular string like a regular strcmp.

Parameters
element1Pointer to an API-tree element.
element2Character array.
Returns
Returns an int value indicating the relationship between the strings.

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

Here is the caller graph for this function:

◆ commander_strcmp_tree_ram_regular()

int Commander::commander_strcmp_tree_ram_regular ( API_t element1,
char *  element2 
)
private

Compare an API-tree element's name with a regular string.

It compares an API-tree element's name with a regular string like a regular strcmp.

Parameters
element1Pointer to an API-tree element.
element2Character array.
Returns
Returns an int value indicating the relationship between the strings.

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

◆ disableDebug()

void Commander::disableDebug ( )

Disables debug messages.

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

◆ enableDebug()

void Commander::enableDebug ( )

Enables debug messages.

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

◆ execute() [1/4]

void Commander::execute ( char *  cmd)

Default execution function.

This function tries to execute a command. It uses the default response channel, so the messages from the command handler wont be visible.

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

Here is the call graph for this function:

◆ execute() [2/4]

void Commander::execute ( char *  cmd,
Stream *  resp 
)

Execution function for Serial response.

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

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

Here is the call graph for this function:

◆ execute() [3/4]

void Commander::execute ( const char *  cmd)

Default execution function.

This function tries to execute a command. It uses the default response channel, so the messages from the command handler wont be visible.

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

Here is the call graph for this function:

◆ execute() [4/4]

void Commander::execute ( const char *  cmd,
Stream *  resp 
)

Execution function for Serial response.

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

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

Here is the call graph for this function:

◆ executeCommand()

void Commander::executeCommand ( 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 285 of file Commander-API.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ find_api_index_by_place()

uint16_t Commander::find_api_index_by_place ( uint16_t  place)
private

Find an API element in the tree by alphabetical place.

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

Here is the caller graph for this function:

◆ hasChar()

int32_t Commander::hasChar ( char *  str,
char  c 
)
private

Search for a character in a string.

Parameters
strPointer to a character array where the search will be.
cThis character will be searched in the string.
Returns
If the character found in the string, the poisition of the first occurance will be returned.

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

Here is the caller graph for this function:

◆ helpFunction() [1/2]

void Commander::helpFunction ( bool  description,
Stream *  out,
bool  style = false 
)
private

Help function.

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. todo Finish description.

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

◆ helpFunction() [2/2]

void Commander::helpFunction ( bool  description = false)
private

Help function.

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. todo Finish description.

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

Here is the call graph for this function:
Here is the caller graph for this function:

◆ init()

void 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 61 of file Commander-API.cpp.

Here is the call graph for this function:

◆ operator[]() [1/3]

Commander::API_t * Commander::operator[] ( char *  name)

Array index operator overload for char array( string ).

With this function you can get a pointer to an element from the API-tree by it's name. If the name is not found the return value will be NULL.

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

◆ operator[]() [2/3]

Commander::API_t * Commander::operator[] ( const char *  name)

Array index operator overload for const char array( string ).

With this function you can get a pointer to an element from the API-tree by it's name. If the name is not found the return value will be NULL.

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

◆ operator[]() [3/3]

Commander::API_t * Commander::operator[] ( int  i)

Array index operator overload for int type.

With this function you can get a pointer to an element from the API-tree by it's index. If the index is invalid, the return value will be NULL.

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

◆ optimize_api_tree()

void Commander::optimize_api_tree ( )
private

Optimizes the tree to make it balanced.

Definition at line 211 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)

Prints out the help string to the specified Stream.

Parameters
outThe help information will be printed to this Stream.

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

Here is the call graph for this function:

◆ recursive_optimizer()

void Commander::recursive_optimizer ( int32_t  start_index,
int32_t  stop_index 
)
private

Recursive function optimize a section in the tree.

It is used by optimize_api_tree function. The elementCounter has to be 0 before using this function. This function just creates an order for the balanced tree, but does not create the links between the elements.

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

Here is the call graph for this function:
Here is the caller graph for this function:

◆ swap_api_elements()

void Commander::swap_api_elements ( uint16_t  index,
uint16_t  place 
)
private

Swap two API elements in the tree.

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

Here is the call graph for this function:
Here is the caller graph for this function:

Member Data Documentation

◆ API_tree

API_t* Commander::API_tree = NULL
private

Starting address of the API-tree.

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

◆ API_tree_size

uint32_t Commander::API_tree_size = 0
private

Number of elements in the API-tree.

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

◆ commander_strcmp

int(Commander::* Commander::commander_strcmp) (API_t *element1, API_t *element2) = &Commander::commander_strcmp_regular
private

Function pointer to an internal strcmp like function.

It uses the regular version by default.

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

◆ commander_strcmp_tree_ram

int(Commander::* Commander::commander_strcmp_tree_ram) (API_t *element1, char *element2) = &Commander::commander_strcmp_tree_ram_regular
private

Function pointer to an internal strcmp like function.

It uses the regular version by default.

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

◆ dbgResponse

Stream* Commander::dbgResponse = &defaultDebugResponse
private

Pointer to response class.

By default it points to the default debug response handler.

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

◆ debugEnabled

bool Commander::debugEnabled = false
private

Flag to enable or disable debug messages.

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

◆ defaultDebugResponse

commandResponse Commander::defaultDebugResponse
private

Default response handler for debug messages.

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

◆ defaultResponse

commandResponse Commander::defaultResponse
private

Default response handler class.

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

◆ elementCounter

uint32_t Commander::elementCounter
private

Internal variable for counting purpose.

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

◆ memoryType

memoryType_t Commander::memoryType = MEMORY_REGULAR

Flag for memory type.

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

◆ pipeArgBuffer

char Commander::pipeArgBuffer[COMMANDER_MAX_COMMAND_SIZE]
private

If piping happenes 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.

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

◆ pipeChannel

commanderPipeChannel Commander::pipeChannel
private

Channel for the internal piping.

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

◆ progmemBuffer

char Commander::progmemBuffer[COMMANDER_MAX_COMMAND_SIZE]
private

With the PROGMEM implementation we need to copy the data from the PROGMEM area to a buffer for compersation.

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

◆ response

Stream* Commander::response = &defaultResponse
private

Pointer to response class.

By default it points to the default response handler.

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

◆ tempBuff

char Commander::tempBuff[COMMANDER_MAX_COMMAND_SIZE]
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 237 of file Commander-API.hpp.

◆ version

const char * Commander::version = COMMANDER_API_VERSION
static

Library version string.

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