Debian Codegraph @

upstream/mageia-cauldron/man3pm/B::Concise.3pm

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