| /* |
| * Copyright 2001-2004 Brandon Long |
| * All Rights Reserved. |
| * |
| * ClearSilver Templating System |
| * |
| * This code is made available under the terms of the ClearSilver License. |
| * http://www.clearsilver.net/license.hdf |
| * |
| */ |
| |
| #ifndef __NEO_HDF_H_ |
| #define __NEO_HDF_H_ 1 |
| |
| __BEGIN_DECLS |
| |
| #include <stdio.h> |
| #include "util/neo_err.h" |
| #include "util/neo_hash.h" |
| |
| #define FORCE_HASH_AT 10 |
| |
| typedef struct _hdf HDF; |
| |
| /* HDFFILELOAD is a callback function to intercept file load requests and |
| * provide templates via another mechanism. This way you can load templates |
| * that you compiled-into your binary, from in-memory caches, or from a |
| * zip file, etc. The HDF is provided so you can choose to use the |
| * hdf_search_path function to find the file. contents should return |
| * a full malloc copy of the contents of the file, which the parser will |
| * own and free. Use hdf_register_fileload to set this function for |
| * your top level HDF node. |
| * NOTE: Technically, we shouldn't need a separate copy for each parse, but |
| * using the separate copy makes this equivalent to the CSFILELOAD function. We |
| * can change this if we really want to save that copy at the expense of |
| * slightly more complicated code. */ |
| typedef NEOERR* (*HDFFILELOAD)(void *ctx, HDF *hdf, const char *filename, |
| char **contents); |
| |
| typedef struct _attr |
| { |
| char *key; |
| char *value; |
| struct _attr *next; |
| } HDF_ATTR; |
| |
| struct _hdf |
| { |
| int link; |
| int alloc_value; |
| char *name; |
| int name_len; |
| char *value; |
| struct _attr *attr; |
| struct _hdf *top; |
| struct _hdf *next; |
| struct _hdf *child; |
| |
| /* the following fields are used to implement a cache */ |
| struct _hdf *last_hp; |
| struct _hdf *last_hs; |
| |
| /* the following HASH is used when we reach more than FORCE_HASH_AT |
| * elements */ |
| NE_HASH *hash; |
| /* When using the HASH, we need to know where to append new children */ |
| struct _hdf *last_child; |
| |
| /* Should only be set on the head node, used to override the default file |
| * load method */ |
| void *fileload_ctx; |
| HDFFILELOAD fileload; |
| }; |
| |
| /* |
| * Function: hdf_init - Initialize an HDF data set |
| * Description: hdf_init initializes an HDF data set and returns the |
| * pointer to the top node in the data set. |
| * Input: hdf - pointer to an HDF pointer |
| * Output: hdf - allocated hdf node |
| * Returns: NERR_NOMEM - unable to allocate memory for dataset |
| */ |
| NEOERR* hdf_init (HDF **hdf); |
| |
| /* |
| * Function: hdf_destroy - deallocate an HDF data set |
| * Description: hdf_destroy is used to deallocate all memory associated |
| * with an hdf data set. Although you can pass an HDF node |
| * as an argument to this function, you are likely to cause |
| * a segfault if you continue to access the data set. In |
| * the future, we may restrict hdf_destroy so it only works |
| * on the top level node. |
| * Input: hdf - pointer to an HDF data set allocated with hdf_init |
| * Output: None |
| * Returns: None |
| */ |
| void hdf_destroy (HDF **hdf); |
| |
| /* |
| * Function: hdf_get_int_value - Return the integer value of a point in |
| * the data set |
| * Description: hdf_get_int_value walks the HDF data set pointed to by |
| * hdf to name, and returns the value of that node |
| * converted to an integer. If that node does not exist, |
| * or it does not contain a number, the defval is returned. |
| * Input: hdf -> a node in an HDF data set |
| * name -> the name of a node to walk to in the data set |
| * defval -> value to return in case of error or if the node |
| * doesn't exist |
| * Output: None |
| * Returns: The integer value of the node, or the defval |
| */ |
| int hdf_get_int_value (HDF *hdf, const char *name, int defval); |
| |
| /* |
| * Function: hdf_get_value - Return the value of a node in the data set |
| * Description: hdf_get_value walks the data set pointed to by hdf via |
| * name and returns the string value located there, or |
| * defval if the node doesn't exist |
| * Input: hdf -> the dataset node to start from |
| * name -> the name to walk the data set to |
| * defval -> the default value to return if the node doesn't |
| * exist |
| * Output: None |
| * Returns: A pointer to the string stored in the data set, or defval. |
| * The data set maintains ownership of the string, if you want |
| * a copy you either have to call strdup yourself, or use |
| * hdf_get_copy |
| */ |
| char *hdf_get_value (HDF *hdf, const char *name, const char *defval); |
| |
| /* |
| * Function: hdf_get_valuevf - Return the value of a node in the data set |
| * Description: hdf_get_valuevf walks the data set pointed to by hdf via |
| * namefmt printf expanded with varargs ap, and returns the |
| * string value located there, or NULL if it doesn't exist. |
| * This differs from hdf_get_value in that there is no |
| * default value possible. |
| * Input: hdf -> the dataset node to start from |
| * namefmt -> the format string |
| * ap -> va_list of varargs |
| * Output: None |
| * Returns: A pointer to the string stored in the data set, or NULL. |
| * The data set maintains ownership of the string, if you want |
| * a copy you either have to call strdup yourself. |
| */ |
| char* hdf_get_valuevf (HDF *hdf, const char *namefmt, va_list ap); |
| |
| /* |
| * Function: hdf_get_valuef - Return the value of a node in the data set |
| * Description: hdf_get_valuef walks the data set pointed to by hdf via |
| * namefmt printf expanded with varargs, and returns the |
| * string value located there, or NULL if it doesn't exist. |
| * This differs from hdf_get_value in that there is no |
| * default value possible. |
| * Input: hdf -> the dataset node to start from |
| * namefmt -> the printf-style format string |
| * ... -> arguments to fill out namefmt |
| * Output: None |
| * Returns: A pointer to the string stored in the data set, or NULL. |
| * The data set maintains ownership of the string, if you want |
| * a copy you either have to call strdup yourself. |
| */ |
| char* hdf_get_valuef (HDF *hdf, const char *namefmt, ...) |
| ATTRIBUTE_PRINTF(2,3); |
| |
| /* |
| * Function: hdf_get_copy - Returns a copy of a string in the HDF data set |
| * Description: hdf_get_copy is similar to hdf_get_value, except that it |
| * returns an malloc'd copy of the string. |
| * Input: hdf -> the dataset node to start from |
| * name -> the name to walk the data set to |
| * defval -> the default value to return if the node doesn't |
| * exist |
| * Output: value -> the allocated string (if defval = NULL, then value |
| * will be NULL if defval is used) |
| * Returns: NERR_NOMEM if unable to allocate the new copy |
| */ |
| NEOERR* hdf_get_copy (HDF *hdf, const char *name, char **value, |
| const char *defval); |
| |
| /* |
| * Function: hdf_get_obj - return the HDF data set node at a named location |
| * Description: hdf_get_obj walks the dataset given by hdf to the node |
| * named name, and then returns the pointer to that node |
| * Input: hdf -> the dataset node to start from |
| * name -> the name to walk to |
| * Output: None |
| * Returns: the pointer to the named node, or NULL if it doesn't exist |
| */ |
| HDF* hdf_get_obj (HDF *hdf, const char *name); |
| |
| /* |
| * Function: hdf_get_node - Similar to hdf_get_obj except all the nodes |
| * are created if the don't exist. |
| * Description: hdf_get_node is similar to hdf_get_obj, except instead |
| * of stopping if it can't find a node in the tree, it will |
| * create all of the nodes necessary to hand you back the |
| * node you ask for. Nodes are created with no value. |
| * Input: hdf -> the dataset node to start from |
| * name -> the name to walk to |
| * Output: ret -> the dataset node you asked for |
| * Returns: NERR_NOMEM - unable to allocate new nodes |
| */ |
| NEOERR * hdf_get_node (HDF *hdf, const char *name, HDF **ret); |
| |
| /* |
| * Function: hdf_get_child - return the first child of the named node |
| * Description: hdf_get_child will walk the dataset starting at hdf to |
| * name, and return the first child of that node |
| * Input: hdf -> the dataset node to start from |
| * name -> the name to walk to |
| * Output: None |
| * Returns: The first child of the named dataset node or NULL if the |
| * node is not found (or it has no children) |
| */ |
| HDF* hdf_get_child (HDF *hdf, const char *name); |
| |
| /* |
| * Function: hdf_get_attr - |
| * Description: |
| * Input: |
| * Output: |
| * Returns: |
| */ |
| HDF_ATTR* hdf_get_attr (HDF *hdf, const char *name); |
| |
| /* |
| * Function: hdf_set_attr - |
| * Description: |
| * Input: |
| * Output: |
| * Returns: |
| */ |
| NEOERR* hdf_set_attr (HDF *hdf, const char *name, const char *key, |
| const char *value); |
| |
| /* |
| * Function: hdf_obj_child - Return the first child of a dataset node |
| * Description: hdf_obj_child and the other hdf_obj_ functions are |
| * accessors to the HDF dataset. Although we do not |
| * currently "hide" the HDF struct implementation, we |
| * recommend you use the accessor functions instead of |
| * accessing the values directly. |
| * Input: hdf -> the hdf dataset node |
| * Output: None |
| * Returns: The pointer to the first child, or NULL if there is none |
| */ |
| HDF* hdf_obj_child (HDF *hdf); |
| |
| /* |
| * Function: hdf_obj_next - Return the next node of a dataset level |
| * Description: hdf_obj_next is an accessor function for the HDF struct |
| * Input: hdf -> the hdf dataset node |
| * Output: None |
| * Returns: The pointer to the next node, or NULL if there is none |
| */ |
| HDF* hdf_obj_next (HDF *hdf); |
| |
| /* |
| * Function: hdf_obj_top - Return the pointer to the top dataset node |
| * Description: hdf_obj_top is an accessor function which returns a |
| * pointer to the top of the dataset, the node which was |
| * returned by hdf_init. This is most useful for |
| * implementations of language wrappers where individual |
| * nodes are tied garbage colletion wise to the top node of |
| * the data set |
| * Input: hdf -> the hdf dataset node |
| * Output: None |
| * Returns: The pointer to the top node |
| */ |
| HDF* hdf_obj_top (HDF *hdf); |
| |
| /* |
| * Function: hdf_obj_attr - Return the HDF Attributes for a node |
| * Description: |
| * Input: |
| * Output: |
| * Returns: |
| */ |
| HDF_ATTR* hdf_obj_attr (HDF *hdf); |
| |
| /* |
| * Function: hdf_obj_name - Return the name of a node |
| * Description: hdf_obj_name is an accessor function for a datset node |
| * which returns the name of the node. This is just the |
| * local name, and not the full path. |
| * Input: hdf -> the hdf dataset node |
| * Output: None |
| * Returns: The name of the node. If this is the top node, the name is |
| * NULL. |
| */ |
| char* hdf_obj_name (HDF *hdf); |
| |
| /* |
| * Function: hdf_obj_value - Return the value of a node |
| * Description: hdf_obj_value is an accessor function for a dataset node |
| * which returns the value of the node, or NULL if the node |
| * has no value. This is not a copy of the value, so the |
| * node retains ownership of the value |
| * Input: hdf -> the hdf dataset node |
| * Output: None |
| * Returns: The value of the node, or NULL if it has no value |
| */ |
| char* hdf_obj_value (HDF *hdf); |
| |
| /* |
| * Function: hdf_set_value - Set the value of a named node |
| * Description: hdf_set_value will set the value of a named node. All |
| * of the interstitial nodes which don't exist will be |
| * created with a value of NULL. Existing nodes are not |
| * modified. New nodes are created at the end of the list. |
| * If a list of nodes exceeds FORCE_HASH_AT, then a HASH |
| * will be created at that level and all of the nodes will |
| * be added to the hash for faster lookup times. |
| * The copy of the value will be made which the dataset |
| * will own. |
| * Input: hdf -> the pointer to the hdf dataset |
| * name -> the named node to walk to |
| * value -> the value to set the node to |
| * Output: None |
| * Returns: NERR_NOMEM |
| */ |
| NEOERR* hdf_set_value (HDF *hdf, const char *name, const char *value); |
| |
| /* |
| * Function: hdf_set_valuef - Set the value of a named node |
| * Description: hdf_set_valuef is a convenience function that wraps |
| * hdf_set_value. Due to limitations of C, the fmt is in |
| * the format "name=value", where we will first format the |
| * entire string, and then break it at the first (from the |
| * left) equal sign (=) and use the left portion as the |
| * name and the right portion as the value. This function |
| * is somewhat inefficient in that it first allocates the |
| * full name=value, and then the call to hdf_set_value |
| * duplicates the value portion, and then we free the |
| * name=value. |
| * Currently, we don't strip whitespace from the key or |
| * value. In the future, this function might work more |
| * like reading a single line of an HDF string or file, |
| * allowing for attributes and symlinks to be specified... |
| * maybe. |
| * Input: hdf -> the pointer to the hdf dataset |
| * fmt -> the name=value printf(3) format string |
| * Output: None |
| * Returns: NERR_NOMEM |
| */ |
| NEOERR* hdf_set_valuef (HDF *hdf, const char *fmt, ...) |
| ATTRIBUTE_PRINTF(2,3); |
| NEOERR* hdf_set_valuevf (HDF *hdf, const char *fmt, va_list ap); |
| |
| /* |
| * Function: hdf_set_int_value - Set the value of a named node to a number |
| * Description: hdf_set_int_value is a helper function that maps an |
| * integer to a string, and then calls hdf_set_value with |
| * that string |
| * Input: hdf -> the pointer to the hdf dataset |
| * name -> the named node to walk to |
| * value -> the value to set the node to |
| * Output: None |
| * Returns: NERR_NOMEM |
| */ |
| NEOERR* hdf_set_int_value (HDF *hdf, const char *name, int value); |
| |
| /* |
| * Function: hdf_set_copy -> Copy a value from one location in the |
| * dataset to another |
| * Description: hdf_set_copy first walks the hdf dataset to the named src |
| * node, and then copies that value to the named dest node. |
| * If the src node is not found, an error is raised. |
| * Input: hdf -> the pointer to the dataset node |
| * dest -> the name of the destination node |
| * src -> the name of the source node |
| * Output: None |
| * Returns: NERR_NOMEM, NERR_NOT_FOUND |
| */ |
| NEOERR* hdf_set_copy (HDF *hdf, const char *dest, const char *src); |
| |
| /* |
| * Function: hdf_set_buf - Set the value of a node without duplicating |
| * the value |
| * Description: hdf_set_buf is similar to hdf_set_value, except the |
| * dataset takes ownership of the value instead of making a |
| * copy of it. The dataset assumes that value was |
| * malloc'd, since it will attempt to free it when |
| * hdf_destroy is called |
| * Input: hdf -> the hdf dataset node |
| * name -> the name to walk to |
| * value -> the malloc'd value |
| * Output: None |
| * Returns: NERR_NOMEM - unable to allocate a node |
| */ |
| |
| NEOERR* hdf_set_buf (HDF *hdf, const char *name, char *value); |
| |
| /* |
| * Function: hdf_set_symlink - Set part of the tree to link to another |
| * Description: hdf_set_symlink creates a link between two sections of |
| * an HDF dataset. The link is "by name" hence the term |
| * "symlink". This means that the destination node does |
| * not need to exist. Any attempt to access the source |
| * node will cause the function to walk to the dest node, |
| * and then continue walking from there. Using symlinks |
| * can "hide" values in the dataset since you won't be able |
| * to access any children of the linked node directly, |
| * though dumps and other things which access the data |
| * structure directly will bypass the symlink. Use this |
| * feature sparingly as its likely to surprise you. |
| * Input: hdf -> the dataset node |
| * src -> the source node name |
| * dest -> the destination node name (from the top of the |
| * dataset, not relative names) |
| * Output: None |
| * Returns: NERR_NOMEM |
| */ |
| NEOERR *hdf_set_symlink (HDF *hdf, const char *src, const char *dest); |
| |
| /* |
| * Function: hdf_sort_obj - sort the children of an HDF node |
| * Description: hdf_sort_obj will sort the children of an HDF node, |
| * based on the given comparison function. |
| * This function works by creating an array of the pointers |
| * for each child object of h, using qsort to sort that |
| * array, and then re-ordering the linked list of children |
| * to the new order. The qsort compare function uses a |
| * pointer to the value in the array, which in our case is |
| * a pointer to an HDF struct, so your comparison function |
| * should work on HDF ** pointers. |
| * Input: h - HDF node |
| * compareFunc - function which returns 1,0,-1 depending on some |
| * criteria. The arguments to this sort function |
| * are pointers to pointers to HDF elements. For |
| * example: |
| * int sortByName(const void *a, const void *b) { |
| * HDF **ha = (HDF **)a; |
| * HDF **hb = (HDF **)b; |
| * |
| * return strcasecmp(hdf_obj_name(*ha), hdf_obj_name(*hb)); |
| * } |
| * |
| * Output: None (h children will be sorted) |
| * Return: NERR_NOMEM |
| */ |
| NEOERR *hdf_sort_obj(HDF *h, int (*compareFunc)(const void *, const void *)); |
| |
| /* |
| * Function: hdf_read_file - read an HDF data file |
| * Description: |
| * Input: |
| * Output: |
| * Returns: NERR_IO, NERR_NOMEM, NERR_PARSE |
| */ |
| NEOERR* hdf_read_file (HDF *hdf, const char *path); |
| |
| /* |
| * Function: hdf_write_file - write an HDF data file |
| * Description: |
| * Input: |
| * Output: |
| * Returns: NERR_IO |
| */ |
| NEOERR* hdf_write_file (HDF *hdf, const char *path); |
| |
| /* |
| * Function: hdf_write_file_atomic - write an HDF data file atomically |
| * Description: hdf_write_file_atomic is similar to hdf_write_file, |
| * except the new file is created with a unique name and |
| * then rename(2) is used to atomically replace the old |
| * file with the new file |
| * Input: |
| * Output: |
| * Returns: NERR_IO |
| */ |
| NEOERR* hdf_write_file_atomic (HDF *hdf, const char *path); |
| |
| /* |
| * Function: hdf_read_string - read an HDF string |
| * Description: |
| * Input: |
| * Output: |
| * Returns: NERR_NOMEM, NERR_PARSE |
| */ |
| NEOERR* hdf_read_string (HDF *hdf, const char *s); |
| |
| /* |
| * Function: hdf_read_string_ignore - Read an HDF string and ignore errors |
| * Description: |
| * Input: |
| * Output: |
| * Returns: NERR_NOMEM |
| */ |
| NEOERR* hdf_read_string_ignore (HDF *hdf, const char *s, int ignore); |
| |
| /* |
| * Function: hdf_write_string - serialize an HDF dataset to a string |
| * Description: |
| * Input: |
| * Output: |
| * Returns: NERR_NOMEM |
| */ |
| NEOERR* hdf_write_string (HDF *hdf, char **s); |
| |
| /* |
| * Function: hdf_dump - dump an HDF dataset to stdout |
| * Description: |
| * Input: |
| * Output: |
| * Returns: |
| */ |
| NEOERR* hdf_dump (HDF *hdf, const char *prefix); |
| |
| /* |
| * Function: hdf_dump_format - dump an HDF dataset to FILE *fp |
| * Description: |
| * Input: |
| * Output: |
| * Returns: |
| */ |
| NEOERR* hdf_dump_format (HDF *hdf, int lvl, FILE *fp); |
| |
| /* |
| * Function: hdf_dump_str - dump an HDF dataset to STRING |
| * Description: |
| * Input: |
| * Output: |
| * Returns: |
| */ |
| NEOERR* hdf_dump_str(HDF *hdf, const char *prefix, int compact, STRING *str); |
| |
| /* |
| * Function: hdf_remove_tree - delete a subtree of an HDF dataset |
| * Description: |
| * Input: |
| * Output: |
| * Returns: |
| */ |
| NEOERR* hdf_remove_tree (HDF *hdf, const char *name); |
| |
| /* |
| * Function: hdf_copy - copy part of an HDF dataset to another |
| * Description: hdf_copy is a deep copy of an HDF tree pointed to by |
| * src to the named node of dest. dest and src need not be |
| * part of the same data set |
| * Input: dest_hdf -> the destination dataset |
| * name -> the name of the destination node |
| * src -> the hdf dataset to copy to the destination |
| * Output: None |
| * Returns: NERR_NOMEM, NERR_NOT_FOUND |
| */ |
| NEOERR* hdf_copy (HDF *dest_hdf, const char *name, HDF *src); |
| |
| /* |
| * Function: hdf_search_path - Find a file given a search path in HDF |
| * Description: hdf_search_path is a convenience/utility function that |
| * searches for relative filenames in a search path. The |
| * search path is the list given by the children of |
| * hdf.loadpaths. |
| * Input: hdf -> the hdf dataset to use |
| * path -> the relative path |
| * full -> a pointer to a _POSIX_PATH_MAX buffer |
| * Output: full -> the full path of the file |
| * Returns: NERR_NOT_FOUND if the file wasn't found in the search path |
| */ |
| NEOERR* hdf_search_path (HDF *hdf, const char *path, char *full); |
| |
| /* |
| * Function: hdf_register_fileload - register a fileload function |
| * Description: hdf_register_fileload registers a fileload function that |
| * overrides the built-in function. The built-in function |
| * uses hdf_search_path and ne_file_load (based on stat/open/read) |
| * to find and load the file on every hdf_read_file (including |
| * #include). You can override this function if you wish to provide |
| * other file search functions, or load the hdf file |
| * from an in-memory cache, etc. |
| * Input: hdf - pointer to a head HDF node |
| * ctx - pointer that is passed to the HDFFILELOAD function when called |
| * fileload - a HDFFILELOAD function |
| * Output: None |
| * Return: None |
| * |
| */ |
| |
| void hdf_register_fileload(HDF *hdf, void *ctx, HDFFILELOAD fileload); |
| |
| __END_DECLS |
| |
| #endif /* __NEO_HDF_H_ */ |
