pod/perlpragma.pod

   1 =head1 NAME
   2
   3 perlpragma - how to write a user pragma
   4
   5 =head1 DESCRIPTION
   6
   7 A pragma is a module which influences some aspect of the compile time or run
   8 time behaviour of Perl, such as C<strict> or C<warnings>. With Perl 5.10 you
   9 are no longer limited to the built in pragmata; you can now create user
  10 pragmata that modify the behaviour of user functions within a lexical scope.
  11
  12 =head1 A basic example
  13
  14 For example, say you need to create a class implementing overloaded
  15 mathematical operators, and would like to provide your own pragma that
  16 functions much like C<use integer;> You'd like this code
  17
  18     use MyMaths;
  19
  20     my $l = MyMaths->new(1.2);
  21     my $r = MyMaths->new(3.4);
  22
  23     print "A: ", $l + $r, "\n";
  24
  25     use myint;
  26     print "B: ", $l + $r, "\n";
  27
  28     {
  29         no myint;
  30         print "C: ", $l + $r, "\n";
  31     }
  32
  33     print "D: ", $l + $r, "\n";
  34
  35     no myint;
  36     print "E: ", $l + $r, "\n";
  37
  38 to give the output
  39
  40     A: 4.6
  41     B: 4
  42     C: 4.6
  43     D: 4
  44     E: 4.6
  45
  46 I<i.e.>, where C<use myint;> is in effect, addition operations are forced
  47 to integer, whereas by default they are not, with the default behaviour being
  48 restored via C<no myint;>
  49
  50 The minimal implementation of the package C<MyMaths> would be something like
  51 this:
  52
  53     package MyMaths;
  54     use warnings;
  55     use strict;
  56     use myint();
  57     use overload '+' => sub {
  58         my ($l, $r) = @_;
  59         # Pass 1 to check up one call level from here
  60         if (myint::in_effect(1)) {
  61             int($$l) + int($$r);
  62         } else {
  63             $$l + $$r;
  64         }
  65     };
  66
  67     sub new {
  68         my ($class, $value) = @_;
  69         bless \$value, $class;
  70     }
  71
  72     1;
  73
  74 Note how we load the user pragma C<myint> with C<()> to prevent its C<import>
  75 being called.
  76
  77 The interaction with the Perl compile happens inside package C<myint>:
  78
  79 package myint;
  80
  81     use strict;
  82     use warnings;
  83
  84     sub import {
  85         $^H{myint} = 1;
  86     }
  87
  88     sub unimport {
  89         $^H{myint} = 0;
  90     }
  91
  92     sub in_effect {
  93         my $level = shift // 0;
  94         my $hinthash = (caller($level))[10];
  95         return $hinthash->{myint};
  96     }
  97
  98     1;
  99
 100 As pragmata are implemented as modules, like any other module, C<use myint;>
 101 becomes
 102
 103     BEGIN {
 104         require myint;
 105         myint->import();
 106     }
 107
 108 and C<no myint;> is
 109
 110     BEGIN {
 111         require myint;
 112         myint->unimport();
 113     }
 114
 115 Hence the C<import> and C<unimport> routines are called at B<compile time>
 116 for the user's code.
 117
 118 User pragmata store their state by writing to C<%^H>, hence these two
 119 routines manipulate C<%^H>. The state information in C<%^H> is stored in the
 120 optree, and can be retrieved at runtime with C<caller>, at index 10 of the
 121 list of returned results. In the example pragma, retrieval is encapsulated
 122 into the routine C<in_effect()>. This uses C<caller(0)> to determine the
 123 state of C<$^H{myint}> when each line of the user's script was called, and
 124 therefore provide the correct semantics in the subroutine implementing the
 125 overloaded addition.
 126
 127 =head1 Implementation details
 128
 129 The optree is shared between threads, which means there is a possibility that
 130 the optree will outlive the particular thread (and therefore interpreter
 131 instance) that created it, so true Perl scalars cannot be stored in the
 132 optree. Instead a compact form is used, which can only store values that are
 133 integers (signed and unsigned), strings or C<undef> - references and
 134 floating point values are stringified.  If you need to store multiple values
 135 or complex structures, you should serialise them, for example with C<pack>.
 136 The deletion of a hash key from C<%^H> is recorded, and as ever can be
 137 distinguished from the existence of a key with value C<undef> with
 138 C<exists>.