summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/pods/perlpragma.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlpragma.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlpragma.pod163
1 files changed, 0 insertions, 163 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlpragma.pod b/Master/tlpkg/tlperl/lib/pods/perlpragma.pod
deleted file mode 100644
index 604387d9f97..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlpragma.pod
+++ /dev/null
@@ -1,163 +0,0 @@
-=head1 NAME
-
-perlpragma - how to write a user pragma
-
-=head1 DESCRIPTION
-
-A pragma is a module which influences some aspect of the compile time or run
-time behaviour of Perl, such as C<strict> or C<warnings>. With Perl 5.10 you
-are no longer limited to the built in pragmata; you can now create user
-pragmata that modify the behaviour of user functions within a lexical scope.
-
-=head1 A basic example
-
-For example, say you need to create a class implementing overloaded
-mathematical operators, and would like to provide your own pragma that
-functions much like C<use integer;> You'd like this code
-
- use MyMaths;
-
- my $l = MyMaths->new(1.2);
- my $r = MyMaths->new(3.4);
-
- print "A: ", $l + $r, "\n";
-
- use myint;
- print "B: ", $l + $r, "\n";
-
- {
- no myint;
- print "C: ", $l + $r, "\n";
- }
-
- print "D: ", $l + $r, "\n";
-
- no myint;
- print "E: ", $l + $r, "\n";
-
-to give the output
-
- A: 4.6
- B: 4
- C: 4.6
- D: 4
- E: 4.6
-
-I<i.e.>, where C<use myint;> is in effect, addition operations are forced
-to integer, whereas by default they are not, with the default behaviour being
-restored via C<no myint;>
-
-The minimal implementation of the package C<MyMaths> would be something like
-this:
-
- package MyMaths;
- use warnings;
- use strict;
- use myint();
- use overload '+' => sub {
- my ($l, $r) = @_;
- # Pass 1 to check up one call level from here
- if (myint::in_effect(1)) {
- int($$l) + int($$r);
- } else {
- $$l + $$r;
- }
- };
-
- sub new {
- my ($class, $value) = @_;
- bless \$value, $class;
- }
-
- 1;
-
-Note how we load the user pragma C<myint> with an empty list C<()> to
-prevent its C<import> being called.
-
-The interaction with the Perl compilation happens inside package C<myint>:
-
- package myint;
-
- use strict;
- use warnings;
-
- sub import {
- $^H{"myint/in_effect"} = 1;
- }
-
- sub unimport {
- $^H{"myint/in_effect"} = 0;
- }
-
- sub in_effect {
- my $level = shift // 0;
- my $hinthash = (caller($level))[10];
- return $hinthash->{"myint/in_effect"};
- }
-
- 1;
-
-As pragmata are implemented as modules, like any other module, C<use myint;>
-becomes
-
- BEGIN {
- require myint;
- myint->import();
- }
-
-and C<no myint;> is
-
- BEGIN {
- require myint;
- myint->unimport();
- }
-
-Hence the C<import> and C<unimport> routines are called at B<compile time>
-for the user's code.
-
-User pragmata store their state by writing to the magical hash C<%^H>,
-hence these two routines manipulate it. The state information in C<%^H> is
-stored in the optree, and can be retrieved read-only at runtime with C<caller()>,
-at index 10 of the list of returned results. In the example pragma, retrieval
-is encapsulated into the routine C<in_effect()>, which takes as parameter
-the number of call frames to go up to find the value of the pragma in the
-user's script. This uses C<caller()> to determine the value of
-C<$^H{"myint/in_effect"}> when each line of the user's script was called, and
-therefore provide the correct semantics in the subroutine implementing the
-overloaded addition.
-
-=head1 Key naming
-
-There is only a single C<%^H>, but arbitrarily many modules that want
-to use its scoping semantics. To avoid stepping on each other's toes,
-they need to be sure to use different keys in the hash. It is therefore
-conventional for a module to use only keys that begin with the module's
-name (the name of its main package) and a "/" character. After this
-module-identifying prefix, the rest of the key is entirely up to the
-module: it may include any characters whatsoever. For example, a module
-C<Foo::Bar> should use keys such as C<Foo::Bar/baz> and C<Foo::Bar/$%/_!>.
-Modules following this convention all play nicely with each other.
-
-The Perl core uses a handful of keys in C<%^H> which do not follow this
-convention, because they predate it. Keys that follow the convention
-won't conflict with the core's historical keys.
-
-=head1 Implementation details
-
-The optree is shared between threads. This means there is a possibility that
-the optree will outlive the particular thread (and therefore the interpreter
-instance) that created it, so true Perl scalars cannot be stored in the
-optree. Instead a compact form is used, which can only store values that are
-integers (signed and unsigned), strings or C<undef> - references and
-floating point values are stringified. If you need to store multiple values
-or complex structures, you should serialise them, for example with C<pack>.
-The deletion of a hash key from C<%^H> is recorded, and as ever can be
-distinguished from the existence of a key with value C<undef> with
-C<exists>.
-
-B<Don't> attempt to store references to data structures as integers which
-are retrieved via C<caller> and converted back, as this will not be threadsafe.
-Accesses would be to the structure without locking (which is not safe for
-Perl's scalars), and either the structure has to leak, or it has to be
-freed when its creating thread terminates, which may be before the optree
-referencing it is deleted, if other threads outlive it.