drae: the RAE Spanish dictionary in the terminalHEADmain

1 files changed, 131 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dc9f816
--- /dev/null
+++ b/README.md
@@ -0,0 +1,131 @@
+# drae
+
+[Español](README.es.md)
+
+The Spanish dictionary of the Real Academia Española (RAE) in your terminal:
+definitions, etymology, synonyms and antonyms, and full verb conjugation.
+
+```console
+$ drae casa
+casa
+Del lat. casa 'choza'.
+
+1. f. Edificio para habitar.
+   Una casa de ocho plantas.
+   Sin.: vivienda, inmueble, domicilio, hogar, residencia, piso, apartamento…
+
+2. f. Edificio de una o pocas plantas destinado a vivienda unifamiliar, en
+   oposición a piso.
+   Quieren vender el piso y comprarse una casa.
+   Sin.: chalé, chalet
+```
+
+Every lookup is stored in a local cache, so the second time it answers
+instantly and offline.
+
+The tool is meant for Spanish speakers, so its commands, flags and messages
+are in Spanish; the code is in English.
+
+## Install
+
+```sh
+git clone https://git.all.ar/pub/drae-cli.git
+cd drae-cli
+cargo install --path .
+```
+
+This puts the `drae` binary in `~/.cargo/bin`.
+
+## Usage
+
+| Command | What it does |
+| --- | --- |
+| `drae casa` | Defines a word |
+| `drae definir sin` | Defines a word that clashes with a command name |
+| `drae sin casa` | Synonyms and antonyms, sense by sense |
+| `drae conjugar hablar` | Full conjugation, including voseo |
+| `drae conjugar ser --modo subjuntivo` | A single mood |
+| `drae dia` | The RAE word of the day |
+| `drae azar` | A random word |
+| `drae buscar edificio` | Searches inside the definitions already cached |
+| `drae cache info \| listar \| limpiar` | Manages the cache |
+
+Global options:
+
+| Option | What it does |
+| --- | --- |
+| `--json` | Prints JSON instead of formatted text |
+| `-a`, `--abreviaturas` | Expands the marks: `f. = nombre femenino` |
+| `-A`, `--actualizar` | Ignores the cache and downloads again |
+| `--sin-cache` | Neither reads nor writes the cache |
+| `--ancho N` | Output width in columns |
+| `--color auto\|always\|never` | When to use color |
+| `--fuente auto\|dle\|rae-api` | Where to read from |
+
+Color turns itself off when the output goes to a pipe or when `NO_COLOR` is set.
+
+### When the word does not exist
+
+The closest words are looked up in the system hunspell dictionary, offline and
+ignoring accents:
+
+```console
+$ drae arbol
+drae: «arbol» no está en el Diccionario
+  ¿quiso decir árbol?
+```
+
+## Where the data comes from
+
+| What | Source |
+| --- | --- |
+| Definitions, etymology, synonyms | [rae-api.com](https://rae-api.com), which serves the content of the *Diccionario de la lengua española* as JSON |
+| Conjugation | [Spanish Wiktionary](https://es.wiktionary.org) (CC BY-SA) |
+| Suggestions | `/usr/share/hunspell/es_*.dic`, local |
+
+`dle.rae.es` is an optional source (`--fuente dle`). The site answers every
+non-browser client with a Cloudflare challenge, so it almost never responds
+from a terminal; its HTML reader is kept, and tested against a fixture, in
+case it gets through on your network.
+
+Conjugation comes from Wiktionary rather than the RAE for the same reason,
+with a bonus: it includes voseo («vos hablás»), which the RAE tables leave out.
+
+```console
+$ drae conjugar ser --modo subjuntivo
+Modo subjuntivo
+  Presente
+    que yo sea · que tú seas · que vos seas, seás · que él/ella/ud. sea ·
+    que nosotros seamos · que vosotros seáis · que uds./ellos sean
+```
+
+rae-api.com allows 10 requests per minute. The cache hides that, but keep it
+in mind if you look up many words in a row.
+
+## Configuration
+
+Optional, in `~/.config/drae/config.toml`. Everything has a default and
+command-line options always win over the file.
+
+```toml
+fuente = "auto"        # auto | dle | rae-api
+timeout = 15           # seconds per request
+ancho = 80             # defaults to the terminal width
+# cache = "~/.cache/drae/entries.db"
+# diccionario = "/usr/share/hunspell/es_AR.dic"
+```
+
+## Development
+
+```sh
+cargo test          # 70 tests, none of them touch the network
+cargo build --release
+```
+
+The DLE reader is tested against `tests/fixtures/dle-casa.html`, a real page
+trimmed down, so it stays verified even while the live path is blocked.
+
+## License
+
+MIT. The dictionary content belongs to the Real Academia Española; the
+conjugation tables come from Wiktionary, under CC BY-SA.