CORE.pod

Message-Id: <200707091728.43634@bloodgate.com>

p4raw-id: //depot/perl@31574

2 files changed, 52 insertions, 0 deletions

diff --git a/MANIFEST b/MANIFEST
index 87d2ade9d2..4477a78902 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 0000000000..c3c7c1f24c
--- /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