kiwi_rs/lib.rs
1#![deny(missing_docs)]
2
3//! Rust bindings for Kiwi C API.
4//!
5//! This crate provides a high-level API that is convenient for day-to-day use,
6//! while still exposing lower-level handles for advanced scenarios.
7//!
8//! ## Quick Start
9//! ```no_run
10//! use kiwi_rs::Kiwi;
11//!
12//! fn main() -> Result<(), Box<dyn std::error::Error>> {
13//! let kiwi = Kiwi::init()?;
14//! let tokens = kiwi.tokenize("아버지가방에들어가신다.")?;
15//! for token in tokens {
16//! println!("{}/{}", token.form, token.tag);
17//! }
18//! Ok(())
19//! }
20//! ```
21//!
22//! ## Initialization Paths
23//! `kiwi-rs` supports two common initialization modes:
24//!
25//! 1. Automatic bootstrap via [`Kiwi::init`]
26//! - Uses local paths first.
27//! - If unavailable, downloads a matching Kiwi library/model pair into cache.
28//! 2. Explicit setup via [`Kiwi::from_config`]
29//! - For controlled deployments with fixed library/model paths.
30//!
31//! ```no_run
32//! use kiwi_rs::{Kiwi, KiwiConfig};
33//!
34//! fn main() -> Result<(), Box<dyn std::error::Error>> {
35//! let config = KiwiConfig::default()
36//! .with_library_path("/path/to/libkiwi.dylib")
37//! .with_model_path("/path/to/models/cong/base");
38//! let kiwi = Kiwi::from_config(config)?;
39//! let _tokens = kiwi.tokenize("형태소 분석 예시")?;
40//! Ok(())
41//! }
42//! ```
43//!
44//! ## Offset And Unit Rules
45//! - For UTF-8 APIs, offsets are character indices (based on `str.chars()`),
46//! not byte indices.
47//! - UTF-16 APIs accept `&[u16]`, but returned text in this crate is converted
48//! back to Rust UTF-8 `String`.
49//!
50//! ## Environment Variables
51//! - `KIWI_LIBRARY_PATH`: explicit dynamic library path.
52//! - `KIWI_MODEL_PATH`: explicit model directory path.
53//! - `KIWI_RS_VERSION`: version used by [`Kiwi::init`] bootstrap (`latest` by default).
54//! - `KIWI_RS_CACHE_DIR`: cache root used by [`Kiwi::init`] bootstrap.
55
56mod bootstrap;
57mod config;
58mod constants;
59mod discovery;
60mod error;
61mod model;
62mod native;
63mod runtime;
64mod types;
65
66pub use constants::*;
67pub use error::{KiwiError, Result};
68pub use model::{
69 ExtractedWord, GlobalConfig, MorphemeInfo, MorphemeSense, PreAnalyzedToken, SentenceBoundary,
70 SimilarityPair, TokenInfo,
71};
72pub use runtime::{
73 Kiwi, KiwiBuilder, KiwiLibrary, KiwiTypo, MorphemeSet, PreparedJoinMorphs, PreparedJoiner,
74 Pretokenized, SwTokenizer,
75};
76pub use types::{
77 Analysis, AnalysisCandidate, AnalyzeOptions, BuilderConfig, KiwiConfig, Sentence, Token,
78 UserWord,
79};
80
81#[cfg(test)]
82mod tests;