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//! // Optional: pre-populate DFA for peak performance
38//! engine.warm_up();
39//!
40//! // Process a string and get the output immediately
41//! let word = engine.process("tieengs", Mode::Vietnamese);
42//! assert_eq!(word, "tiếng");
43//!
44//! // Reset for a new word
45//! engine.reset();
46//! let word2 = engine.process("vieetj", Mode::Vietnamese);
47//! assert_eq!(word2, "việt");
48//! ```
49//!
50//! ## Advanced Usage
51//!
52//! ### Customizing Output
53//!
54//! You can use [`OutputOptions`] to transform the result on the fly:
55//!
56//! ```rust
57//! use bamboo_core::{Engine, Mode, InputMethod, OutputOptions};
58//!
59//! let mut engine = Engine::new(InputMethod::telex());
60//! engine.process_str("Trangws", Mode::Vietnamese);
61//!
62//! // Get toneless version
63//! let options = OutputOptions::TONE_LESS;
64//! assert_eq!(engine.get_processed_str(options), "Trăng");
65//! ```
66//!
67//! ### Handling Backspaces
68//!
69//! The engine supports removing the last transformation while maintaining DFA consistency:
70//!
71//! ```rust
72//! # use bamboo_core::{Engine, Mode, InputMethod};
73//! # let mut engine = Engine::new(InputMethod::telex());
74//! engine.process_str("chuyeenr", Mode::Vietnamese);
75//! assert_eq!(engine.output(), "chuyển");
76//!
77//! // remove_last_char removes the last physical keystroke and its effects
78//! engine.remove_last_char(true);
79//! assert_eq!(engine.output(), "chuyên");
80//! ```
81
82mod bamboo_util;
83mod charset_def;
84mod config;
85mod dfa;
86mod encoder;
87mod engine;
88mod flattener;
89mod input_method;
90mod input_method_def;
91mod mode;
92mod spelling;
93mod utils;
94
95pub mod ffi;
96pub mod wasm;
97
98pub use config::Config;
99pub use engine::{Engine, Transformation, TransformationStack};
100pub use input_method::InputMethod;
101pub use mode::{Mode, OutputOptions};
102
103/// Advanced types for low-level interaction with the engine.
104///
105/// This module exposes internal structures and raw definitions
106/// for users who need to build custom input methods or analyze the composition state.
107pub mod advanced {
108    pub use crate::engine::{MAX_ACTIVE_TRANS, Transformation, TransformationStack};
109    pub use crate::input_method::{EffectType, Mark, Rule, Tone};
110    pub use crate::mode::OutputOptions;
111
112    pub use crate::charset_def::{get_charset_definition, get_charset_definitions};
113    pub use crate::dfa::{Dfa, State};
114    pub use crate::encoder::{encode, get_charset_name, get_charset_names};
115    pub use crate::input_method_def::{get_input_method, get_input_method_definitions};
116}
bamboo_core/lib.rs

bamboo_core/
lib.rs
