Commander-API  V0.2A
Commander-API is a C API, that interprets character-based commands
interpreter.h File Reference
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include "Arduino.h"

Go to the source code of this file.

Classes

struct  API_t
 Structure for command data. More...
 

Macros

#define COMMANDER_API_VERSION   "V0.2A"
 Version information. More...
 
#define ARDUINO_PLATFORM
 Arduino environment used. More...
 
#define INTERPRETER_BUFFER_SIZE   30
 Definition to a buffer size. More...
 
#define NUM_OF_API_FUNCS   4
 The number of API functions. More...
 
#define INTERPRETER_DBG   printf
 Debug message output. More...
 
#define ARDUINP_PRINTF_BUFF_SIZE   150
 Arduino printf buffer size. More...
 
#define INTERPRETER_DBG   arduino_printf
 Debug message output. More...
 
#define INTERPRETER_PRINTF   printf
 Output messages. More...
 
#define INTERPRETER_PRINTF   arduino_printf
 Output messages. More...
 

Typedefs

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

Functions

int arduino_printf (const char *fmt,...)
 If you use Arduino environment you have to include Arduino.h. 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 init_interpreter (void)
 This is the initialization function. More...
 
void print_apis_in_order (API_t *head)
 Prints your commands. More...
 
void recursive_indexer (API_t *head)
 Indexes all elements in the tree. More...
 
void index_apis_in_order (API_t *head)
 Indexes all elements in the tree. More...
 
uint16_t find_api_index_by_place (uint16_t place)
 Finds an element in API tree by alphabetical order. More...
 
void optimise_api_tree (API_t *head)
 Tree optimizer. More...
 
void swap_api_elements (uint16_t index, uint16_t place)
 Swap two elements in API tree. 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...
 

Macro Definition Documentation

◆ ARDUINO_PLATFORM

#define ARDUINO_PLATFORM

Arduino environment used.

If you use the Arduino environment with this library, The easiest way is to uncomment this macro( uncommented by default ). It creates a printf like function to you called arduino_printf. A printf like function is necessary for this library, it is explained below why and how.

◆ ARDUINP_PRINTF_BUFF_SIZE

#define ARDUINP_PRINTF_BUFF_SIZE   150

Arduino printf buffer size.

With this definition you can define the size of the output buffer size of the arduino_printf function.

◆ COMMANDER_API_VERSION

#define COMMANDER_API_VERSION   "V0.2A"

Version information.

◆ INTERPRETER_BUFFER_SIZE

#define INTERPRETER_BUFFER_SIZE   30

Definition to a buffer size.

If you want to use the execute function with const char command as argument, you must define this macro with a resonable size. The importance of this is explained in the execute function. If you wont use the execute function with const char command parameter, you can comment this macro out.

◆ INTERPRETER_DBG [1/2]

#define INTERPRETER_DBG   printf

Debug message output.

You can define a printf()-like function to send debug messages from the interpreter. It can be useful to validate that the API tree generation was succesfull. comment out if you does not want to get debug messages

◆ INTERPRETER_DBG [2/2]

#define INTERPRETER_DBG   arduino_printf

Debug message output.

You can define a printf()-like function to send debug messages from the interpreter. It can be useful to validate that the API tree generation was succesfull. comment out if you does not want to get debug messages

◆ INTERPRETER_PRINTF [1/2]

#define INTERPRETER_PRINTF   printf

Output messages.

This is the output channel of the interpreter. THIS IS NOT OPTIONAL! Default configuration is uses printf, but you can use any printf like function.

◆ INTERPRETER_PRINTF [2/2]

#define INTERPRETER_PRINTF   arduino_printf

Output messages.

This is the output channel of the interpreter. THIS IS NOT OPTIONAL! Default configuration is uses printf, but you can use any printf like function.

◆ NUM_OF_API_FUNCS

#define NUM_OF_API_FUNCS   4

The number of API functions.

You have to set an exact value to this definition about how many commands have you added to the interpreter. If this number is not correct, than the compiler can't reserve space correctly for the API tree. To make this library work you have to use at least 3 commands. If you have less than 3 command just use simple strcmp.

Typedef Documentation

◆ API_t

typedef struct API_t 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.

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

◆ arduino_printf()

int arduino_printf ( const char *  fmt,
  ... 
)

If you use Arduino environment you have to include Arduino.h.

If you use Arduino environment you have to create a printf like function

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

◆ 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

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