hangulx 🚀

hangulx is a TypeScript library designed to work with Hangul (Korean characters) in various formats, providing utility functions for detecting, parsing, and manipulating Korean syllables and jamo (individual consonant and vowel components). This package can be especially useful for applications that need to handle Hangul text at a granular level, linguistic research, and educational tools for learning Korean.

Installation

Install the package using package manager

npm install hangulx

yarn add hangulx

Browser

Script tag (using CDN)

<script src="https://unpkg.com/hangulx" type="text/javascript"></script>

Script tag

<script src="hangulx.min.js" type="text/javascript"></script>

Usage

Node.js

import {Hangul} from 'hangulx';

import * as hangulx from 'hangulx';

AMD

<script type="text/javascript">
    (function () {
        hangulx.Hangul.disassemble('한글');     // ['ㅎ', 'ㅏ', 'ㄴ', 'ㄱ', 'ㅡ', 'ㄹ']
    })();
</script>

API

Hangul

import

import {Hangul} from 'hangulx';

<script type="text/javascript">
    (function () {
        var Hangul = hangulx.Hangul;    // or
        const {Hangul} = hangulx;
    })();
</script>

Hangul.disassemble(str: string, option?: Hangul.DisassembleOption): string[]

한글을 자모로 분리합니다.
Splits Korean Hangul characters into their phonetic components(jamo)

Hangul.disassemble('강');    // [ 'ㄱ', 'ㅏ', 'ㅇ' ]
Hangul.disassemble('싻');    // [ 'ㅆ', 'ㅏ', 'ㄽ' ]

한글이 아닌 문자는 반환됩니다.
Non-Hangul characters are returned as they are.

Hangul.disassemble('ABC123蓚!');   // [ 'A',  'B', 'C', '1',  '2', '3', '蓚', '!' ]
Hangul.disassemble('한글A');       // [ 'ㅎ', 'ㅏ', 'ㄴ', 'ㄱ', 'ㅡ', 'ㄹ', 'A' ]

복합자음(쌍자음) (ㄲ, ㄸ, ㅃ ... ) 분리
splitting complex consonants (double consonants) such as ㄲ, ㄸ, ㅃ.

Hangul.disassemble('까닭', {doubleConsonant: true});    // [ 'ㄱ', 'ㄱ', 'ㅏ', 'ㄷ', 'ㅏ', 'ㄺ' ]
Hangul.disassemble('꺾다', {doubleConsonant: true});    // [ 'ㄱ', 'ㄱ', 'ㅓ', 'ㄱ', 'ㄱ', 'ㄷ', 'ㅏ' ]

자음군(겹받침) (ㄳ, ㄵ, ㅄ ... ) 분리
splitting consonant clusters (compound final consonants) such as ㄳ, ㄵ, ㅄ.

Hangul.disassemble('까닭', {clusterConsonant: true});    // [ 'ㄲ', 'ㅏ', 'ㄷ', 'ㅏ', 'ㄹ', 'ㄱ' ]
Hangul.disassemble('읽다', {clusterConsonant: true});    // [ 'ㅇ', 'ㅣ', 'ㄹ', 'ㄱ', 'ㄷ', 'ㅏ' ]

복합자음(쌍자음) 및 자음군(겹받침) 분리
splitting complex consonants (double consonants) and consonant clusters (compound final consonants) such as ㄲ, ㄸ, ㅃ, ㄳ, ㄵ, ㅄ.

const option: Hangul.DisassembleOption = {
  doubleConsonant: true,      // 쌍자음(ㄲ, ㄸ, ㅃ, ㅆ, ㅉ) 분리 여부(각자 병서)
  clusterConsonant: true,    // 복합자음(ㄳ, ㄵ, ㄶ, ㄺ ...) 분리 여부(합용 병서)
};

Hangul.disassemble('싻', option);   // [ 'ㅅ', 'ㅅ', 'ㅏ', 'ㄱ', 'ㅅ' ]
Hangul.disassemble('닭볶음탕', option);   // [ 'ㄷ', 'ㅏ', 'ㄹ', 'ㄱ', 'ㅂ', 'ㅗ', 'ㄱ', 'ㄱ', 'ㅇ', 'ㅡ', 'ㅁ', 'ㅌ', 'ㅏ', 'ㅇ' ]

Hangul.disassembleToString(str: string, option?: Hangul.DisassembleToStringOption): string

한글을 분해하여 자모로 분리된 문자열로 반환합니다.

Hangul.disassembleToString('한글');   // ㅎㅏㄴㄱㅡㄹ
Hangul.disassembleToString('구글');   // ㄱㅜㄱㅡㄹ

Separator 사용

Hangul.disassembleToString('한글', {separator: ','});   // ㅎ,ㅏ,ㄴ,ㄱ,ㅡ,ㄹ
Hangul.disassembleToString('구글', {separator: ','});   // ㄱ,ㅜ,ㄱ,ㅡ,ㄹ

Hangul.disassembleToGroup(str: string, option?: Hangul.DisassembleOption): string[][]

한글을 글자별로 자모로 분리합니다.
Splits Korean Hangul into individual jamos for each character.

Hangul.disassembleToGroup('프랑스');   // [['ㅍ', 'ㅡ'], ['ㄹ', 'ㅏ', 'ㅇ'], ['ㅅ', 'ㅡ']]

Interface: Hangul.DisassembleOption

| Option | Description | Required | |------------------|-----------------------------------------------------------------------------------------------------------------|----------| | doubleConsonant | 쌍자음(ㄲ, ㄸ, ㅃ, ㅆ, ㅉ) 분리 여부 Determines whether double consonants (e.g., ㄲ, ㄸ, ㅃ, ㅆ, ㅉ) should be disassembled | N | | clusterConsonant | 복합자음(ㄳ, ㄵ, ㄶ, ㄺ ...) 분리 여부 Determines whether cluster consonants (e.g., ㄳ, ㄵ, ㄶ, ㄺ) should be disassembled | N | | risingJDiphthong | ㅣ(［j］)계 상승이중모음(ㅑ, ㅕ, ㅕ, ㅠ, ㅐ, ㅖ) 분리 여부 Determines whether rising diphthongs with ㅣ[j] should be disassembled | N | | risingWDiphthong | ㅗ/ㅜ([w])계 상승이중모음(ㅘ, ㅝ, ㅙ, ㅞ) 분리 여부 Determines whether rising diphthongs with ㅗ/ㅜ[w] should be disassembled | N | | fallingDiphthong | 하강이중모음(ㅢ) 분리 여부 Determines whether falling diphthongs should be disassembled | N |

Syllable

한글의 음절 분리/조합 및 기타 기능을 제공합니다.
Provides functions for splitting and combining Korean Hangul syllables, along with other features.

import

import {Syllable} from 'hangulx';

<script type="text/javascript">
    (function () {
        var Syllable = hangulx.Syllable;    // or
        const {Syllable} = hangulx;
    })();
</script>

Syllable.disassemble(str: string): ISyllable[]

문자열을 음절(초성, 중성, 종성)로 분리합니다.
Splits a string into syllables consisting of initial sounds (cho), medial sounds (jung), and final sounds (jong).

Syllable.disassemble('가위');   // [{ cho: 'ㄱ', jung: 'ㅏ', jong: undefined }, { cho: 'ㅇ', jung: 'ㅟ', jong: undefined }]

음절로 나눌 수 없는 문자는 제거되어 반환됩니다.
Characters that cannot be divided into syllables are removed and not returned.

Syllable.disassemble('강-A1ㅎ');    // [{ cho: 'ㄱ', jung: 'ㅏ', jong: 'ㅇ' }]
Syllable.disassemble('ㄱㄳA1');     // []

Syllable.disassembleFromChar(char: string): ISyllable | null

문자를 음절(초성, 중성, 종성)로 분리합니다.
Splits single character into syllables consisting of initial sounds (cho), medial sounds (jung), and final sounds (jong).

Syllable.disassembleFromChar('강');    // { cho: 'ㄱ', jung: 'ㅏ', jong: 'ㅇ' }
Syllable.disassembleFromChar('되');    // { cho: 'ㄷ', jung: 'ㅚ', jong: undefined }

길이가 1을 초과하는 경우 첫번째 문자를 분리합니다. 1개 이상의 문자를 음절 분리하려면 Syllable.disassemble 함수를 사용합니다.
If the length exceeds 1, only the first character is split into syllables. To disassemble more than one character into syllables, use the Syllable.disassemble function.

Syllable.disassembleFromChar('세종대왕');   // { cho: 'ㅅ', jung: 'ㅔ', jong: undefined }

분리할 수 없는 문자는 null 반한됩니다.
Characters that cannot be split are returned as null.

Syllable.disassembleFromChar('ㅅ');    // null
Syllable.disassembleFromChar('A');    // null
Syllable.disassembleFromChar('7');    // null
Syllable.disassembleFromChar('-');    // null

Syllable.assemble(syllable: ISyllable | ISyllable[]): string

음절(초성, 중성, 종성)을 병합하여 문자열로 반환합니다.
Merges syllables consisting of initial sounds (cho), medial sounds (jung), and final sounds (jong) into a string.

Syllable.assemble({cho: 'ㄱ', jung: 'ㅏ'});               // 가
Syllable.assemble({cho: 'ㅎ', jung: 'ㅏ', jong: 'ㅂ'});   // 합
Syllable.assemble({cho: 'ㅅ', jung: 'ㅓ', jong: 'ㄲ'});   // 섞
Syllable.assemble({cho: 'ㅂ', jung: 'ㅏ', jong: 'ㄼ'});   // 밟

Syllable.assemble({cho: 'A', jung: 'ㅓ', jong: 'ㄴ'})   // Error - Invalid cho("A" can not be cho)
Syllable.assemble({cho: 'ㄱ', jung: 'ㅓ', jong: 'ㅃ'})   // Error - Invalid jong("ㅃ" can not be jong)
Syllable.assemble({cho: 'ㅎ', jung: 'A', jong: 'ㄴ'})   // Error - Invalid jung("A" can not be jung)

여러개의 음절을 병합할 수 있습니다.
Multiple syllables can be merged.

const syllables: ISyllable[] = [
  {cho: 'ㄱ', jung: 'ㅏ', jong: 'ㅂ'},
  {cho: 'ㅇ', jung: 'ㅗ', jong: undefined},
  {cho: 'ㄴ', jung: 'ㅕ', jong: 'ㄴ'},
];

Syllable.assemble(syllables);   // 갑오년

Syllable.disassemble 함수로 분리한 음절을 다시 합칠 수 있습니다.
Syllables split using the Syllable.disassemble function can be recombined.

const syllables: ISyllable[] = Syllable.disassemble('세종대왕');
/* [
     { cho: 'ㅅ', jung: 'ㅔ', jong: undefined },
     { cho: 'ㅈ', jung: 'ㅗ', jong: 'ㅇ' },
     { cho: 'ㄷ', jung: 'ㅐ', jong: undefined },
     { cho: 'ㅇ', jung: 'ㅘ', jong: 'ㅇ' }
   ] */

Syllable.assemble(syllables);   // 세종대왕