stenodict-cli 0.1.0
Command line tools for building and modifying stenography dictionary files.
Requires Python: >=3.10

# stenodict-cli

Tools for building and modifying stenography dictionary files, with [Plover](https://opensteno.org/plover/)-focused workflows.

## CLI

Install from PyPI:

```bash
pip install stenodict-cli
```

Commands:

- `convert` - Convert Markdown dictionaries to JSON.
- `expand` - Expand a template using entry sources to create a JSON dictionary that contains all combinations.
- `remap` - Remap strokes in JSON dictionaries to exclude strokes that appear in given Markdown dictionaries.
- `merge` - Merge Markdown and JSON dictionaries into one JSON output.

### convert

Converts one or more Markdown sources into JSON.
If `--output` is a `.json` file, all inputs are merged into that file.
If `--output` is a directory, each source is converted to a separate JSON file preserving its relative path.
Use `--exclude` to skip files or folders by regex.

```bash
stenodict convert \
  --input /path/to/md/sources \
  --input /path/to/extra/md \
  --output /path/to/output/json \
  --exclude "modifier-keys" \
  --quiet
```

```bash
stenodict convert \
  --input /path/to/md/sources \
  --output /path/to/output/combined.json
```

#### Input Format

Source files are Markdown documents that contain YAML code blocks:

````markdown
# Navigation

## Navigation Keys

```yaml
-FPL: '{}{#up}' # Up
-RBG: '{}{#down}' # Down
-FR: '{}{#left}' # Left
-LG: '{}{#right}' # Right
```
````

### expand

Expands template entries into a JSON dictionary that contains all combinations.
Each template line defines an outline pattern and translation pattern using `<outline>` and `<translation>` placeholders.
Each entry file provides outline → translation mappings that are substituted into the template to produce final dictionary entries.
If `--output` is a `.json` file, the result is written there.
If `--output` is a directory, the output filename matches the template source filename with a `.json` extension.

Templates and entries are Markdown files that contain YAML code blocks.
You can also pass an inline template string.
See the file format examples below.

```bash
stenodict expand \
  --template /path/to/modifier-keys.md \
  --entries /path/to/entries.md \
  --entries /path/to/extra-entries.md \
  --output /path/to/output/directory/ \
  --quiet
```

```bash
stenodict expand \
  --template /path/to/modifier-keys.md \
  --entries /path/to/entries.md \
  --output /path/to/output/modifier-keys.json
```

```bash
stenodict expand \
  --template "<outline>: '{^}<translation>'" \
  --entries /path/to/entries.md \
  --output /path/to/output/inline.json
```

#### Template Format

Use `<outline>` and `<translation>` placeholders in your template.
Each entry in the entry files supplies both parts and will be expanded into a full stroke/translation pair.

````markdown
# Modifier Keys

```yaml
PWA/<outline>: '{#option(<translation>)}' # Option
KPWA/<outline>: '{#option(control(<translation>))}' # Option+Control
SKPWA/<outline>: '{#option(control(shift(<translation>)))}' # Option+Control+Shift
```
````

#### Entries Format

Entry files are plain YAML mappings from outline to translation.
These are the values substituted into `<outline>` and `<translation>` in the template.

````markdown
# Keys

```yaml
A: '{^}a' # a
TPW-R: '{#F1}' # F1
-FRPB: '{}{#backspace}' # Backspace
K-BG: '{^,}' # Comma
KW-PL: '{?}' # Question Mark (Leading space)
```
````

### remap

Remaps strokes in JSON dictionaries using stroke lists from `.md` files.
`--input` and `--entries` accept a file or directory and can be repeated.
If `--output` is a `.json` file, all inputs are merged into it.
If `--output` is a directory, each input file is written to a corresponding output path.
Use `--exclude` to skip stroke list files by regex.

```bash
stenodict remap \
  --input /path/to/input.json \
  --input /path/to/more/input.json \
  --entries /path/to/remap-md \
  --output /path/to/output.json \
  --quiet
```

#### Remap Entries Format

The remap entries inputs are Markdown documents that contain YAML code blocks.

````markdown
# Keys

## Letters

```yaml
A: '{^}a' # a
AP: '{^}A' # A
-B: '{^}b' # b
P-B: '{^}B' # B
KR: '{^}c' # c
KR-P: '{^}C' # C
```
````

### merge

Merges Markdown and JSON dictionaries into a single JSON output.
Inputs can be `.md` or `.json` files, or directories that contain them.
Use `--exclude` to skip files by regex.
Use `--on-conflict` to control duplicate strokes (`error`, `error-delete-output`, `keep-first`, or `keep-last`).
`error-delete-output` removes the output file before raising.

```bash
stenodict merge \
  --input /path/to/md \
  --input /path/to/dicts.json \
  --output /path/to/merged.json \
  --on-conflict keep-last \
  --quiet
```

## Development

Set up a local environment with uv and run from source:

```bash
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
stenodict --help
```

Install the pre-commit hook and run checks:

```bash
pre-commit install
pre-commit run --all-files
```

## Testing

Run the test suite with pytest:

```bash
pytest
```