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:

    *   any object satisfying the name contract (see
        "implements_name_contract" in PersonName::Format::Name)

    *   a hash reference of name fields

    *   a flat key/value list of name fields

    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.