Moving old tlperl prior to committing new one

git-svn-id: svn://tug.org/texlive/trunk@21422 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 0 insertions, 147 deletions

diff --git a/Master/tlpkg/tlperl/lib/pods/perlpragma.pod b/Master/tlpkg/tlperl/lib/pods/perlpragma.pod
deleted file mode 100755
index 51292a8a12c..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlpragma.pod
+++ /dev/null
@@ -1,147 +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} = 1;
-    }
-    
-    sub unimport {
-        $^H{myint} = 0;
-    }
-    
-    sub in_effect {
-        my $level = shift // 0;
-        my $hinthash = (caller($level))[10];
-        return $hinthash->{myint};
-    }
-    
-    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 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}> when each line of the user's script was called, and
-therefore provide the correct semantics in the subroutine implementing the
-overloaded addition.
-
-=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.