perl/lib/English.pm

package English;

our $VERSION = '1.01';

require Exporter;
@ISA = (Exporter);

=head1 NAME

English - use nice English (or awk) names for ugly punctuation variables

=head1 SYNOPSIS

    use English qw( -no_match_vars ) ;  # Avoids regex performance penalty
    use English;
    ...
    if ($ERRNO =~ /denied/) { ... }

=head1 DESCRIPTION

This module provides aliases for the built-in variables whose
names no one seems to like to read.  Variables with side-effects
which get triggered just by accessing them (like $0) will still 
be affected.

For those variables that have an B<awk> version, both long
and short English alternatives are provided.  For example, 
the C<$/> variable can be referred to either $RS or 
$INPUT_RECORD_SEPARATOR if you are using the English module.

See L<perlvar> for a complete list of these.

=head1 PERFORMANCE

This module can provoke sizeable inefficiencies for regular expressions,
due to unfortunate implementation details.  If performance matters in
your application and you don't need $PREMATCH, $MATCH, or $POSTMATCH,
try doing

   use English qw( -no_match_vars ) ;

.  B<It is especially important to do this in modules to avoid penalizing
all applications which use them.>

=cut

no warnings;

my $globbed_match ;

# Grandfather $NAME import
sub import {
    my $this = shift;
    my @list = grep { ! /^-no_match_vars$/ } @_ ;
    local $Exporter::ExportLevel = 1;
    if ( @_ == @list ) {
        *EXPORT = \@COMPLETE_EXPORT ;
        $globbed_match ||= (
            eval q{
                *MATCH                          = *&    ;
                *PREMATCH                       = *`    ;
                *POSTMATCH                      = *'    ;
                1 ;
               }
            || do {
                require Carp ;
                Carp::croak "Can't create English for match leftovers: $@" ;
            }
        ) ;
    }
    else {
        *EXPORT = \@MINIMAL_EXPORT ;
    }
    Exporter::import($this,grep {s/^\$/*/} @list);
}

@MINIMAL_EXPORT = qw(
        *ARG
        *LAST_PAREN_MATCH
        *INPUT_LINE_NUMBER
        *NR
        *INPUT_RECORD_SEPARATOR
        *RS
        *OUTPUT_AUTOFLUSH
        *OUTPUT_FIELD_SEPARATOR
        *OFS
        *OUTPUT_RECORD_SEPARATOR
        *ORS
        *LIST_SEPARATOR
        *SUBSCRIPT_SEPARATOR
        *SUBSEP
        *FORMAT_PAGE_NUMBER
        *FORMAT_LINES_PER_PAGE
        *FORMAT_LINES_LEFT
        *FORMAT_NAME
        *FORMAT_TOP_NAME
        *FORMAT_LINE_BREAK_CHARACTERS
        *FORMAT_FORMFEED
        *CHILD_ERROR
        *OS_ERROR
        *ERRNO
        *EXTENDED_OS_ERROR
        *EVAL_ERROR
        *PROCESS_ID
        *PID
        *REAL_USER_ID
        *UID
        *EFFECTIVE_USER_ID
        *EUID
        *REAL_GROUP_ID
        *GID
        *EFFECTIVE_GROUP_ID
        *EGID
        *PROGRAM_NAME
        *PERL_VERSION
        *ACCUMULATOR
        *DEBUGGING
        *SYSTEM_FD_MAX
        *INPLACE_EDIT
        *PERLDB
        *BASETIME
        *WARNING
        *EXECUTABLE_NAME
        *OSNAME
        *LAST_REGEXP_CODE_RESULT
        *EXCEPTIONS_BEING_CAUGHT
        *LAST_SUBMATCH_RESULT
        @LAST_MATCH_START
        @LAST_MATCH_END
);


@MATCH_EXPORT = qw(
        *MATCH
        *PREMATCH
        *POSTMATCH
);

@COMPLETE_EXPORT = ( @MINIMAL_EXPORT, @MATCH_EXPORT ) ;

# The ground of all being. @ARG is deprecated (5.005 makes @_ lexical)

        *ARG                                    = *_    ;

# Matching.

        *LAST_PAREN_MATCH                       = *+    ;
        *LAST_SUBMATCH_RESULT                   = *^N ;
        *LAST_MATCH_START                       = *-{ARRAY} ;
        *LAST_MATCH_END                         = *+{ARRAY} ;

# Input.

        *INPUT_LINE_NUMBER                      = *.    ;
            *NR                                 = *.    ;
        *INPUT_RECORD_SEPARATOR                 = */    ;
            *RS                                 = */    ;

# Output.

        *OUTPUT_AUTOFLUSH                       = *|    ;
        *OUTPUT_FIELD_SEPARATOR                 = *,    ;
            *OFS                                = *,    ;
        *OUTPUT_RECORD_SEPARATOR                = *\    ;
            *ORS                                = *\    ;

# Interpolation "constants".

        *LIST_SEPARATOR                         = *"    ;
        *SUBSCRIPT_SEPARATOR                    = *;    ;
            *SUBSEP                             = *;    ;

# Formats

        *FORMAT_PAGE_NUMBER                     = *%    ;
        *FORMAT_LINES_PER_PAGE                  = *=    ;
        *FORMAT_LINES_LEFT                      = *-    ;
        *FORMAT_NAME                            = *~    ;
        *FORMAT_TOP_NAME                        = *^    ;
        *FORMAT_LINE_BREAK_CHARACTERS           = *:    ;
        *FORMAT_FORMFEED                        = *^L   ;

# Error status.

        *CHILD_ERROR                            = *?    ;
        *OS_ERROR                               = *!    ;
            *ERRNO                              = *!    ;
        *OS_ERROR                               = *!    ;
            *ERRNO                              = *!    ;
        *EXTENDED_OS_ERROR                      = *^E   ;
        *EVAL_ERROR                             = *@    ;

# Process info.

        *PROCESS_ID                             = *$    ;
            *PID                                = *$    ;
        *REAL_USER_ID                           = *<    ;
            *UID                                = *<    ;
        *EFFECTIVE_USER_ID                      = *>    ;
            *EUID                               = *>    ;
        *REAL_GROUP_ID                          = *(    ;
            *GID                                = *(    ;
        *EFFECTIVE_GROUP_ID                     = *)    ;
            *EGID                               = *)    ;
        *PROGRAM_NAME                           = *0    ;

# Internals.

        *PERL_VERSION                           = *^V   ;
        *ACCUMULATOR                            = *^A   ;
        *COMPILING                              = *^C   ;
        *DEBUGGING                              = *^D   ;
        *SYSTEM_FD_MAX                          = *^F   ;
        *INPLACE_EDIT                           = *^I   ;
        *PERLDB                                 = *^P   ;
        *LAST_REGEXP_CODE_RESULT                = *^R   ;
        *EXCEPTIONS_BEING_CAUGHT                = *^S   ;
        *BASETIME                               = *^T   ;
        *WARNING                                = *^W   ;
        *EXECUTABLE_NAME                        = *^X   ;
        *OSNAME                                 = *^O   ;

# Deprecated.

#       *ARRAY_BASE                             = *[    ;
#       *OFMT                                   = *#    ;
#       *MULTILINE_MATCHING                     = **    ;
#       *OLD_PERL_VERSION                       = *]    ;

1;
Revision:	1.1
Committed:	Thu Jun 30 14:27:08 2005 UTC (21 years, 3 months ago) by root
Branch:	MAIN
CVS Tags:	PERL-5-8-7, HEAD
Branch point for:	PERL
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	package English;
2
3			our $VERSION = '1.01';
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_SUBMATCH_RESULT
128			@LAST_MATCH_START
129			@LAST_MATCH_END
130			);
131
132
133			@MATCH_EXPORT = qw(
134			*MATCH
135			*PREMATCH
136			*POSTMATCH
137			);
138
139			@COMPLETE_EXPORT = ( @MINIMAL_EXPORT, @MATCH_EXPORT ) ;
140
141			# The ground of all being. @ARG is deprecated (5.005 makes @_ lexical)
142
143			ARG = _ ;
144
145			# Matching.
146
147			LAST_PAREN_MATCH = + ;
148			LAST_SUBMATCH_RESULT = ^N ;
149			LAST_MATCH_START = -{ARRAY} ;
150			LAST_MATCH_END = +{ARRAY} ;
151
152			# Input.
153
154			INPUT_LINE_NUMBER = . ;
155			NR = . ;
156			INPUT_RECORD_SEPARATOR = / ;
157			RS = / ;
158
159			# Output.
160
161			OUTPUT_AUTOFLUSH = \| ;
162			OUTPUT_FIELD_SEPARATOR = , ;
163			OFS = , ;
164			OUTPUT_RECORD_SEPARATOR = \ ;
165			ORS = \ ;
166
167			# Interpolation "constants".
168
169			LIST_SEPARATOR = " ;
170			SUBSCRIPT_SEPARATOR = ; ;
171			SUBSEP = ; ;
172
173			# Formats
174
175			FORMAT_PAGE_NUMBER = % ;
176			FORMAT_LINES_PER_PAGE = = ;
177			FORMAT_LINES_LEFT = - ;
178			FORMAT_NAME = ~ ;
179			FORMAT_TOP_NAME = ^ ;
180			FORMAT_LINE_BREAK_CHARACTERS = : ;
181			FORMAT_FORMFEED = ^L ;
182
183			# Error status.
184
185			CHILD_ERROR = ? ;
186			OS_ERROR = ! ;
187			ERRNO = ! ;
188			OS_ERROR = ! ;
189			ERRNO = ! ;
190			EXTENDED_OS_ERROR = ^E ;
191			EVAL_ERROR = @ ;
192
193			# Process info.
194
195			PROCESS_ID = $ ;
196			PID = $ ;
197			REAL_USER_ID = < ;
198			UID = < ;
199			EFFECTIVE_USER_ID = > ;
200			EUID = > ;
201			REAL_GROUP_ID = ( ;
202			GID = ( ;
203			EFFECTIVE_GROUP_ID = ) ;
204			EGID = ) ;
205			PROGRAM_NAME = 0 ;
206
207			# Internals.
208
209			PERL_VERSION = ^V ;
210			ACCUMULATOR = ^A ;
211			COMPILING = ^C ;
212			DEBUGGING = ^D ;
213			SYSTEM_FD_MAX = ^F ;
214			INPLACE_EDIT = ^I ;
215			PERLDB = ^P ;
216			LAST_REGEXP_CODE_RESULT = ^R ;
217			EXCEPTIONS_BEING_CAUGHT = ^S ;
218			BASETIME = ^T ;
219			WARNING = ^W ;
220			EXECUTABLE_NAME = ^X ;
221			OSNAME = ^O ;
222
223			# Deprecated.
224
225			# ARRAY_BASE = [ ;
226			# OFMT = # ;
227			# MULTILINE_MATCHING = * ;
228			# OLD_PERL_VERSION = ] ;
229
230			1;