# 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 ```bash npm install hangulx ``` ```bash yarn add hangulx ``` ### Browser #### Script tag (using CDN) ```bash ``` #### Script tag ```bash ``` ## Usage #### Node.js ```javascript import {Hangul} from 'hangulx'; ``` ```javascript import * as hangulx from 'hangulx'; ``` #### AMD ```html ``` # API ## Hangul ### import ```typescript import {Hangul} from 'hangulx'; ``` ```html ``` ### Hangul.disassemble(str: string, option?: Hangul.DisassembleOption): string[] ν•œκΈ€μ„ 자λͺ¨λ‘œ λΆ„λ¦¬ν•©λ‹ˆλ‹€. Splits Korean Hangul characters into their phonetic components(jamo) ```typescript Hangul.disassemble('κ°•'); // [ 'γ„±', 'ㅏ', 'γ…‡' ] Hangul.disassemble('μ‹»'); // [ 'γ…†', 'ㅏ', 'γ„½' ] ``` ν•œκΈ€μ΄ μ•„λ‹Œ λ¬ΈμžλŠ” λ°˜ν™˜λ©λ‹ˆλ‹€. Non-Hangul characters are returned as they are. ```typescript Hangul.disassemble('ABC123θ“š!'); // [ 'A', 'B', 'C', '1', '2', '3', 'θ“š', '!' ] Hangul.disassemble('ν•œκΈ€A'); // [ 'γ…Ž', 'ㅏ', 'γ„΄', 'γ„±', 'γ…‘', 'γ„Ή', 'A' ] ``` **λ³΅ν•©μžμŒ**_(쌍자음)_ (γ„², γ„Έ, γ…ƒ ... ) 뢄리 splitting complex consonants (double consonants) such as γ„², γ„Έ, γ…ƒ. ```typescript Hangul.disassemble('κΉŒλ‹­', {doubleConsonant: true}); // [ 'γ„±', 'γ„±', 'ㅏ', 'γ„·', 'ㅏ', 'γ„Ί' ] Hangul.disassemble('κΊΎλ‹€', {doubleConsonant: true}); // [ 'γ„±', 'γ„±', 'γ…“', 'γ„±', 'γ„±', 'γ„·', 'ㅏ' ] ``` **자음ꡰ**_(κ²Ήλ°›μΉ¨)_ (γ„³, γ„΅, γ…„ ... ) 뢄리 splitting consonant clusters (compound final consonants) such as γ„³, γ„΅, γ…„. ```typescript Hangul.disassemble('κΉŒλ‹­', {clusterConsonant: true}); // [ 'γ„²', 'ㅏ', 'γ„·', 'ㅏ', 'γ„Ή', 'γ„±' ] Hangul.disassemble('읽닀', {clusterConsonant: true}); // [ 'γ…‡', 'γ…£', 'γ„Ή', 'γ„±', 'γ„·', 'ㅏ' ] ``` **λ³΅ν•©μžμŒ**_(쌍자음)_ 및 **자음ꡰ**_(κ²Ήλ°›μΉ¨)_ 뢄리 splitting complex consonants (double consonants) and consonant clusters (compound final consonants) such as γ„², γ„Έ, γ…ƒ, γ„³, γ„΅, γ…„. ```typescript const option: Hangul.DisassembleOption = { doubleConsonant: true, // 쌍자음(γ„², γ„Έ, γ…ƒ, γ…†, γ…‰) 뢄리 μ—¬λΆ€(각자 λ³‘μ„œ) clusterConsonant: true, // λ³΅ν•©μžμŒ(γ„³, γ„΅, γ„Ά, γ„Ί ...) 뢄리 μ—¬λΆ€(ν•©μš© λ³‘μ„œ) }; Hangul.disassemble('μ‹»', option); // [ 'γ……', 'γ……', 'ㅏ', 'γ„±', 'γ……' ] Hangul.disassemble('λ‹­λ³ΆμŒνƒ•', option); // [ 'γ„·', 'ㅏ', 'γ„Ή', 'γ„±', 'γ…‚', 'γ…—', 'γ„±', 'γ„±', 'γ…‡', 'γ…‘', 'ㅁ', 'γ…Œ', 'ㅏ', 'γ…‡' ] ``` ### Hangul.disassembleToString(str: string, option?: Hangul.DisassembleToStringOption): string ν•œκΈ€μ„ λΆ„ν•΄ν•˜μ—¬ 자λͺ¨λ‘œ λΆ„λ¦¬λœ λ¬Έμžμ—΄λ‘œ λ°˜ν™˜ν•©λ‹ˆλ‹€. ```typescript Hangul.disassembleToString('ν•œκΈ€'); // γ…Žγ…γ„΄γ„±γ…‘γ„Ή Hangul.disassembleToString('ꡬ글'); // γ„±γ…œγ„±γ…‘γ„Ή ``` Separator μ‚¬μš© ```typescript Hangul.disassembleToString('ν•œκΈ€', {separator: ','}); // γ…Ž,ㅏ,γ„΄,γ„±,γ…‘,γ„Ή Hangul.disassembleToString('ꡬ글', {separator: ','}); // γ„±,γ…œ,γ„±,γ…‘,γ„Ή ``` ### Hangul.disassembleToGroup(str: string, option?: Hangul.DisassembleOption): string[][] ν•œκΈ€μ„ **κΈ€μžλ³„λ‘œ** 자λͺ¨λ‘œ λΆ„λ¦¬ν•©λ‹ˆλ‹€. Splits Korean Hangul into individual jamos for **each character.** ```typescript 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 ```typescript import {Syllable} from 'hangulx'; ``` ```html ``` ### Syllable.disassemble(str: string): ISyllable[] λ¬Έμžμ—΄μ„ 음절(μ΄ˆμ„±, 쀑성, μ’…μ„±)둜 λΆ„λ¦¬ν•©λ‹ˆλ‹€. Splits a string into syllables consisting of initial sounds (cho), medial sounds (jung), and final sounds (jong). ```typescript Syllable.disassemble('κ°€μœ„'); // [{ cho: 'γ„±', jung: 'ㅏ', jong: undefined }, { cho: 'γ…‡', jung: 'γ…Ÿ', jong: undefined }] ``` 음절둜 λ‚˜λˆŒ 수 μ—†λŠ” λ¬ΈμžλŠ” μ œκ±°λ˜μ–΄ λ°˜ν™˜λ©λ‹ˆλ‹€. Characters that cannot be divided into syllables are removed and not returned. ```typescript 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). ```typescript 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. ```typescript Syllable.disassembleFromChar('μ„Έμ’…λŒ€μ™•'); // { cho: 'γ……', jung: 'γ…”', jong: undefined } ``` 뢄리할 수 μ—†λŠ” λ¬ΈμžλŠ” null λ°˜ν•œλ©λ‹ˆλ‹€. Characters that cannot be split are returned as null. ```typescript 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. ```typescript 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. ```typescript 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. ```typescript const syllables: ISyllable[] = Syllable.disassemble('μ„Έμ’…λŒ€μ™•'); /* [ { cho: 'γ……', jung: 'γ…”', jong: undefined }, { cho: 'γ…ˆ', jung: 'γ…—', jong: 'γ…‡' }, { cho: 'γ„·', jung: 'ㅐ', jong: undefined }, { cho: 'γ…‡', jung: 'γ…˜', jong: 'γ…‡' } ] */ Syllable.assemble(syllables); // μ„Έμ’…λŒ€μ™• ```