dry-cli-help 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8756ab593e09c6cdc0e0ab32fe6f3909d05625734a07e7d7c334e3d832ba70ac
-  data.tar.gz: 4477df389d4c4c0d984fe4024f768adf3e254772464694f7acd81609936060a4
+  metadata.gz: 603fe4d7d4f905ffd720b33ce12f7847ce9d61658935a68609444ea35de0afed
+  data.tar.gz: 5ba0fe8b6319be69b6308f4613afbbaf56b818fdbed8ff1844b790e83d47cb74
 SHA512:
-  metadata.gz: 6a61174289b02e6a523ba5ccdae1a79cd72241ea7c5bb16de5d543e3aad488a3de9d973644a0297c2c94e0516475241c490470f5d52208f450d7efc243dfd575
-  data.tar.gz: 041553f6adda56086400f208d6bef2ce77613e635581e871ffc58488a3ead1cca4038c3ce4d89f39e79049f529ffaa7cb013dea09bea8701e9c7b5c78ea1d3eb
+  metadata.gz: cf16c7662f59e52d41f97569be72627dd946af8f0e13f19563f202daa6576895c3d594e5114ab2980830f2b0943b47bd6a1c17b8a45ae121e7f62673b8b594a5
+  data.tar.gz: 268c5be6c337e75f509e557d85e5e78ac9e72799b8fbca949ec729a3e8c34dc05e129e97c5f4eb8c37e7d8a7c769347d13e67f5b82b7a30a283e37b290320444

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+- Every setting is made once, in `Dry::CLI::Help.configure`, which now also accepts a block without an argument and runs it against the configuration. The `help` block on registries is removed, along with `Help.config_for` and `Configuration#merge`: the gem adds nothing to dry-cli's registry or command DSL.
+- A `styles` block declares every element's look in one place, replacing `style(element, *names)`. New elements `usage`, `example` and `example_comment`; `comment` is renamed `example_comment` and defaults to bold black.
+- Heading case moves into the heading style: `styles { heading :bold, case: :Capitalize }`, one of `:UPPERCASE`, `:Capitalize`, `:lowercase` or `:as_is`. The `heading_case` setting is removed.
+- `examples/` holds three single-file dry-cli tools that switch this gem on with `--with-dry-cli-help` or `-w`.
+
 ## [0.1.0] - 2026-09-12
 
 - Initial release as `dry-cli-help`, converted from `dry-cli-autocomplete`. The shell completion generator is removed; that gem remains the place for it.

data/README.md

@@ -11,14 +11,14 @@ dry-cli prints help as it finds it: no title, no description of the program, no
 
 ## Before and after
 
-`taxlibris compile -h` with dry-cli alone:
+`my-cli compile -h` with dry-cli alone:
 
 ```text
 Command:
-  taxlibris compile
+  my-cli compile
 
 Usage:
-  taxlibris compile RULES [OUTPUT]
+  my-cli compile RULES [OUTPUT]
 
 Description:
   Compile tax rules
@@ -37,7 +37,7 @@ With `require "dry/cli/help"`:
 
 ```text
 USAGE
-  taxlibris compile RULES [OUTPUT] [OPTIONS]
+  my-cli compile RULES [OUTPUT] [OPTIONS]
 
 DESCRIPTION
   Compile tax rules
@@ -54,6 +54,13 @@ OPTIONS
 
 Headings are bold and yellow, commands green, options and arguments cyan, and every description wraps to the terminal with a hanging indent.
 
+Although, it is best to show them side by side as a screenshot: this script `rbcheck` is in the `examples` folder of the gem.
+
+| Standard dry-cli Help Screen                    | Require `dry/cli/help`                   |
+| :---------------------------------------------- | :--------------------------------------- |
+| ![original](docs/img/without-dry-cli-help.avif) | ![with](docs/img/with-dry-cli-help.avif) |
+|                                                 |                                          |
+
 ## Installation
 
 ```bash
@@ -71,26 +78,26 @@ require "dry/cli"
 require "dry/cli/help"
 ```
 
-Describe the program in the registry:
+Then make every setting once, in one block, before the CLI runs. Your registry, commands and options stay plain dry-cli: the gem adds nothing to them, so you can add or remove it without touching a command.
 
 ```ruby
-module Taxlibris
-  module CLI
-    extend Dry::CLI::Registry
+Dry::CLI::Help.configure do
+  title "MyCLI"
 
-    help do
-      title "Taxlibris"
+  description <<~TEXT
+    This utility does something very important.
+  TEXT
 
-      description <<~TEXT
-        Compile, validate, and evaluate tax rules.
-      TEXT
+  epilogue "Documentation: https://example.com/my-cli"
 
-      epilogue "Documentation: https://example.com/taxlibris"
+  color :auto
+  width :terminal
+  wrap true
+end
 
-      color :auto
-      width :terminal
-      wrap true
-    end
+module My
+  module CLI
+    extend Dry::CLI::Registry
 
     register "compile", Compile
     register "validate", Validate
@@ -100,15 +107,15 @@ module Taxlibris
 end
 ```
 
-`taxlibris -h` then prints:
+`my-cli -h` then prints:
 
 ```text
-Taxlibris
+MyCLI
 
-Compile, validate, and evaluate tax rules.
+Compile, validate, and evaluate rules.
 
 USAGE
-  taxlibris COMMAND [OPTIONS]
+  my-cli COMMAND [OPTIONS]
 
 COMMANDS
   compile        Compile tax rules
@@ -120,12 +127,12 @@ OPTIONS
   -h, --help     Show help
   -v, --version  Show version
 
-Documentation: https://example.com/taxlibris
+Documentation: https://example.com/my-cli
 ```
 
 A command reachable as `--version` lists under Options by its dashed names.
 
-Settings for the whole process go through `configure`. A registry's `help` block overrides them:
+A block that takes an argument receives the configuration instead of running against it:
 
 ```ruby
 Dry::CLI::Help.configure do |config|
@@ -134,23 +141,177 @@ Dry::CLI::Help.configure do |config|
 end
 ```
 
-A `help` block that takes an argument receives the configuration instead, so `help { |h| h.title = "Taxlibris" }` works too.
+## Examples
+
+The [`examples`](examples) folder holds three single-file tools built on dry-cli. Each one loads and configures this gem only when you pass `--with-dry-cli-help`, or `-w` for short, so you can run the same command both ways and compare:
+
+```bash
+examples/rbcheck -h                      # dry-cli's own help
+examples/rbcheck -h --with-dry-cli-help  # the same help, through this gem
+```
+
+`examples/rbcheck` has two commands, `version` and `check-ruby-syntax [DIR]`. Condensed:
+
+```ruby
+#!/usr/bin/env ruby
+require "dry/cli"
+
+if [ARGV.delete("--with-dry-cli-help"), ARGV.delete("-w")].any?
+  require "dry/cli/help"
+
+  Dry::CLI::Help.configure do
+    title "RBCheck"
+    description "Small checks for Ruby projects."
+    epilogue "Report bugs at https://example.com/rbcheck/issues"
+  end
+end
+
+module Rbcheck
+  extend Dry::CLI::Registry
+
+  class Version < Dry::CLI::Command
+    desc "Print the version"
+
+    def call(**) = puts("rbcheck 1.0.0")
+  end
+
+  class CheckRubySyntax < Dry::CLI::Command
+    desc "Check every Ruby file under a directory for syntax errors, and report "\
+         "each file that fails to parse with its line number"
+
+    argument :dir, desc: "Directory to scan", default: "."
+    option :exclude, type: :array, desc: "Glob patterns to skip, such as vendor/**"
+    option :quiet, type: :boolean, default: false, aliases: ["-q"],
+           desc: "Print only the files that fail"
+
+    example ["lib # check one directory", "--exclude=vendor/** # skip vendored gems"]
+
+    def call(dir:, quiet:, exclude: [], **)
+      # ... parses every file under dir with Prism ...
+    end
+  end
+
+  register "version", Version, aliases: ["--version", "-v"]
+  register "check-ruby-syntax", CheckRubySyntax
+end
+
+Dry::CLI.new(Rbcheck).call
+```
+
+Every screen below comes from running it in an 80-column terminal.
+
+### `rbcheck -h`
+
+dry-cli alone prints a list of commands and exits 1. Also note the lack of wrapping on the long description.
+
+```text
+Commands:
+  rbcheck check-ruby-syntax [DIR]                 # Check every Ruby file under a directory for syntax errors, and report each file that fails to parse with its line number
+  rbcheck version                                 # Print the version
+```
+
+With this gem in play it exits 0 and prints:
+
+```text
+RB	check
+
+Small checks for Ruby projects.
+
+USAGE
+  rbcheck COMMAND [OPTIONS]
+
+COMMANDS
+  version            Print the version
+  check-ruby-syntax  Check every Ruby file under a directory for syntax errors,
+                     and report each file that fails to parse with its line
+                     number
+
+OPTIONS
+  -h, --help         Show help
+  -v, --version      Print the version
+
+Report bugs at https://example.com/rbcheck/issues
+```
+
+- The title, description and epilogue come from the `configure` block.
+- Commands list in the order they were registered, not alphabetically.
+- The long description wraps to the terminal under its own column.
+- `version` is also reachable as `--version` and `-v`, so it lists under Options too. dry-cli never shows those aliases.
+
+### `rbcheck check-ruby-syntax -h`
+
+dry-cli alone:
+
+```text
+Command:
+  rbcheck check-ruby-syntax
+
+Usage:
+  rbcheck check-ruby-syntax [DIR]
+
+Description:
+  Check every Ruby file under a directory for syntax errors, and report each file that fails to parse with its line number
+
+Arguments:
+  DIR                               # Directory to scan
+
+Options:
+  --exclude=VALUE1,VALUE2,..        # Glob patterns to skip, such as vendor/**
+  --[no-]quiet, -q                  # Print only the files that fail, default: false
+  --help, -h                        # Print this help
+
+Examples:
+  rbcheck check-ruby-syntax lib # check one directory
+  rbcheck check-ruby-syntax --exclude=vendor/** # skip vendored gems
+```
+
+With this gem:
+
+```text
+USAGE
+  rbcheck check-ruby-syntax [DIR] [OPTIONS]
+
+DESCRIPTION
+  Check every Ruby file under a directory for syntax errors, and report each
+  file that fails to parse with its line number
+
+ARGUMENTS
+  DIR                         Directory to scan (default: ".")
+
+OPTIONS
+  --exclude=VALUE1,VALUE2,..  Glob patterns to skip, such as vendor/**
+  -q, --[no-]quiet            Print only the files that fail (default: false)
+  -h, --help                  Show help
+
+EXAMPLES
+  rbcheck check-ruby-syntax lib             check one directory
+  rbcheck check-ruby-syntax --exclude=vendor/**
+                                            skip vendored gems
+```
+
+- The `Command:` section repeats the usage line, so it is gone, and the usage line shows that the command takes options.
+- The argument's default of `"."` shows up; dry-cli leaves it out.
+- Short aliases come first (`-q, --[no-]quiet`), and every description lines up in one column instead of trailing a `#`.
+- Each example's comment moves into a column of its own. An example longer than that column puts its comment on the next line.
+
+In a terminal the headings print bold yellow, usage lines, commands and examples green, arguments and options cyan, and example comments bold black.
+
+`examples/todo` shows nested commands, custom headings and a `styles` block. `examples/deploy` shows a fixed width, a banner above command help, reordered sections and help without a command exiting 0. [`examples/README.md`](examples/README.md) lists what each one demonstrates.
 
 ## Settings
 
-| Setting                       | Values                            | Default         |
-| ----------------------------- | --------------------------------- | --------------- |
-| `title`                       | String                            | none            |
-| `description`                 | String                            | none            |
-| `epilogue`                    | String                            | none            |
-| `color`                       | `true`, `false`, `:auto`          | `:auto`         |
-| `wrap`                        | `true`, `false`                   | `true`          |
-| `width`                       | `:terminal`, Integer              | `:terminal`     |
-| `margin`                      | Integer                           | `0`             |
-| `exit_code_without_arguments` | 0 to 255                          | `1`             |
-| `banner_on_subcommands`       | `true`, `false`                   | `false`         |
-| `heading_case`                | `:upcase`, `:capitalize`, `:none` | `:upcase`       |
-| `command_order`               | `:registration`, `:alphabetical`  | `:registration` |
+| Setting                       | Values                           | Default         | What it does                                                                                                              |
+| ----------------------------- | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `title`                       | String                           | none            | Prints a bold first line at the top of the top-level help                                                                 |
+| `description`                 | String                           | none            | Prints paragraphs under the title, reflowed to the wrap width                                                             |
+| `epilogue`                    | String                           | none            | Prints paragraphs at the very end of the top-level help                                                                   |
+| `color`                       | `true`, `false`, `:auto`         | `:auto`         | Paints headings, commands, arguments and options; `:auto` paints only a terminal                                          |
+| `wrap`                        | `true`, `false`                  | `true`          | Wraps descriptions with a hanging indent; `false` prints each one on a single line as written                             |
+| `width`                       | `:terminal`, Integer             | `:terminal`     | Sets the column text wraps at; `:terminal` follows the terminal's width                                                   |
+| `margin`                      | Integer                          | `0`             | Keeps that many columns free at the right edge when `width` is `:terminal`                                                |
+| `exit_code_without_arguments` | 0 to 255                         | `1`             | Sets the exit status of `my-cli` or `my-cli db` run with no command; `0` also prints the help to stdout instead of stderr |
+| `banner_on_subcommands`       | `true`, `false`                  | `false`         | Prints the title and description above command help and group listings too, not only above the top-level help             |
+| `command_order`               | `:registration`, `:alphabetical` | `:registration` | Lists commands in the order you registered them, or sorted by name as dry-cli does                                        |
 
 `color :auto` colors a terminal and honors [`NO_COLOR`](https://no-color.org). `width :terminal` reads `COLUMNS`, then the console, then falls back to 80, and `margin` keeps columns free at the right edge.
 
@@ -159,9 +320,8 @@ Running the program with no command prints the top-level help and exits 1, as dr
 ### Headings, sections and groups
 
 ```ruby
-help do
+Dry::CLI::Help.configure do
   heading :commands, "Available commands"
-  heading_case :capitalize
 
   group "Rules", "compile", "validate"
   group "Returns", "evaluate"
@@ -171,7 +331,7 @@ help do
 end
 ```
 
-- `heading` replaces one section's heading text.
+- `heading` replaces one section's heading text. How headings are cased belongs to their style, below.
 - `group` lists commands under a heading of their own, in the order given. Ungrouped commands stay under Commands. A group inside a group names the full path, such as `"db migrate"`.
 - `sections` sets the order; a section left out is hidden. `hide` hides sections without restating the order.
 
@@ -179,14 +339,37 @@ The sections are `banner`, `usage`, `description`, `commands`, `subcommands`, `a
 
 ### Styles
 
+Every element's look is declared together, in one `styles` block inside `configure`:
+
 ```ruby
-help do
-  style :heading, :bold, :bright_blue
-  style :comment            # no styles: print it plain
+Dry::CLI::Help.configure do
+  styles do
+    title           :bold
+    heading         :bold, :yellow, case: :UPPERCASE
+    usage           :green
+    command         :green
+    argument        :cyan
+    option          :cyan
+    example         :green
+    example_comment :bold, :black
+  end
 end
 ```
 
-The styled elements are `title`, `heading`, `command`, `argument`, `option` and `comment`, the last being the part of an example after the first `#` surrounded by spaces, as in `"rules.form # compile one file"`.
+Those are the defaults. Name only the elements you want to change; a line with no styles, such as `example_comment`, prints that element plain.
+
+| Element           | Applies to                                                                                           |
+| ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `title`           | The banner title                                                                                     |
+| `heading`         | Every section and group heading                                                                      |
+| `usage`           | Every usage line, whole                                                                              |
+| `command`         | Command names in a list                                                                              |
+| `argument`        | Argument names                                                                                       |
+| `option`          | Option names                                                                                         |
+| `example`         | The command line of an example                                                                       |
+| `example_comment` | The part of an example after the first `#` surrounded by spaces, as in `"lib # check one directory"` |
+
+`heading` alone takes `case:`, one of `:UPPERCASE`, `:Capitalize`, `:lowercase` or `:as_is`, each written the way it cases. `:Capitalize` raises only the first letter. `heading case: :as_is` with no styles changes the case and keeps the colors.
 
 ### The Colors module
 
@@ -210,16 +393,26 @@ The methods are the eight colors `black red green yellow blue magenta cyan white
 The gem prepends one module to `Dry::CLI`, overriding the two private methods dry-cli prints help from. It does not replace `Dry::CLI::Banner` or `Dry::CLI::Usage`.
 
 ```mermaid
-flowchart LR
-  argv[ARGV] --> call["Dry::CLI#call"]
-  call -->|"command found, -h given"| help["#help"]
-  call -->|"no command, a group, -h at a level, a typo"| spell["#spell_checker"]
-  help --> command[Screens::Command]
-  spell --> listing[Screens::Listing]
-  command --> formatter[Formatter]
-  listing --> formatter
-  config["Help.configure + registry help block"] --> formatter
-  formatter --> out[stdout or stderr]
+---
+config:
+  layout: elk
+  theme: forest
+---
+flowchart TB
+    argv["ARGV"] --> cli_call["Dry::CLI#call"]
+
+    cli_call -->|"command found, --help given"| help_method["#help"]
+    cli_call -->|"no command, a group, -h at a level, a typo"| spell_checker["#spell_checker"]
+
+    help_method --> command_screen["Screens::Command"]
+    spell_checker --> listing_screen["Screens::Listing"]
+
+    command_screen --> formatter["Formatter"]
+    listing_screen --> formatter
+
+    help_config["Help.configure + registry help block"] --> formatter
+
+    formatter --> output["stdout or stderr"]
 ```
 
 Both methods are `@api private` in dry-cli. `spec/dry/cli/help/dry_cli_contract_spec.rb` asserts every internal the gem reads, so a dry-cli release that moves one fails this suite, naming what moved.

data/SPECIFICATION.md

@@ -27,46 +27,46 @@ It does not replace `dry-cli` or introduce another command framework. It takes t
 
 ## Example
 
+Every setting is made once, in one block, before any CLI runs. The registry, its commands and their options stay exactly as dry-cli declares them:
+
 ```ruby
 require "dry/cli"
 require "dry/cli/help"
 
-Dry::CLI::Help.configure do |config|
-  config.width = :terminal
-  config.wrap = true
-  config.color = true
-end
-```
+Dry::CLI::Help.configure do
+  title "MyCLI"
 
-An application could provide richer top-level help:
+  description <<~TEXT
+    Compile, validate, and evaluate tax rules.
+  TEXT
 
-```ruby
-class CLI
-  extend Dry::CLI::Registry
+  color :auto
+  width :terminal
 
-  help do
-    title "Taxlibris"
+  styles do
+    heading :bold, :yellow, case: :UPPERCASE
+    example_comment :bold, :black
+  end
+end
 
-    description <<~TEXT
-      Compile, validate, and evaluate tax rules.
-    TEXT
+module CLI
+  extend Dry::CLI::Registry # plain dry-cli, nothing added
 
-    color true
-    width :terminal
-    wrap true
-  end
+  register "compile", Compile
+  register "validate", Validate
+  register "evaluate", Evaluate
 end
 ```
 
 Result:
 
 ```text
-Taxlibris
+MyCLI
 
 Compile, validate, and evaluate tax rules.
 
 USAGE
-  taxlibris COMMAND [OPTIONS]
+  my-cli COMMAND [OPTIONS]
 
 COMMANDS
   compile       Compile tax rules
@@ -125,32 +125,31 @@ Requiring `dry/cli/help` changes help output for every `Dry::CLI` in the process
 
 Both are `@api private` in dry-cli 1.4.1. A spec asserts they exist, so a dry-cli release that renames them fails this gem's suite rather than a host's help screen. `Dry::CLI::Help::Integration` holds the override.
 
-`help` is added to `Dry::CLI::Registry`, so any module or class that extends a registry can call it.
+The gem adds nothing to `Dry::CLI::Registry` or `Dry::CLI::Command`. The DSL a host uses to declare commands, arguments, options and examples is dry-cli's, unchanged, so adding or removing this gem never touches a command definition.
 
 ### Configuration
 
-Two levels, one vocabulary. `Dry::CLI::Help.configure` sets process-wide values. A registry's `help` block overrides them for that registry. A setting neither level sets takes the default below.
-
-Every setting reads and writes both ways: `title "Taxlibris"` inside a `help` block, and `config.title = "Taxlibris"` on the yielded object. A `help` block taking one argument receives the configuration instead of being evaluated against it.
-
-| Setting                       | Values                               | Default         | Effect                                                                 |
-| ----------------------------- | ------------------------------------ | --------------- | ---------------------------------------------------------------------- |
-| `title`                       | String                               | none            | First line of the banner                                               |
-| `description`                 | String                               | none            | Paragraphs under the title, wrapped                                    |
-| `epilogue`                    | String                               | none            | Paragraphs at the end of the top-level help                            |
-| `color`                       | `true`, `false`, `:auto`             | `:auto`         | `:auto` colors a terminal and honors `NO_COLOR`                        |
-| `wrap`                        | `true`, `false`                      | `true`          | `false` prints descriptions as written                                 |
-| `width`                       | `:terminal`, Integer                 | `:terminal`     | The column text wraps at                                               |
-| `margin`                      | Integer                              | `0`             | Columns kept free at the right edge when `width` is `:terminal`        |
-| `exit_code_without_arguments` | Integer, 0 to 255                    | `1`             | Status for `mycli` or `mycli group` with no command                    |
-| `banner_on_subcommands`       | `true`, `false`                      | `false`         | Print the title and description above `mycli command -h`               |
-| `heading_case`                | `:upcase`, `:capitalize`, `:none`    | `:upcase`       | How every heading is cased; `:capitalize` raises only the first letter |
-| `command_order`               | `:registration`, `:alphabetical`     | `:registration` | Order commands list in; dry-cli sorts alphabetically                   |
-| `heading(section, text)`      | Section name, String                 | see below       | Replaces one heading's text                                            |
-| `style(element, *styles)`     | Element name, `Colors::STYLES` names | see below       | Replaces one element's styles                                          |
-| `group(name, *commands)`      | String, command paths                | none            | Lists those commands under their own heading, in declaration order     |
-| `sections(*names)`            | Section names                        | all             | Order of sections; a section left out is hidden                        |
-| `hide(*names)`                | Section names                        | none            | Hides sections without restating the order                             |
+One place. `Dry::CLI::Help.configure` holds every setting for the process, and every CLI in the process renders with it. A setting it leaves alone takes the default below.
+
+The block reads and writes both ways: `title "MyCLI"` when the block takes no argument and runs against the configuration, and `config.title = "MyCLI"` when it takes one and receives it.
+
+| Setting                       | Values                           | Default         | Effect                                                             |
+| ----------------------------- | -------------------------------- | --------------- | ------------------------------------------------------------------ |
+| `title`                       | String                           | none            | First line of the banner                                           |
+| `description`                 | String                           | none            | Paragraphs under the title, wrapped                                |
+| `epilogue`                    | String                           | none            | Paragraphs at the end of the top-level help                        |
+| `color`                       | `true`, `false`, `:auto`         | `:auto`         | `:auto` colors a terminal and honors `NO_COLOR`                    |
+| `wrap`                        | `true`, `false`                  | `true`          | `false` prints descriptions as written                             |
+| `width`                       | `:terminal`, Integer             | `:terminal`     | The column text wraps at                                           |
+| `margin`                      | Integer                          | `0`             | Columns kept free at the right edge when `width` is `:terminal`    |
+| `exit_code_without_arguments` | Integer, 0 to 255                | `1`             | Status for `mycli` or `mycli group` with no command                |
+| `banner_on_subcommands`       | `true`, `false`                  | `false`         | Print the title and description above `mycli command -h`           |
+| `command_order`               | `:registration`, `:alphabetical` | `:registration` | Order commands list in; dry-cli sorts alphabetically               |
+| `heading(section, text)`      | Section name, String             | see below       | Replaces one heading's text                                        |
+| `styles { ... }`              | One line per element             | see below       | Declares how every element looks, and how headings are cased       |
+| `group(name, *commands)`      | String, command paths            | none            | Lists those commands under their own heading, in declaration order |
+| `sections(*names)`            | Section names                    | all             | Order of sections; a section left out is hidden                    |
+| `hide(*names)`                | Section names                    | none            | Hides sections without restating the order                         |
 
 Terminal width comes from `COLUMNS`, then the console, then 80. A resolved wrap width never falls below 20 columns.
 
@@ -170,7 +169,7 @@ In default order, with default headings:
 | `examples`    | Examples    | no             | yes                                 |
 | `epilogue`    | none        | yes            | only for a single command           |
 
-A single command passed to `Dry::CLI.new(SomeCommand)` is the whole program, so its command help prints the banner and the epilogue too. It has no registry, so it renders with the process-wide settings alone.
+A single command passed to `Dry::CLI.new(SomeCommand)` is the whole program, so its command help prints the banner and the epilogue too.
 
 A group listing, `mycli db` where `db` has no command of its own, renders as top-level help scoped to the group, with the banner only when `banner_on_subcommands` is set, and no epilogue.
 
@@ -178,16 +177,30 @@ Every Options section starts with `-h, --help  Show help`, because both spelling
 
 At any level, a command registered under a name or alias starting with `-`, such as `register "version", Version, aliases: ["--version"]`, lists under Options rather than Commands.
 
-### Styled elements
+### Styles
+
+Every element's look is declared in one `styles` block inside `configure`. Each line names an element and its styles, from `Colors::STYLES`. An element left out keeps its default; a line with no styles prints the element plain.
+
+```ruby
+styles do
+  heading :bold, :blue, case: :Capitalize
+  example :yellow
+  example_comment # plain
+end
+```
 
-| Element    | Default styles   | Applies to                             |
-| ---------- | ---------------- | -------------------------------------- |
-| `title`    | `bold`           | The banner title                       |
-| `heading`  | `bold`, `yellow` | Every section heading                  |
-| `command`  | `green`          | Command names and the program in usage |
-| `argument` | `cyan`           | Argument names                         |
-| `option`   | `cyan`           | Option names                           |
-| `comment`  | `bright_black`   | The comment half of an example         |
+| Element           | Default styles   | Applies to                                 |
+| ----------------- | ---------------- | ------------------------------------------ |
+| `title`           | `bold`           | The banner title                           |
+| `heading`         | `bold`, `yellow` | Every section and group heading            |
+| `usage`           | `green`          | Every usage line, whole                    |
+| `command`         | `green`          | Command names in a list                    |
+| `argument`        | `cyan`           | Argument names                             |
+| `option`          | `cyan`           | Option names                               |
+| `example`         | `green`          | The command line of an example             |
+| `example_comment` | `bold`, `black`  | The part of an example after the first `#` |
+
+`heading` alone takes `case:`, one of `:UPPERCASE` (the default), `:Capitalize`, `:lowercase` or `:as_is`, each written the way it cases. It applies to every heading. `:Capitalize` raises only the first letter and leaves the rest as written. `heading case: :as_is` with no styles changes the case and keeps the heading's styles.
 
 ### Layout
 

data/lib/dry/cli/help/configuration.rb

@@ -3,19 +3,18 @@
 module Dry
   class CLI
     module Help
-      # Help settings, readable and writable two ways:
+      # Every help setting, made once for the whole process, two ways:
       #
-      #   help do
-      #     title "Taxlibris"            # inside a registry's help block
+      #   Dry::CLI::Help.configure do
+      #     title "MyCLI"            # as a DSL
       #   end
       #
       #   Dry::CLI::Help.configure do |config|
-      #     config.title = "Taxlibris"   # on the yielded object
+      #     config.title = "MyCLI"   # on the yielded object
       #   end
       #
-      # An instance stores only what was set on it. Everything else reads from
-      # {DEFAULTS}, which is what lets a registry's settings sit over the
-      # process-wide ones through {#merge} without either copying the other.
+      # Every element's look is declared in one {#styles} block. Anything not
+      # set reads from {DEFAULTS}, {HEADINGS} or {STYLES}.
       class Configuration
         # Every section, in default order.
         SECTIONS = %i[
@@ -37,13 +36,18 @@ module Dry
         STYLES = {
           title: %i[bold],
           heading: %i[bold yellow],
+          usage: %i[green],
           command: %i[green],
           argument: %i[cyan],
           option: %i[cyan],
-          comment: %i[bright_black]
+          example: %i[green],
+          example_comment: %i[bold black]
         }.freeze
 
-        HEADING_CASES = %i[upcase capitalize none].freeze
+        # How headings can be cased; each name is written the way it cases.
+        # `:Capitalize` raises only the first letter.
+        HEADING_CASES = %i[UPPERCASE Capitalize lowercase as_is].freeze
+        DEFAULT_HEADING_CASE = :UPPERCASE
         COMMAND_ORDERS = %i[registration alphabetical].freeze
 
         # Narrowest column text wraps at, however small the terminal.
@@ -63,7 +67,6 @@ module Dry
           margin: ->(value) { value.is_a?(Integer) && !value.negative? },
           exit_code_without_arguments: ->(value) { value.is_a?(Integer) && value.between?(0, 255) },
           banner_on_subcommands: BOOLEAN,
-          heading_case: ->(value) { HEADING_CASES.include?(value) },
           command_order: ->(value) { COMMAND_ORDERS.include?(value) }
         }.freeze
 
@@ -77,7 +80,6 @@ module Dry
           margin: 0,
           exit_code_without_arguments: 1,
           banner_on_subcommands: false,
-          heading_case: :upcase,
           command_order: :registration
         }.freeze
 
@@ -122,26 +124,36 @@ module Dry
           HEADINGS.merge(@values.fetch(:headings, {}))
         end
 
-        # Replace the styles of one element. No styles prints it plain.
+        # Declare how elements look, all in one place. Each line names an
+        # element from {STYLES} and its styles from {Colors::STYLES}; no styles
+        # prints it plain. Elements left out keep their defaults. `heading` also
+        # takes `case:`, one of {HEADING_CASES}. A block taking an argument
+        # receives the declarations instead.
+        #
+        # @example
+        #   styles do
+        #     heading :bold, :blue, case: :Capitalize
+        #     example_comment              # plain
+        #   end
         #
-        # @param element [Symbol] a key of {STYLES}
-        # @param names [Array<Symbol>] names from {Colors::STYLES}
-        # @return [Array<Symbol>]
-        def style(element, *names)
-          raise ArgumentError, "#{element.inspect} is not a styled element" unless STYLES.key?(element)
-
-          unknown = names - Colors::STYLES
-          raise ArgumentError, "unknown styles: #{unknown.inspect}" unless unknown.empty?
-
-          @values[:styles] = @values.fetch(:styles, {}).merge(element => names.freeze)
-          names
-        end
-
         # @return [Hash{Symbol => Array<Symbol>}] every element's styles
-        def styles
+        def styles(&block)
+          if block
+            sheet = StyleSheet.new
+            block.arity == 1 ? yield(sheet) : sheet.instance_eval(&block)
+            @values[:styles] = @values.fetch(:styles, {}).merge(sheet.styles)
+            @values[:heading_case] = sheet.heading_case if sheet.heading_case
+          end
           STYLES.merge(@values.fetch(:styles, {}))
         end
 
+        # How every heading is cased, set by `heading ..., case:` in {#styles}.
+        #
+        # @return [Symbol] one of {HEADING_CASES}
+        def heading_case
+          @values.fetch(:heading_case, DEFAULT_HEADING_CASE)
+        end
+
         # List commands under a heading of their own, in the order given.
         # Groups print in the order they are declared, after ungrouped commands.
         #
@@ -206,27 +218,6 @@ module Dry
           [columns, MIN_WIDTH].max
         end
 
-        # These settings with another instance's laid over them. Headings and
-        # styles merge key by key, hidden sections add up, and any other setting
-        # the other instance made replaces this one's.
-        #
-        # @param other [Configuration]
-        # @return [Configuration] a new instance
-        def merge(other)
-          combined = @values.merge(other.values) do |key, mine, theirs|
-            case key
-            when :headings, :styles then mine.merge(theirs)
-            when :hidden then mine | theirs
-            else theirs
-            end
-          end
-          self.class.new(combined)
-        end
-
-        protected
-
-        attr_reader :values
-
         private
 
         def validate_sections(names)
@@ -235,6 +226,48 @@ module Dry
 
           names.freeze
         end
+
+        # What a {Configuration#styles} block runs against: one method per
+        # element, each validating what it is given.
+        class StyleSheet
+          # @return [Hash{Symbol => Array<Symbol>}] the elements declared
+          attr_reader :styles
+
+          # @return [Symbol, nil] the heading case, when declared
+          attr_reader :heading_case
+
+          def initialize
+            @styles = {}
+          end
+
+          STYLES.each_key do |element|
+            define_method(element) do |*names, **options|
+              declare(element, names.flatten, options)
+            end
+          end
+
+          private
+
+          def declare(element, names, options)
+            unknown = names - Colors::STYLES
+            raise ArgumentError, "unknown styles for #{element}: #{unknown.inspect}" unless unknown.empty?
+
+            @heading_case = letter_case(element, options) unless options.empty?
+            # `heading case: :as_is` alone changes the case and keeps the styles.
+            @styles[element] = names.freeze unless names.empty? && !options.empty?
+          end
+
+          def letter_case(element, options)
+            unless element == :heading && options.keys == [:case]
+              raise ArgumentError, "#{element} takes no #{options.keys.map { "#{it}:" }.join(', ')}"
+            end
+
+            value = options.fetch(:case)
+            return value if HEADING_CASES.include?(value)
+
+            raise ArgumentError, "case cannot be #{value.inspect}; use one of #{HEADING_CASES.inspect}"
+          end
+        end
       end
     end
   end

data/lib/dry/cli/help/formatter.rb

@@ -49,12 +49,15 @@ module Dry
           title(config.headings.fetch(section))
         end
 
-        # A heading with the configured case and style, for any text.
+        # A heading in the configured case and style, for any text.
+        #
+        # @param text [String]
         # @return [String]
         def title(text)
           cased = case config.heading_case
-                  when :upcase then text.upcase
-                  when :capitalize then text.sub(/\A\p{Ll}/, &:upcase)
+                  when :UPPERCASE then text.upcase
+                  when :lowercase then text.downcase
+                  when :Capitalize then text.sub(/\A\p{Ll}/, &:upcase)
                   else text
                   end
           paint(cased, :heading)

data/lib/dry/cli/help/integration.rb

@@ -20,7 +20,7 @@ module Dry
           def help(command, prog_name)
             screen = Screens::Command.new(
               command:, prog_name:, top_level: !kommand.nil?,
-              config: Help.config_for(registry), io: out
+              config: Help.config, io: out
             )
             out.puts screen.render
             exit(0)
@@ -30,7 +30,7 @@ module Dry
           # all, a group without a command of its own, `-h` or `--help` at a
           # registry level, or a typo.
           def spell_checker(result, arguments)
-            config = Help.config_for(registry)
+            config = Help.config
             unmatched = arguments.drop(result.names.length)
 
             if unmatched.empty?
@@ -50,34 +50,6 @@ module Dry
             exit(status)
           end
         end
-
-        # Included into Dry::CLI::Registry, so every registry can describe itself.
-        module RegistryMethods
-          # Configure this registry's help. A block taking an argument receives
-          # the configuration; any other block runs against it.
-          #
-          # @example
-          #   help do
-          #     title "Taxlibris"
-          #     width 100
-          #   end
-          #
-          # @return [Configuration] this registry's settings
-          def help(&block)
-            @help_config ||= Configuration.new
-            if block&.arity == 1
-              yield @help_config
-            elsif block
-              @help_config.instance_eval(&block)
-            end
-            @help_config
-          end
-
-          # @return [Configuration, nil] nil until {#help} is called
-          def help_config
-            @help_config
-          end
-        end
       end
     end
   end

data/lib/dry/cli/help/screens/command.rb

@@ -32,10 +32,9 @@ module Dry
           end
 
           def render_usage
-            program = format.paint(prog_name, :command)
-            lines = ["#{INDENT}#{program}#{usage_arguments} [OPTIONS]"]
-            lines << "#{INDENT}#{program} COMMAND [OPTIONS]" if subcommand_rows.any?
-            section(:usage, lines)
+            lines = ["#{prog_name}#{usage_arguments} [OPTIONS]"]
+            lines << "#{prog_name} COMMAND [OPTIONS]" if subcommand_rows.any?
+            section(:usage, lines.map { INDENT + format.paint(it, :usage) })
           end
 
           def render_description
@@ -59,7 +58,8 @@ module Dry
           def render_examples
             rows = command.examples.map do |example|
               line, comment = example.split(" # ", 2)
-              Row.new(term: "#{prog_name} #{line.strip}", text: comment&.strip, text_style: :comment)
+              Row.new(term: "#{prog_name} #{line.strip}", text: comment&.strip,
+                      term_style: :example, text_style: :example_comment)
             end
             section(:examples, format.definitions(rows, format.column_for(rows)))
           end
@@ -72,7 +72,7 @@ module Dry
             required = command.required_arguments.map { argument_name(it) }
             optional = command.optional_arguments.map { "[#{argument_name(it)}]" }
             names = [*required, *optional]
-            " #{format.paint(names.join(' '), :argument)}" unless names.empty?
+            " #{names.join(' ')}" unless names.empty?
           end
 
           def subcommand_rows

data/lib/dry/cli/help/screens/listing.rb

@@ -32,8 +32,8 @@ module Dry
           end
 
           def render_usage
-            program = format.paint(ProgramName.call(result.names), :command)
-            section(:usage, ["#{INDENT}#{program} COMMAND [OPTIONS]"])
+            usage = format.paint("#{ProgramName.call(result.names)} COMMAND [OPTIONS]", :usage)
+            section(:usage, ["#{INDENT}#{usage}"])
           end
 
           def render_commands

data/lib/dry/cli/help/version.rb

@@ -9,7 +9,7 @@ module Dry
   # inherits from Object, so an empty reopening is compatible either way.
   class CLI
     module Help
-      VERSION = "0.1.0"
+      VERSION = "0.2.1"
     end
   end
 end

data/lib/dry/cli/help.rb

@@ -19,14 +19,22 @@ module Dry
     # Configurable, wrapped and colored help screens for dry-cli.
     #
     # Requiring this file changes the help every Dry::CLI in the process prints.
-    # Settings come from {.configure} for the whole process, and from a
-    # registry's `help` block for that registry.
+    # Every setting is made once, in {.configure}, so the way dry-cli declares
+    # registries, commands and options stays exactly as dry-cli ships it.
     module Help
       class << self
-        # @yieldparam config [Configuration] the process-wide settings
+        # Make every setting. A block taking an argument receives the
+        # configuration; any other block runs against it.
+        #
+        # @example
+        #   Dry::CLI::Help.configure do
+        #     title "MyCLI"
+        #     styles { heading :bold, :blue }
+        #   end
+        #
         # @return [Configuration]
-        def configure
-          yield config
+        def configure(&block)
+          block.arity == 1 ? yield(config) : config.instance_eval(&block)
           config
         end
 
@@ -40,21 +48,9 @@ module Dry
         def reset!
           @config = nil
         end
-
-        # The settings a registry renders with: its own `help` block over the
-        # process-wide settings. A single command passed to Dry::CLI.new has no
-        # `help` block, so it renders with the process-wide settings alone.
-        #
-        # @param registry [Module, Class, Dry::CLI::Command, nil]
-        # @return [Configuration]
-        def config_for(registry)
-          own = registry.help_config if registry.respond_to?(:help_config)
-          own ? config.merge(own) : config
-        end
       end
     end
   end
 end
 
 Dry::CLI.prepend(Dry::CLI::Help::Integration::CLIMethods)
-Dry::CLI::Registry.include(Dry::CLI::Help::Integration::RegistryMethods)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dry-cli-help
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Konstantin Gredeskoul