This file is indexed.

/usr/share/perl5/XML/Grove.pm is in libxml-grove-perl 0.46alpha-12.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
#
# Copyright (C) 1998 Ken MacLeod
# XML::Grove is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
# $Id: Grove.pm,v 1.15 1999/08/17 15:01:28 kmacleod Exp $
#

use strict;
use 5.005;
use UNIVERSAL;
use Data::Grove;

package XML::Grove;
use vars qw{$VERSION @ISA};

$VERSION = '0.46alpha';

@ISA = qw{Data::Grove};

package XML::Grove::Document;
use vars qw{@ISA $type_name};
@ISA = qw{XML::Grove};

$type_name = 'document';

# Override methods that may be loaded from Data::Grove::Parent.  In
# XML::Grove, `root' and `rootpath' refer to the root _element_ of the
# grove, not the document that contains it.

# Note: this routine specifically sets $value and does last instead of
# returning $child immediately because there is a bug in Perl 5.005 that
# causes the returned value to disappear
sub root {
    my $self = shift;

    if (@_) {
	return $self->{Contents} = [ shift ];
    } else {
	my $value = undef;

	foreach my $child (@{$self->{Contents}}) {
	    if ($child->isa('XML::Grove::Element')) {
		$value = $child;
		last;
	    }
	}

	return $value;
    }
}

sub rootpath {
    return;
}

package XML::Grove::Element;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'element';

package XML::Grove::PI;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'pi';

package XML::Grove::Entity::External;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'external_entity';

package XML::Grove::Entity::SubDoc;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'subdoc_entity';

package XML::Grove::Entity::SGML;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'sgml_entity';

package XML::Grove::Entity;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'entity';

package XML::Grove::Notation;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'notation';

package XML::Grove::Comment;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'comment';

package XML::Grove::SubDoc;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'subdoc';

package XML::Grove::Characters;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'characters';

package XML::Grove::CData;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'cdata';

package XML::Grove::ElementDecl;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'element_decl';

package XML::Grove::AttListDecl;
use vars qw{ @ISA $type_name };
@ISA = qw{XML::Grove};
$type_name = 'attlist_decl';

1;

__END__

=head1 NAME

XML::Grove - Perl-style XML objects

=head1 SYNOPSIS

 use XML::Grove;

 # Basic parsing and grove building
 use XML::Grove::Builder;
 use XML::Parser::PerlSAX;
 $grove_builder = XML::Grove::Builder->new;
 $parser = XML::Parser::PerlSAX->new ( Handler => $grove_builder );
 $document = $parser->parse ( Source => { SystemId => 'filename' } );

 # Creating new objects
 $document = XML::Grove::Document->new ( Contents => [ ] );
 $element = XML::Grove::Element->new ( Name => 'tag',
                                       Attributes => { },
				       Contents => [ ] );

 # Accessing XML objects
 $tag_name = $element->{Name};
 $contents = $element->{Contents};
 $parent = $element->{Parent};
 $characters->{Data} = 'XML is fun!';

=head1 DESCRIPTION

XML::Grove is a tree-based object model for accessing the information
set of parsed or stored XML, HTML, or SGML instances.  XML::Grove
objects are Perl hashes and arrays where you access the properties of
the objects using normal Perl syntax:

  $text = $characters->{Data};

=head2 How To Create a Grove

There are several ways for groves to come into being, they can be read
from a file or string using a parser and a grove builder, they can be
created by your Perl code using the `C<new()>' methods of
XML::Grove::Objects, or databases or other sources can act as groves.

The most common way to build groves is using a parser and a grove
builder.  The parser is the package that reads the characters of an
XML file, recognizes the XML syntax, and produces ``events'' reporting
when elements (tags), text (characters), processing instructions, and
other sequences occur.  A grove builder receives (``consumes'' or
``handles'') these events and builds XML::Grove objects.  The last
thing the parser does is return the XML::Grove::Document object that
the grove builder created, with all of it's elements and character
data.

The most common parser and grove builder are XML::Parser::PerlSAX (in
libxml-perl) and XML::Grove::Builder.  To build a grove, create the
grove builder first:

  $grove_builder = XML::Grove::Builder->new;

Then create the parser, passing it the grove builder as it's handler:

  $parser = XML::Parser::PerlSAX->new ( Handler => $grove_builder );

This associates the grove builder with the parser so that every time
you parse a document with this parser it will return an
XML::Grove::Document object.  To parse a file, use the `C<Source>'
parameter to the `C<parse()>' method containing a `C<SystemId>'
parameter (URL or path) of the file you want to parse:

  $document = $parser->parse ( Source => { SystemId => 'kjv.xml' } );

To parse a string held in a Perl variable, use the `C<Source>'
parameter containing a `C<String>' parameter:

  $document = $parser->parse ( Source => { String => $xml_text } );

The following are all parsers that work with XML::Grove::Builder:

  XML::Parser::PerlSAX (in libxml-perl, uses XML::Parser)
  XML::ESISParser      (in libxml-perl, uses James Clark's `nsgmls')
  XML::SAX2Perl        (in libxml-perl, translates SAX 1.0 to PerlSAX)

Most parsers supply more properties than the standard information set
below and XML::Grove will make available all the properties given by
the parser, refer to the parser documentation to find out what
additional properties it may provide.

Although there are not any available yet (August 1999), PerlSAX filters
can be used to process the output of a parser before it is passed to
XML::Grove::Builder.  XML::Grove::PerlSAX can be used to provide input
to PerlSAX filters or other PerlSAX handlers.

=head2 Using Groves

The properties provided by parsers are available directly using Perl's
normal syntax for accessing hashes and arrays.  For example, to get
the name of an element:

  $element_name = $element->{Name};

By convention, all properties provided by parsers are in mixed case.
`C<Parent>' properties are available using the
`C<Data::Grove::Parent>' module.

The following is the minimal set of objects and their properties that
you are likely to get from all parsers:

=head2 XML::Grove::Document

The Document object is parent of the root element of the parsed XML
document.

=over 12

=item Contents

An array containing the root element.

=back

A document's `Contents' may also contain processing instructions,
comments, and whitespace.

Some parsers provide information about the document type, the XML
declaration, or notations and entities.  Check the parser
documentation for property names.

=head2 XML::Grove::Element

The Element object represents elements from the XML source.

=over 12

=item Parent

The parent object of this element.

=item Name

A string, the element type name of this element

=item Attributes

A hash of strings or arrays

=item Contents

An array of elements, characters, processing instructions, etc.

=back

In a purely minimal grove, the attributes of an element will be plain
text (Perl scalars).  Some parsers provide access to notations and
entities in attributes, in which case the attribute may contain an
array.

=head2 XML::Grove::Characters

The Characters object represents text from the XML source.

=over 12

=item Parent

The parent object of this characters object

=item Data

A string, the characters

=back

=head2 XML::Grove::PI

The PI object represents processing instructions from the XML source.

=over 12

=item Parent

The parent object of this PI object.

=item Target

A string, the processing instruction target.

=item Data

A string, the processing instruction data, or undef if none was supplied.

=back

In addition to the minimal set of objects above, XML::Grove knows
about and parsers may provide the following objects.  Refer to the
parser documentation for descriptions of the properties of these
objects.

  XML::Grove::
  ::Entity::External  External entity reference
  ::Entity::SubDoc    External SubDoc reference (SGML)
  ::Entity::SGML      External SGML reference (SGML)
  ::Entity            Entity reference
  ::Notation          Notation declaration
  ::Comment           <!-- A Comment -->
  ::SubDoc            A parsed subdocument (SGML)
  ::CData             A CDATA marked section
  ::ElementDecl       An element declaration from the DTD
  ::AttListDecl       An element's attribute declaration, from the DTD

=head1 METHODS

XML::Grove by itself only provides one method, new(), for creating new
XML::Grove objects.  There are Data::Grove and XML::Grove extension
modules that give additional methods for working with XML::Grove
objects and new extensions can be created as needed.

=over 4

=item $obj = XML::Grove::OBJECT->new( [PROPERTIES] )

`C<new>' creates a new XML::Grove object with the type I<OBJECT>, and
with the initial I<PROPERTIES>.  I<PROPERTIES> may be given as either
a list of key-value pairs, a hash, or an XML::Grove object to copy.
I<OBJECT> may be any of the objects listed above.

=back

This is a list of available extensions and the methods they provide
(as of Feb 1999).  Refer to their module documentation for more
information on how to use them.

  XML::Grove::AsString
    as_string       return portions of groves as a string
    attr_as_string  return an element's attribute as a string

  XML::Grove::AsCanonXML
    as_canon_xml    return XML text in canonical XML format

  XML::Grove::PerlSAX
    parse           emulate a PerlSAX parser using the grove objects

  Data::Grove::Parent
    root            return the root element of a grove
    rootpath        return an array of all objects between the root
                    element and this object, inclusive

    Data::Grove::Parent also adds `C<Parent>' and `C<Raw>' properties
    to grove objects.

  Data::Grove::Visitor
    accept          call back a subroutine using an object type name
    accept_name     call back using an element or tag name
    children_accept for each child in Contents, call back a sub
    children_accept_name  same, but using tag names
    attr_accept     call back for the objects in attributes

  XML::Grove::IDs
    get_ids         return a list of all ID attributes in grove

  XML::Grove::Path
    at_path         $el->at_path('/html/body/ul/li[4]')

  XML::Grove::Sub
    filter          run a sub against all the objects in the grove

=head1 WRITING EXTENSIONS

The class `C<XML::Grove>' is the superclass of all classes in the
XML::Grove module.  `C<XML::Grove>' is a subclass of `C<Data::Grove>'.

If you create an extension and you want to add a method to I<all>
XML::Grove objects, then create that method in the XML::Grove
package.  Many extensions only need to add methods to
XML::Grove::Document and/or XML::Grove::Element.

When you create an extension you should definitly provide a way to
invoke your module using objects from your package too.  For example,
XML::Grove::AsString's `C<as_string()>' method can also be called
using an XML::Grove::AsString object:

  $writer= new XML::Grove::AsString;
  $string = $writer->as_string ( $xml_object );

=head1 AUTHOR

Ken MacLeod, ken@bitsko.slc.ut.us

=head1 SEE ALSO

perl(1), XML::Grove(3)

Extensible Markup Language (XML) <http://www.w3c.org/XML>

=cut