This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
replace misleading docs with a BUGS section
[perl5.git] / lib / English.pm
index d40d28a..86d75a4 100644 (file)
@@ -3,7 +3,39 @@ package English;
 require Exporter;
 @ISA = (Exporter);
 
-local $^W = 0;
+=head1 NAME
+
+English - use nice English (or awk) names for ugly punctuation variables
+
+=head1 SYNOPSIS
+
+    use English;
+    ...
+    if ($ERRNO =~ /denied/) { ... }
+
+=head1 DESCRIPTION
+
+This module provides aliases for the built-in variables whose
+names no one seems to like to read.  Variables with side-effects
+which get triggered just by accessing them (like $0) will still 
+be affected.
+
+For those variables that have an B<awk> version, both long
+and short English alternatives are provided.  For example, 
+the C<$/> variable can be referred to either $RS or 
+$INPUT_RECORD_SEPARATOR if you are using the English module.
+
+See L<perlvar> for a complete list of these.
+
+=head1 BUGS
+
+This module provokes sizeable inefficiencies for regular expressions,
+due to unfortunate implementation details.  If performance matters,
+consider avoiding English.
+
+=cut
+
+no warnings;
 
 # Grandfather $NAME import
 sub import {
@@ -41,6 +73,7 @@ sub import {
        *CHILD_ERROR
        *OS_ERROR
        *ERRNO
+       *EXTENDED_OS_ERROR
        *EVAL_ERROR
        *PROCESS_ID
        *PID
@@ -62,9 +95,10 @@ sub import {
        *BASETIME
        *WARNING
        *EXECUTABLE_NAME
+       *OSNAME
 );
 
-# The ground of all being.
+# The ground of all being. @ARG is deprecated (5.005 makes @_ lexical)
 
        *ARG                                    = *_    ;
 
@@ -111,6 +145,7 @@ sub import {
        *CHILD_ERROR                            = *?    ;
        *OS_ERROR                               = *!    ;
            *ERRNO                              = *!    ;
+       *EXTENDED_OS_ERROR                      = *^E   ;
        *EVAL_ERROR                             = *@    ;
 
 # Process info.
@@ -131,6 +166,7 @@ sub import {
 
        *PERL_VERSION                           = *]    ;
        *ACCUMULATOR                            = *^A   ;
+       *COMPILING                              = *^C   ;
        *DEBUGGING                              = *^D   ;
        *SYSTEM_FD_MAX                          = *^F   ;
        *INPLACE_EDIT                           = *^I   ;
@@ -138,6 +174,7 @@ sub import {
        *BASETIME                               = *^T   ;
        *WARNING                                = *^W   ;
        *EXECUTABLE_NAME                        = *^X   ;
+       *OSNAME                                 = *^O   ;
 
 # Deprecated.