diff options
Diffstat (limited to 'upstream/archlinux/man3/B::Concise.3perl')
| -rw-r--r-- | upstream/archlinux/man3/B::Concise.3perl | 752 |
1 files changed, 752 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/B::Concise.3perl b/upstream/archlinux/man3/B::Concise.3perl new file mode 100644 index 00000000..3241b8ca --- /dev/null +++ b/upstream/archlinux/man3/B::Concise.3perl @@ -0,0 +1,752 @@ +.\" -*- 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 "B::Concise 3perl" +.TH B::Concise 3perl 2024-02-11 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" 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 +B::Concise \- Walk Perl syntax tree, printing concise info about ops +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& perl \-MO=Concise[,OPTIONS] foo.pl +\& +\& use B::Concise qw(set_style add_callback); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This compiler backend prints the internal OPs of a Perl program's syntax +tree in one of several space-efficient text formats suitable for debugging +the inner workings of perl or other compiler backends. It can print OPs in +the order they appear in the OP tree, in the order they will execute, or +in a text approximation to their tree structure, and the format of the +information displayed is customizable. Its function is similar to that of +perl's \fB\-Dx\fR debugging flag or the \fBB::Terse\fR module, but it is more +sophisticated and flexible. +.SH EXAMPLE +.IX Header "EXAMPLE" +Here's two outputs (or 'renderings'), using the \-exec and \-basic +(i.e. default) formatting conventions on the same code snippet. +.PP +.Vb 9 +\& % perl \-MO=Concise,\-exec \-e \*(Aq$a = $b + 42\*(Aq +\& 1 <0> enter +\& 2 <;> nextstate(main 1 \-e:1) v +\& 3 <#> gvsv[*b] s +\& 4 <$> const[IV 42] s +\& * 5 <2> add[t3] sK/2 +\& 6 <#> gvsv[*a] s +\& 7 <2> sassign vKS/2 +\& 8 <@> leave[1 ref] vKP/REFC +.Ve +.PP +In this \-exec rendering, each opcode is executed in the order shown. +The add opcode, marked with '*', is discussed in more detail. +.PP +The 1st column is the op's sequence number, starting at 1, and is +displayed in base 36 by default. Here they're purely linear; the +sequences are very helpful when looking at code with loops and +branches. +.PP +The symbol between angle brackets indicates the op's type, for +example; <2> is a BINOP, <@> a LISTOP, and <#> is a PADOP, which is +used in threaded perls. (see "OP class abbreviations"). +.PP +The opname, as in \fB'add[t1]'\fR, may be followed by op-specific +information in parentheses or brackets (ex \fB'[t1]'\fR). +.PP +The op-flags (ex \fB'sK/2'\fR) are described in ("OP flags +abbreviations"). +.PP +.Vb 11 +\& % perl \-MO=Concise \-e \*(Aq$a = $b + 42\*(Aq +\& 8 <@> leave[1 ref] vKP/REFC \->(end) +\& 1 <0> enter \->2 +\& 2 <;> nextstate(main 1 \-e:1) v \->3 +\& 7 <2> sassign vKS/2 \->8 +\& * 5 <2> add[t1] sK/2 \->6 +\& \- <1> ex\-rv2sv sK/1 \->4 +\& 3 <$> gvsv(*b) s \->4 +\& 4 <$> const(IV 42) s \->5 +\& \- <1> ex\-rv2sv sKRM*/1 \->7 +\& 6 <$> gvsv(*a) s \->7 +.Ve +.PP +The default rendering is top-down, so they're not in execution order. +This form reflects the way the stack is used to parse and evaluate +expressions; the add operates on the two terms below it in the tree. +.PP +Nullops appear as \f(CW\*(C`ex\-opname\*(C'\fR, where \fIopname\fR is an op that has been +optimized away by perl. They're displayed with a sequence-number of +\&'\-', because they are not executed (they don't appear in previous +example), they're printed here because they reflect the parse. +.PP +The arrow points to the sequence number of the next op; they're not +displayed in \-exec mode, for obvious reasons. +.PP +Note that because this rendering was done on a non-threaded perl, the +PADOPs in the previous examples are now SVOPs, and some (but not all) +of the square brackets have been replaced by round ones. This is a +subtle feature to provide some visual distinction between renderings +on threaded and un-threaded perls. +.SH OPTIONS +.IX Header "OPTIONS" +Arguments that don't start with a hyphen are taken to be the names of +subroutines or formats to render; if no +such functions are specified, the main +body of the program (outside any subroutines, and not including use'd +or require'd files) is rendered. Passing \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, +\&\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 +special blocks to be printed. Arguments must follow options. +.PP +Options affect how things are rendered (ie printed). They're presented +here by their visual effect, 1st being strongest. They're grouped +according to how they interrelate; within each group the options are +mutually exclusive (unless otherwise stated). +.SS "Options for Opcode Ordering" +.IX Subsection "Options for Opcode Ordering" +These options control the 'vertical display' of opcodes. The display +\&'order' is also called 'mode' elsewhere in this document. +.IP \fB\-basic\fR 4 +.IX Item "-basic" +Print OPs in the order they appear in the OP tree (a preorder +traversal, starting at the root). The indentation of each OP shows its +level in the tree, and the '\->' at the end of the line indicates the +next opcode in execution order. This mode is the default, so the flag +is included simply for completeness. +.IP \fB\-exec\fR 4 +.IX Item "-exec" +Print OPs in the order they would normally execute (for the majority +of constructs this is a postorder traversal of the tree, ending at the +root). In most cases the OP that usually follows a given OP will +appear directly below it; alternate paths are shown by indentation. In +cases like loops when control jumps out of a linear path, a 'goto' +line is generated. +.IP \fB\-tree\fR 4 +.IX Item "-tree" +Print OPs in a text approximation of a tree, with the root of the tree +at the left and 'left\-to\-right' order of children transformed into +\&'top\-to\-bottom'. Because this mode grows both to the right and down, +it isn't suitable for large programs (unless you have a very wide +terminal). +.SS "Options for Line-Style" +.IX Subsection "Options for Line-Style" +These options select the line-style (or just style) used to render +each opcode, and dictates what info is actually printed into each line. +.IP \fB\-concise\fR 4 +.IX Item "-concise" +Use the author's favorite set of formatting conventions. This is the +default, of course. +.IP \fB\-terse\fR 4 +.IX Item "-terse" +Use formatting conventions that emulate the output of \fBB::Terse\fR. The +basic mode is almost indistinguishable from the real \fBB::Terse\fR, and the +exec mode looks very similar, but is in a more logical order and lacks +curly brackets. \fBB::Terse\fR doesn't have a tree mode, so the tree mode +is only vaguely reminiscent of \fBB::Terse\fR. +.IP \fB\-linenoise\fR 4 +.IX Item "-linenoise" +Use formatting conventions in which the name of each OP, rather than being +written out in full, is represented by a one\- or two-character abbreviation. +This is mainly a joke. +.IP \fB\-debug\fR 4 +.IX Item "-debug" +Use formatting conventions reminiscent of CPAN module \fBB::Debug\fR; these aren't +very concise at all. +.IP \fB\-env\fR 4 +.IX Item "-env" +Use formatting conventions read from the environment variables +\&\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. +.SS "Options for tree-specific formatting" +.IX Subsection "Options for tree-specific formatting" +.IP \fB\-compact\fR 4 +.IX Item "-compact" +Use a tree format in which the minimum amount of space is used for the +lines connecting nodes (one character in most cases). This squeezes out +a few precious columns of screen real estate. +.IP \fB\-loose\fR 4 +.IX Item "-loose" +Use a tree format that uses longer edges to separate OP nodes. This format +tends to look better than the compact one, especially in ASCII, and is +the default. +.IP \fB\-vt\fR 4 +.IX Item "-vt" +Use tree connecting characters drawn from the VT100 line-drawing set. +This looks better if your terminal supports it. +.IP \fB\-ascii\fR 4 +.IX Item "-ascii" +Draw the tree with standard ASCII characters like \f(CW\*(C`+\*(C'\fR and \f(CW\*(C`|\*(C'\fR. These don't +look as clean as the VT100 characters, but they'll work with almost any +terminal (or the horizontal scrolling mode of \fBless\fR\|(1)) and are suitable +for text documentation or email. This is the default. +.PP +These are pairwise exclusive, i.e. compact or loose, vt or ascii. +.SS "Options controlling sequence numbering" +.IX Subsection "Options controlling sequence numbering" +.IP \fB\-base\fR\fIn\fR 4 +.IX Item "-basen" +Print OP sequence numbers in base \fIn\fR. If \fIn\fR is greater than 10, the +digit for 11 will be 'a', and so on. If \fIn\fR is greater than 36, the digit +for 37 will be 'A', and so on until 62. Values greater than 62 are not +currently supported. The default is 36. +.IP \fB\-bigendian\fR 4 +.IX Item "-bigendian" +Print sequence numbers with the most significant digit first. This is the +usual convention for Arabic numerals, and the default. +.IP \fB\-littleendian\fR 4 +.IX Item "-littleendian" +Print sequence numbers with the least significant digit first. This is +obviously mutually exclusive with bigendian. +.SS "Other options" +.IX Subsection "Other options" +.IP \fB\-src\fR 4 +.IX Item "-src" +With this option, the rendering of each statement (starting with the +nextstate OP) will be preceded by the 1st line of source code that +generates it. For example: +.Sp +.Vb 10 +\& 1 <0> enter +\& # 1: my $i; +\& 2 <;> nextstate(main 1 junk.pl:1) v:{ +\& 3 <0> padsv[$i:1,10] vM/LVINTRO +\& # 3: for $i (0..9) { +\& 4 <;> nextstate(main 3 junk.pl:3) v:{ +\& 5 <0> pushmark s +\& 6 <$> const[IV 0] s +\& 7 <$> const[IV 9] s +\& 8 <{> enteriter(next\->j last\->m redo\->9)[$i:1,10] lKS +\& k <0> iter s +\& l <|> and(other\->9) vK/1 +\& # 4: print "line "; +\& 9 <;> nextstate(main 2 junk.pl:4) v +\& a <0> pushmark s +\& b <$> const[PV "line "] s +\& c <@> print vK +\& # 5: print "$i\en"; +\& ... +.Ve +.IP "\fB\-stash=""somepackage""\fR" 4 +.IX Item "-stash=""somepackage""" +With this, "somepackage" will be required, then the stash is +inspected, and each function is rendered. +.PP +The following options are pairwise exclusive. +.IP \fB\-main\fR 4 +.IX Item "-main" +Include the main program in the output, even if subroutines were also +specified. This rendering is normally suppressed when a subroutine +name or reference is given. +.IP \fB\-nomain\fR 4 +.IX Item "-nomain" +This restores the default behavior after you've changed it with '\-main' +(it's not normally needed). If no subroutine name/ref is given, main is +rendered, regardless of this flag. +.IP \fB\-nobanner\fR 4 +.IX Item "-nobanner" +Renderings usually include a banner line identifying the function name +or stringified subref. This suppresses the printing of the banner. +.Sp +TBC: Remove the stringified coderef; while it provides a 'cookie' for +each function rendered, the cookies used should be 1,2,3.. not a +random hex-address. It also complicates string comparison of two +different trees. +.IP \fB\-banner\fR 4 +.IX Item "-banner" +restores default banner behavior. +.IP "\fB\-banneris\fR => subref" 4 +.IX Item "-banneris => subref" +TBC: a hookpoint (and an option to set it) for a user-supplied +function to produce a banner appropriate for users needs. It's not +ideal, because the rendering-state variables, which are a natural +candidate for use in concise.t, are unavailable to the user. +.SS "Option Stickiness" +.IX Subsection "Option Stickiness" +If you invoke Concise more than once in a program, you should know that +the options are 'sticky'. This means that the options you provide in +the first call will be remembered for the 2nd call, unless you +re-specify or change them. +.SH ABBREVIATIONS +.IX Header "ABBREVIATIONS" +The concise style uses symbols to convey maximum info with minimal +clutter (like hex addresses). With just a little practice, you can +start to see the flowers, not just the branches, in the trees. +.SS "OP class abbreviations" +.IX Subsection "OP class abbreviations" +These symbols appear before the op-name, and indicate the +B:: namespace that represents the ops in your Perl code. +.PP +.Vb 10 +\& 0 OP (aka BASEOP) An OP with no children +\& 1 UNOP An OP with one child +\& + UNOP_AUX A UNOP with auxillary fields +\& 2 BINOP An OP with two children +\& | LOGOP A control branch OP +\& @ LISTOP An OP that could have lots of children +\& / PMOP An OP with a regular expression +\& $ SVOP An OP with an SV +\& " PVOP An OP with a string +\& { LOOP An OP that holds pointers for a loop +\& ; COP An OP that marks the start of a statement +\& # PADOP An OP with a GV on the pad +\& . METHOP An OP with method call info +.Ve +.SS "OP flags abbreviations" +.IX Subsection "OP flags abbreviations" +OP flags are either public or private. The public flags alter the +behavior of each opcode in consistent ways, and are represented by 0 +or more single characters. +.PP +.Vb 12 +\& v OPf_WANT_VOID Want nothing (void context) +\& s OPf_WANT_SCALAR Want single value (scalar context) +\& l OPf_WANT_LIST Want list of any length (list context) +\& Want is unknown +\& K OPf_KIDS There is a firstborn child. +\& P OPf_PARENS This operator was parenthesized. +\& (Or block needs explicit scope entry.) +\& R OPf_REF Certified reference. +\& (Return container, not containee). +\& M OPf_MOD Will modify (lvalue). +\& S OPf_STACKED Some arg is arriving on the stack. +\& * OPf_SPECIAL Do something weird for this op (see op.h) +.Ve +.PP +Private flags, if any are set for an opcode, are displayed after a '/' +.PP +.Vb 2 +\& 8 <@> leave[1 ref] vKP/REFC \->(end) +\& 7 <2> sassign vKS/2 \->8 +.Ve +.PP +They're opcode specific, and occur less often than the public ones, so +they're represented by short mnemonics instead of single-chars; see +B::Op_private and \fIregen/op_private\fR for more details. +.PP +Note that a number after a '/' often indicates the number of arguments. +In the \fIsassign\fR example above, the OP takes 2 arguments. These values +are sometimes used at runtime: in particular, the MAXARG macro makes use +of them. +.SH "FORMATTING SPECIFICATIONS" +.IX Header "FORMATTING SPECIFICATIONS" +For each line-style ('concise', 'terse', 'linenoise', etc.) there are +3 format-specs which control how OPs are rendered. +.PP +The first is the 'default' format, which is used in both basic and exec +modes to print all opcodes. The 2nd, goto-format, is used in exec +mode when branches are encountered. They're not real opcodes, and are +inserted to look like a closing curly brace. The tree-format is tree +specific. +.PP +When a line is rendered, the correct format-spec is copied and scanned +for the following items; data is substituted in, and other +manipulations like basic indenting are done, for each opcode rendered. +.PP +There are 3 kinds of items that may be populated; special patterns, +#vars, and literal text, which is copied verbatim. (Yes, it's a set +of s///g steps.) +.SS "Special Patterns" +.IX Subsection "Special Patterns" +These items are the primitives used to perform indenting, and to +select text from amongst alternatives. +.IP \fB(x(\fR\fIexec_text\fR\fB;\fR\fIbasic_text\fR\fB)x)\fR 4 +.IX Item "(x(exec_text;basic_text)x)" +Generates \fIexec_text\fR in exec mode, or \fIbasic_text\fR in basic mode. +.IP \fB(*(\fR\fItext\fR\fB)*)\fR 4 +.IX Item "(*(text)*)" +Generates one copy of \fItext\fR for each indentation level. +.IP \fB(*(\fR\fItext1\fR\fB;\fR\fItext2\fR\fB)*)\fR 4 +.IX Item "(*(text1;text2)*)" +Generates one fewer copies of \fItext1\fR than the indentation level, followed +by one copy of \fItext2\fR if the indentation level is more than 0. +.IP \fB(?(\fR\fItext1\fR\fB#\fR\fIvar\fR\fIText2\fR\fB)?)\fR 4 +.IX Item "(?(text1#varText2)?)" +If the value of \fIvar\fR is true (not empty or zero), generates the +value of \fIvar\fR surrounded by \fItext1\fR and \fIText2\fR, otherwise +nothing. +.IP \fB~\fR 4 +.IX Item "~" +Any number of tildes and surrounding whitespace will be collapsed to +a single space. +.SS "# Variables" +.IX Subsection "# Variables" +These #vars represent opcode properties that you may want as part of +your rendering. The '#' is intended as a private sigil; a #var's +value is interpolated into the style-line, much like "read \f(CW$this\fR". +.PP +These vars take 3 forms: +.IP \fB#\fR\fIvar\fR 4 +.IX Item "#var" +A property named 'var' is assumed to exist for the opcodes, and is +interpolated into the rendering. +.IP \fB#\fR\fIvar\fR\fIN\fR 4 +.IX Item "#varN" +Generates the value of \fIvar\fR, left justified to fill \fIN\fR spaces. +Note that this means while you can have properties 'foo' and 'foo2', +you cannot render 'foo2', but you could with 'foo2a'. You would be +wise not to rely on this behavior going forward ;\-) +.IP \fB#\fR\fIVar\fR 4 +.IX Item "#Var" +This ucfirst form of #var generates a tag-value form of itself for +display; it converts '#Var' into a 'Var => #var' style, which is then +handled as described above. (Imp-note: #Vars cannot be used for +conditional-fills, because the => #var transform is done after the check +for #Var's value). +.PP +The following variables are 'defined' by B::Concise; when they are +used in a style, their respective values are plugged into the +rendering of each opcode. +.PP +Only some of these are used by the standard styles, the others are +provided for you to delve into optree mechanics, should you wish to +add a new style (see "add_style" below) that uses them. You can +also add new ones using "add_callback". +.IP \fB#addr\fR 4 +.IX Item "#addr" +The address of the OP, in hexadecimal. +.IP \fB#arg\fR 4 +.IX Item "#arg" +The OP-specific information of the OP (such as the SV for an SVOP, the +non-local exit pointers for a LOOP, etc.) enclosed in parentheses. +.IP \fB#class\fR 4 +.IX Item "#class" +The B\-determined class of the OP, in all caps. +.IP \fB#classsym\fR 4 +.IX Item "#classsym" +A single symbol abbreviating the class of the OP. +.IP \fB#coplabel\fR 4 +.IX Item "#coplabel" +The label of the statement or block the OP is the start of, if any. +.IP \fB#exname\fR 4 +.IX Item "#exname" +The name of the OP, or 'ex\-foo' if the OP is a null that used to be a foo. +.IP \fB#extarg\fR 4 +.IX Item "#extarg" +The target of the OP, or nothing for a nulled OP. +.IP \fB#firstaddr\fR 4 +.IX Item "#firstaddr" +The address of the OP's first child, in hexadecimal. +.IP \fB#flags\fR 4 +.IX Item "#flags" +The OP's flags, abbreviated as a series of symbols. +.IP \fB#flagval\fR 4 +.IX Item "#flagval" +The numeric value of the OP's flags. +.IP \fB#hints\fR 4 +.IX Item "#hints" +The COP's hint flags, rendered with abbreviated names if possible. An empty +string if this is not a COP. Here are the symbols used: +.Sp +.Vb 10 +\& $ strict refs +\& & strict subs +\& * strict vars +\& x$ explicit use/no strict refs +\& x& explicit use/no strict subs +\& x* explicit use/no strict vars +\& i integers +\& l locale +\& b bytes +\& { block scope +\& % localise %^H +\& < open in +\& > open out +\& I overload int +\& F overload float +\& B overload binary +\& S overload string +\& R overload re +\& T taint +\& E eval +\& X filetest access +\& U utf\-8 +\& +\& us use feature \*(Aqunicode_strings\*(Aq +\& fea=NNN feature bundle number +.Ve +.IP \fB#hintsval\fR 4 +.IX Item "#hintsval" +The numeric value of the COP's hint flags, or an empty string if this is not +a COP. +.IP \fB#hyphseq\fR 4 +.IX Item "#hyphseq" +The sequence number of the OP, or a hyphen if it doesn't have one. +.IP \fB#label\fR 4 +.IX Item "#label" +\&'NEXT', 'LAST', or 'REDO' if the OP is a target of one of those in exec +mode, or empty otherwise. +.IP \fB#lastaddr\fR 4 +.IX Item "#lastaddr" +The address of the OP's last child, in hexadecimal. +.IP \fB#name\fR 4 +.IX Item "#name" +The OP's name. +.IP \fB#NAME\fR 4 +.IX Item "#NAME" +The OP's name, in all caps. +.IP \fB#next\fR 4 +.IX Item "#next" +The sequence number of the OP's next OP. +.IP \fB#nextaddr\fR 4 +.IX Item "#nextaddr" +The address of the OP's next OP, in hexadecimal. +.IP \fB#noise\fR 4 +.IX Item "#noise" +A one\- or two-character abbreviation for the OP's name. +.IP \fB#private\fR 4 +.IX Item "#private" +The OP's private flags, rendered with abbreviated names if possible. +.IP \fB#privval\fR 4 +.IX Item "#privval" +The numeric value of the OP's private flags. +.IP \fB#seq\fR 4 +.IX Item "#seq" +The sequence number of the OP. Note that this is a sequence number +generated by B::Concise. +.IP \fB#opt\fR 4 +.IX Item "#opt" +Whether or not the op has been optimized by the peephole optimizer. +.IP \fB#sibaddr\fR 4 +.IX Item "#sibaddr" +The address of the OP's next youngest sibling, in hexadecimal. +.IP \fB#svaddr\fR 4 +.IX Item "#svaddr" +The address of the OP's SV, if it has an SV, in hexadecimal. +.IP \fB#svclass\fR 4 +.IX Item "#svclass" +The class of the OP's SV, if it has one, in all caps (e.g., 'IV'). +.IP \fB#svval\fR 4 +.IX Item "#svval" +The value of the OP's SV, if it has one, in a short human-readable format. +.IP \fB#targ\fR 4 +.IX Item "#targ" +The numeric value of the OP's targ. +.IP \fB#targarg\fR 4 +.IX Item "#targarg" +The name of the variable the OP's targ refers to, if any, otherwise the +letter t followed by the OP's targ in decimal. +.IP \fB#targarglife\fR 4 +.IX Item "#targarglife" +Same as \fB#targarg\fR, but followed by the COP sequence numbers that delimit +the variable's lifetime (or 'end' for a variable in an open scope) for a +variable. +.IP \fB#typenum\fR 4 +.IX Item "#typenum" +The numeric value of the OP's type, in decimal. +.SH "One-Liner Command tips" +.IX Header "One-Liner Command tips" +.IP "perl \-MO=Concise,bar foo.pl" 4 +.IX Item "perl -MO=Concise,bar foo.pl" +Renders only \fBbar()\fR from foo.pl. To see main, drop the ',bar'. To see +both, add ',\-main' +.IP "perl \-MDigest::MD5=md5 \-MO=Concise,md5 \-e1" 4 +.IX Item "perl -MDigest::MD5=md5 -MO=Concise,md5 -e1" +Identifies md5 as an XS function. The export is needed so that BC can +find it in main. +.IP "perl \-MPOSIX \-MO=Concise,_POSIX_ARG_MAX \-e1" 4 +.IX Item "perl -MPOSIX -MO=Concise,_POSIX_ARG_MAX -e1" +Identifies _POSIX_ARG_MAX as a constant sub, optimized to an IV. +Although POSIX isn't entirely consistent across platforms, this is +likely to be present in virtually all of them. +.IP "perl \-MPOSIX \-MO=Concise,a \-e 'print _POSIX_SAVED_IDS'" 4 +.IX Item "perl -MPOSIX -MO=Concise,a -e 'print _POSIX_SAVED_IDS'" +This renders a print statement, which includes a call to the function. +It's identical to rendering a file with a use call and that single +statement, except for the filename which appears in the nextstate ops. +.IP "perl \-MPOSIX \-MO=Concise,a \-e 'sub a{_POSIX_SAVED_IDS}'" 4 +.IX Item "perl -MPOSIX -MO=Concise,a -e 'sub a{_POSIX_SAVED_IDS}'" +This is \fBvery\fR similar to previous, only the first two ops differ. This +subroutine rendering is more representative, insofar as a single main +program will have many subs. +.IP "perl \-MB::Concise \-e 'B::Concise::compile(""\-exec"",""\-src"", \e%B::Concise::)\->()'" 4 +.IX Item "perl -MB::Concise -e 'B::Concise::compile(""-exec"",""-src"", %B::Concise::)->()'" +This renders all functions in the B::Concise package with the source +lines. It eschews the O framework so that the stashref can be passed +directly to \fBB::Concise::compile()\fR. See \-stash option for a more +convenient way to render a package. +.SH "Using B::Concise outside of the O framework" +.IX Header "Using B::Concise outside of the O framework" +The common (and original) usage of B::Concise was for command-line +renderings of simple code, as given in EXAMPLE. But you can also use +\&\fBB::Concise\fR from your code, and call \fBcompile()\fR directly, and +repeatedly. By doing so, you can avoid the compile-time only +operation of O.pm, and even use the debugger to step through +\&\fBB::Concise::compile()\fR itself. +.PP +Once you're doing this, you may alter Concise output by adding new +rendering styles, and by optionally adding callback routines which +populate new variables, if such were referenced from those (just +added) styles. +.SS "Example: Altering Concise Renderings" +.IX Subsection "Example: Altering Concise Renderings" +.Vb 9 +\& use B::Concise qw(set_style add_callback); +\& add_style($yourStyleName => $defaultfmt, $gotofmt, $treefmt); +\& add_callback +\& ( sub { +\& my ($h, $op, $format, $level, $stylename) = @_; +\& $h\->{variable} = some_func($op); +\& }); +\& $walker = B::Concise::compile(@options,@subnames,@subrefs); +\& $walker\->(); +.Ve +.SS \fBset_style()\fP +.IX Subsection "set_style()" +\&\fBset_style\fR accepts 3 arguments, and updates the three format-specs +comprising a line-style (basic-exec, goto, tree). It has one minor +drawback though; it doesn't register the style under a new name. This +can become an issue if you render more than once and switch styles. +Thus you may prefer to use \fBadd_style()\fR and/or \fBset_style_standard()\fR +instead. +.SS set_style_standard($name) +.IX Subsection "set_style_standard($name)" +This restores one of the standard line-styles: \f(CW\*(C`terse\*(C'\fR, \f(CW\*(C`concise\*(C'\fR, +\&\f(CW\*(C`linenoise\*(C'\fR, \f(CW\*(C`debug\*(C'\fR, \f(CW\*(C`env\*(C'\fR, into effect. It also accepts style +names previously defined with \fBadd_style()\fR. +.SS "add_style ()" +.IX Subsection "add_style ()" +This subroutine accepts a new style name and three style arguments as +above, and creates, registers, and selects the newly named style. It is +an error to re-add a style; call \fBset_style_standard()\fR to switch between +several styles. +.SS "add_callback ()" +.IX Subsection "add_callback ()" +If your newly minted styles refer to any new #variables, you'll need +to define a callback subroutine that will populate (or modify) those +variables. They are then available for use in the style you've +chosen. +.PP +The callbacks are called for each opcode visited by Concise, in the +same order as they are added. Each subroutine is passed five +parameters. +.PP +.Vb 6 +\& 1. A hashref, containing the variable names and values which are +\& populated into the report\-line for the op +\& 2. the op, as a B<B::OP> object +\& 3. a reference to the format string +\& 4. the formatting (indent) level +\& 5. the selected stylename +.Ve +.PP +To define your own variables, simply add them to the hash, or change +existing values if you need to. The level and format are passed in as +references to scalars, but it is unlikely that they will need to be +changed or even used. +.SS "Running \fBB::Concise::compile()\fP" +.IX Subsection "Running B::Concise::compile()" +\&\fBcompile\fR accepts options as described above in "OPTIONS", and +arguments, which are either coderefs, or subroutine names. +.PP +It constructs and returns a \f(CW$treewalker\fR coderef, which when invoked, +traverses, or walks, and renders the optrees of the given arguments to +STDOUT. You can reuse this, and can change the rendering style used +each time; thereafter the coderef renders in the new style. +.PP +\&\fBwalk_output\fR lets you change the print destination from STDOUT to +another open filehandle, or into a string passed as a ref (unless +you've built perl with \-Uuseperlio). +.PP +.Vb 7 +\& my $walker = B::Concise::compile(\*(Aq\-terse\*(Aq,\*(AqaFuncName\*(Aq, \e&aSubRef); # 1 +\& walk_output(\emy $buf); +\& $walker\->(); # 1 renders \-terse +\& set_style_standard(\*(Aqconcise\*(Aq); # 2 +\& $walker\->(); # 2 renders \-concise +\& $walker\->(@new); # 3 renders whatever +\& print "3 different renderings: terse, concise, and @new: $buf\en"; +.Ve +.PP +When \f(CW$walker\fR is called, it traverses the subroutines supplied when it +was created, and renders them using the current style. You can change +the style afterwards in several different ways: +.PP +.Vb 3 +\& 1. call C<compile>, altering style or mode/order +\& 2. call C<set_style_standard> +\& 3. call $walker, passing @new options +.Ve +.PP +Passing new options to the \f(CW$walker\fR is the easiest way to change +amongst any pre-defined styles (the ones you add are automatically +recognized as options), and is the only way to alter rendering order +without calling compile again. Note however that rendering state is +still shared amongst multiple \f(CW$walker\fR objects, so they must still be +used in a coordinated manner. +.SS \fBB::Concise::reset_sequence()\fP +.IX Subsection "B::Concise::reset_sequence()" +This function (not exported) lets you reset the sequence numbers (note +that they're numbered arbitrarily, their goal being to be human +readable). Its purpose is mostly to support testing, i.e. to compare +the concise output from two identical anonymous subroutines (but +different instances). Without the reset, B::Concise, seeing that +they're separate optrees, generates different sequence numbers in +the output. +.SS Errors +.IX Subsection "Errors" +Errors in rendering (non-existent function-name, non-existent coderef) +are written to the STDOUT, or wherever you've set it via +\&\fBwalk_output()\fR. +.PP +Errors using the various *style* calls, and bad args to \fBwalk_output()\fR, +result in \fBdie()\fR. Use an eval if you wish to catch these errors and +continue processing. +.SH AUTHOR +.IX Header "AUTHOR" +Stephen McCamant, <smcc@CSUA.Berkeley.EDU>. |