charnames - define character names for C<\N{named}> string literal escape.

- NAME
- SYNOPSIS
- DESCRIPTION
- CUSTOM TRANSLATORS
- BUGS

# NAME

charnames - define character names for `\N{named}` string literal escape.

# SYNOPSIS

      use charnames ':full';
      print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n";

      use charnames ':short';
      print "\N{greek:Sigma} is an upper-case sigma.\n";

      use charnames qw(cyrillic greek);
      print "\N{sigma} is Greek sigma, and \N{be} is Cyrillic b.\n";

# DESCRIPTION

Pragma `use charnames` supports arguments `:full`, `:short` and script names. If `:full` is present, for expansion of `\N{CHARNAME}}` string `CHARNAME` is first looked in the list of standard Unicode names of chars. If `:short` is present, and `CHARNAME` has the form `SCRIPT:CNAME`, then `CNAME` is looked up as a letter in script `SCRIPT`. If pragma `use charnames` is used with script name arguments, then for `\N{CHARNAME}}` the name `CHARNAME` is looked up as a letter in the given scripts (in the specified order).

For lookup of `CHARNAME` inside a given script `SCRIPTNAME` this pragma looks for the names

      SCRIPTNAME CAPITAL LETTER CHARNAME
      SCRIPTNAME SMALL LETTER CHARNAME
      SCRIPTNAME LETTER CHARNAME

in the table of standard Unicode names. If `CHARNAME` is lowercase, then the `CAPITAL` variant is ignored, otherwise the `SMALL` variant is ignored.

# CUSTOM TRANSLATORS

The mechanism of translation of `\N{...}` escapes is general and not hardwired into charnames.pm. A module can install custom translations (inside the scope which `use`s the module) with the following magic incantation:

        use charnames ();           # for $charnames::hint_bits
        sub import {
            shift;
            $^H |= $charnames::hint_bits;
            $^H{charnames} = \&translator;
        }

Here `translator()` is a subroutine which takes `CHARNAME` as an argument, and returns text to insert into the string instead of the `\N{CHARNAME}` escape. Since the text to insert should be different in `bytes` mode and out of it, the function should check the current state of `bytes`-flag as in:

        use bytes ();                       # for $bytes::hint_bits
        sub translator {
            if ($^H & $bytes::hint_bits) {
                return bytes_translator(@_);
            }
            else {
                return utf8_translator(@_);
            }
        }

# BUGS

Since evaluation of the translation function happens in a middle of compilation (of a string literal), the translation function should not do any `eval`s or `require`s. This restriction should be lifted in a future version of Perl.

charnames - define character names for C<\N{named}> string literal escape.