home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / perl5 / XML / Grove / Path.pm < prev    next >
Encoding:
Perl POD Document  |  1999-10-23  |  3.2 KB  |  133 lines

  1. #
  2. # Copyright (C) 1998, 1999 Ken MacLeod
  3. # XML::Grove::Path is free software; you can redistribute it
  4. # and/or modify it under the same terms as Perl itself.
  5. #
  6. # $Id: Path.pm,v 1.2 1999/08/17 15:01:28 kmacleod Exp $
  7. #
  8.  
  9. package XML::Grove::Path;
  10.  
  11. use XML::Grove;
  12. use XML::Grove::XPointer;
  13. use UNIVERSAL;
  14.  
  15. sub at_path {
  16.     my $element = shift;    # or Grove
  17.     my $path = shift;
  18.  
  19.     $path =~ s|^/*||;
  20.  
  21.     my @path = split('/', $path);
  22.  
  23.     return (_at_path ($element, [@path]));
  24. }
  25.  
  26. sub _at_path {
  27.     my $element = shift;    # or Grove
  28.     my $path = shift;
  29.     my $segment = shift @$path;
  30.  
  31.     # segment := [ type ] [ '[' index ']' ]
  32.     #
  33.     # strip off the first segment, finding the type and index
  34.     $segment =~ m|^
  35.                 ([^\[]+)?     # - look for an optional type
  36.                               #   by matching anything but '['
  37.                 (?:           # - don't backreference the literals
  38.                   \[          # - literal '['
  39.                     ([^\]]+)  # - index, any non-']' chars
  40.                   \]          # - literal ']'
  41.                 )?            # - the whole index is optional
  42.                |x;
  43.     my ($node_type, $instance, $match) = ($1, $2, $&);
  44.     # issues:
  45.     #   - should assert that no chars come after index and before next
  46.     #     segment or the end of the query string
  47.  
  48.     $instance = 1 if !defined $instance;
  49.  
  50.     my $object = $element->xp_child ($instance, $node_type);
  51.  
  52.     if ($#$path eq -1) {
  53.         return $object;
  54.     } elsif (!$object->isa('XML::Grove::Element')) {
  55.         # FIXME a location would be nice.
  56.         die "\`$match' doesn't exist or is not an element\n";
  57.     } else {
  58.         return (_at_path($object, $path));
  59.     }
  60. }
  61.  
  62. package XML::Grove::Document;
  63.  
  64. sub at_path {
  65.     goto &XML::Grove::Path::at_path;
  66. }
  67.  
  68. package XML::Grove::Element;
  69.  
  70. sub at_path {
  71.     goto &XML::Grove::Path::at_path;
  72. }
  73.  
  74. 1;
  75.  
  76. __END__
  77.  
  78. =head1 NAME
  79.  
  80. XML::Grove::Path - return the object at a path
  81.  
  82. =head1 SYNOPSIS
  83.  
  84.  use XML::Grove::Path;
  85.  
  86.  # Using at_path method on XML::Grove::Document or XML::Grove::Element:
  87.  $xml_obj = $grove_object->at_path("/some/path");
  88.  
  89.  # Using an XML::Grove::Path instance:
  90.  $pather = XML::Grove::Path->new();
  91.  $xml_obj = $pather->at_path($grove_object);
  92.  
  93. =head1 DESCRIPTION
  94.  
  95. C<XML::Grove::Path> returns XML objects located at paths.  Paths are
  96. strings of element names or XML object types seperated by slash ("/")
  97. characters.  Paths must always start at the grove object passed to
  98. `C<at_path()>'.  C<XML::Grove::Path> is B<not> XPath, but it should
  99. become obsolete when an XPath implementation is available.
  100.  
  101. Paths are like URLs
  102.  
  103.     /html/body/ul/li[4]
  104.     /html/body/#pi[2]
  105.  
  106. The path segments can be element names or object types, the objects
  107. types are named using:
  108.  
  109.     #element
  110.     #pi
  111.     #comment
  112.     #text
  113.     #cdata
  114.     #any
  115.  
  116. The `C<#any>' object type matches any type of object, it is
  117. essentially an index into the contents of the parent object.
  118.  
  119. The `C<#text>' object type treats text objects as if they are not
  120. normalized.  Two consecutive text objects are seperate text objects.
  121.  
  122. =head1 AUTHOR
  123.  
  124. Ken MacLeod, ken@bitsko.slc.ut.us
  125.  
  126. =head1 SEE ALSO
  127.  
  128. perl(1), XML::Grove(3)
  129.  
  130. Extensible Markup Language (XML) <http://www.w3c.org/XML>
  131.  
  132. =cut
  133.