A class to parse names of people. Different locales have different conventions when it
comes to naming people.
The options can contain any of the following properties:
- locale - use the rules and conventions of the given locale in order to parse
the name
- style - explicitly use the named style to parse the name. Valid values so
far are "western" and "asian". If this property is not specified, then the style will
be gleaned from the name itself. This class will count the total number of Latin or Asian
characters. If the majority of the characters are in one style, that style will be
used to parse the whole name.
- order - explicitly use the given order for names. In some locales, such
as Russian, names may be written equally validly as "givenName familyName" or "familyName
givenName". This option tells the parser which order to prefer, and overrides the
default order for the locale. Valid values are "gf" (given-family) or "fg" (family-given).
- useSpaces - explicitly specifies whether to use spaces or not between the given name , middle name
and family name.
- compoundFamilyName - for Asian and some other types of names, search for compound
family names. If this parameter is not specified, the default is to use the setting that is
most common for the locale. If it is specified, the locale default is
overridden with this flag.
- onLoad - a callback function to call when the name info is fully
loaded and the name has been parsed. When the onLoad option is given, the name object
will attempt to load any missing locale data using the ilib loader callback.
When the constructor is done (even if the data is already preassembled), the
onLoad function is called with the current instance as a parameter, so this
callback can be used with preassembled or dynamic loading or a mix of the two.
- sync - tell whether to load any missing locale data synchronously or
asynchronously. If this option is given as "false", then the "onLoad"
callback must be given, as the instance returned from this constructor will
not be usable for a while.
- loadParams - an object containing parameters to pass to the
loader callback function when locale data is missing. The parameters are not
interpretted or modified in any way. They are simply passed along. The object
may contain any property/value pairs as long as the calling code is in
agreement with the loader callback function as to what those parameters mean.
Additionally, a name instance can be constructed by giving the explicit
already-parsed fields or by using another name instance as the parameter. (That is,
it becomes a copy constructor.) The name fields can be any of the following:
- prefix - the prefix prepended to the name
- givenName - the person's given or "first" name
- middleName - one or more middle names, separated by spaces even if the
language doesn't use usually use spaces. The spaces are merely separators.
- familyName - one or more family or "last" names, separated by spaces
even if the language doesn't use usually use spaces. The spaces are merely separators.
- suffix - the suffix appended to the name
- honorific - the honorific title of the name. This could be formatted
as a prefix or a suffix, depending on the customs of the particular locale. You
should only give either an honorific or a prefix/suffix, but not both.
When the parser has completed its parsing, it fills in the same fields as listed
above.
For names that include auxilliary words, such as the family name "van der Heijden", all
of the auxilliary words ("van der") will be included in the field.
For names in some Spanish locales, it is assumed that the family name is doubled. That is,
a person may have a paternal family name followed by a maternal family name. All
family names will be listed in the familyName field as normal, separated by spaces.
When formatting the short version of such names, only the paternal family name is used.