License and example added

Author: dani007200964

LICENSE

@@ -1,2 +1,92 @@
 # Commander API
- Commander API is a C API to interpret character based commands and map them to their functions easily
+
+**Version 1.0.0**
+
+ Commander API is a C API to interpret character based commands and map them to their functions easily. It is designed mainly to work with low memory capacity devices for example small ARM devices or some embedded stuff.
+
+
+
+## Installation
+
+Installation is easy. Jus add __interpreter.h__, and __interpreter.c__ files to your project.
+
+## Usage
+
+First you have to add the two files to your project. Than you have to create the instruction data in __interpreter.c__ file under the following comment:
+
+'''c
+//  +----  Create instruction data for the API  ----+
+//  |                                               |
+//  |       This is where you have to add           |
+//  |               your commands!                  |
+//  |                                               |
+//  +-----------------------------------------------+
+
+create_instruction_data(stop, "basic stop command");
+'''
+
+Use the __create_instruction_data()__ macro to add your commands to the interpreter like above. You have to do this for every instruction that you want to add. The first argument is the exact command name( this will be the exact command name! ), and the second one is a short description. Note that the first argument __must not have any quotes before and after!__
+
+The next step is to match the functions to your commands. You have to do it in interpreter.c file, in the init_interpreter() function, under the following comment:
+
+'''c
+//  +----  Match instruction to it's function   ----+
+//  |                                               |
+//  |       This is where you have to match         |
+//  |       every instruction name to it's          |
+//  |                   function.                   |
+//  |                                               |
+//  +-----------------------------------------------+
+    add_instruction(stop, stop_func);
+'''
+
+Use the __add_instruction()__ macro to match the name and the asociated function like above. You have to do this for every instruction that you have added previously. The first argument is the instruction name __exactly like the previous step__, the second argument is the function that you want to use when this command gets executed. This function has to be a __void__ return type with two arguments. The first argument is a __char*__ type and the second one is a __int(*resp_fn)(const char*, ...)__ type. I know that it looks scary but it can be very handy and you have to just copy the example function to create a new one.
+
+The next thing you have to do is to specify the number of commands you have been added. It can be done in the __interpreter.h__ file under the following comment:
+
+'''c
+//  +----  Set the correct values  ----+
+//  |                                  |
+//  |     NUM_OF_API_FUNCS value has   |
+//  |           to be exact!           |
+//  |                                  |
+//  +----------------------------------+
+
+#define NUM_OF_API_FUNCS  4
+'''
+
+Modify the __NUM_OF_API_FUNCS__ value to the right number unless __the program will crash!__
+
+The last thing you have to do is to actually create your functions. A simple example function can be like this:
+
+'''c
+void stop_func(char *args, int(*resp_fn)(const char*, ...))
+{
+    printf("STOP!\r\n");
+    printf("Args: %s\r\n", args);
+
+    //  Always check the response function channel!
+    //  If it's a NULL pointer you can't use it,
+    //  because itt will crash your porgram!
+    if( resp_fn != NULL ){
+
+        resp_fn( "Wow! Magic!!!!\r\n" );
+
+    }
+}
+'''
+
+The example function above shows the function of the response function. The interpreter can send messages back to the sender channel. If not used just pass a __null__ pointer to it.
+
+## How it works, why to use?
+ The library does not use any malloc or dynamic memory. The module creates a balanced binary tree by alphabetical order in initialization time. The memory requirement of this tree can be calculated at compile time if we know how many instructions we have. This is why you must configure __NUM_OF_API_FUNCS__ symbol correctly! To create the balanced tree it is a bit more compute hungry than the old strcmp method, but the tree method will boost significantly the speed in search time, so I think it's worth it. In the worst case it finds a command in O*log2(N). That means it can find a command(if it exists) in a __1024__ element long command list under __10__ search steps.
+
+## Contributing
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.
+
+
+## License & copyright
+© Daniel Hajnal
+Licensed under the [MIT License](https://choosealicense.com/licenses/mit/)

README.md

@@ -7,9 +7,21 @@
 #include <stdint.h>
 #include <string.h>
 
-#define NUM_OF_API_FUNCS  8
-#define MAX_RESP_LEN      100
-#define CMD_BUFF_LEN      30
+//  +----  Set the correct values  ----+
+//  |                                  |
+//  |     NUM_OF_API_FUNCS value has   |
+//  |           to be exact!           |
+//  |                                  |
+//  +----------------------------------+
+
+#define NUM_OF_API_FUNCS  4
+
+//  comment out if you does not want to get debug messages
+#define INTERPRETER_DBG printf
+
+//  configure it if necessary
+//  it has to be printf like( int( * )( const char*, ... ) )
+#define INTERPRETER_PRINTF printf
 
 //  structure for instruction data
 typedef struct API_t{
@@ -19,13 +31,12 @@ typedef struct API_t{
   struct API_t *right;      //  Right element on a binary tree branch
   const char **name;        //  Name of the instruction
   const char **desc;        //  Description of the command
-  void(*func)(char*,char*); //  Function pointer to the command function
-  //void(*resp_fn)(char*, ...)
+  void(*func)(char*,int(*resp_fn)(const char*, ...)); //  Function pointer to the command function
 
 }API_t;
 
 
-void add_interpreter_instruction(const char **name, const char **desc, void(*func)(char*,char*));
+void add_interpreter_instruction(const char **name, const char **desc, void(*func)(char*,int(*resp_fn)(const char*, ...)));
 
 void init_interpreter(void);
 
@@ -43,7 +54,7 @@ void swap_api_elements( uint16_t index, uint16_t place );
 
 void recursive_optimiser( int32_t start_index, int32_t stop_index );
 
-void execute( char *cmd, char *response );
+void execute( char *cmd, int(*resp_fn)(const char*, ...) );
 
 void teszt(void);
 

inc/interpreter.h

@@ -10,44 +10,80 @@ uint32_t API_place_cntr;
     const char *name##_API_NAME = (const char *)#name; \
     const char *name##_API_DESC = (const char *)desc;
 
-//  *****  Create instruction data for the API  *****
-create_instruction_data(cica, "cica fuggveny leirasa, jeeee :)");
-create_instruction_data(kutya, "kutya fuggveny leirasa, joooo :)");
-create_instruction_data(tehen, "tehen fuggveny leirasa, jii :)");
-create_instruction_data(majom, "majom fuggveny leirasa, jaaaa :)");
-create_instruction_data(eger, "eger fuggveny leirasa, gyoooo :)");
-create_instruction_data(okor, "eger fuggveny leirasa, gyaaa :)");
-create_instruction_data(csiga, "eger fuggveny leirasa, dikk :)");
-create_instruction_data(v, "Vagod csotany, hihihiiii ;)");
-
 #define add_instruction(name, func) add_interpreter_instruction(&name##_API_NAME, &name##_API_DESC, func);
 
-void cica_func(char *args, char *response)
+
+//  +----  Create instruction data for the API  ----+
+//  |                                               |
+//  |       This is where you have to add           |
+//  |               your commands!                  |
+//  |                                               |
+//  +-----------------------------------------------+
+
+create_instruction_data(stop, "basic stop command");
+create_instruction_data(start, "basic start command");
+create_instruction_data(left, "command used to turn left");
+create_instruction_data(right, "command used to turn right");
+
+
+//  This is an example function for the stop command
+void stop_func(char *args, int(*resp_fn)(const char*, ...))
+{
+    printf("STOP!\r\n");
+    printf("Args: %s\r\n", args);
+
+    //  Always check the response function channel!
+    //  If it's a NULL pointer you can't use it,
+    //  because itt will crash your porgram!
+    if( resp_fn != NULL ){
+
+        resp_fn( "Wow! Magic!!!!\r\n" );
+
+    }
+}
+
+//  This is an example function for the start command
+void start_func(char *args, int(*resp_fn)(const char*, ...))
+{
+    printf("START!\r\n");
+    printf("Args: %s\r\n", args);
+
+}
+
+//  This is an example function for the left command
+void left_func(char *args, int(*resp_fn)(const char*, ...))
 {
-    printf("Cica!\r\n");
+    printf("Turning left!\r\n");
     printf("Args: %s\r\n", args);
+
 }
 
-void kutya_func(char *args, char *response)
+//  This is an example function for the right command
+void right_func(char *args, int(*resp_fn)(const char*, ...))
 {
-    printf("Kutya!\r\n");
+    printf("Turning right!\r\n");
     printf("Args: %s\r\n", args);
+
 }
 
+
 void init_interpreter(void)
 {
     //  Initialize the 'API_cntr' variable as zero before adding new items
     API_cntr = 0;
 
-    //  *****  Create the binary tree of the instructions  *****
-    add_instruction(majom, kutya_func);
-    add_instruction(tehen, kutya_func);
-    add_instruction(cica, cica_func);
-    add_instruction(kutya, kutya_func);
-    add_instruction(eger, kutya_func);
-    add_instruction(okor, kutya_func);
-    add_instruction(csiga, kutya_func);
-    add_instruction(v, kutya_func);
+//  +----  Match instruction to it's function   ----+
+//  |                                               |
+//  |       This is where you have to match         |
+//  |       every instruction name to it's          |
+//  |                   function.                   |
+//  |                                               |
+//  +-----------------------------------------------+
+    add_instruction(stop, stop_func);
+    add_instruction(start, start_func);
+    add_instruction(left, left_func);
+    add_instruction(right, right_func);
+
 
     //  Index eache element to find their place in alphabetic order
     index_apis_in_order( &API_tree[0] );
@@ -59,11 +95,15 @@ void init_interpreter(void)
     print_apis_in_order( &API_tree[0] );
 
     if( API_cntr != NUM_OF_API_FUNCS ){
-        printf("**ERROR**\tAPI function number mismatch!!!\r\n");
+
+        #ifdef INTERPRETER_DBG
+        INTERPRETER_DBG( "**ERROR**\tAPI function number mismatch!!!\r\n" );
+        #endif
+
     }
 }
 
-void add_interpreter_instruction(const char **name, const char **desc, void (*func)(char *, char *))
+void add_interpreter_instruction(const char **name, const char **desc, void (*func)(char *, int(*resp_fn)(const char*, ...)))
 {
     API_t *next;
     API_t *prev;
@@ -74,7 +114,10 @@ void add_interpreter_instruction(const char **name, const char **desc, void (*fu
     if (API_cntr >= NUM_OF_API_FUNCS)
     {
 
-        printf("**ERROR**\tToo many instruction, memory is full!\r\n");
+        #ifdef INTERPRETER_DBG
+        INTERPRETER_DBG( "**ERROR**\tToo many instruction, memory is full!\r\n" );
+        #endif
+
         return;
     }
 
@@ -141,7 +184,10 @@ void index_apis_in_order(API_t *head){
 
     recursive_indexer( head );
 
-    printf( "Indexer finished...\r\n" );
+    #ifdef INTERPRETER_DBG
+    INTERPRETER_DBG( "Indexer finished...\r\n" );
+    #endif
+    
 
 }
 
@@ -173,7 +219,7 @@ void print_apis_in_order(API_t *head){
   }
 
     print_apis_in_order( head -> left );
-    printf( "%d.\t%s\r\n", head -> place , *(head -> name) );
+    INTERPRETER_PRINTF( "%d.\t%s\r\n", head -> place , *(head -> name) );
     print_apis_in_order( head -> right );
 
 }
@@ -277,7 +323,7 @@ void recursive_optimiser( int32_t start_index, int32_t stop_index ){
 
 }
 
-void execute( char *cmd, char *response ){
+void execute( char *cmd, int(*resp_fn)(const char*, ...) ){
 
     API_t *next;
     API_t *prev;
@@ -310,16 +356,14 @@ void execute( char *cmd, char *response ){
 
     prev = &API_tree[0];
 
-    //comp_res = strncmp( (char*)*(prev->name), cmd, cmd_name_cntr );
-
     comp_res = strncmp( (char*)*(prev->name), cmd, strlen( (char*)*(prev->name) ) );
 
     (comp_res > 0) ? (next = (prev->left)) : ( next = (prev->right));
 
     while( ( comp_res !=0 ) && ( next != NULL ) ){
 
         prev = next;
-        //comp_res = strncmp( (char*)*(prev->name), cmd, cmd_name_cntr );
+
         comp_res = strncmp( (char*)*(prev->name), cmd, strlen( (char*)*(prev->name) ) );
 
         (comp_res > 0) ? (next = (prev->left)) : ( next = (prev->right));
@@ -328,13 +372,13 @@ void execute( char *cmd, char *response ){
 
     if( comp_res == 0 ){
 
-        (prev -> func)( arg, response );
+        (prev -> func)( arg, resp_fn );
 
     }
 
     else{
 
-        printf( "Command \'%s\' not found!!!\r\n", cmd );
+        INTERPRETER_PRINTF( "Command \'%s\' not found!!!\r\n", cmd );
 
     }
 

interpreter.d

@@ -5,24 +5,42 @@
 
 int main(){
 
-    char response[100];
+    //  The interpreter modifies the content of
+    //  the string it gets. Make shore you backup
+    //  it before use it is used after.
+    //  Also note that this variable must not have
+    //  a const type. const char* as argument will
+    //  cause crash!
+    char cmd_to_execute[100] = "stop 10";
 
-    char cmd[100] = "cica 1";
+    printf("Program begin...\r\n");
 
-    printf("Program START...\r\n");
+    //  Interpreter initialization code
+    init_interpreter();
 
+    //  Execute string stored in cmd_to_execute
+    execute( cmd_to_execute, printf );
 
-    init_interpreter();
+    //  Try with empty response function
+    execute( cmd_to_execute, NULL );
 
+    //  Modify the content of cmd_to_execute
+    strcpy( cmd_to_execute, "start 31" );
+    //  Execute string stored in cmd_to_execute
+    execute( cmd_to_execute, printf );
 
-    execute( cmd, response );
+    //  Modify the content of cmd_to_execute
+    strcpy( cmd_to_execute, "left 3" );
+    //  Execute string stored in cmd_to_execute
+    execute( cmd_to_execute, printf );
 
-    strcpy( cmd, "kutya 10" );
-    execute( cmd, response );
+    //  Modify the content of cmd_to_execute
+    strcpy( cmd_to_execute, "right 0" );
+    //  Execute string stored in cmd_to_execute
+    execute( cmd_to_execute, printf );
 
-    strcpy( cmd, "retek 10" );
-    execute( cmd, response );
 
+    printf( "Program end..." );
 
     return 0;
 }