.\" 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::AsString 3pm"
.TH XML::Grove::AsString 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::AsString \- output content of XML objects as a string
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use XML::Grove::AsString;
\&
\& # Using as_string method on XML::Grove::Document or XML::Grove::Element:
\& $string = $xml_object\->as_string OPTIONS;
\& $string = $element\->attr_as_string $attr, OPTIONS;
\&
\& # Using an XML::Grove::AsString instance:
\& $writer = new XML::Grove::AsString OPTIONS;
\&
\& $string = $writer\->as_string($xml_object);
\& $writer\->as_string($xml_object, $file_handle);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Calling `\f(CW\*(C`as_string\*(C'\fR' on an \s-1XML\s0 object returns the character data
contents of that object as a string, including all elements below that
object.  Calling `\f(CW\*(C`attr_as_string\*(C'\fR' on an element returns the
contents of the named attribute as a string.  Comments, processing
instructions, and, by default, entities all return an empty string.
.PP
\&\fI\s-1OPTIONS\s0\fR may either be a key-value list or a hash containing the
options described below.  \fI\s-1OPTIONS\s0\fR may be modified directly in the
object.  The default options are no filtering and entities are mapped
to empty strings.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "Filter" 4
.IX Item "Filter"
`\f(CW\*(C`Filter\*(C'\fR' is an anonymous sub that gets called to process character
data before it is appended to the string to be returned.  This can be
used, for example, to escape characters that are special in output
formats.  The `\f(CW\*(C`Filter\*(C'\fR' sub is called like this:
.Sp
.Vb 1
\&    $string = &$filter ($character_data);
.Ve
.IP "EntityMap" 4
.IX Item "EntityMap"
`\f(CW\*(C`EntityMap\*(C'\fR' is an object that accepts `\f(CW\*(C`lookup\*(C'\fR' methods or an
anonymous sub that gets called with the entity replacement text (data)
and mapper options as arguments and returns the corresponding
character replacements.  It is called like this if it is an object:
.Sp
.Vb 2
\&    $replacement_text = $entity_map\->lookup ($entity_data,
\&                                             $entity_map_options);
.Ve
.Sp
or this if it is a sub:
.Sp
.Vb 2
\&    $replacement_text = &$entity_map ($entity_data,
\&                                      $entity_map_options);
.Ve
.IP "EntityMapOptions" 4
.IX Item "EntityMapOptions"
`\f(CW\*(C`EntityMapOptions\*(C'\fR' is a hash passed through to the `\f(CW\*(C`lookup\*(C'\fR'
method or anonymous sub, the type of value is defined by the entity
mapping package or the anonymous sub.
.IP "EntityMapFilter" 4
.IX Item "EntityMapFilter"
`\f(CW\*(C`EntityMapFilter\*(C'\fR' is a flag to indicate if mapped entities should
be filtered after mapping.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Here is an example of entity mapping using the Text::EntityMap module:
.PP
.Vb 2
\&    use Text::EntityMap;
\&    use XML::Grove::AsString;
\&
\&    $html_iso_dia = Text::EntityMap\->load (\*(AqISOdia.2html\*(Aq);
\&    $html_iso_pub = Text::EntityMap\->load (\*(AqISOpub.2html\*(Aq);
\&    $html_map = Text::EntityMap\->group ($html_iso_dia,
\&                                        $html_iso_pub);
\&
\&    $element\->as_string (EntityMap => $html_map);
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Ken MacLeod, ken@bitsko.slc.ut.us
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), \fIXML::Grove\fR\|(3)
.PP
Extensible Markup Language (\s-1XML\s0) <http://www.w3c.org/XML>