lib/English.pm

   1 package English;
   2
   3 our $VERSION = '1.11';
   4
   5 require Exporter;
   6 @ISA = qw(Exporter);
   7
   8 =head1 NAME
   9
  10 English - use nice English (or awk) names for ugly punctuation variables
  11
  12 =head1 SYNOPSIS
  13
  14     use English;
  15     use English qw( -no_match_vars ) ;  # Avoids regex performance
  16                                         # penalty in perl 5.18 and
  17                                         # earlier
  18     ...
  19     if ($ERRNO =~ /denied/) { ... }
  20
  21 =head1 DESCRIPTION
  22
  23 This module provides aliases for the built-in variables whose
  24 names no one seems to like to read.  Variables with side-effects
  25 which get triggered just by accessing them (like $0) will still
  26 be affected.
  27
  28 For those variables that have an B<awk> version, both long
  29 and short English alternatives are provided.  For example,
  30 the C<$/> variable can be referred to either $RS or
  31 $INPUT_RECORD_SEPARATOR if you are using the English module.
  32
  33 See L<perlvar> for a complete list of these.
  34
  35 =head1 PERFORMANCE
  36
  37 NOTE: This was fixed in perl 5.20.  Mentioning these three variables no
  38 longer makes a speed difference.  This section still applies if your code
  39 is to run on perl 5.18 or earlier.
  40
  41 This module can provoke sizeable inefficiencies for regular expressions,
  42 due to unfortunate implementation details.  If performance matters in
  43 your application and you don't need $PREMATCH, $MATCH, or $POSTMATCH,
  44 try doing
  45
  46    use English qw( -no_match_vars ) ;
  47
  48 .  B<It is especially important to do this in modules to avoid penalizing
  49 all applications which use them.>
  50
  51 =cut
  52
  53 no warnings;
  54
  55 my $globbed_match ;
  56
  57 # Grandfather $NAME import
  58 sub import {
  59     my $this = shift;
  60     my @list = grep { ! /^-no_match_vars$/ } @_ ;
  61     local $Exporter::ExportLevel = 1;
  62     if ( @_ == @list ) {
  63         *EXPORT = \@COMPLETE_EXPORT ;
  64         $globbed_match ||= (
  65             eval q{
  66                 *MATCH                          = *&    ;
  67                 *PREMATCH                       = *`    ;
  68                 *POSTMATCH                      = *'    ;
  69                 1 ;
  70                }
  71             || do {
  72                 require Carp ;
  73                 Carp::croak("Can't create English for match leftovers: $@") ;
  74             }
  75         ) ;
  76     }
  77     else {
  78         *EXPORT = \@MINIMAL_EXPORT ;
  79     }
  80     Exporter::import($this,grep {s/^\$/*/} @list);
  81 }
  82
  83 @MINIMAL_EXPORT = qw(
  84         *ARG
  85         *LAST_PAREN_MATCH
  86         *INPUT_LINE_NUMBER
  87         *NR
  88         *INPUT_RECORD_SEPARATOR
  89         *RS
  90         *OUTPUT_AUTOFLUSH
  91         *OUTPUT_FIELD_SEPARATOR
  92         *OFS
  93         *OUTPUT_RECORD_SEPARATOR
  94         *ORS
  95         *LIST_SEPARATOR
  96         *SUBSCRIPT_SEPARATOR
  97         *SUBSEP
  98         *FORMAT_PAGE_NUMBER
  99         *FORMAT_LINES_PER_PAGE
 100         *FORMAT_LINES_LEFT
 101         *FORMAT_NAME
 102         *FORMAT_TOP_NAME
 103         *FORMAT_LINE_BREAK_CHARACTERS
 104         *FORMAT_FORMFEED
 105         *CHILD_ERROR
 106         *OS_ERROR
 107         *ERRNO
 108         *EXTENDED_OS_ERROR
 109         *EVAL_ERROR
 110         *PROCESS_ID
 111         *PID
 112         *REAL_USER_ID
 113         *UID
 114         *EFFECTIVE_USER_ID
 115         *EUID
 116         *REAL_GROUP_ID
 117         *GID
 118         *EFFECTIVE_GROUP_ID
 119         *EGID
 120         *PROGRAM_NAME
 121         *PERL_VERSION
 122         *OLD_PERL_VERSION
 123         *ACCUMULATOR
 124         *COMPILING
 125         *DEBUGGING
 126         *SYSTEM_FD_MAX
 127         *INPLACE_EDIT
 128         *PERLDB
 129         *BASETIME
 130         *WARNING
 131         *EXECUTABLE_NAME
 132         *OSNAME
 133         *LAST_REGEXP_CODE_RESULT
 134         *EXCEPTIONS_BEING_CAUGHT
 135         *LAST_SUBMATCH_RESULT
 136         @LAST_MATCH_START
 137         @LAST_MATCH_END
 138 );
 139
 140
 141 @MATCH_EXPORT = qw(
 142         *MATCH
 143         *PREMATCH
 144         *POSTMATCH
 145 );
 146
 147 @COMPLETE_EXPORT = ( @MINIMAL_EXPORT, @MATCH_EXPORT ) ;
 148
 149 # The ground of all being.
 150
 151         *ARG                                    = *_    ;
 152
 153 # Matching.
 154
 155         *LAST_PAREN_MATCH                       = *+    ;
 156         *LAST_SUBMATCH_RESULT                   = *^N ;
 157         *LAST_MATCH_START                       = *-{ARRAY} ;
 158         *LAST_MATCH_END                         = *+{ARRAY} ;
 159
 160 # Input.
 161
 162         *INPUT_LINE_NUMBER                      = *.    ;
 163             *NR                                 = *.    ;
 164         *INPUT_RECORD_SEPARATOR                 = */    ;
 165             *RS                                 = */    ;
 166
 167 # Output.
 168
 169         *OUTPUT_AUTOFLUSH                       = *|    ;
 170         *OUTPUT_FIELD_SEPARATOR                 = *,    ;
 171             *OFS                                = *,    ;
 172         *OUTPUT_RECORD_SEPARATOR                = *\    ;
 173             *ORS                                = *\    ;
 174
 175 # Interpolation "constants".
 176
 177         *LIST_SEPARATOR                         = *"    ;
 178         *SUBSCRIPT_SEPARATOR                    = *;    ;
 179             *SUBSEP                             = *;    ;
 180
 181 # Formats
 182
 183         *FORMAT_PAGE_NUMBER                     = *%    ;
 184         *FORMAT_LINES_PER_PAGE                  = *=    ;
 185         *FORMAT_LINES_LEFT                      = *-{SCALAR}    ;
 186         *FORMAT_NAME                            = *~    ;
 187         *FORMAT_TOP_NAME                        = *^    ;
 188         *FORMAT_LINE_BREAK_CHARACTERS           = *:    ;
 189         *FORMAT_FORMFEED                        = *^L   ;
 190
 191 # Error status.
 192
 193         *CHILD_ERROR                            = *?    ;
 194         *OS_ERROR                               = *!    ;
 195             *ERRNO                              = *!    ;
 196         *OS_ERROR                               = *!    ;
 197             *ERRNO                              = *!    ;
 198         *EXTENDED_OS_ERROR                      = *^E   ;
 199         *EVAL_ERROR                             = *@    ;
 200
 201 # Process info.
 202
 203         *PROCESS_ID                             = *$    ;
 204             *PID                                = *$    ;
 205         *REAL_USER_ID                           = *<    ;
 206             *UID                                = *<    ;
 207         *EFFECTIVE_USER_ID                      = *>    ;
 208             *EUID                               = *>    ;
 209         *REAL_GROUP_ID                          = *(    ;
 210             *GID                                = *(    ;
 211         *EFFECTIVE_GROUP_ID                     = *)    ;
 212             *EGID                               = *)    ;
 213         *PROGRAM_NAME                           = *0    ;
 214
 215 # Internals.
 216
 217         *PERL_VERSION                           = *^V   ;
 218         *OLD_PERL_VERSION                       = *]    ;
 219         *ACCUMULATOR                            = *^A   ;
 220         *COMPILING                              = *^C   ;
 221         *DEBUGGING                              = *^D   ;
 222         *SYSTEM_FD_MAX                          = *^F   ;
 223         *INPLACE_EDIT                           = *^I   ;
 224         *PERLDB                                 = *^P   ;
 225         *LAST_REGEXP_CODE_RESULT                = *^R   ;
 226         *EXCEPTIONS_BEING_CAUGHT                = *^S   ;
 227         *BASETIME                               = *^T   ;
 228         *WARNING                                = *^W   ;
 229         *EXECUTABLE_NAME                        = *^X   ;
 230         *OSNAME                                 = *^O   ;
 231
 232 # Deprecated.
 233
 234 #       *ARRAY_BASE                             = *[    ;
 235 #       *OFMT                                   = *#    ;
 236
 237 1;