Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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>.