Gukhanmun

https://gukhanmun.org/
Admin
Gukhanmun is a project that provides documentation and API references, likely for a JavaScript...
Tokens:40,133
Snippets:486
Trust Score:3.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install gukhanmun-mkdict Builder

Source: https://gukhanmun.org/guide/cli/dictionary

Install the `gukhanmun-mkdict` builder using Cargo if you built Gukhanmun from source.

```sh
cargo install gukhanmun-mkdict
```

--------------------------------

### Install Gukhanmun via mise

Source: https://gukhanmun.org/guide/cli/install

Use this command to install a prebuilt binary of Gukhanmun globally using the mise package manager. Omit the -g flag to install only for the current project.

```sh
mise use -g aqua:dahlia/gukhanmun
```

--------------------------------

### Minimal Gukhanmun Setup with WASM Backend

Source: https://gukhanmun.org/guide/javascript/start

This snippet shows the basic setup for Gukhanmun using the WASM backend. It imports the load function and a dictionary, then initializes Gukhanmun and performs a conversion.

```typescript
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({
  dictionaries: [await stdictFst()]
});

console.log(g.convert("漢字를 한글로"));
// → 한자를 한글로
```

--------------------------------

### Install @gukhanmun/napi with deno

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Node-API implementation of Gukhanmun to your project via deno.

```sh
deno add npm:@gukhanmun/napi
```

--------------------------------

### Install @gukhanmun/napi with bun

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Node-API implementation of Gukhanmun to your project via bun.

```sh
bun add @gukhanmun/napi
```

--------------------------------

### Install Gukhanmun from crates.io

Source: https://gukhanmun.org/guide/cli/install

If you have a Rust toolchain installed, you can install Gukhanmun and its companion tool from crates.io using cargo. Ensure ~/.cargo/bin is on your PATH.

```sh
cargo install gukhanmun-cli gukhanmun-mkdict
```

--------------------------------

### Example Directives TSV File

Source: https://gukhanmun.org/guide/cli/directives

An example TSV file demonstrating how to specify actions, patterns, and kinds for hanja annotation overrides.

```tsv
# Force reading for proper nouns
require-hanja	東京	literal
require-hanja	北京	literal
# Suppress annotation for all middle-dot separated names
skip-annotation	*·*	glob
```

--------------------------------

### Install @gukhanmun/wasm with deno

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the WebAssembly implementation of Gukhanmun to your project via deno.

```sh
deno add jsr:@gukhanmun/wasm
```

--------------------------------

### Install @gukhanmun/opendict-cdb with bun

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Open Korean Dictionary (CDB format) to your project via bun.

```sh
bun add @gukhanmun/opendict-cdb
```

--------------------------------

### Verify Gukhanmun Installation

Source: https://gukhanmun.org/guide/cli/install

After installation, verify that both gukhanmun and gukhanmun-mkdict are accessible and working by checking their help messages.

```sh
gukhanmun --help
gukhanmun-mkdict --help
```

--------------------------------

### Install @gukhanmun/opendict-cdb with deno

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Open Korean Dictionary (CDB format) to your project via deno.

```sh
deno add jsr:@gukhanmun/opendict-cdb
```

--------------------------------

### Install @gukhanmun/wasm with bun

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the WebAssembly implementation of Gukhanmun to your project via bun.

```sh
bun add @gukhanmun/wasm
```

--------------------------------

### Install @gukhanmun/napi with npm

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Node-API implementation of Gukhanmun to your project via npm.

```sh
npm add @gukhanmun/napi
```

--------------------------------

### Install @gukhanmun/wasm with pnpm

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the WebAssembly implementation of Gukhanmun to your project via pnpm.

```sh
pnpm add @gukhanmun/wasm
```

--------------------------------

### Install @gukhanmun/napi with yarn

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Node-API implementation of Gukhanmun to your project via yarn.

```sh
yarn add @gukhanmun/napi
```

--------------------------------

### Install Gukhanmun via winget on Windows

Source: https://gukhanmun.org/guide/cli/install

On Windows systems, Gukhanmun can be installed using the winget package manager.

```powershell
winget install HongMinhee.Gukhanmun
```

--------------------------------

### Install @gukhanmun/napi with pnpm

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Node-API implementation of Gukhanmun to your project via pnpm.

```sh
pnpm add @gukhanmun/napi
```

--------------------------------

### Install @gukhanmun/stdict-cdb with deno

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Standard Korean Dictionary (CDB format) to your project via deno.

```sh
deno add jsr:@gukhanmun/stdict-cdb
```

--------------------------------

### Install Gukhanmun for plain-text only

Source: https://gukhanmun.org/guide/rust/install

Build a minimal plain-text-only binary by disabling default features and enabling the 'stdict' feature. This reduces the binary size by excluding other functionalities.

```sh
cargo add gukhanmun --no-default-features -F stdict
```

--------------------------------

### Install @gukhanmun/stdict-cdb with bun

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Standard Korean Dictionary (CDB format) to your project via bun.

```sh
bun add @gukhanmun/stdict-cdb
```

--------------------------------

### Install @gukhanmun/opendict-fst with bun

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Open Korean Dictionary (FST format) to your project via bun.

```sh
bun add @gukhanmun/opendict-fst
```

--------------------------------

### Canonical TSV Input Example

Source: https://gukhanmun.org/internals/dictionary-format

Example of a UTF-8 TSV file with a header row, including required and optional columns.

```tsv
hanja	hangul	require_hanja	require_hangul	category
天地	천지	false	false	basic
漢字	한자	true	false	basic
色깔論	색깔론	false	true	mixed
```

--------------------------------

### Install @gukhanmun/wasm with npm

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the WebAssembly implementation of Gukhanmun to your project via npm.

```sh
npm add @gukhanmun/wasm
```

--------------------------------

### Install @gukhanmun/opendict-fst with deno

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Open Korean Dictionary (FST format) to your project via deno.

```sh
deno add jsr:@gukhanmun/opendict-fst
```

--------------------------------

### JSONL Input Example

Source: https://gukhanmun.org/internals/dictionary-format

Example of a JSON Lines file where each line is a JSON object representing a dictionary entry. Boolean fields accept snake_case or camelCase.

```json
{"hanja":"漢字","hangul":"한자","requireHanja":false,"requireHangul":true}
```

--------------------------------

### CSV Input Example

Source: https://gukhanmun.org/internals/dictionary-format

Example of a CSV file adhering to the same header names as the canonical TSV format.

```csv
hanja,hangul,require_hanja,require_hangul
天地,천지,true,false
```

--------------------------------

### Minimal Gukhanmun Rust Example

Source: https://gukhanmun.org/guide/rust/start

Demonstrates the basic usage of Gukhanmun to convert Hanja to Hangul using a preset.

```rust
use gukhanmun::{Builder, Preset};

fn main() -> gukhanmun::Result<()> {
    let converter = Builder::with_preset(Preset::KoKr).build()?;
    let output = converter.convert_text_to_string("漢字를 한글로")?;
    println!("{output}");  // 한자를 한글로
    Ok(())
}
```

--------------------------------

### Install @gukhanmun/opendict-cdb with npm

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Open Korean Dictionary (CDB format) to your project via npm.

```sh
npm add @gukhanmun/opendict-cdb
```

--------------------------------

### Install @gukhanmun/wasm with yarn

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the WebAssembly implementation of Gukhanmun to your project via yarn.

```sh
yarn add @gukhanmun/wasm
```

--------------------------------

### Install @gukhanmun/stdict-fst with bun

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Standard Korean Dictionary (FST format) to your project via bun.

```sh
bun add @gukhanmun/stdict-fst
```

--------------------------------

### Install @gukhanmun/stdict-fst with deno

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Standard Korean Dictionary (FST format) to your project via deno.

```sh
deno add jsr:@gukhanmun/stdict-fst
```

--------------------------------

### Install @gukhanmun/opendict-fst with npm

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Open Korean Dictionary (FST format) to your project via npm.

```sh
npm add @gukhanmun/opendict-fst
```

--------------------------------

### Install @gukhanmun/opendict-cdb with pnpm

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Open Korean Dictionary (CDB format) to your project via pnpm.

```sh
pnpm add @gukhanmun/opendict-cdb
```

--------------------------------

### Install @gukhanmun/opendict-cdb with yarn

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Open Korean Dictionary (CDB format) to your project via yarn.

```sh
yarn add @gukhanmun/opendict-cdb
```

--------------------------------

### Install @gukhanmun/stdict-cdb with npm

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Standard Korean Dictionary (CDB format) to your project via npm.

```sh
npm add @gukhanmun/stdict-cdb
```

--------------------------------

### Install @gukhanmun/stdict-cdb with pnpm

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Standard Korean Dictionary (CDB format) to your project via pnpm.

```sh
pnpm add @gukhanmun/stdict-cdb
```

--------------------------------

### Install @gukhanmun/stdict-cdb with yarn

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Standard Korean Dictionary (CDB format) to your project via yarn.

```sh
yarn add @gukhanmun/stdict-cdb
```

--------------------------------

### Install @gukhanmun/opendict-fst with pnpm

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Open Korean Dictionary (FST format) to your project via pnpm.

```sh
pnpm add @gukhanmun/opendict-fst
```

--------------------------------

### Install @gukhanmun/opendict-fst with yarn

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Open Korean Dictionary (FST format) to your project via yarn.

```sh
yarn add @gukhanmun/opendict-fst
```

--------------------------------

### Install @gukhanmun/stdict-fst with npm

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Standard Korean Dictionary (FST format) to your project via npm.

```sh
npm add @gukhanmun/stdict-fst
```

--------------------------------

### Install @gukhanmun/stdict-fst with pnpm

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Standard Korean Dictionary (FST format) to your project via pnpm.

```sh
pnpm add @gukhanmun/stdict-fst
```

--------------------------------

### Install @gukhanmun/stdict-fst with yarn

Source: https://gukhanmun.org/guide/javascript/install

Use this command to add the Standard Korean Dictionary (FST format) to your project via yarn.

```sh
yarn add @gukhanmun/stdict-fst
```

--------------------------------

### Install Gukhanmun without default features

Source: https://gukhanmun.org/guide/rust/install

Build the gukhanmun crate without default features and explicitly enable the 'fst' feature. This is useful when you want to provide your own dictionary files.

```sh
cargo add gukhanmun --no-default-features -F fst
```

--------------------------------

### load

Source: https://gukhanmun.org/api/js/modules/_gukhanmun_wasm

Loads the WebAssembly module and initializes the Gukhanmun converter. This function is intended to be called once to get an instance of the Gukhanmun converter. The WASM module is initialized lazily on the first `load()` call and cached for subsequent calls. Dictionary data must be supplied explicitly via `GukhanmunOptions.dictionaries`.

```APIDOC
## load

### Description
Loads the WebAssembly module and initializes the Gukhanmun converter. This function is intended to be called once to get an instance of the Gukhanmun converter. The WASM module is initialized lazily on the first `load()` call and cached for subsequent calls. Dictionary data must be supplied explicitly via `GukhanmunOptions.dictionaries`.

### Function Signature
`load(options: GukhanmunOptions): Promise<Gukhanmun>`

### Parameters
#### Options
- **options** (GukhanmunOptions) - Required - An object containing configuration options for the Gukhanmun converter.
  - **dictionaries** (Array<DictionarySource>) - Required - An array of dictionary sources to be loaded.

### Returns
- Promise<Gukhanmun> - A Promise that resolves to an instance of the Gukhanmun converter.

### Example
```ts
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({ dictionaries: [await stdictFst()] });
console.log(g.convert("漢字를 한글로"));  // "한자를 한글로"
```
```

--------------------------------

### Capture Stack Trace Example

Source: https://gukhanmun.org/api/js/classes/_gukhanmun_wasm.GukhanmunError

Demonstrates how to use Error.captureStackTrace to create a .stack property on an object. The optional constructorOpt argument can be used to omit frames from the stack trace.

```javascript
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

```javascript
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

--------------------------------

### Enable GitHub Flavored Markdown (GFM)

Source: https://gukhanmun.org/guide/javascript/markdown

Enable GFM extensions like tables, task lists, and strikethrough by passing a format object with `gfm: true`. This example demonstrates converting a Markdown table.

```typescript
import type { Gukhanmun } from "@gukhanmun/types";
const g: Gukhanmun = {} as unknown as Gukhanmun;
// ---cut-before---
const output = g.convert(
  "| 漢字 | 讀音 |\n|------|------|\n| 東 | 동 |",
  { format: "markdown", gfm: true },
);
```

--------------------------------

### Apply Directives with Dictionary Loading

Source: https://gukhanmun.org/guide/javascript/directives

Loads dictionaries and applies custom directives during initialization. This example forces '漢' and '字' to show hanja, '東' to show hangul, and suppresses annotation for '中'.

```typescript
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({
  dictionaries: [await stdictFst()],
  directives: {
    requireHanja:   ["漢", "字"],
    requireHangul:  ["東"],
    skipAnnotation: ["中"],
  },
});
```

--------------------------------

### Register Predicate Directive

Source: https://gukhanmun.org/guide/rust/directives

Use `directive_predicate` with a closure to apply rules based on patterns. This example requires hanja starting with '東' to be included.

```rust
builder.directive_predicate(
    |hanja: &str| hanja.starts_with('東'),
    DirectiveAction::RequireHanja,
);
```

--------------------------------

### Switching to Gukhanmun NAPI Backend

Source: https://gukhanmun.org/guide/javascript/start

Demonstrates how to switch to the NAPI backend for Gukhanmun. The API remains the same, only the import path changes.

```typescript
import { load } from "@gukhanmun/napi";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({
  dictionaries: [await stdictFst()]
});
```

--------------------------------

### load()

Source: https://gukhanmun.org/api/js/functions/_gukhanmun_napi.load

Creates a Gukhanmun converter with the given options. The native addon is synchronously ready; dictionaries supplied via GukhanmunOptions.dictionaries are fetched or read from disk and passed to the Rust engine as FileDictionarySource values.

```APIDOC
## load()

### Description
Creates a Gukhanmun converter with the given options. The native addon is synchronously ready; dictionaries supplied via `{@link GukhanmunOptions.dictionaries}` are fetched or read from disk and passed to the Rust engine as `FileDictionarySource` values.

Note: unlike the Rust `ko-kr` preset, the JavaScript preset never includes a bundled dictionary. Pass `dictionaries: [await stdictFst()]` to include the Standard Korean Language Dictionary.

### Method
`load(options?)`

### Parameters
#### options?
- **options?** (`GukhanmunOptions` = `{}`) - Optional. Conversion options. All fields are optional; defaults match the `ko-kr` preset.

### Returns
- `Promise<Gukhanmun>` - A `{@link Gukhanmun}` instance.

### Throws
- `GukhanmunError` - On invalid options or dictionary load failure.
```

--------------------------------

### Use KoKp Preset for North Korean Orthography

Source: https://gukhanmun.org/guide/rust/dictionary

Initialize a converter with the `ko-kp` preset, which disables the initial sound law and includes the North Korean Open Korean Dictionary. Demonstrates text conversion with this preset.

```rust
let converter = Builder::with_preset(Preset::KoKp).build()?;
assert_eq!(converter.convert_text_to_string("歷史와 來日")?, "력사와 래일");
```

--------------------------------

### Chaining Builder Options in Rust

Source: https://gukhanmun.org/guide/rust/start

Shows how to use the fluent interface of the Builder pattern to chain multiple configuration options.

```rust
use gukhanmun::{Builder, Preset, RenderMode, NumeralStrategy};

let converter = Builder::with_preset(Preset::KoKr)
    .rendering(RenderMode::HangulHanjaParens)
    .numerals(NumeralStrategy::Smart)
    .build()?;
```

--------------------------------

### load()

Source: https://gukhanmun.org/api/js/functions/_gukhanmun_wasm.load

Creates a Gukhanmun converter instance with the given options. It initializes the WASM module and handles dictionary loading.

```APIDOC
## Function: load()

> **load**(`options?`): `Promise`

Creates a Gukhanmun converter with the given options.

Initialises the WASM module on the first call (subsequent calls reuse the
cached module). Dictionaries supplied via `{@link GukhanmunOptions.dictionaries}` are fetched and passed to the Rust
engine as `FileDictionarySource` values.

Note: unlike the Rust `ko-kr` preset, the JavaScript preset never includes a
bundled dictionary. Pass `dictionaries: [await stdictFst()]` to include the
Standard Korean Language Dictionary.

## Parameters

### options?

[`GukhanmunOptions`](/api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md) = `{}`

Conversion options. All fields are optional; defaults match
the `ko-kr` preset.

## Returns

`Promise`

A `{@link Gukhanmun}` instance.

## Throws

[GukhanmunError](/api/js/classes/_gukhanmun_wasm.GukhanmunError.md) on invalid options or dictionary load failure.
```

--------------------------------

### Using Gukhanmun Convert Method with Different Formats

Source: https://gukhanmun.org/guide/javascript/start

Illustrates how to use the `convert()` method with different output formats like plain text, HTML, and Markdown. It shows default behavior and specific format options.

```typescript
import type { Gukhanmun } from "@gukhanmun/types";
const g: Gukhanmun = {} as unknown as Gukhanmun;
// ---cut-before---
g.convert("漢字를 한글로");             // plain text (default)
g.convert("<p>漢字</p>", "html");       // HTML fragment
g.convert("# 漢字", "markdown");        // CommonMark
g.convert("# 漢字", { format: "markdown", gfm: true });  // GFM
```

--------------------------------

### Load with Preset 'ko-kp'

Source: https://gukhanmun.org/guide/javascript/conversion

Loads Gukhanmun with the 'ko-kp' preset, which implies initialSoundLaw is false and segmentation is eager. Dictionaries must be explicitly provided.

```typescript
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({ preset: "ko-kp", dictionaries: [] });
```

--------------------------------

### Register Literal Directives

Source: https://gukhanmun.org/guide/rust/directives

Use `directive` to specify actions for individual hanja characters. This example sets rules for '漢', '字', '東', and '中'.

```rust
use gukhanmun::DirectiveAction;

builder
    .directive("漢", DirectiveAction::RequireHanja)
    .directive("字", DirectiveAction::RequireHanja)
    .directive("東", DirectiveAction::RequireHangul)
    .directive("中", DirectiveAction::SkipAnnotation);
```

--------------------------------

### Convert Text to Markdown

Source: https://gukhanmun.org/guide/javascript/markdown

Use the `convert()` function with the 'markdown' format to transform plain text into Markdown. This example shows converting a heading and descriptive text.

```typescript
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({ dictionaries: [await stdictFst()] });

const output = g.convert("# 漢字\n\n漢字를 한글로 변환합니다.", "markdown");
// → "# 한자\n\n한자를 한글로 변환합니다."
```

--------------------------------

### Load and Use Standard Korean Dictionary

Source: https://gukhanmun.org/api/js/modules/_gukhanmun_stdict-cdb

Loads the standard Korean dictionary using the WASM module and demonstrates its conversion capability. Ensure `@gukhanmun/wasm` and `@gukhanmun/stdict-cdb` are installed.

```typescript
import { load } from "@gukhanmun/wasm";
import { stdictCdb } from "@gukhanmun/stdict-cdb";

const g = await load({ dictionaries: [await stdictCdb()] });
console.log(g.convert("漢字를 한글로"));  // "한자를 한글로"
```

--------------------------------

### Convert HTML Content

Source: https://gukhanmun.org/guide/javascript/html

Pass 'html' as the format to the convert function to process HTML content. This example shows basic conversion of Hanja within an HTML paragraph.

```typescript
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({ dictionaries: [await stdictFst()] });

console.log(g.convert("<p>漢字</p>", "html"));
// → <p>한자</p>
```

--------------------------------

### Converting Different Text Formats with Gukhanmun

Source: https://gukhanmun.org/guide/rust/start

Illustrates how to use the Converter to convert plain text, HTML fragments, and Markdown. Requires enabling specific features for HTML and Markdown.

```rust
// Plain text
let text = converter.convert_text_to_string("漢字를 한글로")?;
```

```rust
// HTML fragment (requires the `html` feature)
let html = converter.convert_html_fragment_to_string("<p>漢字</p>")?;
```

```rust
// Markdown (requires the `markdown` feature)
use gukhanmun::MarkdownVariant;
let md = converter.convert_markdown_to_string("# 漢字", MarkdownVariant::CommonMark)?;
```

--------------------------------

### Create Dictionary Entries with Options

Source: https://gukhanmun.org/guide/cli/dictionary

Include optional columns like `require_hanja` and `require_hangul` to control rendering behavior.

```tsv
hanja	hangul	require_hanja	require_hangul
北京	베이징	false	false
色깔論	색깔론	false	true
```

--------------------------------

### Load North Korean Dictionary FST

Source: https://gukhanmun.org/api/js/modules/_gukhanmun_opendict-fst

Demonstrates how to load the North Korean dictionary FST using the `@gukhanmun/wasm` loader and perform a text conversion. Ensure the `@gukhanmun/wasm` and `@gukhanmun/opendict-fst` packages are installed.

```typescript
import { load } from "@gukhanmun/wasm";
import { opendictNorthKoreanFst } from "@gukhanmun/opendict-fst";

const g = await load({
  preset: "ko-kp",
  dictionaries: [await opendictNorthKoreanFst()]
});
console.log(g.convert("歷史와來日"));  // "력사와 래일"
```

--------------------------------

### Load Dictionary from File

Source: https://gukhanmun.org/guide/rust/dictionary

Load a custom dictionary from a file (e.g., `.gukfst` or `.gukcdb`) using `FstDictionary` or `CdbDictionary`. Dictionaries added this way are consulted before bundled ones.

```rust
use gukhanmun::FstDictionary;  // or CdbDictionary

let dict = FstDictionary::open("custom.gukfst")?;
let converter = Builder::with_preset(Preset::KoKr)
    .push_dictionary(dict)
    .build()?;
```

--------------------------------

### Load and Convert Hanja to Hangul

Source: https://gukhanmun.org/api/js/modules/_gukhanmun_napi

Demonstrates how to load the Gukhanmun native addon with dictionaries and perform a conversion. Ensure dictionaries are loaded asynchronously before use.

```typescript
import { load } from "@gukhanmun/napi";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({ dictionaries: [await stdictFst()] });
console.log(g.convert("漢字를 한글로"));  // "한자를 한글로"
```

--------------------------------

### Load Custom Dictionary from File Path (Node.js/Deno/Bun)

Source: https://gukhanmun.org/guide/javascript/dictionary

Load a custom dictionary using a file system path. This is only supported in Node.js, Deno, and Bun environments.

```typescript
import { load } from "@gukhanmun/napi";
// ---cut-before---
const g = await load({
  dictionaries: [{ format: "fst", data: "/data/domain.gukfst" }],
});

```

--------------------------------

### gukhanmun-mkdict CLI Usage

Source: https://gukhanmun.org/internals/design

Command-line interface for building CDB and FST dictionary files. It supports various input formats, merging strategies, and metadata embedding.

```bash
gukhanmun-mkdict [OPTIONS] -o OUTPUT <INPUT>...

INPUT FORMATS:
    tsv     hanja TAB hangul [TAB flags]
    csv     hanja,hangul[,require_hanja,require_hangul]
    jsonl   {"hanja":..., "hangul":..., "requireHanja":..., ...}

OPTIONS:
    -o, --output PATH               output path
    -f, --format FMT                cdb|fst            (default: fst)
        --merge STRATEGY            first-wins|last-wins|error
        --metadata KEY=VAL          embedded metadata
        --validate                  round-trip verification
        --max-key-bytes N           reject pathologically long entries
        --rules PATH                annotation rules TSV (repeatable)
        --allow-unmatched-rules     accept rules that match no entries
```

--------------------------------

### Load and Convert with Standard Korean Dictionary

Source: https://gukhanmun.org/api/js/modules/_gukhanmun_stdict-fst

Demonstrates how to load the standard Korean dictionary FST using `@gukhanmun/wasm` and perform a character conversion. Ensure the necessary dictionaries are imported.

```typescript
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({ dictionaries: [await stdictFst()] });
console.log(g.convert("漢字를 한글로"));  // "한자를 한글로"
```

--------------------------------

### Load with Segmentation Strategy

Source: https://gukhanmun.org/guide/javascript/conversion

Configures Gukhanmun's segmentation strategy. 'lattice' uses dynamic programming for optimal segmentation, while 'eager' uses a greedy approach for faster processing.

```typescript
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({
  segmentation: "lattice",  // default: optimal, dynamic programming
  // segmentation: "eager", // greedy, faster but less accurate
});
```

--------------------------------

### stdictFstBytes()

Source: https://gukhanmun.org/api/js/functions/_gukhanmun_stdict-fst.stdictFstBytes

Loads the bundled Standard Korean Language Dictionary as raw bytes. The access strategy is chosen from the URL scheme. A `file:` URL is read from disk with `node:fs/promises`; any other scheme is retrieved with `fetch`.

```APIDOC
## Function: stdictFstBytes()

> **stdictFstBytes**(`url?`): `Promise`

Loads the bundled Standard Korean Language Dictionary as raw bytes.

The access strategy is chosen from the URL scheme, not from the host runtime. A `file:` URL is read from disk with `node:fs/promises`; any other scheme is retrieved with `fetch`.

## Parameters

### url?

`URL` = `stdictFstUrl`

Location of the FST binary to read. Defaults to the bundled [stdictFstUrl](/api/js/variables/_gukhanmun_stdict-fst.stdictFstUrl.md); pass another URL to load a relocated copy.

## Returns

`Promise`

The FST binary as a `Uint8Array`.
```

--------------------------------

### Configuring Original Mode with Gloss Style

Source: https://gukhanmun.org/guide/rust/rendering

Shows how to use RenderMode::Original with custom gloss styles like parentheses or Ruby. This is useful for disambiguating homophones.

```rust
use gukhanmun::{RenderOptions, RenderMode, OriginalGloss};

builder.rendering(RenderOptions {
    mode: RenderMode::Original,
    original_gloss: Some(OriginalGloss::Parens),  // or OriginalGloss::Ruby
});
```

--------------------------------

### Enable Initial Sound Law (Redundant)

Source: https://gukhanmun.org/guide/cli/conversion

Explicitly enables the initial sound law. This flag is redundant when the `ko-kr` preset is used, as the law is enabled by default.

```sh
gukhanmun --initial-sound-law input.txt
```

--------------------------------

### Process Input with Definition Gloss

Source: https://gukhanmun.org/guide/cli/conversion

Shows how Gukhanmun handles input with a parenthetical gloss that serves as a definition rather than a reading annotation. The gloss is passed through untouched.

```sh
echo '庫間(물건을 간직하여 두는 곳)' | gukhanmun
# 곳간(물건을 간직하여 두는 곳)
```

--------------------------------

### Load with Numeral Handling Options

Source: https://gukhanmun.org/guide/javascript/conversion

Demonstrates different numeral handling strategies. 'hangul-phonetic' provides phonetic readings, 'positional-arabic' and 'additive-arabic' render numbers using Arabic numerals, and 'smart' intelligently chooses the best representation.

```typescript
// @noErrors: 2451
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({ numerals: "hangul-phonetic" }); // 이공일륙 (default)
const g = await load({ numerals: "positional-arabic"}); // 2016
const g = await load({ numerals: "additive-arabic" });  // 11 (月), 1234
const g = await load({ numerals: "smart" });            // picks best per context
```

--------------------------------

### Basic Rendering with Hangul and Hanja in Parentheses

Source: https://gukhanmun.org/guide/javascript/rendering

Demonstrates the 'hangul-hanja-parens' rendering mode, which displays the Hangul reading followed by the original Hanja in parentheses. This mode is useful for providing both the pronunciation and the original characters.

```typescript
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({
  rendering: "hangul-hanja-parens",
  dictionaries: [await stdictFst()],
});

console.log(g.convert("漢字"));  // 한자(漢字)
```
Tokens:
Raw