/ 
PersonName-Format-v0.1.0
/ PersonName::Format

NAME

PersonName::Format - CLDR person-name formatter for Perl

SYNOPSIS

my $formatter = PersonName::Format->new(
    'ja-JP',
    length         => 'long',
    usage          => 'referring',
    formality      => 'formal',
    displayOrder   => 'default',
    surnameAllCaps => 0,
);

# Native Japanese order: 宮崎駿
my $native = $formatter->format(
    given      => '駿',
    surname    => '宮崎',
    nameLocale => 'ja-JP',
);

# Japanese formatter switching to Latin conventions for a foreign name
my $foreign = $formatter->format(
    given      => 'Albert',
    surname    => 'Einstein',
    nameLocale => 'de-CH',
);

# Pass a hash reference instead of a flat list
my $by_ref = $formatter->format({
    given      => 'Albert',
    surname    => 'Einstein',
    nameLocale => 'de-CH',
});

# Or pass any object that satisfies the name contract
my $by_obj = $formatter->format( $my_name_object );

DESCRIPTION

PersonName::Format formats structured personal names using CLDR person-name patterns provided by Locale::Unicode::Data.

The formatter derives the name script by inspecting the surname and then the given name, derives or adjusts the name locale using likely-subtag data, compares the name and formatting scripts, and switches to an effective formatting locale when required by UTS #35 Part 8.

The implementation is pure Perl. Script detection is intentionally isolated so it can later be replaced by an optional XS backend without changing the public API.

CONSTRUCTOR

new

my $formatter = PersonName::Format->new( $locale, %options );

Creates a new formatter. The first positional argument is the BCP 47 formatting locale tag (required). All remaining arguments are named options documented under "CONSTRUCTOR OPTIONS".

CONSTRUCTOR OPTIONS

display_order

displayOrder

default, givenFirst, surnameFirst, or sorting.

formality

formal or informal. When omitted, the CLDR default inherited by the formatter locale is used.

length

long, medium, or short. When omitted, the CLDR default inherited by the formatter locale is used.

surname_all_caps

surnameAllCaps

Boolean option causing surname fields to be rendered in uppercase.

usage

referring, addressing, or monogram. Defaults to referring.

METHODS

compile

my $compiled = $formatter->compile(
    nameLocale => 'fr-FR',
    nameScript => 'Latn',
);

Returns a PersonName::Format::Compiled object with the name identity and resolved CLDR context frozen. nameScript is required. nameLocale and preferredOrder are optional but, when supplied, are enforced for every name formatted by the compiled object.

format

my $string = $formatter->format( $name_object );
my $string = $formatter->format( \%fields );
my $string = $formatter->format( given => 'John', surname => 'Doe' );

Formats a name and returns the resulting string. The argument may be:

The name locale may be omitted. When present, its language and region are retained and its script is replaced by the script detected in the name data.

format_to_parts

my $parts = $formatter->format_to_parts( \%fields );

Returns an array reference of hash references describing the generated parts. Literal spacing replacement is applied only to literal parts. Each hash has the following keys:

type

For field parts, the CLDR pattern field expression such as given or given-initial. For spacing between fields, the value is literal.

value

The rendered text for this part.

field

Present on non-literal parts. The base CLDR field name such as given or surname.

modifiers

Present on non-literal parts when modifiers were resolved. An array reference of modifier names.

resolved_options

Returns the resolved constructor options. Per-name derived locales are not constructor options and are therefore not included.

resolvedOptions

Alias for resolved_options().

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.