local-lib5/man/man3/PPI::Dumper.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "PPI::Dumper 3"
 127 .TH PPI::Dumper 3 "2009-08-08" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 PPI::Dumper \- Dumping of PDOM trees
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 2
 137 \&  # Load a document
 138 \&  my $Module = PPI::Document\->new( \*(AqMyModule.pm\*(Aq );
 139 \&
 140 \&  # Create the dumper
 141 \&  my $Dumper = PPI::Dumper\->new( $Module );
 142 \&
 143 \&  # Dump the document
 144 \&  $Dumper\->print;
 145 .Ve
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 The \s-1PDOM\s0 trees in \s-1PPI\s0 are quite complex, and getting a dump of their
 149 structure for development and debugging purposes is important.
 150 .PP
 151 This module provides that functionality.
 152 .PP
 153 The process is relatively simple. Create a dumper object with a
 154 particular set of options, and then call one of the dump methods to
 155 generate the dump content itself.
 156 .SH "METHODS"
 157 .IX Header "METHODS"
 158 .ie n .SS "new $Element, param => value, ..."
 159 .el .SS "new \f(CW$Element\fP, param => value, ..."
 160 .IX Subsection "new $Element, param => value, ..."
 161 The \f(CW\*(C`new\*(C'\fR constructor creates a dumper, and takes as argument a single
 162 PPI::Element object of any type to serve as the root of the tree to
 163 be dumped, and a number of key\->value parameters to control the output
 164 format of the Dumper. Details of the parameters are listed below.
 165 .PP
 166 Returns a new \f(CW\*(C`PPI::Dumper\*(C'\fR object, or \f(CW\*(C`undef\*(C'\fR if the constructor
 167 is not passed a correct PPI::Element root object.
 168 .IP "memaddr" 4
 169 .IX Item "memaddr"
 170 Should the dumper print the memory addresses of each \s-1PDOM\s0 element.
 171 True/false value, off by default.
 172 .IP "indent" 4
 173 .IX Item "indent"
 174 Should the structures being dumped be indented. This value is numeric,
 175 with the number representing the number of spaces to use when indenting
 176 the dumper output. Set to '2' by default.
 177 .IP "class" 4
 178 .IX Item "class"
 179 Should the dumper print the full class for each element.
 180 True/false value, on by default.
 181 .IP "content" 4
 182 .IX Item "content"
 183 Should the dumper show the content of each element. True/false value,
 184 on by default.
 185 .IP "whitespace" 4
 186 .IX Item "whitespace"
 187 Should the dumper show whitespace tokens. By not showing the copious
 188 numbers of whitespace tokens the structure of the code can often be
 189 made much clearer. True/false value, on by default.
 190 .IP "comments" 4
 191 .IX Item "comments"
 192 Should the dumper show comment tokens. In situations where you have
 193 a lot of comments, the code can often be made clearer by ignoring
 194 comment tokens. True/value value, on by default.
 195 .IP "locations" 4
 196 .IX Item "locations"
 197 Should the dumper show the location of each token. The values shown are
 198 [ line, rowchar, column ]. See \*(L"location\*(R" in PPI::Element for a description of
 199 what these values really are. True/false value, off by default.
 200 .SS "print"
 201 .IX Subsection "print"
 202 The \f(CW\*(C`print\*(C'\fR method generates the dump and prints it to \s-1STDOUT\s0.
 203 .PP
 204 Returns as for the internal print function.
 205 .SS "string"
 206 .IX Subsection "string"
 207 The \f(CW\*(C`string\*(C'\fR method generates the dump and provides it as a
 208 single string.
 209 .PP
 210 Returns a string or undef if there is an error while generating the dump.
 211 .SS "list"
 212 .IX Subsection "list"
 213 The \f(CW\*(C`list\*(C'\fR method generates the dump and provides it as a raw
 214 list, without trailing newlines.
 215 .PP
 216 Returns a list or the null list if there is an error while generation
 217 the dump.
 218 .SH "SUPPORT"
 219 .IX Header "SUPPORT"
 220 See the support section in the main module.
 221 .SH "AUTHOR"
 222 .IX Header "AUTHOR"
 223 Adam Kennedy <adamk@cpan.org>
 224 .SH "COPYRIGHT"
 225 .IX Header "COPYRIGHT"
 226 Copyright 2001 \- 2009 Adam Kennedy.
 227 .PP
 228 This program is free software; you can redistribute
 229 it and/or modify it under the same terms as Perl itself.
 230 .PP
 231 The full text of the license can be found in the
 232 \&\s-1LICENSE\s0 file included with this module.