.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "XML::LibXML::PrettyPrint 3"
.TH XML::LibXML::PrettyPrint 3 2023-07-25 "perl v5.38.0" "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::LibXML::PrettyPrint \- add pleasant whitespace to a DOM tree
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\& my $document = XML::LibXML\->new\->parse_file(\*(Aqin.xml\*(Aq);
\& my $pp = XML::LibXML::PrettyPrint\->new(indent_string => " ");
\& $pp\->pretty_print($document); # modified in\-place
\& print $document\->toString;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Long XML files can be daunting for humans to read. Of course, XML is really
designed for computers to read \- not people \- but there are times when mere
mortals do need to read and edit XML by hand. For example, if your
application stores its configuration in XML, or you need to dump some
XML to STDOUT for debugging purposes.
.PP
Syntax highlighting helps, but to really make sense of some XML, proper
indentation can be vital. Hence \f(CW\*(C`XML::LibXML::PrettyPrint\*(C'\fR \- it can
be applied to an XML::LibXML DOM tree to reformat it into a more
readable result.
.PP
Pretty-printing XML is not as CPU-efficient as dumping it out sloppily,
so unless you're pretty sure that a human is going to need to make sense
of your XML, you should probably not use this module.
.SS Constructors
.IX Subsection "Constructors"
.ie n .IP new(%options) 4
.el .IP \f(CWnew(%options)\fR 4
.IX Item "new(%options)"
Constructs a pretty-printer object.
.Sp
Options:
.RS 4
.IP \(bu 4
\&\fBindent_string\fR \- The string to use to indent each line. Defaults to a single tab character. Setting it to a non-whitespace character is allowed, but will carp a warning.
.IP \(bu 4
\&\fBnew_line\fR \- The string to use to begin a new line. Defaults to "\en".
.IP \(bu 4
\&\fBelement\fR \- A hashref of element categorisations. Each categorisation is a reference to an array of element names or callback functions. Element names may use Clark notation.
.Sp
.Vb 10
\& my $callback = sub {
\& my $node = shift;
\& return 1 if $node\->hasAttribute(\*(Aqis_block\*(Aq);
\& return undef;
\& };
\& my $pp = XML::LibXML::PrettyPrint\->new(
\& element => {
\& inline => [qw/span strong em b i a/],
\& block => [qw/p div body html head/, $callback],
\& compact => [qw/title caption li dd dt th td/],
\& preserves_whitespace => [qw/pre script style/],
\& }
\& );
.Ve
.Sp
Callbacks should return 1 (true), 0 (false) or undef (dunno).
.RE
.RS 4
.RE
.ie n .IP new_for_html(%options) 4
.el .IP \f(CWnew_for_html(%options)\fR 4
.IX Item "new_for_html(%options)"
Constructs a pretty printer object pre-configured to be suitable for
HTML and XHTML. The \fBindent_string\fR and \fBnew_line\fR options are
supported.
.SS Methods
.IX Subsection "Methods"
If you just need to use a default configuration (no options passed to
the constructor, then you can call these as class methods, unless otherwise
stated.
.ie n .IP strip_whitespace($node) 4
.el .IP \f(CWstrip_whitespace($node)\fR 4
.IX Item "strip_whitespace($node)"
Strips superfluous whitespace from an \f(CW\*(C`XML::LibXML::Document\*(C'\fR or
\&\f(CW\*(C`XML::LibXML::Element\*(C'\fR.
.Sp
Whitespace just before, just after or leading/trailing within an inline
element is not considered superfluous. Runs of multiple whitespace
characters are replaced with a single space. Whitespace is not changed
within an element that preserves whitespace.
.Sp
The node is modified in place.
.ie n .IP """indent($node, $level)""" 4
.el .IP "\f(CWindent($node, $level)\fR" 4
.IX Item "indent($node, $level)"
Indents the node to a certain indentation level, and its direct children to
\&\f(CW\*(C`$level + 1\*(C'\fR, grandchildren to \f(CW\*(C`$level + 2\*(C'\fR, etc. Typically you'd
just want to indent the root node to level 0.
.Sp
The node is modified in place.
.Sp
Elements that preserve whitespace are not changed.
.ie n .IP """pretty_print($node, $level)""" 4
.el .IP "\f(CWpretty_print($node, $level)\fR" 4
.IX Item "pretty_print($node, $level)"
Strip whitespace and indent. The node is modified in place and returned.
.Sp
Example use as a class method:
.Sp
.Vb 3
\& print XML::LibXML::PrettyPrint
\& \->pretty_print(XML::LibXML\->new\->parse_string($XML))
\& \->toString;
.Ve
.ie n .IP indent_string($level) 4
.el .IP \f(CWindent_string($level)\fR 4
.IX Item "indent_string($level)"
Returns the string that would be used to indent something to a particular
level. Descendent classes could override this method to do funky indentation,
such as having varying levels of indentation.
.ie n .IP """new_line""" 4
.el .IP \f(CWnew_line\fR 4
.IX Item "new_line"
Returns the string that would be used to begin a new line.
.ie n .IP element_category($node) 4
.el .IP \f(CWelement_category($node)\fR 4
.IX Item "element_category($node)"
Returns EL_INLINE, EL_BLOCK, EL_COMPACT or undef.
.ie n .IP element_preserves_whitespace($node) 4
.el .IP \f(CWelement_preserves_whitespace($node)\fR 4
.IX Item "element_preserves_whitespace($node)"
Boolean indicating whether the contents of the element have significant
whitespace that needs preserving.
.Sp
Returns undef if \f(CW$node\fR is not an \f(CW\*(C`XML::LibXML::Element\*(C'\fR.
.SS Functions
.IX Subsection "Functions"
.ie n .IP """print_xml $xml""" 4
.el .IP "\f(CWprint_xml $xml\fR" 4
.IX Item "print_xml $xml"
Given an XML string or an XML::LibXML::Node object, prints it nicely.
.Sp
This function is not exported by default, but can be requested:
.Sp
.Vb 1
\& use XML::LibXML::PrettyPrint 0.001 qw(print_xml);
.Ve
.Sp
Use like this:
.Sp
.Vb 1
\& print_xml \*(Aq