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 extremely 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 Features
12//!
13//! - **Hybrid Engine**: Combines rule-based flexibility with DFA-based speed.
14//! - **Zero-Allocation**: Core processing path avoids heap allocations for maximum performance.
15//! - **Lazy JIT DFA**: Learns and caches syllable states on-the-fly.
16//! - **WASM Ready**: Optimized for web and constrained environments.
17//!
18//! ## Core Concepts
19//!
20//! - **[`Engine`]**: The main stateful processor. You feed it characters/strings, and it
21//!   maintains the internal composition state to produce the correctly marked Vietnamese text.
22//! - **[`InputMethod`]**: Defines the rules for transformations (e.g., how "as" becomes "á").
23//!   Built-in methods include [`InputMethod::telex()`], [`InputMethod::vni()`], etc.
24//! - **[`Mode`]**: Determines if the engine should process characters as Vietnamese or
25//!   treat them as plain English.
26//! - **[`OutputOptions`]**: A bitmask to customize the flattened string output (e.g., lowercase,
27//!   toneless, etc.).
28//!
29//! ## Quick Start
30//!
31//! ```rust
32//! use bamboo_core::{Engine, Mode, InputMethod, OutputOptions};
33//!
34//! // Create an engine with the standard Telex input method
35//! let mut engine = Engine::new(InputMethod::telex());
36//!
37//! // No explicit warm-up needed: the DFA learns on demand (lazy JIT)
38//!
39//! // Process a string and get the output immediately
40//! let word = engine.process("tieengs", Mode::Vietnamese);
41//! assert_eq!(word, "tiếng");
42//!
43//! // Reset for a new word
44//! engine.reset();
45//! let word2 = engine.process("vieetj", Mode::Vietnamese);
46//! assert_eq!(word2, "việt");
47//! ```
48//!
49//! ## Advanced Usage
50//!
51//! ### Customizing Output
52//!
53//! You can use [`OutputOptions`] to transform the result on the fly:
54//!
55//! ```rust
56//! use bamboo_core::{Engine, Mode, InputMethod, OutputOptions};
57//!
58//! let mut engine = Engine::new(InputMethod::telex());
59//! engine.process_str("Trangws", Mode::Vietnamese);
60//!
61//! // Get toneless version
62//! let options = OutputOptions::TONE_LESS;
63//! assert_eq!(engine.get_processed_str(options), "Trăng");
64//! ```
65//!
66//! ### Handling Backspaces
67//!
68//! The engine supports removing the last transformation while maintaining DFA consistency:
69//!
70//! ```rust
71//! # use bamboo_core::{Engine, Mode, InputMethod};
72//! # let mut engine = Engine::new(InputMethod::telex());
73//! engine.process_str("chuyeenr", Mode::Vietnamese);
74//! assert_eq!(engine.output(), "chuyển");
75//!
76//! // remove_last_char removes the last physical keystroke and its effects
77//! engine.remove_last_char(true);
78//! assert_eq!(engine.output(), "chuyên");
79//! ```
80
81mod bamboo_util;
82mod charset_def;
83mod config;
84mod dfa;
85mod encoder;
86mod engine;
87mod flattener;
88mod input_method;
89mod input_method_def;
90mod mode;
91mod spelling;
92mod utils;
93
94pub mod ffi;
95pub mod wasm;
96
97pub use config::Config;
98pub use engine::{Engine, Transformation, TransformationStack};
99pub use input_method::InputMethod;
100pub use mode::{Mode, OutputOptions};
101
102/// Advanced types for low-level interaction with the engine.
103///
104/// This module exposes internal structures and raw definitions
105/// for users who need to build custom input methods or analyze the composition state.
106pub mod advanced {
107    pub use crate::engine::{MAX_ACTIVE_TRANS, Transformation, TransformationStack};
108    pub use crate::input_method::{EffectType, Mark, Rule, Tone};
109    pub use crate::mode::OutputOptions;
110
111    pub use crate::charset_def::{get_charset_definition, get_charset_definitions};
112    pub use crate::dfa::{Dfa, State};
113    pub use crate::encoder::{encode, get_charset_name, get_charset_names};
114    pub use crate::input_method_def::{get_input_method, get_input_method_definitions};
115}
bamboo_core/lib.rs

bamboo_core/
lib.rs
