home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / perl5 / XML / Grove / Factory.pm < prev    next >
Encoding:
Text File  |  1999-10-23  |  8.0 KB  |  333 lines

  1. #
  2. # Copyright (C) 1998, 1999 Ken MacLeod
  3. # XML::Grove::Factory is free software; you can redistribute it and/or
  4. # modify it under the same terms as Perl itself.
  5. #
  6. # $Id: Factory.pm,v 1.1 1999/09/03 21:41:00 kmacleod Exp $
  7. #
  8.  
  9. use strict;
  10.  
  11. package XML::Grove::Factory;
  12.  
  13. sub grove_factory {
  14.     my $type = shift;
  15.     my $self = ($#_ == 0) ? { %{ (shift) } } : { @_ };
  16.  
  17.     bless $self, $type;
  18.  
  19.     return $self;
  20. }
  21.  
  22. sub element_factory {
  23.     my $type = shift;
  24.     my $self = ($#_ == 0) ? { %{ (shift) } } : { @_ };
  25.  
  26.     bless $self, 'XML::Grove::Factory_';
  27.  
  28.     return $self;
  29. }
  30.  
  31. sub element_functions {
  32.     my $type = shift;
  33.     my $prefix = shift;
  34.  
  35.     my $package = caller;
  36.  
  37.     foreach my $name (@_) {
  38.     my $eval_str = <<'EOF;';
  39. package @PACKAGE@;
  40. sub @NAME@ {
  41.  
  42.     if (ref($_[0]) eq 'HASH') {
  43.     my $attributes = { %{(shift)} };
  44.     return XML::Grove::Element->new( Name => '@NAME@',
  45.                      Attributes => $attributes,
  46.                  Contents => XML::Grove::Factory::chars_(@_) );
  47.     } else {
  48.     return XML::Grove::Element->new( Name => '@NAME@',
  49.                  Contents => XML::Grove::Factory::chars_(@_) );
  50.     }
  51. }
  52. EOF;
  53.         $eval_str =~ s'@PACKAGE@'$package'ge;
  54.         $eval_str =~ s'@NAME@'$name'ge;
  55.         eval $eval_str;
  56.         die $@ if ($@);
  57.     }
  58. }
  59.  
  60. sub document {
  61.     my $self = shift;
  62.  
  63.     return XML::Grove::Document->new( Contents => chars_(@_) );
  64. }
  65.  
  66. sub element {
  67.     my $self = shift;
  68.     my $name = shift;
  69.  
  70.     if (ref($_[0]) eq 'HASH') {
  71.     my $attributes = { %{(shift)} };
  72.     return XML::Grove::Element->new( Name => $name,
  73.                      Attributes => $attributes,
  74.                      Contents => chars_(@_) );
  75.     } else {
  76.     return XML::Grove::Element->new( Name => $name,
  77.                      Contents => chars_(@_) );
  78.     }
  79. }
  80.  
  81. sub pi {
  82.     my $self = shift;
  83.     if ($#_ == 0) {
  84.     my $data = shift;
  85.     return XML::Grove::PI->new( Data => $data );
  86.     } else {
  87.     my $target = shift;
  88.     my $data = shift;
  89.     return XML::Grove::PI->new( Target => $target,
  90.                     Data => $data );
  91.     }
  92. }
  93.  
  94. sub comment {
  95.     my $self = shift;
  96.     my $comment = shift;
  97.  
  98.     return XML::Grove::Comment->new( Data => $comment );
  99. }
  100.  
  101. sub chars_ {
  102.     my $chars = [ ];
  103.     foreach my $obj (@_) {
  104.     if (ref $obj) {
  105.         push @$chars, $obj;
  106.     } else {
  107.         push @$chars, XML::Grove::Characters->new( Data => $obj );
  108.     }
  109.     }
  110.  
  111.     return $chars;
  112. }
  113.  
  114. package XML::Grove::Factory_;
  115. use vars qw{ $AUTOLOAD };
  116.  
  117. sub AUTOLOAD {
  118.     my $self = shift;
  119.  
  120.     my $name = $AUTOLOAD;
  121.     $name =~ s/.*:://;
  122.     return if $name eq 'DESTROY';
  123.  
  124.     if (ref($_[0]) eq 'HASH') {
  125.     my $attributes = { %{(shift)} };
  126.     return XML::Grove::Element->new( Name => $name,
  127.                      Attributes => $attributes,
  128.                  Contents => XML::Grove::Factory::chars_(@_) );
  129.     } else {
  130.     return XML::Grove::Element->new( Name => $name,
  131.                  Contents => XML::Grove::Factory::chars_(@_) );
  132.     }
  133. }
  134.  
  135. 1;
  136.  
  137. __END__
  138.  
  139. =head1 NAME
  140.  
  141. XML::Grove::Factory - simplify creation of XML::Grove objects
  142.  
  143. =head1 SYNOPSIS
  144.  
  145.  use XML::Grove::Factory;
  146.  
  147.  ### An object that creates Grove objects directly
  148.  my $gf = XML::Grove::Factory->grove_factory;
  149.  
  150.  $grove = $gf->document( CONTENTS );
  151.  $element = $gf->element( $name, { ATTRIBUTES }, CONTENTS );
  152.  $pi = $gf->pi( $target, $data );
  153.  $comment = $gf->comment( $data );
  154.  
  155.  ### An object that creates elements by method name
  156.  my $ef = XML::Grove::Factory->element_factory();
  157.  
  158.  $element = $ef->NAME( { ATTRIBUTES }, CONTENTS);
  159.  
  160.  ### Similar to `element_factory', but creates functions in the
  161.  ### current package
  162.  XML::Grove::Factory->element_functions( PREFIX, ELEMENTS );
  163.  
  164.  $element = NAME( { ATTRIBUTES }, CONTENTS );
  165.  
  166. =head1 DESCRIPTION
  167.  
  168. C<XML::Grove::Factory> provides objects or defines functions that let
  169. you simply and quickly create the most commonly used XML::Grove
  170. objects.  C<XML::Grove::Factory> supports three types of object
  171. creation.  The first type is to create raw XML::Grove objects.  The
  172. second type creates XML elements by element name.  The third type is
  173. like the second, but defines local functions for you to call instead
  174. of using an object, which might save typing in some cases.
  175.  
  176. The three types of factories can be mixed.  For example, you can use
  177. local functions for all element names that don't conflict with your
  178. own sub names or contain special characters, and then use a
  179. `C<grove_factory()>' object for those elements that do conflict.
  180.  
  181. In the examples that follow, each example is creating an XML instance
  182. similar to the following, assuming it's pretty printed:
  183.  
  184.     <?xml version="1.0"?>
  185.     <HTML>
  186.       <HEAD>
  187.         <TITLE>Some Title</TITLE>
  188.       </HEAD>
  189.       <BODY bgcolor="#FFFFFF">
  190.         <P>A paragraph.</P>
  191.       </BODY>
  192.     </HTML>
  193.   
  194.  
  195. =head1 GROVE FACTORY
  196.  
  197. =over 4
  198.  
  199. =item $gf = XML::Grove::Factory->grove_factory()
  200.  
  201. Creates a new grove factory object that creates raw XML::Grove
  202. objects.
  203.  
  204. =item $gf->document( I<CONTENTS> );
  205.  
  206. Creates an XML::Grove::Document object.  I<CONTENTS> may contain
  207. processing instructions, strings containing only whitespace
  208. characters, and a single element object (but note that there is no
  209. checking).  Strings are converted to XML::Grove::Characters objects.
  210.  
  211. =item $gf->element($name, I<CONTENTS>);
  212.  
  213. =item $gf->element($name, { I<ATTRIBUTES> }, I<CONTENTS>);
  214.  
  215. Creates an XML::Grove::Element object with the name `C<$name>'.  If
  216. the argument following `C<$name>' is an anonymous hash, I<ATTRIBUTES>,
  217. then they will be copied to the elements attributes.  I<CONTENTS> will
  218. be stored in the element's content (note that there is no validity
  219. checking).  Strings in I<CONTENTS> are converted to
  220. XML::Grove::Characters objects.
  221.  
  222. =item $gf->pi( I<TARGET>, I<DATA>)
  223.  
  224. =item $gf->pi( I<DATA> )
  225.  
  226. Create an XML::Grove::PI object with I<TARGET> and I<DATA>.
  227.  
  228. =item $gf->comment( I<DATA> )
  229.  
  230. Create an XML::Grove::Comment object with I<DATA>.
  231.  
  232. =back
  233.  
  234. =head2 GROVE FACTORY EXAMPLE
  235.  
  236.  use XML::Grove::Factory;
  237.  
  238.  $gf = XML::Grove::Factory->grove_factory;
  239.  
  240.  $element = 
  241.    $gf->element('HTML',
  242.      $gf->element('HEAD',
  243.        $gf->element('TITLE', 'Some Title')),
  244.      $gf->element('BODY', { bgcolor => '#FFFFFF' },
  245.        $gf->element('P', 'A paragraph.')));
  246.  
  247. =head1 ELEMENT FACTORY
  248.  
  249. =over 4
  250.  
  251. =item $ef = XML::Grove::Factory->element_factory()
  252.  
  253. Creates a new element factory object for creating elements.
  254. `C<element_factory()>' objects work by creating an element for any
  255. name used to call the object.
  256.  
  257. =item $ef->I<NAME>( I<CONTENTS> )
  258.  
  259. =item $ef->I<NAME>( { I<ATTRIBUTES> }, I<CONTENTS>)
  260.  
  261. Creates an XML::Grove::Element object with the given I<NAME>,
  262. I<ATTRIBUTES>, and I<CONTENTS>.  The hash containing I<ATTRIBUTES> is
  263. optional if this element doesn't need attributes.  Strings in
  264. I<CONTENTS> are converted to XML::Grove::Characters objects.
  265.  
  266. =back
  267.  
  268. =head2 ELEMENT FACTORY EXAMPLE
  269.  
  270.  use XML::Grove::Factory;
  271.  
  272.  $ef = XML::Grove::Factory->element_factory();
  273.  
  274.  $element =
  275.    $ef->HTML(
  276.      $ef->HEAD(
  277.        $ef->TITLE('Some Title')),
  278.      $ef->BODY({ bgcolor => '#FFFFFF' },
  279.        $ef->P('A paragraph.')));
  280.  
  281. =head1 ELEMENT FUNCTIONS
  282.  
  283. =over 4
  284.  
  285. =item XML::Grove::Factory->element_functions (PREFIX, ELEMENTS)
  286.  
  287. Creates functions in the current package for creating elements with
  288. the names provided in the list I<ELEMENTS>.  I<PREFIX> will be
  289. prepended to every function name, or I<PREFIX> can be an empty string
  290. ('') if you're confident that there won't be any conflicts with
  291. functions in your package.
  292.  
  293. =item I<NAME>( I<CONTENTS> )
  294.  
  295. =item I<NAME>( { I<ATTRIBUTES> }, I<CONTENTS> )
  296.  
  297. =item I<PREFIX>I<NAME>( I<CONTENTS> )
  298.  
  299. =item I<PREFIX>I<NAME>( { I<ATTRIBUTES> }, I<CONTENTS> )
  300.  
  301. Functions created for `C<I<NAME>>' or `C<I<PREFIX>I<NAME>>' can be
  302. called to create XML::Grove::Element objects with the given I<NAME>,
  303. I<ATTRIBUTES>, and I<CONTENT>.  The hash containing I<ATTRIBUTES> is
  304. optional if this element doesn't need attributes.  Strings in
  305. I<CONTENT> are converted to XML::Grove::Characters objects.
  306.  
  307. =head2 ELEMENT FACTORY EXAMPLE
  308.  
  309.  use XML::Grove::Factory;
  310.  
  311.  XML::Grove::Factory->element_functions('', qw{ HTML HEAD TITLE BODY P });
  312.  
  313.  $element =
  314.    HTML(
  315.      HEAD(
  316.        TITLE('Some Title')),
  317.      BODY({ bgcolor => '#FFFFFF' },
  318.        P('A paragraph.')));
  319.  
  320. =head1 AUTHOR
  321.  
  322. Ken MacLeod, ken@bitsko.slc.ut.us
  323.  
  324. Inspired by the HTML::AsSubs module by Gisle Aas.
  325.  
  326. =head1 SEE ALSO
  327.  
  328. perl(1), XML::Grove(3).
  329.  
  330. Extensible Markup Language (XML) <http://www.w3c.org/XML>
  331.  
  332. =cut
  333.