hangulx/README.md

Providing various utilities for Hangul

# 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 src="https://unpkg.com/hangulx" type="text/javascript"></script>
```

#### Script tag
```bash
<script src="hangulx.min.js" type="text/javascript"></script>
```

## Usage

#### Node.js

```javascript
import {Hangul} from 'hangulx';
```

```javascript
import * as hangulx from 'hangulx';
```

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

# API

## Hangul

### import
```typescript
import {Hangul} from 'hangulx';
```
```html
<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)
```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  | 쌍자음(ㄲ, ㄸ, ㅃ, ㅆ, ㅉ) 분리 여부 <br> Determines whether double consonants (e.g., ㄲ, ㄸ, ㅃ, ㅆ, ㅉ) should be disassembled | N        |
| clusterConsonant | 복합자음(ㄳ, ㄵ, ㄶ, ㄺ ...) 분리 여부 <br> Determines whether cluster consonants (e.g., ㄳ, ㄵ, ㄶ, ㄺ) should be disassembled | N        |
| risingJDiphthong | ㅣ(［j］)계 상승이중모음(ㅑ, ㅕ, ㅕ, ㅠ, ㅐ, ㅖ) 분리 여부<br> Determines whether rising diphthongs with ㅣ[j] should be disassembled | N        |
| risingWDiphthong | ㅗ/ㅜ([w])계 상승이중모음(ㅘ, ㅝ, ㅙ, ㅞ) 분리 여부 <br> Determines whether rising diphthongs with ㅗ/ㅜ[w] should be disassembled | N        |
| fallingDiphthong | 하강이중모음(ㅢ) 분리 여부 <br> 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
<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).
```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);   // 세종대왕
```