Introduce NVef, NVff, and NVgf, use the middle one.
[perl.git] / 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;