hphp/neo/neo_hdf.h

   1 /*
   2  * Copyright 2001-2004 Brandon Long
   3  * All Rights Reserved.
   4  *
   5  * ClearSilver Templating System
   6  *
   7  * This code is made available under the terms of the ClearSilver License.
   8  * http://www.clearsilver.net/license.hdf
   9  *
  10  */
  11
  12 #ifndef incl_HPHP_NEO_HDF_H_
  13 #define incl_HPHP_NEO_HDF_H_ 1
  14
  15
  16 #include <stdio.h>
  17 #include "hphp/neo/neo_err.h"
  18 #include "hphp/neo/neo_hash.h"
  19
  20 __BEGIN_DECLS
  21 #define FORCE_HASH_AT 10
  22
  23 typedef struct _hdf HDF;
  24
  25 typedef struct _attr
  26 {
  27   char *key;
  28   char *value;
  29   struct _attr *next;
  30 } HDF_ATTR;
  31
  32 struct _hdf
  33 {
  34   int link;
  35   int alloc_value;
  36   char *name;
  37   int name_len;
  38   char *value;
  39   struct _attr *attr;
  40   struct _hdf *top;
  41   struct _hdf *next;
  42   struct _hdf *child;
  43
  44   /* the following fields are used to implement a cache */
  45   struct _hdf *last_hp;
  46   struct _hdf *last_hs;
  47
  48   /* the following HASH is used when we reach more than FORCE_HASH_AT
  49    * elements */
  50   NE_HASH *hash;
  51   /* When using the HASH, we need to know where to append new children */
  52   struct _hdf *last_child;
  53
  54   int visited;
  55 };
  56
  57 /*
  58  * Function: hdf_init - Initialize an HDF data set
  59  * Description: hdf_init initializes an HDF data set and returns the
  60  *              pointer to the top node in the data set.
  61  * Input: hdf - pointer to an HDF pointer
  62  * Output: hdf - allocated hdf node
  63  * Returns: NERR_NOMEM - unable to allocate memory for dataset
  64  */
  65 NEOERR* hdf_init (HDF **hdf);
  66
  67 /*
  68  * Function: hdf_destroy - deallocate an HDF data set
  69  * Description: hdf_destroy is used to deallocate all memory associated
  70  *              with an hdf data set.  Although you can pass an HDF node
  71  *              as an argument to this function, you are likely to cause
  72  *              a segfault if you continue to access the data set.  In
  73  *              the future, we may restrict hdf_destroy so it only works
  74  *              on the top level node.
  75  * Input: hdf - pointer to an HDF data set allocated with hdf_init
  76  * Output: None
  77  * Returns: None
  78  */
  79 void hdf_destroy (HDF **hdf);
  80
  81 /*
  82  * Function: hdf_get_obj - return the HDF data set node at a named location
  83  * Description: hdf_get_obj walks the dataset given by hdf to the node
  84  *              named name, and then returns the pointer to that node
  85  * Input: hdf -> the dataset node to start from
  86  *        name -> the name to walk to
  87  * Output: None
  88  * Returns: the pointer to the named node, or NULL if it doesn't exist
  89  */
  90 HDF* hdf_get_obj (HDF *hdf, const char *name, NEOERR** err);
  91
  92 /*
  93  * Function: hdf_get_node - Similar to hdf_get_obj except all the nodes
  94  *           are created if the don't exist.
  95  * Description: hdf_get_node is similar to hdf_get_obj, except instead
  96  *              of stopping if it can't find a node in the tree, it will
  97  *              create all of the nodes necessary to hand you back the
  98  *              node you ask for.  Nodes are created with no value.
  99  * Input: hdf -> the dataset node to start from
 100  *        name -> the name to walk to
 101  * Output: ret -> the dataset node you asked for
 102  * Returns: NERR_NOMEM - unable to allocate new nodes
 103  */
 104 NEOERR * hdf_get_node (HDF *hdf, const char *name, HDF **ret);
 105
 106 /*
 107  * Function: hdf_get_child - return the first child of the named node
 108  * Description: hdf_get_child will walk the dataset starting at hdf to
 109  *              name, and return the first child of that node
 110  * Input: hdf -> the dataset node to start from
 111  *        name -> the name to walk to
 112  * Output: None
 113  * Returns: The first child of the named dataset node or NULL if the
 114  *          node is not found (or it has no children)
 115  */
 116 HDF* hdf_get_child (HDF *hdf, const char *name, NEOERR** err);
 117
 118 /*
 119  * Function: hdf_set_visited - Mark a node visited or not
 120  */
 121 void hdf_set_visited (HDF *hdf, int visited);
 122
 123 /*
 124  * Function: hdf_is_visited - Return a node visited or not
 125  */
 126 int hdf_is_visited (HDF *hdf);
 127
 128 /*
 129  * Function: hdf_obj_child - Return the first child of a dataset node
 130  * Description: hdf_obj_child and the other hdf_obj_ functions are
 131  *              accessors to the HDF dataset.  Although we do not
 132  *              currently "hide" the HDF struct implementation, we
 133  *              recommend you use the accessor functions instead of
 134  *              accessing the values directly.
 135  * Input: hdf -> the hdf dataset node
 136  * Output: None
 137  * Returns: The pointer to the first child, or NULL if there is none
 138  */
 139 HDF* hdf_obj_child (HDF *hdf, NEOERR**);
 140
 141 /*
 142  * Function: hdf_obj_next - Return the next node of a dataset level
 143  * Description: hdf_obj_next is an accessor function for the HDF struct
 144  * Input: hdf -> the hdf dataset node
 145  * Output: None
 146  * Returns: The pointer to the next node, or NULL if there is none
 147  */
 148 HDF* hdf_obj_next (HDF *hdf);
 149
 150 /*
 151  * Function: hdf_obj_name - Return the name of a node
 152  * Description: hdf_obj_name is an accessor function for a datset node
 153  *              which returns the name of the node.  This is just the
 154  *              local name, and not the full path.
 155  * Input: hdf -> the hdf dataset node
 156  * Output: None
 157  * Returns: The name of the node.  If this is the top node, the name is
 158  * NULL.
 159  */
 160 char* hdf_obj_name (HDF *hdf);
 161
 162 /*
 163  * Function: hdf_obj_value - Return the value of a node
 164  * Description: hdf_obj_value is an accessor function for a dataset node
 165  *              which returns the value of the node, or NULL if the node
 166  *              has no value.  This is not a copy of the value, so the
 167  *              node retains ownership of the value
 168  * Input: hdf -> the hdf dataset node
 169  * Output: None
 170  * Returns: The value of the node, or NULL if it has no value
 171  */
 172 char* hdf_obj_value (HDF *hdf, NEOERR**);
 173
 174 /*
 175  * Function: hdf_set_value - Set the value of a named node
 176  * Description: hdf_set_value will set the value of a named node.  All
 177  *              of the interstitial nodes which don't exist will be
 178  *              created with a value of NULL.  Existing nodes are not
 179  *              modified.  New nodes are created at the end of the list.
 180  *              If a list of nodes exceeds FORCE_HASH_AT, then a HASH
 181  *              will be created at that level and all of the nodes will
 182  *              be added to the hash for faster lookup times.
 183  *              The copy of the value will be made which the dataset
 184  *              will own.
 185  * Input: hdf -> the pointer to the hdf dataset
 186  *        name -> the named node to walk to
 187  *        value -> the value to set the node to
 188  * Output: None
 189  * Returns: NERR_NOMEM
 190  */
 191 NEOERR* hdf_set_value (HDF *hdf, const char *name, const char *value);
 192
 193 /*
 194  * Function: hdf_read_file - read an HDF data file
 195  * Description:
 196  * Input:
 197  * Output:
 198  * Returns: NERR_IO, NERR_NOMEM, NERR_PARSE
 199  */
 200 NEOERR* hdf_read_file (HDF *hdf, const char *path);
 201
 202 /*
 203  * Function: hdf_write_file - write an HDF data file
 204  * Description:
 205  * Input:
 206  * Output:
 207  * Returns: NERR_IO
 208  */
 209 NEOERR* hdf_write_file (HDF *hdf, const char *path);
 210
 211 /*
 212  * Function: hdf_read_string - read an HDF string
 213  * Description:
 214  * Input:
 215  * Output:
 216  * Returns: NERR_NOMEM, NERR_PARSE
 217  */
 218 NEOERR* hdf_read_string (HDF *hdf, const char *s);
 219
 220 /*
 221  * Function: hdf_write_string - serialize an HDF dataset to a string
 222  * Description:
 223  * Input:
 224  * Output:
 225  * Returns: NERR_NOMEM
 226  */
 227 NEOERR* hdf_write_string (HDF *hdf, char **s);
 228
 229 /*
 230  * Function: hdf_dump_format - dump an HDF dataset to FILE *fp
 231  * Description:
 232  * Input:
 233  * Output:
 234  * Returns:
 235  */
 236 NEOERR* hdf_dump_format (HDF *hdf, int lvl, FILE *fp);
 237
 238 /*
 239  * Function: hdf_dump_str - dump an HDF dataset to NEOSTRING
 240  * Description:
 241  * Input:
 242  * Output:
 243  * Returns:
 244  */
 245 NEOERR* hdf_dump_str(HDF *hdf, const char *prefix, int compact, NEOSTRING *str);
 246
 247 /*
 248  * Function: hdf_remove_tree - delete a subtree of an HDF dataset
 249  * Description:
 250  * Input:
 251  * Output:
 252  * Returns:
 253  */
 254 NEOERR* hdf_remove_tree (HDF *hdf, const char *name);
 255
 256 /*
 257  * Function: hdf_copy - copy part of an HDF dataset to another
 258  * Description: hdf_copy is a deep copy of an HDF tree pointed to by
 259  *              src to the named node of dest.  dest and src need not be
 260  *              part of the same data set
 261  * Input: dest_hdf -> the destination dataset
 262  *        name -> the name of the destination node
 263  *        src -> the hdf dataset to copy to the destination
 264  * Output: None
 265  * Returns: NERR_NOMEM, NERR_NOT_FOUND
 266  */
 267 NEOERR* hdf_copy (HDF *dest_hdf, const char *name, HDF *src);
 268
 269 /*
 270  * Function: hdf_search_path - Find a file given a search path in HDF
 271  * Description: hdf_search_path is a convenience/utility function that
 272  *              searches for relative filenames in a search path.  The
 273  *              search path is the list given by the children of
 274  *              hdf.loadpaths.
 275  * Input: hdf -> the hdf dataset to use
 276  *        path -> the relative path
 277  *        full -> a pointer to a buffer
 278  *        full_len -> size of full buffer
 279  * Output: full -> the full path of the file
 280  * Returns: NERR_NOT_FOUND if the file wasn't found in the search path
 281  */
 282 NEOERR* hdf_search_path (HDF *hdf, const char *path, char *full, int full_len);
 283
 284 __END_DECLS
 285
 286 #endif /* incl_HPHP_NEO_HDF_H_ */