rename key bindings API

- `KeyBindMatcher` -> `KeybindDispatcher`
- `KeyBinds` -> `Keybinds`
- `Keybind` -> `Keybind`

Author: rhysd

Cargo.lock

@@ -1,9 +1,9 @@
 [package]
 name = "keybinds"
-version = "0.0.2"
+version = "0.0.3"
 edition = "2021"
 authors = ["rhysd <[email protected]>"]
-description = "Platform&Framework-agnostic key bindings parser and matcher"
+description = "Platform&Framework-agnostic key bindings parser and dispatcher"
 license = "MIT"
 homepage = "https://github.com/rhysd/keybinds-rs#readme"
 repository = "https://github.com/rhysd/keybinds-rs"

Cargo.toml

@@ -5,7 +5,7 @@ keybinds-rs
 **THIS CRATE IS WORK IN PROGRESS YET. The first beta release is planned as 0.1.0. Until then, this
 library can be buggy and have arbitrary breaking changes.**
 
-[keybinds-rs][crates-io] is a small Rust crate to define/parse/match key bindings.
+[keybinds-rs][crates-io] is a small Rust crate to define/parse/dispatch key bindings.
 
 - Provide a syntax to easily define key bindings in a configuration file like `Ctrl+A`
 - Support key sequences like `Ctrl+X Ctrl+S`
@@ -34,12 +34,12 @@ cargo add keybinds --features=serde
 
 ## Basic usage
 
-This crate is platform-agnostic. Define key bindings by `KeyBinds` and build `KeyBindMatcher` instance with it.
+This crate is platform-agnostic. Define key bindings by `Keybinds` and build `KeybindDispatcher` instance with it.
 Pass each key input to the `trigger` method and it returns a triggered action. Key sequence and key combination
 can be parsed using `FromStr` trait. See the [API documentation][api-doc] for more details.
 
 ```rust
-use keybinds::{KeyBind, KeyBinds, KeyBindMatcher, KeyInput, Key, Mods};
+use keybinds::{KeybindDispatcher, KeyInput, Key, Mods};
 
 // Actions triggered by key bindings
 #[derive(PartialEq, Eq, Debug)]
@@ -49,32 +49,32 @@ enum Action {
     ExitApp,
 }
 
-// Create a matcher to trigger actions for upcoming key inputs
-let mut matcher = KeyBindMatcher::default();
+// Create a dispatcher to trigger actions for upcoming key inputs
+let mut dispatcher = KeybindDispatcher::default();
 
 // Register key bindings to trigger the actions
 
 // Key sequence "hello"
-matcher.bind("h e l l o", Action::SayHello).unwrap();
+dispatcher.bind("h e l l o", Action::SayHello).unwrap();
 // Key combination "Ctrl + Shift + Enter"
-matcher.bind("Ctrl+Shift+Enter", Action::OpenFile).unwrap();
+dispatcher.bind("Ctrl+Shift+Enter", Action::OpenFile).unwrap();
 // Sequence of key combinations
-matcher.bind("Ctrl+x Ctrl+c", Action::ExitApp).unwrap();
+dispatcher.bind("Ctrl+x Ctrl+c", Action::ExitApp).unwrap();
 
 // Trigger `SayHello` action
-assert_eq!(matcher.trigger(KeyInput::from('h')), None);
-assert_eq!(matcher.trigger(KeyInput::from('e')), None);
-assert_eq!(matcher.trigger(KeyInput::from('l')), None);
-assert_eq!(matcher.trigger(KeyInput::from('l')), None);
-assert_eq!(matcher.trigger(KeyInput::from('o')), Some(&Action::SayHello));
+assert_eq!(dispatcher.trigger(KeyInput::from('h')), None);
+assert_eq!(dispatcher.trigger(KeyInput::from('e')), None);
+assert_eq!(dispatcher.trigger(KeyInput::from('l')), None);
+assert_eq!(dispatcher.trigger(KeyInput::from('l')), None);
+assert_eq!(dispatcher.trigger(KeyInput::from('o')), Some(&Action::SayHello));
 
 // Trigger `OpenFile` action
-let action = matcher.trigger(KeyInput::new(Key::Enter, Mods::CTRL | Mods::SHIFT));
+let action = dispatcher.trigger(KeyInput::new(Key::Enter, Mods::CTRL | Mods::SHIFT));
 assert_eq!(action, Some(&Action::OpenFile));
 
 // Trigger `ExitApp` action
-assert_eq!(matcher.trigger(KeyInput::new('x', Mods::CTRL)), None);
-assert_eq!(matcher.trigger(KeyInput::new('c', Mods::CTRL)), Some(&Action::ExitApp));
+assert_eq!(dispatcher.trigger(KeyInput::new('x', Mods::CTRL)), None);
+assert_eq!(dispatcher.trigger(KeyInput::new('c', Mods::CTRL)), Some(&Action::ExitApp));
 ```
 
 ## Syntax for key sequence and combination
@@ -118,11 +118,11 @@ The serde support requires the `serde` feature enabled.
 
 ### Parsing key bindings configurations
 
-`KeyBinds` implements serde's `Deserialize` trait. This is an example to parse key bindings with [toml][] crate.
+`Keybinds` implements serde's `Deserialize` trait. This is an example to parse key bindings with [toml][] crate.
 
 ```rust,ignore
 use serde::Deserialize;
-use keybinds::{KeyBinds, KeyBindMatcher, Key, Mods, KeyInput};
+use keybinds::{Keybinds, KeybindDispatcher, Key, Mods, KeyInput};
 
 // Actions triggered by key bindings
 #[derive(Deserialize, PartialEq, Eq, Debug)]
@@ -134,8 +134,8 @@ enum Action {
 // Configuration file format of your application
 #[derive(Deserialize)]
 struct Config {
-    // `KeyBinds` implements serde's `Deserialize`
-    bindings: KeyBinds<Action>,
+    // `Keybinds` implements serde's `Deserialize`
+    bindings: Keybinds<Action>,
 }
 
 let configuration = r#"
@@ -148,8 +148,8 @@ let configuration = r#"
 let config: Config = toml::from_str(configuration).unwrap();
 
 // Use the key bindings parsed from the TOML input
-let mut matcher = KeyBindMatcher::new(config.bindings);
-let action = matcher.trigger(KeyInput::new(Key::Enter, Mods::CTRL | Mods::SHIFT));
+let mut dispatcher = KeybindDispatcher::new(config.bindings);
+let action = dispatcher.trigger(KeyInput::new(Key::Enter, Mods::CTRL | Mods::SHIFT));
 assert_eq!(action, Some(&Action::OpenFile));
 ```
 

README.md

@@ -1,6 +1,6 @@
 use crossterm::event::{read, Event};
 use crossterm::terminal::{disable_raw_mode, enable_raw_mode};
-use keybinds::{KeyBindMatcher, KeyInput};
+use keybinds::{KeyInput, KeybindDispatcher};
 use std::io;
 
 // Actions triggered by key bindings
@@ -13,14 +13,14 @@ enum Action {
 }
 
 fn main() -> io::Result<()> {
-    // Create a matcher to trigger actions for upcoming key inputs
-    let mut matcher = KeyBindMatcher::default();
+    // Create a dispatcher to trigger actions for upcoming key inputs
+    let mut dispatcher = KeybindDispatcher::default();
 
     // Key bindings to trigger the actions
-    matcher.bind("h i", Action::SayHi).unwrap();
-    matcher.bind("Left", Action::MoveLeft).unwrap();
-    matcher.bind("Ctrl+p", Action::Paste).unwrap();
-    matcher.bind("Ctrl+x Ctrl+c", Action::ExitApp).unwrap();
+    dispatcher.bind("h i", Action::SayHi).unwrap();
+    dispatcher.bind("Left", Action::MoveLeft).unwrap();
+    dispatcher.bind("Ctrl+p", Action::Paste).unwrap();
+    dispatcher.bind("Ctrl+x Ctrl+c", Action::ExitApp).unwrap();
 
     println!("Type Ctrl+X → Ctrl+C to exit");
     enable_raw_mode()?;
@@ -30,8 +30,8 @@ fn main() -> io::Result<()> {
             // Can convert crossterm's `KeyEvent` into `KeyInput`
             println!("Key input `{:?}`\r", KeyInput::from(event));
 
-            // `KeyBindMatcher::trigger` accepts crossterm's `KeyEvent`
-            if let Some(action) = matcher.trigger(event) {
+            // `KeybindDispatcher::trigger` accepts crossterm's `KeyEvent`
+            if let Some(action) = dispatcher.trigger(event) {
                 println!("Triggered action `{action:?}`\r");
                 if action == &Action::ExitApp {
                     break;

examples/crossterm.rs

@@ -1,4 +1,4 @@
-use keybinds::{KeyBindMatcher, KeyInput};
+use keybinds::{KeyInput, KeybindDispatcher};
 use termwiz::caps::Capabilities;
 use termwiz::cell::AttributeChange;
 use termwiz::color::{AnsiColor, ColorAttribute};
@@ -17,14 +17,14 @@ enum Action {
 }
 
 fn main() -> Result<(), Error> {
-    // Create a matcher to trigger actions for upcoming key inputs
-    let mut matcher = KeyBindMatcher::default();
+    // Create an action dispatcher to trigger actions for upcoming key inputs
+    let mut dispatcher = KeybindDispatcher::default();
 
     // Key bindings to trigger the actions
-    matcher.bind("h i", Action::SayHi).unwrap();
-    matcher.bind("Left", Action::MoveLeft).unwrap();
-    matcher.bind("Ctrl+p", Action::Paste).unwrap();
-    matcher.bind("Ctrl+x Ctrl+c", Action::ExitApp).unwrap();
+    dispatcher.bind("h i", Action::SayHi).unwrap();
+    dispatcher.bind("Left", Action::MoveLeft).unwrap();
+    dispatcher.bind("Ctrl+p", Action::Paste).unwrap();
+    dispatcher.bind("Ctrl+x Ctrl+c", Action::ExitApp).unwrap();
 
     let caps = Capabilities::new_from_env()?;
     let terminal = new_terminal(caps)?;
@@ -43,7 +43,7 @@ fn main() -> Result<(), Error> {
         };
 
         // Trigger action by matching the key input
-        let action = matcher.trigger(&input);
+        let action = dispatcher.trigger(&input);
 
         buf.add_change(Change::CursorPosition {
             x: Position::Absolute(0),

examples/termwiz.rs

@@ -1,5 +1,5 @@
 use keybinds::winit::WinitEventConverter;
-use keybinds::KeyBindMatcher;
+use keybinds::KeybindDispatcher;
 use winit::application::ApplicationHandler;
 use winit::event::WindowEvent;
 use winit::event_loop::{ActiveEventLoop, EventLoop};
@@ -16,23 +16,23 @@ enum Action {
 
 struct App {
     window: Option<Window>,
-    matcher: KeyBindMatcher<Action>,
+    dispatcher: KeybindDispatcher<Action>,
     converter: WinitEventConverter,
 }
 
 impl Default for App {
     fn default() -> Self {
-        let mut matcher = KeyBindMatcher::default();
+        let mut dispatcher = KeybindDispatcher::default();
 
         // Key bindings to trigger the actions
-        matcher.bind("h i", Action::SayHi).unwrap();
-        matcher.bind("Mod+m", Action::ToggleMaximized).unwrap();
-        matcher.bind("Mod+Shift+t", Action::ToggleTheme).unwrap();
-        matcher.bind("Mod+x Mod+c", Action::Exit).unwrap();
+        dispatcher.bind("h i", Action::SayHi).unwrap();
+        dispatcher.bind("Mod+m", Action::ToggleMaximized).unwrap();
+        dispatcher.bind("Mod+Shift+t", Action::ToggleTheme).unwrap();
+        dispatcher.bind("Mod+x Mod+c", Action::Exit).unwrap();
 
         Self {
             window: None,
-            matcher,
+            dispatcher,
             converter: WinitEventConverter::default(),
         }
     }
@@ -50,7 +50,7 @@ impl ApplicationHandler for App {
         let input = self.converter.convert(&event);
 
         // Check if the converted key input triggers some action
-        if let Some(action) = self.matcher.trigger(input) {
+        if let Some(action) = self.dispatcher.trigger(input) {
             println!("Action: {action:?}");
 
             match action {

examples/winit.rs

@@ -274,12 +274,12 @@ impl From<char> for KeySeq {
 }
 
 #[derive(Clone, PartialEq, Eq, Debug)]
-pub struct KeyBind<A> {
+pub struct Keybind<A> {
     seq: KeySeq,
     action: A,
 }
 
-impl<A> KeyBind<A> {
+impl<A> Keybind<A> {
     pub fn multiple(seq: KeySeq, action: A) -> Self {
         Self { seq, action }
     }
@@ -290,20 +290,20 @@ impl<A> KeyBind<A> {
 }
 
 #[derive(Clone, PartialEq, Eq, Debug)]
-pub struct KeyBinds<A>(Vec<KeyBind<A>>);
+pub struct Keybinds<A>(Vec<Keybind<A>>);
 
-impl<A> Default for KeyBinds<A> {
+impl<A> Default for Keybinds<A> {
     fn default() -> Self {
         Self(vec![])
     }
 }
 
-impl<A> KeyBinds<A> {
-    pub fn new(v: Vec<KeyBind<A>>) -> Self {
+impl<A> Keybinds<A> {
+    pub fn new(v: Vec<Keybind<A>>) -> Self {
         Self(v)
     }
 
-    pub fn find(&self, seq: &[KeyInput]) -> Match<&KeyBind<A>> {
+    pub fn find(&self, seq: &[KeyInput]) -> Match<&Keybind<A>> {
         let mut saw_prefix = false;
         for bind in self.0.iter() {
             match bind.seq.matches(seq) {
@@ -320,21 +320,21 @@ impl<A> KeyBinds<A> {
     }
 }
 
-pub struct KeyBindMatcher<A> {
-    binds: KeyBinds<A>,
+pub struct KeybindDispatcher<A> {
+    binds: Keybinds<A>,
     ongoing: Vec<KeyInput>,
     last_input: Option<Instant>,
     timeout: Duration,
 }
 
-impl<A> Default for KeyBindMatcher<A> {
+impl<A> Default for KeybindDispatcher<A> {
     fn default() -> Self {
-        Self::new(KeyBinds::default())
+        Self::new(Keybinds::default())
     }
 }
 
-impl<A> KeyBindMatcher<A> {
-    pub fn new(binds: KeyBinds<A>) -> Self {
+impl<A> KeybindDispatcher<A> {
+    pub fn new(binds: Keybinds<A>) -> Self {
         Self {
             binds,
             ongoing: vec![],
@@ -345,7 +345,7 @@ impl<A> KeyBindMatcher<A> {
 
     pub fn add<K: Into<KeySeq>>(&mut self, key: K, action: A) {
         let seq = key.into();
-        self.binds.0.push(KeyBind::multiple(seq, action));
+        self.binds.0.push(Keybind::multiple(seq, action));
     }
 
     pub fn bind(&mut self, key: &str, action: A) -> Result<()> {
@@ -453,19 +453,19 @@ mod tests {
     #[test]
     fn handle_input() {
         let binds = vec![
-            KeyBind::single(KeyInput::new('a', Mods::NONE), A::Action1),
-            KeyBind::single(KeyInput::new('a', Mods::CTRL | Mods::SHIFT), A::Action2),
-            KeyBind::multiple(
+            Keybind::single(KeyInput::new('a', Mods::NONE), A::Action1),
+            Keybind::single(KeyInput::new('a', Mods::CTRL | Mods::SHIFT), A::Action2),
+            Keybind::multiple(
                 KeySeq::new(vec![
                     KeyInput::new('b', Mods::NONE),
                     KeyInput::new('c', Mods::NONE),
                 ]),
                 A::Action3,
             ),
-            KeyBind::single(KeyInput::new(Key::Up, Mods::NONE), A::Action4),
+            Keybind::single(KeyInput::new(Key::Up, Mods::NONE), A::Action4),
         ];
 
-        let mut keybinds = KeyBindMatcher::new(KeyBinds(binds.clone()));
+        let mut keybinds = KeybindDispatcher::new(Keybinds(binds.clone()));
 
         for bind in binds {
             keybinds.reset();
@@ -481,8 +481,8 @@ mod tests {
 
     #[test]
     fn discard_ongoing_nothing_matched() {
-        let binds = vec![KeyBind::single(KeyInput::new('a', Mods::NONE), A::Action1)];
-        let mut keybinds = KeyBindMatcher::new(KeyBinds(binds.clone()));
+        let binds = vec![Keybind::single(KeyInput::new('a', Mods::NONE), A::Action1)];
+        let mut keybinds = KeybindDispatcher::new(Keybinds(binds.clone()));
 
         assert_eq!(keybinds.trigger(KeyInput::from('x')), None);
         assert_eq!(keybinds.trigger(KeyInput::from('y')), None);