Merge pull request #41 from ZeroX-DG/method-definition

Method definition
ZeroX-DG · Jun 3, 2024 · 401e094 · 401e094
2 parents 9fdff07 + 163aa83
commit 401e094
Show file tree

Hide file tree

Showing 17 changed files with 382 additions and 196 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- `vi::telex` & `vi::vni` are deprecated & will be removed in the next release. Users are recommended to use `vi::methods` instead.
+- `vi::telex::transform_buffer` & `vi::vni::transform_buffer` are deprecated. Users are recommended to use `vi::transform_buffer` instead.
+
+### Added
+
+- `vi::methods` module containing method definition & transforming functions.
diff --git a/benches/transform_benchmark.rs b/benches/transform_benchmark.rs
@@ -4,42 +4,42 @@ pub fn telex_benchmark(c: &mut Criterion) {
     c.bench_function("telex vieejt", |b| {
         b.iter(|| {
             let mut output = String::new();
-            vi::telex::transform_buffer(black_box("vieejt".chars()), &mut output)
+            vi::transform_buffer(&vi::TELEX, black_box("vieejt".chars()), &mut output)
         })
     });
 
     c.bench_function("telex ddaay", |b| {
         b.iter(|| {
             let mut output = String::new();
-            vi::telex::transform_buffer(black_box("ddaay".chars()), &mut output)
+            vi::transform_buffer(&vi::TELEX, black_box("ddaay".chars()), &mut output)
         })
     });
 
     c.bench_function("telex jjjjjjjjjjjjjj", |b| {
         b.iter(|| {
             let mut output = String::new();
-            vi::telex::transform_buffer(black_box("jjjjjjjjjjjjjj".chars()), &mut output)
+            vi::transform_buffer(&vi::TELEX, black_box("jjjjjjjjjjjjjj".chars()), &mut output)
         })
     });
 
     c.bench_function("telex jj", |b| {
         b.iter(|| {
             let mut output = String::new();
-            vi::telex::transform_buffer(black_box("jj".chars()), &mut output)
+            vi::transform_buffer(&vi::TELEX, black_box("jj".chars()), &mut output)
         })
     });
 
     c.bench_function("telex nghienge", |b| {
         b.iter(|| {
             let mut output = String::new();
-            vi::telex::transform_buffer(black_box("nghienge".chars()), &mut output)
+            vi::transform_buffer(&vi::TELEX, black_box("nghienge".chars()), &mut output)
         })
     });
 
     c.bench_function("telex ddaaysf", |b| {
         b.iter(|| {
             let mut output = String::new();
-            vi::telex::transform_buffer(black_box("ddaaysf".chars()), &mut output)
+            vi::transform_buffer(&vi::TELEX, black_box("ddaaysf".chars()), &mut output)
         })
     });
 }
@@ -48,42 +48,42 @@ pub fn vni_benchmark(c: &mut Criterion) {
     c.bench_function("vni viet65", |b| {
         b.iter(|| {
             let mut output = String::new();
-            vi::vni::transform_buffer(black_box("viet65".chars()), &mut output)
+            vi::transform_buffer(&vi::VNI, black_box("viet65".chars()), &mut output)
         })
     });
 
     c.bench_function("vni day96", |b| {
         b.iter(|| {
             let mut output = String::new();
-            vi::vni::transform_buffer(black_box("ddaay".chars()), &mut output)
+            vi::transform_buffer(&vi::VNI, black_box("ddaay".chars()), &mut output)
         })
     });
 
     c.bench_function("vni 1111111111111111", |b| {
         b.iter(|| {
             let mut output = String::new();
-            vi::vni::transform_buffer(black_box("1111111111111111".chars()), &mut output)
+            vi::transform_buffer(&vi::VNI, black_box("1111111111111111".chars()), &mut output)
         })
     });
 
     c.bench_function("vni 11", |b| {
         b.iter(|| {
             let mut output = String::new();
-            vi::vni::transform_buffer(black_box("11".chars()), &mut output)
+            vi::transform_buffer(&vi::VNI, black_box("11".chars()), &mut output)
         })
     });
 
     c.bench_function("vni nghieng6", |b| {
         b.iter(|| {
             let mut output = String::new();
-            vi::vni::transform_buffer(black_box("nghieng6".chars()), &mut output)
+            vi::transform_buffer(&vi::VNI, black_box("nghieng6".chars()), &mut output)
         })
     });
 
     c.bench_function("vni day9612", |b| {
         b.iter(|| {
             let mut output = String::new();
-            vi::vni::transform_buffer(black_box("day9612".chars()), &mut output)
+            vi::transform_buffer(&vi::VNI, black_box("day9612".chars()), &mut output)
         })
     });
 }

diff --git a/examples/custom_definition.rs b/examples/custom_definition.rs
@@ -0,0 +1,34 @@
+use phf::phf_map;
+use vi::{
+    processor::{LetterModification, ToneMark},
+    Action, Definition,
+};
+
+// Custom vni method with ư short hand using the w character
+const MY_VNI: Definition = phf_map! {
+    '1' => &[Action::AddTonemark(ToneMark::Acute)],
+    '2' => &[Action::AddTonemark(ToneMark::Grave)],
+    '3' => &[Action::AddTonemark(ToneMark::HookAbove)],
+    '4' => &[Action::AddTonemark(ToneMark::Tilde)],
+    '5' => &[Action::AddTonemark(ToneMark::Underdot)],
+    '6' => &[Action::ModifyLetter(LetterModification::Circumflex)],
+    '7' => &[Action::ModifyLetter(LetterModification::Horn)],
+    '8' => &[Action::ModifyLetter(LetterModification::Breve)],
+    '9' => &[Action::ModifyLetter(LetterModification::Dyet)],
+    'z' => &[Action::ResetInsertedƯ, Action::InsertƯ],
+    '0' => &[Action::RemoveToneMark],
+};
+
+fn main() {
+    let inputs = "Xin hay4 mo73 toang het61 nhzng4 canh1 cza3 cua3 qua1 khz1 de963 thuyen62 toi6 nzong gio1 lang4 quen6 ra khoi7";
+
+    let words = inputs.split(' ');
+
+    let mut result = String::new();
+    for word in words {
+        vi::transform_buffer(&MY_VNI, word.chars(), &mut result);
+        result.push(' ');
+    }
+
+    println!("{}", result); // prints "Xin hãy mở toang hết những cánh cửa của quá khứ để thuyền tôi nương gió lãng quên ra khơi"
+}
diff --git a/examples/long.rs b/examples/long.rs
@@ -1,6 +1,6 @@
 extern crate vi;
 
-use vi::vni;
+use vi::{transform_buffer, VNI};
 
 fn main() {
     let inputs = "xin chao2 toi6 la2 Hung7, toi6 den961 tu72 Viet65 Nam";
@@ -9,7 +9,7 @@ fn main() {
 
     let mut result = String::new();
     for word in words {
-        vni::transform_buffer(word.chars(), &mut result);
+        transform_buffer(&VNI, word.chars(), &mut result);
         result.push(' ');
     }
 

diff --git a/examples/repl.rs b/examples/repl.rs
@@ -1,7 +1,6 @@
 extern crate vi;
 
 use rustyline::DefaultEditor;
-use vi::{telex, vni};
 
 // A REPL for testing transformation result.
 fn main() {
@@ -16,11 +15,13 @@ fn main() {
         let mut result = String::new();
 
         for word in input.split_whitespace() {
-            if method == "telex" {
-                telex::transform_buffer(word.chars(), &mut result)
+            let definition = if method == "telex" {
+                &vi::TELEX
             } else {
-                vni::transform_buffer(word.chars(), &mut result)
+                &vi::VNI
             };
+
+            vi::transform_buffer(definition, word.chars(), &mut result);
             result.push(' ');
         }
 

diff --git a/examples/simple.rs b/examples/simple.rs
@@ -1,13 +1,11 @@
 extern crate vi;
 
-use vi::vni;
-
 fn main() {
     let inputs = vec![vec!['v', 'i', 'e', 't', '5', '6'], vec!['n', 'a', 'm']];
 
     let mut result = String::new();
     for input in inputs {
-        vni::transform_buffer(input.iter().cloned(), &mut result);
+        vi::transform_buffer(&vi::VNI, input.iter().cloned(), &mut result);
         result.push(' ');
     }
 

diff --git a/examples/telex.rs b/examples/telex.rs
@@ -1,15 +1,13 @@
 extern crate vi;
 
-use vi::telex;
-
 fn main() {
     let inputs = "hoiwx anh tifnh yeue gioosng nhuw cais cheets nuotos trooi taats car";
 
     let words = inputs.split(' ');
 
     let mut result = String::new();
     for word in words {
-        telex::transform_buffer(word.chars(), &mut result);
+        vi::transform_buffer(&vi::TELEX, word.chars(), &mut result);
         result.push(' ');
     }
 

diff --git a/examples/vni.rs b/examples/vni.rs
@@ -1,15 +1,13 @@
 extern crate vi;
 
-use vi::vni;
-
 fn main() {
     let inputs = "anh se4 lam2, lam2 ta6t1 ca3 de963 d9uo75c che6t1 thay em";
 
     let words = inputs.split(' ');
 
     let mut result = String::new();
     for word in words {
-        vni::transform_buffer(word.chars(), &mut result);
+        vi::transform_buffer(&vi::VNI, word.chars(), &mut result);
         result.push(' ');
     }
 

diff --git a/src/editing.rs b/src/editing.rs
@@ -1,3 +1,6 @@
+//! Functions used for character editing.
+//!
+//! These functions work directly with character & string instead of the abstract word struct.
 use crate::{
     maps::{
         ACCUTE_MAP, BREVE_MAP, CIRCUMFLEX_MAP, DOT_MAP, DYET_MAP, GRAVE_MAP, HOOK_ABOVE_MAP,

diff --git a/src/lib.rs b/src/lib.rs
@@ -14,11 +14,10 @@
 //! # Example
 //!
 //! ```
-//! use vi::vni;
 //! let inputs = vec![vec!['v', 'i', 'e', 't', '5', '6'], vec!['n', 'a', 'm']];
 //! let mut result = String::new();
 //! for input in inputs {
-//!     vni::transform_buffer(input.iter().cloned(), &mut result);
+//!     vi::transform_buffer(&vi::VNI, input.iter().cloned(), &mut result);
 //!     result.push(' ');
 //! }
 //! println!("{}", result); // prints "việt nam "
@@ -29,24 +28,21 @@
 //! VI aims to be as lean as possible, focusing on only the useful features and main use-cases. Therefore, the engine
 //! implemented these rules by default with no way of configuring them:
 //!
-//! - **Tone mark are placed in the new accent:** hoà instead of hòa
+//! - **Tone mark are placed in the new accent:** `hoà` instead of `hòa`
 //! - **`w` in telex will insert `ư`:** so `chuw` or `chw` will produce `chư`
+//!
+//! Although, should you need to customise any behaviour, you can create your custom typing methods. See: [`methods`].
 pub mod editing;
 pub mod maps;
+pub mod methods;
 pub mod parsing;
 pub mod processor;
+#[deprecated(since = "0.7.0")]
 pub mod telex;
 pub mod util;
 pub mod validation;
+#[deprecated(since = "0.7.0")]
 pub mod vni;
 pub mod word;
 
-/// A result of a buffer transformation.
-#[derive(Debug, Clone)]
-#[allow(dead_code)]
-pub struct TransformResult {
-    /// Indicates whether a tone mark has been removed after the transformation.
-    pub tone_mark_removed: bool,
-    /// Indicates whether a letter modification has been removed after the transformation.
-    pub letter_modification_removed: bool,
-}
+pub use methods::*;