Skip to content

feat: adopt docopt-config 0.3.0 - #8

Merged
ralsina merged 4 commits into
mainfrom
docopt-config-0.3.0
Sep 8, 2026
Merged

ralsina merged 4 commits into
mainfrom
docopt-config-0.3.0

Conversation

@ralsina

@ralsina ralsina commented Sep 7, 2026

Copy link
Copy Markdown
Owner

Adopts docopt-config v0.3.0 in all three CLIs (markterm, markmark, markpdf), which shipped several improvements since the v0.2.0 integration.

What we gain

  • --print-config (all three CLIs): dumps the fully-resolved configuration — CLI arguments, environment variables, config file and docopt defaults merged — as YAML that can be saved and used as a config file as is:
    $ markpdf --print-config --style book
    ---
    page_size: a4
    margin: "20"
    style: book
    language: en
    markterm/markmark still require their file argument, so use e.g. markterm --print-config - < document.md.
  • Environment variable type coercion: MARKTERM_HYPHENATE=1 is now a real boolean, and repeatable options accept comma-separated lists (MARKPDF_FONT=a.ttf,b.ttf).
  • Better failure modes: invalid arguments print the message and usage to stderr and exit 1 (v0.2.0 printed the doc and exited 0); a config file that exists but cannot be parsed produces a warning on stderr instead of being silently ignored. Missing config files remain silent.

Adaptation required by this PR

v0.3.0 preserves config-file floats and large integers as Float64/Int64 instead of stringifying them. Cli.option_string now handles all numeric types, so margin: 20.5 keeps working instead of being dropped. Cli.option_flag shrank to value == true since the library now coerces env values itself.

Verification

  • shards build: all four binaries build
  • crystal spec: 231 examples, 0 failures
  • ameba: 0 failures
  • README help blocks verified identical to the actual --help output
  • Smoke-tested: precedence (CLI > env > config > defaults), env bool coercion, env comma-split font lists, fractional margins, broken-config warning, usage-error exit codes, and the --print-config roundtrip (dump → save as config.yml → same effective configuration)

- config floats and large ints now survive (Float64/Int64 arms in
  Cli.option_string), so margin: 20.5 works instead of being dropped
- simplify Cli.option_flag: docopt-config now coerces env var values
  itself (MARKTERM_HYPHENATE=1 is a real boolean, MARKPDF_FONT=a.ttf
  ,b.ttf comma-splits into a list)
- add --print-config to all three CLIs: dumps the fully-resolved
  configuration as YAML that can be saved and used as a config file
- usage errors now print the message and usage to stderr and exit 1
  (0.2.0 exited 0), and unparseable config files warn on stderr
  instead of failing silently
- README: document env var coercion, --print-config and the new
  warning behavior
All three CLIs accept --config <path> (or --config=<path>) to read
options from a specific YAML file instead of the per-tool XDG default.
An explicitly given file must exist; the flag itself only comes from
the command line, and tokens after -- are never taken as --config.
@ralsina
ralsina merged commit f386223 into main Sep 8, 2026
2 checks passed
@ralsina
ralsina deleted the docopt-config-0.3.0 branch September 8, 2026 13:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant