XML::Grove::Factory - phpMan

Che Dong
NAME
    XML::Grove::Factory - simplify creation of XML::Grove objects

SYNOPSIS
     use XML::Grove::Factory;

     ### An object that creates Grove objects directly
     my $gf = XML::Grove::Factory->grove_factory;

     $grove = $gf->document( CONTENTS );
     $element = $gf->element( $name, { ATTRIBUTES }, CONTENTS );
     $pi = $gf->pi( $target, $data );
     $comment = $gf->comment( $data );

     ### An object that creates elements by method name
     my $ef = XML::Grove::Factory->element_factory();

     $element = $ef->NAME( { ATTRIBUTES }, CONTENTS);

     ### Similar to `element_factory', but creates functions in the
     ### current package
     XML::Grove::Factory->element_functions( PREFIX, ELEMENTS );

     $element = NAME( { ATTRIBUTES }, CONTENTS );

DESCRIPTION
    "XML::Grove::Factory" provides objects or defines functions that let you
    simply and quickly create the most commonly used XML::Grove objects.
    "XML::Grove::Factory" supports three types of object creation. The first
    type is to create raw XML::Grove objects. The second type creates XML
    elements by element name. The third type is like the second, but defines
    local functions for you to call instead of using an object, which might
    save typing in some cases.

    The three types of factories can be mixed. For example, you can use
    local functions for all element names that don't conflict with your own
    sub names or contain special characters, and then use a
    `"grove_factory()"' object for those elements that do conflict.

    In the examples that follow, each example is creating an XML instance
    similar to the following, assuming it's pretty printed:

        <?xml version="1.0"?>
        <HTML>
          <HEAD>
            <TITLE>Some Title</TITLE>
          </HEAD>
          <BODY bgcolor="#FFFFFF">
            <P>A paragraph.</P>
          </BODY>
        </HTML>

GROVE FACTORY
    $gf = XML::Grove::Factory->grove_factory()
        Creates a new grove factory object that creates raw XML::Grove
        objects.

    $gf->document( *CONTENTS* );
        Creates an XML::Grove::Document object. *CONTENTS* may contain
        processing instructions, strings containing only whitespace
        characters, and a single element object (but note that there is no
        checking). Strings are converted to XML::Grove::Characters objects.

    $gf->element($name, *CONTENTS*);
    $gf->element($name, { *ATTRIBUTES* }, *CONTENTS*);
        Creates an XML::Grove::Element object with the name `$name'. If the
        argument following `$name' is an anonymous hash, *ATTRIBUTES*, then
        they will be copied to the elements attributes. *CONTENTS* will be
        stored in the element's content (note that there is no validity
        checking). Strings in *CONTENTS* are converted to
        XML::Grove::Characters objects.

    $gf->pi( *TARGET*, *DATA*)
    $gf->pi( *DATA* )
        Create an XML::Grove::PI object with *TARGET* and *DATA*.

    $gf->comment( *DATA* )
        Create an XML::Grove::Comment object with *DATA*.

  GROVE FACTORY EXAMPLE
     use XML::Grove::Factory;

     $gf = XML::Grove::Factory->grove_factory;

     $element =
       $gf->element('HTML',
         $gf->element('HEAD',
           $gf->element('TITLE', 'Some Title')),
         $gf->element('BODY', { bgcolor => '#FFFFFF' },
           $gf->element('P', 'A paragraph.')));

ELEMENT FACTORY
    $ef = XML::Grove::Factory->element_factory()
        Creates a new element factory object for creating elements.
        `"element_factory()"' objects work by creating an element for any
        name used to call the object.

    $ef->*NAME*( *CONTENTS* )
    $ef->*NAME*( { *ATTRIBUTES* }, *CONTENTS*)
        Creates an XML::Grove::Element object with the given *NAME*,
        *ATTRIBUTES*, and *CONTENTS*. The hash containing *ATTRIBUTES* is
        optional if this element doesn't need attributes. Strings in
        *CONTENTS* are converted to XML::Grove::Characters objects.

  ELEMENT FACTORY EXAMPLE
     use XML::Grove::Factory;

     $ef = XML::Grove::Factory->element_factory();

     $element =
       $ef->HTML(
         $ef->HEAD(
           $ef->TITLE('Some Title')),
         $ef->BODY({ bgcolor => '#FFFFFF' },
           $ef->P('A paragraph.')));

ELEMENT FUNCTIONS
    XML::Grove::Factory->element_functions (PREFIX, ELEMENTS)
        Creates functions in the current package for creating elements with
        the names provided in the list *ELEMENTS*. *PREFIX* will be
        prepended to every function name, or *PREFIX* can be an empty string
        ('') if you're confident that there won't be any conflicts with
        functions in your package.

    *NAME*( *CONTENTS* )
    *NAME*( { *ATTRIBUTES* }, *CONTENTS* )
    *PREFIX**NAME*( *CONTENTS* )
    *PREFIX**NAME*( { *ATTRIBUTES* }, *CONTENTS* )
        Functions created for `"*NAME*"' or `"*PREFIX**NAME*"' can be called
        to create XML::Grove::Element objects with the given *NAME*,
        *ATTRIBUTES*, and *CONTENT*. The hash containing *ATTRIBUTES* is
        optional if this element doesn't need attributes. Strings in
        *CONTENT* are converted to XML::Grove::Characters objects.

  ELEMENT FACTORY EXAMPLE
     use XML::Grove::Factory;

     XML::Grove::Factory->element_functions('', qw{ HTML HEAD TITLE BODY P });

     $element =
       HTML(
         HEAD(
           TITLE('Some Title')),
         BODY({ bgcolor => '#FFFFFF' },
           P('A paragraph.')));

AUTHOR
    Ken MacLeod, ken AT bitsko.us

    Inspired by the HTML::AsSubs module by Gisle Aas.

SEE ALSO
    perl(1), XML::Grove(3).

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