src/axl/axl_node.h

   1 /**
   2  *  LibAxl:  Another XML library
   3  *  Copyright (C) 2006 Advanced Software Production Line, S.L.
   4  *
   5  *  This program is free software; you can redistribute it and/or
   6  *  modify it under the terms of the GNU Lesser General Public License
   7  *  as published by the Free Software Foundation; either version 2.1 of
   8  *  the License, or (at your option) any later version.
   9  *
  10  *  This program is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  *  GNU Lesser General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU Lesser General Public
  16  *  License along with this program; if not, write to the Free
  17  *  Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  18  *  02111-1307 USA
  19  *
  20  *  You may find a copy of the license under this software is released
  21  *  at COPYING file. This is LGPL software: you are welcome to
  22  *  develop proprietary applications using this library without any
  23  *  royalty or fee but returning back any change, improvement or
  24  *  addition in the form of source code, project image, documentation
  25  *  patches, etc.
  26  *
  27  *  For commercial support on build XML enabled solutions contact us:
  28  *
  29  *      Postal address:
  30  *         Advanced Software Production Line, S.L.
  31  *         C/ Dr. Michavila Nº 14
  32  *         Coslada 28820 Madrid
  33  *         Spain
  34  *
  35  *      Email address:
  36  *         info@aspl.es - http://fact.aspl.es
  37  */
  38 #ifndef __AXL_NODE_H__
  39 #define __AXL_NODE_H__
  40
  41 #include <axl_decl.h>
  42
  43 BEGIN_C_DECLS
  44
  45 /**
  46  * \addtogroup axl_node_module
  47  * @{
  48  */
  49
  50 axlNode * axl_node_create                   (const char * name);
  51
  52 axlNode * axl_node_create_ref               (char * name);
  53
  54 axlNode * axl_node_parse_strings            (axlError ** error, ...);
  55
  56 axlNode * axl_node_parse                    (axlError ** error, const char * content, ...);
  57
  58 void      axl_node_set_name                 (axlNode * node,
  59                                              const char * name);
  60
  61 void      axl_node_set_name_ref             (axlNode * node,
  62                                              char * name);
  63
  64 void      axl_node_set_name_from_factory    (axlNode * node,
  65                                              char * name);
  66
  67 axlNode * axl_node_copy                     (axlNode * node,
  68                                              bool      copy_attributes,
  69                                              bool      copy_childs);
  70
  71 axlDoc  * axl_node_get_doc                  (axlNode * node);
  72
  73 void      axl_node_set_doc                  (axlNode * node,
  74                                              axlDoc  * doc);
  75
  76 void      axl_node_set_attribute            (axlNode    * node,
  77                                              const char * attribute,
  78                                              const char * value);
  79
  80 void      axl_node_set_attribute_ref        (axlNode * node,
  81                                              char    * attribute,
  82                                              char    * value);
  83
  84 void      axl_node_set_attribute_from_factory  (axlFactory * factory,
  85                                                 axlNode    * node,
  86                                                 char       * attribute,
  87                                                 char       * value);
  88
  89 /**
  90  * @brief Macro definition which works as an alias for \ref
  91  * axl_node_get_attribute_value.
  92  *
  93  * @param node The node being checked to have an attribute value.
  94  * @param attr The attribute that is being check to be present in the node provided.
  95  *
  96  * @return \ref true if the node has the provided attribute, otherwise
  97  * \ref false is returned.
  98  */
  99 #define HAS_ATTR(node,attr) axl_node_has_attribute(node,attr)
 100
 101 bool      axl_node_has_attribute            (axlNode    * node,
 102                                              const char * attribute);
 103
 104 void      axl_node_remove_attribute         (axlNode    * node,
 105                                              const char * attribute);
 106
 107 int       axl_node_num_attributes           (axlNode    * node);
 108
 109
 110 /**
 111  * @brief Macro definition, which works as an alias for \ref
 112  * axl_node_get_attribute_value.
 113  *
 114  * @param node The node that is being required to return the content
 115  * of a particular node.
 116  *
 117  * @param attr The attribute that is requested.
 118  *
 119  * @return The value assocaited to the attribute value or null if it
 120  * fails. See \ref axl_node_get_attribute_value.
 121  */
 122 #define ATTR_VALUE(node,attr) axl_node_get_attribute_value(node, attr)
 123
 124 const char    * axl_node_get_attribute_value      (axlNode    * node,
 125                                                    const char * attribute);
 126
 127 char    * axl_node_get_attribute_value_copy (axlNode    * node,
 128                                              const char * attribute);
 129
 130 /**
 131  * @brief Simple alias definition to \ref axl_node_get_attribute_value_trans function.
 132  *
 133  * @param node The node which contains the attribute requested.
 134  *
 135  * @param attr The attribute key that is being requested.
 136  *
 137  * @return A newly allocated string containing the attribute value,
 138  * with known entity references translated.
 139  */
 140 #define ATTR_VALUE_TRANS(node,attr) axl_node_get_attribute_value_trans(node,attr)
 141
 142 char    * axl_node_get_attribute_value_trans (axlNode * node,
 143                                               const char * attribute);
 144
 145 /**
 146  * @brief Allows to get the value associated to the attributed
 147  * provided, inside the node selected, removing trailing and ending
 148  * white spaces (in the W3C sence: \\n, \\t, \\r, ' ').
 149  *
 150  * This is a macro alias to \ref axl_node_get_attribute_value_trimmed.
 151  *
 152  * @param node The node that is requested to return the associated
 153  * value to the attributed.
 154  *
 155  * @param attr The attribute that is being requested.
 156  *
 157  * @return A reference to the attribute value or NULL if it fails.
 158  */
 159 #define ATTR_VALUE_TRIMMED(node,attr) axl_node_get_attribute_value_trimmed(node,attr)
 160
 161 const char    * axl_node_get_attribute_value_trimmed (axlNode    * node,
 162                                                       const char * attribute);
 163
 164 /**
 165  * @brief Convenience macro wrapping \ref
 166  * axl_node_has_attribute_value.
 167  */
 168 #define HAS_ATTR_VALUE(node, attr,value) (axl_node_has_attribute_value (node, attr, value))
 169
 170 bool      axl_node_has_attribute_value       (axlNode    * node,
 171                                               const char * attribute,
 172                                               const char * value);
 173
 174 bool      axl_node_has_attributes (axlNode * node);
 175
 176 /**
 177  * @}
 178  */
 179
 180 /**
 181  * \addtogroup axl_node_attribute_cursor
 182  * @{
 183  */
 184
 185 /* XML node attribute iteration API provided to traverse all
 186  * attributes without knowing them. */
 187 axlAttrCursor * axl_node_attr_cursor_new       (axlNode * node);
 188
 189 void            axl_node_attr_cursor_first     (axlAttrCursor * cursor);
 190
 191 void            axl_node_attr_cursor_next      (axlAttrCursor * cursor);
 192
 193 bool            axl_node_attr_cursor_has_next  (axlAttrCursor * cursor);
 194
 195 bool            axl_node_attr_cursor_has_item  (axlAttrCursor * cursor);
 196
 197 const char *    axl_node_attr_cursor_get_key   (axlAttrCursor * cursor);
 198
 199 const char *    axl_node_attr_cursor_get_value (axlAttrCursor * cursor);
 200
 201 void            axl_node_attr_cursor_free      (axlAttrCursor * cursor);
 202
 203 void            axl_node_attr_foreach          (axlNode       * node,
 204                                                 axlNodeAttrForeachFunc func,
 205                                                 axlPointer      data,
 206                                                 axlPointer      data2);
 207
 208
 209 /**
 210  * @}
 211  */
 212
 213 /**
 214  * \addtogroup axl_node_annotate
 215  * @{
 216  */
 217
 218 void      axl_node_annotate_data                 (axlNode     * node,
 219                                                  const char  * key,
 220                                                  axlPointer    data);
 221
 222 void      axl_node_annotate_data_full            (axlNode       * node,
 223                                                  const char    * key,
 224                                                  axlDestroyFunc  key_destroy,
 225                                                  axlPointer      data,
 226                                                  axlDestroyFunc  data_destroy);
 227
 228 axlPointer axl_node_annotate_get                 (axlNode       * node,
 229                                                  const char    * key,
 230                                                  bool            lookup_in_parent);
 231
 232 void       axl_node_annotate_int                 (axlNode * node,
 233                                                  const char    * key,
 234                                                  int             int_value);
 235
 236 void       axl_node_annotate_string              (axlNode * node,
 237                                                  const char    * key,
 238                                                  const char    * string_value);
 239
 240 void       axl_node_annotate_double              (axlNode    * node,
 241                                                  const char * key,
 242                                                  double       double_value);
 243
 244 int        axl_node_annotate_get_int             (axlNode     * node,
 245                                                  const char  * key,
 246                                                  bool          lookup_in_parent);
 247
 248 char *     axl_node_annotate_get_string          (axlNode       * node,
 249                                                  const char    * key,
 250                                                  bool            lookup_in_parent);
 251
 252 double     axl_node_annotate_get_double          (axlNode       * node,
 253                                                  const char    * key,
 254                                                  bool            lookup_in_parent);
 255
 256 /**
 257  * @}
 258  */
 259
 260
 261 /**
 262  * \addtogroup axl_node_module
 263  * @{
 264  */
 265
 266 /**
 267  * @brief Allows to easily check that the given xml node (\ref
 268  * axlNode) have the provided name.
 269  *
 270  * This macro is provided as a convenience to check that a particular
 271  * node have a particular name. Check the documentation that this
 272  * macro is wrapping to get examples: \ref axl_node_get_name.
 273  *
 274  * <i><b>NOTE:</b> This function isn't XML Namespace aware. You must use \ref axl_ns_node_cmp instead. See \ref axl_ns_doc_validate. </i>
 275  *
 276  * @param node The \ref axlNode where the name will be compared with
 277  * the provided value.
 278  *
 279  * @param name The name to compare.
 280  *
 281  * @return \ref true if names are equal or \ref false if not.
 282  */
 283 #define NODE_CMP_NAME(node,name) (axl_cmp ((node != NULL) ? axl_node_get_name(node) : "><", (name != NULL) ? name : "<>"))
 284
 285 const char * axl_node_get_name           (axlNode * node);
 286
 287 axlNode * axl_node_get_parent         (axlNode * node);
 288
 289 axlNode * axl_node_get_next           (axlNode * node);
 290
 291 axlNode * axl_node_get_next_called    (axlNode * node,
 292                                        char    * name);
 293
 294 axlNode * axl_node_get_previous         (axlNode * node);
 295
 296 axlNode * axl_node_get_previous_called  (axlNode * node,
 297                                          char    * name);
 298
 299 axlNode * axl_node_get_first_child    (axlNode * node);
 300
 301 axlNode * axl_node_get_last_child     (axlNode * node);
 302
 303 void      axl_node_set_child          (axlNode * parent,
 304                                        axlNode * child);
 305
 306 void      axl_node_set_child_after    (axlNode * reference,
 307                                        axlNode * child);
 308
 309 void      axl_node_replace            (axlNode * node,
 310                                        axlNode * new_node,
 311                                        bool      dealloc);
 312
 313 void      axl_node_remove             (axlNode * node,
 314                                        bool      dealloc);
 315
 316 void      axl_node_deattach           (axlNode * node);
 317
 318
 319 void      axl_node_set_is_empty       (axlNode  * node,
 320                                        bool       empty);
 321
 322 bool      axl_node_is_empty           (axlNode * node);
 323
 324 const char    * axl_node_get_content  (axlNode * node,
 325                                        int  * content_size);
 326
 327 char    * axl_node_get_content_copy   (axlNode * node,
 328                                        int  * content_size);
 329
 330 char    * axl_node_get_content_trans  (axlNode * node,
 331                                        int * content_size);
 332
 333 char    * axl_node_get_content_trim   (axlNode * node,
 334                                        int * content_size);
 335
 336 void      axl_node_set_content        (axlNode    * node,
 337                                        const char * content,
 338                                        int content_size);
 339
 340 void      axl_node_set_content_ref    (axlNode * node,
 341                                        char * content,
 342                                        int content_size);
 343
 344 void      axl_node_set_content_from_factory (axlFactory * factory,
 345                                              axlNode    * node,
 346                                              char       * content,
 347                                              int          content_size);
 348
 349 void      axl_node_set_cdata_content  (axlNode * node,
 350                                        char * content,
 351                                        int content_size);
 352
 353 void      axl_node_set_cdata_content_from_factory (axlFactory * factory,
 354                                                    axlNode    * node,
 355                                                    char       * content,
 356                                                    int          content_size);
 357
 358 void      axl_node_set_comment        (axlNode * node,
 359                                        char * comment,
 360                                        int    comment_size);
 361
 362 void      axl_node_set_have_childs    (axlNode * node, bool     childs);
 363
 364 bool      axl_node_have_childs        (axlNode * node);
 365
 366 axlNode * axl_node_get_child_called   (axlNode * parent, char * name);
 367
 368 axlNode * axl_node_find_called        (axlNode * parent, char * name);
 369
 370 axlNode * axl_node_get_child_nth      (axlNode * parent, int position);
 371
 372 int       axl_node_get_child_num      (axlNode * parent);
 373
 374 axlList * axl_node_get_childs         (axlNode * node);
 375
 376 bool      axl_node_are_equal          (axlNode * node, axlNode * node2);
 377
 378 void      axl_node_add_pi_target            (axlNode * node,
 379                                              char * target,
 380                                              char * content);
 381
 382 bool      axl_node_has_pi_target            (axlNode * node,
 383                                              char * pi_target);
 384
 385 char    * axl_node_get_pi_target_content    (axlNode * node,
 386                                              char * pi_target);
 387
 388 axlList * axl_node_get_pi_target_list       (axlNode * node);
 389
 390 void      axl_node_transfer_childs          (axlNode * old_parent,
 391                                              axlNode * new_parent);
 392
 393 bool      axl_node_dump                    (axlNode  * node,
 394                                             char    ** content,
 395                                             int      * size);
 396
 397 bool      axl_node_dump_pretty             (axlNode  * node,
 398                                             char    ** content,
 399                                             int      * size,
 400                                             int        tabular);
 401
 402 bool      axl_node_dump_to_file            (axlNode  * node,
 403                                             char     * file_path);
 404
 405 bool      axl_node_dump_pretty_to_file     (axlNode  * node,
 406                                             char     * file_path,
 407                                             int        tabular);
 408
 409 int       axl_node_get_flat_size            (axlNode * node,
 410                                              bool      pretty_print,
 411                                              int       level,
 412                                              int       tabular);
 413
 414 int       axl_node_dump_at                  (axlNode * node,
 415                                              char    * content,
 416                                              int       desp,
 417                                              bool      pretty_print,
 418                                              int       level,
 419                                              int       tabular);
 420
 421 bool      axl_node_has_invalid_chars        (const char * content,
 422                                              int    content_size,
 423                                              int  * added_size);
 424
 425 char    * axl_node_content_copy_and_escape (const char * content,
 426                                             int          content_size,
 427                                             int          additional_size);
 428
 429 void      axl_node_free            (axlNode * node);
 430
 431 void      axl_node_free_full       (axlNode * node, bool also_childs);
 432
 433 /* @} */
 434
 435 /* item interface */
 436
 437 axlItem     * axl_item_new             (AxlItemType type,
 438                                         axlPointer  data);
 439
 440 axlItem     * axl_item_new_ref         (AxlItemType type,
 441                                         axlPointer  data);
 442
 443 axlDoc      * axl_item_get_doc         (axlItem * item);
 444
 445 void          axl_item_set_doc         (axlItem * item, axlDoc * doc);
 446
 447 axlNode     * axl_item_get_parent      (axlItem * item);
 448
 449 axlItem     * axl_item_get_next        (axlItem * item);
 450
 451 axlItem     * axl_item_node_next       (axlNode * node);
 452
 453 axlItem     * axl_item_get_previous    (axlItem * item);
 454
 455 axlItem     * axl_item_node_previous   (axlNode * node);
 456
 457 axlItem     * axl_item_node_holder     (axlNode * node);
 458
 459 axlItem     * axl_item_get_first_child (axlNode * node);
 460
 461 axlItem     * axl_item_get_last_child  (axlNode * node);
 462
 463 AxlItemType   axl_item_get_type        (axlItem * item);
 464
 465 axlPointer    axl_item_get_data        (axlItem * item);
 466
 467 char        * axl_item_get_content     (axlItem * item,
 468                                         int * size);
 469
 470 void          axl_item_set_child       (axlNode * parent,
 471                                         AxlItemType type,
 472                                         axlPointer data);
 473
 474 void          axl_item_set_child_ref   (axlNode * parent,
 475                                         axlItem * item);
 476
 477 void          axl_item_set_after       (axlItem * item,
 478                                         AxlItemType type,
 479                                         axlPointer data);
 480
 481 axlItem     * axl_item_copy            (axlItem * item,
 482                                         axlNode * set_parent);
 483
 484 void          axl_item_remove          (axlItem * item,
 485                                         bool      dealloc);
 486
 487 void          axl_item_replace         (axlItem * item,
 488                                         axlItem * new_item,
 489                                         bool      dealloc);
 490
 491 void          axl_item_transfer_childs_after (axlNode * old_parent,
 492                                               axlItem * item_ref);
 493
 494 bool          axl_item_are_equal      (axlItem * item,
 495                                        axlItem * item2,
 496                                        bool      trimmed);
 497
 498 void          axl_item_free           (axlItem * item,
 499                                        bool      dealloc);
 500
 501 axlFactory     * axl_item_factory_create ();
 502
 503 axlItem        * axl_item_factory_get (axlFactory * factory);
 504
 505 axlFactory     * axl_node_factory_create ();
 506
 507 axlNode        * axl_node_factory_get (axlFactory * factory);
 508
 509 axlFactory     * axl_item_content_factory_create ();
 510
 511 axlFactory     * axl_item_attr_factory_create ();
 512
 513 END_C_DECLS
 514
 515 #endif
 516
 517