From: Tels <nospam-abuse@bloodgate.com>
Date: Mon, 9 Jul 2007 17:28:43 +0000 (+0200)
Subject: CORE.pod
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=c8472d06082df3e0150ffe3794f2af69985f0f68;p=p5sagit%2Fp5-mst-13.2.git

CORE.pod
Message-Id: <200707091728.43634@bloodgate.com>

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

diff --git a/MANIFEST b/MANIFEST
index 87d2ade..4477a78 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -1567,6 +1567,7 @@ lib/Config/Extensions.t		See if Config::Extensions works
 lib/Config.t			See if Config works
 lib/constant.pm			For "use constant"
 lib/constant.t			See if compile-time constants work
+lib/CORE.pod			document the CORE namespace
 lib/CPAN/bin/cpan		easily interact with CPAN from the command line
 lib/CPAN/Debug.pm		helper package for CPAN.pm
 lib/CPAN/FirstTime.pm		Utility for creating CPAN config files
diff --git a/lib/CORE.pod b/lib/CORE.pod
new file mode 100644
index 0000000..c3c7c1f
--- /dev/null
+++ b/lib/CORE.pod
@@ -0,0 +1,51 @@
+=head1 NAME
+
+CORE - Virtual namespace for Perl's core routines
+
+=head1 SYNOPSIS
+
+	BEGIN
+		{
+		*CORE::GLOBAL::hex = sub { 1; };
+		}
+
+	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.
+
+A list of the build-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:
+
+	*CORE::GLOBAL::hex = sub 
+		{
+		# ... your code here
+		};
+
+The new routine will be called whenever a build-in function is called
+without a qualifying package:
+
+	print hex("0x50"),"\n";			# prints 1
+
+If you want access to the original, unaltered routine, use the C<CORE::>
+prefix:
+
+	print CORE::hex("0x50"),"\n";		# prints 80
+
+=head1 AUTHOR
+
+Tels <nospam-abuse@bloodgate.com> 2007.
+
+=head1 SEE ALSO
+
+L<perl>, L<perlfunc>.
+
+=cut