my_plvarsp nulling and PERL_GLOBAL_STRUCT_PRIVATE
[perl.git] / lib / English.pm
1 package English;
2
3 our $VERSION = '1.09';
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.16 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                      = *-    ;
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;