| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "B::Concise 3perl" |
| 58 |
.TH B::Concise 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
B::Concise \- Walk Perl syntax tree, printing concise info about ops |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& perl \-MO=Concise[,OPTIONS] foo.pl |
| 69 |
\& |
| 70 |
\& use B::Concise qw(set_style add_callback); |
| 71 |
.Ve |
| 72 |
.SH DESCRIPTION |
| 73 |
.IX Header "DESCRIPTION" |
| 74 |
This compiler backend prints the internal OPs of a Perl program's syntax |
| 75 |
tree in one of several space-efficient text formats suitable for debugging |
| 76 |
the inner workings of perl or other compiler backends. It can print OPs in |
| 77 |
the order they appear in the OP tree, in the order they will execute, or |
| 78 |
in a text approximation to their tree structure, and the format of the |
| 79 |
information displayed is customizable. Its function is similar to that of |
| 80 |
perl's \fB\-Dx\fR debugging flag or the \fBB::Terse\fR module, but it is more |
| 81 |
sophisticated and flexible. |
| 82 |
.SH EXAMPLE |
| 83 |
.IX Header "EXAMPLE" |
| 84 |
Here's two outputs (or 'renderings'), using the \-exec and \-basic |
| 85 |
(i.e. default) formatting conventions on the same code snippet. |
| 86 |
.PP |
| 87 |
.Vb 9 |
| 88 |
\& % perl \-MO=Concise,\-exec \-e \*(Aq$a = $b + 42\*(Aq |
| 89 |
\& 1 <0> enter |
| 90 |
\& 2 <;> nextstate(main 1 \-e:1) v |
| 91 |
\& 3 <#> gvsv[*b] s |
| 92 |
\& 4 <$> const[IV 42] s |
| 93 |
\& * 5 <2> add[t3] sK/2 |
| 94 |
\& 6 <#> gvsv[*a] s |
| 95 |
\& 7 <2> sassign vKS/2 |
| 96 |
\& 8 <@> leave[1 ref] vKP/REFC |
| 97 |
.Ve |
| 98 |
.PP |
| 99 |
In this \-exec rendering, each opcode is executed in the order shown. |
| 100 |
The add opcode, marked with '*', is discussed in more detail. |
| 101 |
.PP |
| 102 |
The 1st column is the op's sequence number, starting at 1, and is |
| 103 |
displayed in base 36 by default. Here they're purely linear; the |
| 104 |
sequences are very helpful when looking at code with loops and |
| 105 |
branches. |
| 106 |
.PP |
| 107 |
The symbol between angle brackets indicates the op's type, for |
| 108 |
example; <2> is a BINOP, <@> a LISTOP, and <#> is a PADOP, which is |
| 109 |
used in threaded perls. (see "OP class abbreviations"). |
| 110 |
.PP |
| 111 |
The opname, as in \fB'add[t1]'\fR, may be followed by op-specific |
| 112 |
information in parentheses or brackets (ex \fB'[t1]'\fR). |
| 113 |
.PP |
| 114 |
The op-flags (ex \fB'sK/2'\fR) are described in ("OP flags |
| 115 |
abbreviations"). |
| 116 |
.PP |
| 117 |
.Vb 11 |
| 118 |
\& % perl \-MO=Concise \-e \*(Aq$a = $b + 42\*(Aq |
| 119 |
\& 8 <@> leave[1 ref] vKP/REFC \->(end) |
| 120 |
\& 1 <0> enter \->2 |
| 121 |
\& 2 <;> nextstate(main 1 \-e:1) v \->3 |
| 122 |
\& 7 <2> sassign vKS/2 \->8 |
| 123 |
\& * 5 <2> add[t1] sK/2 \->6 |
| 124 |
\& \- <1> ex\-rv2sv sK/1 \->4 |
| 125 |
\& 3 <$> gvsv(*b) s \->4 |
| 126 |
\& 4 <$> const(IV 42) s \->5 |
| 127 |
\& \- <1> ex\-rv2sv sKRM*/1 \->7 |
| 128 |
\& 6 <$> gvsv(*a) s \->7 |
| 129 |
.Ve |
| 130 |
.PP |
| 131 |
The default rendering is top-down, so they're not in execution order. |
| 132 |
This form reflects the way the stack is used to parse and evaluate |
| 133 |
expressions; the add operates on the two terms below it in the tree. |
| 134 |
.PP |
| 135 |
Nullops appear as \f(CW\*(C`ex\-opname\*(C'\fR, where \fIopname\fR is an op that has been |
| 136 |
optimized away by perl. They're displayed with a sequence-number of |
| 137 |
\&'\-', because they are not executed (they don't appear in previous |
| 138 |
example), they're printed here because they reflect the parse. |
| 139 |
.PP |
| 140 |
The arrow points to the sequence number of the next op; they're not |
| 141 |
displayed in \-exec mode, for obvious reasons. |
| 142 |
.PP |
| 143 |
Note that because this rendering was done on a non-threaded perl, the |
| 144 |
PADOPs in the previous examples are now SVOPs, and some (but not all) |
| 145 |
of the square brackets have been replaced by round ones. This is a |
| 146 |
subtle feature to provide some visual distinction between renderings |
| 147 |
on threaded and un-threaded perls. |
| 148 |
.SH OPTIONS |
| 149 |
.IX Header "OPTIONS" |
| 150 |
Arguments that don't start with a hyphen are taken to be the names of |
| 151 |
subroutines or formats to render; if no |
| 152 |
such functions are specified, the main |
| 153 |
body of the program (outside any subroutines, and not including use'd |
| 154 |
or require'd files) is rendered. Passing \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, |
| 155 |
\&\f(CW\*(C`CHECK\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR, or \f(CW\*(C`END\*(C'\fR will cause all of the corresponding |
| 156 |
special blocks to be printed. Arguments must follow options. |
| 157 |
.PP |
| 158 |
Options affect how things are rendered (ie printed). They're presented |
| 159 |
here by their visual effect, 1st being strongest. They're grouped |
| 160 |
according to how they interrelate; within each group the options are |
| 161 |
mutually exclusive (unless otherwise stated). |
| 162 |
.SS "Options for Opcode Ordering" |
| 163 |
.IX Subsection "Options for Opcode Ordering" |
| 164 |
These options control the 'vertical display' of opcodes. The display |
| 165 |
\&'order' is also called 'mode' elsewhere in this document. |
| 166 |
.IP \fB\-basic\fR 4 |
| 167 |
.IX Item "-basic" |
| 168 |
Print OPs in the order they appear in the OP tree (a preorder |
| 169 |
traversal, starting at the root). The indentation of each OP shows its |
| 170 |
level in the tree, and the '\->' at the end of the line indicates the |
| 171 |
next opcode in execution order. This mode is the default, so the flag |
| 172 |
is included simply for completeness. |
| 173 |
.IP \fB\-exec\fR 4 |
| 174 |
.IX Item "-exec" |
| 175 |
Print OPs in the order they would normally execute (for the majority |
| 176 |
of constructs this is a postorder traversal of the tree, ending at the |
| 177 |
root). In most cases the OP that usually follows a given OP will |
| 178 |
appear directly below it; alternate paths are shown by indentation. In |
| 179 |
cases like loops when control jumps out of a linear path, a 'goto' |
| 180 |
line is generated. |
| 181 |
.IP \fB\-tree\fR 4 |
| 182 |
.IX Item "-tree" |
| 183 |
Print OPs in a text approximation of a tree, with the root of the tree |
| 184 |
at the left and 'left\-to\-right' order of children transformed into |
| 185 |
\&'top\-to\-bottom'. Because this mode grows both to the right and down, |
| 186 |
it isn't suitable for large programs (unless you have a very wide |
| 187 |
terminal). |
| 188 |
.SS "Options for Line-Style" |
| 189 |
.IX Subsection "Options for Line-Style" |
| 190 |
These options select the line-style (or just style) used to render |
| 191 |
each opcode, and dictates what info is actually printed into each line. |
| 192 |
.IP \fB\-concise\fR 4 |
| 193 |
.IX Item "-concise" |
| 194 |
Use the author's favorite set of formatting conventions. This is the |
| 195 |
default, of course. |
| 196 |
.IP \fB\-terse\fR 4 |
| 197 |
.IX Item "-terse" |
| 198 |
Use formatting conventions that emulate the output of \fBB::Terse\fR. The |
| 199 |
basic mode is almost indistinguishable from the real \fBB::Terse\fR, and the |
| 200 |
exec mode looks very similar, but is in a more logical order and lacks |
| 201 |
curly brackets. \fBB::Terse\fR doesn't have a tree mode, so the tree mode |
| 202 |
is only vaguely reminiscent of \fBB::Terse\fR. |
| 203 |
.IP \fB\-linenoise\fR 4 |
| 204 |
.IX Item "-linenoise" |
| 205 |
Use formatting conventions in which the name of each OP, rather than being |
| 206 |
written out in full, is represented by a one\- or two-character abbreviation. |
| 207 |
This is mainly a joke. |
| 208 |
.IP \fB\-debug\fR 4 |
| 209 |
.IX Item "-debug" |
| 210 |
Use formatting conventions reminiscent of CPAN module \fBB::Debug\fR; these aren't |
| 211 |
very concise at all. |
| 212 |
.IP \fB\-env\fR 4 |
| 213 |
.IX Item "-env" |
| 214 |
Use formatting conventions read from the environment variables |
| 215 |
\&\f(CW\*(C`B_CONCISE_FORMAT\*(C'\fR, \f(CW\*(C`B_CONCISE_GOTO_FORMAT\*(C'\fR, and \f(CW\*(C`B_CONCISE_TREE_FORMAT\*(C'\fR. |
| 216 |
.SS "Options for tree-specific formatting" |
| 217 |
.IX Subsection "Options for tree-specific formatting" |
| 218 |
.IP \fB\-compact\fR 4 |
| 219 |
.IX Item "-compact" |
| 220 |
Use a tree format in which the minimum amount of space is used for the |
| 221 |
lines connecting nodes (one character in most cases). This squeezes out |
| 222 |
a few precious columns of screen real estate. |
| 223 |
.IP \fB\-loose\fR 4 |
| 224 |
.IX Item "-loose" |
| 225 |
Use a tree format that uses longer edges to separate OP nodes. This format |
| 226 |
tends to look better than the compact one, especially in ASCII, and is |
| 227 |
the default. |
| 228 |
.IP \fB\-vt\fR 4 |
| 229 |
.IX Item "-vt" |
| 230 |
Use tree connecting characters drawn from the VT100 line-drawing set. |
| 231 |
This looks better if your terminal supports it. |
| 232 |
.IP \fB\-ascii\fR 4 |
| 233 |
.IX Item "-ascii" |
| 234 |
Draw the tree with standard ASCII characters like \f(CW\*(C`+\*(C'\fR and \f(CW\*(C`|\*(C'\fR. These don't |
| 235 |
look as clean as the VT100 characters, but they'll work with almost any |
| 236 |
terminal (or the horizontal scrolling mode of \fBless\fR\|(1)) and are suitable |
| 237 |
for text documentation or email. This is the default. |
| 238 |
.PP |
| 239 |
These are pairwise exclusive, i.e. compact or loose, vt or ascii. |
| 240 |
.SS "Options controlling sequence numbering" |
| 241 |
.IX Subsection "Options controlling sequence numbering" |
| 242 |
.IP \fB\-base\fR\fIn\fR 4 |
| 243 |
.IX Item "-basen" |
| 244 |
Print OP sequence numbers in base \fIn\fR. If \fIn\fR is greater than 10, the |
| 245 |
digit for 11 will be 'a', and so on. If \fIn\fR is greater than 36, the digit |
| 246 |
for 37 will be 'A', and so on until 62. Values greater than 62 are not |
| 247 |
currently supported. The default is 36. |
| 248 |
.IP \fB\-bigendian\fR 4 |
| 249 |
.IX Item "-bigendian" |
| 250 |
Print sequence numbers with the most significant digit first. This is the |
| 251 |
usual convention for Arabic numerals, and the default. |
| 252 |
.IP \fB\-littleendian\fR 4 |
| 253 |
.IX Item "-littleendian" |
| 254 |
Print sequence numbers with the least significant digit first. This is |
| 255 |
obviously mutually exclusive with bigendian. |
| 256 |
.SS "Other options" |
| 257 |
.IX Subsection "Other options" |
| 258 |
.IP \fB\-src\fR 4 |
| 259 |
.IX Item "-src" |
| 260 |
With this option, the rendering of each statement (starting with the |
| 261 |
nextstate OP) will be preceded by the 1st line of source code that |
| 262 |
generates it. For example: |
| 263 |
.Sp |
| 264 |
.Vb 10 |
| 265 |
\& 1 <0> enter |
| 266 |
\& # 1: my $i; |
| 267 |
\& 2 <;> nextstate(main 1 junk.pl:1) v:{ |
| 268 |
\& 3 <0> padsv[$i:1,10] vM/LVINTRO |
| 269 |
\& # 3: for $i (0..9) { |
| 270 |
\& 4 <;> nextstate(main 3 junk.pl:3) v:{ |
| 271 |
\& 5 <0> pushmark s |
| 272 |
\& 6 <$> const[IV 0] s |
| 273 |
\& 7 <$> const[IV 9] s |
| 274 |
\& 8 <{> enteriter(next\->j last\->m redo\->9)[$i:1,10] lKS |
| 275 |
\& k <0> iter s |
| 276 |
\& l <|> and(other\->9) vK/1 |
| 277 |
\& # 4: print "line "; |
| 278 |
\& 9 <;> nextstate(main 2 junk.pl:4) v |
| 279 |
\& a <0> pushmark s |
| 280 |
\& b <$> const[PV "line "] s |
| 281 |
\& c <@> print vK |
| 282 |
\& # 5: print "$i\en"; |
| 283 |
\& ... |
| 284 |
.Ve |
| 285 |
.IP "\fB\-stash=""somepackage""\fR" 4 |
| 286 |
.IX Item "-stash=""somepackage""" |
| 287 |
With this, "somepackage" will be required, then the stash is |
| 288 |
inspected, and each function is rendered. |
| 289 |
.PP |
| 290 |
The following options are pairwise exclusive. |
| 291 |
.IP \fB\-main\fR 4 |
| 292 |
.IX Item "-main" |
| 293 |
Include the main program in the output, even if subroutines were also |
| 294 |
specified. This rendering is normally suppressed when a subroutine |
| 295 |
name or reference is given. |
| 296 |
.IP \fB\-nomain\fR 4 |
| 297 |
.IX Item "-nomain" |
| 298 |
This restores the default behavior after you've changed it with '\-main' |
| 299 |
(it's not normally needed). If no subroutine name/ref is given, main is |
| 300 |
rendered, regardless of this flag. |
| 301 |
.IP \fB\-nobanner\fR 4 |
| 302 |
.IX Item "-nobanner" |
| 303 |
Renderings usually include a banner line identifying the function name |
| 304 |
or stringified subref. This suppresses the printing of the banner. |
| 305 |
.Sp |
| 306 |
TBC: Remove the stringified coderef; while it provides a 'cookie' for |
| 307 |
each function rendered, the cookies used should be 1,2,3.. not a |
| 308 |
random hex-address. It also complicates string comparison of two |
| 309 |
different trees. |
| 310 |
.IP \fB\-banner\fR 4 |
| 311 |
.IX Item "-banner" |
| 312 |
restores default banner behavior. |
| 313 |
.IP "\fB\-banneris\fR => subref" 4 |
| 314 |
.IX Item "-banneris => subref" |
| 315 |
TBC: a hookpoint (and an option to set it) for a user-supplied |
| 316 |
function to produce a banner appropriate for users needs. It's not |
| 317 |
ideal, because the rendering-state variables, which are a natural |
| 318 |
candidate for use in concise.t, are unavailable to the user. |
| 319 |
.SS "Option Stickiness" |
| 320 |
.IX Subsection "Option Stickiness" |
| 321 |
If you invoke Concise more than once in a program, you should know that |
| 322 |
the options are 'sticky'. This means that the options you provide in |
| 323 |
the first call will be remembered for the 2nd call, unless you |
| 324 |
re-specify or change them. |
| 325 |
.SH ABBREVIATIONS |
| 326 |
.IX Header "ABBREVIATIONS" |
| 327 |
The concise style uses symbols to convey maximum info with minimal |
| 328 |
clutter (like hex addresses). With just a little practice, you can |
| 329 |
start to see the flowers, not just the branches, in the trees. |
| 330 |
.SS "OP class abbreviations" |
| 331 |
.IX Subsection "OP class abbreviations" |
| 332 |
These symbols appear before the op-name, and indicate the |
| 333 |
B:: namespace that represents the ops in your Perl code. |
| 334 |
.PP |
| 335 |
.Vb 10 |
| 336 |
\& 0 OP (aka BASEOP) An OP with no children |
| 337 |
\& 1 UNOP An OP with one child |
| 338 |
\& + UNOP_AUX A UNOP with auxillary fields |
| 339 |
\& 2 BINOP An OP with two children |
| 340 |
\& | LOGOP A control branch OP |
| 341 |
\& @ LISTOP An OP that could have lots of children |
| 342 |
\& / PMOP An OP with a regular expression |
| 343 |
\& $ SVOP An OP with an SV |
| 344 |
\& " PVOP An OP with a string |
| 345 |
\& { LOOP An OP that holds pointers for a loop |
| 346 |
\& ; COP An OP that marks the start of a statement |
| 347 |
\& # PADOP An OP with a GV on the pad |
| 348 |
\& . METHOP An OP with method call info |
| 349 |
.Ve |
| 350 |
.SS "OP flags abbreviations" |
| 351 |
.IX Subsection "OP flags abbreviations" |
| 352 |
OP flags are either public or private. The public flags alter the |
| 353 |
behavior of each opcode in consistent ways, and are represented by 0 |
| 354 |
or more single characters. |
| 355 |
.PP |
| 356 |
.Vb 12 |
| 357 |
\& v OPf_WANT_VOID Want nothing (void context) |
| 358 |
\& s OPf_WANT_SCALAR Want single value (scalar context) |
| 359 |
\& l OPf_WANT_LIST Want list of any length (list context) |
| 360 |
\& Want is unknown |
| 361 |
\& K OPf_KIDS There is a firstborn child. |
| 362 |
\& P OPf_PARENS This operator was parenthesized. |
| 363 |
\& (Or block needs explicit scope entry.) |
| 364 |
\& R OPf_REF Certified reference. |
| 365 |
\& (Return container, not containee). |
| 366 |
\& M OPf_MOD Will modify (lvalue). |
| 367 |
\& S OPf_STACKED Some arg is arriving on the stack. |
| 368 |
\& * OPf_SPECIAL Do something weird for this op (see op.h) |
| 369 |
.Ve |
| 370 |
.PP |
| 371 |
Private flags, if any are set for an opcode, are displayed after a '/' |
| 372 |
.PP |
| 373 |
.Vb 2 |
| 374 |
\& 8 <@> leave[1 ref] vKP/REFC \->(end) |
| 375 |
\& 7 <2> sassign vKS/2 \->8 |
| 376 |
.Ve |
| 377 |
.PP |
| 378 |
They're opcode specific, and occur less often than the public ones, so |
| 379 |
they're represented by short mnemonics instead of single-chars; see |
| 380 |
B::Op_private and \fIregen/op_private\fR for more details. |
| 381 |
.PP |
| 382 |
Note that a number after a '/' often indicates the number of arguments. |
| 383 |
In the \fIsassign\fR example above, the OP takes 2 arguments. These values |
| 384 |
are sometimes used at runtime: in particular, the MAXARG macro makes use |
| 385 |
of them. |
| 386 |
.SH "FORMATTING SPECIFICATIONS" |
| 387 |
.IX Header "FORMATTING SPECIFICATIONS" |
| 388 |
For each line-style ('concise', 'terse', 'linenoise', etc.) there are |
| 389 |
3 format-specs which control how OPs are rendered. |
| 390 |
.PP |
| 391 |
The first is the 'default' format, which is used in both basic and exec |
| 392 |
modes to print all opcodes. The 2nd, goto-format, is used in exec |
| 393 |
mode when branches are encountered. They're not real opcodes, and are |
| 394 |
inserted to look like a closing curly brace. The tree-format is tree |
| 395 |
specific. |
| 396 |
.PP |
| 397 |
When a line is rendered, the correct format-spec is copied and scanned |
| 398 |
for the following items; data is substituted in, and other |
| 399 |
manipulations like basic indenting are done, for each opcode rendered. |
| 400 |
.PP |
| 401 |
There are 3 kinds of items that may be populated; special patterns, |
| 402 |
#vars, and literal text, which is copied verbatim. (Yes, it's a set |
| 403 |
of s///g steps.) |
| 404 |
.SS "Special Patterns" |
| 405 |
.IX Subsection "Special Patterns" |
| 406 |
These items are the primitives used to perform indenting, and to |
| 407 |
select text from amongst alternatives. |
| 408 |
.IP \fB(x(\fR\fIexec_text\fR\fB;\fR\fIbasic_text\fR\fB)x)\fR 4 |
| 409 |
.IX Item "(x(exec_text;basic_text)x)" |
| 410 |
Generates \fIexec_text\fR in exec mode, or \fIbasic_text\fR in basic mode. |
| 411 |
.IP \fB(*(\fR\fItext\fR\fB)*)\fR 4 |
| 412 |
.IX Item "(*(text)*)" |
| 413 |
Generates one copy of \fItext\fR for each indentation level. |
| 414 |
.IP \fB(*(\fR\fItext1\fR\fB;\fR\fItext2\fR\fB)*)\fR 4 |
| 415 |
.IX Item "(*(text1;text2)*)" |
| 416 |
Generates one fewer copies of \fItext1\fR than the indentation level, followed |
| 417 |
by one copy of \fItext2\fR if the indentation level is more than 0. |
| 418 |
.IP \fB(?(\fR\fItext1\fR\fB#\fR\fIvar\fR\fIText2\fR\fB)?)\fR 4 |
| 419 |
.IX Item "(?(text1#varText2)?)" |
| 420 |
If the value of \fIvar\fR is true (not empty or zero), generates the |
| 421 |
value of \fIvar\fR surrounded by \fItext1\fR and \fIText2\fR, otherwise |
| 422 |
nothing. |
| 423 |
.IP \fB~\fR 4 |
| 424 |
.IX Item "~" |
| 425 |
Any number of tildes and surrounding whitespace will be collapsed to |
| 426 |
a single space. |
| 427 |
.SS "# Variables" |
| 428 |
.IX Subsection "# Variables" |
| 429 |
These #vars represent opcode properties that you may want as part of |
| 430 |
your rendering. The '#' is intended as a private sigil; a #var's |
| 431 |
value is interpolated into the style-line, much like "read \f(CW$this\fR". |
| 432 |
.PP |
| 433 |
These vars take 3 forms: |
| 434 |
.IP \fB#\fR\fIvar\fR 4 |
| 435 |
.IX Item "#var" |
| 436 |
A property named 'var' is assumed to exist for the opcodes, and is |
| 437 |
interpolated into the rendering. |
| 438 |
.IP \fB#\fR\fIvar\fR\fIN\fR 4 |
| 439 |
.IX Item "#varN" |
| 440 |
Generates the value of \fIvar\fR, left justified to fill \fIN\fR spaces. |
| 441 |
Note that this means while you can have properties 'foo' and 'foo2', |
| 442 |
you cannot render 'foo2', but you could with 'foo2a'. You would be |
| 443 |
wise not to rely on this behavior going forward ;\-) |
| 444 |
.IP \fB#\fR\fIVar\fR 4 |
| 445 |
.IX Item "#Var" |
| 446 |
This ucfirst form of #var generates a tag-value form of itself for |
| 447 |
display; it converts '#Var' into a 'Var => #var' style, which is then |
| 448 |
handled as described above. (Imp-note: #Vars cannot be used for |
| 449 |
conditional-fills, because the => #var transform is done after the check |
| 450 |
for #Var's value). |
| 451 |
.PP |
| 452 |
The following variables are 'defined' by B::Concise; when they are |
| 453 |
used in a style, their respective values are plugged into the |
| 454 |
rendering of each opcode. |
| 455 |
.PP |
| 456 |
Only some of these are used by the standard styles, the others are |
| 457 |
provided for you to delve into optree mechanics, should you wish to |
| 458 |
add a new style (see "add_style" below) that uses them. You can |
| 459 |
also add new ones using "add_callback". |
| 460 |
.IP \fB#addr\fR 4 |
| 461 |
.IX Item "#addr" |
| 462 |
The address of the OP, in hexadecimal. |
| 463 |
.IP \fB#arg\fR 4 |
| 464 |
.IX Item "#arg" |
| 465 |
The OP-specific information of the OP (such as the SV for an SVOP, the |
| 466 |
non-local exit pointers for a LOOP, etc.) enclosed in parentheses. |
| 467 |
.IP \fB#class\fR 4 |
| 468 |
.IX Item "#class" |
| 469 |
The B\-determined class of the OP, in all caps. |
| 470 |
.IP \fB#classsym\fR 4 |
| 471 |
.IX Item "#classsym" |
| 472 |
A single symbol abbreviating the class of the OP. |
| 473 |
.IP \fB#coplabel\fR 4 |
| 474 |
.IX Item "#coplabel" |
| 475 |
The label of the statement or block the OP is the start of, if any. |
| 476 |
.IP \fB#exname\fR 4 |
| 477 |
.IX Item "#exname" |
| 478 |
The name of the OP, or 'ex\-foo' if the OP is a null that used to be a foo. |
| 479 |
.IP \fB#extarg\fR 4 |
| 480 |
.IX Item "#extarg" |
| 481 |
The target of the OP, or nothing for a nulled OP. |
| 482 |
.IP \fB#firstaddr\fR 4 |
| 483 |
.IX Item "#firstaddr" |
| 484 |
The address of the OP's first child, in hexadecimal. |
| 485 |
.IP \fB#flags\fR 4 |
| 486 |
.IX Item "#flags" |
| 487 |
The OP's flags, abbreviated as a series of symbols. |
| 488 |
.IP \fB#flagval\fR 4 |
| 489 |
.IX Item "#flagval" |
| 490 |
The numeric value of the OP's flags. |
| 491 |
.IP \fB#hints\fR 4 |
| 492 |
.IX Item "#hints" |
| 493 |
The COP's hint flags, rendered with abbreviated names if possible. An empty |
| 494 |
string if this is not a COP. Here are the symbols used: |
| 495 |
.Sp |
| 496 |
.Vb 10 |
| 497 |
\& $ strict refs |
| 498 |
\& & strict subs |
| 499 |
\& * strict vars |
| 500 |
\& x$ explicit use/no strict refs |
| 501 |
\& x& explicit use/no strict subs |
| 502 |
\& x* explicit use/no strict vars |
| 503 |
\& i integers |
| 504 |
\& l locale |
| 505 |
\& b bytes |
| 506 |
\& { block scope |
| 507 |
\& % localise %^H |
| 508 |
\& < open in |
| 509 |
\& > open out |
| 510 |
\& I overload int |
| 511 |
\& F overload float |
| 512 |
\& B overload binary |
| 513 |
\& S overload string |
| 514 |
\& R overload re |
| 515 |
\& T taint |
| 516 |
\& E eval |
| 517 |
\& X filetest access |
| 518 |
\& U utf\-8 |
| 519 |
\& |
| 520 |
\& us use feature \*(Aqunicode_strings\*(Aq |
| 521 |
\& fea=NNN feature bundle number |
| 522 |
.Ve |
| 523 |
.IP \fB#hintsval\fR 4 |
| 524 |
.IX Item "#hintsval" |
| 525 |
The numeric value of the COP's hint flags, or an empty string if this is not |
| 526 |
a COP. |
| 527 |
.IP \fB#hyphseq\fR 4 |
| 528 |
.IX Item "#hyphseq" |
| 529 |
The sequence number of the OP, or a hyphen if it doesn't have one. |
| 530 |
.IP \fB#label\fR 4 |
| 531 |
.IX Item "#label" |
| 532 |
\&'NEXT', 'LAST', or 'REDO' if the OP is a target of one of those in exec |
| 533 |
mode, or empty otherwise. |
| 534 |
.IP \fB#lastaddr\fR 4 |
| 535 |
.IX Item "#lastaddr" |
| 536 |
The address of the OP's last child, in hexadecimal. |
| 537 |
.IP \fB#name\fR 4 |
| 538 |
.IX Item "#name" |
| 539 |
The OP's name. |
| 540 |
.IP \fB#NAME\fR 4 |
| 541 |
.IX Item "#NAME" |
| 542 |
The OP's name, in all caps. |
| 543 |
.IP \fB#next\fR 4 |
| 544 |
.IX Item "#next" |
| 545 |
The sequence number of the OP's next OP. |
| 546 |
.IP \fB#nextaddr\fR 4 |
| 547 |
.IX Item "#nextaddr" |
| 548 |
The address of the OP's next OP, in hexadecimal. |
| 549 |
.IP \fB#noise\fR 4 |
| 550 |
.IX Item "#noise" |
| 551 |
A one\- or two-character abbreviation for the OP's name. |
| 552 |
.IP \fB#private\fR 4 |
| 553 |
.IX Item "#private" |
| 554 |
The OP's private flags, rendered with abbreviated names if possible. |
| 555 |
.IP \fB#privval\fR 4 |
| 556 |
.IX Item "#privval" |
| 557 |
The numeric value of the OP's private flags. |
| 558 |
.IP \fB#seq\fR 4 |
| 559 |
.IX Item "#seq" |
| 560 |
The sequence number of the OP. Note that this is a sequence number |
| 561 |
generated by B::Concise. |
| 562 |
.IP \fB#opt\fR 4 |
| 563 |
.IX Item "#opt" |
| 564 |
Whether or not the op has been optimized by the peephole optimizer. |
| 565 |
.IP \fB#sibaddr\fR 4 |
| 566 |
.IX Item "#sibaddr" |
| 567 |
The address of the OP's next youngest sibling, in hexadecimal. |
| 568 |
.IP \fB#svaddr\fR 4 |
| 569 |
.IX Item "#svaddr" |
| 570 |
The address of the OP's SV, if it has an SV, in hexadecimal. |
| 571 |
.IP \fB#svclass\fR 4 |
| 572 |
.IX Item "#svclass" |
| 573 |
The class of the OP's SV, if it has one, in all caps (e.g., 'IV'). |
| 574 |
.IP \fB#svval\fR 4 |
| 575 |
.IX Item "#svval" |
| 576 |
The value of the OP's SV, if it has one, in a short human-readable format. |
| 577 |
.IP \fB#targ\fR 4 |
| 578 |
.IX Item "#targ" |
| 579 |
The numeric value of the OP's targ. |
| 580 |
.IP \fB#targarg\fR 4 |
| 581 |
.IX Item "#targarg" |
| 582 |
The name of the variable the OP's targ refers to, if any, otherwise the |
| 583 |
letter t followed by the OP's targ in decimal. |
| 584 |
.IP \fB#targarglife\fR 4 |
| 585 |
.IX Item "#targarglife" |
| 586 |
Same as \fB#targarg\fR, but followed by the COP sequence numbers that delimit |
| 587 |
the variable's lifetime (or 'end' for a variable in an open scope) for a |
| 588 |
variable. |
| 589 |
.IP \fB#typenum\fR 4 |
| 590 |
.IX Item "#typenum" |
| 591 |
The numeric value of the OP's type, in decimal. |
| 592 |
.SH "One-Liner Command tips" |
| 593 |
.IX Header "One-Liner Command tips" |
| 594 |
.IP "perl \-MO=Concise,bar foo.pl" 4 |
| 595 |
.IX Item "perl -MO=Concise,bar foo.pl" |
| 596 |
Renders only \fBbar()\fR from foo.pl. To see main, drop the ',bar'. To see |
| 597 |
both, add ',\-main' |
| 598 |
.IP "perl \-MDigest::MD5=md5 \-MO=Concise,md5 \-e1" 4 |
| 599 |
.IX Item "perl -MDigest::MD5=md5 -MO=Concise,md5 -e1" |
| 600 |
Identifies md5 as an XS function. The export is needed so that BC can |
| 601 |
find it in main. |
| 602 |
.IP "perl \-MPOSIX \-MO=Concise,_POSIX_ARG_MAX \-e1" 4 |
| 603 |
.IX Item "perl -MPOSIX -MO=Concise,_POSIX_ARG_MAX -e1" |
| 604 |
Identifies _POSIX_ARG_MAX as a constant sub, optimized to an IV. |
| 605 |
Although POSIX isn't entirely consistent across platforms, this is |
| 606 |
likely to be present in virtually all of them. |
| 607 |
.IP "perl \-MPOSIX \-MO=Concise,a \-e 'print _POSIX_SAVED_IDS'" 4 |
| 608 |
.IX Item "perl -MPOSIX -MO=Concise,a -e 'print _POSIX_SAVED_IDS'" |
| 609 |
This renders a print statement, which includes a call to the function. |
| 610 |
It's identical to rendering a file with a use call and that single |
| 611 |
statement, except for the filename which appears in the nextstate ops. |
| 612 |
.IP "perl \-MPOSIX \-MO=Concise,a \-e 'sub a{_POSIX_SAVED_IDS}'" 4 |
| 613 |
.IX Item "perl -MPOSIX -MO=Concise,a -e 'sub a{_POSIX_SAVED_IDS}'" |
| 614 |
This is \fBvery\fR similar to previous, only the first two ops differ. This |
| 615 |
subroutine rendering is more representative, insofar as a single main |
| 616 |
program will have many subs. |
| 617 |
.IP "perl \-MB::Concise \-e 'B::Concise::compile(""\-exec"",""\-src"", \e%B::Concise::)\->()'" 4 |
| 618 |
.IX Item "perl -MB::Concise -e 'B::Concise::compile(""-exec"",""-src"", %B::Concise::)->()'" |
| 619 |
This renders all functions in the B::Concise package with the source |
| 620 |
lines. It eschews the O framework so that the stashref can be passed |
| 621 |
directly to \fBB::Concise::compile()\fR. See \-stash option for a more |
| 622 |
convenient way to render a package. |
| 623 |
.SH "Using B::Concise outside of the O framework" |
| 624 |
.IX Header "Using B::Concise outside of the O framework" |
| 625 |
The common (and original) usage of B::Concise was for command-line |
| 626 |
renderings of simple code, as given in EXAMPLE. But you can also use |
| 627 |
\&\fBB::Concise\fR from your code, and call \fBcompile()\fR directly, and |
| 628 |
repeatedly. By doing so, you can avoid the compile-time only |
| 629 |
operation of O.pm, and even use the debugger to step through |
| 630 |
\&\fBB::Concise::compile()\fR itself. |
| 631 |
.PP |
| 632 |
Once you're doing this, you may alter Concise output by adding new |
| 633 |
rendering styles, and by optionally adding callback routines which |
| 634 |
populate new variables, if such were referenced from those (just |
| 635 |
added) styles. |
| 636 |
.SS "Example: Altering Concise Renderings" |
| 637 |
.IX Subsection "Example: Altering Concise Renderings" |
| 638 |
.Vb 9 |
| 639 |
\& use B::Concise qw(set_style add_callback); |
| 640 |
\& add_style($yourStyleName => $defaultfmt, $gotofmt, $treefmt); |
| 641 |
\& add_callback |
| 642 |
\& ( sub { |
| 643 |
\& my ($h, $op, $format, $level, $stylename) = @_; |
| 644 |
\& $h\->{variable} = some_func($op); |
| 645 |
\& }); |
| 646 |
\& $walker = B::Concise::compile(@options,@subnames,@subrefs); |
| 647 |
\& $walker\->(); |
| 648 |
.Ve |
| 649 |
.SS \fBset_style()\fP |
| 650 |
.IX Subsection "set_style()" |
| 651 |
\&\fBset_style\fR accepts 3 arguments, and updates the three format-specs |
| 652 |
comprising a line-style (basic-exec, goto, tree). It has one minor |
| 653 |
drawback though; it doesn't register the style under a new name. This |
| 654 |
can become an issue if you render more than once and switch styles. |
| 655 |
Thus you may prefer to use \fBadd_style()\fR and/or \fBset_style_standard()\fR |
| 656 |
instead. |
| 657 |
.SS set_style_standard($name) |
| 658 |
.IX Subsection "set_style_standard($name)" |
| 659 |
This restores one of the standard line-styles: \f(CW\*(C`terse\*(C'\fR, \f(CW\*(C`concise\*(C'\fR, |
| 660 |
\&\f(CW\*(C`linenoise\*(C'\fR, \f(CW\*(C`debug\*(C'\fR, \f(CW\*(C`env\*(C'\fR, into effect. It also accepts style |
| 661 |
names previously defined with \fBadd_style()\fR. |
| 662 |
.SS "add_style ()" |
| 663 |
.IX Subsection "add_style ()" |
| 664 |
This subroutine accepts a new style name and three style arguments as |
| 665 |
above, and creates, registers, and selects the newly named style. It is |
| 666 |
an error to re-add a style; call \fBset_style_standard()\fR to switch between |
| 667 |
several styles. |
| 668 |
.SS "add_callback ()" |
| 669 |
.IX Subsection "add_callback ()" |
| 670 |
If your newly minted styles refer to any new #variables, you'll need |
| 671 |
to define a callback subroutine that will populate (or modify) those |
| 672 |
variables. They are then available for use in the style you've |
| 673 |
chosen. |
| 674 |
.PP |
| 675 |
The callbacks are called for each opcode visited by Concise, in the |
| 676 |
same order as they are added. Each subroutine is passed five |
| 677 |
parameters. |
| 678 |
.PP |
| 679 |
.Vb 6 |
| 680 |
\& 1. A hashref, containing the variable names and values which are |
| 681 |
\& populated into the report\-line for the op |
| 682 |
\& 2. the op, as a B<B::OP> object |
| 683 |
\& 3. a reference to the format string |
| 684 |
\& 4. the formatting (indent) level |
| 685 |
\& 5. the selected stylename |
| 686 |
.Ve |
| 687 |
.PP |
| 688 |
To define your own variables, simply add them to the hash, or change |
| 689 |
existing values if you need to. The level and format are passed in as |
| 690 |
references to scalars, but it is unlikely that they will need to be |
| 691 |
changed or even used. |
| 692 |
.SS "Running \fBB::Concise::compile()\fP" |
| 693 |
.IX Subsection "Running B::Concise::compile()" |
| 694 |
\&\fBcompile\fR accepts options as described above in "OPTIONS", and |
| 695 |
arguments, which are either coderefs, or subroutine names. |
| 696 |
.PP |
| 697 |
It constructs and returns a \f(CW$treewalker\fR coderef, which when invoked, |
| 698 |
traverses, or walks, and renders the optrees of the given arguments to |
| 699 |
STDOUT. You can reuse this, and can change the rendering style used |
| 700 |
each time; thereafter the coderef renders in the new style. |
| 701 |
.PP |
| 702 |
\&\fBwalk_output\fR lets you change the print destination from STDOUT to |
| 703 |
another open filehandle, or into a string passed as a ref (unless |
| 704 |
you've built perl with \-Uuseperlio). |
| 705 |
.PP |
| 706 |
.Vb 7 |
| 707 |
\& my $walker = B::Concise::compile(\*(Aq\-terse\*(Aq,\*(AqaFuncName\*(Aq, \e&aSubRef); # 1 |
| 708 |
\& walk_output(\emy $buf); |
| 709 |
\& $walker\->(); # 1 renders \-terse |
| 710 |
\& set_style_standard(\*(Aqconcise\*(Aq); # 2 |
| 711 |
\& $walker\->(); # 2 renders \-concise |
| 712 |
\& $walker\->(@new); # 3 renders whatever |
| 713 |
\& print "3 different renderings: terse, concise, and @new: $buf\en"; |
| 714 |
.Ve |
| 715 |
.PP |
| 716 |
When \f(CW$walker\fR is called, it traverses the subroutines supplied when it |
| 717 |
was created, and renders them using the current style. You can change |
| 718 |
the style afterwards in several different ways: |
| 719 |
.PP |
| 720 |
.Vb 3 |
| 721 |
\& 1. call C<compile>, altering style or mode/order |
| 722 |
\& 2. call C<set_style_standard> |
| 723 |
\& 3. call $walker, passing @new options |
| 724 |
.Ve |
| 725 |
.PP |
| 726 |
Passing new options to the \f(CW$walker\fR is the easiest way to change |
| 727 |
amongst any pre-defined styles (the ones you add are automatically |
| 728 |
recognized as options), and is the only way to alter rendering order |
| 729 |
without calling compile again. Note however that rendering state is |
| 730 |
still shared amongst multiple \f(CW$walker\fR objects, so they must still be |
| 731 |
used in a coordinated manner. |
| 732 |
.SS \fBB::Concise::reset_sequence()\fP |
| 733 |
.IX Subsection "B::Concise::reset_sequence()" |
| 734 |
This function (not exported) lets you reset the sequence numbers (note |
| 735 |
that they're numbered arbitrarily, their goal being to be human |
| 736 |
readable). Its purpose is mostly to support testing, i.e. to compare |
| 737 |
the concise output from two identical anonymous subroutines (but |
| 738 |
different instances). Without the reset, B::Concise, seeing that |
| 739 |
they're separate optrees, generates different sequence numbers in |
| 740 |
the output. |
| 741 |
.SS Errors |
| 742 |
.IX Subsection "Errors" |
| 743 |
Errors in rendering (non-existent function-name, non-existent coderef) |
| 744 |
are written to the STDOUT, or wherever you've set it via |
| 745 |
\&\fBwalk_output()\fR. |
| 746 |
.PP |
| 747 |
Errors using the various *style* calls, and bad args to \fBwalk_output()\fR, |
| 748 |
result in \fBdie()\fR. Use an eval if you wish to catch these errors and |
| 749 |
continue processing. |
| 750 |
.SH AUTHOR |
| 751 |
.IX Header "AUTHOR" |
| 752 |
Stephen McCamant, <[email protected]>. |