This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
replace misleading docs with a BUGS section
[perl5.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;
13     ...
14     if ($ERRNO =~ /denied/) { ... }
15
16 =head1 DESCRIPTION
17
18 This module provides aliases for the built-in variables whose
19 names no one seems to like to read.  Variables with side-effects
20 which get triggered just by accessing them (like $0) will still 
21 be affected.
22
23 For those variables that have an B<awk> version, both long
24 and short English alternatives are provided.  For example, 
25 the C<$/> variable can be referred to either $RS or 
26 $INPUT_RECORD_SEPARATOR if you are using the English module.
27
28 See L<perlvar> for a complete list of these.
29
30 =head1 BUGS
31
32 This module provokes sizeable inefficiencies for regular expressions,
33 due to unfortunate implementation details.  If performance matters,
34 consider avoiding English.
35
36 =cut
37
38 no warnings;
39
40 # Grandfather $NAME import
41 sub import {
42     my $this = shift;
43     my @list = @_;
44     local $Exporter::ExportLevel = 1;
45     Exporter::import($this,grep {s/^\$/*/} @list);
46 }
47
48 @EXPORT = qw(
49         *ARG
50         *MATCH
51         *PREMATCH
52         *POSTMATCH
53         *LAST_PAREN_MATCH
54         *INPUT_LINE_NUMBER
55         *NR
56         *INPUT_RECORD_SEPARATOR
57         *RS
58         *OUTPUT_AUTOFLUSH
59         *OUTPUT_FIELD_SEPARATOR
60         *OFS
61         *OUTPUT_RECORD_SEPARATOR
62         *ORS
63         *LIST_SEPARATOR
64         *SUBSCRIPT_SEPARATOR
65         *SUBSEP
66         *FORMAT_PAGE_NUMBER
67         *FORMAT_LINES_PER_PAGE
68         *FORMAT_LINES_LEFT
69         *FORMAT_NAME
70         *FORMAT_TOP_NAME
71         *FORMAT_LINE_BREAK_CHARACTERS
72         *FORMAT_FORMFEED
73         *CHILD_ERROR
74         *OS_ERROR
75         *ERRNO
76         *EXTENDED_OS_ERROR
77         *EVAL_ERROR
78         *PROCESS_ID
79         *PID
80         *REAL_USER_ID
81         *UID
82         *EFFECTIVE_USER_ID
83         *EUID
84         *REAL_GROUP_ID
85         *GID
86         *EFFECTIVE_GROUP_ID
87         *EGID
88         *PROGRAM_NAME
89         *PERL_VERSION
90         *ACCUMULATOR
91         *DEBUGGING
92         *SYSTEM_FD_MAX
93         *INPLACE_EDIT
94         *PERLDB
95         *BASETIME
96         *WARNING
97         *EXECUTABLE_NAME
98         *OSNAME
99 );
100
101 # The ground of all being. @ARG is deprecated (5.005 makes @_ lexical)
102
103         *ARG                                    = *_    ;
104
105 # Matching.
106
107         *MATCH                                  = *&    ;
108         *PREMATCH                               = *`    ;
109         *POSTMATCH                              = *'    ;
110         *LAST_PAREN_MATCH                       = *+    ;
111
112 # Input.
113
114         *INPUT_LINE_NUMBER                      = *.    ;
115             *NR                                 = *.    ;
116         *INPUT_RECORD_SEPARATOR                 = */    ;
117             *RS                                 = */    ;
118
119 # Output.
120
121         *OUTPUT_AUTOFLUSH                       = *|    ;
122         *OUTPUT_FIELD_SEPARATOR                 = *,    ;
123             *OFS                                = *,    ;
124         *OUTPUT_RECORD_SEPARATOR                = *\    ;
125             *ORS                                = *\    ;
126
127 # Interpolation "constants".
128
129         *LIST_SEPARATOR                         = *"    ;
130         *SUBSCRIPT_SEPARATOR                    = *;    ;
131             *SUBSEP                             = *;    ;
132
133 # Formats
134
135         *FORMAT_PAGE_NUMBER                     = *%    ;
136         *FORMAT_LINES_PER_PAGE                  = *=    ;
137         *FORMAT_LINES_LEFT                      = *-    ;
138         *FORMAT_NAME                            = *~    ;
139         *FORMAT_TOP_NAME                        = *^    ;
140         *FORMAT_LINE_BREAK_CHARACTERS           = *:    ;
141         *FORMAT_FORMFEED                        = *^L   ;
142
143 # Error status.
144
145         *CHILD_ERROR                            = *?    ;
146         *OS_ERROR                               = *!    ;
147             *ERRNO                              = *!    ;
148         *EXTENDED_OS_ERROR                      = *^E   ;
149         *EVAL_ERROR                             = *@    ;
150
151 # Process info.
152
153         *PROCESS_ID                             = *$    ;
154             *PID                                = *$    ;
155         *REAL_USER_ID                           = *<    ;
156             *UID                                = *<    ;
157         *EFFECTIVE_USER_ID                      = *>    ;
158             *EUID                               = *>    ;
159         *REAL_GROUP_ID                          = *(    ;
160             *GID                                = *(    ;
161         *EFFECTIVE_GROUP_ID                     = *)    ;
162             *EGID                               = *)    ;
163         *PROGRAM_NAME                           = *0    ;
164
165 # Internals.
166
167         *PERL_VERSION                           = *]    ;
168         *ACCUMULATOR                            = *^A   ;
169         *COMPILING                              = *^C   ;
170         *DEBUGGING                              = *^D   ;
171         *SYSTEM_FD_MAX                          = *^F   ;
172         *INPLACE_EDIT                           = *^I   ;
173         *PERLDB                                 = *^P   ;
174         *BASETIME                               = *^T   ;
175         *WARNING                                = *^W   ;
176         *EXECUTABLE_NAME                        = *^X   ;
177         *OSNAME                                 = *^O   ;
178
179 # Deprecated.
180
181 #       *ARRAY_BASE                             = *[    ;
182 #       *OFMT                                   = *#    ;
183 #       *MULTILINE_MATCHING                     = **    ;
184
185 1;