Win32 pacifying from mjd.
[perl.git] / 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;