The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
perl-5.11.2
River stage five • 11292 direct dependents • 32664 total dependents
419 ++
/ legacy

NAME

legacy - Perl pragma to preserve legacy behaviors or enable new non-default behaviors

SYNOPSIS

 use legacy ':5.10'; # Keeps semantics the same as in perl 5.10

 use legacy qw(unicode8bit);

 no legacy;

 no legacy qw(unicode8bit);

DESCRIPTION

Some programs may rely on behaviors that for others are problematic or even wrong. A new version of Perl may change behaviors from past ones, and when it is viewed that the old way of doing things may be required to still be supported, the new behavior will be able to be turned off by using this pragma.

Additionally, a new behavior may be supported in a new version of Perl, but for whatever reason the default remains the old one. This pragma can enable the new behavior.

Like other pragmas (use feature, for example), use legacy qw(foo) will only make the legacy behavior for "foo" available from that point to the end of the enclosing block.

use legacy

Preserve the old way of doing things when a new version of Perl is released that would otherwise change the behavior.

The one current possibility is:

unicode8bit

THIS IS SUBJECT TO CHANGE

Use legacy semantics for the 128 characters on ASCII systems that have the 8th bit set. (See "EBCDIC platforms" below for EBCDIC systems.) Unless use locale is specified, or the scalar containing such a character is known by Perl to be encoded in UTF8, the semantics are essentially that the characters have an ordinal number, and that's it. They are caseless, and aren't anything: they're not controls, not letters, not punctuation, ..., not anything.

This behavior stems from when Perl did not support Unicode, and ASCII was the only known character set outside of use locale. In order to not possibly break pre_Unicode programs, these characters have retained their old non-meanings, except when it is clear to Perl that Unicode is what is meant, for example by calling utf8::upgrade() on a scalar, or if the scalar also contains characters that are only available in Unicode. Then these 128 characters take on their Unicode meanings.

The problem with this behavior is that a scalar that encodes these characters has a different meaning depending on if it is stored as utf8 or not. In general, the internal storage method should not affect the external behavior.

The behavior is known to have effects on these areas:

  • Changing the case of a scalar, that is, using uc(), ucfirst(), lc(), and lcfirst(), or \L, \U, \u and \l in regular expression substitutions.

  • Using caseless (/i) regular expression matching

  • Matching a number of properties in regular expressions, such as \w

  • User-defined case change mappings. You can create a ToUpper() function, for example, which overrides Perl's built-in case mappings. The scalar must be encoded in utf8 for your function to actually be invoked.

This lack of semantics for these characters is currently the default, outside of use locale. See below for EBCDIC. To turn on case changing semantics only for these characters, use no legacy. The other legacy behaviors regarding these characters are currently unaffected by this pragma.

EBCDIC platforms

On EBCDIC platforms, the situation is somewhat different. The legacy semantics are whatever the underlying semantics of the native C language library are. Each of the three EBCDIC encodings currently known by Perl is an isomorph of the Latin-1 character set. That means every character in Latin-1 has a corresponding EBCDIC equivalent, and vice-versa. Specifying no legacy currently makes sure that all EBCDIC characters have the same casing only semantics as their corresponding Latin-1 characters.

no legacy

Turn on a new behavior in a version of Perl that understands it but has it turned off by default. For example, no legacy 'foo' turns on behavior foo in the lexical scope of the pragma. no legacy without any modifier turns on all new behaviors known to the pragma.

LEGACY BUNDLES

It's possible to turn off all new behaviors past a given release by using a legacy bundle, which is the name of the release prefixed with a colon, to distinguish it from an individual legacy behavior.

Specifying sub-versions such as the 0 in 5.10.0 in legacy bundles has no effect: legacy bundles are guaranteed to be the same for all sub-versions.

Legacy bundles are not allowed with no legacy