How chaosnyaruko/ondict works
Project Overview & Core Purpose
• This is a dictionary application written in Go. It supports online queries (e.g., fetching definitions from the Longman online dictionary), offline queries (by decoding MDX/MDX-like dictionary files), and serves in multiple modes: CLI, interactive “repl”, and HTTP server mode. It also offers a standalone MDX parser tool (“dumpdict”) to convert MDX files into an SQLite database.
• In addition, integrations with external tools (for example, Neovim, FZF, and even hammerspoon for macOS) are provided. Users can also embed dictionary lookup functionality in different workflows.
Key Architectural Components
a. User Interface & Integration Layers:
• CLI (main.go, repl.go, server.go command-line options)
• HTTP/Web server (server.go, the assets directory, index.html, and associated static files)
• External integrations (Neovim integration via Lua scripts under the lua/ folder, FZF integration from the fzf/ directory, and hammerspoon usage mentioned in the README)
b. Dictionary Processing Engines:
• Online Engine: Module(s) responsible for fetching and processing online queries (references in sources/ and render/ for processing Longman online definitions).
• Offline/MDX Engine: Components in the decoder/ folder that parse MDX files (mdx.go, related cryptography functions for decoding) and the dumpdict command (cmd/dumpdict) for conversion into a SQLite database.
c. Rendering Layer:
• The render/ directory indicates modular renderers that can output HTML, Markdown, or other formats. These modules transform the processed dictionary entries into user-friendly output for different environments.
d. Data Modeling and Sources:
• The sources/ directory, including several files for managing dictionary entry definitions (e.g., aho_corasick.go for pattern matching, configuration, and parsing functions).
• Schema and Storage: schema.sql defines the database schema along with the “db/” directory (with an example SQLite database file "history.sqlite") that may be used to store query histories and additional data.
e. Utility and Infrastructure:
• Configuration files (e.g., config.json in the user’s config folder as described in the README, and the dotfiles like .dockerignore, .gitignore, and Dockerfile for containerized deployment).
• Build scripts and integration support (Makefile, build.sh, and GitHub workflow definitions under .github/).
Relationships and Data Flow
• Start at the User Interface layer (CLI, HTTP request, or an integration call from an editor).
• The query-handling module then selects which dictionary engine to invoke:
• The Online Engine calls out to external web APIs, processes the HTTP response, and passes the data to the renderer.
• The MDX Engine loads a dictionary file, decodes it using modules in the decoder/ folder, and then optionally persists or retrieves entries from the SQLite database.
• The processing engine hands off processed data to the Renderer modules (in render/) which convert entries into HTML, Markdown, or plain text.
• Final results are then returned to the user’s interface (CLI output, HTTP response, or embedded view in an editor).
• There is also an auxiliary “dumpdict” command (inside cmd/dumpdict) that periodically or on-demand converts MDX dictionaries into an SQLite database using schema.sql.
Architectural Patterns and Design Principles
• Separation of Concerns: Distinct modules for UI, processing engines, and rendering.
• Modularity & Extensibility: Extra dictionary sources can be plugged in (the “sources/” folder), and independent decoupled modules allow for multiple integration methods.
• Cross-platform Compatibility: The project’s design supports CLI usage, web server deployment, and integration with different tools, all implemented in Go.
• Use of Standard Configuration Conventions: Adhering to XDG_CONFIG_HOME for storing config and user data.