Back to index

radiance  4R0+20100331
ezxml.c
Go to the documentation of this file.
00001 #ifndef lint
00002 static const char RCSid[] = "$Id: ezxml.c,v 2.1 2009/06/17 20:41:47 greg Exp $";
00003 #endif
00004 /* ezxml.c
00005  *
00006  * Copyright 2004-2006 Aaron Voisine <aaron@voisine.org>
00007  *
00008  * Permission is hereby granted, free of charge, to any person obtaining
00009  * a copy of this software and associated documentation files (the
00010  * "Software"), to deal in the Software without restriction, including
00011  * without limitation the rights to use, copy, modify, merge, publish,
00012  * distribute, sublicense, and/or sell copies of the Software, and to
00013  * permit persons to whom the Software is furnished to do so, subject to
00014  * the following conditions:
00015  *
00016  * The above copyright notice and this permission notice shall be included
00017  * in all copies or substantial portions of the Software.
00018  *
00019  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00020  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00021  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00022  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
00023  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
00024  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
00025  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00026  */
00027 
00028 #include <stdlib.h>
00029 #include <stdio.h>
00030 #include <stdarg.h>
00031 #include <string.h>
00032 #include <ctype.h>
00033 #include <sys/types.h>
00034 #ifndef EZXML_NOMMAP
00035 #include <unistd.h>
00036 #include <sys/mman.h>
00037 #endif // EZXML_NOMMAP
00038 #include <sys/stat.h>
00039 #include "ezxml.h"
00040 
00041 #define EZXML_WS   "\t\r\n "  // whitespace
00042 #define EZXML_ERRL 128        // maximum error string length
00043 
00044 typedef struct ezxml_root *ezxml_root_t;
00045 struct ezxml_root {       // additional data for the root tag
00046     struct ezxml xml;     // is a super-struct built on top of ezxml struct
00047     ezxml_t cur;          // current xml tree insertion point
00048     char *m;              // original xml string
00049     size_t len;           // length of allocated memory for mmap, -1 for malloc
00050     char *u;              // UTF-8 conversion of string if original was UTF-16
00051     char *s;              // start of work area
00052     char *e;              // end of work area
00053     char **ent;           // general entities (ampersand sequences)
00054     char ***attr;         // default attributes
00055     char ***pi;           // processing instructions
00056     short standalone;     // non-zero if <?xml standalone="yes"?>
00057     char err[EZXML_ERRL]; // error string
00058 };
00059 
00060 char *EZXML_NIL[] = { NULL }; // empty, null terminated array of strings
00061 
00062 // returns the first child tag with the given name or NULL if not found
00063 ezxml_t ezxml_child(ezxml_t xml, const char *name)
00064 {
00065     xml = (xml) ? xml->child : NULL;
00066     while (xml && strcmp(name, xml->name)) xml = xml->sibling;
00067     return xml;
00068 }
00069 
00070 // returns the Nth tag with the same name in the same subsection or NULL if not
00071 // found
00072 ezxml_t ezxml_idx(ezxml_t xml, int idx)
00073 {
00074     for (; xml && idx; idx--) xml = xml->next;
00075     return xml;
00076 }
00077 
00078 // returns the value of the requested tag attribute or NULL if not found
00079 const char *ezxml_attr(ezxml_t xml, const char *attr)
00080 {
00081     int i = 0, j = 1;
00082     ezxml_root_t root = (ezxml_root_t)xml;
00083 
00084     if (! xml || ! xml->attr) return NULL;
00085     while (xml->attr[i] && strcmp(attr, xml->attr[i])) i += 2;
00086     if (xml->attr[i]) return xml->attr[i + 1]; // found attribute
00087 
00088     while (root->xml.parent) root = (ezxml_root_t)root->xml.parent; // root tag
00089     for (i = 0; root->attr[i] && strcmp(xml->name, root->attr[i][0]); i++);
00090     if (! root->attr[i]) return NULL; // no matching default attributes
00091     while (root->attr[i][j] && strcmp(attr, root->attr[i][j])) j += 3;
00092     return (root->attr[i][j]) ? root->attr[i][j + 1] : NULL; // found default
00093 }
00094 
00095 // same as ezxml_get but takes an already initialized va_list
00096 ezxml_t ezxml_vget(ezxml_t xml, va_list ap)
00097 {
00098     char *name = va_arg(ap, char *);
00099     int idx = -1;
00100 
00101     if (name && *name) {
00102         idx = va_arg(ap, int);    
00103         xml = ezxml_child(xml, name);
00104     }
00105     return (idx < 0) ? xml : ezxml_vget(ezxml_idx(xml, idx), ap);
00106 }
00107 
00108 // Traverses the xml tree to retrieve a specific subtag. Takes a variable
00109 // length list of tag names and indexes. The argument list must be terminated
00110 // by either an index of -1 or an empty string tag name. Example: 
00111 // title = ezxml_get(library, "shelf", 0, "book", 2, "title", -1);
00112 // This retrieves the title of the 3rd book on the 1st shelf of library.
00113 // Returns NULL if not found.
00114 ezxml_t ezxml_get(ezxml_t xml, ...)
00115 {
00116     va_list ap;
00117     ezxml_t r;
00118 
00119     va_start(ap, xml);
00120     r = ezxml_vget(xml, ap);
00121     va_end(ap);
00122     return r;
00123 }
00124 
00125 // returns a null terminated array of processing instructions for the given
00126 // target
00127 const char **ezxml_pi(ezxml_t xml, const char *target)
00128 {
00129     ezxml_root_t root = (ezxml_root_t)xml;
00130     int i = 0;
00131 
00132     if (! root) return (const char **)EZXML_NIL;
00133     while (root->xml.parent) root = (ezxml_root_t)root->xml.parent; // root tag
00134     while (root->pi[i] && strcmp(target, root->pi[i][0])) i++; // find target
00135     return (const char **)((root->pi[i]) ? root->pi[i] + 1 : EZXML_NIL);
00136 }
00137 
00138 // set an error string and return root
00139 ezxml_t ezxml_err(ezxml_root_t root, char *s, const char *err, ...)
00140 {
00141     va_list ap;
00142     int line = 1;
00143     char *t, fmt[EZXML_ERRL];
00144     
00145     for (t = root->s; t < s; t++) if (*t == '\n') line++;
00146     snprintf(fmt, EZXML_ERRL, "[error near line %d]: %s", line, err);
00147 
00148     va_start(ap, err);
00149     vsnprintf(root->err, EZXML_ERRL, fmt, ap);
00150     va_end(ap);
00151 
00152     return &root->xml;
00153 }
00154 
00155 // Recursively decodes entity and character references and normalizes new lines
00156 // ent is a null terminated array of alternating entity names and values. set t
00157 // to '&' for general entity decoding, '%' for parameter entity decoding, 'c'
00158 // for cdata sections, ' ' for attribute normalization, or '*' for non-cdata
00159 // attribute normalization. Returns s, or if the decoded string is longer than
00160 // s, returns a malloced string that must be freed.
00161 char *ezxml_decode(char *s, char **ent, char t)
00162 {
00163     char *e, *r = s, *m = s;
00164     long b, c, d, l;
00165 
00166     for (; *s; s++) { // normalize line endings
00167         while (*s == '\r') {
00168             *(s++) = '\n';
00169             if (*s == '\n') memmove(s, (s + 1), strlen(s));
00170         }
00171     }
00172     
00173     for (s = r; ; ) {
00174         while (*s && *s != '&' && (*s != '%' || t != '%') && !isspace(*s)) s++;
00175 
00176         if (! *s) break;
00177         else if (t != 'c' && ! strncmp(s, "&#", 2)) { // character reference
00178             if (s[2] == 'x') c = strtol(s + 3, &e, 16); // base 16
00179             else c = strtol(s + 2, &e, 10); // base 10
00180             if (! c || *e != ';') { s++; continue; } // not a character ref
00181 
00182             if (c < 0x80) *(s++) = c; // US-ASCII subset
00183             else { // multi-byte UTF-8 sequence
00184                 for (b = 0, d = c; d; d /= 2) b++; // number of bits in c
00185                 b = (b - 2) / 5; // number of bytes in payload
00186                 *(s++) = (0xFF << (7 - b)) | (c >> (6 * b)); // head
00187                 while (b) *(s++) = 0x80 | ((c >> (6 * --b)) & 0x3F); // payload
00188             }
00189 
00190             memmove(s, strchr(s, ';') + 1, strlen(strchr(s, ';')));
00191         }
00192         else if ((*s == '&' && (t == '&' || t == ' ' || t == '*')) ||
00193                  (*s == '%' && t == '%')) { // entity reference
00194             for (b = 0; ent[b] && strncmp(s + 1, ent[b], strlen(ent[b]));
00195                  b += 2); // find entity in entity list
00196 
00197             if (ent[b++]) { // found a match
00198                 if ((c = strlen(ent[b])) - 1 > (e = strchr(s, ';')) - s) {
00199                     l = (d = (s - r)) + c + strlen(e); // new length
00200                     r = (r == m) ? strcpy(malloc(l), r) : realloc(r, l);
00201                     e = strchr((s = r + d), ';'); // fix up pointers
00202                 }
00203 
00204                 memmove(s + c, e + 1, strlen(e)); // shift rest of string
00205                 strncpy(s, ent[b], c); // copy in replacement text
00206             }
00207             else s++; // not a known entity
00208         }
00209         else if ((t == ' ' || t == '*') && isspace(*s)) *(s++) = ' ';
00210         else s++; // no decoding needed
00211     }
00212 
00213     if (t == '*') { // normalize spaces for non-cdata attributes
00214         for (s = r; *s; s++) {
00215             if ((l = strspn(s, " "))) memmove(s, s + l, strlen(s + l) + 1);
00216             while (*s && *s != ' ') s++;
00217         }
00218         if (--s >= r && *s == ' ') *s = '\0'; // trim any trailing space
00219     }
00220     return r;
00221 }
00222 
00223 // called when parser finds start of new tag
00224 void ezxml_open_tag(ezxml_root_t root, char *name, char **attr)
00225 {
00226     ezxml_t xml = root->cur;
00227     
00228     if (xml->name) xml = ezxml_add_child(xml, name, strlen(xml->txt));
00229     else xml->name = name; // first open tag
00230 
00231     xml->attr = attr;
00232     root->cur = xml; // update tag insertion point
00233 }
00234 
00235 // called when parser finds character content between open and closing tag
00236 void ezxml_char_content(ezxml_root_t root, char *s, size_t len, char t)
00237 {
00238     ezxml_t xml = root->cur;
00239     char *m = s;
00240     size_t l;
00241 
00242     if (! xml || ! xml->name || ! len) return; // sanity check
00243 
00244     s[len] = '\0'; // null terminate text (calling functions anticipate this)
00245     len = strlen(s = ezxml_decode(s, root->ent, t)) + 1;
00246 
00247     if (! *(xml->txt)) xml->txt = s; // initial character content
00248     else { // allocate our own memory and make a copy
00249         xml->txt = (xml->flags & EZXML_TXTM) // allocate some space
00250                    ? realloc(xml->txt, (l = strlen(xml->txt)) + len)
00251                    : strcpy(malloc((l = strlen(xml->txt)) + len), xml->txt);
00252         strcpy(xml->txt + l, s); // add new char content
00253         if (s != m) free(s); // free s if it was malloced by ezxml_decode()
00254     }
00255 
00256     if (xml->txt != m) ezxml_set_flag(xml, EZXML_TXTM);
00257 }
00258 
00259 // called when parser finds closing tag
00260 ezxml_t ezxml_close_tag(ezxml_root_t root, char *name, char *s)
00261 {
00262     if (! root->cur || ! root->cur->name || strcmp(name, root->cur->name))
00263         return ezxml_err(root, s, "unexpected closing tag </%s>", name);
00264 
00265     root->cur = root->cur->parent;
00266     return NULL;
00267 }
00268 
00269 // checks for circular entity references, returns non-zero if no circular
00270 // references are found, zero otherwise
00271 int ezxml_ent_ok(char *name, char *s, char **ent)
00272 {
00273     int i;
00274 
00275     for (; ; s++) {
00276         while (*s && *s != '&') s++; // find next entity reference
00277         if (! *s) return 1;
00278         if (! strncmp(s + 1, name, strlen(name))) return 0; // circular ref.
00279         for (i = 0; ent[i] && strncmp(ent[i], s + 1, strlen(ent[i])); i += 2);
00280         if (ent[i] && ! ezxml_ent_ok(name, ent[i + 1], ent)) return 0;
00281     }
00282 }
00283 
00284 // called when the parser finds a processing instruction
00285 void ezxml_proc_inst(ezxml_root_t root, char *s, size_t len)
00286 {
00287     int i = 0, j = 1;
00288     char *target = s;
00289 
00290     s[len] = '\0'; // null terminate instruction
00291     if (*(s += strcspn(s, EZXML_WS))) {
00292         *s = '\0'; // null terminate target
00293         s += strspn(s + 1, EZXML_WS) + 1; // skip whitespace after target
00294     }
00295 
00296     if (! strcmp(target, "xml")) { // <?xml ... ?>
00297         if ((s = strstr(s, "standalone")) && ! strncmp(s + strspn(s + 10,
00298             EZXML_WS "='\"") + 10, "yes", 3)) root->standalone = 1;
00299         return;
00300     }
00301 
00302     if (! root->pi[0]) *(root->pi = malloc(sizeof(char **))) = NULL; //first pi
00303 
00304     while (root->pi[i] && strcmp(target, root->pi[i][0])) i++; // find target
00305     if (! root->pi[i]) { // new target
00306         root->pi = realloc(root->pi, sizeof(char **) * (i + 2));
00307         root->pi[i] = malloc(sizeof(char *) * 3);
00308         root->pi[i][0] = target;
00309         root->pi[i][1] = (char *)(root->pi[i + 1] = NULL); // terminate pi list
00310         root->pi[i][2] = strdup(""); // empty document position list
00311     }
00312 
00313     while (root->pi[i][j]) j++; // find end of instruction list for this target
00314     root->pi[i] = realloc(root->pi[i], sizeof(char *) * (j + 3));
00315     root->pi[i][j + 2] = realloc(root->pi[i][j + 1], j + 1);
00316     strcpy(root->pi[i][j + 2] + j - 1, (root->xml.name) ? ">" : "<");
00317     root->pi[i][j + 1] = NULL; // null terminate pi list for this target
00318     root->pi[i][j] = s; // set instruction
00319 }
00320 
00321 // called when the parser finds an internal doctype subset
00322 short ezxml_internal_dtd(ezxml_root_t root, char *s, size_t len)
00323 {
00324     char q, *c, *t, *n = NULL, *v, **ent, **pe;
00325     int i, j;
00326     
00327     pe = memcpy(malloc(sizeof(EZXML_NIL)), EZXML_NIL, sizeof(EZXML_NIL));
00328 
00329     for (s[len] = '\0'; s; ) {
00330         while (*s && *s != '<' && *s != '%') s++; // find next declaration
00331 
00332         if (! *s) break;
00333         else if (! strncmp(s, "<!ENTITY", 8)) { // parse entity definitions
00334             c = s += strspn(s + 8, EZXML_WS) + 8; // skip white space separator
00335             n = s + strspn(s, EZXML_WS "%"); // find name
00336             *(s = n + strcspn(n, EZXML_WS)) = ';'; // append ; to name
00337 
00338             v = s + strspn(s + 1, EZXML_WS) + 1; // find value
00339             if ((q = *(v++)) != '"' && q != '\'') { // skip externals
00340                 s = strchr(s, '>');
00341                 continue;
00342             }
00343 
00344             for (i = 0, ent = (*c == '%') ? pe : root->ent; ent[i]; i++);
00345             ent = realloc(ent, (i + 3) * sizeof(char *)); // space for next ent
00346             if (*c == '%') pe = ent;
00347             else root->ent = ent;
00348 
00349             *(++s) = '\0'; // null terminate name
00350             if ((s = strchr(v, q))) *(s++) = '\0'; // null terminate value
00351             ent[i + 1] = ezxml_decode(v, pe, '%'); // set value
00352             ent[i + 2] = NULL; // null terminate entity list
00353             if (! ezxml_ent_ok(n, ent[i + 1], ent)) { // circular reference
00354                 if (ent[i + 1] != v) free(ent[i + 1]);
00355                 ezxml_err(root, v, "circular entity declaration &%s", n);
00356                 break;
00357             }
00358             else ent[i] = n; // set entity name
00359         }
00360         else if (! strncmp(s, "<!ATTLIST", 9)) { // parse default attributes
00361             t = s + strspn(s + 9, EZXML_WS) + 9; // skip whitespace separator
00362             if (! *t) { ezxml_err(root, t, "unclosed <!ATTLIST"); break; }
00363             if (*(s = t + strcspn(t, EZXML_WS ">")) == '>') continue;
00364             else *s = '\0'; // null terminate tag name
00365             for (i = 0; root->attr[i] && strcmp(n, root->attr[i][0]); i++);
00366 
00367             while (*(n = ++s + strspn(s, EZXML_WS)) && *n != '>') {
00368                 if (*(s = n + strcspn(n, EZXML_WS))) *s = '\0'; // attr name
00369                 else { ezxml_err(root, t, "malformed <!ATTLIST"); break; }
00370 
00371                 s += strspn(s + 1, EZXML_WS) + 1; // find next token
00372                 c = (strncmp(s, "CDATA", 5)) ? "*" : " "; // is it cdata?
00373                 if (! strncmp(s, "NOTATION", 8))
00374                     s += strspn(s + 8, EZXML_WS) + 8;
00375                 s = (*s == '(') ? strchr(s, ')') : s + strcspn(s, EZXML_WS);
00376                 if (! s) { ezxml_err(root, t, "malformed <!ATTLIST"); break; }
00377 
00378                 s += strspn(s, EZXML_WS ")"); // skip white space separator
00379                 if (! strncmp(s, "#FIXED", 6))
00380                     s += strspn(s + 6, EZXML_WS) + 6;
00381                 if (*s == '#') { // no default value
00382                     s += strcspn(s, EZXML_WS ">") - 1;
00383                     if (*c == ' ') continue; // cdata is default, nothing to do
00384                     v = NULL;
00385                 }
00386                 else if ((*s == '"' || *s == '\'')  &&  // default value
00387                          (s = strchr(v = s + 1, *s))) *s = '\0';
00388                 else { ezxml_err(root, t, "malformed <!ATTLIST"); break; }
00389 
00390                 if (! root->attr[i]) { // new tag name
00391                     root->attr = (! i) ? malloc(2 * sizeof(char **))
00392                                        : realloc(root->attr,
00393                                                  (i + 2) * sizeof(char **));
00394                     root->attr[i] = malloc(2 * sizeof(char *));
00395                     root->attr[i][0] = t; // set tag name
00396                     root->attr[i][1] = (char *)(root->attr[i + 1] = NULL);
00397                 }
00398 
00399                 for (j = 1; root->attr[i][j]; j += 3); // find end of list
00400                 root->attr[i] = realloc(root->attr[i],
00401                                         (j + 4) * sizeof(char *));
00402 
00403                 root->attr[i][j + 3] = NULL; // null terminate list
00404                 root->attr[i][j + 2] = c; // is it cdata?
00405                 root->attr[i][j + 1] = (v) ? ezxml_decode(v, root->ent, *c)
00406                                            : NULL;
00407                 root->attr[i][j] = n; // attribute name 
00408             }
00409         }
00410         else if (! strncmp(s, "<!--", 4)) s = strstr(s + 4, "-->"); // comments
00411         else if (! strncmp(s, "<?", 2)) { // processing instructions
00412             if ((s = strstr(c = s + 2, "?>")))
00413                 ezxml_proc_inst(root, c, s++ - c);
00414         }
00415         else if (*s == '<') s = strchr(s, '>'); // skip other declarations
00416         else if (*(s++) == '%' && ! root->standalone) break;
00417     }
00418 
00419     free(pe);
00420     return ! *root->err;
00421 }
00422 
00423 // Converts a UTF-16 string to UTF-8. Returns a new string that must be freed
00424 // or NULL if no conversion was needed.
00425 char *ezxml_str2utf8(char **s, size_t *len)
00426 {
00427     char *u;
00428     size_t l = 0, sl, max = *len;
00429     long c, d;
00430     int b, be = (**s == '\xFE') ? 1 : (**s == '\xFF') ? 0 : -1;
00431 
00432     if (be == -1) return NULL; // not UTF-16
00433 
00434     u = malloc(max);
00435     for (sl = 2; sl < *len - 1; sl += 2) {
00436         c = (be) ? (((*s)[sl] & 0xFF) << 8) | ((*s)[sl + 1] & 0xFF)  //UTF-16BE
00437                  : (((*s)[sl + 1] & 0xFF) << 8) | ((*s)[sl] & 0xFF); //UTF-16LE
00438         if (c >= 0xD800 && c <= 0xDFFF && (sl += 2) < *len - 1) { // high-half
00439             d = (be) ? (((*s)[sl] & 0xFF) << 8) | ((*s)[sl + 1] & 0xFF)
00440                      : (((*s)[sl + 1] & 0xFF) << 8) | ((*s)[sl] & 0xFF);
00441             c = (((c & 0x3FF) << 10) | (d & 0x3FF)) + 0x10000;
00442         }
00443 
00444         while (l + 6 > max) u = realloc(u, max += EZXML_BUFSIZE);
00445         if (c < 0x80) u[l++] = c; // US-ASCII subset
00446         else { // multi-byte UTF-8 sequence
00447             for (b = 0, d = c; d; d /= 2) b++; // bits in c
00448             b = (b - 2) / 5; // bytes in payload
00449             u[l++] = (0xFF << (7 - b)) | (c >> (6 * b)); // head
00450             while (b) u[l++] = 0x80 | ((c >> (6 * --b)) & 0x3F); // payload
00451         }
00452     }
00453     return *s = realloc(u, *len = l);
00454 }
00455 
00456 // frees a tag attribute list
00457 void ezxml_free_attr(char **attr) {
00458     int i = 0;
00459     char *m;
00460     
00461     if (! attr || attr == EZXML_NIL) return; // nothing to free
00462     while (attr[i]) i += 2; // find end of attribute list
00463     m = attr[i + 1]; // list of which names and values are malloced
00464     for (i = 0; m[i]; i++) {
00465         if (m[i] & EZXML_NAMEM) free(attr[i * 2]);
00466         if (m[i] & EZXML_TXTM) free(attr[(i * 2) + 1]);
00467     }
00468     free(m);
00469     free(attr);
00470 }
00471 
00472 // parse the given xml string and return an ezxml structure
00473 ezxml_t ezxml_parse_str(char *s, size_t len)
00474 {
00475     ezxml_root_t root = (ezxml_root_t)ezxml_new(NULL);
00476     char q, e, *d, **attr, **a = NULL; // initialize a to avoid compile warning
00477     int l, i, j;
00478 
00479     root->m = s;
00480     if (! len) return ezxml_err(root, NULL, "root tag missing");
00481     root->u = ezxml_str2utf8(&s, &len); // convert utf-16 to utf-8
00482     root->e = (root->s = s) + len; // record start and end of work area
00483     
00484     e = s[len - 1]; // save end char
00485     s[len - 1] = '\0'; // turn end char into null terminator
00486 
00487     while (*s && *s != '<') s++; // find first tag
00488     if (! *s) return ezxml_err(root, s, "root tag missing");
00489 
00490     for (; ; ) {
00491         attr = (char **)EZXML_NIL;
00492         d = ++s;
00493         
00494         if (isalpha(*s) || *s == '_' || *s == ':' || *s < '\0') { // new tag
00495             if (! root->cur)
00496                 return ezxml_err(root, d, "markup outside of root element");
00497 
00498             s += strcspn(s, EZXML_WS "/>");
00499             while (isspace(*s)) *(s++) = '\0'; // null terminate tag name
00500   
00501             if (*s && *s != '/' && *s != '>') // find tag in default attr list
00502                 for (i = 0; (a = root->attr[i]) && strcmp(a[0], d); i++);
00503 
00504             for (l = 0; *s && *s != '/' && *s != '>'; l += 2) { // new attrib
00505                 attr = (l) ? realloc(attr, (l + 4) * sizeof(char *))
00506                            : malloc(4 * sizeof(char *)); // allocate space
00507                 attr[l + 3] = (l) ? realloc(attr[l + 1], (l / 2) + 2)
00508                                   : malloc(2); // mem for list of maloced vals
00509                 strcpy(attr[l + 3] + (l / 2), " "); // value is not malloced
00510                 attr[l + 2] = NULL; // null terminate list
00511                 attr[l + 1] = ""; // temporary attribute value
00512                 attr[l] = s; // set attribute name
00513 
00514                 s += strcspn(s, EZXML_WS "=/>");
00515                 if (*s == '=' || isspace(*s)) { 
00516                     *(s++) = '\0'; // null terminate tag attribute name
00517                     q = *(s += strspn(s, EZXML_WS "="));
00518                     if (q == '"' || q == '\'') { // attribute value
00519                         attr[l + 1] = ++s;
00520                         while (*s && *s != q) s++;
00521                         if (*s) *(s++) = '\0'; // null terminate attribute val
00522                         else {
00523                             ezxml_free_attr(attr);
00524                             return ezxml_err(root, d, "missing %c", q);
00525                         }
00526 
00527                         for (j = 1; a && a[j] && strcmp(a[j], attr[l]); j +=3);
00528                         attr[l + 1] = ezxml_decode(attr[l + 1], root->ent, (a
00529                                                    && a[j]) ? *a[j + 2] : ' ');
00530                         if (attr[l + 1] < d || attr[l + 1] > s)
00531                             attr[l + 3][l / 2] = EZXML_TXTM; // value malloced
00532                     }
00533                 }
00534                 while (isspace(*s)) s++;
00535             }
00536 
00537             if (*s == '/') { // self closing tag
00538                 *(s++) = '\0';
00539                 if ((*s && *s != '>') || (! *s && e != '>')) {
00540                     if (l) ezxml_free_attr(attr);
00541                     return ezxml_err(root, d, "missing >");
00542                 }
00543                 ezxml_open_tag(root, d, attr);
00544                 ezxml_close_tag(root, d, s);
00545             }
00546             else if ((q = *s) == '>' || (! *s && e == '>')) { // open tag
00547                 *s = '\0'; // temporarily null terminate tag name
00548                 ezxml_open_tag(root, d, attr);
00549                 *s = q;
00550             }
00551             else {
00552                 if (l) ezxml_free_attr(attr);
00553                 return ezxml_err(root, d, "missing >"); 
00554             }
00555         }
00556         else if (*s == '/') { // close tag
00557             s += strcspn(d = s + 1, EZXML_WS ">") + 1;
00558             if (! (q = *s) && e != '>') return ezxml_err(root, d, "missing >");
00559             *s = '\0'; // temporarily null terminate tag name
00560             if (ezxml_close_tag(root, d, s)) return &root->xml;
00561             if (isspace(*s = q)) s += strspn(s, EZXML_WS);
00562         }
00563         else if (! strncmp(s, "!--", 3)) { // xml comment
00564             if (! (s = strstr(s + 3, "--")) || (*(s += 2) != '>' && *s) ||
00565                 (! *s && e != '>')) return ezxml_err(root, d, "unclosed <!--");
00566         }
00567         else if (! strncmp(s, "![CDATA[", 8)) { // cdata
00568             if ((s = strstr(s, "]]>")))
00569                 ezxml_char_content(root, d + 8, (s += 2) - d - 10, 'c');
00570             else return ezxml_err(root, d, "unclosed <![CDATA[");
00571         }
00572         else if (! strncmp(s, "!DOCTYPE", 8)) { // dtd
00573             for (l = 0; *s && ((! l && *s != '>') || (l && (*s != ']' || 
00574                  *(s + strspn(s + 1, EZXML_WS) + 1) != '>')));
00575                  l = (*s == '[') ? 1 : l) s += strcspn(s + 1, "[]>") + 1;
00576             if (! *s && e != '>')
00577                 return ezxml_err(root, d, "unclosed <!DOCTYPE");
00578             d = (l) ? strchr(d, '[') + 1 : d;
00579             if (l && ! ezxml_internal_dtd(root, d, s++ - d)) return &root->xml;
00580         }
00581         else if (*s == '?') { // <?...?> processing instructions
00582             do { s = strchr(s, '?'); } while (s && *(++s) && *s != '>');
00583             if (! s || (! *s && e != '>')) 
00584                 return ezxml_err(root, d, "unclosed <?");
00585             else ezxml_proc_inst(root, d + 1, s - d - 2);
00586         }
00587         else return ezxml_err(root, d, "unexpected <");
00588         
00589         if (! s || ! *s) break;
00590         *s = '\0';
00591         d = ++s;
00592         if (*s && *s != '<') { // tag character content
00593             while (*s && *s != '<') s++;
00594             if (*s) ezxml_char_content(root, d, s - d, '&');
00595             else break;
00596         }
00597         else if (! *s) break;
00598     }
00599 
00600     if (! root->cur) return &root->xml;
00601     else if (! root->cur->name) return ezxml_err(root, d, "root tag missing");
00602     else return ezxml_err(root, d, "unclosed tag <%s>", root->cur->name);
00603 }
00604 
00605 // Wrapper for ezxml_parse_str() that accepts a file stream. Reads the entire
00606 // stream into memory and then parses it. For xml files, use ezxml_parse_file()
00607 // or ezxml_parse_fd()
00608 ezxml_t ezxml_parse_fp(FILE *fp)
00609 {
00610     ezxml_root_t root;
00611     size_t l, len = 0;
00612     char *s;
00613 
00614     if (! (s = malloc(EZXML_BUFSIZE))) return NULL;
00615     do {
00616         len += (l = fread((s + len), 1, EZXML_BUFSIZE, fp));
00617         if (l == EZXML_BUFSIZE) s = realloc(s, len + EZXML_BUFSIZE);
00618     } while (s && l == EZXML_BUFSIZE);
00619 
00620     if (! s) return NULL;
00621     root = (ezxml_root_t)ezxml_parse_str(s, len);
00622     root->len = -1; // so we know to free s in ezxml_free()
00623     return &root->xml;
00624 }
00625 
00626 // A wrapper for ezxml_parse_str() that accepts a file descriptor. First
00627 // attempts to mem map the file. Failing that, reads the file into memory.
00628 // Returns NULL on failure.
00629 ezxml_t ezxml_parse_fd(int fd)
00630 {
00631     ezxml_root_t root;
00632     struct stat st;
00633     size_t l;
00634     void *m;
00635 
00636     if (fd < 0) return NULL;
00637     fstat(fd, &st);
00638 
00639 #ifndef EZXML_NOMMAP
00640     l = (st.st_size + sysconf(_SC_PAGESIZE) - 1) & ~(sysconf(_SC_PAGESIZE) -1);
00641     if ((m = mmap(NULL, l, PROT_READ|PROT_WRITE, MAP_PRIVATE, fd, 0))
00642               !=  MAP_FAILED) {
00643         madvise(m, l, MADV_SEQUENTIAL); // optimize for sequential access
00644         root = (ezxml_root_t)ezxml_parse_str(m, st.st_size);
00645         madvise(m, root->len = l, MADV_NORMAL); // put it back to normal
00646     }
00647     else { // mmap failed, read file into memory
00648 #endif // EZXML_NOMMAP
00649         l = read(fd, m = malloc(st.st_size), st.st_size);
00650         root = (ezxml_root_t)ezxml_parse_str(m, l);
00651         root->len = -1; // so we know to free s in ezxml_free()
00652 #ifndef EZXML_NOMMAP
00653     }
00654 #endif // EZXML_NOMMAP
00655     return &root->xml;
00656 }
00657 
00658 // a wrapper for ezxml_parse_fd that accepts a file name
00659 ezxml_t ezxml_parse_file(const char *file)
00660 {
00661     int fd = open(file, O_RDONLY, 0);
00662     ezxml_t xml = ezxml_parse_fd(fd);
00663     
00664     if (fd >= 0) close(fd);
00665     return xml;
00666 }
00667 
00668 // Encodes ampersand sequences appending the results to *dst, reallocating *dst
00669 // if length excedes max. a is non-zero for attribute encoding. Returns *dst
00670 char *ezxml_ampencode(const char *s, size_t len, char **dst, size_t *dlen,
00671                       size_t *max, short a)
00672 {
00673     const char *e;
00674     
00675     for (e = s + len; s != e; s++) {
00676         while (*dlen + 10 > *max) *dst = realloc(*dst, *max += EZXML_BUFSIZE);
00677 
00678         switch (*s) {
00679         case '\0': return *dst;
00680         case '&': *dlen += sprintf(*dst + *dlen, "&amp;"); break;
00681         case '<': *dlen += sprintf(*dst + *dlen, "&lt;"); break;
00682         case '>': *dlen += sprintf(*dst + *dlen, "&gt;"); break;
00683         case '"': *dlen += sprintf(*dst + *dlen, (a) ? "&quot;" : "\""); break;
00684         case '\n': *dlen += sprintf(*dst + *dlen, (a) ? "&#xA;" : "\n"); break;
00685         case '\t': *dlen += sprintf(*dst + *dlen, (a) ? "&#x9;" : "\t"); break;
00686         case '\r': *dlen += sprintf(*dst + *dlen, "&#xD;"); break;
00687         default: (*dst)[(*dlen)++] = *s;
00688         }
00689     }
00690     return *dst;
00691 }
00692 
00693 // Recursively converts each tag to xml appending it to *s. Reallocates *s if
00694 // its length excedes max. start is the location of the previous tag in the
00695 // parent tag's character content. Returns *s.
00696 char *ezxml_toxml_r(ezxml_t xml, char **s, size_t *len, size_t *max,
00697                     size_t start, char ***attr)
00698 {
00699     int i, j;
00700     char *txt = (xml->parent) ? xml->parent->txt : "";
00701     size_t off = 0;
00702 
00703     // parent character content up to this tag
00704     *s = ezxml_ampencode(txt + start, xml->off - start, s, len, max, 0);
00705 
00706     while (*len + strlen(xml->name) + 4 > *max) // reallocate s
00707         *s = realloc(*s, *max += EZXML_BUFSIZE);
00708 
00709     *len += sprintf(*s + *len, "<%s", xml->name); // open tag
00710     for (i = 0; xml->attr[i]; i += 2) { // tag attributes
00711         if (ezxml_attr(xml, xml->attr[i]) != xml->attr[i + 1]) continue;
00712         while (*len + strlen(xml->attr[i]) + 7 > *max) // reallocate s
00713             *s = realloc(*s, *max += EZXML_BUFSIZE);
00714 
00715         *len += sprintf(*s + *len, " %s=\"", xml->attr[i]);
00716         ezxml_ampencode(xml->attr[i + 1], -1, s, len, max, 1);
00717         *len += sprintf(*s + *len, "\"");
00718     }
00719 
00720     for (i = 0; attr[i] && strcmp(attr[i][0], xml->name); i++);
00721     for (j = 1; attr[i] && attr[i][j]; j += 3) { // default attributes
00722         if (! attr[i][j + 1] || ezxml_attr(xml, attr[i][j]) != attr[i][j + 1])
00723             continue; // skip duplicates and non-values
00724         while (*len + strlen(attr[i][j]) + 7 > *max) // reallocate s
00725             *s = realloc(*s, *max += EZXML_BUFSIZE);
00726 
00727         *len += sprintf(*s + *len, " %s=\"", attr[i][j]);
00728         ezxml_ampencode(attr[i][j + 1], -1, s, len, max, 1);
00729         *len += sprintf(*s + *len, "\"");
00730     }
00731     *len += sprintf(*s + *len, ">");
00732 
00733     *s = (xml->child) ? ezxml_toxml_r(xml->child, s, len, max, 0, attr) //child
00734                       : ezxml_ampencode(xml->txt, -1, s, len, max, 0);  //data
00735     
00736     while (*len + strlen(xml->name) + 4 > *max) // reallocate s
00737         *s = realloc(*s, *max += EZXML_BUFSIZE);
00738 
00739     *len += sprintf(*s + *len, "</%s>", xml->name); // close tag
00740 
00741     while (txt[off] && off < xml->off) off++; // make sure off is within bounds
00742     return (xml->ordered) ? ezxml_toxml_r(xml->ordered, s, len, max, off, attr)
00743                           : ezxml_ampencode(txt + off, -1, s, len, max, 0);
00744 }
00745 
00746 // Converts an ezxml structure back to xml. Returns a string of xml data that
00747 // must be freed.
00748 char *ezxml_toxml(ezxml_t xml)
00749 {
00750     ezxml_t p = (xml) ? xml->parent : NULL, o = (xml) ? xml->ordered : NULL;
00751     ezxml_root_t root = (ezxml_root_t)xml;
00752     size_t len = 0, max = EZXML_BUFSIZE;
00753     char *s = strcpy(malloc(max), ""), *t, *n;
00754     int i, j, k;
00755 
00756     if (! xml || ! xml->name) return realloc(s, len + 1);
00757     while (root->xml.parent) root = (ezxml_root_t)root->xml.parent; // root tag
00758 
00759     for (i = 0; ! p && root->pi[i]; i++) { // pre-root processing instructions
00760         for (k = 2; root->pi[i][k - 1]; k++);
00761         for (j = 1; (n = root->pi[i][j]); j++) {
00762             if (root->pi[i][k][j - 1] == '>') continue; // not pre-root
00763             while (len + strlen(t = root->pi[i][0]) + strlen(n) + 7 > max)
00764                 s = realloc(s, max += EZXML_BUFSIZE);
00765             len += sprintf(s + len, "<?%s%s%s?>\n", t, *n ? " " : "", n);
00766         }
00767     }
00768 
00769     xml->parent = xml->ordered = NULL;
00770     s = ezxml_toxml_r(xml, &s, &len, &max, 0, root->attr);
00771     xml->parent = p;
00772     xml->ordered = o;
00773 
00774     for (i = 0; ! p && root->pi[i]; i++) { // post-root processing instructions
00775         for (k = 2; root->pi[i][k - 1]; k++);
00776         for (j = 1; (n = root->pi[i][j]); j++) {
00777             if (root->pi[i][k][j - 1] == '<') continue; // not post-root
00778             while (len + strlen(t = root->pi[i][0]) + strlen(n) + 7 > max)
00779                 s = realloc(s, max += EZXML_BUFSIZE);
00780             len += sprintf(s + len, "\n<?%s%s%s?>", t, *n ? " " : "", n);
00781         }
00782     }
00783     return realloc(s, len + 1);
00784 }
00785 
00786 // free the memory allocated for the ezxml structure
00787 void ezxml_free(ezxml_t xml)
00788 {
00789     ezxml_root_t root = (ezxml_root_t)xml;
00790     int i, j;
00791     char **a, *s;
00792 
00793     if (! xml) return;
00794     ezxml_free(xml->child);
00795     ezxml_free(xml->ordered);
00796 
00797     if (! xml->parent) { // free root tag allocations
00798         for (i = 10; root->ent[i]; i += 2) // 0 - 9 are default entites (<>&"')
00799             if ((s = root->ent[i + 1]) < root->s || s > root->e) free(s);
00800         free(root->ent); // free list of general entities
00801 
00802         for (i = 0; (a = root->attr[i]); i++) {
00803             for (j = 1; a[j++]; j += 2) // free malloced attribute values
00804                 if (a[j] && (a[j] < root->s || a[j] > root->e)) free(a[j]);
00805             free(a);
00806         }
00807         if (root->attr[0]) free(root->attr); // free default attribute list
00808 
00809         for (i = 0; root->pi[i]; i++) {
00810             for (j = 1; root->pi[i][j]; j++);
00811             free(root->pi[i][j + 1]);
00812             free(root->pi[i]);
00813         }            
00814         if (root->pi[0]) free(root->pi); // free processing instructions
00815 
00816         if (root->len == -1) free(root->m); // malloced xml data
00817 #ifndef EZXML_NOMMAP
00818         else if (root->len) munmap(root->m, root->len); // mem mapped xml data
00819 #endif // EZXML_NOMMAP
00820         if (root->u) free(root->u); // utf8 conversion
00821     }
00822 
00823     ezxml_free_attr(xml->attr); // tag attributes
00824     if ((xml->flags & EZXML_TXTM)) free(xml->txt); // character content
00825     if ((xml->flags & EZXML_NAMEM)) free(xml->name); // tag name
00826     free(xml);
00827 }
00828 
00829 // return parser error message or empty string if none
00830 const char *ezxml_error(ezxml_t xml)
00831 {
00832     while (xml && xml->parent) xml = xml->parent; // find root tag
00833     return (xml) ? ((ezxml_root_t)xml)->err : "";
00834 }
00835 
00836 // returns a new empty ezxml structure with the given root tag name
00837 ezxml_t ezxml_new(const char *name)
00838 {
00839     static char *ent[] = { "lt;", "&#60;", "gt;", "&#62;", "quot;", "&#34;",
00840                            "apos;", "&#39;", "amp;", "&#38;", NULL };
00841     ezxml_root_t root = (ezxml_root_t)memset(malloc(sizeof(struct ezxml_root)), 
00842                                              '\0', sizeof(struct ezxml_root));
00843     root->xml.name = (char *)name;
00844     root->cur = &root->xml;
00845     strcpy(root->err, root->xml.txt = "");
00846     root->ent = memcpy(malloc(sizeof(ent)), ent, sizeof(ent));
00847     root->attr = root->pi = (char ***)(root->xml.attr = EZXML_NIL);
00848     return &root->xml;
00849 }
00850 
00851 // inserts an existing tag into an ezxml structure
00852 ezxml_t ezxml_insert(ezxml_t xml, ezxml_t dest, size_t off)
00853 {
00854     ezxml_t cur, prev, head;
00855 
00856     xml->next = xml->sibling = xml->ordered = NULL;
00857     xml->off = off;
00858     xml->parent = dest;
00859 
00860     if ((head = dest->child)) { // already have sub tags
00861         if (head->off <= off) { // not first subtag
00862             for (cur = head; cur->ordered && cur->ordered->off <= off;
00863                  cur = cur->ordered);
00864             xml->ordered = cur->ordered;
00865             cur->ordered = xml;
00866         }
00867         else { // first subtag
00868             xml->ordered = head;
00869             dest->child = xml;
00870         }
00871 
00872         for (cur = head, prev = NULL; cur && strcmp(cur->name, xml->name);
00873              prev = cur, cur = cur->sibling); // find tag type
00874         if (cur && cur->off <= off) { // not first of type
00875             while (cur->next && cur->next->off <= off) cur = cur->next;
00876             xml->next = cur->next;
00877             cur->next = xml;
00878         }
00879         else { // first tag of this type
00880             if (prev && cur) prev->sibling = cur->sibling; // remove old first
00881             xml->next = cur; // old first tag is now next
00882             for (cur = head, prev = NULL; cur && cur->off <= off;
00883                  prev = cur, cur = cur->sibling); // new sibling insert point
00884             xml->sibling = cur;
00885             if (prev) prev->sibling = xml;
00886         }
00887     }
00888     else dest->child = xml; // only sub tag
00889 
00890     return xml;
00891 }
00892 
00893 // Adds a child tag. off is the offset of the child tag relative to the start
00894 // of the parent tag's character content. Returns the child tag.
00895 ezxml_t ezxml_add_child(ezxml_t xml, const char *name, size_t off)
00896 {
00897     ezxml_t child;
00898 
00899     if (! xml) return NULL;
00900     child = (ezxml_t)memset(malloc(sizeof(struct ezxml)), '\0',
00901                             sizeof(struct ezxml));
00902     child->name = (char *)name;
00903     child->attr = EZXML_NIL;
00904     child->txt = "";
00905 
00906     return ezxml_insert(child, xml, off);
00907 }
00908 
00909 // sets the character content for the given tag and returns the tag
00910 ezxml_t ezxml_set_txt(ezxml_t xml, const char *txt)
00911 {
00912     if (! xml) return NULL;
00913     if (xml->flags & EZXML_TXTM) free(xml->txt); // existing txt was malloced
00914     xml->flags &= ~EZXML_TXTM;
00915     xml->txt = (char *)txt;
00916     return xml;
00917 }
00918 
00919 // Sets the given tag attribute or adds a new attribute if not found. A value
00920 // of NULL will remove the specified attribute. Returns the tag given.
00921 ezxml_t ezxml_set_attr(ezxml_t xml, const char *name, const char *value)
00922 {
00923     int l = 0, c;
00924 
00925     if (! xml) return NULL;
00926     while (xml->attr[l] && strcmp(xml->attr[l], name)) l += 2;
00927     if (! xml->attr[l]) { // not found, add as new attribute
00928         if (! value) return xml; // nothing to do
00929         if (xml->attr == EZXML_NIL) { // first attribute
00930             xml->attr = malloc(4 * sizeof(char *));
00931             xml->attr[1] = strdup(""); // empty list of malloced names/vals
00932         }
00933         else xml->attr = realloc(xml->attr, (l + 4) * sizeof(char *));
00934 
00935         xml->attr[l] = (char *)name; // set attribute name
00936         xml->attr[l + 2] = NULL; // null terminate attribute list
00937         xml->attr[l + 3] = realloc(xml->attr[l + 1],
00938                                    (c = strlen(xml->attr[l + 1])) + 2);
00939         strcpy(xml->attr[l + 3] + c, " "); // set name/value as not malloced
00940         if (xml->flags & EZXML_DUP) xml->attr[l + 3][c] = EZXML_NAMEM;
00941     }
00942     else if (xml->flags & EZXML_DUP) free((char *)name); // name was strduped
00943 
00944     for (c = l; xml->attr[c]; c += 2); // find end of attribute list
00945     if (xml->attr[c + 1][l / 2] & EZXML_TXTM) free(xml->attr[l + 1]); //old val
00946     if (xml->flags & EZXML_DUP) xml->attr[c + 1][l / 2] |= EZXML_TXTM;
00947     else xml->attr[c + 1][l / 2] &= ~EZXML_TXTM;
00948 
00949     if (value) xml->attr[l + 1] = (char *)value; // set attribute value
00950     else { // remove attribute
00951         if (xml->attr[c + 1][l / 2] & EZXML_NAMEM) free(xml->attr[l]);
00952         memmove(xml->attr + l, xml->attr + l + 2, (c - l + 2) * sizeof(char*));
00953         xml->attr = realloc(xml->attr, (c + 2) * sizeof(char *));
00954         memmove(xml->attr[c + 1] + (l / 2), xml->attr[c + 1] + (l / 2) + 1,
00955                 (c / 2) - (l / 2)); // fix list of which name/vals are malloced
00956     }
00957     xml->flags &= ~EZXML_DUP; // clear strdup() flag
00958     return xml;
00959 }
00960 
00961 // sets a flag for the given tag and returns the tag
00962 ezxml_t ezxml_set_flag(ezxml_t xml, short flag)
00963 {
00964     if (xml) xml->flags |= flag;
00965     return xml;
00966 }
00967 
00968 // removes a tag along with its subtags without freeing its memory
00969 ezxml_t ezxml_cut(ezxml_t xml)
00970 {
00971     ezxml_t cur;
00972 
00973     if (! xml) return NULL; // nothing to do
00974     if (xml->next) xml->next->sibling = xml->sibling; // patch sibling list
00975 
00976     if (xml->parent) { // not root tag
00977         cur = xml->parent->child; // find head of subtag list
00978         if (cur == xml) xml->parent->child = xml->ordered; // first subtag
00979         else { // not first subtag
00980             while (cur->ordered != xml) cur = cur->ordered;
00981             cur->ordered = cur->ordered->ordered; // patch ordered list
00982 
00983             cur = xml->parent->child; // go back to head of subtag list
00984             if (strcmp(cur->name, xml->name)) { // not in first sibling list
00985                 while (strcmp(cur->sibling->name, xml->name))
00986                     cur = cur->sibling;
00987                 if (cur->sibling == xml) { // first of a sibling list
00988                     cur->sibling = (xml->next) ? xml->next
00989                                                : cur->sibling->sibling;
00990                 }
00991                 else cur = cur->sibling; // not first of a sibling list
00992             }
00993 
00994             while (cur->next && cur->next != xml) cur = cur->next;
00995             if (cur->next) cur->next = cur->next->next; // patch next list
00996         }        
00997     }
00998     xml->ordered = xml->sibling = xml->next = NULL;
00999     return xml;
01000 }
01001 
01002 #ifdef EZXML_TEST // test harness
01003 int main(int argc, char **argv)
01004 {
01005     ezxml_t xml;
01006     char *s;
01007     int i;
01008 
01009     if (argc != 2) return fprintf(stderr, "usage: %s xmlfile\n", argv[0]);
01010 
01011     xml = ezxml_parse_file(argv[1]);
01012     printf("%s\n", (s = ezxml_toxml(xml)));
01013     free(s);
01014     i = fprintf(stderr, "%s", ezxml_error(xml));
01015     ezxml_free(xml);
01016     return (i) ? 1 : 0;
01017 }
01018 #endif // EZXML_TEST