update the demo in readme to more practical example

Author: rhysd

Cargo.toml

@@ -35,7 +35,7 @@ required-features = ["arbitrary"]
 
 [[example]]
 name = "crossterm"
-required-features = ["crossterm"]
+required-features = ["crossterm", "serde"]
 
 [[example]]
 name = "termwiz"

README.md

@@ -28,49 +28,101 @@ library can be buggy and have arbitrary breaking changes.**
 cargo add keybinds
 ```
 
-## Minimal usage
+## Usage
 
-This crate is platform-agnostic. Create `KeybindDispatcher` instance and define key bindings by `bind` method.
-Pass each key input to the `dispatch` method call. It returns a dispatched action. See the [API documentation][api-doc]
-for more details.
+This code demonstrates the usage by parsing and dispatching key bindings for moving the cursor inside terminal
+using the `serde` and `crossterm` optional features. You can run this code as the [example](./examples/crossterm.rs)
+as well. See the [API documentation][api-doc] for more details.
 
 ```rust
-use keybinds::{KeybindDispatcher, KeyInput, Key, Mods};
+use crossterm::terminal::{disable_raw_mode, enable_raw_mode};
+use crossterm::{cursor, event, execute};
+use keybinds::{KeybindDispatcher, Keybinds};
+use serde::Deserialize;
+use std::io;
 
 // Actions dispatched by key bindings
-#[derive(PartialEq, Eq, Debug)]
+#[derive(Deserialize)]
 enum Action {
-    SayHello,
-    OpenFile,
-    ExitApp,
+    Exit,
+    Up,
+    Down,
+    Left,
+    Right,
+    Top,
+    Bottom,
+    Home,
+    End,
 }
 
-// Create a dispatcher to dispatch actions for upcoming key inputs
-let mut dispatcher = KeybindDispatcher::default();
-
-// Register key bindings to dispatch the actions
-
-// Key sequence "h" → "e" → "l" → "l" → "o"
-dispatcher.bind("h e l l o", Action::SayHello).unwrap();
-// Key combination "Ctrl + Alt + Enter"
-dispatcher.bind("Ctrl+Alt+Enter", Action::OpenFile).unwrap();
-// Sequence of key combinations
-dispatcher.bind("Ctrl+x Ctrl+c", Action::ExitApp).unwrap();
-
-// Dispatch `SayHello` action
-assert_eq!(dispatcher.dispatch(KeyInput::from('h')), None);
-assert_eq!(dispatcher.dispatch(KeyInput::from('e')), None);
-assert_eq!(dispatcher.dispatch(KeyInput::from('l')), None);
-assert_eq!(dispatcher.dispatch(KeyInput::from('l')), None);
-assert_eq!(dispatcher.dispatch(KeyInput::from('o')), Some(&Action::SayHello));
-
-// Dispatch `OpenFile` action
-let action = dispatcher.dispatch(KeyInput::new(Key::Enter, Mods::CTRL | Mods::ALT));
-assert_eq!(action, Some(&Action::OpenFile));
+// Configuration of your app
+#[derive(Deserialize)]
+struct Config {
+    keyboard: Keybinds<Action>,
+}
 
-// Dispatch `ExitApp` action
-assert_eq!(dispatcher.dispatch(KeyInput::new('x', Mods::CTRL)), None);
-assert_eq!(dispatcher.dispatch(KeyInput::new('c', Mods::CTRL)), Some(&Action::ExitApp));
+const CONFIG_FILE: &str = r#"
+[keyboard]
+"Esc" = "Exit"
+
+# Standard bindings
+"Up" = "Up"
+"Down" = "Down"
+"Left" = "Left"
+"Right" = "Right"
+"PageUp" = "Top"
+"PageDown" = "Bottom"
+"Home" = "Home"
+"End" = "End"
+
+# Emacs-like bindings
+"Ctrl+p" = "Up"
+"Ctrl+n" = "Down"
+"Ctrl+b" = "Left"
+"Ctrl+f" = "Right"
+"Alt+<" = "Top"
+"Alt+>" = "Bottom"
+"Ctrl+a" = "Home"
+"Ctrl+e" = "End"
+
+# Vim-like bindings
+"k" = "Up"
+"j" = "Down"
+"h" = "Left"
+"l" = "Right"
+"g g" = "Top"
+"G" = "Bottom"
+"^" = "Home"
+"$" = "End"
+"#;
+
+fn main() -> io::Result<()> {
+    // Parse the configuration from the file content
+    let config: Config = toml::from_str(CONFIG_FILE).unwrap();
+
+    // Create the key binding dispatcher to handle key input events
+    let mut dispatcher = KeybindDispatcher::new(config.keyboard);
+
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    while let Ok(event) = event::read() {
+        // If the event triggered some action, dispatch it
+        if let Some(action) = dispatcher.dispatch(&event) {
+            match action {
+                Action::Exit => break,
+                Action::Up => execute!(stdout, cursor::MoveUp(1))?,
+                Action::Down => execute!(stdout, cursor::MoveDown(1))?,
+                Action::Left => execute!(stdout, cursor::MoveLeft(1))?,
+                Action::Right => execute!(stdout, cursor::MoveRight(1))?,
+                Action::Top => execute!(stdout, cursor::MoveUp(9999))?,
+                Action::Bottom => execute!(stdout, cursor::MoveDown(9999))?,
+                Action::Home => execute!(stdout, cursor::MoveLeft(9999))?,
+                Action::End => execute!(stdout, cursor::MoveRight(9999))?,
+            }
+        }
+    }
+    disable_raw_mode()
+}
 ```
 
 ## Examples

examples/crossterm.rs

@@ -1,45 +1,88 @@
-use crossterm::event::{read, Event};
 use crossterm::terminal::{disable_raw_mode, enable_raw_mode};
-use keybinds::{KeyInput, KeybindDispatcher};
+use crossterm::{cursor, event, execute};
+use keybinds::{KeybindDispatcher, Keybinds};
+use serde::Deserialize;
 use std::io;
 
 // Actions dispatched by key bindings
-#[derive(PartialEq, Eq, Debug)]
+#[derive(Deserialize)]
 enum Action {
-    SayHi,
-    MoveLeft,
-    Paste,
-    ExitApp,
+    Exit,
+    Up,
+    Down,
+    Left,
+    Right,
+    Top,
+    Bottom,
+    Home,
+    End,
 }
 
+// Configuration of your app
+#[derive(Deserialize)]
+struct Config {
+    keyboard: Keybinds<Action>,
+}
+
+const CONFIG_FILE: &str = r#"
+[keyboard]
+"Esc" = "Exit"
+
+# Standard bindings
+"Up" = "Up"
+"Down" = "Down"
+"Left" = "Left"
+"Right" = "Right"
+"PageUp" = "Top"
+"PageDown" = "Bottom"
+"Home" = "Home"
+"End" = "End"
+
+# Emacs-like bindings
+"Ctrl+p" = "Up"
+"Ctrl+n" = "Down"
+"Ctrl+b" = "Left"
+"Ctrl+f" = "Right"
+"Alt+<" = "Top"
+"Alt+>" = "Bottom"
+"Ctrl+a" = "Home"
+"Ctrl+e" = "End"
+
+# Vim-like bindings
+"k" = "Up"
+"j" = "Down"
+"h" = "Left"
+"l" = "Right"
+"g g" = "Top"
+"G" = "Bottom"
+"^" = "Home"
+"$" = "End"
+"#;
+
 fn main() -> io::Result<()> {
-    // Create a dispatcher to dispatch actions for upcoming key inputs
-    let mut dispatcher = KeybindDispatcher::default();
+    // Parse the configuration from the file content
+    let config: Config = toml::from_str(CONFIG_FILE).unwrap();
 
-    // Key bindings to dispatch the actions
-    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();
+    // Create the key binding dispatcher to handle key input events
+    let mut dispatcher = KeybindDispatcher::new(config.keyboard);
 
-    println!("Type Ctrl+X → Ctrl+C to exit");
     enable_raw_mode()?;
-
-    while let Ok(event) = read() {
-        if let Event::Key(event) = event {
-            // Can convert crossterm's `KeyEvent` into `KeyInput`
-            println!("Key input `{:?}`\r", KeyInput::from(event));
-
-            // `KeybindDispatcher::dispatch` accepts crossterm's `KeyEvent`
-            if let Some(action) = dispatcher.dispatch(event) {
-                println!("Triggered action `{action:?}`\r");
-                if action == &Action::ExitApp {
-                    break;
-                }
+    let mut stdout = io::stdout();
+    while let Ok(event) = event::read() {
+        // If the event triggered some action, dispatch it
+        if let Some(action) = dispatcher.dispatch(&event) {
+            match action {
+                Action::Exit => break,
+                Action::Up => execute!(stdout, cursor::MoveUp(1))?,
+                Action::Down => execute!(stdout, cursor::MoveDown(1))?,
+                Action::Left => execute!(stdout, cursor::MoveLeft(1))?,
+                Action::Right => execute!(stdout, cursor::MoveRight(1))?,
+                Action::Top => execute!(stdout, cursor::MoveUp(9999))?,
+                Action::Bottom => execute!(stdout, cursor::MoveDown(9999))?,
+                Action::Home => execute!(stdout, cursor::MoveLeft(9999))?,
+                Action::End => execute!(stdout, cursor::MoveRight(9999))?,
             }
         }
     }
-
-    disable_raw_mode()?;
-    Ok(())
+    disable_raw_mode()
 }

src/arbitrary.rs

@@ -36,11 +36,21 @@ use arbitrary::{Arbitrary, Result, Unstructured};
 impl Arbitrary<'_> for Mods {
     fn arbitrary(u: &mut Unstructured<'_>) -> Result<Self> {
         let mut mods = Self::NONE;
-        mods.set(Mods::CTRL, u.arbitrary()?);
-        mods.set(Mods::CMD, u.arbitrary()?);
-        mods.set(Mods::ALT, u.arbitrary()?);
-        mods.set(Mods::WIN, u.arbitrary()?);
-        mods.set(Mods::SHIFT, u.arbitrary()?);
+        if u.arbitrary()? {
+            mods |= Mods::CTRL;
+        }
+        if u.arbitrary()? {
+            mods |= Mods::CMD;
+        }
+        if u.arbitrary()? {
+            mods |= Mods::ALT;
+        }
+        if u.arbitrary()? {
+            mods |= Mods::WIN;
+        }
+        if u.arbitrary()? {
+            mods |= Mods::SHIFT;
+        }
         Ok(mods)
     }
 }

src/keybind.rs

@@ -70,6 +70,12 @@ impl<A> From<Vec<Keybind<A>>> for Keybinds<A> {
     }
 }
 
+impl<A> From<Keybinds<A>> for Vec<Keybind<A>> {
+    fn from(binds: Keybinds<A>) -> Self {
+        binds.0
+    }
+}
+
 pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(1);
 
 pub struct KeybindDispatcher<A> {

src/lib.rs

@@ -12,6 +12,12 @@
 //!   - [winit][]
 //! - Support structral fuzzing using [arbitrary][] optionally.
 //!
+//! # Installation
+//!
+//! ```sh
+//! cargo add keybinds
+//! ```
+//!
 //! # Minimal example
 //!
 //! ```

src/serde.rs

@@ -37,7 +37,7 @@
 //! assert_eq!(&generated, configuration);
 //! ```
 use crate::{Key, KeyInput, KeySeq, Keybind, Keybinds, Mods};
-use serde::de::{Deserialize, Deserializer, MapAccess, Visitor};
+use serde::de::{self, Deserialize, Deserializer, MapAccess, Visitor};
 use serde::ser::{Serialize, SerializeMap, Serializer};
 use std::fmt;
 
@@ -52,7 +52,7 @@ impl<'de> Deserialize<'de> for KeyInput {
                 formatter.write_str("key sequence for a key bind")
             }
 
-            fn visit_str<E: serde::de::Error>(self, v: &str) -> Result<Self::Value, E> {
+            fn visit_str<E: de::Error>(self, v: &str) -> Result<Self::Value, E> {
                 v.parse().map_err(E::custom)
             }
         }
@@ -72,7 +72,7 @@ impl<'de> Deserialize<'de> for KeySeq {
                 formatter.write_str("key sequence for a key bind")
             }
 
-            fn visit_str<E: serde::de::Error>(self, v: &str) -> Result<Self::Value, E> {
+            fn visit_str<E: de::Error>(self, v: &str) -> Result<Self::Value, E> {
                 v.parse().map_err(E::custom)
             }
         }