src/TortoiseMerge/libsvn_diff/svn_xml.h

   1 /**\r
   2  * @copyright\r
   3  * ====================================================================\r
   4  * Copyright (c) 2000-2006, 2008 CollabNet.  All rights reserved.\r
   5  *\r
   6  * This software is licensed as described in the file COPYING, which\r
   7  * you should have received as part of this distribution.  The terms\r
   8  * are also available at http://subversion.tigris.org/license-1.html.\r
   9  * If newer versions of this license are posted there, you may use a\r
  10  * newer version instead, at your option.\r
  11  *\r
  12  * This software consists of voluntary contributions made by many\r
  13  * individuals.  For exact contribution history, see the revision\r
  14  * history and logs, available at http://subversion.tigris.org/.\r
  15  * ====================================================================\r
  16  * @endcopyright\r
  17  *\r
  18  * @file svn_xml.h\r
  19  * @brief XML code shared by various Subversion libraries.\r
  20  */\r
  21 \r
  22 #ifndef SVN_XML_H\r
  23 #define SVN_XML_H\r
  24 \r
  25 #include <apr.h>\r
  26 #include <apr_pools.h>\r
  27 #include <apr_hash.h>\r
  28 \r
  29 #include "svn_types.h"\r
  30 #include "svn_string.h"\r
  31 \r
  32 #ifdef __cplusplus\r
  33 extern "C" {\r
  34 #endif /* __cplusplus */\r
  35 \r
  36 /** The namespace all Subversion XML uses. */\r
  37 #define SVN_XML_NAMESPACE "svn:"\r
  38 \r
  39 /** Used as style argument to svn_xml_make_open_tag() and friends. */\r
  40 enum svn_xml_open_tag_style {\r
  41   /** <tag ...> */\r
  42   svn_xml_normal = 1,\r
  43 \r
  44   /** <tag ...>, no cosmetic newline */\r
  45   svn_xml_protect_pcdata,\r
  46 \r
  47   /** <tag .../>  */\r
  48   svn_xml_self_closing\r
  49 };\r
  50 \r
  51 \f\r
  52 \r
  53 /** Determine if a string of character @a data of length @a len is a\r
  54  * safe bet for use with the svn_xml_escape_* functions found in this\r
  55  * header.\r
  56  *\r
  57  * Return @c TRUE if it is, @c FALSE otherwise.\r
  58  *\r
  59  * Essentially, this function exists to determine whether or not\r
  60  * simply running a string of bytes through the Subversion XML escape\r
  61  * routines will produce legitimate XML.  It should only be necessary\r
  62  * for data which might contain bytes that cannot be safely encoded\r
  63  * into XML (certain control characters, for example).\r
  64  */\r
  65 svn_boolean_t\r
  66 svn_xml_is_xml_safe(const char *data,\r
  67                     apr_size_t len);\r
  68 \r
  69 /** Create or append in @a *outstr an xml-escaped version of @a string,\r
  70  * suitable for output as character data.\r
  71  *\r
  72  * If @a *outstr is @c NULL, set @a *outstr to a new stringbuf allocated\r
  73  * in @a pool, else append to the existing stringbuf there.\r
  74  */\r
  75 void\r
  76 svn_xml_escape_cdata_stringbuf(svn_stringbuf_t **outstr,\r
  77                                const svn_stringbuf_t *string,\r
  78                                apr_pool_t *pool);\r
  79 \r
  80 /** Same as svn_xml_escape_cdata_stringbuf(), but @a string is an\r
  81  * @c svn_string_t.\r
  82  */\r
  83 void\r
  84 svn_xml_escape_cdata_string(svn_stringbuf_t **outstr,\r
  85                             const svn_string_t *string,\r
  86                             apr_pool_t *pool);\r
  87 \r
  88 /** Same as svn_xml_escape_cdata_stringbuf(), but @a string is a\r
  89  * NULL-terminated C string.\r
  90  */\r
  91 void\r
  92 svn_xml_escape_cdata_cstring(svn_stringbuf_t **outstr,\r
  93                              const char *string,\r
  94                              apr_pool_t *pool);\r
  95 \r
  96 \r
  97 /** Create or append in @a *outstr an xml-escaped version of @a string,\r
  98  * suitable for output as an attribute value.\r
  99  *\r
 100  * If @a *outstr is @c NULL, set @a *outstr to a new stringbuf allocated\r
 101  * in @a pool, else append to the existing stringbuf there.\r
 102  */\r
 103 void\r
 104 svn_xml_escape_attr_stringbuf(svn_stringbuf_t **outstr,\r
 105                               const svn_stringbuf_t *string,\r
 106                               apr_pool_t *pool);\r
 107 \r
 108 /** Same as svn_xml_escape_attr_stringbuf(), but @a string is an\r
 109  * @c svn_string_t.\r
 110  */\r
 111 void\r
 112 svn_xml_escape_attr_string(svn_stringbuf_t **outstr,\r
 113                            const svn_string_t *string,\r
 114                            apr_pool_t *pool);\r
 115 \r
 116 /** Same as svn_xml_escape_attr_stringbuf(), but @a string is a\r
 117  * NULL-terminated C string.\r
 118  */\r
 119 void\r
 120 svn_xml_escape_attr_cstring(svn_stringbuf_t **outstr,\r
 121                             const char *string,\r
 122                             apr_pool_t *pool);\r
 123 \r
 124 /**\r
 125  * Return UTF-8 string @a string if it contains no characters that are\r
 126  * unrepresentable in XML.  Else, return a copy of @a string,\r
 127  * allocated in @a pool, with each unrepresentable character replaced\r
 128  * by "?\uuu", where "uuu" is the three-digit unsigned decimal value\r
 129  * of that character.\r
 130  *\r
 131  * Neither the input nor the output need be valid XML; however, the\r
 132  * output can always be safely XML-escaped.\r
 133  *\r
 134  * @note The current implementation treats all Unicode characters as\r
 135  * representable, except for most ASCII control characters (the\r
 136  * exceptions being CR, LF, and TAB, which are valid in XML).  There\r
 137  * may be other UTF-8 characters that are invalid in XML; see\r
 138  * http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=90591\r
 139  * and its thread for details.\r
 140  *\r
 141  * @since New in 1.2.\r
 142  */\r
 143 const char *\r
 144 svn_xml_fuzzy_escape(const char *string,\r
 145                      apr_pool_t *pool);\r
 146 \r
 147 \r
 148 /*---------------------------------------------------------------*/\r
 149 \f\r
 150 /* Generalized Subversion XML Parsing */\r
 151 \r
 152 /** A generalized Subversion XML parser object */\r
 153 typedef struct svn_xml_parser_t svn_xml_parser_t;\r
 154 \r
 155 typedef void (*svn_xml_start_elem)(void *baton,\r
 156                                    const char *name,\r
 157                                    const char **atts);\r
 158 \r
 159 typedef void (*svn_xml_end_elem)(void *baton, const char *name);\r
 160 \r
 161 /* data is not NULL-terminated. */\r
 162 typedef void (*svn_xml_char_data)(void *baton,\r
 163                                   const char *data,\r
 164                                   apr_size_t len);\r
 165 \r
 166 \r
 167 /** Create a general Subversion XML parser */\r
 168 svn_xml_parser_t *\r
 169 svn_xml_make_parser(void *baton,\r
 170                     svn_xml_start_elem start_handler,\r
 171                     svn_xml_end_elem end_handler,\r
 172                     svn_xml_char_data data_handler,\r
 173                     apr_pool_t *pool);\r
 174 \r
 175 \r
 176 /** Free a general Subversion XML parser */\r
 177 void\r
 178 svn_xml_free_parser(svn_xml_parser_t *svn_parser);\r
 179 \r
 180 \r
 181 /** Push @a len bytes of xml data in @a buf at @a svn_parser.\r
 182  *\r
 183  * If this is the final push, @a is_final must be set.\r
 184  *\r
 185  * An error will be returned if there was a syntax problem in the XML,\r
 186  * or if any of the callbacks set an error using\r
 187  * svn_xml_signal_bailout().\r
 188  *\r
 189  * If an error is returned, the @c svn_xml_parser_t will have been freed\r
 190  * automatically, so the caller should not call svn_xml_free_parser().\r
 191  */\r
 192 svn_error_t *\r
 193 svn_xml_parse(svn_xml_parser_t *svn_parser,\r
 194               const char *buf,\r
 195               apr_size_t len,\r
 196               svn_boolean_t is_final);\r
 197 \r
 198 \r
 199 \r
 200 /** The way to officially bail out of xml parsing.\r
 201  *\r
 202  * Store @a error in @a svn_parser and set all expat callbacks to @c NULL.\r
 203  */\r
 204 void\r
 205 svn_xml_signal_bailout(svn_error_t *error,\r
 206                        svn_xml_parser_t *svn_parser);\r
 207 \r
 208 \r
 209 \r
 210 \r
 211 \f\r
 212 /*** Helpers for dealing with the data Expat gives us. ***/\r
 213 \r
 214 /** Return the value associated with @a name in expat attribute array @a atts,\r
 215  * else return @c NULL.\r
 216  *\r
 217  * (There could never be a @c NULL attribute value in the XML,\r
 218  * although the empty string is possible.)\r
 219  *\r
 220  * @a atts is an array of c-strings: even-numbered indexes are names,\r
 221  * odd-numbers hold values.  If all is right, it should end on an\r
 222  * even-numbered index pointing to @c NULL.\r
 223  */\r
 224 const char *\r
 225 svn_xml_get_attr_value(const char *name,\r
 226                        const char **atts);\r
 227 \r
 228 \r
 229 \f\r
 230 /* Converting between Expat attribute lists and APR hash tables. */\r
 231 \r
 232 \r
 233 /** Create an attribute hash from @c va_list @a ap.\r
 234  *\r
 235  * The contents of @a ap are alternating <tt>char *</tt> keys and\r
 236  * <tt>char *</tt> vals, terminated by a final @c NULL falling on an\r
 237  * even index (zero-based).\r
 238  */\r
 239 apr_hash_t *\r
 240 svn_xml_ap_to_hash(va_list ap,\r
 241                    apr_pool_t *pool);\r
 242 \r
 243 /** Create a hash that corresponds to Expat xml attribute list @a atts.\r
 244  *\r
 245  * The hash's keys and values are <tt>char *</tt>'s.\r
 246  *\r
 247  * @a atts may be NULL, in which case you just get an empty hash back\r
 248  * (this makes life more convenient for some callers).\r
 249  */\r
 250 apr_hash_t *\r
 251 svn_xml_make_att_hash(const char **atts,\r
 252                       apr_pool_t *pool);\r
 253 \r
 254 \r
 255 /** Like svn_xml_make_att_hash(), but takes a hash and preserves any\r
 256  * key/value pairs already in it.\r
 257  */\r
 258 void\r
 259 svn_xml_hash_atts_preserving(const char **atts,\r
 260                              apr_hash_t *ht,\r
 261                              apr_pool_t *pool);\r
 262 \r
 263 /** Like svn_xml_make_att_hash(), but takes a hash and overwrites\r
 264  * key/value pairs already in it that also appear in @a atts.\r
 265  */\r
 266 void\r
 267 svn_xml_hash_atts_overlaying(const char **atts,\r
 268                              apr_hash_t *ht,\r
 269                              apr_pool_t *pool);\r
 270 \r
 271 \r
 272 \f\r
 273 /* Printing XML */\r
 274 \r
 275 /** Create an XML header and return it in @a *str.\r
 276  *\r
 277  * Fully-formed XML documents should start out with a header,\r
 278  * something like\r
 279  *         \<?xml version="1.0" encoding="utf-8"?\>\r
 280  *\r
 281  * This function returns such a header.  @a *str must either be @c NULL, in\r
 282  * which case a new string is created, or it must point to an existing\r
 283  * string to be appended to.\r
 284  */\r
 285 void\r
 286 svn_xml_make_header(svn_stringbuf_t **str,\r
 287                     apr_pool_t *pool);\r
 288 \r
 289 \r
 290 /** Store a new xml tag @a tagname in @a *str.\r
 291  *\r
 292  * If @a *str is @c NULL, set @a *str to a new stringbuf allocated\r
 293  * in @a pool, else append to the existing stringbuf there.\r
 294  *\r
 295  * Take the tag's attributes from varargs, a NULL-terminated list of\r
 296  * alternating <tt>char *</tt> key and <tt>char *</tt> val.  Do xml-escaping\r
 297  * on each val.\r
 298  *\r
 299  * @a style is one of the enumerated styles in @c svn_xml_open_tag_style.\r
 300  */\r
 301 void\r
 302 svn_xml_make_open_tag(svn_stringbuf_t **str,\r
 303                       apr_pool_t *pool,\r
 304                       enum svn_xml_open_tag_style style,\r
 305                       const char *tagname,\r
 306                       ...);\r
 307 \r
 308 \r
 309 /** Like svn_xml_make_open_tag(), but takes a @c va_list instead of being\r
 310  * variadic.\r
 311  */\r
 312 void\r
 313 svn_xml_make_open_tag_v(svn_stringbuf_t **str,\r
 314                         apr_pool_t *pool,\r
 315                         enum svn_xml_open_tag_style style,\r
 316                         const char *tagname,\r
 317                         va_list ap);\r
 318 \r
 319 \r
 320 /** Like svn_xml_make_open_tag(), but takes a hash table of attributes\r
 321  * (<tt>char *</tt> keys mapping to <tt>char *</tt> values).\r
 322  *\r
 323  * You might ask, why not just provide svn_xml_make_tag_atts()?\r
 324  *\r
 325  * The reason is that a hash table is the most natural interface to an\r
 326  * attribute list; the fact that Expat uses <tt>char **</tt> atts instead is\r
 327  * certainly a defensible implementation decision, but since we'd have\r
 328  * to have special code to support such lists throughout Subversion\r
 329  * anyway, we might as well write that code for the natural interface\r
 330  * (hashes) and then convert in the few cases where conversion is\r
 331  * needed.  Someday it might even be nice to change expat-lite to work\r
 332  * with apr hashes.\r
 333  *\r
 334  * See conversion functions svn_xml_make_att_hash() and\r
 335  * svn_xml_make_att_hash_overlaying().  Callers should use those to\r
 336  * convert Expat attr lists into hashes when necessary.\r
 337  */\r
 338 void\r
 339 svn_xml_make_open_tag_hash(svn_stringbuf_t **str,\r
 340                            apr_pool_t *pool,\r
 341                            enum svn_xml_open_tag_style style,\r
 342                            const char *tagname,\r
 343                            apr_hash_t *attributes);\r
 344 \r
 345 \r
 346 /** Store an xml close tag @a tagname in @a str.\r
 347  *\r
 348  * If @a *str is @c NULL, set @a *str to a new stringbuf allocated\r
 349  * in @a pool, else append to the existing stringbuf there.\r
 350  */\r
 351 void\r
 352 svn_xml_make_close_tag(svn_stringbuf_t **str,\r
 353                        apr_pool_t *pool,\r
 354                        const char *tagname);\r
 355 \r
 356 \r
 357 #ifdef __cplusplus\r
 358 }\r
 359 #endif /* __cplusplus */\r
 360 \r
 361 #endif /* SVN_XML_H */\r