litsea_binding_core/lib.rs
1//! FFI-independent helpers shared by the Litsea language bindings
2//! (`litsea-python`, `litsea-nodejs`, `litsea-php`, `litsea-ruby`,
3//! `litsea-wasm`).
4//!
5//! Each binding wraps the [`litsea`] crate for its own FFI layer (PyO3,
6//! napi, ext-php-rs, magnus, wasm-bindgen). Without a shared layer, all five
7//! would reimplement the same plumbing: parsing a language name, deciding
8//! whether a model file is a segmentation model or a two-stage POS model,
9//! keeping a reusable [`litsea::SegmentBuffer`], attaching byte offsets to
10//! tokens, driving the trainers with a cancellation flag, and turning
11//! [`litsea::LitseaError`] into something the host language can raise. That
12//! logic lives here as plain Rust, so it can be unit-tested without any FFI
13//! toolchain.
14//!
15//! # Model loading
16//!
17//! Models are never embedded in a binding package (they range from 86 KB to
18//! 8.3 MB); the caller supplies one as bytes, a filesystem path, or a URI:
19//!
20//! ```no_run
21//! use litsea::Language;
22//! use litsea_binding_core::CoreSegmenter;
23//!
24//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
25//! let segmenter = CoreSegmenter::from_path(Language::Japanese, "japanese.model".as_ref())?;
26//! assert!(!segmenter.has_pos());
27//! println!("{:?}", segmenter.segment("すもももももももものうち"));
28//! # Ok(())
29//! # }
30//! ```
31//!
32//! The model kind is detected from the file itself
33//! ([`litsea::ModelKind::detect`]), so bindings do not expose a `--pos`-style
34//! flag: loading `japanese_pos.model` yields a segmenter where
35//! [`CoreSegmenter::has_pos`] is `true` and
36//! [`CoreSegmenter::segment_with_pos`] works.
37//!
38//! # Platform support
39//!
40//! [`trainer`] and the blocking model loaders are unavailable on
41//! `wasm32-unknown-unknown`: feature extraction and training are file-based,
42//! and there is no filesystem. WASM callers fetch the model bytes in
43//! JavaScript and use [`CoreSegmenter::from_bytes`].
44
45pub mod cancel;
46pub mod error;
47pub mod language;
48pub mod model;
49#[cfg(not(target_arch = "wasm32"))]
50pub mod runtime;
51pub mod segmenter;
52pub mod token;
53#[cfg(not(target_arch = "wasm32"))]
54pub mod trainer;
55
56pub use cancel::CancelToken;
57pub use error::{CoreError, CoreResult, ErrorKind};
58pub use language::{SUPPORTED_LANGUAGES, language_name, parse_language, supported_language_names};
59#[cfg(not(target_arch = "wasm32"))]
60pub use model::read_model_file;
61pub use model::{
62 BuiltSegmenter, build_segmenter, build_segmenter_with, build_user_dictionary,
63 build_user_dictionary_with_tags, read_model_uri,
64};
65pub use segmenter::CoreSegmenter;
66pub use token::TokenView;
67#[cfg(not(target_arch = "wasm32"))]
68pub use trainer::{
69 CoreExtractor, CorePerceptronTrainer, CoreTrainer, CoreTwoStageTrainer, CorpusFormat,
70 parse_feature_set,
71};
72
73/// Returns the version of the `litsea-binding-core` crate.
74///
75/// It always equals [`litsea::version`], since the workspace crates share
76/// `workspace.package.version` (the test below checks it). The bindings
77/// report [`litsea::version`] from their own `version()` functions and do
78/// not call this one.
79///
80/// # Returns
81/// The crate's `CARGO_PKG_VERSION`.
82#[must_use]
83pub fn version() -> &'static str {
84 env!("CARGO_PKG_VERSION")
85}
86
87#[cfg(test)]
88mod tests {
89 use super::*;
90
91 #[test]
92 fn test_version_matches_the_workspace_version() {
93 assert_eq!(version(), env!("CARGO_PKG_VERSION"));
94 // Every workspace crate shares `workspace.package.version`.
95 assert_eq!(version(), litsea::version());
96 }
97}