View Source Cldr.PersonName behaviour (Cldr Person Names v0.2.1)
ex_cldr_person_names
provides formatting for person names, such as John Smith or 宮崎駿 based upon the CLDR Person Names specification. These use patterns to show how a name object (for example, from a database) should be formatted for a particular locale. Name data has fields for the parts of people’s names, such as a given name field with a value of “Maria”, and a surname field value of “Schmidt”.
There is a wide variety in the way that people’s names appear in different languages.
- People may have a different number of names, depending on their culture—they might have only one name (“Zendaya”), two (“Albert Einstein”), or three or more.
- People may have multiple words in a particular name field, eg “Mary Beth” as a given name, or “van Berg” as a surname.
- Some languages, such as Spanish, have two surnames (where each can be composed of multiple words).
- The ordering of name fields can be different across languages, as well as the spacing (or lack thereof) and punctuation.
- Name formatting needs to be adapted to different circumstances, such as a need to be presented shorter or longer; formal or informal context; or when talking about someone, or talking to someone, or as a monogram (JFK).
The ex_cldr_person_names
functionality is targeted at formatting names for typical usage on computers (e.g. contact names, automated greetings, etc.), rather than being designed for special circumstances or protocol, such addressing royalty. However, the structure may be enhanced in the future when it becomes clear that additional features are needed for some languages.
Not in scope
The following features are currently out of scope for Person Names formating:
- Grammatical inflection of formatted names.
- Context-specific cultural aspects, such as when to use “-san” vs “-sama” when addressing a Japanese person.
- Providing locale-specific lists of titles, generation terms, and credentials for use in pull-down menus or validation (Mr, Ms., Mx., Dr., Jr., M.D., etc.).
- Validation of input, such as which fields are required, and what characters are allowed.
- Combining alternative names, such as multicultural names in Hong Kong "Jackie Chan Kong-Sang”, or ‘Dwayne “The Rock” Johnson’.
- More than two levels of formality for names.
- Parsing of names.
- Parsing of name strings into specific name parts such as given and given2. A name like "Mary Beth Estrella" could conceivably be any of the following.
Given Name Other Given Names Surname Other Surnames Mary Beth Estrella Mary Beth Estrella Mary Beth Estrella Mary Beth Estrella - Parsing out the other components of a name in a string, such as surname prefixes (Tussenvoegsel in Dutch).
Structure of a Person Name
Person name formatting depends on data supplied by a Cldr.PersonName.t/0
data structure. A Cldr.PersonName
behaviour and a Cldr.PersonName.Format
protocol are provided to support easy integration with existing data structures.
The Cldr.PersonName.t/0
struct is composed of one or more name parts:
title
- a string that represents one or more honorifics or titles, such as “Mr.”, or “Herr Doctor”.given_name
- usually a name given to someone that is not passed to a person by way of parentage.informal_given_name
- usually either a nickname or a shortened form of the given name that is used to address a person informally.other_given_names
- name or names that may appear between the first given name string and the surname. In the West, this may be a middle name, in Slavic regions it may be a patronymic name, and in parts of the Middle East, it may be the nasab (نسب) or series of patronymics.surname_prefix
- in some languages the surname may have a prefix that needs to be treated differently, for example “van den Berg”.surname
- usually the family name passed to a person that indicates their family, tribe, or community. In most Western languages, this is known as the last name.other_surnames
- in some cultures, both the parent’s surnames are used and need to be handled separately for formatting in different contexts.generation
- a string that represents a generation marker, such as “Jr.” or “III”.credentials
- a string that represents one or more credentials or accreditations, such as “M.D.”, or “MBA”.locale
- defines thet.Cldr.LanguageTag.t/0
of a name. This allows different formatting of a name depending on whether it is being formatted for its native locale, or for a different locale.preferred_order
- an atom indicating the preferred name order for this name. The valid values are:given_first
,:surname_first
,:sorting
. By default,ex_cldr_person_names
will derive the name order based upon the name's locale and the formatting locale.
At mininum, a given_name
is required. All other name attributes are optional.
Integration with Existing Data
Its clear that existing person name data isn't going to be neatly structured in a Cldr.PersonName.t/0
. ex_cldr_person_names
provides two mechanisms to integrate existing data:
The
Cldr.PersonName
behaviour can be used when the developer has control over the data structure, and the data structure is an Elixirstruct
. This is the recommended approach when the developer has control over the struct module. In this case, callbacks can be implemented for thestruct
that return the person name data to the formatter. The formatter implementation will callCldr.PersonName.cast_to_person_name/1
using the callbacks.The
Cldr.PersonName.Format
protocol is useful when the developer has no control over the existing data structure. Therefore theCldr.PesonName.Format.to_string/2
function can be called and the protocol implementation is expected to craft a structure compatible with - or actually is - aCldr.PersonName.t/0
struct, and then calls theCldr.PersonName.to_string/2
function. SinceCldr.PersonName.t/0
implements theCldr.PersonName.Format
protocol,Cldr.PersonName.Format.to_string/2
can be used consistently throughout an application if preferred.
Summary
Types
Standard error response
A PersonName struct containing the fields supported
for person name formatting. Any struct that implements
the Cldr.PersonName
behaviour can be converted
to this struct by calling Cldr.PersonName.cast_to_person_name/1
.
Callbacks
Return the credentials as a String.t/0
or nil
for the given struct
Return the generation as a String.t/0
or nil
for the given struct
Return the given name as a String.t/0
or nil
for the given struct
Return the informal given name as a String.t/0
or nil
for the given struct
Return the locale reference or nil for the given struct
Return the other given names as a String.t/0
or nil
for the given struct
Return the other surnames as a String.t/0
or nil
for the given struct
Return the other preferred name order for the given struct
Return the surname as a String.t/0
or nil
for the given struct
Return the surname prefix as a String.t/0
or nil
for the given struct
Return the title as a String.t/0
or nil
for the given struct
Functions
Casts any struct that implements the Cldr.PersonName
behaviour into a Cldr.PersonName.t/0
struct.
Returns a Cldr.PersonName.t/0
struct crafted
from a keyword list of attributes.
Returns a formatted person name as an
:erlang.iodata
term.
Returns a formatted person name as an
:erlang.iodata
term.
Returns a formatted person name as an
:erlang.iodata
term.
Types
Standard error response
@type t() :: %Cldr.PersonName{ credentials: String.t() | nil, generation: String.t() | nil, given_name: String.t() | nil, informal_given_name: String.t() | nil, locale: Cldr.Locale.locale_reference(), other_given_names: String.t() | nil, other_surnames: String.t() | nil, preferred_order: Cldr.PersonName.Formatter.name_order() | nil, surname: String.t() | nil, surname_prefix: String.t() | nil, title: String.t() | nil }
A PersonName struct containing the fields supported
for person name formatting. Any struct that implements
the Cldr.PersonName
behaviour can be converted
to this struct by calling Cldr.PersonName.cast_to_person_name/1
.
Callbacks
Return the credentials as a String.t/0
or nil
for the given struct
Return the generation as a String.t/0
or nil
for the given struct
Return the given name as a String.t/0
or nil
for the given struct
Return the informal given name as a String.t/0
or nil
for the given struct
@callback locale(name :: struct()) :: Cldr.Locale.locale_reference() | nil
Return the locale reference or nil for the given struct
Return the other given names as a String.t/0
or nil
for the given struct
Return the other surnames as a String.t/0
or nil
for the given struct
@callback preferred_order(name :: struct()) :: Cldr.PersonName.Formatter.name_order()
Return the other preferred name order for the given struct
Return the surname as a String.t/0
or nil
for the given struct
Return the surname prefix as a String.t/0
or nil
for the given struct
Return the title as a String.t/0
or nil
for the given struct
Functions
Casts any struct that implements the Cldr.PersonName
behaviour into a Cldr.PersonName.t/0
struct.
Arguments
struct
is any struct that implements theCldr.PersonName
behaviour.
Returns
- A
Cldr.PersonName.t/0
struct.
@spec new(attributes :: Keyword.t()) :: {:ok, t()} | {:error, error_message()}
Returns a Cldr.PersonName.t/0
struct crafted
from a keyword list of attributes.
Arguments
attributes
is a keyword list of person name attributes that is used to contruct aCldr.PersonName.t/0
.
Attributes
:given_name
is a persons given name. This is a required attribute. The value is anyString.t/0
:title
is a person's title such as "Mr," or "Dr.".:other_given_names
is anyString.t/0
ornil
. The default isnil
.:informal_given_name
is anyString.t/0
ornil
. The default isnil
.:surname_prefix
is anyString.t/0
ornil
. The default isnil
.:surname
is anyString.t/0
ornil
. The default isnil
.:other_surnames
is anyString.t/0
ornil
. The default isnil
.:generation
is anyString.t/0
ornil
. The default isnil
.:credentials
is anyString.t/0
ornil
. The default isnil
.:locale
is anyCldr.LanguageTag.t/0
or nil. The default isnil
.:backend
is anyCldr
backend. That is, any module that containsuse Cldr
. This is used to validate the:locale
only. The default isCldr.default_backend!/0
.:name_order
is one of:given_name
,:last_name
or:sorting
. The default isnil
, meaning that the name order is derived from the name's locale and the formatting locale.
Returns
{:ok, person_name_struct}
or{:error, reason}
Examples
iex> Cldr.PersonName.new(title: "Mr.", given_name: "José", surname: "Valim", credentials: "Ph.D.", locale: "pt")
{:ok,
%Cldr.PersonName{
title: "Mr.",
given_name: "José",
other_given_names: nil,
informal_given_name: nil,
surname_prefix: nil,
surname: "Valim",
other_surnames: nil,
generation: nil,
credentials: "Ph.D.",
preferred_order: nil,
locale: AllBackend.Cldr.Locale.new!("pt")
}}
iex> Cldr.PersonName.new(surname: "Valim")
{:error, "Person Name requires at least a :given_name"}
@spec to_iodata( person_name :: struct(), options :: Cldr.PersonName.Formatter.format_options() ) :: {:ok, :erlang.iodata()} | {:error, error_message()}
Returns a formatted person name as an
:erlang.iodata
term.
Arguments
person_name
is any struct that implements theCldr.PersonName
behaviour, including the nativeCldr.PersonName.t/0
struct.options
is a keyword list of options.
Options
:format
is the relative length of a formatted name depending on context. For example, a long formal name in English might include:title
,:given_name
,:other_given_names
,:surname
plus:generation
and:credentials
; whereas a short informal name may only be the:given_name
. The valid values are:short
,:medium
and:long
. The default is derived from the formatting locales preferences.:usage
indicates if the formatted name is being used to address someone, refer to someone, or present their name in an abbreviated form. The valid values are:referring
,:addressing
or:monogram
. The default is:referring
. The pattern for:referring
may be the same as the pattern for:addressing
.:formality
indicates the formality of usage. A name on a badge for an informal gathering may be much different from an award announcement at the Nobel Prize Ceremonies. The valid values are:formal
and:informal
. Note that the formats may be the same for different formality scenarios depending on the length, usage, and cultural conventions for the locale. For example short formal and short informal may both be just the given name. The default is derived from the formatting locale preferences.:order
is used express preference for the orders of attributes in the formatted string. The valid values are:given_first
,:surname_first
and:sorting
. The default is based on features of the person name struct and the formatting locale. The option:sorting
is only every defined as an option - not the person name or locale data.
Notes
The formats may be the same for different lengths depending on the formality, usage, and cultural conventions for the locale.
For example, medium and short may be the same for a particular context.
Returns
{:ok, formatted_name_as_iodata}
or{:error, reason}
.
Examples
iex> {:ok, jose} = Cldr.PersonName.new(title: "Mr.", given_name: "José", surname: "Valim", credentials: "Ph.D.", locale: "pt")
iex> Cldr.PersonName.to_iodata(jose)
{:ok, ["José"]}
iex> Cldr.PersonName.to_iodata(jose, format: :long)
{:ok, ["José"]}
iex> Cldr.PersonName.to_iodata(jose, format: :long, formality: :formal)
{:ok, ["Mr.", " ", "Valim"]}
iex> Cldr.PersonName.to_iodata(jose, format: :long, formality: :formal, usage: :referring)
{:ok, ["Mr.", " ", "José", " ", "Valim", " ", "Ph.D."]}
@spec to_iodata!( person_name :: struct(), options :: Cldr.PersonName.Formatter.format_options() ) :: :erlang.iodata() | no_return()
@spec to_string( name :: struct(), options :: Cldr.PersonName.Formatter.format_options() ) :: {:ok, String.t()} | {:error, error_message()}
Returns a formatted person name as an
:erlang.iodata
term.
Arguments
person_name
is any struct that implements theCldr.PersonName
behaviour, including the nativeCldr.PersonName.t/0
struct.options
is a keyword list of options.
Options
:format
is the relative length of a formatted name depending on context. For example, a long formal name in English might include:title
,:given_name
,:other_given_names
,:surname
plus:generation
and:credentials
; whereas a short informal name may only be the:given_name
. The valid values are:short
,:medium
and:long
. The default is derived from the formatting locales preferences.:usage
indicates if the formatted name is being used to address someone, refer to someone, or present their name in an abbreviated form. The valid values are:referring
,:addressing
or:monogram
. The default is:referring
. The pattern for:referring
may be the same as the pattern for:addressing
.:formality
indicates the formality of usage. A name on a badge for an informal gathering may be much different from an award announcement at the Nobel Prize Ceremonies. The valid values are:formal
and:informal
. Note that the formats may be the same for different formality scenarios depending on the length, usage, and cultural conventions for the locale. For example short formal and short informal may both be just the given name. The default is derived from the formatting locale preferences.:order
is used express preference for the orders of attributes in the formatted string. The valid values are:given_first
,:surname_first
and:sorting
. The default is based on features of the person name struct and the formatting locale. The option:sorting
is only every defined as an option - not the person name or locale data.
Notes
The formats may be the same for different lengths depending on the formality, usage, and cultural conventions for the locale.
For example, medium and short may be the same for a particular context.
Returns
{:ok, formatted_name}
or{:error, reason}
.
Examples
iex> {:ok, jose} = Cldr.PersonName.new(title: "Mr.", given_name: "José", surname: "Valim", credentials: "Ph.D.", locale: "pt")
iex> Cldr.PersonName.to_string(jose)
{:ok, "José"}
iex> Cldr.PersonName.to_string(jose, format: :long)
{:ok, "José"}
iex> Cldr.PersonName.to_string(jose, format: :long, formality: :formal)
{:ok, "Mr. Valim"}
iex> Cldr.PersonName.to_string(jose, format: :long, formality: :formal, usage: :referring)
{:ok, "Mr. José Valim Ph.D."}
@spec to_string!( name :: struct(), options :: Cldr.PersonName.Formatter.format_options() ) :: String.t() | no_return()
Returns a formatted person name as an
:erlang.iodata
term.
Arguments
person_name
is any struct that implements theCldr.PersonName
behaviour, including the nativeCldr.PersonName.t/0
struct.options
is a keyword list of options.
Options
:format
is the relative length of a formatted name depending on context. For example, a long formal name in English might include:title
,:given_name
,:other_given_names
,:surname
plus:generation
and:credentials
; whereas a short informal name may only be the:given_name
. The valid values are:short
,:medium
and:long
. The default is derived from the formatting locales preferences.:usage
indicates if the formatted name is being used to address someone, refer to someone, or present their name in an abbreviated form. The valid values are:referring
,:addressing
or:monogram
. The default is:referring
. The pattern for:referring
may be the same as the pattern for:addressing
.:formality
indicates the formality of usage. A name on a badge for an informal gathering may be much different from an award announcement at the Nobel Prize Ceremonies. The valid values are:formal
and:informal
. Note that the formats may be the same for different formality scenarios depending on the length, usage, and cultural conventions for the locale. For example short formal and short informal may both be just the given name. The default is derived from the formatting locale preferences.:order
is used express preference for the orders of attributes in the formatted string. The valid values are:given_first
,:surname_first
and:sorting
. The default is based on features of the person name struct and the formatting locale. The option:sorting
is only every defined as an option - not the person name or locale data.
Notes
The formats may be the same for different lengths depending on the formality, usage, and cultural conventions for the locale.
For example, medium and short may be the same for a particular context.
Returns
{:ok, formatted_name}
or{:error, reason}
.
Examples
iex> {:ok, jose} = Cldr.PersonName.new(title: "Mr.", given_name: "José", surname: "Valim", credentials: "Ph.D.", locale: "pt")
iex> Cldr.PersonName.to_string!(jose)
"José"
iex> Cldr.PersonName.to_string!(jose, format: :long)
"José"
iex> Cldr.PersonName.to_string!(jose, format: :long, formality: :formal)
"Mr. Valim"
iex> Cldr.PersonName.to_string!(jose, format: :long, formality: :formal, usage: :referring)
"Mr. José Valim Ph.D."