/usr/include/ClearSilver/util/neo_hdf.h is in clearsilver-dev 0.10.5-1.6build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 | /*
* 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_ */
|