/ 
PersonName-Format-v0.1.1
/ PersonName::Format::PP

NAME

PersonName::Format::PP - Pure-Perl backend for PersonName::Format

SYNOPSIS

# Loaded automatically by PersonName::Format; not intended for direct use.
# Force the pure-Perl path at runtime:
BEGIN { $ENV{PERSONNAME_FORMAT_PUREPERL} = 1 }
use PersonName::Format;

# Or call the primitives directly in tests or tooling:
use PersonName::Format::PP;

my $grapheme = PersonName::Format::PP::_first_grapheme( $string );
my $script   = PersonName::Format::PP::_get_name_script( $surname, $given );

DESCRIPTION

This module provides the pure-Perl implementations of internal Unicode primitives used by PersonName::Format. It is not part of the public API.

The XS backend must return exactly the same values as these functions.

FUNCTIONS

_first_grapheme

my $grapheme = PersonName::Format::PP::_first_grapheme( $value );

Returns the first Unicode extended grapheme cluster from $value. Returns an empty string for an undefined or empty value.

The implementation uses \X as its primary mechanism, but extends the result manually to cover two cases that \X does not handle correctly on older Perl versions:

Regional Indicator pairs (UAX #29 rule GB12/GB13)

Two adjacent Regional Indicator codepoints (U+1F1E6..U+1F1FF) must form a single flag grapheme such as \x{1F1EF}\x{1F1F5} (🇯🇵). \X handles this correctly from Perl 5.18 onward; on Perl 5.16 only the first codepoint is returned.

ZWJ emoji sequences (UAX #29 rule GB11)

A sequence of the form base + ZWJ (U+200D) + emoji must form a single grapheme such as \x{1F469}\x{200D}\x{1F4BB} (👩‍💻). \X handles this correctly from Perl 5.28 onward. On intermediate versions, \X consumes base + ZWJ but stops before the following emoji (case B). On very old versions, \X stops before the ZWJ itself (case C). Both are corrected by post-processing.

Both cases are corrected by post-processing the \X result at the codepoint level. The XS backend must return exactly the same values as this function.

_get_name_script

my $script = PersonName::Format::PP::_get_name_script(
    $surname,
    $given,
);

Returns the first significant Unicode Script code found in the surname and then the given name. Common, Inherited, and Unknown are ignored. Returns Zzzz when no significant script is found.

_script_code_for_uv

my $code = PersonName::Format::PP::_script_code_for_uv( $codepoint );

Returns the ISO 15924 four-letter script code for a Unicode codepoint.

On Perl 5.16 and later, Unicode::UCD::prop_value_aliases() is used directly to resolve the script name returned by Unicode::UCD::charscript(). On earlier versions, the mapping is loaded on first use from PersonName/Format/ScriptNames.pl via require. In both cases, processes that never call _get_name_script pay no memory cost for the table.

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

Copyright(c) 2026 DEGUEST Pte. Ltd.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.