Commander-API  V0.2A
Commander-API is a C API, that interprets character-based commands
interpreter.c File Reference
#include "interpreter.hpp"

Macros

#define create_command_data(name, desc)
 Command data creator function. More...
 
#define add_command(name, func)   add_interpreter_command(&name##_API_NAME, &name##_API_DESC, func);
 Add command to the interpreter. More...
 

Functions

 create_command_data (stop, "This command can be used to stop something.\r\nargs:\td - generic number\r\n\tc - someting else")
 
 create_command_data (start, "This command can be used to start something.\r\nargs:\td - generic number\r\n\tc - someting else")
 
 create_command_data (left, "This command can be used to make someting turn left.\r\nargs:\td - generic number\r\n\tc - someting else")
 
 create_command_data (right, "This command can be used to make someting turn right.\r\nargs:\td - generic number\r\n\tc - someting else")
 
void stop_func (char *args, int(*resp_fn)(const char *,...))
 
void start_func (char *args, int(*resp_fn)(const char *,...))
 This is an example function for the start command. More...
 
void left_func (char *args, int(*resp_fn)(const char *,...))
 This is an example function for the left command. More...
 
void right_func (char *args, int(*resp_fn)(const char *,...))
 This is an example function for the right command. More...
 
void init_interpreter (void)
 This is the initialization function. More...
 
void add_interpreter_command (const char **name, const char **desc, void(*func)(char *, int(*resp_fn)(const char *,...)))
 This command is used to add a new command to the interpreter. More...
 
void index_apis_in_order (API_t *head)
 Indexes all elements in the tree. More...
 
void recursive_indexer (API_t *head)
 Indexes all elements in the tree. More...
 
void print_apis_in_order (API_t *head)
 Prints your commands. More...
 
uint16_t find_api_index_by_place (uint16_t place)
 Finds an element in API tree by alphabetical order. More...
 
void swap_api_elements (uint16_t index, uint16_t place)
 Swap two elements in API tree. More...
 
void optimise_api_tree (API_t *head)
 Tree optimizer. More...
 
void recursive_optimiser (int32_t start_index, int32_t stop_index)
 Recorsive Optinizer function. More...
 
void execute (char *cmd, int(*resp_fn)(const char *,...))
 Execution function. More...
 

Variables

API_t API_tree [NUM_OF_API_FUNCS]
 
uint32_t API_cntr
 
uint32_t API_place_cntr
 

Macro Definition Documentation

◆ add_command

#define add_command (   name,
  func 
)    add_interpreter_command(&name##_API_NAME, &name##_API_DESC, func);

Add command to the interpreter.

This macro helps adding the command to the interpreter.

Warning
Before using this macro for a specific command you have to use create_command_data macro first!
Parameters
namethe name of the command without "". @func the function that will be called when this command arrives.

◆ create_command_data

#define create_command_data (   name,
  desc 
)
Value:
const char *name##_API_NAME = (const char *)#name; \
const char *name##_API_DESC = (const char *)desc;

Command data creator function.

This macro helps to create the command data for a new command. Every command has a name and a description. These data wont change so they are constant. To save some RAM it is handy to store constant data in program memory( FLASH ). This macro handles all of this constant variable cration.

Warning
The name has to bee an ASCII text. It can't have special characters( !,+,?..etc ), or spaces. It can contain numbers, but the first character has ro be a character not a number!
Parameters
namethe name of the command without ""
descthe description of the command with ""

Function Documentation

◆ add_interpreter_command()

void add_interpreter_command ( const char **  name,
const char **  desc,
void(*)(char *, int(*resp_fn)(const char *,...))  func 
)

This command is used to add a new command to the interpreter.

In practise you wont have to use this command, because there is a macro for it called add_command. Using this function without command creation macros is not recommended.

Parameters
namepointer to a const char* that holds the name of the command
descpointer to a const char* that holds the description of the command
funcfunction-pointer to a function that will be called, when the command will be executed

◆ create_command_data() [1/4]

create_command_data ( left  ,
"This command can be used to make someting turn left.\r\nargs:\td - generic number\r\n\tc - someting else"   
)

◆ create_command_data() [2/4]

create_command_data ( right  ,
"This command can be used to make someting turn right.\r\nargs:\td - generic number\r\n\tc - someting else"   
)

◆ create_command_data() [3/4]

create_command_data ( start  ,
"This command can be used to start something.\r\nargs:\td - generic number\r\n\tc - someting else"   
)

◆ create_command_data() [4/4]

create_command_data ( stop  ,
"This command can be used to stop something.\r\nargs:\td - generic number\r\n\tc - someting else"   
)

◆ execute()

void execute ( char *  cmd,
int(*)(const char *,...)  resp_fn 
)

Execution function.

You have to call this function when you want to execute a command. The command is basically a C-like string.

Warning
use this function after init_interpreter.
Parameters
cmdthe command that you want to execute.
resp_fnthe response function for command execution.

◆ find_api_index_by_place()

uint16_t find_api_index_by_place ( uint16_t  place)

Finds an element in API tree by alphabetical order.

You give the alphabetical index of an element and it returns the index of that elment in the binary tree.

Parameters
placealphabetical order of an element
Returns
place of that element in the API tree

◆ index_apis_in_order()

void index_apis_in_order ( API_t head)

Indexes all elements in the tree.

It is used by the library to calculate and store every elements alphabetical index.

Note
Use this function to index the commands.
Warning
It uses a recursive function, so it can consume a lot of stack memory. Please don't use it after init!
Parameters
headthis is the head of the API tree

◆ init_interpreter()

void init_interpreter ( void  )

This is the initialization function.

This function handles the API tree generation. In this function you have to add your commands to the interpreter with add_command macro. The init function also compares NUM_OF_API_FUNCS with the number of added commands. If there's a mismatch it sends an error to the debug port.

◆ left_func()

void left_func ( char *  args,
int(*)(const char *,...)  resp_fn 
)

This is an example function for the left command.

◆ optimise_api_tree()

void optimise_api_tree ( API_t head)

Tree optimizer.

This function is used to balance the API_tree to get the highest search performance.

Warning
It uses a recursive function, so it can consume a lot of stack memory. Please don't use it after init!
Parameters
headthis is the head of the API tree

◆ print_apis_in_order()

void print_apis_in_order ( API_t head)

Prints your commands.

This function prints your commands in alphabetical order.

Warning
It is a recursive function, so it can consume a lot of stack memory. Please don't use it after init!
Parameters
headthis is the head of the API tree

◆ recursive_indexer()

void recursive_indexer ( API_t head)

Indexes all elements in the tree.

It is used by the library to calculate and store every elements alphabetical index.

Warning
It is a recursive function, so it can consume a lot of stack memory. Please don't use it after init! Do not use it alone. The index_apis_in_order function can be used for this purpose.
Parameters
headthis is the head of the API tree

◆ recursive_optimiser()

void recursive_optimiser ( int32_t  start_index,
int32_t  stop_index 
)

Recorsive Optinizer function.

This function is used by the optimise_api_tree function. Please do not use it alone!

Warning
It is a recursive function, so it can consume a lot of stack memory. Please don't use it after init!
Parameters
start_indexstart boundary of the intervall where to optimise
stop_indexstop boundary of the intervall where to optimise

◆ right_func()

void right_func ( char *  args,
int(*)(const char *,...)  resp_fn 
)

This is an example function for the right command.

◆ start_func()

void start_func ( char *  args,
int(*)(const char *,...)  resp_fn 
)

This is an example function for the start command.

◆ stop_func()

void stop_func ( char *  args,
int(*)(const char *,...)  resp_fn 
)

◆ swap_api_elements()

void swap_api_elements ( uint16_t  index,
uint16_t  place 
)

Swap two elements in API tree.

This is a tricky function. Basically it swaps two elements, but the tricky part is that how to specify those two elements. The index argument is refer to the index in the API tree, for example API_tree[0]. The place refers to an alphabetical place of a command in API tree. For example, to swap a command thats alphabetical index is 3 with a command that is the 0th element in the API tree you should call this function like this: swap_api_elements( 0, 3 )

Parameters
indexthe index of an element in API tree.
alphabeticalplace in API tree.

Variable Documentation

◆ API_cntr

uint32_t API_cntr

◆ API_place_cntr

uint32_t API_place_cntr

◆ API_tree

API_t::name
const char ** name
Definition: interpreter.h:107
API_t::desc
const char ** desc
Definition: interpreter.h:108