.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "XML::Grove::Factory 3pm" .TH XML::Grove::Factory 3pm "2018-07-12" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" XML::Grove::Factory \- simplify creation of XML::Grove objects .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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\*(Aq, but creates functions in the \& ### current package \& XML::Grove::Factory\->element_functions( PREFIX, ELEMENTS ); \& \& $element = NAME( { ATTRIBUTES }, CONTENTS ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`XML::Grove::Factory\*(C'\fR provides objects or defines functions that let you simply and quickly create the most commonly used XML::Grove objects. \f(CW\*(C`XML::Grove::Factory\*(C'\fR supports three types of object creation. The first type is to create raw XML::Grove objects. The second type creates \s-1XML\s0 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. .PP 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 `\f(CW\*(C`grove_factory()\*(C'\fR' object for those elements that do conflict. .PP In the examples that follow, each example is creating an \s-1XML\s0 instance similar to the following, assuming it's pretty printed: .PP .Vb 9 \& \& \& \& Some Title \& \& \&

A paragraph.

\& \& .Ve .SH "GROVE FACTORY" .IX Header "GROVE FACTORY" .ie n .IP "$gf = XML::Grove::Factory\->\fIgrove_factory()\fR" 4 .el .IP "\f(CW$gf\fR = XML::Grove::Factory\->\fIgrove_factory()\fR" 4 .IX Item "$gf = XML::Grove::Factory->grove_factory()" Creates a new grove factory object that creates raw XML::Grove objects. .ie n .IP "$gf\->document( \fI\s-1CONTENTS\s0\fR );" 4 .el .IP "\f(CW$gf\fR\->document( \fI\s-1CONTENTS\s0\fR );" 4 .IX Item "$gf->document( CONTENTS );" Creates an XML::Grove::Document object. \fI\s-1CONTENTS\s0\fR 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. .ie n .IP "$gf\->element($name, \fI\s-1CONTENTS\s0\fR);" 4 .el .IP "\f(CW$gf\fR\->element($name, \fI\s-1CONTENTS\s0\fR);" 4 .IX Item "$gf->element($name, CONTENTS);" .PD 0 .ie n .IP "$gf\->element($name, { \fI\s-1ATTRIBUTES\s0\fR }, \fI\s-1CONTENTS\s0\fR);" 4 .el .IP "\f(CW$gf\fR\->element($name, { \fI\s-1ATTRIBUTES\s0\fR }, \fI\s-1CONTENTS\s0\fR);" 4 .IX Item "$gf->element($name, { ATTRIBUTES }, CONTENTS);" .PD Creates an XML::Grove::Element object with the name `\f(CW$name\fR'. If the argument following `\f(CW$name\fR' is an anonymous hash, \fI\s-1ATTRIBUTES\s0\fR, then they will be copied to the elements attributes. \fI\s-1CONTENTS\s0\fR will be stored in the element's content (note that there is no validity checking). Strings in \fI\s-1CONTENTS\s0\fR are converted to XML::Grove::Characters objects. .ie n .IP "$gf\->pi( \fI\s-1TARGET\s0\fR, \fI\s-1DATA\s0\fR)" 4 .el .IP "\f(CW$gf\fR\->pi( \fI\s-1TARGET\s0\fR, \fI\s-1DATA\s0\fR)" 4 .IX Item "$gf->pi( TARGET, DATA)" .PD 0 .ie n .IP "$gf\->pi( \fI\s-1DATA\s0\fR )" 4 .el .IP "\f(CW$gf\fR\->pi( \fI\s-1DATA\s0\fR )" 4 .IX Item "$gf->pi( DATA )" .PD Create an XML::Grove::PI object with \fI\s-1TARGET\s0\fR and \fI\s-1DATA\s0\fR. .ie n .IP "$gf\->comment( \fI\s-1DATA\s0\fR )" 4 .el .IP "\f(CW$gf\fR\->comment( \fI\s-1DATA\s0\fR )" 4 .IX Item "$gf->comment( DATA )" Create an XML::Grove::Comment object with \fI\s-1DATA\s0\fR. .SS "\s-1GROVE FACTORY EXAMPLE\s0" .IX Subsection "GROVE FACTORY EXAMPLE" .Vb 1 \& use XML::Grove::Factory; \& \& $gf = XML::Grove::Factory\->grove_factory; \& \& $element = \& $gf\->element(\*(AqHTML\*(Aq, \& $gf\->element(\*(AqHEAD\*(Aq, \& $gf\->element(\*(AqTITLE\*(Aq, \*(AqSome Title\*(Aq)), \& $gf\->element(\*(AqBODY\*(Aq, { bgcolor => \*(Aq#FFFFFF\*(Aq }, \& $gf\->element(\*(AqP\*(Aq, \*(AqA paragraph.\*(Aq))); .Ve .SH "ELEMENT FACTORY" .IX Header "ELEMENT FACTORY" .ie n .IP "$ef = XML::Grove::Factory\->\fIelement_factory()\fR" 4 .el .IP "\f(CW$ef\fR = XML::Grove::Factory\->\fIelement_factory()\fR" 4 .IX Item "$ef = XML::Grove::Factory->element_factory()" Creates a new element factory object for creating elements. `\f(CW\*(C`element_factory()\*(C'\fR' objects work by creating an element for any name used to call the object. .ie n .IP "$ef\->\fI\s-1NAME\s0\fR( \fI\s-1CONTENTS\s0\fR )" 4 .el .IP "\f(CW$ef\fR\->\fI\s-1NAME\s0\fR( \fI\s-1CONTENTS\s0\fR )" 4 .IX Item "$ef->NAME( CONTENTS )" .PD 0 .ie n .IP "$ef\->\fI\s-1NAME\s0\fR( { \fI\s-1ATTRIBUTES\s0\fR }, \fI\s-1CONTENTS\s0\fR)" 4 .el .IP "\f(CW$ef\fR\->\fI\s-1NAME\s0\fR( { \fI\s-1ATTRIBUTES\s0\fR }, \fI\s-1CONTENTS\s0\fR)" 4 .IX Item "$ef->NAME( { ATTRIBUTES }, CONTENTS)" .PD Creates an XML::Grove::Element object with the given \fI\s-1NAME\s0\fR, \&\fI\s-1ATTRIBUTES\s0\fR, and \fI\s-1CONTENTS\s0\fR. The hash containing \fI\s-1ATTRIBUTES\s0\fR is optional if this element doesn't need attributes. Strings in \&\fI\s-1CONTENTS\s0\fR are converted to XML::Grove::Characters objects. .SS "\s-1ELEMENT FACTORY EXAMPLE\s0" .IX Subsection "ELEMENT FACTORY EXAMPLE" .Vb 1 \& use XML::Grove::Factory; \& \& $ef = XML::Grove::Factory\->element_factory(); \& \& $element = \& $ef\->HTML( \& $ef\->HEAD( \& $ef\->TITLE(\*(AqSome Title\*(Aq)), \& $ef\->BODY({ bgcolor => \*(Aq#FFFFFF\*(Aq }, \& $ef\->P(\*(AqA paragraph.\*(Aq))); .Ve .SH "ELEMENT FUNCTIONS" .IX Header "ELEMENT FUNCTIONS" .IP "XML::Grove::Factory\->element_functions (\s-1PREFIX, ELEMENTS\s0)" 4 .IX Item "XML::Grove::Factory->element_functions (PREFIX, ELEMENTS)" Creates functions in the current package for creating elements with the names provided in the list \fI\s-1ELEMENTS\s0\fR. \fI\s-1PREFIX\s0\fR will be prepended to every function name, or \fI\s-1PREFIX\s0\fR can be an empty string ('') if you're confident that there won't be any conflicts with functions in your package. .IP "\fI\s-1NAME\s0\fR( \fI\s-1CONTENTS\s0\fR )" 4 .IX Item "NAME( CONTENTS )" .PD 0 .IP "\fI\s-1NAME\s0\fR( { \fI\s-1ATTRIBUTES\s0\fR }, \fI\s-1CONTENTS\s0\fR )" 4 .IX Item "NAME( { ATTRIBUTES }, CONTENTS )" .IP "\fI\s-1PREFIX\s0\fR\fI\s-1NAME\s0\fR( \fI\s-1CONTENTS\s0\fR )" 4 .IX Item "PREFIXNAME( CONTENTS )" .IP "\fI\s-1PREFIX\s0\fR\fI\s-1NAME\s0\fR( { \fI\s-1ATTRIBUTES\s0\fR }, \fI\s-1CONTENTS\s0\fR )" 4 .IX Item "PREFIXNAME( { ATTRIBUTES }, CONTENTS )" .PD Functions created for `\f(CW\*(C`\f(CINAME\f(CW\*(C'\fR' or `\f(CW\*(C`\f(CIPREFIX\f(CW\f(CINAME\f(CW\*(C'\fR' can be called to create XML::Grove::Element objects with the given \fI\s-1NAME\s0\fR, \&\fI\s-1ATTRIBUTES\s0\fR, and \fI\s-1CONTENT\s0\fR. The hash containing \fI\s-1ATTRIBUTES\s0\fR is optional if this element doesn't need attributes. Strings in \&\fI\s-1CONTENT\s0\fR are converted to XML::Grove::Characters objects. .SS "\s-1ELEMENT FACTORY EXAMPLE\s0" .IX Subsection "ELEMENT FACTORY EXAMPLE" .Vb 1 \& use XML::Grove::Factory; \& \& XML::Grove::Factory\->element_functions(\*(Aq\*(Aq, qw{ HTML HEAD TITLE BODY P }); \& \& $element = \& HTML( \& HEAD( \& TITLE(\*(AqSome Title\*(Aq)), \& BODY({ bgcolor => \*(Aq#FFFFFF\*(Aq }, \& P(\*(AqA paragraph.\*(Aq))); .Ve .SH "AUTHOR" .IX Header "AUTHOR" Ken MacLeod, ken@bitsko.slc.ut.us .PP Inspired by the HTML::AsSubs module by Gisle Aas. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIperl\fR\|(1), \fIXML::Grove\fR\|(3). .PP Extensible Markup Language (\s-1XML\s0)