gukhanmun/
lib.rs

1// Gukhanmun: umbrella library that wires the engine and adapters together.
2// Copyright (C) 2026  Hong Minhee
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program.  If not, see <https://www.gnu.org/licenses/>.
16
17//! Gukhanmun umbrella library.
18//!
19//! This crate is the high-level entry point for the gukhanmun hanja-to-hangul
20//! conversion pipeline. It re-exports public items from the workspace's
21//! sibling crates under feature flags and provides a [`Builder`] /
22//! [`Converter`] facade that wires the reader, engine, middlewares, renderer,
23//! and writer stages together.
24//!
25//! See the workspace's `DESIGN.md` for the architectural overview.
26//!
27//! # Quick start (default preset, bundled dictionary)
28//!
29//! ```
30//! # #[cfg(feature = "stdict")] {
31//! use gukhanmun::Builder;
32//!
33//! let converter = Builder::new().build()?;
34//! assert_eq!(converter.convert_text_to_string("學校")?, "학교");
35//! # } Ok::<(), gukhanmun::Error>(())
36//! ```
37//!
38//! # Custom user dictionary, no bundled data
39//!
40//! ```
41//! use gukhanmun::{Builder, MapDictionary};
42//!
43//! let mut user = MapDictionary::new();
44//! user.insert("外字", "외자");
45//! let converter = Builder::new()
46//!     .no_bundled_stdict()
47//!     .push_dictionary(user)
48//!     .build()?;
49//! assert_eq!(converter.convert_text_to_string("外字")?, "외자");
50//! # Ok::<(), gukhanmun::Error>(())
51//! ```
52//!
53//! # North Korean (`ko-kp`) preset
54//!
55//! ```
56//! use gukhanmun::{Builder, Preset};
57//!
58//! let converter = Builder::with_preset(Preset::KoKp).build()?;
59//! // Without the initial sound law, `來日` falls back to `래일`.
60//! assert_eq!(converter.convert_text_to_string("來日")?, "래일");
61//! # Ok::<(), gukhanmun::Error>(())
62//! ```
63//!
64//! # HTML fragment conversion (`feature = "html"`)
65//!
66//! ```
67//! # #[cfg(all(feature = "html", feature = "stdict"))] {
68//! use gukhanmun::Builder;
69//!
70//! let converter = Builder::new().build()?;
71//! let output = converter.convert_html_fragment_to_string("<p>學校</p>")?;
72//! assert!(output.contains("학교"));
73//! # } Ok::<(), gukhanmun::Error>(())
74//! ```
75
76#![forbid(unsafe_code)]
77#![deny(missing_docs)]
78
79mod builder;
80mod error;
81mod options;
82
83pub use builder::{Builder, Converter};
84pub use error::{Error, Result};
85pub use options::{ConversionOptions, Preset};
86
87// Always-on re-exports from `gukhanmun-core` so that downstream users do not
88// have to depend on the core crate directly.
89pub use gukhanmun_core::{
90    Annotation, ChainDictionary, ContextWindow, DictionaryRecord, DirectiveAction, Engine,
91    EngineOptions, FirstOccurrenceFilter, HanjaDictionary, HomophoneDetection, HomophoneMarker,
92    InputToken, MapDictionary, Match, MatchMark, NumeralStrategy, OriginalGloss, OutputToken,
93    PlainScopeData, RecoverableInputError, Recovery, RenderMode, RenderOptions, RenderedToken,
94    Renderer, RubyBase, Scope, ScopeData, SegmentationStrategy, UnihanCharDict, UserDirectives,
95    apply_user_directives, apply_user_directives_iter, convert_plain_text,
96    convert_plain_text_with_options, filter_first_occurrences, is_hanja, mark_homophones,
97    mark_homophones_with_detection, process_fallible_tokens, process_fallible_tokens_with_options,
98    process_tokens, process_tokens_iter, process_tokens_iter_with_options,
99    process_tokens_with_options, read_plain_text, recover_input_token, recover_input_tokens,
100    render_tokens, render_tokens_iter, write_plain_text,
101};
102
103/// HTML adapter (re-export of [`gukhanmun_html`]).
104#[cfg(feature = "html")]
105pub mod html {
106    pub use gukhanmun_html::*;
107}
108
109/// Markdown adapter (re-export of [`gukhanmun_markdown`]).
110#[cfg(feature = "markdown")]
111pub mod markdown {
112    pub use gukhanmun_markdown::*;
113}
114
115/// FST dictionary backend (re-export of [`gukhanmun_fst`]).
116#[cfg(feature = "fst")]
117pub mod fst {
118    pub use gukhanmun_fst::*;
119}
120
121/// CDB dictionary backend (re-export of [`gukhanmun_cdb`]).
122#[cfg(feature = "cdb")]
123pub mod cdb {
124    pub use gukhanmun_cdb::*;
125}
126
127/// Bundled *Standard Korean Language Dictionary* (re-export of
128/// [`gukhanmun_stdict`]).
129#[cfg(feature = "stdict")]
130pub mod stdict {
131    pub use gukhanmun_stdict::*;
132}
gukhanmun/lib.rs

gukhanmun/
lib.rs
