bamboo_core/lib.rs
1//! # Bamboo Core Rust
2//!
3//! A high-performance Vietnamese input method engine (IME) core, ported from the original
4//! [bamboo-core](https://github.com/BambooEngine/bamboo-core) in Go.
5//!
6//! This crate provides the foundational logic for processing Vietnamese text, supporting
7//! various input methods like Telex, VNI, and VIQR. It is designed to be fast,
8//! memory-efficient (zero-allocation in core processing), and easy to integrate into
9//! UI applications or other text processing tools.
10//!
11//! ## Core Concepts
12//!
13//! - **[`Engine`]**: The main stateful processor. You feed it characters/strings, and it
14//! maintains the internal composition state to produce the correctly marked Vietnamese text.
15//! - **[`InputMethod`]**: Defines the rules for transformations (e.g., how "as" becomes "á").
16//! Built-in methods include [`InputMethod::telex()`], [`InputMethod::vni()`], etc.
17//! - **[`Mode`]**: Determines if the engine should process characters as Vietnamese or
18//! treat them as plain English.
19//! - **[`OutputOptions`]**: A bitmask to customize the flattened string output (e.g., lowercase,
20//! toneless, etc.).
21//!
22//! ## Quick Start
23//!
24//! ```rust
25//! use bamboo_core::{Engine, Mode, InputMethod, OutputOptions};
26//!
27//! // Create an engine with the standard Telex input method
28//! let mut engine = Engine::new(InputMethod::telex());
29//!
30//! // Process a string of keys
31//! engine.process_str("tieengs", Mode::Vietnamese);
32//! assert_eq!(engine.output(), "tiếng");
33//!
34//! // Reset for a new word
35//! engine.reset();
36//! engine.process_str("vieetj", Mode::Vietnamese);
37//! assert_eq!(engine.output(), "việt");
38//! ```
39//!
40//! ## Advanced Usage
41//!
42//! ### Customizing Output
43//!
44//! You can use [`OutputOptions`] to transform the result on the fly:
45//!
46//! ```rust
47//! use bamboo_core::{Engine, Mode, InputMethod, OutputOptions};
48//!
49//! let mut engine = Engine::new(InputMethod::telex());
50//! engine.process_str("Trangws", Mode::Vietnamese);
51//!
52//! // Get toneless version
53//! let options = OutputOptions::TONE_LESS;
54//! assert_eq!(engine.get_processed_str(options), "Trăng");
55//! ```
56//!
57//! ### Handling Backspaces
58//!
59//! The engine supports removing the last transformation:
60//!
61//! ```rust
62//! # use bamboo_core::{Engine, Mode, InputMethod};
63//! # let mut engine = Engine::new(InputMethod::telex());
64//! engine.process_str("chuyeenr", Mode::Vietnamese);
65//! assert_eq!(engine.output(), "chuyển");
66//!
67//! // remove_last_char removes the last 'appending' character and its marks
68//! engine.remove_last_char(true);
69//! assert_eq!(engine.output(), "chuyể");
70//! ```
71
72mod bamboo_util;
73mod charset_def;
74mod config;
75mod dfa;
76mod encoder;
77mod engine;
78mod flattener;
79mod input_method;
80mod input_method_def;
81mod mode;
82mod spelling;
83mod utils;
84
85pub mod ffi;
86pub mod wasm;
87
88pub use config::Config;
89pub use engine::Engine;
90pub use input_method::InputMethod;
91pub use mode::{Mode, OutputOptions};
92
93/// Advanced types for low-level interaction with the engine.
94///
95/// This module exposes internal structures like [`crate::advanced::Transformation`] and raw definitions
96/// for users who need to build custom input methods or analyze the composition state.
97pub mod advanced {
98 pub use crate::engine::Transformation;
99 pub use crate::input_method::{EffectType, Mark, Rule, Tone};
100 pub use crate::mode::OutputOptions;
101
102 pub use crate::charset_def::{get_charset_definition, get_charset_definitions};
103 pub use crate::dfa::{Dfa, State};
104 pub use crate::encoder::{encode, get_charset_name, get_charset_names};
105 pub use crate::input_method_def::{get_input_method, get_input_method_definitions};
106}