XML::G...Factory(3pm)

✨ NAME ✨

XML::Grove::Factory — bestie, it's here to simplify creation of XML::Grove objects 💖 like it literally does the tedious part so you don't have to, periodt.

---

🎀 SYNOPSIS 🎀

okay so this is the whole vibe in one block, no cap:

 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 🌸

So XML::Grove::Factory hands you objects — or straight up defines functions — that let you create the most commonly used XML::Grove objects simply and quickly. It's giving convenience. It's giving "why are you typing all that by hand bestie". 💅

It supports three types of object creation:

1. create raw XML::Grove objects 🪵
2. create XML elements by element name 🏷️
3. same as the second one, but it defines local functions for you to call instead of using an object — which might save typing in some cases ⌨️✨

And the slay part? 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. iykyk 🫶

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() — makes you a brand new grove factory object whose whole personality is creating raw XML::Grove objects. iconic behavior honestly.
• $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 heads up bestie, there is no checking 🙈. Strings get 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 element's attributes. CONTENTS gets stored in the element's content (and again, note that there is no validity checking 💀). Strings in CONTENTS are converted to XML::Grove::Characters objects.
• $gf->pi( TARGET, DATA) $gf->pi( DATA ) — creates an XML::Grove::PI object with TARGET and DATA. two ways, pick your fighter ✨
• $gf->comment( DATA ) — creates an XML::Grove::Comment object with DATA. 🍓

💜 GROVE FACTORY EXAMPLE 💜

look at this nesting, it's giving matryoshka doll:

 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. so you just... call it. by name. and it manifests. main character energy fr fr 👑
• $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 💜

same tree, but the methods are wearing name tags:

 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. confidence is key bestie but so is namespace hygiene 🫶
• NAME( CONTENTS ) NAME( { ATTRIBUTES }, CONTENTS ) PREFIXNAME( CONTENTS ) PREFIXNAME( { ATTRIBUTES }, CONTENTS ) — functions created for "NAME" or "PREFIXNAME" 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 💜

(yes bestie the heading says factory, we're keeping it exactly as the page has it, no notes 💀)

 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@bitsko.slc.ut.us 🌟

Inspired by the HTML::AsSubs module by Gisle Aas. (shoutout to the ancestors, we stan 💖)

---

💫 SEE ALSO 💫

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

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

---

and that's the whole page bestie!! this was XML::Grove::Factory, documented as part of perl v5.36.0, dated 2022-11-29 — so if you ever need it, that's the version and the day this little legend got written down. go forth and build groves, you absolute icon 💅✨🦋