View Source Zhuyin (hanyutils v0.3.0)
Utilities to deal with zhuyin syllables and groups thereof.
The main goal of this module is to provide functions to manipulate strings that contain zhuyin
words, which are potentially mixed with other content. These strings are represented by the
zhuyin_list/0 type. Zhuyin lists can be obtained by parsing a string with the read/2,
read!/2 or sigil_z/2 functions. Afterwards, these lists can be converted into astring
representation by using to_string/1n.
A zhuyin_list/0 is a list which contains strings and zhuyin structs (t/0). These structs
are used to encode zhuyin syllables; they can be created directly through the use of the
from_string/1 or from_string!/1 functions. Like t:zhuyin_lists/0, t/0 structs can be
converted strings through the use of the to_string/1functions.
Additionally both zhuyin_list/0 and zhuyin structs (t/0) can be created from or
converted to pinyin structs (Pinyin.t:t/0) using from_pinyin/1 or to_pinyin/1 or
Link to this section Summary
Functions
Create zhuyin structs from a pinyin struct or list.
Create a single zhuyin struct (t/0) from a string.
Create a single zhuyin struct (t/0) from a string.
Read a string and convert it into a list of strings and zhuyin structs.
Identical to read/2, but returns the result or a ParseError
Sigil to create a zhuyin list or struct.
Create pinyin structs from a zhuyin struct or list.
Link to this section Types
List of zhuyin syllables mixed with plain strings.
Link to this section Functions
@spec from_pinyin(Pinyin.t() | Pinyin.pinyin_list()) :: t()
Create zhuyin structs from a pinyin struct or list.
examples
Examples
iex> Zhuyin.from_pinyin(~p/nǐhǎo/)
[%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}, %Zhuyin{initial: "ㄏ", final: "ㄠ", tone: 3}]
iex> Zhuyin.from_pinyin(%Pinyin{initial: "n", final: "i", tone: 3})
%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}Create a single zhuyin struct (t/0) from a string.
This function can be used to parse a single zhuyin syllable.
If parsing fails, an {:error, <remainder of string>} is returned, <remainder of string>
contains the part of the string which made parsing fail.
examples
Examples
iex> Zhuyin.from_string("ㄋㄧˇ")
{:ok, %Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}}
iex> Zhuyin.from_string("ㄋㄧˇㄏㄠˇ")
{:error, "ㄏㄠˇ"}
iex> Zhuyin.from_string("ㄋㄧˇhǎo")
{:error, "hǎo"}Create a single zhuyin struct (t/0) from a string.
Like from_string/1, but returns the result or raises an exception if an error occurred while
parsing.
examples
Examples
iex> Zhuyin.from_string!("ㄋㄧˇ")
%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}
iex> Zhuyin.from_string!("ㄋㄧˇㄏㄠˇ")
** (ParseError) Error occurred when attempting to parse: "ㄏㄠˇ"
iex> Zhuyin.from_string!("ㄋㄧˇhǎo")
** (ParseError) Error occurred when attempting to parse: "hǎo"@spec read(String.t(), :exclusive | :words | :mixed) :: {:ok, zhuyin_list()} | {:error, String.t()}
Read a string and convert it into a list of strings and zhuyin structs.
This function reads a string containing zhuyin words mixed with normal text. The output of this function is a list of strings and zhuyin structs. White space and punctuation will be separated from other strings.
parse-modes
Parse Modes
By default, this function only accepts strings which consists exclusively of zhuyin, whitespace and punctuation. Parsing any text that cannot be interpreted as zhuyin will result in an error:
iex> Zhuyin.read("ㄋㄧˇㄏㄠˇ!")
{:ok, [%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}, %Zhuyin{initial: "ㄏ", final: "ㄠ", tone: 3}, "!"]}
iex> Zhuyin.read("ㄋㄧˇㄏㄠˇ, hello!")
{:error, "hello!"}This behaviour can be tweaked if zhuyin mixed with regular text needs to be parsed; this can be
done by passing a mode to this function. There are 3 available modes:
:exclusive: The default. Every character (except white space and punctuation) is interpreted as zhuyin. If this is not possible, an error is returned.:words: Any word (i.e. a continuous part of the string that does not contain whitespace or punctuation) is either interpreted as a sequence of zhuyin syllables or as non-pinyin text. If a word contains any characters that cannot be interpreted as zhuyin, the whole word is considered to be non-zhuyin text. This mode does not return errors.:mixed: Any word can contain a mixture of zhuyin and non-zhuyin characters. The read function will interpret anything it can interpret as zhuyin as zhuyin and leaves the other text unmodified. This is mainly useful to mix characters and zhuyin. It is recommend to use the:wordsmode when possible instead of this mode, as this mode will often parse regular text as zhuyin text. This mode does not return errors.
The following examples show the use of all three modes:
iex> Zhuyin.read("ㄋㄧˇㄏㄠˇ!", :exclusive)
{:ok, [%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}, %Zhuyin{initial: "ㄏ", final: "ㄠ", tone: 3}, "!"]}
iex> Zhuyin.read("ㄋㄧˇㄏㄠˇ, hello!", :exclusive)
{:error, "hello!"}
iex> Zhuyin.read("ㄋㄧˇ好, hello!", :exclusive)
{:error, "ㄋㄧˇ好, hello!"}
iex> Zhuyin.read("ㄋㄧˇㄏㄠˇ!", :words)
{:ok, [%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}, %Zhuyin{initial: "ㄏ", final: "ㄠ", tone: 3}, "!"]}
iex> Zhuyin.read("ㄋㄧˇㄏㄠˇ, hello!", :words)
{:ok, [%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}, %Zhuyin{initial: "ㄏ", final: "ㄠ", tone: 3}, ", ", "hello", "!"]}
iex> Zhuyin.read("ㄋㄧˇ好, hello!", :words)
{:ok, ["ㄋㄧˇ好", ", ", "hello", "!"]}
iex> Zhuyin.read("ㄋㄧˇㄏㄠˇ!", :mixed)
{:ok, [%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}, %Zhuyin{initial: "ㄏ", final: "ㄠ", tone: 3}, "!"]}
iex> Zhuyin.read("ㄋㄧˇㄏㄠˇ, hello!", :mixed)
{:ok, [%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}, %Zhuyin{initial: "ㄏ", final: "ㄠ", tone: 3}, ", ", "hello", "!"]}
iex> Zhuyin.read("ㄋㄧˇ好, hello!", :mixed)
{:ok, [%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}, "好", ", ", "hello", "!"]}@spec read!(String.t(), :exclusive | :words | :mixed) :: zhuyin_list() | no_return()
Identical to read/2, but returns the result or a ParseError
examples
Examples
iex> Zhuyin.read!("ㄋㄧˇㄏㄠˇ!")
[%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}, %Zhuyin{initial: "ㄏ", final: "ㄠ", tone: 3}, "!"]
iex> Zhuyin.read!("ㄋㄧˇㄏㄠˇ, hello!")
** (ParseError) Error occurred when attempting to parse: "hello!"
iex> Zhuyin.read!("ㄋㄧˇㄏㄠˇ, hello!", :words)
[%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3}, %Zhuyin{initial: "ㄏ", final: "ㄠ", tone: 3}, ", ", "hello", "!"]Sigil to create a zhuyin list or struct.
When used without any modifiers, this sigil converts its input into a zhuyin list through the
use of read!/2 in :exclusive mode. The w and m modifiers can be used to use :words or
:mixed mode respectively.
When this sigil is called with the s modifier, a zhuyin struct is created by calling
from_string!/1.
examples
Examples
iex> ~z/ㄋㄧˇ/
[%Zhuyin{tone: 3, initial: "ㄋ", final: "ㄧ"}]
iex> ~z/ㄋㄧˇ hello/w
[%Zhuyin{tone: 3, initial: "ㄋ", final: "ㄧ"}, " ", "hello"]
iex> ~z/ㄋㄧˇ好/m
[%Zhuyin{tone: 3, initial: "ㄋ", final: "ㄧ"}, "好"]
iex> ~z/ㄋㄧˇ/s
%Zhuyin{tone: 3, initial: "ㄋ", final: "ㄧ"}@spec to_pinyin(t() | zhuyin_list()) :: Pinyin.t() | Pinyin.pinyin_list()
Create pinyin structs from a zhuyin struct or list.
examples
Examples
iex> Zhuyin.to_pinyin(~z/ㄋㄧˇㄏㄠˇ/)
~p/nǐhǎo/
iex> Zhuyin.to_pinyin(%Zhuyin{initial: "ㄋ", final: "ㄧ", tone: 3})
%Pinyin{initial: "n", final: "i", tone: 3}