README.md
1# NAME
2
3Opcodes - More Opcodes information from opnames.h and opcode.h
4
5# SYNOPSIS
6
7 use Opcodes;
8 print "Empty opcodes are null and ",
9 join ",", map {opname $_}, opaliases(opname2code('null'));
10
11 # All LOGOPs
12 perl -MOpcodes -e'$,=q( );print map {opname $_} grep {opclass($_) == 2} 1..opcodes'
13
14 # Ops which can return other than op->next
15 perl -MOpcodes -e'$,=q( );print map {opname $_} grep {Opcodes::maybranch $_} 1..opcodes'
16
17
18
19# DESCRIPTION
20
21# Operator Names and Operator Lists
22
23The canonical list of operator names is the contents of the array
24PL\_op\_name, defined and initialised in file `opcode.h` of the Perl
25source distribution (and installed into the perl library).
26
27Each operator has both a terse name (its opname) and a more verbose or
28recognisable descriptive name. The opdesc function can be used to
29return a the description for an OP.
30
31- an operator name (opname)
32
33 Operator names are typically small lowercase words like enterloop,
34 leaveloop, last, next, redo etc. Sometimes they are rather cryptic
35 like gv2cv, i\_ncmp and ftsvtx.
36
37- an OP opcode
38
39 The opcode information functions all take the integer code, 0..MAX0,
40 MAXO being accessed by scalar @opcodes, the length of
41 the opcodes array.
42
43
44
45# Opcode Information
46
47Retrieve information of the Opcodes. All are available for export by the package.
48Functions names starting with "op" are automatically exported.
49
50- opcodes
51
52 In a scalar context opcodes returns the number of opcodes in this
53 version of perl (361 with perl-5.10).
54
55 In a list context it returns a list of all the operators with
56 its properties, a list of \[ opcode opname ppaddr check opargs \].
57
58- opname (OP)
59
60 Returns the lowercase name without pp\_ for the OP,
61 an integer between 0 and MAXO.
62
63- ppaddr (OP)
64
65 Returns the address of the ppaddr, which can be used to
66 get the aliases for each opcode.
67
68- check (OP)
69
70 Returns the address of the check function.
71
72- opdesc (OP)
73
74 Returns the string description of the OP.
75
76- opargs (OP)
77
78 Returns the opcode args encoded as integer of the opcode.
79 See below or `opcode.pl` for the encoding details.
80
81 opflags 1-128 + opclass 1-13 << 9 + argnum 1-15.. << 13
82
83- argnum (OP)
84
85 Returns the arguments and types encoded as number acccording
86 to the following table, 4 bit for each argument.
87
88 'S', 1, # scalar
89 'L', 2, # list
90 'A', 3, # array value
91 'H', 4, # hash value
92 'C', 5, # code value
93 'F', 6, # file value
94 'R', 7, # scalar reference
95
96 + '?', 8, # optional
97
98 Example:
99
100 argnum(opname2code('bless')) => 145
101 145 = 0b10010001 => S S?
102
103 first 4 bits 0001 => 1st arg is a Scalar,
104 next 4 bits 1001 => (bit 8+1) 2nd arg is an optional Scalar
105
106- opclass (OP)
107
108 Returns the op class as number according to the following table
109 from `opcode.pl`:
110
111 '0', 0, # baseop
112 '1', 1, # unop
113 '2', 2, # binop
114 '|', 3, # logop
115 '@', 4, # listop
116 '/', 5, # pmop
117 '$', 6, # svop_or_padop
118 '#', 7, # padop
119 '"', 8, # pvop_or_svop
120 '{', 9, # loop
121 ';', 10, # cop
122 '%', 11, # baseop_or_unop
123 '-', 12, # filestatop
124 '}', 13, # loopexop
125
126- opflags (OP)
127
128 Returns op flags as number according to the following table
129 from `opcode.pl`. In doubt see your perl source.
130 _Warning: There is currently an attempt to change that, but I posted a fix_
131
132 'm' => OA_MARK, # needs stack mark
133 'f' => OA_FOLDCONST, # fold constants
134 's' => OA_RETSCALAR, # always produces scalar
135 't' => OA_TARGET, # needs target scalar
136 'T' => OA_TARGET | OA_TARGLEX, # ... which may be lexical
137 'i' => OA_RETINTEGER, # always produces integer (this bit is in question)
138 'I' => OA_OTHERINT, # has corresponding int op
139 'd' => OA_DANGEROUS, # danger, unknown side effects
140 'u' => OA_DEFGV, # defaults to $_
141
142 plus not from `opcode.pl`:
143
144 'n' => OA_NOSTACK, # nothing on the stack, no args and return
145 'N' => OA_MAYBRANCH # No next. may return other than PL_op->op_next, maybranch
146
147 These not yet:
148
149 'S' => OA_MAYSCALAR # retval may be scalar
150 'A' => OA_MAYARRAY # retval may be array
151 'V' => OA_MAYVOID # retval may be void
152 'F' => OA_RETFIXED # fixed retval type, either S or A or V
153
154- OA\_\* constants
155
156 All OA\_ flag, class and argnum constants from `op.h` are exported.
157 Addionally new OA\_ flags have been created which are needed for [B::CC](https://metacpan.org/pod/B::CC).
158
159- opaliases (OP)
160
161 Returns the opcodes for the aliased opcode functions for the given OP, the ops
162 with the same ppaddr.
163
164- opname2code (OPNAME)
165
166 Does a reverse lookup in the opcodes list to get the opcode for the given
167 name.
168
169- maybranch (OP)
170
171 Returns if the OP function may return not op->op\_next.
172
173 Note that not all OP classes which have op->op\_other, op->op\_first or op->op\_last
174 (higher then UNOP) are actually returning an other next op than op->op\_next.
175
176 opflags(OP) & 16384
177
178# SEE ALSO
179
180[Opcode](https://metacpan.org/pod/Opcode) -- The Perl CORE Opcode module for handling sets of Opcodes used by [Safe](https://metacpan.org/pod/Safe).
181
182[Safe](https://metacpan.org/pod/Safe) -- Opcode and namespace limited execution compartments
183
184[B::CC](https://metacpan.org/pod/B::CC) -- The optimizing perl compiler uses this module. [Jit](https://metacpan.org/pod/Jit) also,
185 but only the static information
186
187# TEST REPORTS
188
189CPAN Testers: [http://cpantesters.org/distro/O/Opcodes](http://cpantesters.org/distro/O/Opcodes)
190
191[![Travis](https://travis-ci.org/rurban/Opcodes.png)](https://travis-ci.org/rurban/Opcodes/)
192
193[![Coveralls](https://coveralls.io/repos/rurban/Opcodes/badge.png)](https://coveralls.io/r/rurban/Opcodes?branch=master)
194
195# AUTHOR
196
197Reini Urban `rurban@cpan.org` 2010, 2014
198
199# LICENSE
200
201Copyright 1995, Malcom Beattie.
202Copyright 1996, Tim Bunce.
203Copyright 2010, 2014 Reini Urban.
204All rights reserved.
205
206This program is free software; you can redistribute it and/or
207modify it under the same terms as Perl itself.
208