How iberianpig/fusuma works
Project Overview and Main Components
• Project Type & Purpose: Fusuma is a Ruby-based application that processes touchpad inputs (such as swipes, pinches, rotates, and holds) to trigger configurable commands. It acts both as a daemon listening for multitouch events and as a configurable tool with an extensible plugin system.
• Core Areas: The system comprises a core engine (located in lib/fusuma/) that deals with inputs, configuration, device management, logging, and then a very modular plugin system. Key directories include:
• lib/fusuma (core logic, configuration, device handling, multi_logger, etc.)
• lib/fusuma/plugin (the plugin architecture that is subdivided into various aspects: inputs, filters, detectors, parsers, executors, and events)
Detailed Component Breakdown
a. Core Engine:
• Entry Point: The executable (exe/fusuma) calls into the primary module (lib/fusuma.rb) which initializes the environment, loads configuration (found in lib/fusuma/config.rb and config files), and sets up device listeners.
• Configuration: The system reads gesture mapping and sensitivity settings from YAML configuration files (lib/fusuma/config.yml and user’s ~/.config/fusuma/config.yml).
• Device Handling & Environment: Components such as device.rb and environment.rb are responsible for interfacing with /dev/input and setting up an accurate context for gesture recognition.
• Logging: multi_logger.rb is used to track events and errors through the application's lifecycle.
b. Plugin System:
• Modular Plugins: Fusuma offers a robust plugin system to extend its core functions. The system is organized into several key plugin directories:
– Input Plugins (located in lib/fusuma/plugin/inputs): where the raw touchpad events are captured. Notable files include:
• libinput_command_input.rb – handles command-based inputs
• timer_input.rb – manages time-based input events.
– Filter Plugins (located in lib/fusuma/plugin/filters): to pre-process and filter raw events. Primary file is:
• libinput_device_filter.rb – used to validate and filter device-specific events.
– Parser Plugins (located in lib/fusuma/plugin/parsers): to convert filtered input events into gesture events that the system understands. Key file:
• libinput_gesture_parser.rb – responsible for interpreting the raw event sequences.
– Additional Plugins: Beyond these, there are detectors (for identifying swipes, pinches, etc.), executors (which execute configured commands), and event recorders. Though your custom instructions focus on the chain from inputs → filters → parsers, these other plugins complete the flow.
Relationships and Data Flow
• Next Stage: From the Filter Plugins, the flow continues to “Parser Plugins” (featuring libinput_gesture_parser.rb) which transform filtered data into actionable gestures.
• Final Routing: Although not specifically in your custom instructions, from the parser stage, consider showing flow toward “Detector Plugins”, “Event Management”, and finally “Executor Plugins” which carry out the actual command (like invoking xdotool) as configured in the YAML files.
• Feedback & Logging: A bi-directional link from all stages back to the “Multi Logger” and “Environment” components can also be drawn to indicate logging, error handling, and environment adjustments.
Architectural Patterns & Technologies
• Modular Plugin Architecture: The design relies heavily on a modular plugin pattern which allows easy extension and swapping out of functionality.
• Configuration-Driven Behavior: Emphasize that YAML configuration files drive most behavioral aspects (e.g., gesture mapping, thresholds, and intervals).
• Ruby Ecosystem: Note the use of RubyGems (with fusuma.gemspec and Gemfile) and the separation between production files (in lib/) and tests (in spec/). This is characteristic of well-structured Ruby projects.