[perl5.git] / regen / op_private

#!perl

=head1 F<regen/op_private>

This file contains all the definitions of the meanings of the flags in the
op_private field of an OP.

After editing this file, run C<make regen>. This will generate/update data
in:

    opcode.h
    lib/B/Op_private.pm

C<B::Op_private> holds three global hashes, C<%bits>, C<%defines>,
C<%labels>, which hold roughly the same information as found in this file
(after processing).

F<opcode.h> gains a series of C<OPp*> defines, and a few static data
structures:

C<PL_op_private_valid> defines, per-op, which op_private bits are legally,
allowed to be set. This is a first good place to look to see if an op has
any spare private bits.

C<PL_op_private_bitdef_ix>, C<PL_op_private_bitdefs>,
C<PL_op_private_labels>, C<PL_op_private_bitfields>,
C<PL_op_private_valid> contain (in a compact form) the data needed by
Perl_do_op_dump() to dump the op_private field of an op.

This file actually contains perl code which is run by F<regen/opcode.pl>.
The basic idea is that you keep calling addbits() to add definitions of
what a particular bit or range of bits in op_private means for a
particular op. This can be specified either as a 1-bit flag or a 1-or-more
bit bit field. Here's a general example:

    addbits('aelem',
            7 => qw(OPpLVAL_INTRO LVINTRO),
       '5..6' =>  {
                       mask_def  => 'OPpDEREF',
                       enum => [ qw(
                                   1   OPpDEREF_AV   DREFAV
                                   2   OPpDEREF_HV   DREFHV
                                   3   OPpDEREF_SV   DREFSV
                               )],
                   },
            4 => qw(OPpLVAL_DEFER LVDEFER),
    );

Here for the op C<aelem>, bits 4 and 7 (bits are numbered 0..7) are
defined as single-bit flags. The first string following the bit number is
the define name that gets emitted in F<opcode.h>, and the second string is
the label, which will be displayed by F<Concise.pm> and Perl_do_op_dump()
(as used by C<perl -Dx>).

If the bit number is actually two numbers connected with '..', then this
defines a bit field, which is 1 or more bits taken to hold a small
unsigned integer. Instead of two string arguments, it just has a single
hash ref argument. A bit field allows you to generate extra defines, such
as a mask, and optionally allows you to define an enumeration, where a
subset of the possible values of the bit field are given their own defines
and labels. The full syntax of this hash is explained further below.

Note that not all bits for a particular op need to be added in a single
addbits() call; they accumulate. In particular, this file is arranged in
two halves; first, generic flags shared by multiple ops are added, then
in the second half, specific per-op flags are added, e.g.

   addbits($_, 7 => qw(OPpLVAL_INTRO LVINTRO)) for qw(pos substr vec  ...);

   ....
   
   addbits('substr',
               4 => qw(OPpSUBSTR_REPL_FIRST REPL1ST),
               3 => ...
           );

(although the diving line between these two halves is somewhat subjective,
and is based on whether "OPp" is followed by the op name or something
generic).

There are some utility functions for generating a list of ops from
F<regen/opcodes> based on various criteria. These are:

    ops_with_check('ck_foo')
    ops_with_flag('X')
    ops_with_arg(N, 'XYZ')

which return a list of op names where:

    field 3 of regen/opcodes specifies 'ck_foo' as the check function;
    field 4 of of regen/opcodes has flag or type 'X' set;
    argument field N of of regen/opcodes matches 'XYZ';

For example

    addbits($_, 4 => qw(OPpTARGET_MY TARGMY)) for ops_with_flag('T');

If a label is specified as '-', then the flag or bit field is not
displayed symbolically by Concise/-Dx; instead the bits are treated as
unrecognised and included in the final residual integer value after all
recognised bits have been processed (this doesn't apply to individual
enum labels).

Here is a full example of a bit field hash:

    '5..6' =>  {
        mask_def      => 'OPpFOO_MASK',
        baseshift_def => 'OPpFOO_SHIFT',
        bitcount_def  => 'OPpFOO_BITS',
        label         => 'FOO',
        enum          => [ qw(
                             1   OPpFOO_A  A
                             2   OPpFOO_B  B
                             3   OPpFOO_C  C
                         )],
    };

The optional C<*_def> keys cause defines to be emitted that specify
useful values based on the bit range (5 to 6 in this case):

    mask_def:      a mask that will extract the bit field
    baseshift_def: how much to shift to make the bit field reach bit 0
    bitcount_def:  how many bits make up the bit field

The example above will generate

    #define OPpFOO_MASK 0x60
    #define OPpFOO_SHIFT   5
    #define OPpFOO_BITS    2

The optional enum list specifies a set of defines and labels for (possibly
a subset of) the possible values of the bit field (which in this example
are 0,1,2,3). If a particular value matches an enum, then it will be
displayed symbolically (e.g. 'C'), otherwise as a small integer. The
defines are suitably shifted. The example above will generate

    #define OPpFOO_A 0x20
    #define OPpFOO_B 0x40
    #define OPpFOO_C 0x60

So you can write code like

    if ((o->op_private & OPpFOO_MASK) == OPpFOO_C) ...

The optional 'label' key causes Concise/-Dx output to prefix the value
with C<LABEL=>; so in this case it might display C<FOO=C>.  If the field
value is zero, and if no label is present, and if no enum matches, then
the field isn't displayed.

=cut


use warnings;
use strict;


# ====================================================================
#
# GENERIC OPpFOO flags
#
# Flags where FOO is a generic term (like LVAL), and the flag is
# shared between multiple (possibly unrelated) ops.


{
    # The lower few bits of op_private often indicate the number of
    # arguments. This is usually set by newUNOP() and newLOGOP (to 1),
    # by newBINOP() (to 1 or 2), and by ck_fun() (to 1..15).
    #
    # These values are sometimes used at runtime: in particular,
    # the MAXARG macro extracts out the lower 4 bits.
    #
    # Some ops encroach upon these bits; for example, entersub is a unop,
    # but uses bit 0 for something else. Bit 0 is initially set to 1 in
    # newUNOP(), but is later cleared (in ck_rvconst()), when the code
    # notices that this op is an entersub.
    #
    # The important thing below is that any ops which use MAXARG at
    # runtime must have all 4 bits allocated; if bit 3 were used for a new
    # flag say, then things could break.  The information on the other
    # types of op is for completeness (so we can account for every bit
    # used in every op)

    my (%maxarg, %args0, %args1, %args2, %args3, %args4);

    # these are the functions which currently use MAXARG at runtime
    # (i.e. in the pp() functions). Thus they must always have 4 bits
    # allocated
    $maxarg{$_} = 1 for qw(
        binmode bless caller chdir close enterwrite eof exit fileno getc
        getpgrp gmtime index mkdir rand reset setpgrp sleep srand sysopen
        tell umask
    );

    # find which ops use 0,1,2,3 or 4 bits of op_private for arg count info

    $args0{$_} = 1 for qw(entersub); # UNOPs that usurp bit 0

    $args1{$_} = 1 for (
                        qw(reverse), # ck_fun(), but most bits stolen
                        grep !$maxarg{$_} && !$args0{$_},
                            ops_with_flag('1'), # UNOP
                            ops_with_flag('%'), # BASEOP/UNOP
                            ops_with_flag('|'), # LOGOP
                            ops_with_flag('-'), # FILESTATOP
                            ops_with_flag('}'), # LOOPEXOP
                    );

    $args2{$_} = 1 for (
                        qw(vec),
                        grep !$maxarg{$_} && !$args0{$_} && !$args1{$_},
                            ops_with_flag('2'), # BINOP
                            # this is a binop, but special-cased as a
                            # baseop in regen/opcodes
                            'sassign',
                    );

    $args3{$_} = 1 for grep !$maxarg{$_} && !$args0{$_}
                                            && !$args1{$_} && !$args2{$_},
                            # substr starts off with 4 bits set in
                            # ck_fun(), but since it never has more than 7
                            # args, bit 3 is later stolen
                            qw(substr);

    $args4{$_} = 1 for  keys %maxarg,
                        grep !$args0{$_} && !$args1{$_}
                                                && !$args2{$_} && !$args3{$_},
                            ops_with_check('ck_fun'),
                            # these other ck_*() functions call ck_fun()
                            ops_with_check('ck_exec'),
                            ops_with_check('ck_glob'),
                            ops_with_check('ck_index'),
                            ops_with_check('ck_join'),
                            ops_with_check('ck_lfun'),
                            ops_with_check('ck_open'),
                            ops_with_check('ck_select'),
                            ops_with_check('ck_tell'),
                            ops_with_check('ck_trunc'),
                            ;


    for (sort keys %args1) {
        addbits($_, '0..0' => {
                mask_def  => 'OPpARG1_MASK',
                label     => '-',
            }
        );
    }

    for (sort keys %args2) {
        addbits($_, '0..1' => {
                mask_def  => 'OPpARG2_MASK',
                label     => '-',
            }
        );
    }

    for (sort keys %args3) {
        addbits($_, '0..2' => {
                mask_def  => 'OPpARG3_MASK',
                label     => '-',
            }
        );
    }

    for (sort keys %args4) {
        addbits($_, '0..3' => {
                mask_def  => 'OPpARG4_MASK',
                label     => '-',
            }
        );
    }
}


# if NATIVE_HINTS is defined, op_private on cops holds the top 8 bits
# of PL_hints, although only bits 6 & 7 are officially used for that
# purpose (the rest ought to be masked off). Bit 5 is set separately

for (qw(nextstate dbstate)) {
    addbits($_,
        5 => qw(OPpHUSH_VMSISH          HUSH),
        # should match HINT_M_VMSISH_STATUS, HINT_M_VMSISH_TIME
        6 => qw(OPpHINT_M_VMSISH_STATUS VMSISH_STATUS),
        7 => qw(OPpHINT_M_VMSISH_TIME   VMSISH_TIME),

    );
}


addbits($_, 7 => qw(OPpLVAL_INTRO LVINTRO))
    for qw(pos substr vec gvsv rv2sv rv2hv rv2gv rv2av aelem helem aslice
           hslice delete padsv padav padhv enteriter entersub padrange
           pushmark cond_expr),
           'list', # this gets set in my_attrs() for some reason
           ;


# TARGLEX
#
# in constructs like my $x; ...; $x = $a + $b,
# the sassign is optimised away and OPpTARGET_MY is set on the add op

# XXX the old Concise.pm disagreed with regen/opcodes as to which ops have
# this flag: in Concise, but not T:
#       bit_and bit_or bit_xor chop complement join negate postdec postinc
#       quotemeta schop sprintf
# in T but not Concise:
#       srand

addbits($_, 4 => qw(OPpTARGET_MY TARGMY))
    for ops_with_flag('T'),
    # This flag is also used to indicate matches against implicit $_,
    # where $_ is lexical; e.g. my $_; ....; /foo/
    qw(match subst trans transr);
;


# op_targ carries a refcount
addbits($_, 6 => qw(OPpREFCOUNTED REFC))
    for qw(leave leavesub leavesublv leavewrite leaveeval);


# Do not copy return value
addbits($_, 7 => qw(OPpLVALUE LV)) for qw(leave leaveloop);


# Pattern coming in on the stack
addbits($_, 6 => qw(OPpRUNTIME RTIME))
    for qw(match subst substcont qr pushre);


# autovivify: Want ref to something
for (qw(rv2gv rv2sv padsv aelem helem entersub)) {
    addbits($_, '5..6' => {
                mask_def  => 'OPpDEREF',
                enum => [ qw(
                            1   OPpDEREF_AV   DREFAV
                            2   OPpDEREF_HV   DREFHV
                            3   OPpDEREF_SV   DREFSV
                        )],
            }
    );
}


# Defer creation of array/hash elem
addbits($_, 4 => qw(OPpLVAL_DEFER LVDEFER)) for qw(aelem helem);


addbits($_, 2 => qw(OPpSLICEWARNING SLICEWARN)) # warn about @hash{$scalar}
    for qw(rv2hv rv2av padav padhv hslice aslice);


# XXX Concise seemed to think that OPpOUR_INTRO is used in rv2gv too,
# but I can't see it - DAPM
addbits($_, 4 => qw(OPpOUR_INTRO OURINTR)) # Variable was in an our()
    for qw(gvsv rv2sv rv2av rv2hv enteriter);


# We might be an lvalue to return
addbits($_, 3 => qw(OPpMAYBE_LVSUB LVSUB))
    for qw(aassign rv2av rv2gv rv2hv padav padhv aelem helem aslice hslice
           av2arylen keys rkeys kvaslice kvhslice substr pos vec);


for (qw(rv2hv padhv)) {
    addbits($_,                           # e.g. %hash in (%hash || $foo) ...
        5 => qw(OPpTRUEBOOL       BOOL),  # ... in void cxt
        6 => qw(OPpMAYBE_TRUEBOOL BOOL?), # ... cx not known till run time
    );
}


addbits($_, 1 => qw(OPpHINT_STRICT_REFS STRICT)) for qw(rv2sv rv2av rv2hv rv2gv);


# Treat caller(1) as caller(2)
addbits($_, 7 => qw(OPpOFFBYONE  +1)) for qw(caller wantarray runcv);


# label is in UTF8 */
addbits($_, 7 => qw(OPpPV_IS_UTF8 UTF)) for qw(last redo next goto dump);


# ====================================================================
#
# OP-SPECIFIC OPpFOO_* flags:
#
# where FOO is typically the name of an op, and the flag is used by a
# single op (or maybe by a few closely related ops).


addbits($_, 4 => qw(OPpPAD_STATE STATE))  for qw(padav padhv padsv pushmark);


addbits('aassign', 6 => qw(OPpASSIGN_COMMON COMMON));


addbits('sassign',
    6 => qw(OPpASSIGN_BACKWARDS BKWARD), # Left & right switched
    7 => qw(OPpASSIGN_CV_TO_GV  CV2GV),  # Possible optimisation for constants
);


for (qw(trans transr)) {
    addbits($_,
        0 => qw(OPpTRANS_FROM_UTF   <UTF),
        1 => qw(OPpTRANS_TO_UTF     >UTF),
        2 => qw(OPpTRANS_IDENTICAL  IDENT),   # right side is same as left
        3 => qw(OPpTRANS_SQUASH     SQUASH),
        # 4 is used for OPpTARGET_MY
        5 => qw(OPpTRANS_COMPLEMENT COMPL),
        6 => qw(OPpTRANS_GROWS      GROWS),
        7 => qw(OPpTRANS_DELETE     DEL),
    );
}


addbits('repeat', 6 => qw(OPpREPEAT_DOLIST DOLIST)); # List replication


# OP_ENTERSUB and OP_RV2CV flags
#
# Flags are set on entersub and rv2cv in three phases:
#   parser  - the parser passes the flag to the op constructor
#   check   - the check routine called by the op constructor sets the flag
#   context - application of scalar/ref/lvalue context applies the flag
#
# In the third stage, an entersub op might turn into an rv2cv op (undef &foo,
# \&foo, lock &foo, exists &foo, defined &foo).  The two places where that
# happens (op_lvalue_flags and doref in op.c) need to make sure the flags do
# not conflict, since some flags with different meanings overlap between
# the two ops.  Flags applied in the context phase are only set when there
# is no conversion of op type.
#
#   bit  entersub flag       phase   rv2cv flag             phase
#   ---  -------------       -----   ----------             -----
#     0  OPpENTERSUB_INARGS  context
#     1  HINT_STRICT_REFS    check   HINT_STRICT_REFS       check
#     2  OPpENTERSUB_HASTARG check
#     3  OPpENTERSUB_AMPER   check   OPpENTERSUB_AMPER      parser
#     4  OPpENTERSUB_DB      check
#     5  OPpDEREF_AV         context
#     6  OPpDEREF_HV         context OPpMAY_RETURN_CONSTANT parser/context
#     7  OPpLVAL_INTRO       context OPpENTERSUB_NOPAREN    parser

# NB: OPpHINT_STRICT_REFS must equal HINT_STRICT_REFS

addbits('entersub',
    0      => qw(OPpENTERSUB_INARGS   INARGS), # Lval used as arg to a sub
    1      => qw(OPpHINT_STRICT_REFS  STRICT), # 'use strict' in scope
    2      => qw(OPpENTERSUB_HASTARG  TARG  ), # Called from OP tree
    3      => qw(OPpENTERSUB_AMPER    AMPER),  # Used & form to call
    4      => qw(OPpENTERSUB_DB       DBG   ), # Debug subroutine
    # 5..6 => OPpDEREF,      already defined above
    # 7    => OPpLVAL_INTRO, already defined above
);
addbits('rv2cv',
    # If a constant sub, return the constant
    1 => qw(OPpHINT_STRICT_REFS    STRICT),  # 'use strict' in scope

    3 => qw(OPpENTERSUB_AMPER      AMPER),  # Used & form to call

    6 => qw(OPpMAY_RETURN_CONSTANT CONST),
    7 => qw(OPpENTERSUB_NOPAREN    NO() ),  # bare sub call (without parens)
);

# XXX perhaps ought the clear these flags in Perl_doref when converting
# and entersub into an rv2cv???? Failing that, update the comments above
# and add them as part of the main addbits('rv2cv'.

addbits('rv2cv',
              # If a constant sub, return the constant
    2 => qw(OPpENTERSUB_HASTARG TARG),
    4 => qw(OPpENTERSUB_DB       DBG   ), # Debug subroutine
);


#foo() called before sub foo was parsed */
addbits('gv', 5 => qw(OPpEARLY_CV EARLYCV));


# 1st arg is replacement string */
addbits('substr', 4 => qw(OPpSUBSTR_REPL_FIRST REPL1ST));


addbits('padrange',
    # bits 0..6 hold target range
    '0..6' =>  {
            label         => '-',
            mask_def      => 'OPpPADRANGE_COUNTMASK',
            bitcount_def  => 'OPpPADRANGE_COUNTSHIFT',
          }
     # 7    => OPpLVAL_INTRO, already defined above
);


for (qw(aelemfast aelemfast_lex)) {
    addbits($_,
        '0..7' =>  {
                label     => '-',
              }
    );
}


addbits('rv2gv',
    2 => qw(OPpDONT_INIT_GV NOINIT), # Call gv_fetchpv with GV_NOINIT
                            # (Therefore will return whatever is currently in
                            # the symbol table, not guaranteed to be a PVGV)
    4 => qw(OPpALLOW_FAKE   FAKE),   # OK to return fake glob
);


addbits('enteriter',
                    2 => qw(OPpITER_REVERSED REVERSED),# for (reverse ...)
                    3 => qw(OPpITER_DEF      DEF),     # 'for $_' or 'for my $_'
);
addbits('iter',     2 => qw(OPpITER_REVERSED REVERSED));


addbits('const',
    1 => qw(OPpCONST_NOVER        NOVER),   # no 6;
    2 => qw(OPpCONST_SHORTCIRCUIT SHORT),   # e.g. the constant 5 in (5 || foo)
    3 => qw(OPpCONST_STRICT       STRICT),  # bareword subject to strict 'subs'
    4 => qw(OPpCONST_ENTERED      ENTERED), # Has been entered as symbol
    6 => qw(OPpCONST_BARE         BARE),    # Was a bare word (filehandle?)
);


# Range arg potentially a line num. */
addbits($_, 6 => qw(OPpFLIP_LINENUM LINENUM)) for qw(flip flop);


# Guessed that pushmark was needed. */
addbits('list', 6 => qw(OPpLIST_GUESSED GUESSED));


# Operating on a list of keys
addbits('delete', 6 => qw(OPpSLICE SLICE));
# also 7 => OPpLVAL_INTRO, already defined above


# Checking for &sub, not {} or [].
addbits('exists', 6 => qw(OPpEXISTS_SUB SUB));


addbits('sort',
    0 => qw(OPpSORT_NUMERIC  NUM    ), # Optimized away { $a <=> $b }
    1 => qw(OPpSORT_INTEGER  INT    ), # Ditto while under "use integer"
    2 => qw(OPpSORT_REVERSE  REV    ), # Reversed sort
    3 => qw(OPpSORT_INPLACE  INPLACE), # sort in-place; eg @a = sort @a
    4 => qw(OPpSORT_DESCEND  DESC   ), # Descending sort
    5 => qw(OPpSORT_QSORT    QSORT  ), # Use quicksort (not mergesort)
    6 => qw(OPpSORT_STABLE   STABLE ), # Use a stable algorithm
);


# reverse in-place (@a = reverse @a) */
addbits('reverse', 3 => qw(OPpREVERSE_INPLACE  INPLACE));


for (qw(open backtick)) {
    addbits($_,
        4 => qw(OPpOPEN_IN_RAW    INBIN ), # binmode(F,":raw")  on input  fh
        5 => qw(OPpOPEN_IN_CRLF   INCR  ), # binmode(F,":crlf") on input  fh
        6 => qw(OPpOPEN_OUT_RAW   OUTBIN), # binmode(F,":raw")  on output fh
        7 => qw(OPpOPEN_OUT_CRLF  OUTCR ), # binmode(F,":crlf") on output fh
    );
}


# The various OPpFT* filetest ops

# "use filetest 'access'" is in scope:
# this flag is set only on a subset of the FT* ops
addbits($_, 1 => qw(OPpFT_ACCESS FTACCESS)) for ops_with_arg(0, 'F-+');

# all OPpFT* ops except stat and lstat
for (grep { $_ !~ /^l?stat$/ } ops_with_flag('-')) {
    addbits($_,
        2 => qw(OPpFT_STACKED  FTSTACKED ),  # stacked filetest,
                                             #    e.g. "-f" in "-f -x $foo"
        3 => qw(OPpFT_STACKING FTSTACKING),  # stacking filetest.
                                             #    e.g. "-x" in "-f -x $foo"
        4 => qw(OPpFT_AFTER_t  FTAFTERt  ),  # previous op was -t
    );
}


addbits($_, 1 => qw(OPpGREP_LEX GREPLEX)) # iterate over lexical $_
    for qw(mapwhile mapstart grepwhile grepstart);


addbits('entereval',
    1 => qw(OPpEVAL_HAS_HH       HAS_HH ), # Does it have a copy of %^H ?
    2 => qw(OPpEVAL_UNICODE      UNI    ),
    3 => qw(OPpEVAL_BYTES        BYTES  ),
    4 => qw(OPpEVAL_COPHH        COPHH  ), # Construct %^H from COP hints
    5 => qw(OPpEVAL_RE_REPARSING REPARSE), # eval_sv(..., G_RE_REPARSING)
);


# These must not conflict with OPpDONT_INIT_GV or OPpALLOW_FAKE.
# See pp.c:S_rv2gv. */
addbits('coreargs',
    0 => qw(OPpCOREARGS_DEREF1    DEREF1), # Arg 1 is a handle constructor
    1 => qw(OPpCOREARGS_DEREF2    DEREF2), # Arg 2 is a handle constructor
   #2 reserved for OPpDONT_INIT_GV in rv2gv
   #4 reserved for OPpALLOW_FAKE   in rv2gv
    6 => qw(OPpCOREARGS_SCALARMOD $MOD  ), # \$ rather than \[$@%*]
    7 => qw(OPpCOREARGS_PUSHMARK  MARK  ), # Call pp_pushmark
);


addbits('split', 7 => qw(OPpSPLIT_IMPLIM IMPLIM)); # implicit limit

1;

# ex: set ts=8 sts=4 sw=4 et:
Commit	Line	Data
f3574cc6 DM	1	#!perl
	2
	3	=head1 F<regen/op_private>
	4
	5	This file contains all the definitions of the meanings of the flags in the
	6	op_private field of an OP.
	7
	8	After editing this file, run C<make regen>. This will generate/update data
	9	in:
	10
	11	opcode.h
	12	lib/B/Op_private.pm
	13
	14	C<B::Op_private> holds three global hashes, C<%bits>, C<%defines>,
	15	C<%labels>, which hold roughly the same information as found in this file
	16	(after processing).
	17
	18	F<opcode.h> gains a series of C<OPp*> defines, and a few static data
	19	structures:
	20
	21	C<PL_op_private_valid> defines, per-op, which op_private bits are legally,
	22	allowed to be set. This is a first good place to look to see if an op has
	23	any spare private bits.
	24
	25	C<PL_op_private_bitdef_ix>, C<PL_op_private_bitdefs>,
	26	C<PL_op_private_labels>, C<PL_op_private_bitfields>,
	27	C<PL_op_private_valid> contain (in a compact form) the data needed by
	28	Perl_do_op_dump() to dump the op_private field of an op.
	29
	30	This file actually contains perl code which is run by F<regen/opcode.pl>.
	31	The basic idea is that you keep calling addbits() to add definitions of
	32	what a particular bit or range of bits in op_private means for a
	33	particular op. This can be specified either as a 1-bit flag or a 1-or-more
	34	bit bit field. Here's a general example:
	35
	36	addbits('aelem',
	37	7 => qw(OPpLVAL_INTRO LVINTRO),
	38	'5..6' => {
	39	mask_def => 'OPpDEREF',
	40	enum => [ qw(
	41	1 OPpDEREF_AV DREFAV
	42	2 OPpDEREF_HV DREFHV
	43	3 OPpDEREF_SV DREFSV
	44	)],
	45	},
	46	4 => qw(OPpLVAL_DEFER LVDEFER),
	47	);
	48
	49	Here for the op C<aelem>, bits 4 and 7 (bits are numbered 0..7) are
	50	defined as single-bit flags. The first string following the bit number is
	51	the define name that gets emitted in F<opcode.h>, and the second string is
	52	the label, which will be displayed by F<Concise.pm> and Perl_do_op_dump()
	53	(as used by C<perl -Dx>).
	54
	55	If the bit number is actually two numbers connected with '..', then this
	56	defines a bit field, which is 1 or more bits taken to hold a small
	57	unsigned integer. Instead of two string arguments, it just has a single
	58	hash ref argument. A bit field allows you to generate extra defines, such
	59	as a mask, and optionally allows you to define an enumeration, where a
	60	subset of the possible values of the bit field are given their own defines
	61	and labels. The full syntax of this hash is explained further below.
	62
	63	Note that not all bits for a particular op need to be added in a single
	64	addbits() call; they accumulate. In particular, this file is arranged in
65	two halves; first, generic flags shared by multiple ops are added, then
66	in the second half, specific per-op flags are added, e.g.
67
68	addbits($_, 7 => qw(OPpLVAL_INTRO LVINTRO)) for qw(pos substr vec ...);
69
70	....
71
72	addbits('substr',
73	4 => qw(OPpSUBSTR_REPL_FIRST REPL1ST),
74	3 => ...
75	);
76
77	(although the diving line between these two halves is somewhat subjective,
78	and is based on whether "OPp" is followed by the op name or something
79	generic).
80
81	There are some utility functions for generating a list of ops from
82	F<regen/opcodes> based on various criteria. These are:
83
84	ops_with_check('ck_foo')
85	ops_with_flag('X')
86	ops_with_arg(N, 'XYZ')
87
88	which return a list of op names where:
89
90	field 3 of regen/opcodes specifies 'ck_foo' as the check function;
91	field 4 of of regen/opcodes has flag or type 'X' set;
92	argument field N of of regen/opcodes matches 'XYZ';
93
94	For example
95
96	addbits($_, 4 => qw(OPpTARGET_MY TARGMY)) for ops_with_flag('T');
97
98	If a label is specified as '-', then the flag or bit field is not
99	displayed symbolically by Concise/-Dx; instead the bits are treated as
100	unrecognised and included in the final residual integer value after all
101	recognised bits have been processed (this doesn't apply to individual
102	enum labels).
103
104	Here is a full example of a bit field hash:
105
106	'5..6' => {
107	mask_def => 'OPpFOO_MASK',
108	baseshift_def => 'OPpFOO_SHIFT',
109	bitcount_def => 'OPpFOO_BITS',
110	label => 'FOO',
111	enum => [ qw(
112	1 OPpFOO_A A
113	2 OPpFOO_B B
114	3 OPpFOO_C C
115	)],
116	};
117
118	The optional C<*_def> keys cause defines to be emitted that specify
119	useful values based on the bit range (5 to 6 in this case):
120
121	mask_def: a mask that will extract the bit field
122	baseshift_def: how much to shift to make the bit field reach bit 0
123	bitcount_def: how many bits make up the bit field
124
125	The example above will generate
126
127	#define OPpFOO_MASK 0x60
128	#define OPpFOO_SHIFT 5
129	#define OPpFOO_BITS 2
130
131	The optional enum list specifies a set of defines and labels for (possibly
132	a subset of) the possible values of the bit field (which in this example
133	are 0,1,2,3). If a particular value matches an enum, then it will be
134	displayed symbolically (e.g. 'C'), otherwise as a small integer. The
135	defines are suitably shifted. The example above will generate
136
137	#define OPpFOO_A 0x20
138	#define OPpFOO_B 0x40
139	#define OPpFOO_C 0x60
140
141	So you can write code like
142
143	if ((o->op_private & OPpFOO_MASK) == OPpFOO_C) ...
144
145	The optional 'label' key causes Concise/-Dx output to prefix the value
146	with C<LABEL=>; so in this case it might display C<FOO=C>. If the field
147	value is zero, and if no label is present, and if no enum matches, then
148	the field isn't displayed.
149
150	=cut
151
152
153	use warnings;
154	use strict;
155
156
157
158
159	# ====================================================================
160	#
161	# GENERIC OPpFOO flags
162	#
163	# Flags where FOO is a generic term (like LVAL), and the flag is
164	# shared between multiple (possibly unrelated) ops.
165
166
167
168
169	{
170	# The lower few bits of op_private often indicate the number of
171	# arguments. This is usually set by newUNOP() and newLOGOP (to 1),
172	# by newBINOP() (to 1 or 2), and by ck_fun() (to 1..15).
173	#
174	# These values are sometimes used at runtime: in particular,
175	# the MAXARG macro extracts out the lower 4 bits.
176	#
177	# Some ops encroach upon these bits; for example, entersub is a unop,
178	# but uses bit 0 for something else. Bit 0 is initially set to 1 in
179	# newUNOP(), but is later cleared (in ck_rvconst()), when the code
180	# notices that this op is an entersub.
181	#
182	# The important thing below is that any ops which use MAXARG at
183	# runtime must have all 4 bits allocated; if bit 3 were used for a new
184	# flag say, then things could break. The information on the other
185	# types of op is for completeness (so we can account for every bit
186	# used in every op)
187
188	my (%maxarg, %args0, %args1, %args2, %args3, %args4);
189
190	# these are the functions which currently use MAXARG at runtime
191	# (i.e. in the pp() functions). Thus they must always have 4 bits
192	# allocated
193	$maxarg{$_} = 1 for qw(
194	binmode bless caller chdir close enterwrite eof exit fileno getc
195	getpgrp gmtime index mkdir rand reset setpgrp sleep srand sysopen
196	tell umask
197	);
198
199	# find which ops use 0,1,2,3 or 4 bits of op_private for arg count info
200
201	$args0{$_} = 1 for qw(entersub); # UNOPs that usurp bit 0
202
203	$args1{$_} = 1 for (
204	qw(reverse), # ck_fun(), but most bits stolen
205	grep !$maxarg{$_} && !$args0{$_},
206	ops_with_flag('1'), # UNOP
207	ops_with_flag('%'), # BASEOP/UNOP
208	ops_with_flag('\|'), # LOGOP
209	ops_with_flag('-'), # FILESTATOP
210	ops_with_flag('}'), # LOOPEXOP
211	);
212
213	$args2{$_} = 1 for (
214	qw(vec),
215	grep !$maxarg{$_} && !$args0{$_} && !$args1{$_},
216	ops_with_flag('2'), # BINOP
217	# this is a binop, but special-cased as a
218	# baseop in regen/opcodes
219	'sassign',
220	);
221
222	$args3{$_} = 1 for grep !$maxarg{$_} && !$args0{$_}
223	&& !$args1{$_} && !$args2{$_},
224	# substr starts off with 4 bits set in
225	# ck_fun(), but since it never has more than 7
226	# args, bit 3 is later stolen
227	qw(substr);
228
229	$args4{$_} = 1 for keys %maxarg,
230	grep !$args0{$_} && !$args1{$_}
231	&& !$args2{$_} && !$args3{$_},
232	ops_with_check('ck_fun'),
233	# these other ck_*() functions call ck_fun()
234	ops_with_check('ck_exec'),
235	ops_with_check('ck_glob'),
236	ops_with_check('ck_index'),
237	ops_with_check('ck_join'),
238	ops_with_check('ck_lfun'),
239	ops_with_check('ck_open'),
240	ops_with_check('ck_select'),
241	ops_with_check('ck_tell'),
242	ops_with_check('ck_trunc'),
243	;
244
245
246	for (sort keys %args1) {
247	addbits($_, '0..0' => {
248	mask_def => 'OPpARG1_MASK',
249	label => '-',
250	}
251	);
252	}
253
254	for (sort keys %args2) {
255	addbits($_, '0..1' => {
256	mask_def => 'OPpARG2_MASK',
257	label => '-',
258	}
259	);
260	}
261
262	for (sort keys %args3) {
263	addbits($_, '0..2' => {
264	mask_def => 'OPpARG3_MASK',
265	label => '-',
266	}
267	);
268	}
269
270	for (sort keys %args4) {
271	addbits($_, '0..3' => {
272	mask_def => 'OPpARG4_MASK',
273	label => '-',
274	}
275	);
276	}
277	}
278
279
280
281	# if NATIVE_HINTS is defined, op_private on cops holds the top 8 bits
282	# of PL_hints, although only bits 6 & 7 are officially used for that
283	# purpose (the rest ought to be masked off). Bit 5 is set separately
284
285	for (qw(nextstate dbstate)) {
286	addbits($_,
287	5 => qw(OPpHUSH_VMSISH HUSH),
288	# should match HINT_M_VMSISH_STATUS, HINT_M_VMSISH_TIME
289	6 => qw(OPpHINT_M_VMSISH_STATUS VMSISH_STATUS),
290	7 => qw(OPpHINT_M_VMSISH_TIME VMSISH_TIME),
291
292	);
293	}
294
295
296
297	addbits($_, 7 => qw(OPpLVAL_INTRO LVINTRO))
298	for qw(pos substr vec gvsv rv2sv rv2hv rv2gv rv2av aelem helem aslice
299	hslice delete padsv padav padhv enteriter entersub padrange
300	pushmark cond_expr),
301	'list', # this gets set in my_attrs() for some reason
302	;
303
304
305
306	# TARGLEX
307	#
308	# in constructs like my $x; ...; $x = $a + $b,
309	# the sassign is optimised away and OPpTARGET_MY is set on the add op
310
311	# XXX the old Concise.pm disagreed with regen/opcodes as to which ops have
312	# this flag: in Concise, but not T:
313	# bit_and bit_or bit_xor chop complement join negate postdec postinc
314	# quotemeta schop sprintf
315	# in T but not Concise:
316	# srand
317
318	addbits($_, 4 => qw(OPpTARGET_MY TARGMY))
319	for ops_with_flag('T'),
320	# This flag is also used to indicate matches against implicit $_,
321	# where $_ is lexical; e.g. my $_; ....; /foo/
322	qw(match subst trans transr);
323	;
324
325
326
327
328
329	# op_targ carries a refcount
330	addbits($_, 6 => qw(OPpREFCOUNTED REFC))
331	for qw(leave leavesub leavesublv leavewrite leaveeval);
332
333
334
335	# Do not copy return value
336	addbits($_, 7 => qw(OPpLVALUE LV)) for qw(leave leaveloop);
337
338
339
340	# Pattern coming in on the stack
341	addbits($_, 6 => qw(OPpRUNTIME RTIME))
342	for qw(match subst substcont qr pushre);
343
344
345
346	# autovivify: Want ref to something
347	for (qw(rv2gv rv2sv padsv aelem helem entersub)) {
348	addbits($_, '5..6' => {
349	mask_def => 'OPpDEREF',
350	enum => [ qw(
351	1 OPpDEREF_AV DREFAV
352	2 OPpDEREF_HV DREFHV
353	3 OPpDEREF_SV DREFSV
354	)],
355	}
356	);
357	}
358
359
360
361	# Defer creation of array/hash elem
362	addbits($_, 4 => qw(OPpLVAL_DEFER LVDEFER)) for qw(aelem helem);
363
364
365
366	addbits($_, 2 => qw(OPpSLICEWARNING SLICEWARN)) # warn about @hash{$scalar}
367	for qw(rv2hv rv2av padav padhv hslice aslice);
368
369
370
371	# XXX Concise seemed to think that OPpOUR_INTRO is used in rv2gv too,
372	# but I can't see it - DAPM
373	addbits($_, 4 => qw(OPpOUR_INTRO OURINTR)) # Variable was in an our()
374	for qw(gvsv rv2sv rv2av rv2hv enteriter);
375
376
377
378	# We might be an lvalue to return
379	addbits($_, 3 => qw(OPpMAYBE_LVSUB LVSUB))
380	for qw(aassign rv2av rv2gv rv2hv padav padhv aelem helem aslice hslice
381	av2arylen keys rkeys kvaslice kvhslice substr pos vec);
382
383
384
385	for (qw(rv2hv padhv)) {
386	addbits($_, # e.g. %hash in (%hash \|\| $foo) ...
387	5 => qw(OPpTRUEBOOL BOOL), # ... in void cxt
388	6 => qw(OPpMAYBE_TRUEBOOL BOOL?), # ... cx not known till run time
389	);
390	}
391
392
393
c486bd5c	394	addbits($_, 1 => qw(OPpHINT_STRICT_REFS STRICT)) for qw(rv2sv rv2av rv2hv rv2gv);
f3574cc6 DM	395
	396
	397
	398	# Treat caller(1) as caller(2)
	399	addbits($_, 7 => qw(OPpOFFBYONE +1)) for qw(caller wantarray runcv);
	400
	401
	402
	403	# label is in UTF8 */
	404	addbits($_, 7 => qw(OPpPV_IS_UTF8 UTF)) for qw(last redo next goto dump);
	405
	406
	407
	408	# ====================================================================
	409	#
	410	# OP-SPECIFIC OPpFOO_* flags:
	411	#
	412	# where FOO is typically the name of an op, and the flag is used by a
	413	# single op (or maybe by a few closely related ops).
	414
	415
	416
	417	addbits($_, 4 => qw(OPpPAD_STATE STATE)) for qw(padav padhv padsv pushmark);
	418
	419
	420
	421	addbits('aassign', 6 => qw(OPpASSIGN_COMMON COMMON));
	422
	423
	424
	425	addbits('sassign',
	426	6 => qw(OPpASSIGN_BACKWARDS BKWARD), # Left & right switched
	427	7 => qw(OPpASSIGN_CV_TO_GV CV2GV), # Possible optimisation for constants
	428	);
	429
	430
	431
	432	for (qw(trans transr)) {
	433	addbits($_,
	434	0 => qw(OPpTRANS_FROM_UTF <UTF),
	435	1 => qw(OPpTRANS_TO_UTF >UTF),
	436	2 => qw(OPpTRANS_IDENTICAL IDENT), # right side is same as left
	437	3 => qw(OPpTRANS_SQUASH SQUASH),
	438	# 4 is used for OPpTARGET_MY
	439	5 => qw(OPpTRANS_COMPLEMENT COMPL),
	440	6 => qw(OPpTRANS_GROWS GROWS),
	441	7 => qw(OPpTRANS_DELETE DEL),
	442	);
	443	}
	444
	445
	446
	447	addbits('repeat', 6 => qw(OPpREPEAT_DOLIST DOLIST)); # List replication
	448
	449
	450
	451	# OP_ENTERSUB and OP_RV2CV flags
	452	#
	453	# Flags are set on entersub and rv2cv in three phases:
	454	# parser - the parser passes the flag to the op constructor
	455	# check - the check routine called by the op constructor sets the flag
	456	# context - application of scalar/ref/lvalue context applies the flag
	457	#
	458	# In the third stage, an entersub op might turn into an rv2cv op (undef &foo,
459	# \&foo, lock &foo, exists &foo, defined &foo). The two places where that
460	# happens (op_lvalue_flags and doref in op.c) need to make sure the flags do
461	# not conflict, since some flags with different meanings overlap between
462	# the two ops. Flags applied in the context phase are only set when there
463	# is no conversion of op type.
464	#
465	# bit entersub flag phase rv2cv flag phase
466	# --- ------------- ----- ---------- -----
467	# 0 OPpENTERSUB_INARGS context
468	# 1 HINT_STRICT_REFS check HINT_STRICT_REFS check
469	# 2 OPpENTERSUB_HASTARG check
470	# 3 OPpENTERSUB_AMPER check OPpENTERSUB_AMPER parser
471	# 4 OPpENTERSUB_DB check
472	# 5 OPpDEREF_AV context
0eb7ca05	473	# 6 OPpDEREF_HV context OPpMAY_RETURN_CONSTANT parser/context
f3574cc6 DM	474	# 7 OPpLVAL_INTRO context OPpENTERSUB_NOPAREN parser
	475
	476	# NB: OPpHINT_STRICT_REFS must equal HINT_STRICT_REFS
	477
	478	addbits('entersub',
	479	0 => qw(OPpENTERSUB_INARGS INARGS), # Lval used as arg to a sub
c486bd5c	480	1 => qw(OPpHINT_STRICT_REFS STRICT), # 'use strict' in scope
f3574cc6 DM	481	2 => qw(OPpENTERSUB_HASTARG TARG ), # Called from OP tree
	482	3 => qw(OPpENTERSUB_AMPER AMPER), # Used & form to call
	483	4 => qw(OPpENTERSUB_DB DBG ), # Debug subroutine
	484	# 5..6 => OPpDEREF, already defined above
	485	# 7 => OPpLVAL_INTRO, already defined above
	486	);
	487	addbits('rv2cv',
	488	# If a constant sub, return the constant
c486bd5c	489	1 => qw(OPpHINT_STRICT_REFS STRICT), # 'use strict' in scope
f3574cc6 DM	490
	491	3 => qw(OPpENTERSUB_AMPER AMPER), # Used & form to call
	492
	493	6 => qw(OPpMAY_RETURN_CONSTANT CONST),
	494	7 => qw(OPpENTERSUB_NOPAREN NO() ), # bare sub call (without parens)
	495	);
	496
	497	# XXX perhaps ought the clear these flags in Perl_doref when converting
	498	# and entersub into an rv2cv???? Failing that, update the comments above
	499	# and add them as part of the main addbits('rv2cv'.
	500
	501	addbits('rv2cv',
	502	# If a constant sub, return the constant
	503	2 => qw(OPpENTERSUB_HASTARG TARG),
	504	4 => qw(OPpENTERSUB_DB DBG ), # Debug subroutine
	505	);
	506
	507
	508
	509	#foo() called before sub foo was parsed */
	510	addbits('gv', 5 => qw(OPpEARLY_CV EARLYCV));
	511
	512
	513
	514	# 1st arg is replacement string */
	515	addbits('substr', 4 => qw(OPpSUBSTR_REPL_FIRST REPL1ST));
	516
	517
	518
	519	addbits('padrange',
	520	# bits 0..6 hold target range
	521	'0..6' => {
	522	label => '-',
	523	mask_def => 'OPpPADRANGE_COUNTMASK',
	524	bitcount_def => 'OPpPADRANGE_COUNTSHIFT',
	525	}
	526	# 7 => OPpLVAL_INTRO, already defined above
	527	);
	528
	529
	530
	531	for (qw(aelemfast aelemfast_lex)) {
	532	addbits($_,
	533	'0..7' => {
	534	label => '-',
	535	}
	536	);
	537	}
	538
	539
	540
	541	addbits('rv2gv',
	542	2 => qw(OPpDONT_INIT_GV NOINIT), # Call gv_fetchpv with GV_NOINIT
	543	# (Therefore will return whatever is currently in
	544	# the symbol table, not guaranteed to be a PVGV)
	545	4 => qw(OPpALLOW_FAKE FAKE), # OK to return fake glob
	546	);
	547
	548
	549
	550	addbits('enteriter',
	551	2 => qw(OPpITER_REVERSED REVERSED),# for (reverse ...)
c486bd5c	552	3 => qw(OPpITER_DEF DEF), # 'for $_' or 'for my $_'
f3574cc6 DM	553	);
	554	addbits('iter', 2 => qw(OPpITER_REVERSED REVERSED));
	555
	556
	557
	558	addbits('const',
	559	1 => qw(OPpCONST_NOVER NOVER), # no 6;
	560	2 => qw(OPpCONST_SHORTCIRCUIT SHORT), # e.g. the constant 5 in (5 \|\| foo)
	561	3 => qw(OPpCONST_STRICT STRICT), # bareword subject to strict 'subs'
	562	4 => qw(OPpCONST_ENTERED ENTERED), # Has been entered as symbol
	563	6 => qw(OPpCONST_BARE BARE), # Was a bare word (filehandle?)
	564	);
	565
	566
	567
	568	# Range arg potentially a line num. */
	569	addbits($_, 6 => qw(OPpFLIP_LINENUM LINENUM)) for qw(flip flop);
	570
	571
	572
	573	# Guessed that pushmark was needed. */
	574	addbits('list', 6 => qw(OPpLIST_GUESSED GUESSED));
	575
	576
	577
	578	# Operating on a list of keys
	579	addbits('delete', 6 => qw(OPpSLICE SLICE));
	580	# also 7 => OPpLVAL_INTRO, already defined above
	581
	582
	583
	584	# Checking for &sub, not {} or [].
	585	addbits('exists', 6 => qw(OPpEXISTS_SUB SUB));
	586
	587
	588
	589	addbits('sort',
	590	0 => qw(OPpSORT_NUMERIC NUM ), # Optimized away { $a <=> $b }
	591	1 => qw(OPpSORT_INTEGER INT ), # Ditto while under "use integer"
	592	2 => qw(OPpSORT_REVERSE REV ), # Reversed sort
	593	3 => qw(OPpSORT_INPLACE INPLACE), # sort in-place; eg @a = sort @a
	594	4 => qw(OPpSORT_DESCEND DESC ), # Descending sort
	595	5 => qw(OPpSORT_QSORT QSORT ), # Use quicksort (not mergesort)
	596	6 => qw(OPpSORT_STABLE STABLE ), # Use a stable algorithm
	597	);
	598
	599
	600
	601	# reverse in-place (@a = reverse @a) */
	602	addbits('reverse', 3 => qw(OPpREVERSE_INPLACE INPLACE));
	603
	604
	605
	606	for (qw(open backtick)) {
	607	addbits($_,
	608	4 => qw(OPpOPEN_IN_RAW INBIN ), # binmode(F,":raw") on input fh
	609	5 => qw(OPpOPEN_IN_CRLF INCR ), # binmode(F,":crlf") on input fh
	610	6 => qw(OPpOPEN_OUT_RAW OUTBIN), # binmode(F,":raw") on output fh
	611	7 => qw(OPpOPEN_OUT_CRLF OUTCR ), # binmode(F,":crlf") on output fh
	612	);
	613	}
	614
	615
	616
617	# The various OPpFT* filetest ops
618
619	# "use filetest 'access'" is in scope:
620	# this flag is set only on a subset of the FT* ops
621	addbits($_, 1 => qw(OPpFT_ACCESS FTACCESS)) for ops_with_arg(0, 'F-+');
622
623	# all OPpFT* ops except stat and lstat
624	for (grep { $_ !~ /^l?stat$/ } ops_with_flag('-')) {
625	addbits($_,
626	2 => qw(OPpFT_STACKED FTSTACKED ), # stacked filetest,
627	# e.g. "-f" in "-f -x $foo"
628	3 => qw(OPpFT_STACKING FTSTACKING), # stacking filetest.
629	# e.g. "-x" in "-f -x $foo"
630	4 => qw(OPpFT_AFTER_t FTAFTERt ), # previous op was -t
631	);
632	}
633
634
635
636	addbits($_, 1 => qw(OPpGREP_LEX GREPLEX)) # iterate over lexical $_
637	for qw(mapwhile mapstart grepwhile grepstart);
638
639
640
641	addbits('entereval',
642	1 => qw(OPpEVAL_HAS_HH HAS_HH ), # Does it have a copy of %^H ?
643	2 => qw(OPpEVAL_UNICODE UNI ),
644	3 => qw(OPpEVAL_BYTES BYTES ),
645	4 => qw(OPpEVAL_COPHH COPHH ), # Construct %^H from COP hints
c486bd5c	646	5 => qw(OPpEVAL_RE_REPARSING REPARSE), # eval_sv(..., G_RE_REPARSING)
f3574cc6 DM	647	);
	648
	649
	650
	651	# These must not conflict with OPpDONT_INIT_GV or OPpALLOW_FAKE.
	652	# See pp.c:S_rv2gv. */
	653	addbits('coreargs',
	654	0 => qw(OPpCOREARGS_DEREF1 DEREF1), # Arg 1 is a handle constructor
	655	1 => qw(OPpCOREARGS_DEREF2 DEREF2), # Arg 2 is a handle constructor
	656	#2 reserved for OPpDONT_INIT_GV in rv2gv
	657	#4 reserved for OPpALLOW_FAKE in rv2gv
	658	6 => qw(OPpCOREARGS_SCALARMOD $MOD ), # \$ rather than \[$@%*]
	659	7 => qw(OPpCOREARGS_PUSHMARK MARK ), # Call pp_pushmark
	660	);
	661
	662
	663
	664	addbits('split', 7 => qw(OPpSPLIT_IMPLIM IMPLIM)); # implicit limit
	665
	666	1;
	667
	668	# ex: set ts=8 sts=4 sw=4 et: