Introduce NVef, NVff, and NVgf, use the middle one.
[perl.git] / lib / utf8.pm
1 package utf8;
2
3 $utf8::hint_bits = 0x00800000;
4
5 sub import {
6     $^H |= $utf8::hint_bits;
7     $enc{caller()} = $_[1] if $_[1];
8 }
9
10 sub unimport {
11     $^H &= ~$utf8::hint_bits;
12 }
13
14 sub AUTOLOAD {
15     require "utf8_heavy.pl";
16     goto &$AUTOLOAD if defined &$AUTOLOAD;
17     Carp::croak("Undefined subroutine $AUTOLOAD called");
18 }
19
20 1;
21 __END__
22
23 =head1 NAME
24
25 utf8 - Perl pragma to enable/disable UTF-8 in source code
26
27 =head1 SYNOPSIS
28
29     use utf8;
30     no utf8;
31
32 =head1 DESCRIPTION
33
34 WARNING: The implementation of Unicode support in Perl is incomplete.
35 See L<perlunicode> for the exact details.
36
37 The C<use utf8> pragma tells the Perl parser to allow UTF-8 in the
38 program text in the current lexical scope.  The C<no utf8> pragma
39 tells Perl to switch back to treating the source text as literal
40 bytes in the current lexical scope.
41
42 This pragma is primarily a compatibility device.  Perl versions
43 earlier than 5.6 allowed arbitrary bytes in source code, whereas
44 in future we would like to standardize on the UTF-8 encoding for
45 source text.  Until UTF-8 becomes the default format for source
46 text, this pragma should be used to recognize UTF-8 in the source.
47 When UTF-8 becomes the standard source format, this pragma will
48 effectively become a no-op.
49
50 Enabling the C<utf8> pragma has the following effects:
51
52 =over
53
54 =item *
55
56 Bytes in the source text that have their high-bit set will be treated
57 as being part of a literal UTF-8 character.  This includes most literals
58 such as identifiers, string constants, constant regular expression patterns
59 and package names.
60
61 =item *
62
63 In the absence of inputs marked as UTF-8, regular expressions within the
64 scope of this pragma will default to using character semantics instead
65 of byte semantics.
66
67     @bytes_or_chars = split //, $data;  # may split to bytes if data
68                                         # $data isn't UTF-8
69     {
70         use utf8;                       # force char semantics
71         @chars = split //, $data;       # splits characters
72     }
73
74 =head1 SEE ALSO
75
76 L<perlunicode>, L<bytes>
77
78 =cut