@spec added(map() | String.t()) :: String.t() | nil

For grandfathered or redundant tags, returns a date string reflecting the date the tag was added to the registry.

Examples

iex> LangTags.Tag.added("cel-gaulish")
"2001-05-25"

@spec deprecated(map() | String.t()) :: String.t() | nil

For grandfathered or redundant tags, returns a date string reflecting the deprecation date if the tag is deprecated.

Examples

iex> LangTags.Tag.deprecated("art-lojban")
"2003-09-02"
iex> "zh-cmn-Hant" |> LangTags.Tag.new() |> LangTags.Tag.deprecated()
"2009-07-29"

@spec descriptions(map() | String.t()) :: String.t() | []

Returns a list of tag descriptions for grandfathered or redundant tags, otherwise returns an empty list.

Examples

iex> LangTags.Tag.descriptions("art-lojban")
["Lojban"]

@spec errors(map() | String.t()) :: [error()]

Returns every reason the tag is invalid, or an empty list if it is valid.

Each entry is a map with a :code, the offending :subtag, and a human-readable :message. All problems are reported, not just the first, so a caller can show them together rather than one per attempt.

Possible codes:

• :deprecated - the tag itself is registered but deprecated
• :subtag_deprecated - a subtag is deprecated
• :no_language - the tag does not begin with a language subtag
• :unknown - a code is not in the registry
• :too_long - a private-use subtag exceeds 8 characters
• :extra_language, :extra_extlang, :extra_script, :extra_region - a subtag type that may appear only once appears more than once
• :duplicate_variant - the same variant subtag appears twice
• :wrong_order - subtags are not in the order required by the ABNF
• :suppress_script - the script subtag is the language's default and should be omitted

Examples

iex> LangTags.Tag.errors("en-GB")
[]

iex> [error] = LangTags.Tag.errors("art-lojban")
iex> error.code
:deprecated

iex> [error] = LangTags.Tag.errors("en-en")
iex> {error.code, error.subtag}
{:extra_language, "en"}

iex> [error] = LangTags.Tag.errors("gsw-Latn")
iex> error.message
"the script subtag 'latn' is the default for language 'gsw' and should be omitted"

@spec find(map() | String.t(), String.t()) :: map()

Find a subtag of the given type from those making up the tag.

Examples

iex> LangTags.Tag.find("az-arab", "script")
%{"Record" => %{"Added" => "2005-10-16", "Description" => ["Arabic"],
  "Subtag" => "arab", "Type" => "script"}, "Subtag" => "arab"}

@spec format(map() | String.t()) :: String.t()

Format a tag according to the case conventions defined in RFC 5646 section 2.1.1.

Examples

iex> LangTags.Tag.format("en-gb-oed")
"en-GB-oed"
iex> "en-gb" |> LangTags.Tag.new() |> LangTags.Tag.format()
"en-GB"

@spec grandfathered?(String.t()) :: boolean()

Returns true if the tag is grandfathered, otherwise returns false

Examples

iex> LangTags.Tag.grandfathered?("zh-xiang")
true
iex> LangTags.Tag.grandfathered?("az-Arab")
false

@spec language(map() | String.t()) :: map()

Shortcut for find/2 with a language filter

Examples

iex> LangTags.Tag.language("az-arab")
%{"Record" => %{"Added" => "2005-10-16", "Description" => ["Azerbaijani"],
  "Scope" => "macrolanguage", "Subtag" => "az", "Type" => "language"},
  "Subtag" => "az"}

@spec new(String.t()) :: map()

Creates a new tag as a map

Examples

iex> LangTags.Tag.new("en-gb-oed")
%{"Record" => %{"Added" => "2003-07-09", "Deprecated" => "2015-04-17",
    "Description" => ["English, Oxford English Dictionary spelling"],
    "Preferred-Value" => "en-GB-oxendict", "Tag" => "en-gb-oed",
    "Type" => "grandfathered"}, "Tag" => "en-gb-oed"}

@spec preferred(map() | String.t()) :: map() | nil

If the tag is listed as deprecated or redundant it might have a preferred value. This method returns a tag as a map if so.

Examples

iex> LangTags.Tag.preferred("i-klingon")
%{"Tag" => "tlh"}
iex> "zh-cmn-Hant" |> LangTags.Tag.new() |> LangTags.Tag.preferred()
%{"Tag" => "cmn-hant"}

@spec redundant?(String.t()) :: boolean()

Returns true if the tag is redundant, otherwise returns false

Examples

iex> LangTags.Tag.redundant?("az-Arab")
true
iex> LangTags.Tag.redundant?("zh-xiang")
false

@spec region(map() | String.t()) :: map()

Shortcut for find/2 with a region filter

Examples

iex> LangTags.Tag.region("en-gb-oeb")["Record"]["Description"] == ["United Kingdom"]
true

@spec script(map() | String.t()) :: map()

Shortcut for find/2 with a script filter

Examples

iex> LangTags.Tag.script("az-arab")
%{"Record" => %{"Added" => "2005-10-16", "Description" => ["Arabic"],
  "Subtag" => "arab", "Type" => "script"}, "Subtag" => "arab"}

@spec subtags(map() | String.t()) :: [map()] | []

Returns a list of subtags making up the tag, as Subtag maps.

Note that if the tag is grandfathered the result will be an empty list

Examples

iex> LangTags.Tag.subtags("en-gb-oed")
[]
iex> LangTags.Tag.subtags("az-arab")
LangTags.Tag.subtags("az-arab")

@spec type(map() | String.t()) :: String.t()

Returns "grandfathered" if the tag is grandfathered, "redundant" if the tag is redundant, and "tag" if neither.

For a definition of grandfathered and redundant tags, see RFC 5646 section 2.2.8.

Examples

iex> LangTags.Tag.type("art-lojban")
"grandfathered"
iex> LangTags.Tag.type("az-Arab")
"redundant"

@spec valid?(map() | String.t()) :: boolean()

Returns true if the tag is valid, false otherwise.

A tag is valid when every subtag is registered, appears in the order required by RFC 5646 section 2.2.9, and is not deprecated. See errors/1 for why a tag was rejected.

Examples

iex> LangTags.Tag.valid?("en-GB")
true
iex> LangTags.Tag.valid?("en-en")
false
iex> LangTags.Tag.valid?("wubble")
false