How cspeterson/splatmoji works
Project Type and Purpose
• Splatmoji is an open-source, command-line utility written in Bash for quickly looking up and inserting emoji and emoticons/kaomoji on a GNU/Linux desktop via a pop-up menu.
• It leverages external tools (rofi, xdotool, xsel, jq) to present a menu, copy selections to the clipboard, or “type” them into the current window.
File‐Structure Analysis
• Top level
• splatmoji (the main executable script)
• splatmoji.config (default config template)
• build.sh, BUILD.md, LICENSE, README.md, CHANGELOG
• data/emoji & data/emoticons – TSV databases (per-language annotation files and emoticon lists)
• importers/ – scripts to convert external data sources into the TSV format
• lib/
• functions/ – reusable Bash functions for CLI parsing, data loading, filtering
• test_helpers/ – utilities for the test suite
• test/unit_tests – integration and unit tests (shunit2‐based)
Key Architecture Insights from README
• Modes of operation: copy, type, copypaste
• Configuration layering: built-in config, user config (~/.config/splatmoji/splatmoji.config), environment vars
• Data‐file discovery: CLI args → XDG_DATA_HOME → XDG_DATA_DIRS → in-repo data/
• Extensibility: custom TSV files, custom emoticon data, add new importers
a. Main Components
1. CLI Front End
• Argument parser, mode dispatcher
2. Configuration Manager
• Reads splatmoji.config and user overrides
3. Data Manager
• Discovers and loads TSV data files (emoji & emoticons)
• Applies language filters and skin-tone filters
4. UI Manager
• Builds the menu payload
• Invokes rofi (pop-up menu)
5. Selection Handler
• Receives user’s choice from rofi
• Updates history (recently‐used list)
6. Output Manager
• For “copy” mode: pipes output to xsel/xclip
• For “type” mode: invokes xdotool to type characters
• For “copypaste” mode: combo of both
7. Importer Tools (optional)
• Scripts in importers/ to generate/update TSV from external sources
8. Test Suite
• Runs functions through lib/test_helpers via shunit2
b. Relationships & Data Flow
• User invokes the splatmoji script → CLI Front End
• CLI Front End → Configuration Manager (load defaults + overrides)
• Configuration Manager → Data Manager (pass parameters: languages, skin-tones, disabled DB flags)
• Data Manager → UI Manager (provides list entries)
• UI Manager ↔ rofi (displays menu, captures selection)
• UI Manager → Selection Handler → updates history file via Data Manager
• Selection Handler → Output Manager → calls external tools (xsel, xdotool)
• Importer Tools → Data Manager (generate or refresh data/)
• Test Suite → each internal component (lib/functions, CLI script)
c. Architectural Patterns & Principles
• Modularization: separate responsibilities into small, reusable functions in lib/functions.
• Config layering: default + user override following XDG conventions.
• Data-driven design: all emoji/emoticon info lives in TSV files, making it easy to extend.
• External integration: thin wrappers around rofi, xdotool, xsel to remain agnostic of specific UI/clipboard implementations.
• Testability: functions are pure enough to be unit‐tested via shunit2.
d. Key Technologies & Libraries
• Bash (>=4.4)
• rofi (menu UI)
• xdotool (auto-typing)
• xsel or xclip (clipboard)
• jq (optional JSON escaping)
• shunit2 (testing)