1 | # B.pm
|
---|
2 | #
|
---|
3 | # Copyright (c) 1996, 1997, 1998 Malcolm Beattie
|
---|
4 | #
|
---|
5 | # You may distribute under the terms of either the GNU General Public
|
---|
6 | # License or the Artistic License, as specified in the README file.
|
---|
7 | #
|
---|
8 | package B;
|
---|
9 |
|
---|
10 | our $VERSION = '1.09_01';
|
---|
11 |
|
---|
12 | use XSLoader ();
|
---|
13 | require Exporter;
|
---|
14 | @ISA = qw(Exporter);
|
---|
15 |
|
---|
16 | # walkoptree_slow comes from B.pm (you are there),
|
---|
17 | # walkoptree comes from B.xs
|
---|
18 | @EXPORT_OK = qw(minus_c ppname save_BEGINs
|
---|
19 | class peekop cast_I32 cstring cchar hash threadsv_names
|
---|
20 | main_root main_start main_cv svref_2object opnumber
|
---|
21 | amagic_generation perlstring
|
---|
22 | walkoptree_slow walkoptree walkoptree_exec walksymtable
|
---|
23 | parents comppadlist sv_undef compile_stats timing_info
|
---|
24 | begin_av init_av check_av end_av regex_padav dowarn
|
---|
25 | defstash curstash warnhook diehook inc_gv
|
---|
26 | );
|
---|
27 |
|
---|
28 | sub OPf_KIDS ();
|
---|
29 | use strict;
|
---|
30 | @B::SV::ISA = 'B::OBJECT';
|
---|
31 | @B::NULL::ISA = 'B::SV';
|
---|
32 | @B::PV::ISA = 'B::SV';
|
---|
33 | @B::IV::ISA = 'B::SV';
|
---|
34 | @B::NV::ISA = 'B::SV';
|
---|
35 | @B::RV::ISA = 'B::SV';
|
---|
36 | @B::PVIV::ISA = qw(B::PV B::IV);
|
---|
37 | @B::PVNV::ISA = qw(B::PVIV B::NV);
|
---|
38 | @B::PVMG::ISA = 'B::PVNV';
|
---|
39 | # Change in the inheritance hierarchy post 5.9.0
|
---|
40 | @B::PVLV::ISA = $] > 5.009 ? 'B::GV' : 'B::PVMG';
|
---|
41 | @B::BM::ISA = 'B::PVMG';
|
---|
42 | @B::AV::ISA = 'B::PVMG';
|
---|
43 | @B::GV::ISA = 'B::PVMG';
|
---|
44 | @B::HV::ISA = 'B::PVMG';
|
---|
45 | @B::CV::ISA = 'B::PVMG';
|
---|
46 | @B::IO::ISA = 'B::PVMG';
|
---|
47 | @B::FM::ISA = 'B::CV';
|
---|
48 |
|
---|
49 | @B::OP::ISA = 'B::OBJECT';
|
---|
50 | @B::UNOP::ISA = 'B::OP';
|
---|
51 | @B::BINOP::ISA = 'B::UNOP';
|
---|
52 | @B::LOGOP::ISA = 'B::UNOP';
|
---|
53 | @B::LISTOP::ISA = 'B::BINOP';
|
---|
54 | @B::SVOP::ISA = 'B::OP';
|
---|
55 | @B::PADOP::ISA = 'B::OP';
|
---|
56 | @B::PVOP::ISA = 'B::OP';
|
---|
57 | @B::LOOP::ISA = 'B::LISTOP';
|
---|
58 | @B::PMOP::ISA = 'B::LISTOP';
|
---|
59 | @B::COP::ISA = 'B::OP';
|
---|
60 |
|
---|
61 | @B::SPECIAL::ISA = 'B::OBJECT';
|
---|
62 |
|
---|
63 | {
|
---|
64 | # Stop "-w" from complaining about the lack of a real B::OBJECT class
|
---|
65 | package B::OBJECT;
|
---|
66 | }
|
---|
67 |
|
---|
68 | sub B::GV::SAFENAME {
|
---|
69 | my $name = (shift())->NAME;
|
---|
70 |
|
---|
71 | # The regex below corresponds to the isCONTROLVAR macro
|
---|
72 | # from toke.c
|
---|
73 |
|
---|
74 | $name =~ s/^([\cA-\cZ\c\\c[\c]\c?\c_\c^])/"^".
|
---|
75 | chr( utf8::unicode_to_native( 64 ^ ord($1) ))/e;
|
---|
76 |
|
---|
77 | # When we say unicode_to_native we really mean ascii_to_native,
|
---|
78 | # which matters iff this is a non-ASCII platform (EBCDIC).
|
---|
79 |
|
---|
80 | return $name;
|
---|
81 | }
|
---|
82 |
|
---|
83 | sub B::IV::int_value {
|
---|
84 | my ($self) = @_;
|
---|
85 | return (($self->FLAGS() & SVf_IVisUV()) ? $self->UVX : $self->IV);
|
---|
86 | }
|
---|
87 |
|
---|
88 | sub B::NULL::as_string() {""}
|
---|
89 | sub B::IV::as_string() {goto &B::IV::int_value}
|
---|
90 | sub B::PV::as_string() {goto &B::PV::PV}
|
---|
91 |
|
---|
92 | my $debug;
|
---|
93 | my $op_count = 0;
|
---|
94 | my @parents = ();
|
---|
95 |
|
---|
96 | sub debug {
|
---|
97 | my ($class, $value) = @_;
|
---|
98 | $debug = $value;
|
---|
99 | walkoptree_debug($value);
|
---|
100 | }
|
---|
101 |
|
---|
102 | sub class {
|
---|
103 | my $obj = shift;
|
---|
104 | my $name = ref $obj;
|
---|
105 | $name =~ s/^.*:://;
|
---|
106 | return $name;
|
---|
107 | }
|
---|
108 |
|
---|
109 | sub parents { \@parents }
|
---|
110 |
|
---|
111 | # For debugging
|
---|
112 | sub peekop {
|
---|
113 | my $op = shift;
|
---|
114 | return sprintf("%s (0x%x) %s", class($op), $$op, $op->name);
|
---|
115 | }
|
---|
116 |
|
---|
117 | sub walkoptree_slow {
|
---|
118 | my($op, $method, $level) = @_;
|
---|
119 | $op_count++; # just for statistics
|
---|
120 | $level ||= 0;
|
---|
121 | warn(sprintf("walkoptree: %d. %s\n", $level, peekop($op))) if $debug;
|
---|
122 | $op->$method($level);
|
---|
123 | if ($$op && ($op->flags & OPf_KIDS)) {
|
---|
124 | my $kid;
|
---|
125 | unshift(@parents, $op);
|
---|
126 | for ($kid = $op->first; $$kid; $kid = $kid->sibling) {
|
---|
127 | walkoptree_slow($kid, $method, $level + 1);
|
---|
128 | }
|
---|
129 | shift @parents;
|
---|
130 | }
|
---|
131 | if (class($op) eq 'PMOP' && ref($op->pmreplroot) && ${$op->pmreplroot}) {
|
---|
132 | unshift(@parents, $op);
|
---|
133 | walkoptree_slow($op->pmreplroot, $method, $level + 1);
|
---|
134 | shift @parents;
|
---|
135 | }
|
---|
136 | }
|
---|
137 |
|
---|
138 | sub compile_stats {
|
---|
139 | return "Total number of OPs processed: $op_count\n";
|
---|
140 | }
|
---|
141 |
|
---|
142 | sub timing_info {
|
---|
143 | my ($sec, $min, $hr) = localtime;
|
---|
144 | my ($user, $sys) = times;
|
---|
145 | sprintf("%02d:%02d:%02d user=$user sys=$sys",
|
---|
146 | $hr, $min, $sec, $user, $sys);
|
---|
147 | }
|
---|
148 |
|
---|
149 | my %symtable;
|
---|
150 |
|
---|
151 | sub clearsym {
|
---|
152 | %symtable = ();
|
---|
153 | }
|
---|
154 |
|
---|
155 | sub savesym {
|
---|
156 | my ($obj, $value) = @_;
|
---|
157 | # warn(sprintf("savesym: sym_%x => %s\n", $$obj, $value)); # debug
|
---|
158 | $symtable{sprintf("sym_%x", $$obj)} = $value;
|
---|
159 | }
|
---|
160 |
|
---|
161 | sub objsym {
|
---|
162 | my $obj = shift;
|
---|
163 | return $symtable{sprintf("sym_%x", $$obj)};
|
---|
164 | }
|
---|
165 |
|
---|
166 | sub walkoptree_exec {
|
---|
167 | my ($op, $method, $level) = @_;
|
---|
168 | $level ||= 0;
|
---|
169 | my ($sym, $ppname);
|
---|
170 | my $prefix = " " x $level;
|
---|
171 | for (; $$op; $op = $op->next) {
|
---|
172 | $sym = objsym($op);
|
---|
173 | if (defined($sym)) {
|
---|
174 | print $prefix, "goto $sym\n";
|
---|
175 | return;
|
---|
176 | }
|
---|
177 | savesym($op, sprintf("%s (0x%lx)", class($op), $$op));
|
---|
178 | $op->$method($level);
|
---|
179 | $ppname = $op->name;
|
---|
180 | if ($ppname =~
|
---|
181 | /^(d?or(assign)?|and(assign)?|mapwhile|grepwhile|entertry|range|cond_expr)$/)
|
---|
182 | {
|
---|
183 | print $prefix, uc($1), " => {\n";
|
---|
184 | walkoptree_exec($op->other, $method, $level + 1);
|
---|
185 | print $prefix, "}\n";
|
---|
186 | } elsif ($ppname eq "match" || $ppname eq "subst") {
|
---|
187 | my $pmreplstart = $op->pmreplstart;
|
---|
188 | if ($$pmreplstart) {
|
---|
189 | print $prefix, "PMREPLSTART => {\n";
|
---|
190 | walkoptree_exec($pmreplstart, $method, $level + 1);
|
---|
191 | print $prefix, "}\n";
|
---|
192 | }
|
---|
193 | } elsif ($ppname eq "substcont") {
|
---|
194 | print $prefix, "SUBSTCONT => {\n";
|
---|
195 | walkoptree_exec($op->other->pmreplstart, $method, $level + 1);
|
---|
196 | print $prefix, "}\n";
|
---|
197 | $op = $op->other;
|
---|
198 | } elsif ($ppname eq "enterloop") {
|
---|
199 | print $prefix, "REDO => {\n";
|
---|
200 | walkoptree_exec($op->redoop, $method, $level + 1);
|
---|
201 | print $prefix, "}\n", $prefix, "NEXT => {\n";
|
---|
202 | walkoptree_exec($op->nextop, $method, $level + 1);
|
---|
203 | print $prefix, "}\n", $prefix, "LAST => {\n";
|
---|
204 | walkoptree_exec($op->lastop, $method, $level + 1);
|
---|
205 | print $prefix, "}\n";
|
---|
206 | } elsif ($ppname eq "subst") {
|
---|
207 | my $replstart = $op->pmreplstart;
|
---|
208 | if ($$replstart) {
|
---|
209 | print $prefix, "SUBST => {\n";
|
---|
210 | walkoptree_exec($replstart, $method, $level + 1);
|
---|
211 | print $prefix, "}\n";
|
---|
212 | }
|
---|
213 | }
|
---|
214 | }
|
---|
215 | }
|
---|
216 |
|
---|
217 | sub walksymtable {
|
---|
218 | my ($symref, $method, $recurse, $prefix) = @_;
|
---|
219 | my $sym;
|
---|
220 | my $ref;
|
---|
221 | my $fullname;
|
---|
222 | no strict 'refs';
|
---|
223 | $prefix = '' unless defined $prefix;
|
---|
224 | while (($sym, $ref) = each %$symref) {
|
---|
225 | $fullname = "*main::".$prefix.$sym;
|
---|
226 | if ($sym =~ /::$/) {
|
---|
227 | $sym = $prefix . $sym;
|
---|
228 | if ($sym ne "main::" && $sym ne "<none>::" && &$recurse($sym)) {
|
---|
229 | walksymtable(\%$fullname, $method, $recurse, $sym);
|
---|
230 | }
|
---|
231 | } else {
|
---|
232 | svref_2object(\*$fullname)->$method();
|
---|
233 | }
|
---|
234 | }
|
---|
235 | }
|
---|
236 |
|
---|
237 | {
|
---|
238 | package B::Section;
|
---|
239 | my $output_fh;
|
---|
240 | my %sections;
|
---|
241 |
|
---|
242 | sub new {
|
---|
243 | my ($class, $section, $symtable, $default) = @_;
|
---|
244 | $output_fh ||= FileHandle->new_tmpfile;
|
---|
245 | my $obj = bless [-1, $section, $symtable, $default], $class;
|
---|
246 | $sections{$section} = $obj;
|
---|
247 | return $obj;
|
---|
248 | }
|
---|
249 |
|
---|
250 | sub get {
|
---|
251 | my ($class, $section) = @_;
|
---|
252 | return $sections{$section};
|
---|
253 | }
|
---|
254 |
|
---|
255 | sub add {
|
---|
256 | my $section = shift;
|
---|
257 | while (defined($_ = shift)) {
|
---|
258 | print $output_fh "$section->[1]\t$_\n";
|
---|
259 | $section->[0]++;
|
---|
260 | }
|
---|
261 | }
|
---|
262 |
|
---|
263 | sub index {
|
---|
264 | my $section = shift;
|
---|
265 | return $section->[0];
|
---|
266 | }
|
---|
267 |
|
---|
268 | sub name {
|
---|
269 | my $section = shift;
|
---|
270 | return $section->[1];
|
---|
271 | }
|
---|
272 |
|
---|
273 | sub symtable {
|
---|
274 | my $section = shift;
|
---|
275 | return $section->[2];
|
---|
276 | }
|
---|
277 |
|
---|
278 | sub default {
|
---|
279 | my $section = shift;
|
---|
280 | return $section->[3];
|
---|
281 | }
|
---|
282 |
|
---|
283 | sub output {
|
---|
284 | my ($section, $fh, $format) = @_;
|
---|
285 | my $name = $section->name;
|
---|
286 | my $sym = $section->symtable || {};
|
---|
287 | my $default = $section->default;
|
---|
288 |
|
---|
289 | seek($output_fh, 0, 0);
|
---|
290 | while (<$output_fh>) {
|
---|
291 | chomp;
|
---|
292 | s/^(.*?)\t//;
|
---|
293 | if ($1 eq $name) {
|
---|
294 | s{(s\\_[0-9a-f]+)} {
|
---|
295 | exists($sym->{$1}) ? $sym->{$1} : $default;
|
---|
296 | }ge;
|
---|
297 | printf $fh $format, $_;
|
---|
298 | }
|
---|
299 | }
|
---|
300 | }
|
---|
301 | }
|
---|
302 |
|
---|
303 | XSLoader::load 'B';
|
---|
304 |
|
---|
305 | 1;
|
---|
306 |
|
---|
307 | __END__
|
---|
308 |
|
---|
309 | =head1 NAME
|
---|
310 |
|
---|
311 | B - The Perl Compiler
|
---|
312 |
|
---|
313 | =head1 SYNOPSIS
|
---|
314 |
|
---|
315 | use B;
|
---|
316 |
|
---|
317 | =head1 DESCRIPTION
|
---|
318 |
|
---|
319 | The C<B> module supplies classes which allow a Perl program to delve
|
---|
320 | into its own innards. It is the module used to implement the
|
---|
321 | "backends" of the Perl compiler. Usage of the compiler does not
|
---|
322 | require knowledge of this module: see the F<O> module for the
|
---|
323 | user-visible part. The C<B> module is of use to those who want to
|
---|
324 | write new compiler backends. This documentation assumes that the
|
---|
325 | reader knows a fair amount about perl's internals including such
|
---|
326 | things as SVs, OPs and the internal symbol table and syntax tree
|
---|
327 | of a program.
|
---|
328 |
|
---|
329 | =head1 OVERVIEW
|
---|
330 |
|
---|
331 | The C<B> module contains a set of utility functions for querying the
|
---|
332 | current state of the Perl interpreter; typically these functions
|
---|
333 | return objects from the B::SV and B::OP classes, or their derived
|
---|
334 | classes. These classes in turn define methods for querying the
|
---|
335 | resulting objects about their own internal state.
|
---|
336 |
|
---|
337 | =head1 Utility Functions
|
---|
338 |
|
---|
339 | The C<B> module exports a variety of functions: some are simple
|
---|
340 | utility functions, others provide a Perl program with a way to
|
---|
341 | get an initial "handle" on an internal object.
|
---|
342 |
|
---|
343 | =head2 Functions Returning C<B::SV>, C<B::AV>, C<B::HV>, and C<B::CV> objects
|
---|
344 |
|
---|
345 | For descriptions of the class hierarchy of these objects and the
|
---|
346 | methods that can be called on them, see below, L<"OVERVIEW OF
|
---|
347 | CLASSES"> and L<"SV-RELATED CLASSES">.
|
---|
348 |
|
---|
349 | =over 4
|
---|
350 |
|
---|
351 | =item sv_undef
|
---|
352 |
|
---|
353 | Returns the SV object corresponding to the C variable C<sv_undef>.
|
---|
354 |
|
---|
355 | =item sv_yes
|
---|
356 |
|
---|
357 | Returns the SV object corresponding to the C variable C<sv_yes>.
|
---|
358 |
|
---|
359 | =item sv_no
|
---|
360 |
|
---|
361 | Returns the SV object corresponding to the C variable C<sv_no>.
|
---|
362 |
|
---|
363 | =item svref_2object(SVREF)
|
---|
364 |
|
---|
365 | Takes a reference to any Perl value, and turns the referred-to value
|
---|
366 | into an object in the appropriate B::OP-derived or B::SV-derived
|
---|
367 | class. Apart from functions such as C<main_root>, this is the primary
|
---|
368 | way to get an initial "handle" on an internal perl data structure
|
---|
369 | which can then be followed with the other access methods.
|
---|
370 |
|
---|
371 | The returned object will only be valid as long as the underlying OPs
|
---|
372 | and SVs continue to exist. Do not attempt to use the object after the
|
---|
373 | underlying structures are freed.
|
---|
374 |
|
---|
375 | =item amagic_generation
|
---|
376 |
|
---|
377 | Returns the SV object corresponding to the C variable C<amagic_generation>.
|
---|
378 |
|
---|
379 | =item init_av
|
---|
380 |
|
---|
381 | Returns the AV object (i.e. in class B::AV) representing INIT blocks.
|
---|
382 |
|
---|
383 | =item check_av
|
---|
384 |
|
---|
385 | Returns the AV object (i.e. in class B::AV) representing CHECK blocks.
|
---|
386 |
|
---|
387 | =item begin_av
|
---|
388 |
|
---|
389 | Returns the AV object (i.e. in class B::AV) representing BEGIN blocks.
|
---|
390 |
|
---|
391 | =item end_av
|
---|
392 |
|
---|
393 | Returns the AV object (i.e. in class B::AV) representing END blocks.
|
---|
394 |
|
---|
395 | =item comppadlist
|
---|
396 |
|
---|
397 | Returns the AV object (i.e. in class B::AV) of the global comppadlist.
|
---|
398 |
|
---|
399 | =item regex_padav
|
---|
400 |
|
---|
401 | Only when perl was compiled with ithreads.
|
---|
402 |
|
---|
403 | =item main_cv
|
---|
404 |
|
---|
405 | Return the (faked) CV corresponding to the main part of the Perl
|
---|
406 | program.
|
---|
407 |
|
---|
408 | =back
|
---|
409 |
|
---|
410 | =head2 Functions for Examining the Symbol Table
|
---|
411 |
|
---|
412 | =over 4
|
---|
413 |
|
---|
414 | =item walksymtable(SYMREF, METHOD, RECURSE, PREFIX)
|
---|
415 |
|
---|
416 | Walk the symbol table starting at SYMREF and call METHOD on each
|
---|
417 | symbol (a B::GV object) visited. When the walk reaches package
|
---|
418 | symbols (such as "Foo::") it invokes RECURSE, passing in the symbol
|
---|
419 | name, and only recurses into the package if that sub returns true.
|
---|
420 |
|
---|
421 | PREFIX is the name of the SYMREF you're walking.
|
---|
422 |
|
---|
423 | For example:
|
---|
424 |
|
---|
425 | # Walk CGI's symbol table calling print_subs on each symbol.
|
---|
426 | # Recurse only into CGI::Util::
|
---|
427 | walksymtable(\%CGI::, 'print_subs', sub { $_[0] eq 'CGI::Util::' },
|
---|
428 | 'CGI::');
|
---|
429 |
|
---|
430 | print_subs() is a B::GV method you have declared. Also see L<"B::GV
|
---|
431 | Methods">, below.
|
---|
432 |
|
---|
433 | =back
|
---|
434 |
|
---|
435 | =head2 Functions Returning C<B::OP> objects or for walking op trees
|
---|
436 |
|
---|
437 | For descriptions of the class hierarchy of these objects and the
|
---|
438 | methods that can be called on them, see below, L<"OVERVIEW OF
|
---|
439 | CLASSES"> and L<"OP-RELATED CLASSES">.
|
---|
440 |
|
---|
441 | =over 4
|
---|
442 |
|
---|
443 | =item main_root
|
---|
444 |
|
---|
445 | Returns the root op (i.e. an object in the appropriate B::OP-derived
|
---|
446 | class) of the main part of the Perl program.
|
---|
447 |
|
---|
448 | =item main_start
|
---|
449 |
|
---|
450 | Returns the starting op of the main part of the Perl program.
|
---|
451 |
|
---|
452 | =item walkoptree(OP, METHOD)
|
---|
453 |
|
---|
454 | Does a tree-walk of the syntax tree based at OP and calls METHOD on
|
---|
455 | each op it visits. Each node is visited before its children. If
|
---|
456 | C<walkoptree_debug> (see below) has been called to turn debugging on then
|
---|
457 | the method C<walkoptree_debug> is called on each op before METHOD is
|
---|
458 | called.
|
---|
459 |
|
---|
460 | =item walkoptree_debug(DEBUG)
|
---|
461 |
|
---|
462 | Returns the current debugging flag for C<walkoptree>. If the optional
|
---|
463 | DEBUG argument is non-zero, it sets the debugging flag to that. See
|
---|
464 | the description of C<walkoptree> above for what the debugging flag
|
---|
465 | does.
|
---|
466 |
|
---|
467 | =back
|
---|
468 |
|
---|
469 | =head2 Miscellaneous Utility Functions
|
---|
470 |
|
---|
471 | =over 4
|
---|
472 |
|
---|
473 | =item ppname(OPNUM)
|
---|
474 |
|
---|
475 | Return the PP function name (e.g. "pp_add") of op number OPNUM.
|
---|
476 |
|
---|
477 | =item hash(STR)
|
---|
478 |
|
---|
479 | Returns a string in the form "0x..." representing the value of the
|
---|
480 | internal hash function used by perl on string STR.
|
---|
481 |
|
---|
482 | =item cast_I32(I)
|
---|
483 |
|
---|
484 | Casts I to the internal I32 type used by that perl.
|
---|
485 |
|
---|
486 | =item minus_c
|
---|
487 |
|
---|
488 | Does the equivalent of the C<-c> command-line option. Obviously, this
|
---|
489 | is only useful in a BEGIN block or else the flag is set too late.
|
---|
490 |
|
---|
491 | =item cstring(STR)
|
---|
492 |
|
---|
493 | Returns a double-quote-surrounded escaped version of STR which can
|
---|
494 | be used as a string in C source code.
|
---|
495 |
|
---|
496 | =item perlstring(STR)
|
---|
497 |
|
---|
498 | Returns a double-quote-surrounded escaped version of STR which can
|
---|
499 | be used as a string in Perl source code.
|
---|
500 |
|
---|
501 | =item class(OBJ)
|
---|
502 |
|
---|
503 | Returns the class of an object without the part of the classname
|
---|
504 | preceding the first C<"::">. This is used to turn C<"B::UNOP"> into
|
---|
505 | C<"UNOP"> for example.
|
---|
506 |
|
---|
507 | =item threadsv_names
|
---|
508 |
|
---|
509 | In a perl compiled for threads, this returns a list of the special
|
---|
510 | per-thread threadsv variables.
|
---|
511 |
|
---|
512 | =back
|
---|
513 |
|
---|
514 |
|
---|
515 |
|
---|
516 |
|
---|
517 | =head1 OVERVIEW OF CLASSES
|
---|
518 |
|
---|
519 | The C structures used by Perl's internals to hold SV and OP
|
---|
520 | information (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a
|
---|
521 | class hierarchy and the C<B> module gives access to them via a true
|
---|
522 | object hierarchy. Structure fields which point to other objects
|
---|
523 | (whether types of SV or types of OP) are represented by the C<B>
|
---|
524 | module as Perl objects of the appropriate class.
|
---|
525 |
|
---|
526 | The bulk of the C<B> module is the methods for accessing fields of
|
---|
527 | these structures.
|
---|
528 |
|
---|
529 | Note that all access is read-only. You cannot modify the internals by
|
---|
530 | using this module. Also, note that the B::OP and B::SV objects created
|
---|
531 | by this module are only valid for as long as the underlying objects
|
---|
532 | exist; their creation doesn't increase the reference counts of the
|
---|
533 | underlying objects. Trying to access the fields of a freed object will
|
---|
534 | give incomprehensible results, or worse.
|
---|
535 |
|
---|
536 | =head2 SV-RELATED CLASSES
|
---|
537 |
|
---|
538 | B::IV, B::NV, B::RV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::BM, B::PVLV,
|
---|
539 | B::AV, B::HV, B::CV, B::GV, B::FM, B::IO. These classes correspond in
|
---|
540 | the obvious way to the underlying C structures of similar names. The
|
---|
541 | inheritance hierarchy mimics the underlying C "inheritance". For 5.9.1
|
---|
542 | and later this is:
|
---|
543 |
|
---|
544 | B::SV
|
---|
545 | |
|
---|
546 | +--------------+----------+------------+
|
---|
547 | | | | |
|
---|
548 | B::PV B::IV B::NV B::RV
|
---|
549 | \ / /
|
---|
550 | \ / /
|
---|
551 | B::PVIV /
|
---|
552 | \ /
|
---|
553 | \ /
|
---|
554 | \ /
|
---|
555 | B::PVNV
|
---|
556 | |
|
---|
557 | |
|
---|
558 | B::PVMG
|
---|
559 | |
|
---|
560 | +-----+----+------+-----+-----+
|
---|
561 | | | | | | |
|
---|
562 | B::BM B::AV B::GV B::HV B::CV B::IO
|
---|
563 | | |
|
---|
564 | B::PVLV |
|
---|
565 | B::FM
|
---|
566 |
|
---|
567 |
|
---|
568 | For 5.9.0 and earlier, PVLV is a direct subclass of PVMG, so the base
|
---|
569 | of this diagram is
|
---|
570 |
|
---|
571 | |
|
---|
572 | B::PVMG
|
---|
573 | |
|
---|
574 | +------+-----+----+------+-----+-----+
|
---|
575 | | | | | | | |
|
---|
576 | B::PVLV B::BM B::AV B::GV B::HV B::CV B::IO
|
---|
577 | |
|
---|
578 | |
|
---|
579 | B::FM
|
---|
580 |
|
---|
581 |
|
---|
582 | Access methods correspond to the underlying C macros for field access,
|
---|
583 | usually with the leading "class indication" prefix removed (Sv, Av,
|
---|
584 | Hv, ...). The leading prefix is only left in cases where its removal
|
---|
585 | would cause a clash in method name. For example, C<GvREFCNT> stays
|
---|
586 | as-is since its abbreviation would clash with the "superclass" method
|
---|
587 | C<REFCNT> (corresponding to the C function C<SvREFCNT>).
|
---|
588 |
|
---|
589 | =head2 B::SV Methods
|
---|
590 |
|
---|
591 | =over 4
|
---|
592 |
|
---|
593 | =item REFCNT
|
---|
594 |
|
---|
595 | =item FLAGS
|
---|
596 |
|
---|
597 | =item object_2svref
|
---|
598 |
|
---|
599 | Returns a reference to the regular scalar corresponding to this
|
---|
600 | B::SV object. In other words, this method is the inverse operation
|
---|
601 | to the svref_2object() subroutine. This scalar and other data it points
|
---|
602 | at should be considered read-only: modifying them is neither safe nor
|
---|
603 | guaranteed to have a sensible effect.
|
---|
604 |
|
---|
605 | =back
|
---|
606 |
|
---|
607 | =head2 B::IV Methods
|
---|
608 |
|
---|
609 | =over 4
|
---|
610 |
|
---|
611 | =item IV
|
---|
612 |
|
---|
613 | Returns the value of the IV, I<interpreted as
|
---|
614 | a signed integer>. This will be misleading
|
---|
615 | if C<FLAGS & SVf_IVisUV>. Perhaps you want the
|
---|
616 | C<int_value> method instead?
|
---|
617 |
|
---|
618 | =item IVX
|
---|
619 |
|
---|
620 | =item UVX
|
---|
621 |
|
---|
622 | =item int_value
|
---|
623 |
|
---|
624 | This method returns the value of the IV as an integer.
|
---|
625 | It differs from C<IV> in that it returns the correct
|
---|
626 | value regardless of whether it's stored signed or
|
---|
627 | unsigned.
|
---|
628 |
|
---|
629 | =item needs64bits
|
---|
630 |
|
---|
631 | =item packiv
|
---|
632 |
|
---|
633 | =back
|
---|
634 |
|
---|
635 | =head2 B::NV Methods
|
---|
636 |
|
---|
637 | =over 4
|
---|
638 |
|
---|
639 | =item NV
|
---|
640 |
|
---|
641 | =item NVX
|
---|
642 |
|
---|
643 | =back
|
---|
644 |
|
---|
645 | =head2 B::RV Methods
|
---|
646 |
|
---|
647 | =over 4
|
---|
648 |
|
---|
649 | =item RV
|
---|
650 |
|
---|
651 | =back
|
---|
652 |
|
---|
653 | =head2 B::PV Methods
|
---|
654 |
|
---|
655 | =over 4
|
---|
656 |
|
---|
657 | =item PV
|
---|
658 |
|
---|
659 | This method is the one you usually want. It constructs a
|
---|
660 | string using the length and offset information in the struct:
|
---|
661 | for ordinary scalars it will return the string that you'd see
|
---|
662 | from Perl, even if it contains null characters.
|
---|
663 |
|
---|
664 | =item RV
|
---|
665 |
|
---|
666 | Same as B::RV::RV, except that it will die() if the PV isn't
|
---|
667 | a reference.
|
---|
668 |
|
---|
669 | =item PVX
|
---|
670 |
|
---|
671 | This method is less often useful. It assumes that the string
|
---|
672 | stored in the struct is null-terminated, and disregards the
|
---|
673 | length information.
|
---|
674 |
|
---|
675 | It is the appropriate method to use if you need to get the name
|
---|
676 | of a lexical variable from a padname array. Lexical variable names
|
---|
677 | are always stored with a null terminator, and the length field
|
---|
678 | (SvCUR) is overloaded for other purposes and can't be relied on here.
|
---|
679 |
|
---|
680 | =back
|
---|
681 |
|
---|
682 | =head2 B::PVMG Methods
|
---|
683 |
|
---|
684 | =over 4
|
---|
685 |
|
---|
686 | =item MAGIC
|
---|
687 |
|
---|
688 | =item SvSTASH
|
---|
689 |
|
---|
690 | =back
|
---|
691 |
|
---|
692 | =head2 B::MAGIC Methods
|
---|
693 |
|
---|
694 | =over 4
|
---|
695 |
|
---|
696 | =item MOREMAGIC
|
---|
697 |
|
---|
698 | =item precomp
|
---|
699 |
|
---|
700 | Only valid on r-magic, returns the string that generated the regexp.
|
---|
701 |
|
---|
702 | =item PRIVATE
|
---|
703 |
|
---|
704 | =item TYPE
|
---|
705 |
|
---|
706 | =item FLAGS
|
---|
707 |
|
---|
708 | =item OBJ
|
---|
709 |
|
---|
710 | Will die() if called on r-magic.
|
---|
711 |
|
---|
712 | =item PTR
|
---|
713 |
|
---|
714 | =item REGEX
|
---|
715 |
|
---|
716 | Only valid on r-magic, returns the integer value of the REGEX stored
|
---|
717 | in the MAGIC.
|
---|
718 |
|
---|
719 | =back
|
---|
720 |
|
---|
721 | =head2 B::PVLV Methods
|
---|
722 |
|
---|
723 | =over 4
|
---|
724 |
|
---|
725 | =item TARGOFF
|
---|
726 |
|
---|
727 | =item TARGLEN
|
---|
728 |
|
---|
729 | =item TYPE
|
---|
730 |
|
---|
731 | =item TARG
|
---|
732 |
|
---|
733 | =back
|
---|
734 |
|
---|
735 | =head2 B::BM Methods
|
---|
736 |
|
---|
737 | =over 4
|
---|
738 |
|
---|
739 | =item USEFUL
|
---|
740 |
|
---|
741 | =item PREVIOUS
|
---|
742 |
|
---|
743 | =item RARE
|
---|
744 |
|
---|
745 | =item TABLE
|
---|
746 |
|
---|
747 | =back
|
---|
748 |
|
---|
749 | =head2 B::GV Methods
|
---|
750 |
|
---|
751 | =over 4
|
---|
752 |
|
---|
753 | =item is_empty
|
---|
754 |
|
---|
755 | This method returns TRUE if the GP field of the GV is NULL.
|
---|
756 |
|
---|
757 | =item NAME
|
---|
758 |
|
---|
759 | =item SAFENAME
|
---|
760 |
|
---|
761 | This method returns the name of the glob, but if the first
|
---|
762 | character of the name is a control character, then it converts
|
---|
763 | it to ^X first, so that *^G would return "^G" rather than "\cG".
|
---|
764 |
|
---|
765 | It's useful if you want to print out the name of a variable.
|
---|
766 | If you restrict yourself to globs which exist at compile-time
|
---|
767 | then the result ought to be unambiguous, because code like
|
---|
768 | C<${"^G"} = 1> is compiled as two ops - a constant string and
|
---|
769 | a dereference (rv2gv) - so that the glob is created at runtime.
|
---|
770 |
|
---|
771 | If you're working with globs at runtime, and need to disambiguate
|
---|
772 | *^G from *{"^G"}, then you should use the raw NAME method.
|
---|
773 |
|
---|
774 | =item STASH
|
---|
775 |
|
---|
776 | =item SV
|
---|
777 |
|
---|
778 | =item IO
|
---|
779 |
|
---|
780 | =item FORM
|
---|
781 |
|
---|
782 | =item AV
|
---|
783 |
|
---|
784 | =item HV
|
---|
785 |
|
---|
786 | =item EGV
|
---|
787 |
|
---|
788 | =item CV
|
---|
789 |
|
---|
790 | =item CVGEN
|
---|
791 |
|
---|
792 | =item LINE
|
---|
793 |
|
---|
794 | =item FILE
|
---|
795 |
|
---|
796 | =item FILEGV
|
---|
797 |
|
---|
798 | =item GvREFCNT
|
---|
799 |
|
---|
800 | =item FLAGS
|
---|
801 |
|
---|
802 | =back
|
---|
803 |
|
---|
804 | =head2 B::IO Methods
|
---|
805 |
|
---|
806 | =over 4
|
---|
807 |
|
---|
808 | =item LINES
|
---|
809 |
|
---|
810 | =item PAGE
|
---|
811 |
|
---|
812 | =item PAGE_LEN
|
---|
813 |
|
---|
814 | =item LINES_LEFT
|
---|
815 |
|
---|
816 | =item TOP_NAME
|
---|
817 |
|
---|
818 | =item TOP_GV
|
---|
819 |
|
---|
820 | =item FMT_NAME
|
---|
821 |
|
---|
822 | =item FMT_GV
|
---|
823 |
|
---|
824 | =item BOTTOM_NAME
|
---|
825 |
|
---|
826 | =item BOTTOM_GV
|
---|
827 |
|
---|
828 | =item SUBPROCESS
|
---|
829 |
|
---|
830 | =item IoTYPE
|
---|
831 |
|
---|
832 | =item IoFLAGS
|
---|
833 |
|
---|
834 | =item IsSTD
|
---|
835 |
|
---|
836 | Takes one arguments ( 'stdin' | 'stdout' | 'stderr' ) and returns true
|
---|
837 | if the IoIFP of the object is equal to the handle whose name was
|
---|
838 | passed as argument ( i.e. $io->IsSTD('stderr') is true if
|
---|
839 | IoIFP($io) == PerlIO_stdin() ).
|
---|
840 |
|
---|
841 | =back
|
---|
842 |
|
---|
843 | =head2 B::AV Methods
|
---|
844 |
|
---|
845 | =over 4
|
---|
846 |
|
---|
847 | =item FILL
|
---|
848 |
|
---|
849 | =item MAX
|
---|
850 |
|
---|
851 | =item OFF
|
---|
852 |
|
---|
853 | =item ARRAY
|
---|
854 |
|
---|
855 | =item ARRAYelt
|
---|
856 |
|
---|
857 | Like C<ARRAY>, but takes an index as an argument to get only one element,
|
---|
858 | rather than a list of all of them.
|
---|
859 |
|
---|
860 | =item AvFLAGS
|
---|
861 |
|
---|
862 | =back
|
---|
863 |
|
---|
864 | =head2 B::CV Methods
|
---|
865 |
|
---|
866 | =over 4
|
---|
867 |
|
---|
868 | =item STASH
|
---|
869 |
|
---|
870 | =item START
|
---|
871 |
|
---|
872 | =item ROOT
|
---|
873 |
|
---|
874 | =item GV
|
---|
875 |
|
---|
876 | =item FILE
|
---|
877 |
|
---|
878 | =item DEPTH
|
---|
879 |
|
---|
880 | =item PADLIST
|
---|
881 |
|
---|
882 | =item OUTSIDE
|
---|
883 |
|
---|
884 | =item OUTSIDE_SEQ
|
---|
885 |
|
---|
886 | =item XSUB
|
---|
887 |
|
---|
888 | =item XSUBANY
|
---|
889 |
|
---|
890 | For constant subroutines, returns the constant SV returned by the subroutine.
|
---|
891 |
|
---|
892 | =item CvFLAGS
|
---|
893 |
|
---|
894 | =item const_sv
|
---|
895 |
|
---|
896 | =back
|
---|
897 |
|
---|
898 | =head2 B::HV Methods
|
---|
899 |
|
---|
900 | =over 4
|
---|
901 |
|
---|
902 | =item FILL
|
---|
903 |
|
---|
904 | =item MAX
|
---|
905 |
|
---|
906 | =item KEYS
|
---|
907 |
|
---|
908 | =item RITER
|
---|
909 |
|
---|
910 | =item NAME
|
---|
911 |
|
---|
912 | =item PMROOT
|
---|
913 |
|
---|
914 | =item ARRAY
|
---|
915 |
|
---|
916 | =back
|
---|
917 |
|
---|
918 | =head2 OP-RELATED CLASSES
|
---|
919 |
|
---|
920 | C<B::OP>, C<B::UNOP>, C<B::BINOP>, C<B::LOGOP>, C<B::LISTOP>, C<B::PMOP>,
|
---|
921 | C<B::SVOP>, C<B::PADOP>, C<B::PVOP>, C<B::LOOP>, C<B::COP>.
|
---|
922 |
|
---|
923 | These classes correspond in the obvious way to the underlying C
|
---|
924 | structures of similar names. The inheritance hierarchy mimics the
|
---|
925 | underlying C "inheritance":
|
---|
926 |
|
---|
927 | B::OP
|
---|
928 | |
|
---|
929 | +---------------+--------+--------+
|
---|
930 | | | | |
|
---|
931 | B::UNOP B::SVOP B::PADOP B::COP
|
---|
932 | ,' `-.
|
---|
933 | / `--.
|
---|
934 | B::BINOP B::LOGOP
|
---|
935 | |
|
---|
936 | |
|
---|
937 | B::LISTOP
|
---|
938 | ,' `.
|
---|
939 | / \
|
---|
940 | B::LOOP B::PMOP
|
---|
941 |
|
---|
942 | Access methods correspond to the underlying C structre field names,
|
---|
943 | with the leading "class indication" prefix (C<"op_">) removed.
|
---|
944 |
|
---|
945 | =head2 B::OP Methods
|
---|
946 |
|
---|
947 | These methods get the values of similarly named fields within the OP
|
---|
948 | data structure. See top of C<op.h> for more info.
|
---|
949 |
|
---|
950 | =over 4
|
---|
951 |
|
---|
952 | =item next
|
---|
953 |
|
---|
954 | =item sibling
|
---|
955 |
|
---|
956 | =item name
|
---|
957 |
|
---|
958 | This returns the op name as a string (e.g. "add", "rv2av").
|
---|
959 |
|
---|
960 | =item ppaddr
|
---|
961 |
|
---|
962 | This returns the function name as a string (e.g. "PL_ppaddr[OP_ADD]",
|
---|
963 | "PL_ppaddr[OP_RV2AV]").
|
---|
964 |
|
---|
965 | =item desc
|
---|
966 |
|
---|
967 | This returns the op description from the global C PL_op_desc array
|
---|
968 | (e.g. "addition" "array deref").
|
---|
969 |
|
---|
970 | =item targ
|
---|
971 |
|
---|
972 | =item type
|
---|
973 |
|
---|
974 | =item opt
|
---|
975 |
|
---|
976 | =item static
|
---|
977 |
|
---|
978 | =item flags
|
---|
979 |
|
---|
980 | =item private
|
---|
981 |
|
---|
982 | =item spare
|
---|
983 |
|
---|
984 | =back
|
---|
985 |
|
---|
986 | =head2 B::UNOP METHOD
|
---|
987 |
|
---|
988 | =over 4
|
---|
989 |
|
---|
990 | =item first
|
---|
991 |
|
---|
992 | =back
|
---|
993 |
|
---|
994 | =head2 B::BINOP METHOD
|
---|
995 |
|
---|
996 | =over 4
|
---|
997 |
|
---|
998 | =item last
|
---|
999 |
|
---|
1000 | =back
|
---|
1001 |
|
---|
1002 | =head2 B::LOGOP METHOD
|
---|
1003 |
|
---|
1004 | =over 4
|
---|
1005 |
|
---|
1006 | =item other
|
---|
1007 |
|
---|
1008 | =back
|
---|
1009 |
|
---|
1010 | =head2 B::LISTOP METHOD
|
---|
1011 |
|
---|
1012 | =over 4
|
---|
1013 |
|
---|
1014 | =item children
|
---|
1015 |
|
---|
1016 | =back
|
---|
1017 |
|
---|
1018 | =head2 B::PMOP Methods
|
---|
1019 |
|
---|
1020 | =over 4
|
---|
1021 |
|
---|
1022 | =item pmreplroot
|
---|
1023 |
|
---|
1024 | =item pmreplstart
|
---|
1025 |
|
---|
1026 | =item pmnext
|
---|
1027 |
|
---|
1028 | =item pmregexp
|
---|
1029 |
|
---|
1030 | =item pmflags
|
---|
1031 |
|
---|
1032 | =item pmdynflags
|
---|
1033 |
|
---|
1034 | =item pmpermflags
|
---|
1035 |
|
---|
1036 | =item precomp
|
---|
1037 |
|
---|
1038 | =item pmoffset
|
---|
1039 |
|
---|
1040 | Only when perl was compiled with ithreads.
|
---|
1041 |
|
---|
1042 | =back
|
---|
1043 |
|
---|
1044 | =head2 B::SVOP METHOD
|
---|
1045 |
|
---|
1046 | =over 4
|
---|
1047 |
|
---|
1048 | =item sv
|
---|
1049 |
|
---|
1050 | =item gv
|
---|
1051 |
|
---|
1052 | =back
|
---|
1053 |
|
---|
1054 | =head2 B::PADOP METHOD
|
---|
1055 |
|
---|
1056 | =over 4
|
---|
1057 |
|
---|
1058 | =item padix
|
---|
1059 |
|
---|
1060 | =back
|
---|
1061 |
|
---|
1062 | =head2 B::PVOP METHOD
|
---|
1063 |
|
---|
1064 | =over 4
|
---|
1065 |
|
---|
1066 | =item pv
|
---|
1067 |
|
---|
1068 | =back
|
---|
1069 |
|
---|
1070 | =head2 B::LOOP Methods
|
---|
1071 |
|
---|
1072 | =over 4
|
---|
1073 |
|
---|
1074 | =item redoop
|
---|
1075 |
|
---|
1076 | =item nextop
|
---|
1077 |
|
---|
1078 | =item lastop
|
---|
1079 |
|
---|
1080 | =back
|
---|
1081 |
|
---|
1082 | =head2 B::COP Methods
|
---|
1083 |
|
---|
1084 | =over 4
|
---|
1085 |
|
---|
1086 | =item label
|
---|
1087 |
|
---|
1088 | =item stash
|
---|
1089 |
|
---|
1090 | =item stashpv
|
---|
1091 |
|
---|
1092 | =item file
|
---|
1093 |
|
---|
1094 | =item cop_seq
|
---|
1095 |
|
---|
1096 | =item arybase
|
---|
1097 |
|
---|
1098 | =item line
|
---|
1099 |
|
---|
1100 | =item warnings
|
---|
1101 |
|
---|
1102 | =item io
|
---|
1103 |
|
---|
1104 | =back
|
---|
1105 |
|
---|
1106 |
|
---|
1107 | =head1 AUTHOR
|
---|
1108 |
|
---|
1109 | Malcolm Beattie, C<[email protected]>
|
---|
1110 |
|
---|
1111 | =cut
|
---|