lib/English.pm

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