Command line¶

dictshelf [command] [flags] [args]

dictshelf --help prints the full reference; dictshelf --version (-v) prints the version. --verbose applies to every command. Flags may be written with one or two dashes.

Commands¶

A command that takes a dictionary path also accepts a library folder: dictshelf info ~/.dmshlabs/dictshelf/db/Oxford and dictshelf info ~/.dmshlabs/dictshelf/db/Oxford/text.db are equivalent.

serve¶

dictshelf
dictshelf serve --port 9090 --no-browser
dictshelf ~/Dictionaries/Oxford.mdx     # serve that file's folder and open it

The other settings have no flag; they are set in the environment or in dictshelf.toml. Configuration lists them all.

list¶

dictshelf list ~/Dictionaries /Volumes/Ext/Dicts

Prints one line per dictionary found in the folders, subfolders included.

info¶

dictshelf info ~/Dictionaries/Oxford.mdx

Prints the name, format, number of entries, search modes, language and its source, description, and the files with their sizes: the dictionary files and the library folder.

files:
  original  ~/Dictionaries/Oxford.mdx    41.2 MB
  original  ~/Dictionaries/Oxford.mdd   301.7 MB
  prepared  ~/.dmshlabs/dictshelf/db/Oxford          63.4 MB
  total                                 406.3 MB

lookup, prefix, contains, fts¶

dictshelf lookup   [-n max] <dictfile> <word>    # exact; accent-folded if nothing matches
dictshelf prefix   [-n max] <dictfile> <word>    # exact, then prefix; accents ignored
dictshelf contains [-n max] <dictfile> <word>    # headwords containing <word>
dictshelf fts      [-n max] <dictfile> <query>   # full-text query, as in the app

contains and fts need an indexed dictionary: pass its library folder. fts reads the query as the app does (Full-text query syntax). The exit status is 1 when nothing matches.

dictshelf lookup -format clean -base http://127.0.0.1:6888 ~/Dictionaries/Oxford.mdx flight > flight.html

searchall¶

dictshelf searchall [-mode m] [-n perDict] [-format f] [-dict-dir <dir>] [<dir>] <term>

Searches every dictionary in the folders and prints each dictionary's results as it answers, so | head works on a large library. Each dictionary is opened for the search and closed when it has answered.

searchall opens each dictionary through its own format. Contains and full-text therefore return results only for dictionaries that index themselves (Lingvo DSL, Babylon, wudict markdown) and for library folders in the searched folders. The exit status is 1 when no dictionary matches.

keys¶

dictshelf keys [-offset N] [-n count] <dictfile>

Lists the headwords, all by default. For an .mdd file, lists the files it contains.

res¶

dictshelf res [-o out] [-f] <dictfile> <name>
dictshelf res ~/Dictionaries/Oxford.mdd audio/word.mp3

Extracts one resource. <name> is a name keys prints; an .mdd can be given directly.

dump¶

dictshelf dump [-format csv|md] [-mode html|clean] [-compress gz] [-resources all|text|none] -o <outdir> <dictfile>

CSV¶

dictshelf dump -o ~/exports ~/Dictionaries/Oxford.mdx

Writes <outdir>/<name>.csv in the layout pyglossary reads and writes (RFC 4180). The first rows are "#key","value" metadata; each following row is one entry: headword, article, alternative headwords.

"#name","Cambridge English Dictionary"
"#sourceLang","en"
"#description","18th Edition"
"aardvark","medium-sized, burrowing, nocturnal mammal","ant bear,earth pig"

Resources are written to <name>.csv_res beside the CSV, with their folder structure, so src="../audio/word.mp3" still resolves. A resource name that is invalid on the file system is normalized; a resource that cannot be normalized or read is reported and skipped.

An MDX @@@LINK redirect is written as its own row pointing at entry://target when dumping the dictionary file, and as an alternative headword of the target when dumping the library folder. pyglossary accepts both.

wudict markdown¶

dictshelf dump -format md -o ~/exports ~/Dictionaries/Oxford.mdx
dictshelf dump -format md -mode clean -compress gz -o ~/exports ~/Dictionaries/Oxford.mdx

Writes <outdir>/<name>.wudict.md (wudict markdown), resources in <name>.wudict.files.

Both formats¶

dump asks before overwriting an existing output folder. Files left there by an earlier dump under other names are not deleted. The library's SQLite schema is documented in The text.db format.

ingest¶

dictshelf ingest [-full] [-fulltext] [-contains] [<dictfile|folder> …]

Indexes dictionaries into <DB_DIR>/<name>/ (text.db, info.txt). Without a path, the dictionary folders (DICT_DIR); with a folder, everything in it. Dictionaries already indexed are skipped.

A flag left out keeps what each dictionary has.

reindex¶

dictshelf reindex [-all] [<name|path> …]

Rebuilds outdated indexes: built by an older version of DictShelf, from dictionary files that changed since, or unreadable. Each dictionary keeps its indexes and media pack. Names limit the rebuild to those dictionaries; -all rebuilds current ones too. A dictionary whose files are gone is reported and kept. While a server uses the library, reindex has the server run the rebuild and shows its progress.

lemmas¶

dictshelf lemmas list                  # installed and available languages
dictshelf lemmas download hu fr pt ru  # install, by code or English name
dictshelf lemmas remove ru             # delete

Lemma files in ~/.dmshlabs/dictshelf/lemmas
1 installed, 24 available

  [x]  en   English          187 kB  ~7 MB RAM  built in
  [ ]  fr   French           661 kB  ~27 MB RAM
  [x]  hu   Hungarian        187 kB  ~5 MB RAM
  [ ]  ru   Russian          1.9 MB  ~63 MB RAM
  ...

  dictshelf lemmas download ru sk    install       [x] ready   [ ] not installed
  dictshelf lemmas remove sk         delete        [!] installed, differs from the catalogue

The RAM column is the memory a language uses while loaded; at most MORPH_CACHE languages are loaded, and only when a search needs them.

download accepts codes or English names (ru, russian) and checks every argument before downloading, so one invalid name fails the whole command. -all installs every language; -f downloads a language again although it is current. Each file is checked against its SHA-256 digest in the catalogue and written atomically. Files go to LEMMA_DIR; the catalogue is LEMMA_URL, which may be a local manifest.json. list works offline and reports why the catalogue could not be read.

A running server reads languages installed this way after a restart. The Lemmatization page (☰ → folder summary → Lemmatization…) installs from the same catalogue without a restart, and is the only way on Android.

clean¶

dictshelf clean                # list
dictshelf clean -f             # delete broken library folders
dictshelf clean -f -orphans    # and orphans

Lists incomplete or unreadable library folders, interrupted indexing, and leftovers of an older library layout; -f deletes them. Also lists orphans, library folders whose dictionary files are gone; -f -orphans deletes those too. A dictionary moved within the dictionary folders is not an orphan: its library folder is linked to the new location. A library folder kept with dictionary files only or rm -keep-index is not listed.

rm¶

dictshelf rm [-f] [-keep-source | -keep-index] <name|path>

Removes one dictionary: its library folder and its dictionary files. The argument is a library name, a library folder, a text.db, or a dictionary file.

After -keep-source, a dictionary still in a dictionary folder is indexed again on its next search.

token¶

dictshelf token           # print the link that carries the access key
dictshelf token -rotate   # replace the key

A browser on another device opens the link once when the server listens on the network. After -rotate, every browser and script holding the old key needs the new link. See AUTH.

licenses¶

Prints the program's licence and the notices for the third-party code built into it.

Examples¶

dictshelf --dict-dir ~/Books/Dicts --port 9090 --no-browser
dictshelf lookup ~/Dictionaries/Oxford.mdx serendipity
dictshelf ingest -full ~/Dictionaries/Oxford.mdx
SERVER_PORT=9000 dictshelf