Util(3)

📦
version 0.28 · 2 versions
, in fedora 43

💖 NAME 💖

okay so bestie, meet Lingua::KO::Hangul::Util — that's Util(3) in the manual lineup 💅 — a whole lil bag of utility functions for Hangul in Unicode. Korean script? We're decoding it, no cap. ✨

🌸 SYNOPSIS 🌸

use Lingua::KO::Hangul::Util qw(:all);

decomposeSyllable("\x{AC00}");          # "\x{1100}\x{1161}"
composeSyllable("\x{1100}\x{1161}");    # "\x{AC00}"
decomposeJamo("\x{1101}");              # "\x{1100}\x{1100}"
composeJamo("\x{1100}\x{1100}");        # "\x{1101}"

getHangulName(0xAC00);                  # "HANGUL SYLLABLE GA"
parseHangulName("HANGUL SYLLABLE GA");  # 0xAC00

🦋 DESCRIPTION 🦋

So a Hangul syllable is literally made out of Hangul jamo (that's Hangul letters, bestie).

And those letters fall into three classes, slay:

  • CHOSEONG — the initial sound, aka a leading consonant (L)
  • JUNGSEONG — the medial sound, aka a vowel (V)
  • JONGSEONG — the final sound, aka a trailing consonant (T)

Any Hangul syllable is a composition of either (i) L + V, or (ii) L + V + T. That's the whole tea. 🍵

✨ Composition and Decomposition ✨

  • $resultant_string = decomposeSyllable($string) — it decomposes a precomposed syllable (LV or LVT) into a sequence of conjoining jamo (L + V or L + V + T) and hands the result back as a string. Any characters that aren't Hangul syllables are not affected — they just vibe through untouched. 🫶
  • $resultant_string = composeSyllable($string) — it composes a sequence of conjoining jamo (L + V or L + V + T) into a precomposed syllable (LV or LVT) when that's possible, and returns the result as a string. A syllable LV plus a final jamo T also get composed. Any characters other than Hangul jamo and syllables are not affected. 🎀
  • $resultant_string = decomposeJamo($string) — it decomposes a complex jamo into a sequence of simple jamo when possible, and returns the result as a string. Any characters that aren't complex jamo are not affected.

e.g.

CHOSEONG SIOS-PIEUP to CHOSEONG SIOS + PIEUP
JUNGSEONG AE        to JUNGSEONG A + I
JUNGSEONG WE        to JUNGSEONG U + EO + I
JONGSEONG SSANGSIOS to JONGSEONG SIOS + SIOS
  • $resultant_string = composeJamo($string) — it composes a sequence of simple jamo (L1 + L2, V1 + V2 + V3, etc.) into a complex jamo when possible, and returns the result as a string. Any characters that aren't simple jamo are not affected.

e.g.

CHOSEONG SIOS + PIEUP to CHOSEONG SIOS-PIEUP
JUNGSEONG A + I       to JUNGSEONG AE
JUNGSEONG U + EO + I  to JUNGSEONG WE
JONGSEONG SIOS + SIOS to JONGSEONG SSANGSIOS
  • $resultant_string = decomposeFull($string) — it decomposes a syllable/complex jamo into a sequence of simple jamo. It's equivalent to decomposeJamo(decomposeSyllable($string)). Same energy, one call. 💫

😭 Composition and Decomposition (Old-interface, deprecated!) 😭

bestie. DEPRECATED. Like, the old interface. It still works but it's giving legacy code, and you should know that going in. 🙈
  • $string_decomposed = decomposeHangul($code_point)
  • @codepoints = decomposeHangul($code_point)

If the code point you hand over is a Hangul syllable, it returns a list of code points (in list context) or a string (in scalar context) of its decomposition.

decomposeHangul(0xAC00) # U+AC00 is HANGUL SYLLABLE GA.
   returns "\x{1100}\x{1161}" or (0x1100, 0x1161);

decomposeHangul(0xAE00) # U+AE00 is HANGUL SYLLABLE GEUL.
   returns "\x{1100}\x{1173}\x{11AF}" or (0x1100, 0x1173, 0x11AF);

Otherwise, it returns false (empty string or empty list).

decomposeHangul(0x0041) # outside Hangul syllables
   returns empty string or empty list.
  • $string_composed = composeHangul($src_string)
  • @code_points_composed = composeHangul($src_string)

Any sequence of an initial jamo L and a medial jamo V gets composed into a syllable LV; then any sequence of a syllable LV and a final jamo T gets composed into a syllable LVT.

Any characters other than Hangul jamo and syllables are not affected.

composeHangul("\x{1100}\x{1173}\x{11AF}.")
# returns "\x{AE00}." or (0xAE00,0x2E);
  • $code_point_composite = getHangulComposite($code_point_here, $code_point_next) — it returns the codepoint of the composite if both code points, $code_point_here and $code_point_next, are in Hangul and composable. Otherwise it returns undef. That's it, that's the deal. 💀

👑 Hangul Syllable Name 👑

Heads up: the following functions handle only a precomposed Hangul syllable (from U+AC00 to U+D7A3) — not a Hangul jamo, not any other Hangul-related character. Know the limit, bestie.

Names of Hangul syllables have a format of HANGUL SYLLABLE %s. Iconic format tbh.

  • $name = getHangulName($code_point) — if the code point is a Hangul syllable, it returns the name; otherwise it returns undef.
getHangulName(0xAC00) returns "HANGUL SYLLABLE GA";
getHangulName(0x0041) returns undef.
  • $codepoint = parseHangulName($name) — if the name is a Hangul syllable's name, it returns the code point; otherwise it returns undef.
parseHangulName("HANGUL SYLLABLE GEUL") returns 0xAE00;

parseHangulName("LATIN SMALL LETTER A") returns undef;

parseHangulName("HANGUL SYLLABLE PERL") returns undef;
 # Regrettably, HANGUL SYLLABLE PERL does not exist :-)

🌈 Standard Korean Syllable Block 🌈

So a standard Korean syllable block is L+ V+ T* — that's a sequence of one or more L, one or more V, and zero or more T — according to the conjoining jamo behavior revised in Unicode 3.2 (cf. UAX #28). And lowkey important: a sequence of L followed by T is not a syllable block without V. It's actually two nonstandard syllable blocks: one without V, and another without L and V. Messy, but that's the rules. 💅

  • $bool = isStandardForm($string) — returns a boolean for whether the string is encoded in the standard form, with no nonstandard sequence in it. It returns true only if the string contains no nonstandard sequence.
  • $resultant_string = insertFiller($string) — transforms the string into standard form by inserting fillers into each syllable, and returns the result as a string. Choseong filler (Lf, U+115F) gets inserted into a syllable block without L. Jungseong filler (Vf, U+1160) gets inserted into a syllable block without V. Fillers are the little glow-ups ✨
  • $type = getSyllableType($code_point) — returns the Hangul syllable type (cf. HangulSyllableType.txt) for the code point, as a string: L for leading jamo, V for vowel jamo, T for trailing jamo, LV for LV syllables, LVT for LVT syllables, and NA for other code points (as Not Applicable). Six possible answers, zero ambiguity. 🎯

🎀 EXPORT 🎀

By default:

decomposeHangul
composeHangul
getHangulName
parseHangulName
getHangulComposite

On request:

decomposeSyllable
composeSyllable
decomposeJamo
composeJamo
decomposeFull
isStandardForm
insertFiller
getSyllableType

💀 CAVEAT 💀

Real talk: this module does not support Hangul jamo assigned in Unicode 5.2.0 (2009). If you were looking for those, this isn't the module, bestie, sorry. 😭

A list of Hangul characters this module supports:

1100..1159 ; 1.1 # [90] HANGUL CHOSEONG KIYEOK..HANGUL CHOSEONG YEORINHIEUH
115F..11A2 ; 1.1 # [68] HANGUL CHOSEONG FILLER..HANGUL JUNGSEONG SSANGARAEA
11A8..11F9 ; 1.1 # [82] HANGUL JONGSEONG KIYEOK..HANGUL JONGSEONG YEORINHIEUH
AC00..D7A3 ; 2.0 # [11172] HANGUL SYLLABLE GA..HANGUL SYLLABLE HIH

🫶 AUTHOR 🫶

SADAHIRO Tomoyuki <SADAHIRO@cpan.org>

Copyright(C) 2001, 2003, 2005, SADAHIRO Tomoyuki. Japan. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Free as in go off, bestie. 💜

🌟 SEE ALSO 🌟

and that's the whole page, bestie!! this lil manual is riding with perl v5.42.0, dated 2025-07-25, and it's filed under Util(3) — go forth and decompose some syllables, you absolute icon 👑💖

📦 where this page comes from