1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>pattern: pattern expression handling</title> 5<meta name="generator" content="Libxml2 devhelp stylesheet"> 6<link rel="start" href="index.html" title="libxml2 Reference Manual"> 7<link rel="up" href="general.html" title="API"> 8<link rel="stylesheet" href="style.css" type="text/css"> 9<link rel="chapter" href="general.html" title="API"> 10</head> 11<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 12<table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"> 13<td><a accesskey="p" href="libxml2-parserInternals.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td> 14<td><a accesskey="u" href="general.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td> 15<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td> 16<td><a accesskey="n" href="libxml2-relaxng.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td> 17<th width="100%" align="center">libxml2 Reference Manual</th> 18</tr></table> 19<h2><span class="refentrytitle">pattern</span></h2> 20<p>pattern - pattern expression handling</p> 21<p>allows to compile and test pattern expressions for nodes either in a tree or based on a parser state. </p> 22<p>Author(s): Daniel Veillard </p> 23<div class="refsynopsisdiv"> 24<h2>Synopsis</h2> 25<pre class="synopsis">typedef struct _xmlPattern <a href="#xmlPattern">xmlPattern</a>; 26typedef enum <a href="#xmlPatternFlags">xmlPatternFlags</a>; 27typedef <a href="libxml2-pattern.html#xmlPattern">xmlPattern</a> * <a href="#xmlPatternPtr">xmlPatternPtr</a>; 28typedef struct _xmlStreamCtxt <a href="#xmlStreamCtxt">xmlStreamCtxt</a>; 29typedef <a href="libxml2-pattern.html#xmlStreamCtxt">xmlStreamCtxt</a> * <a href="#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a>; 30void <a href="#xmlFreePattern">xmlFreePattern</a> (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp); 31void <a href="#xmlFreePatternList">xmlFreePatternList</a> (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp); 32void <a href="#xmlFreeStreamCtxt">xmlFreeStreamCtxt</a> (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream); 33int <a href="#xmlPatternFromRoot">xmlPatternFromRoot</a> (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp); 34<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> <a href="#xmlPatternGetStreamCtxt">xmlPatternGetStreamCtxt</a> (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp); 35int <a href="#xmlPatternMatch">xmlPatternMatch</a> (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp, <br> <a href="libxml2-tree.html#xmlNodePtr">xmlNodePtr</a> node); 36int <a href="#xmlPatternMaxDepth">xmlPatternMaxDepth</a> (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp); 37int <a href="#xmlPatternMinDepth">xmlPatternMinDepth</a> (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp); 38int <a href="#xmlPatternStreamable">xmlPatternStreamable</a> (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp); 39<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); 40int <a href="#xmlStreamPop">xmlStreamPop</a> (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream); 41int <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); 42int <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); 43int <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); 44int <a href="#xmlStreamWantsAnyNode">xmlStreamWantsAnyNode</a> (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> streamCtxt); 45</pre> 46</div> 47<div class="refsect1" lang="en"><h2>Description</h2></div> 48<div class="refsect1" lang="en"> 49<h2>Details</h2> 50<div class="refsect2" lang="en"> 51<div class="refsect2" lang="en"> 52<h3> 53<a name="xmlPattern">Structure </a>xmlPattern</h3> 54<pre class="programlisting">struct _xmlPattern { 55The content of this structure is not made public by the API. 56} xmlPattern; 57</pre> 58<p></p> 59</div> 60<hr> 61<div class="refsect2" lang="en"> 62<h3> 63<a name="xmlPatternFlags">Enum </a>xmlPatternFlags</h3> 64<pre class="programlisting">enum <a href="#xmlPatternFlags">xmlPatternFlags</a> { 65 <a name="XML_PATTERN_DEFAULT">XML_PATTERN_DEFAULT</a> = 0 /* simple pattern match */ 66 <a name="XML_PATTERN_XPATH">XML_PATTERN_XPATH</a> = 1 /* standard XPath pattern */ 67 <a name="XML_PATTERN_XSSEL">XML_PATTERN_XSSEL</a> = 2 /* XPath subset for schema selector */ 68 <a name="XML_PATTERN_XSFIELD">XML_PATTERN_XSFIELD</a> = 4 /* XPath subset for schema field */ 69}; 70</pre> 71<p></p> 72</div> 73<hr> 74<div class="refsect2" lang="en"> 75<h3> 76<a name="xmlPatternPtr">Typedef </a>xmlPatternPtr</h3> 77<pre class="programlisting"><a href="libxml2-pattern.html#xmlPattern">xmlPattern</a> * xmlPatternPtr; 78</pre> 79<p></p> 80</div> 81<hr> 82<div class="refsect2" lang="en"> 83<h3> 84<a name="xmlStreamCtxt">Structure </a>xmlStreamCtxt</h3> 85<pre class="programlisting">struct _xmlStreamCtxt { 86The content of this structure is not made public by the API. 87} xmlStreamCtxt; 88</pre> 89<p></p> 90</div> 91<hr> 92<div class="refsect2" lang="en"> 93<h3> 94<a name="xmlStreamCtxtPtr">Typedef </a>xmlStreamCtxtPtr</h3> 95<pre class="programlisting"><a href="libxml2-pattern.html#xmlStreamCtxt">xmlStreamCtxt</a> * xmlStreamCtxtPtr; 96</pre> 97<p></p> 98</div> 99<hr> 100<div class="refsect2" lang="en"> 101<h3> 102<a name="xmlFreePattern"></a>xmlFreePattern ()</h3> 103<pre class="programlisting">void xmlFreePattern (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br> 104</pre> 105<p>Free up the memory allocated by @comp</p> 106<div class="variablelist"><table border="0"> 107<col align="left"> 108<tbody><tr> 109<td><span class="term"><i><tt>comp</tt></i>:</span></td> 110<td>an XSLT comp</td> 111</tr></tbody> 112</table></div> 113</div> 114<hr> 115<div class="refsect2" lang="en"> 116<h3> 117<a name="xmlFreePatternList"></a>xmlFreePatternList ()</h3> 118<pre class="programlisting">void xmlFreePatternList (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br> 119</pre> 120<p>Free up the memory allocated by all the elements of @comp</p> 121<div class="variablelist"><table border="0"> 122<col align="left"> 123<tbody><tr> 124<td><span class="term"><i><tt>comp</tt></i>:</span></td> 125<td>an XSLT comp list</td> 126</tr></tbody> 127</table></div> 128</div> 129<hr> 130<div class="refsect2" lang="en"> 131<h3> 132<a name="xmlFreeStreamCtxt"></a>xmlFreeStreamCtxt ()</h3> 133<pre class="programlisting">void xmlFreeStreamCtxt (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream)<br> 134</pre> 135<p>Free the stream context</p> 136<div class="variablelist"><table border="0"> 137<col align="left"> 138<tbody><tr> 139<td><span class="term"><i><tt>stream</tt></i>:</span></td> 140<td>the stream context</td> 141</tr></tbody> 142</table></div> 143</div> 144<hr> 145<div class="refsect2" lang="en"> 146<h3> 147<a name="xmlPatternFromRoot"></a>xmlPatternFromRoot ()</h3> 148<pre class="programlisting">int xmlPatternFromRoot (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br> 149</pre> 150<p>Check if the pattern must be looked at from the root.</p> 151<div class="variablelist"><table border="0"> 152<col align="left"> 153<tbody> 154<tr> 155<td><span class="term"><i><tt>comp</tt></i>:</span></td> 156<td>the precompiled pattern</td> 157</tr> 158<tr> 159<td><span class="term"><i><tt>Returns</tt></i>:</span></td> 160<td>1 if true, 0 if false and -1 in case of error</td> 161</tr> 162</tbody> 163</table></div> 164</div> 165<hr> 166<div class="refsect2" lang="en"> 167<h3> 168<a name="xmlPatternGetStreamCtxt"></a>xmlPatternGetStreamCtxt ()</h3> 169<pre class="programlisting"><a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> xmlPatternGetStreamCtxt (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br> 170</pre> 171<p>Get a streaming context for that pattern Use <a href="libxml2-pattern.html#xmlFreeStreamCtxt">xmlFreeStreamCtxt</a> to free the context.</p> 172<div class="variablelist"><table border="0"> 173<col align="left"> 174<tbody> 175<tr> 176<td><span class="term"><i><tt>comp</tt></i>:</span></td> 177<td>the precompiled pattern</td> 178</tr> 179<tr> 180<td><span class="term"><i><tt>Returns</tt></i>:</span></td> 181<td>a pointer to the context or NULL in case of failure</td> 182</tr> 183</tbody> 184</table></div> 185</div> 186<hr> 187<div class="refsect2" lang="en"> 188<h3> 189<a name="xmlPatternMatch"></a>xmlPatternMatch ()</h3> 190<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> 191</pre> 192<p>Test whether the node matches the pattern</p> 193<div class="variablelist"><table border="0"> 194<col align="left"> 195<tbody> 196<tr> 197<td><span class="term"><i><tt>comp</tt></i>:</span></td> 198<td>the precompiled pattern</td> 199</tr> 200<tr> 201<td><span class="term"><i><tt>node</tt></i>:</span></td> 202<td>a node</td> 203</tr> 204<tr> 205<td><span class="term"><i><tt>Returns</tt></i>:</span></td> 206<td>1 if it matches, 0 if it doesn't and -1 in case of failure</td> 207</tr> 208</tbody> 209</table></div> 210</div> 211<hr> 212<div class="refsect2" lang="en"> 213<h3> 214<a name="xmlPatternMaxDepth"></a>xmlPatternMaxDepth ()</h3> 215<pre class="programlisting">int xmlPatternMaxDepth (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br> 216</pre> 217<p>Check the maximum depth reachable by a pattern</p> 218<div class="variablelist"><table border="0"> 219<col align="left"> 220<tbody> 221<tr> 222<td><span class="term"><i><tt>comp</tt></i>:</span></td> 223<td>the precompiled pattern</td> 224</tr> 225<tr> 226<td><span class="term"><i><tt>Returns</tt></i>:</span></td> 227<td>-2 if no limit (using //), otherwise the depth, and -1 in case of error</td> 228</tr> 229</tbody> 230</table></div> 231</div> 232<hr> 233<div class="refsect2" lang="en"> 234<h3> 235<a name="xmlPatternMinDepth"></a>xmlPatternMinDepth ()</h3> 236<pre class="programlisting">int xmlPatternMinDepth (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br> 237</pre> 238<p>Check the minimum depth reachable by a pattern, 0 mean the / or . are part of the set.</p> 239<div class="variablelist"><table border="0"> 240<col align="left"> 241<tbody> 242<tr> 243<td><span class="term"><i><tt>comp</tt></i>:</span></td> 244<td>the precompiled pattern</td> 245</tr> 246<tr> 247<td><span class="term"><i><tt>Returns</tt></i>:</span></td> 248<td>-1 in case of error otherwise the depth,</td> 249</tr> 250</tbody> 251</table></div> 252</div> 253<hr> 254<div class="refsect2" lang="en"> 255<h3> 256<a name="xmlPatternStreamable"></a>xmlPatternStreamable ()</h3> 257<pre class="programlisting">int xmlPatternStreamable (<a href="libxml2-pattern.html#xmlPatternPtr">xmlPatternPtr</a> comp)<br> 258</pre> 259<p>Check if the pattern is streamable i.e. xmlPatternGetStreamCtxt() should work.</p> 260<div class="variablelist"><table border="0"> 261<col align="left"> 262<tbody> 263<tr> 264<td><span class="term"><i><tt>comp</tt></i>:</span></td> 265<td>the precompiled pattern</td> 266</tr> 267<tr> 268<td><span class="term"><i><tt>Returns</tt></i>:</span></td> 269<td>1 if streamable, 0 if not and -1 in case of error.</td> 270</tr> 271</tbody> 272</table></div> 273</div> 274<hr> 275<div class="refsect2" lang="en"> 276<h3> 277<a name="xmlPatterncompile"></a>xmlPatterncompile ()</h3> 278<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> 279</pre> 280<p>Compile a pattern.</p> 281<div class="variablelist"><table border="0"> 282<col align="left"> 283<tbody> 284<tr> 285<td><span class="term"><i><tt>pattern</tt></i>:</span></td> 286<td>the pattern to compile</td> 287</tr> 288<tr> 289<td><span class="term"><i><tt>dict</tt></i>:</span></td> 290<td>an optional dictionary for interned strings</td> 291</tr> 292<tr> 293<td><span class="term"><i><tt>flags</tt></i>:</span></td> 294<td>compilation flags, see <a href="libxml2-pattern.html#xmlPatternFlags">xmlPatternFlags</a> 295</td> 296</tr> 297<tr> 298<td><span class="term"><i><tt>namespaces</tt></i>:</span></td> 299<td>the prefix definitions, array of [URI, prefix] or NULL</td> 300</tr> 301<tr> 302<td><span class="term"><i><tt>Returns</tt></i>:</span></td> 303<td>the compiled form of the pattern or NULL in case of error</td> 304</tr> 305</tbody> 306</table></div> 307</div> 308<hr> 309<div class="refsect2" lang="en"> 310<h3> 311<a name="xmlStreamPop"></a>xmlStreamPop ()</h3> 312<pre class="programlisting">int xmlStreamPop (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> stream)<br> 313</pre> 314<p>push one level from the stream.</p> 315<div class="variablelist"><table border="0"> 316<col align="left"> 317<tbody> 318<tr> 319<td><span class="term"><i><tt>stream</tt></i>:</span></td> 320<td>the stream context</td> 321</tr> 322<tr> 323<td><span class="term"><i><tt>Returns</tt></i>:</span></td> 324<td>-1 in case of error, 0 otherwise.</td> 325</tr> 326</tbody> 327</table></div> 328</div> 329<hr> 330<div class="refsect2" lang="en"> 331<h3> 332<a name="xmlStreamPush"></a>xmlStreamPush ()</h3> 333<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> 334</pre> 335<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> 336<div class="variablelist"><table border="0"> 337<col align="left"> 338<tbody> 339<tr> 340<td><span class="term"><i><tt>stream</tt></i>:</span></td> 341<td>the stream context</td> 342</tr> 343<tr> 344<td><span class="term"><i><tt>name</tt></i>:</span></td> 345<td>the current name</td> 346</tr> 347<tr> 348<td><span class="term"><i><tt>ns</tt></i>:</span></td> 349<td>the namespace name</td> 350</tr> 351<tr> 352<td><span class="term"><i><tt>Returns</tt></i>:</span></td> 353<td>-1 in case of error, 1 if the current state in the stream is a match and 0 otherwise.</td> 354</tr> 355</tbody> 356</table></div> 357</div> 358<hr> 359<div class="refsect2" lang="en"> 360<h3> 361<a name="xmlStreamPushAttr"></a>xmlStreamPushAttr ()</h3> 362<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> 363</pre> 364<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> 365<div class="variablelist"><table border="0"> 366<col align="left"> 367<tbody> 368<tr> 369<td><span class="term"><i><tt>stream</tt></i>:</span></td> 370<td>the stream context</td> 371</tr> 372<tr> 373<td><span class="term"><i><tt>name</tt></i>:</span></td> 374<td>the current name</td> 375</tr> 376<tr> 377<td><span class="term"><i><tt>ns</tt></i>:</span></td> 378<td>the namespace name</td> 379</tr> 380<tr> 381<td><span class="term"><i><tt>Returns</tt></i>:</span></td> 382<td>-1 in case of error, 1 if the current state in the stream is a match and 0 otherwise.</td> 383</tr> 384</tbody> 385</table></div> 386</div> 387<hr> 388<div class="refsect2" lang="en"> 389<h3> 390<a name="xmlStreamPushNode"></a>xmlStreamPushNode ()</h3> 391<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> 392</pre> 393<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> 394<div class="variablelist"><table border="0"> 395<col align="left"> 396<tbody> 397<tr> 398<td><span class="term"><i><tt>stream</tt></i>:</span></td> 399<td>the stream context</td> 400</tr> 401<tr> 402<td><span class="term"><i><tt>name</tt></i>:</span></td> 403<td>the current name</td> 404</tr> 405<tr> 406<td><span class="term"><i><tt>ns</tt></i>:</span></td> 407<td>the namespace name</td> 408</tr> 409<tr> 410<td><span class="term"><i><tt>nodeType</tt></i>:</span></td> 411<td>the type of the node being pushed</td> 412</tr> 413<tr> 414<td><span class="term"><i><tt>Returns</tt></i>:</span></td> 415<td>-1 in case of error, 1 if the current state in the stream is a match and 0 otherwise.</td> 416</tr> 417</tbody> 418</table></div> 419</div> 420<hr> 421<div class="refsect2" lang="en"> 422<h3> 423<a name="xmlStreamWantsAnyNode"></a>xmlStreamWantsAnyNode ()</h3> 424<pre class="programlisting">int xmlStreamWantsAnyNode (<a href="libxml2-pattern.html#xmlStreamCtxtPtr">xmlStreamCtxtPtr</a> streamCtxt)<br> 425</pre> 426<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> 427<div class="variablelist"><table border="0"> 428<col align="left"> 429<tbody> 430<tr> 431<td><span class="term"><i><tt>streamCtxt</tt></i>:</span></td> 432<td>the stream context</td> 433</tr> 434<tr> 435<td><span class="term"><i><tt>Returns</tt></i>:</span></td> 436<td>1 in case of need of nodes of the above described types, 0 otherwise. -1 on API errors.</td> 437</tr> 438</tbody> 439</table></div> 440</div> 441<hr> 442</div> 443</div> 444</body> 445</html> 446
