From: Rafael Garcia-Suarez <rgarciasuarez@gmail.com>
Date: Tue, 10 Jul 2007 06:16:43 +0000 (+0000)
Subject: Mention the two ways of overriding built-ins.
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=1694bc1323f3c2ea90d7478c304c5f10b28e69f3;p=p5sagit%2Fp5-mst-13.2.git

Mention the two ways of overriding built-ins.
Link to perlsub. Fix typos and indentation.

p4raw-id: //depot/perl@31575
---

diff --git a/lib/CORE.pod b/lib/CORE.pod
index c3c7c1f..c917bba 100644
--- a/lib/CORE.pod
+++ b/lib/CORE.pod
@@ -1,51 +1,62 @@
 =head1 NAME
 
-CORE - Virtual namespace for Perl's core routines
+CORE - Pseudo-namespace for Perl's core routines
 
 =head1 SYNOPSIS
 
-	BEGIN
-		{
-		*CORE::GLOBAL::hex = sub { 1; };
-		}
+    BEGIN {
+        *CORE::GLOBAL::hex = sub { 1; };
+    }
 
-	print hex("0x50"),"\n";			# prints 1
-	print CORE::hex("0x50"),"\n";		# prints 80
+    print hex("0x50"),"\n";			# prints 1
+    print CORE::hex("0x50"),"\n";		# prints 80
 
 =head1 DESCRIPTION
 
-The C<CORE> namespace gives access to the original build-in functions from
-Perl. There is no C<CORE>-package, and therefore you do not need to use or
-require the CORE-module prior to accessing routines in this namespace.
+The C<CORE> namespace gives access to the original built-in functions of
+Perl. There is no C<CORE> package, and therefore you do not need to use or
+require an hypothetical "CORE" module prior to accessing routines in this
+namespace.
 
-A list of the build-in functions in Perl can be found in L<perlfunc>.
+A list of the built-in functions in Perl can be found in L<perlfunc>.
 
 =head1 OVERRIDING CORE FUNCTIONS
 
-The C<CORE::GLOBAL> namespace allows you to override the Perl build-in
-routines with your own version:
+To override a Perl built-in routine with your own version, you need to
+import it at compile-time. This can be conveniently achieved with the
+C<subs> pragma. This will affect only the package in which you've imported
+the said subroutine:
 
-	*CORE::GLOBAL::hex = sub 
-		{
-		# ... your code here
-		};
+    use subs 'chdir';
+    sub chdir { ... }
+    chdir $somewhere;
 
-The new routine will be called whenever a build-in function is called
+To override a built-in globally (that is, in all namespaces), you need to
+import your function into the C<CORE::GLOBAL> pseudo-namespace at compile
+time:
+
+    BEGIN {
+        *CORE::GLOBAL::hex = sub {
+            # ... your code here
+        };
+    }
+
+The new routine will be called whenever a built-in function is called
 without a qualifying package:
 
-	print hex("0x50"),"\n";			# prints 1
+    print hex("0x50"),"\n";			# prints 1
 
-If you want access to the original, unaltered routine, use the C<CORE::>
-prefix:
+In both cases, if you want access to the original, unaltered routine, use
+the C<CORE::> prefix:
 
-	print CORE::hex("0x50"),"\n";		# prints 80
+    print CORE::hex("0x50"),"\n";		# prints 80
 
 =head1 AUTHOR
 
-Tels <nospam-abuse@bloodgate.com> 2007.
+This documentation provided by Tels <nospam-abuse@bloodgate.com> 2007.
 
 =head1 SEE ALSO
 
-L<perl>, L<perlfunc>.
+L<perlsub>, L<perlfunc>.
 
 =cut