local-lib5/lib/perl5/i486-linux-gnu-thread-multi/XML/LibXML/Pattern.pod

   1 =head1 NAME
   2
   3 XML::LibXML::Pattern - XML::LibXML::Pattern - interface to libxml2 XPath patterns
   4
   5 =head1 SYNOPSIS
   6
   7
   8
   9   use XML::LibXML;
  10   my $pattern = new XML::LibXML::Pattern('/x:html/x:body//x:div', { 'x' => 'http://www.w3.org/1999/xhtml' });
  11   # test a match on a XML::LibXML::Node $node
  12
  13   if ($pattern->matchesNode($node)) { ... }
  14
  15   # or on a XML::LibXML::Reader
  16
  17   if ($reader->matchesPattern($pattern)) { ... }
  18
  19   # or skip reading all nodes that do not match
  20
  21   print $reader->nodePath while $reader->nextPatternMatch($pattern);
  22
  23   $pattern = XML::LibXML::Pattern->new( pattern, { prefix => namespace_URI, ... } );
  24   $bool = $pattern->matchesNode($node);
  25
  26 =head1 DESCRIPTION
  27
  28 This is a perl interface to libxml2's pattern matching support I<<<<<< http://xmlsoft.org/html/libxml-pattern.html >>>>>>. This feature requires recent versions of libxml2.
  29
  30 Patterns are a small subset of XPath language, which is limitted to
  31 (disjunctions of) location paths involving the child and descendant axes in
  32 abbreviated form as described by the extended BNF given below:
  33
  34
  35
  36   Selector ::=     Path ( '|' Path )*
  37   Path     ::=     ('.//' | '//' | '/' )? Step ( '/' Step )*
  38   Step     ::=     '.' | NameTest
  39   NameTest ::=     QName | '*' | NCName ':' '*'
  40
  41 For readability, whitespace may be used in selector XPath expressions even
  42 though not explicitly allowed by the grammar: whitespace may be freely added
  43 within patterns before or after any token, where
  44
  45
  46
  47   token     ::=     '.' | '/' | '//' | '|' | NameTest
  48
  49 Note that no predicates or attribute tests are allowed.
  50
  51 Patterns are particularly useful for stream parsing provided via the C<<<<<< XML::LibXML::Reader >>>>>> interface.
  52
  53 =over 4
  54
  55 =item new()
  56
  57   $pattern = XML::LibXML::Pattern->new( pattern, { prefix => namespace_URI, ... } );
  58
  59 The constructor of a pattern takes a pattern expression (as described by the
  60 BNF grammar above) and an optional HASH reference mapping prefixes to namespace
  61 URIs. The method returns a compiled pattern object.
  62
  63 Note that if the document has a default namespace, it must still be given an
  64 prefix in order to be matched (as demanded by the XPath 1.0 specification). For
  65 example, to match an element C<<<<<< <a xmlns="http://foo.bar"</a> >>>>>>, one should use a pattern like this:
  66
  67
  68
  69   $pattern = XML::LibXML::Pattern->new( 'foo:a', { foo => 'http://foo.bar' });
  70
  71
  72 =item matchesNode($node)
  73
  74   $bool = $pattern->matchesNode($node);
  75
  76 Given a XML::LibXML::Node object, returns a true value if the node is matched
  77 by the compiled pattern expression.
  78
  79
  80
  81 =back
  82
  83
  84 =head1 SEE ALSO
  85
  86 L<<<<<< XML::LibXML::Reader >>>>>> for other methods involving compiled patterns.
  87
  88 =head1 AUTHORS
  89
  90 Matt Sergeant,
  91 Christian Glahn,
  92 Petr Pajas
  93
  94
  95 =head1 VERSION
  96
  97 1.70
  98
  99 =head1 COPYRIGHT
 100
 101 2001-2007, AxKit.com Ltd.
 102
 103 2002-2006, Christian Glahn.
 104
 105 2006-2009, Petr Pajas.
 106
 107 =cut