Restructuring the main API and project

This commit rewrites pretty much the entire library. It is now much
smaller and more maintainable (split over multiple files). It will now
also support more features (that aren't implemented yet).

Adding two examples to show how to use the new API. Also changing the
name of the library everywhere.

1 files changed, 66 insertions, 347 deletions

diff --git a/bowl.h b/bowl.h
index 88811c4..63149d2 100644
--- a/bowl.h
+++ b/bowl.h
@@ -1,378 +1,97 @@
-/*
- * Please use the API to create and destroy objects as only this way
- * memory-safety and memory leaks can be guaranteed.
- *
- * With the API you can easily create structures like the following:
- *
- * root [list]
- *    child1 [list]
- *       key [literal] - "Username"
- *       value [literal] - "spacekookie"
- *    child2 [list]
- *       key [literal] - "Age"
- *       value [numerical] - 23
- *    child3
- *       subchild [list]
- *          ...
- *
- * Freeing the root node will free all children
- */
-
 #ifndef _BOWL_H_
 #define _BOWL_H_
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 #include <memory.h>
 #include <stdbool.h>
 
-/* A helpful macro that can take care of \0 termated strings! */
 #define REAL_STRLEN(str) (strlen(str) + 1)
+#define CHECK(ptr, err) if(!ptr) return err;
 
-/* Also make sure we're _always_ interpreted as a C file */
-#ifdef __cplusplus
-extern "C" {
-#endif
-
+/** Define some generic error codes first that we can propagate **/
+typedef enum err_t {
+    OK = 0,
+    ERR = -1,
+    NOT_IMPLEMENTED = 1,    // A runtime error for missing features
+
+    INVALID_PARAMS = 2,     // A function didn't get the required parameters
+    MALLOC_FAILED = 3,      // A memory allocation failed
+    INVALID_STATE = 4,      // Calling an operation on an invalid state
+} err_t;
+
+typedef enum data_t {
+    LITERAL,    // Any string that is \0 terminated
+    INTEGER,    // Integer value
+    REAL,       // Floating point value
+    BOOLEAN,    // A 1-byte boolean
+    RAW         // A platform-length pointer
+} data_t;
 
-/* Type that determines what data is stored inside a tree-node */
 typedef enum bowl_t {
-    UNSET, LITERAL, NUMERIC, LONG_NUMERIC, BOOLEAN, LIST, PAIR, POINTER
+    LEAF = 1, ARRAY, HASH, LINKED
 } bowl_t;
 
-
 struct bowl {
-    bowl_t          type;
-    short           encset;
-    size_t          size, used;
-    short           copy;
+    bowl_t  type;
     union {
-        char                *literal;
-        bool                boolean;
-        struct bowl        *(*list);
-        void                *pointer;
-#ifdef __LONG_LONG_SUPPORT__
-        long long           numeral;
-#else
-        long                numeral;
-#endif
-
-    } payload;
+        struct data     *data;
+        struct bowl_arr *array;
+        struct b_ptr    *linked;
+    } _pl;
 };
 
+struct data {
+    data_t type;
+    union {
+        char    *literal;
+        bool    boolean;
+        long    integer;
+        double  real;
+        void    *raw;
+    } _pl;
+};
 
-/** Define some generic error codes first that we can propagate **/
-typedef enum dt_err {
-
-    /* General purpose error codes */
-    FAILURE = -1,
-    SUCCESS = 0,
-
-    INVALID_PARAMS,         // A function didn't get the required parameters
-    MALLOC_FAILED,          // A memory allocation failed
-    INVALID_PAYLOAD,        // The payload of a node is invalid
-    DATA_NOT_RELATED,       // Tried to split non-related trees
-    NODE_NOT_FOUND,         // The sought after node was not found
-    NODE_NOT_ORIGINAL,      // Tried to free a node which was a shallow copy
-    QUERY_TOO_DEEP,
-
-} dt_err;
-
-
-/**
- * Malloc a new bowl object
- *
- * @param data Reference pointer to bowl element
- * @return
- */
-dt_err bowl_malloc(struct bowl *(*data));
-
-
-/**
- * Reset the type of a node and free child data
- *
- * @param data
- * @return
- */
-dt_err bowl_resettype(struct bowl *data);
-
-
-/**
- * Set the data element to a literal and save it's length
- *
- * @param data Reference to a bowl object
- * @param literal String to store
- * @return
- */
-dt_err bowl_addliteral(struct bowl *data, const char *literal);
-
-
-/**
- * Set the data element to a numeral
- *
- * @param data Reference to a bowl object
- * @param numeral Number to store
- * @return
- */
-dt_err bowl_addnumeral(struct bowl *data, long numeral);
-
-
-/**
- * Set the data element to a boolean. Do you really
- * need this? Consider using @bowl_add_numeral instead.
- *
- * @param data Reference to a bowl object
- * @param b boolean value (true, false)
- * @return
- */
-dt_err bowl_addboolean(struct bowl *data, bool b);
-
-
-/**
- * Add two new elements as a PAIR node under an existing node
- *
- * @param data bowl node to become the sub-root
- * @param key Reference pointer to the key node
- * @param value Reference pointer to the value node
- * @return
- */
-dt_err bowl_addpair(struct bowl *data, struct bowl *(*key), struct bowl *(*value));
-
-
-/**
- * Add a new data element to the resursive data store
- *
- * @param data Root reference
- * @param new_data Reference pointer to a new bowl node
- * @return
- */
-dt_err bowl_addlist(struct bowl *data, struct bowl *(*new_data));
-
-
-/**
- * This function enables you to store your own structures in a node. It however
- * also requires you to do some of your own memory management.
- *
- * WARNING: Can leak memory if pointer is previously set!
- *
- * To make sure that this function CAN NOT leak memory you should run
- * "bowl_resettype" on the root element to remove the pointer.
- *
- * Also make sure that no other part of your application will use the
- * pointer at a later date!
- *
- * @param data Root reference
- * @param ptr A pointer to store in this node
- * @return
- */
-dt_err bowl_addpointer(struct bowl *data, void *ptr);
-
-
-/**
- * This function takes two nodes as arguments. The nodes MUST be
- * related or an error will be thrown. Both nodes will still
- * be accessable after this operation but no longer be related to
- * each other.
- *
- * The second node will be removed from the tree of the root node.
- *
- *
- *
- * @param data Root reference
- * @param sp Subtree node related to root to split off
- * @return
- */
-dt_err bowl_split_trees(struct bowl *data, struct bowl *sp);
-
-
-/**
- * This function is very simmilar to  dt_err "bowl_addlist"
- * with the difference that it doesn't allocate new memory but instead
- * works with existing nodes.
- *
- * You need to provide a ROOT node which is of type list. It will
- * procede to add the second (merge) node into the child-list of the
- * root data node - essentially making them related.
- *
- * This allows for very efficient tree merging.
- *
- * @param data Root reference
- * @param merge Second root reference to merge
- * @return
- */
-dt_err bowl_merge_trees(struct bowl *data, struct bowl *merge);
-
-
-/**
- * You can use this function to search the structure of a root node to find the
- * parent of the node you provide as "data". It will leave the search pointer
- * blanked if the node can't be found in the structure.
- *
- * @param root Root reference to search
- * @param data The node we are searching for
- * @param parent The node parent we are interested in
- * @return
- */
-dt_err bowl_parent(struct bowl *root, struct bowl *data, struct bowl **parent);
-
-
-/**
- * Recursive tree search function that will return the first occurence match
- * to a provided payload (with an exact type). If you have data duplication
- * in your tree this _might_ return some false positives.
- *
- * @param data Root reference to search
- * @param found Empty pointer to put found node into
- * @param payload What should be found
- * @param type What type of data should be found
- * @return
- */
-dt_err bowl_search_payload(struct bowl *data, struct bowl *(*found), void *payload, bowl_t type);
-
-
-/**
- * Much like #{bowl_search_payload} but limiting it's search to keys in a list structure of certain depth.
- * This means that in a key-value store structure only top-level items can be searched or the entire
- * depth of the tree (or any vaue in between)
- *
- * @param data
- * @param found
- * @param payload
- * @param type
- * @return
- */
-dt_err bowl_search_keypayload(struct bowl *data, struct bowl *(*found), void *payload, bowl_t type, int depth);
-
-
-/**
- * Performs a deep copy of a data node hirarchy. Does not copy externally
- * pointed structures. Does garuantee safety of hirarchy.
- *
- * @param data
- * @param copy
- * @return
- */
-dt_err bowl_copy_deep(struct bowl *data, struct bowl *(*copy));
-
-
-/**
- * Performs a copy operation on a single node. Copies the payload on a pointer
- * level which means that strings and numbers will be duplicated whereas external
- * pointers and lists will only be references to the original content.
- *
- * Freeing the copy has no effect on the original payloads stored in other
- * nodes.
- *
- * @param data
- * @param copy
- * @return
- */
-dt_err bowl_copy(struct bowl *data, struct bowl *(*copy));
-
-
-/**
- * A retrieve function to get data back from a node that doesn't require
- * you to manually access parts of the struct.
- *
- * Needs to be provided with a reference to a pointer that can then be
- * written to. You can make the reference type specific if you know
- * what kind of data you're expecting. Please however note that compiler
- * errors might occur if you provide a wrong pointer type.
- *
- * @param data Node reference to access
- * @param val Reference pointer to write into
- * @return
- */
-dt_err bowl_get(struct bowl *data, void *(*val));
-
-
-/**
- * Return the type of a node as plain text
- *
- * @param data
- * @return
- */
-const char *bowl_dtype(struct bowl *data);
-
-
-/**
- * Prints the data bowl object and all of its children
- *
- * @param data
- */
-void bowl_print(struct bowl *data);
-
-
-/**
- * Will free the data reference and all of it's children. It will however NOT
- * touch pointers to objects that weren't allocated by libdyntree!
- *
- * @param data
- * @return
- */
-dt_err bowl_free_shallow(struct bowl *data);
+struct bowl_arr {
+    size_t size, used;
+    struct bowl **ptr;
+};
 
+struct b_ptr {
+    struct bowl     *self;
+    struct b_ptr    *next;
+};
 
-/**
- * Like #{bowl_free_shallow} but will also remove structs that
- * weren't allocated by libdyntree. Will throw warnings when trying
- * to free payloads from shallow copy nodes
- *
- * @param data
- * @return
- */
-dt_err bowl_free(struct bowl *data);
+/// Allocate memory for an new, empty bowl node
+err_t bowl_malloc(struct bowl **, bowl_t);
 
+/// Insert one node into another
+err_t bowl_insert(struct bowl *, struct bowl *);
 
-/**************************
- *
- * Error handling functions
- *
- **************************/
+/// Insert a node into a specific index of another node
+err_t bowl_insert_key(struct bowl *, size_t idx, struct bowl *);
 
-const char *bowl_err_getmsg(dt_err *e);
+/// Insert and swap a key in place, returning the old one
+err_t bowl_swap_key(struct bowl *, size_t idx, struct bowl *, struct bowl **);
 
-/***************************
- *
- * Encoding/ Decoding support hooks
- *
- ***************************/
+/// Remove a bowl node by it's pointer reference
+err_t bowl_remove(struct bowl *, struct bowl *);
 
-/**
- * This function sets the wanted encoding setting on a
- * root node (and assumes for children). Without setting flags via
- * this function first the encode will fail.
- *
- * @param data Root reference
- * @param setting Look at DYNTREE_JSON flags for options
- * @return
- */
-dt_err bowl_encode_set(struct bowl *data, short setting);
+/// Removing a bowl node with a key
+err_t bowl_remove_key(struct bowl *, size_t idx, struct bowl **);
 
-/**
- * A simple list node walker that encodes a dyn_tree node hirarchy
- * into a json string. Requires the encoding setting to be set on the
- * root node in order to successfully encode.
- *
- * Can throw errors and initialise NULL return string.
- *
- * @param data
- * @param json_data
- * @return
- */
-dt_err bowl_encode_json(struct bowl *data, char *json_data);
+/// Cascade-free memory from a bowl node
+err_t bowl_free(struct bowl *);
 
+/// Allocate memory for a new data node
+err_t data_malloc(struct bowl **, data_t, ...);
 
-/**
- * Decodes a json string into a dyn_tree node hirarchy while providing
- * memory safety and error checking. Will gracefully return errors
- * if the provided json string is invalid or contains errors.
- *
- * @param data New root reference
- * @param json_data Input json string
- * @return
- */
-dt_err bowl_decode_json(struct bowl *(*data), const char *json_data, size_t len);
+/// Free all data node memory
+err_t data_free(struct data *);
 
 #ifdef __cplusplus
 }
 #endif
-#endif //_DYNTREE_H_
+#endif // _BOWL_H_
\ No newline at end of file