{"id":46569023,"url":"https://github.com/alexrios/zmenu","last_synced_at":"2026-03-07T08:02:30.997Z","repository":{"id":321679800,"uuid":"1086778965","full_name":"alexrios/zmenu","owner":"alexrios","description":"A cross-platform dmenu-like application launcher built with Zig and SDL3.","archived":false,"fork":false,"pushed_at":"2025-11-23T18:27:01.000Z","size":72,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-23T20:16:46.983Z","etag":null,"topics":["dmenu","sdl3","sdl3-ttf","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexrios.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-30T22:26:55.000Z","updated_at":"2025-11-23T18:27:05.000Z","dependencies_parsed_at":"2025-10-31T00:24:57.294Z","dependency_job_id":"7fa701c4-3dd0-48fc-95bb-6a5a257aa67b","html_url":"https://github.com/alexrios/zmenu","commit_stats":null,"previous_names":["alexrios/zmenu"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alexrios/zmenu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexrios%2Fzmenu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexrios%2Fzmenu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexrios%2Fzmenu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexrios%2Fzmenu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexrios","download_url":"https://codeload.github.com/alexrios/zmenu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexrios%2Fzmenu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30209796,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T05:23:27.321Z","status":"ssl_error","status_checked_at":"2026-03-07T05:00:17.256Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dmenu","sdl3","sdl3-ttf","zig"],"created_at":"2026-03-07T08:02:30.121Z","updated_at":"2026-03-07T08:02:30.970Z","avatar_url":"https://github.com/alexrios.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zmenu\n\nA cross-platform dmenu-like application launcher built with Zig and SDL3.\n\n## Features\n\n- **Fast and lightweight** menu selection interface\n- **Fuzzy matching** - Type letters and they can match anywhere (e.g., \"abc\" matches \"a_b_c\")\n- **Case-insensitive filtering** - Search without worrying about caps (ASCII only)\n- **UTF-8 safe** - Handles multi-byte characters correctly in input and items\n- **Multi-line display** - See up to 10 items at once with scrolling\n- **Keyboard-driven navigation** with vim-style keybindings\n- **Cross-platform** - Runs on Linux, Windows, and macOS without code changes\n- **Zero configuration** - Works out of the box with sensible defaults\n\n## Usage\n\nzmenu reads items from stdin and displays them in a menu:\n\n```bash\n# Simple example\necho -e \"Apple\\nBanana\\nCherry\\nDate\\nEldberry\" | zmenu\n\n# From a file\ncat items.txt | zmenu\n\n# Use with find\nfind . -type f | zmenu\n```\n\nThe selected item is written to stdout, making it easy to use in scripts:\n\n```bash\nselected=$(find ~/projects -maxdepth 1 -type d | zmenu)\ncd \"$selected\"\n```\n\n### Keyboard Controls\n\n**Navigation:**\n- `↑` / `k` - Move selection up\n- `↓` / `j` - Move selection down\n- `Tab` - Move to next item\n- `Shift+Tab` - Move to previous item\n- `Page Up` - Jump up one page (10 items)\n- `Page Down` - Jump down one page (10 items)\n- `Home` - Jump to first item\n- `End` - Jump to last item\n\n**Input:**\n- Type any text - Fuzzy filter items (case-insensitive, UTF-8 safe)\n- `Backspace` - Delete last character (UTF-8 aware)\n- `Ctrl+U` - Clear entire input\n- `Ctrl+W` - Delete last word\n\n**Actions:**\n- `Enter` - Select current item and output to stdout\n- `Escape` / `Ctrl+C` - Cancel without selection\n\n### Display\n\n- Top left: Input prompt with your query\n- Top right: Filtered count / Total items\n- Bottom right (if needed): Scroll indicator showing visible range\n- Selected item has `\u003e` prefix and highlighted color\n\n## Themes\n\nzmenu supports multiple color themes via the `ZMENU_THEME` environment variable:\n\n```bash\n# Use a specific theme (note: env var must be set for zmenu, not the input command)\necho -e \"Apple\\nBanana\\nCherry\" | ZMENU_THEME=dracula zmenu\n\n# Works with any command\nfind . -type f | ZMENU_THEME=nord zmenu\n\n# Or export first, then use normally\nexport ZMENU_THEME=gruvbox\nseq 1 100 | zmenu\n\n# Set as default in your shell config (~/.bashrc, ~/.zshrc, etc.)\nexport ZMENU_THEME=gruvbox\n```\n\n### Available Themes\n\n**Catppuccin Family** (pastel themes):\n- **mocha** (default) - Dark pastel with purple-gray background\n- **latte** - Light pastel with lavender background\n- **frappe** - Medium-dark pastel\n- **macchiato** - Dark-medium pastel\n\n**Classic Themes**:\n- **dracula** - Popular dark theme with vibrant pink/cyan accents\n- **gruvbox** - Retro warm dark theme with earthy tones\n- **nord** - Cool arctic-inspired theme with blue accents\n- **solarized** - Low-contrast dark theme\n\nIf `ZMENU_THEME` is not set or contains an invalid name, zmenu defaults to **mocha**.\n\nTheme names are case-insensitive (`NORD`, `nord`, and `NoRd` all work).\n\n## Development\n\n- [mise](https://mise.jdx.dev/) for version management\n- **No SDL3 system libraries required!** - zig-sdl3 bundles everything\n\n### Setup\n\n1. Install mise (if not already installed):\n```bash\ncurl https://mise.run | sh\n```\n\n2. Install Zig via mise:\n```bash\nmise install\n```\n\n3. Build the project:\n```bash\nmise run build\n```\n\n### Available mise Tasks\n\n- `mise run build` - Build the project\n- `mise run run` - Run the application\n- `mise run test` - Run tests\n- `mise run clean` - Clean build artifacts\n- `mise run check` - Check code without building\n\n### Project Structure\n\n```\nzmenu/\n├── .mise.toml          # Mise configuration and tasks\n├── build.zig           # Build configuration\n├── build.zig.zon       # Dependencies (zig-sdl3)\n├── src/\n│   ├── main.zig        # Main application (~740 lines)\n│   └── theme.zig       # Theme definitions (8 color themes)\n└── README.md\n```\n\n## Implementation Details\n\n### Fuzzy Matching Algorithm\n\nThe fuzzy matcher allows characters to appear in order but not necessarily consecutively:\n\n```\nQuery: \"abc\"\nMatches: \"AaBbCc\", \"a_long_b_string_c\", \"AbsolutelyBigCat\"\nNo Match: \"cba\", \"acb\"\n```\n\n**Important**: Case-insensitive matching only works for ASCII characters (a-z, A-Z). UTF-8 characters like é, ü, 日 are matched byte-for-byte:\n- ✅ \"Café\" matches \"caf\" (ASCII part is case-insensitive)\n- ❌ \"café\" does NOT match \"cafe\" (é ≠ e)\n- ✅ \"日本語\" matches \"日本\" (exact UTF-8 bytes)\n\nThis design choice ensures UTF-8 safety without complex Unicode normalization.\n\n\n## Design Philosophy\n\nThis project follows a pragmatic approach:\n\n- **Simple, maintainable code** - Single ~500-line file, easy to understand\n- **Minimal dependencies** - Just zig-sdl3 (which bundles SDL3)\n- **Clear separation of concerns** - Init, event handling, rendering, filtering\n- **Performance-conscious but readable** - Optimized where it matters, clear elsewhere\n- **Helper methods** - Navigation, text editing extracted to focused functions\n\n## Testing\n\nThe project includes automated tests covering critical functionality:\n\n```bash\nmise run test  # Run all tests\n```\n\n**Test Coverage:**\n- Fuzzy matching (basic, case-insensitive, UTF-8 handling)\n- UTF-8 boundary detection for safe truncation\n- UTF-8 aware character deletion (backspace, word deletion)\n- Color comparison\n- Configuration validation\n\nAll tests use Zig's built-in testing framework and run on every build.\n\n## Cross-Platform\n\n**Supported Platforms**: Linux, macOS, Windows\n\n**Building for different platforms:**\n\n```bash\n# Native build\nmise run build\n\n# Cross-compile to Windows\nzig build -Dtarget=x86_64-windows\n\n# Cross-compile to macOS\nzig build -Dtarget=x86_64-macos\n\n# Cross-compile to Linux\nzig build -Dtarget=x86_64-linux\n```\n\n## Known limitations\n\n- No configuration file support yet\n- No history/frecency tracking\n- Window size is fixed (800x300)\n\n## Future Enhancements\n\n**Planned:**\n- [ ] Configuration file support (`~/.config/zmenu/config.toml`)\n- [ ] History tracking with frecency scoring\n- [ ] Multi-column layout option\n- [ ] Preview pane for file paths\n- [ ] Custom keybinding support\n\n**Maybe:**\n- [ ] Plugin system for custom filters\n- [ ] Custom theme support (user-defined colors)\n- [ ] Desktop file integration (.desktop files)\n- [ ] Icon support\n\n## Contributing\n\nThis is a learning project exploring Zig + SDL3.\n\nDiscussions, issues and PRs are welcomed!\n\n## License\n\nThis project is open source. Use it however you'd like.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexrios%2Fzmenu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexrios%2Fzmenu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexrios%2Fzmenu/lists"}