lib/English.pm

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