doc/devhelp/libxml2-pattern.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <html>
   3   <head>
   4     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
   5     <title>pattern: pattern expression handling</title>
   6     <meta name="generator" content="Libxml2 devhelp stylesheet"/>
   7     <link rel="start" href="index.html" title="libxml2 Reference Manual"/>
   8     <link rel="up" href="general.html" title="API"/>
   9     <link rel="stylesheet" href="style.css" type="text/css"/>
  10     <link rel="chapter" href="general.html" title="API"/>
  11   </head>
  12   <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13     <table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  14       <tr valign="middle">
  15         <td>
  16           <a accesskey="p" href="libxml2-parserInternals.html">
  17             <img src="left.png" width="24" height="24" border="0" alt="Prev"/>
  18           </a>
  19         </td>
  20         <td>
  21           <a accesskey="u" href="general.html">
  22             <img src="up.png" width="24" height="24" border="0" alt="Up"/>
  23           </a>
  24         </td>
  25         <td>
  26           <a accesskey="h" href="index.html">
  27             <img src="home.png" width="24" height="24" border="0" alt="Home"/>
  28           </a>
  29         </td>
  30         <td>
  31           <a accesskey="n" href="libxml2-relaxng.html">
  32             <img src="right.png" width="24" height="24" border="0" alt="Next"/>
  33           </a>
  34         </td>
  35         <th width="100%" align="center">libxml2 Reference Manual</th>
  36       </tr>
  37     </table>
  38     <h2>
  39       <span class="refentrytitle">pattern</span>
  40     </h2>
  41     <p>pattern - pattern expression handling</p>
  42     <p>allows to compile and test pattern expressions for nodes either in a tree or based on a parser state. </p>
  43     <p>Author(s): Daniel Veillard </p>
  44     <div class="refsynopsisdiv">
  45       <h2>Synopsis</h2>
  46       <pre class="synopsis">typedef <a href="libxml2-pattern.html#xmlStreamCtxt">xmlStreamCtxt</a> * <a href="#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a>;
  47 typedef enum <a href="#xmlPatternFlags">xmlPatternFlags</a>;
  48 typedef struct _xmlStreamCtxt <a href="#xmlStreamCtxt">xmlStreamCtxt</a>;
  49 typedef struct _xmlPattern <a href="#xmlPattern">xmlPattern</a>;
  50 typedef <a href="libxml2-pattern.html#xmlPattern">xmlPattern</a> * <a href="#xmlPatternPtr">xmlPatternPtr</a>;
  51 int     <a href="#xmlPatternMinDepth">xmlPatternMinDepth</a>            (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp);
  52 <a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a>    <a href="#xmlPatternGetStreamCtxt">xmlPatternGetStreamCtxt</a>  (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp);
  53 int     <a href="#xmlPatternFromRoot">xmlPatternFromRoot</a>            (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp);
  54 void    <a href="#xmlFreePatternList">xmlFreePatternList</a>            (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp);
  55 int     <a href="#xmlPatternStreamable">xmlPatternStreamable</a>                (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp);
  56 int     <a href="#xmlStreamPushAttr">xmlStreamPushAttr</a>              (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream, <br/>                                      const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * name, <br/>                                        const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * ns);
  57 int     <a href="#xmlPatternMatch">xmlPatternMatch</a>                  (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp, <br/>                                      <a href="libxml2-tree.html#xmlNodePtr">xmlNodePtr</a> node);
  58 int     <a href="#xmlStreamWantsAnyNode">xmlStreamWantsAnyNode</a>              (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> streamCtxt);
  59 int     <a href="#xmlStreamPop">xmlStreamPop</a>                        (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream);
  60 void    <a href="#xmlFreePattern">xmlFreePattern</a>                    (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp);
  61 int     <a href="#xmlStreamPush">xmlStreamPush</a>                      (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream, <br/>                                      const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * name, <br/>                                        const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * ns);
  62 int     <a href="#xmlPatternMaxDepth">xmlPatternMaxDepth</a>            (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp);
  63 <a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a>  <a href="#xmlPatterncompile">xmlPatterncompile</a>      (const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * pattern, <br/>                                     <a href="libxml2-dict.html#xmlDict">xmlDict</a> * dict, <br/>                                   int flags, <br/>                                        const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> ** namespaces);
  64 int     <a href="#xmlStreamPushNode">xmlStreamPushNode</a>              (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream, <br/>                                      const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * name, <br/>                                        const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * ns, <br/>                                  int nodeType);
  65 void    <a href="#xmlFreeStreamCtxt">xmlFreeStreamCtxt</a>              (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream);
  66 </pre>
  67     </div>
  68     <div class="refsect1" lang="en">
  69       <h2>Description</h2>
  70     </div>
  71     <div class="refsect1" lang="en">
  72       <h2>Details</h2>
  73       <div class="refsect2" lang="en">
  74         <div class="refsect2" lang="en"><h3><a name="xmlPattern">Structure </a>xmlPattern</h3><pre class="programlisting">struct _xmlPattern {
  75 The content of this structure is not made public by the API.
  76 } xmlPattern;
  77 </pre><p/>
  78 </div>
  79         <hr/>
  80         <div class="refsect2" lang="en"><h3><a name="xmlPatternFlags">Enum </a>xmlPatternFlags</h3><pre class="programlisting">enum <a href="#xmlPatternFlags">xmlPatternFlags</a> {
  81     <a name="XML_PATTERN_DEFAULT">XML_PATTERN_DEFAULT</a> = 0 /* simple pattern match */
  82     <a name="XML_PATTERN_XPATH">XML_PATTERN_XPATH</a> = 1 /* standard XPath pattern */
  83     <a name="XML_PATTERN_XSSEL">XML_PATTERN_XSSEL</a> = 2 /* XPath subset for schema selector */
  84     <a name="XML_PATTERN_XSFIELD">XML_PATTERN_XSFIELD</a> = 4 /*  XPath subset for schema field */
  85 };
  86 </pre><p/>
  87 </div>
  88         <hr/>
  89         <div class="refsect2" lang="en"><h3><a name="xmlPatternPtr">Typedef </a>xmlPatternPtr</h3><pre class="programlisting"><a href="libxml2-pattern.html#xmlPattern">xmlPattern</a> * xmlPatternPtr;
  90 </pre><p/>
  91 </div>
  92         <hr/>
  93         <div class="refsect2" lang="en"><h3><a name="xmlStreamCtxt">Structure </a>xmlStreamCtxt</h3><pre class="programlisting">struct _xmlStreamCtxt {
  94 The content of this structure is not made public by the API.
  95 } xmlStreamCtxt;
  96 </pre><p/>
  97 </div>
  98         <hr/>
  99         <div class="refsect2" lang="en"><h3><a name="xmlStreamCtxtPtr">Typedef </a>xmlStreamCtxtPtr</h3><pre class="programlisting"><a href="libxml2-pattern.html#xmlStreamCtxt">xmlStreamCtxt</a> * xmlStreamCtxtPtr;
 100 </pre><p/>
 101 </div>
 102         <hr/>
 103         <div class="refsect2" lang="en"><h3><a name="xmlFreePattern"/>xmlFreePattern ()</h3><pre class="programlisting">void    xmlFreePattern                  (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br/>
 104 </pre><p>Free up the memory allocated by @comp</p>
 105 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>comp</tt></i>:</span></td><td>an XSLT comp</td></tr></tbody></table></div></div>
 106         <hr/>
 107         <div class="refsect2" lang="en"><h3><a name="xmlFreePatternList"/>xmlFreePatternList ()</h3><pre class="programlisting">void    xmlFreePatternList              (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br/>
 108 </pre><p>Free up the memory allocated by all the elements of @comp</p>
 109 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>comp</tt></i>:</span></td><td>an XSLT comp list</td></tr></tbody></table></div></div>
 110         <hr/>
 111         <div class="refsect2" lang="en"><h3><a name="xmlFreeStreamCtxt"/>xmlFreeStreamCtxt ()</h3><pre class="programlisting">void      xmlFreeStreamCtxt               (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream)<br/>
 112 </pre><p>Free the stream context</p>
 113 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>stream</tt></i>:</span></td><td>the stream context</td></tr></tbody></table></div></div>
 114         <hr/>
 115         <div class="refsect2" lang="en"><h3><a name="xmlPatternFromRoot"/>xmlPatternFromRoot ()</h3><pre class="programlisting">int     xmlPatternFromRoot              (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br/>
 116 </pre><p>Check if the pattern must be looked at from the root.</p>
 117 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>comp</tt></i>:</span></td><td>the precompiled pattern</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>1 if true, 0 if false and -1 in case of error</td></tr></tbody></table></div></div>
 118         <hr/>
 119         <div class="refsect2" lang="en"><h3><a name="xmlPatternGetStreamCtxt"/>xmlPatternGetStreamCtxt ()</h3><pre class="programlisting"><a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a>  xmlPatternGetStreamCtxt (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br/>
 120 </pre><p>Get a streaming context for that pattern Use <a href="libxml2-pattern.html#xmlFreeStreamCtxt">xmlFreeStreamCtxt</a> to free the context.</p>
 121 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>comp</tt></i>:</span></td><td>the precompiled pattern</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>a pointer to the context or NULL in case of failure</td></tr></tbody></table></div></div>
 122         <hr/>
 123         <div class="refsect2" lang="en"><h3><a name="xmlPatternMatch"/>xmlPatternMatch ()</h3><pre class="programlisting">int   xmlPatternMatch                 (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp, <br/>                                      <a href="libxml2-tree.html#xmlNodePtr">xmlNodePtr</a> node)<br/>
 124 </pre><p>Test whether the node matches the pattern</p>
 125 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>comp</tt></i>:</span></td><td>the precompiled pattern</td></tr><tr><td><span class="term"><i><tt>node</tt></i>:</span></td><td>a node</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>1 if it matches, 0 if it doesn't and -1 in case of failure</td></tr></tbody></table></div></div>
 126         <hr/>
 127         <div class="refsect2" lang="en"><h3><a name="xmlPatternMaxDepth"/>xmlPatternMaxDepth ()</h3><pre class="programlisting">int     xmlPatternMaxDepth              (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br/>
 128 </pre><p>Check the maximum depth reachable by a pattern</p>
 129 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>comp</tt></i>:</span></td><td>the precompiled pattern</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>-2 if no limit (using //), otherwise the depth, and -1 in case of error</td></tr></tbody></table></div></div>
 130         <hr/>
 131         <div class="refsect2" lang="en"><h3><a name="xmlPatternMinDepth"/>xmlPatternMinDepth ()</h3><pre class="programlisting">int     xmlPatternMinDepth              (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br/>
 132 </pre><p>Check the minimum depth reachable by a pattern, 0 mean the / or . are part of the set.</p>
 133 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>comp</tt></i>:</span></td><td>the precompiled pattern</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>-1 in case of error otherwise the depth,</td></tr></tbody></table></div></div>
 134         <hr/>
 135         <div class="refsect2" lang="en"><h3><a name="xmlPatternStreamable"/>xmlPatternStreamable ()</h3><pre class="programlisting">int xmlPatternStreamable            (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br/>
 136 </pre><p>Check if the pattern is streamable i.e. xmlPatternGetStreamCtxt() should work.</p>
 137 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>comp</tt></i>:</span></td><td>the precompiled pattern</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>1 if streamable, 0 if not and -1 in case of error.</td></tr></tbody></table></div></div>
 138         <hr/>
 139         <div class="refsect2" lang="en"><h3><a name="xmlPatterncompile"/>xmlPatterncompile ()</h3><pre class="programlisting"><a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a>    xmlPatterncompile       (const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * pattern, <br/>                                     <a href="libxml2-dict.html#xmlDict">xmlDict</a> * dict, <br/>                                   int flags, <br/>                                        const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> ** namespaces)<br/>
 140 </pre><p>Compile a pattern.</p>
 141 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>pattern</tt></i>:</span></td><td>the pattern to compile</td></tr><tr><td><span class="term"><i><tt>dict</tt></i>:</span></td><td>an optional dictionary for interned strings</td></tr><tr><td><span class="term"><i><tt>flags</tt></i>:</span></td><td>compilation flags, see <a href="libxml2-pattern.html#xmlPatternFlags">xmlPatternFlags</a></td></tr><tr><td><span class="term"><i><tt>namespaces</tt></i>:</span></td><td>the prefix definitions, array of [URI, prefix] or NULL</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>the compiled form of the pattern or NULL in case of error</td></tr></tbody></table></div></div>
 142         <hr/>
 143         <div class="refsect2" lang="en"><h3><a name="xmlStreamPop"/>xmlStreamPop ()</h3><pre class="programlisting">int xmlStreamPop                    (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream)<br/>
 144 </pre><p>push one level from the stream.</p>
 145 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>stream</tt></i>:</span></td><td>the stream context</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>-1 in case of error, 0 otherwise.</td></tr></tbody></table></div></div>
 146         <hr/>
 147         <div class="refsect2" lang="en"><h3><a name="xmlStreamPush"/>xmlStreamPush ()</h3><pre class="programlisting">int       xmlStreamPush                   (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream, <br/>                                      const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * name, <br/>                                        const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * ns)<br/>
 148 </pre><p>Push new data onto the stream. NOTE: if the call xmlPatterncompile() indicated a dictionary, then strings for name and ns will be expected to come from the dictionary. Both @name and @ns being NULL means the / i.e. the root of the document. This can also act as a reset. Otherwise the function will act as if it has been given an element-node.</p>
 149 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>stream</tt></i>:</span></td><td>the stream context</td></tr><tr><td><span class="term"><i><tt>name</tt></i>:</span></td><td>the current name</td></tr><tr><td><span class="term"><i><tt>ns</tt></i>:</span></td><td>the namespace name</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>-1 in case of error, 1 if the current state in the stream is a match and 0 otherwise.</td></tr></tbody></table></div></div>
 150         <hr/>
 151         <div class="refsect2" lang="en"><h3><a name="xmlStreamPushAttr"/>xmlStreamPushAttr ()</h3><pre class="programlisting">int       xmlStreamPushAttr               (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream, <br/>                                      const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * name, <br/>                                        const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * ns)<br/>
 152 </pre><p>Push new <a href="libxml2-SAX.html#attribute">attribute</a> data onto the stream. NOTE: if the call xmlPatterncompile() indicated a dictionary, then strings for name and ns will be expected to come from the dictionary. Both @name and @ns being NULL means the / i.e. the root of the document. This can also act as a reset. Otherwise the function will act as if it has been given an attribute-node.</p>
 153 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>stream</tt></i>:</span></td><td>the stream context</td></tr><tr><td><span class="term"><i><tt>name</tt></i>:</span></td><td>the current name</td></tr><tr><td><span class="term"><i><tt>ns</tt></i>:</span></td><td>the namespace name</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>-1 in case of error, 1 if the current state in the stream is a match and 0 otherwise.</td></tr></tbody></table></div></div>
 154         <hr/>
 155         <div class="refsect2" lang="en"><h3><a name="xmlStreamPushNode"/>xmlStreamPushNode ()</h3><pre class="programlisting">int       xmlStreamPushNode               (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream, <br/>                                      const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * name, <br/>                                        const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * ns, <br/>                                  int nodeType)<br/>
 156 </pre><p>Push new data onto the stream. NOTE: if the call xmlPatterncompile() indicated a dictionary, then strings for name and ns will be expected to come from the dictionary. Both @name and @ns being NULL means the / i.e. the root of the document. This can also act as a reset. Different from xmlStreamPush() this function can be fed with nodes of type: element-, attribute-, text-, cdata-section-, comment- and processing-instruction-node.</p>
 157 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>stream</tt></i>:</span></td><td>the stream context</td></tr><tr><td><span class="term"><i><tt>name</tt></i>:</span></td><td>the current name</td></tr><tr><td><span class="term"><i><tt>ns</tt></i>:</span></td><td>the namespace name</td></tr><tr><td><span class="term"><i><tt>nodeType</tt></i>:</span></td><td>the type of the node being pushed</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>-1 in case of error, 1 if the current state in the stream is a match and 0 otherwise.</td></tr></tbody></table></div></div>
 158         <hr/>
 159         <div class="refsect2" lang="en"><h3><a name="xmlStreamWantsAnyNode"/>xmlStreamWantsAnyNode ()</h3><pre class="programlisting">int       xmlStreamWantsAnyNode           (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> streamCtxt)<br/>
 160 </pre><p>Query if the streaming pattern additionally needs to be fed with text-, cdata-section-, comment- and processing-instruction-nodes. If the result is 0 then only element-nodes and attribute-nodes need to be pushed.</p>
 161 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>streamCtxt</tt></i>:</span></td><td>the stream context</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>1 in case of need of nodes of the above described types, 0 otherwise. -1 on API errors.</td></tr></tbody></table></div></div>
 162         <hr/>
 163       </div>
 164     </div>
 165   </body>
 166 </html>