home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _e5404645fd476405ce0c5065097337fb < prev    next >
Text File  |  2000-03-15  |  7KB  |  233 lines
  1. package XML::Element;
  2. use vars qw( $VERSION );
  3.  
  4. #
  5. # XML::Element
  6. #
  7. # Base class for XML Elements.  Provides the ability to output the XML document
  8. # once it's been parsed using the XML::Parser module.
  9. #
  10. ###############################################################################
  11. $VERSION = do { my @r = q$Revision: 1.7 $ =~ /\d+/g; sprintf '%d.'.'%02d'x$#r, @r };
  12.  
  13. ###############################################################################
  14. # Required inclusions.
  15. ###############################################################################
  16. use HTML::Entities;                     # Needed for escaping char entities
  17.  
  18. ###############################################################################
  19. # Allow for creation via 'new'.
  20. ###############################################################################
  21. sub new
  22. {
  23.     my ($class, %args) = @_;
  24.     bless \%args, $class;
  25. }
  26.  
  27. ###############################################################################
  28. # Subroutine:   output
  29. ###############################################################################
  30. # Outputs the entire XML document on the currently selected filehandle.
  31. ###############################################################################
  32. sub output
  33. {
  34.     my $self = shift;
  35.     print $self->as_text();
  36. }
  37.  
  38. ###############################################################################
  39. # Subroutine:   content
  40. ###############################################################################
  41. # Returns a string containing all of the content of this element.
  42. ###############################################################################
  43. sub content
  44. {
  45.     my $self = shift;
  46.     my @kids = @{ $self->{'Kids'} };
  47.     my $text;
  48.  
  49.     if (@kids > 0)
  50.     {
  51.         foreach (@kids)
  52.         {
  53.             # Allow for outputting of char data
  54.             if ((ref $_) =~ /::Characters$/o)
  55.                 { $text .= encode_entities( $_->{'Text'} ); }
  56.             else
  57.                 { $text .= $_->as_text(); }
  58.         }
  59.     }
  60.  
  61.     return $text;
  62. }
  63.  
  64. ###############################################################################
  65. # Subroutine:   add_child ($elemref)
  66. ###############################################################################
  67. # Adds a new child element to ourselves.
  68. ###############################################################################
  69. sub add_child (\$)
  70. {
  71.     my $self    = shift;
  72.     my $elemref = shift;
  73.     push( @{$self->{'Kids'}}, $elemref );
  74. }
  75.  
  76. ###############################################################################
  77. # Subroutine:   remove_child ($elemref)
  78. ###############################################################################
  79. # Removes a child element from ourselves.  Returns non-zero if it was able to
  80. # remove the child element, and zero if it was unable to do so.
  81. ###############################################################################
  82. sub remove_child
  83. {
  84.     my $self    = shift;
  85.     my $elemref = shift;
  86.  
  87.     foreach my $idx (0 .. @{$self->{'Kids'}})
  88.     {
  89.         if ($self->{'Kids'}[$idx] == $elemref)
  90.         {
  91.             splice( @{$self->{'Kids'}}, $idx, 1 );
  92.             return 1;
  93.         }
  94.     }
  95.  
  96.     return 0;
  97. }
  98.  
  99. ###############################################################################
  100. # Subroutine:   add_text ($text)
  101. ###############################################################################
  102. # Adds character data to the given element.  Returns undef if unable to add the
  103. # text to this element, and returns a reference to the character data element
  104. # if successful.
  105. ###############################################################################
  106. sub add_text
  107. {
  108.     my $self = shift;
  109.     my $text = shift;
  110.  
  111.     return if (!defined $text);
  112.  
  113.     my $type = ref $self;                   # Do package name magic
  114.     $type =~ s/::[^:]+?$/::Characters/o;
  115.  
  116.     my $elem = new $type;
  117.     $elem->{'Text'} = $text;
  118.     $self->add_child( $elem );
  119.     return $elem;
  120. }
  121.  
  122. ###############################################################################
  123. # Subroutine:   as_text
  124. ###############################################################################
  125. # Returns a string containing the entire XML document.
  126. ###############################################################################
  127. sub as_text
  128. {
  129.     my $self = shift;
  130.     my $text;
  131.  
  132.     my $type = ref $self;
  133.     $type =~ s/.*:://;
  134.  
  135.     $text = '<' . $type;
  136.     foreach (sort keys %{$self})
  137.     {
  138.         if ($_ !~ /Text|Kids/)
  139.             { $text .= " $_=\"" . $self->{$_} . '"'; }
  140.     }
  141.  
  142.     my $cont = $self->content();
  143.     if (defined $cont)
  144.         { $text .= '>' . $cont . '</' . $type . '>'; }
  145.     else
  146.         { $text .= ' />'; }
  147.  
  148.     return $text;
  149. }
  150.  
  151. __END__
  152.  
  153. ###############################################################################
  154. # PPD Documentation
  155. ###############################################################################
  156.  
  157. =head1 NAME
  158.  
  159. XML::Element - Base element class for XML elements
  160.  
  161. =head1 SYNOPSIS
  162.  
  163.  use XML::Element;
  164.  @ISA = qw( XML::Element );
  165.  
  166. =head1 DESCRIPTION
  167.  
  168. Base element class for XML elements.  To be derived from to create your own
  169. elements for use with the XML::Parser module.  Supports output of empty
  170. elements using <.... />.
  171.  
  172. It is recommended that you use a
  173. version of the XML::Parser module which includes support for Styles; by
  174. deriving your own elements from XML::Element and using the 'Objects' style it
  175. becomes B<much> easier to create your own parser.
  176.  
  177. =head1 METHODS
  178.  
  179. =over 4
  180.  
  181. =item add_text ($text)
  182.  
  183. Adds character data to the end of the element.  The element created is placed
  184. within the same package space as the element it was created under (e.g. adding
  185. text to a XML::Foobar::Stuff element would put the character data into an
  186. XML::Foobar::Characters element).  If successful, this method returns a
  187. reference to the newly created element.
  188.  
  189. =item as_text
  190.  
  191. Returns a string value containing the entire XML document from this element on
  192. down.
  193.  
  194. =item content
  195.  
  196. Returns a string value containing the entire content of this XML element.  Note
  197. that this is quite similar to the C<as_text()> method except that it does not
  198. include any information about this element in particular.
  199.  
  200. =item output
  201.  
  202. Recursively outputs the structure of the XML document from this element on
  203. down.
  204.  
  205. =item add_child ($elemref)
  206.  
  207. Adds the child element to the list of children for this element.  Note that the
  208. element given must be a reference to an object derived from C<XML::Element>.
  209.  
  210. =item remove_child ($elemref)
  211.  
  212. Removes the given child element from the list of children for this element.
  213. This method returns non-zero if it is able to locate and remove the child
  214. element, returning zero if it is unable to do so.
  215.  
  216. =back
  217.  
  218. =head1 LIMITATIONS
  219.  
  220. The C<XML::Element> module has no provisions for outputting processor
  221. directives or external entities.  It only outputs child elements and any
  222. character data which the elements may contain.
  223.  
  224. =head1 AUTHORS
  225.  
  226. Graham TerMarsch <gtermars@activestate.com>
  227.  
  228. =head1 SEE ALSO
  229.  
  230. L<XML::Parser>
  231.  
  232. =cut
  233.