stml.h

   1 /* stml.h
   2 * Status Table Modification Language - Main Library
   3 * Written by Michael D. Reiley (Seisatsu)
   4 * Copyright (c) 2010, Omega Software Development Group
   5 * Released under ISC license
   6 */
   7
   8 #ifndef STML_H
   9 #define STML_H
  10
  11 #include <stdio.h>
  12 #include "bool.h" /*Define the Boolean Datatype*/
  13
  14 /* -- DEFINITIONS SECTION -- */
  15
  16 enum STML_STATE_TYPE { /*Types of states*/
  17         parent_data_t, /*Fake data type that points to one or more substates*/
  18         bool_data_t, /*Boolean type*/
  19         int_data_t, /*Integer type*/
  20         string_data_t, /*String type*/
  21         command_data_t /*A char type whose contents disappear immediately after reading*/
  22 };
  23
  24 typedef struct STML_STATE__ {
  25         char* id; /*Identifier of state*/
  26         unsigned long cbid; /*Callback ID of state; will always be unique*/
  27         STML_STATE_TYPE type; /*Type of state*/
  28         struct STML_STATE__** parent_data; /*State contains more states*/
  29         bool* bool_data; /*State contains a boolean*/
  30         int* int_data; /*State contains an integer*/
  31         char** string_data; /*State contains a string*/
  32         char** command_data; /*State contains a command*/
  33 } STML_STATE;
  34
  35 typedef struct {
  36         char* id; /*Identifier of object*/
  37         STML_STATE** states; /*Child states*/
  38 } STML_OBJECT;
  39
  40 typedef struct { /*This is the only struct that the end user needs to care about.*/
  41         char* id; /*Identifier of table*/
  42         STML_OBJECT** objects; /*Child objects*/
  43 } STML_TABLE;
  44
  45 /* -- FUNCTION SECTION -- */
  46
  47 /* (*stml_callback)
  48 * Function pointer to callback the parent program when a change is made.
  49 * Programs can pass a custom callback function.
  50 *
  51 * Arguments:
  52 * -- 1) STML_TABLE* : STML Table to be used
  53 * -- 2) int : Callback ID for the modified state. See the manual.
  54 * -- 2) void* : Convenience variable that immediately returns the new state.
  55 */
  56 typedef void (*stml_callback) (STML_TABLE* table, unsigned long cbid, void* state);
  57
  58 /* stml_create_table
  59 * Create a new STML table.
  60 * An empty table is returned.
  61 *
  62 * Arguments:
  63 * -- NONE
  64 */
  65 STML_TABLE* stml_create_table ();
  66
  67 /* stml_destroy_table
  68 * Destroy the table passed to this function.
  69 *
  70 * Arguments:
  71 * -- STML_TABLE* : The table to be destroyed.
  72 */
  73 void stml_destroy_table (STML_TABLE* table);
  74
  75 /* stml_command
  76 * Pass a command to the interpreter.
  77 * Returns 0 if successful, error code otherwise.
  78 *
  79 * Arguments:
  80 * -- 1) STML_TABLE* : The table to be used.
  81 * -- 2) char* : Command string to be interpreted.
  82 * -- 3) void* : Returns data if the command is a query type.
  83 * -- 4) int* : If a new state was created, returns a unique callback ID. Otherwise, 0. See the manual.
  84 */
  85 int stml_command (STML_TABLE* table, char* command, void* data, int* cbid);
  86
  87 /* stml_save
  88 * Save a table in XML format.
  89 *
  90 * Arguments:
  91 * -- 1) STML_TABLE* : Table to save.
  92 * -- 2) FILE* : File pointer to dump XML data to.
  93 */
  94 void stml_save (STML_TABLE* table, FILE* file);
  95
  96 /* stml_load
  97 * Load a table in XML format.
  98 * Returns a table if successful, null if failed.
  99 *
 100 * Arguments:
 101 * -- 1) FILE* : File pointer to load XML data from.
 102 */
 103 STML_TABLE* stml_load (STML_TABLE* table, FILE* file);
 104
 105 /* stml_macro_import
 106 * Import a macro definition table into the interpreter.
 107 * Returns 0 if successful, error code otherwise.
 108 * Requires STML_XML extension.
 109 *
 110 * Arguments:
 111 * -- 1) FILE* : File pointer to definition table XML file.
 112 */
 113 int stml_macro_import (FILE* macro_table);
 114
 115 #endif