[win32] the EXTCONST in sdbm.h breaks SDBM on Borland, since

[p5sagit/p5-mst-13.2.git] / pod / perlsub.pod

diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 602e5c0..16babd2 100644 (file)
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -58,7 +58,7 @@ it was assigned to.)  Note that assigning to the whole array @_ removes
 the aliasing, and does not update any arguments.
 
 The return value of the subroutine is the value of the last expression
-evaluated.  Alternatively, a return statement may be used exit the
+evaluated.  Alternatively, a return statement may be used to exit the
 subroutine, optionally specifying the returned value, which will be
 evaluated in the appropriate context (list, scalar, or void) depending
 on the context of the subroutine call.  If you specify no return value,
@@ -320,8 +320,9 @@ otherwise.  An inner block may countermand this with S<"no strict 'vars'">.
 
 A my() has both a compile-time and a run-time effect.  At compile time,
 the compiler takes notice of it; the principle usefulness of this is to
-quiet C<use strict 'vars'>.  The actual initialization doesn't happen
-until run time, so gets executed every time through a loop.
+quiet C<use strict 'vars'>.  The actual initialization is delayed until
+run time, so it gets executed appropriately; every time through a loop,
+for example.
 
 Variables declared with "my" are not part of any package and are therefore
 never fully qualified with the package name.  In particular, you're not
@@ -383,7 +384,7 @@ If this function is being sourced in from a separate file
 via C<require> or C<use>, then this is probably just fine.  If it's
 all in the main program, you'll need to arrange for the my()
 to be executed early, either by putting the whole block above
-your pain program, or more likely, placing merely a BEGIN
+your main program, or more likely, placing merely a BEGIN
 sub around it to make sure it gets executed before your program
 starts to run:
 
@@ -468,6 +469,42 @@ both supply a list context to the right-hand side, while
 
 supplies a scalar context.
 
+A note about C<local()> and composite types is in order.  Something
+like C<local(%foo)> works by temporarily placing a brand new hash in
+the symbol table.  The old hash is left alone, but is hidden "behind"
+the new one.
+
+This means the old variable is completely invisible via the symbol
+table (i.e. the hash entry in the C<*foo> typeglob) for the duration
+of the dynamic scope within which the C<local()> was seen.  This
+has the effect of allowing one to temporarily occlude any magic on
+composite types.  For instance, this will briefly alter a tied
+hash to some other implementation:
+
+    tie %ahash, 'APackage';
+    [...]
+    {
+       local %ahash;
+       tie %ahash, 'BPackage';
+       [..called code will see %ahash tied to 'BPackage'..]
+       {
+          local %ahash;
+          [..%ahash is a normal (untied) hash here..]
+       }
+    }
+    [..%ahash back to its initial tied self again..]
+
+As another example, a custom implementation of C<%ENV> might look
+like this:
+
+    {
+        local %ENV;
+        tie %ENV, 'MyOwnEnv';
+        [..do your own fancy %ENV manipulation here..]
+    }
+    [..normal %ENV behavior here..]
+
+
 =head2 Passing Symbol Table Entries (typeglobs)
 
 [Note:  The mechanism described in this section was originally the only
@@ -835,6 +872,12 @@ via the import syntax, and these names may then override the builtin ones:
     chdir $somewhere;
     sub chdir { ... }
 
+To unambiguously refer to the builtin form, one may precede the
+builtin name with the special package qualifier C<CORE::>.  For example,
+saying C<CORE::open()> will always refer to the builtin C<open()>, even
+if the current package has imported some other subroutine called
+C<&open()> from elsewhere.
+
 Library modules should not in general export builtin names like "open"
 or "chdir" as part of their default @EXPORT list, because these may
 sneak into someone else's namespace and change the semantics unexpectedly.
@@ -850,6 +893,10 @@ and it would import the open override, but if they said
 
 they would get the default imports without the overrides.
 
+Note that such overriding is restricted to the package that requests
+the import.  Some means of "globally" overriding builtins may become
+available in future.
+
 =head2 Autoloading
 
 If you call a subroutine that is undefined, you would ordinarily get an