package utf8;
-
$utf8::hint_bits = 0x00800000;
our $VERSION = '1.00';
=head1 DESCRIPTION
-WARNING: The implementation of Unicode support in Perl is incomplete.
-See L<perlunicode> for the exact details.
-
The C<use utf8> pragma tells the Perl parser to allow UTF-8 in the
program text in the current lexical scope (allow UTF-EBCDIC on EBCDIC based
platforms). The C<no utf8> pragma tells Perl to switch back to treating
text, this pragma should be used to recognize UTF-8 in the source.
When UTF-8 becomes the standard source format, this pragma will
effectively become a no-op. For convenience in what follows the
-term UTF-X is used to refer to UTF-8 on ASCII and ISO Latin based
+term I<UTF-X> is used to refer to UTF-8 on ASCII and ISO Latin based
platforms and UTF-EBCDIC on EBCDIC based platforms.
-Enabling the C<utf8> pragma has the following effects:
+Enabling the C<utf8> pragma has the following effect:
=over 4
=item *
Bytes in the source text that have their high-bit set will be treated
-as being part of a literal UTF-8 character. This includes most literals
-such as identifiers, string constants, constant regular expression patterns
-and package names. On EBCDIC platforms characters in the Latin 1
-character set are treated as being part of a literal UTF-EBCDIC character.
-
-=item *
-
-In the absence of inputs marked as UTF-X, regular expressions within the
-scope of this pragma will default to using character semantics instead
-of byte semantics.
-
- @bytes_or_chars = split //, $data; # may split to bytes if data
- # $data isn't UTF-X
- {
- use utf8; # force char semantics
- @chars = split //, $data; # splits characters
- }
+as being part of a literal UTF-8 character. This includes most
+literals such as identifiers, string constants, constant regular
+expression patterns and package names. On EBCDIC platforms characters
+in the Latin 1 character set are treated as being part of a literal
+UTF-EBCDIC character.
=back
=item * $num_octets = utf8::upgrade($string);
-Converts internal representation of string to the perls internal UTF-X form.
-Returns the number of octets necessary to represent the string as UTF-X.
+Converts internal representation of string to the Perl's internal
+I<UTF-X> form. Returns the number of octets necessary to represent
+the string as I<UTF-X>.
=item * utf8::downgrade($string[, CHECK])
=item * utf8::encode($string)
Converts (in-place) I<$string> from logical characters to octet sequence
-representing it in perl's UTF-X encoding.
+representing it in Perl's I<UTF-X> encoding.
=item * $flag = utf8::decode($string)
-Attempts to convert I<$string> in-place from perl's UTF-X encoding into logical characters.
+Attempts to convert I<$string> in-place from Perl's I<UTF-X> encoding
+into logical characters.
=back
Returns the character represented by that NUMBER in the character set.
For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
-chr(0x263a) is a Unicode smiley face. Within the scope of C<use utf8>,
-characters higher than 127 are encoded in Unicode; if you don't want
-this, temporarily C<use bytes> or use C<pack("C*",...)>
+chr(0x263a) is a Unicode smiley face. Note that characters from
+127 to 255 (inclusive) are not encoded in Unicode for backward
+compatibility reasons.
For the reverse, use L</ord>.
See L<utf8> for more about Unicode.
=item lc
Returns an lowercased version of EXPR. This is the internal function
-implementing the C<\L> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>
-and L<utf8>.
+implementing the C<\L> escape in double-quoted strings. Respects
+current LC_CTYPE locale if C<use locale> in force. See L<perllocale>
+and L<perlunicode>.
If EXPR is omitted, uses C<$_>.
=item lcfirst
-Returns the value of EXPR with the first character lowercased. This is
-the internal function implementing the C<\l> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>.
+Returns the value of EXPR with the first character lowercased. This
+is the internal function implementing the C<\l> escape in
+double-quoted strings. Respects current LC_CTYPE locale if C<use
+locale> in force. See L<perllocale> and L<perlunicode>.
If EXPR is omitted, uses C<$_>.
P A pointer to a structure (fixed-length string).
u A uuencoded string.
- U A Unicode character number. Encodes to UTF-8 internally.
- Works even if C<use utf8> is not in effect.
+ U A Unicode character number. Encodes to UTF-8 internally
+ (or UTF-EBCDIC in EBCDIC platforms).
w A BER compressed integer. Its bytes represent an unsigned
integer in base 128, most significant digit first, with as
=item uc
Returns an uppercased version of EXPR. This is the internal function
-implementing the C<\U> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>.
-Under Unicode (C<use utf8>) it uses the standard Unicode uppercase mappings. (It
-does not attempt to do titlecase mapping on initial letters. See C<ucfirst> for that.)
+implementing the C<\U> escape in double-quoted strings. Respects
+current LC_CTYPE locale if C<use locale> in force. See L<perllocale>
+and L<perlunicode>. Under Unicode it uses the standard Unicode
+uppercase mappings. (It does not attempt to do titlecase mapping on
+initial letters. See C<ucfirst> for that.)
If EXPR is omitted, uses C<$_>.
=item ucfirst
-Returns the value of EXPR with the first character
-in uppercase (titlecase in Unicode). This is
-the internal function implementing the C<\u> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>
-and L<utf8>.
+Returns the value of EXPR with the first character in uppercase
+(titlecase in Unicode). This is the internal function implementing
+the C<\u> escape in double-quoted strings. Respects current LC_CTYPE
+locale if C<use locale> in force. See L<perllocale> and L<perlunicode>.
If EXPR is omitted, uses C<$_>.
than C<chr(127)> may be represented using the C<\x{hex}> notation,
with C<hex> a hexadecimal integer:
- use utf8; # We will be doing Unicode processing
/\x{263a}/; # match a Unicode smiley face :)
Unicode characters in the range of 128-255 use two hexadecimal digits
with braces: C<\x{ab}>. Note that this is different than C<\xab>,
-which is just a hexadecimal byte with no Unicode
-significance.
+which is just a hexadecimal byte with no Unicode significance.
+
+B<NOTE>: in perl 5.6.0 it used to be that one needed to say C<use utf8>
+to use any Unicode features. This is no more the case: for almost all
+Unicode processing, the explicit C<utf8> pragma is not needed.
+(The only case where it matters is if your Perl script is in Unicode,
+that is, encoded in UTF-8/UTF-16/UTF-EBCDIC: then an explicit C<use utf8>
+is needed.)
Figuring out the hexadecimal sequence of a Unicode character you want
or deciphering someone else's hexadecimal Unicode regexp is about as
represent or match the astrological sign for the planet Mercury, we
could use
- use utf8; # We will be doing Unicode processing
use charnames ":full"; # use named chars with Unicode full names
$x = "abc\N{MERCURY}def";
$x =~ /\N{MERCURY}/; # matches
One can also use short names or restrict names to a certain alphabet:
- use utf8; # We will be doing Unicode processing
-
use charnames ':full';
print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n";
escape sequence. C<\C> is a character class akin to C<.> except that
it matches I<any> byte 0-255. So
- use utf8; # We will be doing Unicode processing
use charnames ":full"; # use named chars with Unicode full names
$x = "a";
$x =~ /\C/; # matches 'a', eats one byte
C<\p{name}> class. For example, to match lower and uppercase
characters,
- use utf8; # We will be doing Unicode processing
use charnames ":full"; # use named chars with Unicode full names
$x = "BOB";
$x =~ /^\p{IsUpper}/; # matches, uppercase char class
/\s+[abc[:digit:]xyz]\s*/; # match a,b,c,x,y,z, or a digit
/^=item\s[:digit:]/; # match '=item',
# followed by a space and a digit
- use utf8;
use charnames ":full";
/\s+[abc\p{IsDigit}xyz]\s+/; # match a,b,c,x,y,z, or a digit
/^=item\s\p{IsDigit}/; # match '=item',
=item Important Caveats
Input and Output Disciplines, Regular Expressions, C<use utf8> still needed
-to enable a few features
+to enable UTF-8/UTF-EBCDIC in scripts
=item Byte and Character semantics
=back
+=head2 perldos - Perl under DOS, W31, W95.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Prerequisites for Compiling Perl on DOS
+
+DJGPP, Pthreads
+
+=item Shortcomings of Perl under DOS
+
+=item Building Perl on DOS
+
+=item Testing Perl on DOS
+
+=item Installation of Perl on DOS
+
+=back
+
+=item BUILDING AND INSTALLING MODULES ON DOS
+
+=over 4
+
+=item Building Prerequisites for Perl on DOS
+
+=item Unpacking CPAN Modules on DOS
+
+=item Building Non-XS Modules on DOS
+
+=item Building XS Modules on DOS
+
+=back
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
=head2 perlepoc, README.epoc - Perl for EPOC
=over 4
=back
+=head2 perlwin32 - Perl under Win32
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Setting Up Perl on Win32
+
+Make, Command Shell, Borland C++, Microsoft Visual C++, Mingw32 with GCC
+
+=item Building
+
+=item Testing Perl on Win32
+
+=item Installation of Perl on Win32
+
+=item Usage Hints for Perl on Win32
+
+Environment Variables, File Globbing, Using perl from the command line,
+Building Extensions, Command-line Wildcard Expansion, Win32 Specific
+Extensions, Running Perl Scripts, Miscellaneous Things
+
+=back
+
+=item BUGS AND CAVEATS
+
+=item AUTHORS
+
+Gary Ng E<lt>71564.1743@CompuServe.COME<gt>, Gurusamy Sarathy
+E<lt>gsar@activestate.comE<gt>, Nick Ing-Simmons
+E<lt>nick@ing-simmons.netE<gt>
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
=head1 PRAGMA DOCUMENTATION
=head2 attrs - set/get attributes of a subroutine (deprecated)
presented with byte data. The implementation is still new and
(particularly on EBCDIC platforms) may need further work.
-=item C<use utf8> still needed to enable a few features
+=item C<use utf8> still needed to enable UTF-8/UTF-EBCDIC in scripts
The C<utf8> pragma implements the tables used for Unicode support.
These tables are automatically loaded on demand, so the C<utf8> pragma
need not normally be used.
However, as a compatibility measure, this pragma must be explicitly
-used to enable recognition of UTF-8 encoded literals and identifiers
-in the source text on ASCII based machines or recognize UTF-EBCDIC
-encoded literals and identifiers on EBCDIC based machines.
+used to enable recognition of UTF-8 in the Perl scripts themselves on
+ASCII based machines or recognize UTF-EBCDIC on EBCDIC based machines.
+B<This should be the only place where an explicit C<use utf8> is needed>.
=back
projects / p5sagit/p5-mst-13.2.git / commitdiff