document convention for keys in %^H
authorZefram <zefram@fysh.org>
Thu, 15 Sep 2011 21:35:20 +0000 (22:35 +0100)
committerZefram <zefram@fysh.org>
Thu, 15 Sep 2011 21:35:20 +0000 (22:35 +0100)
pod/perlpragma.pod
pod/perlvar.pod

index 8560144..604387d 100644 (file)
@@ -82,17 +82,17 @@ The interaction with the Perl compilation happens inside package C<myint>:
     use warnings;
     
     sub import {
-        $^H{myint} = 1;
+        $^H{"myint/in_effect"} = 1;
     }
     
     sub unimport {
-        $^H{myint} = 0;
+        $^H{"myint/in_effect"} = 0;
     }
     
     sub in_effect {
         my $level = shift // 0;
         my $hinthash = (caller($level))[10];
-        return $hinthash->{myint};
+        return $hinthash->{"myint/in_effect"};
     }
     
     1;
@@ -122,10 +122,26 @@ 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
+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
index 3217e3c..5708c05 100644 (file)
@@ -603,6 +603,12 @@ X<%^H>
 The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes it
 useful for implementation of lexically scoped pragmas. See L<perlpragma>.
 
+When putting items into C<%^H>, in order to avoid conflicting with other
+users of the hash there is a convention regarding which keys to use.
+A module should use only keys that begin with the module's name (the
+name of its main package) and a "/" character.  For example, a module
+C<Foo::Bar> should use keys such as C<Foo::Bar/baz>.
+
 This variable was added in Perl 5.6.
 
 =item @INC