dry-cli-help 0.1.0

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

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module Help
+      # Help settings, readable and writable two ways:
+      #
+      #   help do
+      #     title "Taxlibris"            # inside a registry's help block
+      #   end
+      #
+      #   Dry::CLI::Help.configure do |config|
+      #     config.title = "Taxlibris"   # 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.
+      class Configuration
+        # Every section, in default order.
+        SECTIONS = %i[
+          banner usage description commands subcommands arguments options examples epilogue
+        ].freeze
+
+        # Default heading text. `banner` and `epilogue` print no heading.
+        HEADINGS = {
+          usage: "Usage",
+          description: "Description",
+          commands: "Commands",
+          subcommands: "Subcommands",
+          arguments: "Arguments",
+          options: "Options",
+          examples: "Examples"
+        }.freeze
+
+        # Default styles of every element a screen paints.
+        STYLES = {
+          title: %i[bold],
+          heading: %i[bold yellow],
+          command: %i[green],
+          argument: %i[cyan],
+          option: %i[cyan],
+          comment: %i[bright_black]
+        }.freeze
+
+        HEADING_CASES = %i[upcase capitalize none].freeze
+        COMMAND_ORDERS = %i[registration alphabetical].freeze
+
+        # Narrowest column text wraps at, however small the terminal.
+        MIN_WIDTH = 20
+
+        BOOLEAN = ->(value) { [true, false].include?(value) }
+        TEXT = ->(value) { value.nil? || value.is_a?(String) }
+
+        # Single-value settings and what each accepts.
+        SCALARS = {
+          title: TEXT,
+          description: TEXT,
+          epilogue: TEXT,
+          color: ->(value) { Colors::SETTINGS.include?(value) },
+          wrap: BOOLEAN,
+          width: ->(value) { value == :terminal || (value.is_a?(Integer) && value.positive?) },
+          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
+
+        DEFAULTS = {
+          title: nil,
+          description: nil,
+          epilogue: nil,
+          color: :auto,
+          wrap: true,
+          width: :terminal,
+          margin: 0,
+          exit_code_without_arguments: 1,
+          banner_on_subcommands: false,
+          heading_case: :upcase,
+          command_order: :registration
+        }.freeze
+
+        # Marks a DSL call made without a value, which reads instead of writes.
+        UNSET = Object.new.freeze
+        private_constant :UNSET
+
+        # @param values [Hash] settings made on this instance only
+        def initialize(values = {})
+          @values = values
+        end
+
+        SCALARS.each do |name, valid|
+          define_method(:"#{name}=") do |value|
+            raise ArgumentError, "#{name} cannot be #{value.inspect}" unless valid.call(value)
+
+            @values[name] = value
+          end
+
+          define_method(name) do |value = UNSET|
+            return @values.fetch(name) { DEFAULTS.fetch(name) } if UNSET.equal?(value)
+
+            public_send(:"#{name}=", value)
+          end
+        end
+
+        # Replace the text of one section's heading.
+        #
+        # @param section [Symbol] a key of {HEADINGS}
+        # @param text [String]
+        # @return [String]
+        def heading(section, text)
+          raise ArgumentError, "#{section.inspect} has no heading" unless HEADINGS.key?(section)
+          raise ArgumentError, "a heading must be a String" unless text.is_a?(String)
+
+          @values[:headings] = @values.fetch(:headings, {}).merge(section => text)
+          text
+        end
+
+        # @return [Hash{Symbol => String}] every heading's text, before casing
+        def headings
+          HEADINGS.merge(@values.fetch(:headings, {}))
+        end
+
+        # Replace the styles of one element. No styles prints it plain.
+        #
+        # @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
+          STYLES.merge(@values.fetch(:styles, {}))
+        end
+
+        # List commands under a heading of their own, in the order given.
+        # Groups print in the order they are declared, after ungrouped commands.
+        #
+        # @param name [String] the heading
+        # @param commands [Array<String>] command paths, such as "compile" or "db migrate"
+        # @return [Array<Array(String, Array<String>)>] every group
+        def group(name, *commands)
+          commands = commands.flatten
+          raise ArgumentError, "a group name must be a String" unless name.is_a?(String)
+          raise ArgumentError, "group #{name.inspect} lists no commands" if commands.empty?
+
+          @values[:groups] = groups + [[name, commands.map(&:to_s).freeze].freeze]
+        end
+
+        # @return [Array<Array(String, Array<String>)>]
+        def groups
+          @values.fetch(:groups, [])
+        end
+
+        # With names, set the order sections print in; a section left out is
+        # hidden. Without, read the order.
+        #
+        # @param names [Array<Symbol>] names from {SECTIONS}
+        # @return [Array<Symbol>]
+        def sections(*names)
+          return @values.fetch(:sections, SECTIONS) if names.empty?
+
+          self.sections = names
+        end
+
+        # @param names [Array<Symbol>]
+        def sections=(names)
+          @values[:sections] = validate_sections(names.flatten)
+        end
+
+        # Hide sections without restating the order.
+        #
+        # @param names [Array<Symbol>] names from {SECTIONS}
+        # @return [Array<Symbol>] every hidden section
+        def hide(*names)
+          @values[:hidden] = hidden | validate_sections(names.flatten)
+        end
+
+        # @return [Array<Symbol>]
+        def hidden
+          @values.fetch(:hidden, [])
+        end
+
+        # @return [Array<Symbol>] the sections that print, in order
+        def visible_sections
+          sections - hidden
+        end
+
+        # The column text wraps at, or nil when wrapping is off.
+        #
+        # @param terminal_width [Integer]
+        # @return [Integer, nil]
+        def wrap_width(terminal_width)
+          return unless wrap
+
+          columns = width == :terminal ? terminal_width - margin : width
+          [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)
+          unknown = names - SECTIONS
+          raise ArgumentError, "unknown sections: #{unknown.inspect}" unless unknown.empty?
+
+          names.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module Help
+      # The pieces every help screen is made of: headings, paragraphs and
+      # definition lists, wrapped to one width and painted with one palette.
+      #
+      # Text wraps before it is painted, so escape codes never count toward a
+      # line's length.
+      class Formatter
+        INDENT = "  "
+        GAP = 2
+
+        # One line of a definition list: a term, and the text that describes it.
+        Row = ::Data.define(:term, :text, :term_style, :text_style) do
+          def initialize(term:, text: nil, term_style: :command, text_style: nil)
+            super
+          end
+        end
+
+        # @return [Configuration]
+        attr_reader :config
+
+        # @return [Integer, nil] the column text wraps at, nil when it does not
+        attr_reader :width
+
+        # @param config [Configuration]
+        # @param io [IO] where the screen prints, which decides `color :auto`
+        # @param terminal_width [Integer]
+        def initialize(config, io, terminal_width: Terminal.width)
+          @config = config
+          @width = config.wrap_width(terminal_width)
+          @pastel = ::Pastel.new(enabled: Colors.enabled_for?(config.color, io))
+        end
+
+        # @param text [String]
+        # @param element [Symbol, nil] a key of {Configuration::STYLES}; nil paints nothing
+        # @return [String]
+        def paint(text, element)
+          return text if element.nil?
+
+          @pastel.decorate(text, *config.styles.fetch(element))
+        end
+
+        # @param section [Symbol]
+        # @return [String]
+        def heading(section)
+          title(config.headings.fetch(section))
+        end
+
+        # A heading with the configured case and style, for any text.
+        # @return [String]
+        def title(text)
+          cased = case config.heading_case
+                  when :upcase then text.upcase
+                  when :capitalize then text.sub(/\A\p{Ll}/, &:upcase)
+                  else text
+                  end
+          paint(cased, :heading)
+        end
+
+        # @param text [String, nil]
+        # @param indent [String]
+        # @return [Array<String>] wrapped lines; blank lines carry no indent
+        def paragraph(text, indent: "")
+          Text.lines(text, width && (width - indent.length)).map do |line|
+            line.empty? ? line : indent + line
+          end
+        end
+
+        # The description column for a set of rows: the longest term that has
+        # a description, but never more than half the wrap width. A term with
+        # nothing beside it has nothing to align.
+        #
+        # @param rows [Array<Row>]
+        # @return [Integer]
+        def column_for(rows)
+          longest = rows.reject { it.text.to_s.empty? }.map { it.term.length }.max || 0
+          width ? [longest, width / 2].min : longest
+        end
+
+        # @param rows [Array<Row>]
+        # @param column [Integer] from {#column_for}
+        # @return [Array<String>]
+        def definitions(rows, column)
+          rows.flat_map { definition(it, column) }
+        end
+
+        private
+
+        def definition(row, column)
+          term = INDENT + paint(row.term, row.term_style)
+          offset = INDENT.length + column + GAP
+          lines = Text.lines(row.text, width && [width - offset, Configuration::MIN_WIDTH].max)
+          return [term] if lines.empty?
+
+          body = lines.map { it.empty? ? it : paint(it, row.text_style) }
+          hanging = body.map { it.empty? ? it : (" " * offset) + it }
+          return [term, *hanging] if row.term.length > column
+
+          [term + (" " * (column + GAP - row.term.length)) + body.first, *hanging.drop(1)]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module Help
+      # The only code that touches dry-cli. Everything else renders.
+      module Integration
+        # Prepended to Dry::CLI. Overrides the two private methods dry-cli
+        # prints help from, and nothing else.
+        #
+        # Both are `@api private` in dry-cli, which is why the suite asserts they
+        # exist: a dry-cli release that renames them fails this gem's specs
+        # rather than a host's help screen.
+        module CLIMethods
+          HELP_FLAGS = %w[-h --help].freeze
+
+          private
+
+          # dry-cli calls this for `mycli deploy -h`.
+          def help(command, prog_name)
+            screen = Screens::Command.new(
+              command:, prog_name:, top_level: !kommand.nil?,
+              config: Help.config_for(registry), io: out
+            )
+            out.puts screen.render
+            exit(0)
+          end
+
+          # dry-cli calls this whenever the arguments name no command: none at
+          # 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)
+            unmatched = arguments.drop(result.names.length)
+
+            if unmatched.empty?
+              status = config.exit_code_without_arguments
+              list(result, config, status.zero? ? out : err, status)
+            elsif HELP_FLAGS.include?(unmatched.first)
+              list(result, config, out, 0)
+            else
+              suggestion = SpellChecker.call(result, arguments)
+              err.puts "#{suggestion}\n\n" if suggestion
+              list(result, config, err, 1)
+            end
+          end
+
+          def list(result, config, io, status)
+            io.puts Screens::Listing.new(result:, config:, io:).render
+            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
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module Help
+      # One class per kind of help screen.
+      module Screens
+        # Renders the configured sections a screen supports, in configured
+        # order, one blank line apart. A subclass lists the sections it
+        # supports in `SECTIONS` and renders each in a private `render_<name>`
+        # that returns lines, or nil when there is nothing to print.
+        class Base
+          Row = Formatter::Row
+          INDENT = Formatter::INDENT
+          HELP = Row.new(term: "-h, --help", text: "Show help", term_style: :option)
+
+          # @param config [Configuration]
+          # @param io [IO] where the screen prints
+          # @param terminal_width [Integer]
+          def initialize(config:, io:, terminal_width: Terminal.width)
+            @config = config
+            @format = Formatter.new(config, io, terminal_width:)
+          end
+
+          # @return [String]
+          def render
+            config.visible_sections
+                  .select { self.class::SECTIONS.include?(it) }
+                  .filter_map { send(:"render_#{it}") }
+                  .reject(&:empty?)
+                  .map { it.join("\n") }
+                  .join("\n\n")
+          end
+
+          private
+
+          attr_reader :config, :format
+
+          # A subclass answers `banner?` and `epilogue?`: whether the title and
+          # description, and the epilogue, print on its screen.
+          def render_banner
+            return unless banner?
+
+            lines = []
+            lines << format.paint(config.title, :title) if config.title
+            description = format.paragraph(config.description)
+            lines << "" unless lines.empty? || description.empty?
+            lines.concat(description)
+          end
+
+          def render_epilogue
+            format.paragraph(config.epilogue) if epilogue?
+          end
+
+          def section(name, body)
+            [format.heading(name), *body] unless body.empty?
+          end
+
+          # Every definition list on a screen shares one description column,
+          # measured over the rows a subclass returns from `aligned_rows`.
+          def column
+            @column ||= format.column_for([HELP, *aligned_rows])
+          end
+
+          def definitions(rows)
+            format.definitions(rows, column)
+          end
+
+          # The nodes of one registry level in the configured order, hidden ones left out.
+          def visible(children)
+            shown = children.to_a.reject { |_, node| node.hidden }
+            config.command_order == :alphabetical ? shown.sort_by(&:first) : shown
+          end
+
+          # A group registered without a command has no description of its own,
+          # so it describes itself by what it contains.
+          def describe_node(node)
+            return node.command.description if node.command
+
+            names = visible(node.children).map(&:first)
+            "Subcommands: #{names.join(', ')}" unless names.empty?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module Help
+      module Screens
+        # The help printed for one command: `mycli deploy -h`.
+        class Command < Base
+          SECTIONS = %i[banner usage description subcommands arguments options examples epilogue].freeze
+
+          # @param command [Class, Dry::CLI::Command]
+          # @param prog_name [String] the program and command path, "mycli db migrate"
+          # @param top_level [Boolean] true when the command is the whole CLI,
+          #   as with `Dry::CLI.new(SomeCommand)`
+          def initialize(command:, prog_name:, top_level: false, **)
+            super(**)
+            @command = command
+            @prog_name = prog_name
+            @top_level = top_level
+          end
+
+          private
+
+          attr_reader :command, :prog_name
+
+          def banner?
+            @top_level || config.banner_on_subcommands
+          end
+
+          def epilogue?
+            @top_level
+          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)
+          end
+
+          def render_description
+            section(:description, format.paragraph(command.description, indent: INDENT))
+          end
+
+          def render_subcommands
+            section(:subcommands, definitions(subcommand_rows))
+          end
+
+          def render_arguments
+            section(:arguments, definitions(argument_rows))
+          end
+
+          def render_options
+            section(:options, definitions([*option_rows, HELP]))
+          end
+
+          # Examples align among themselves: a full command line is longer than
+          # any option, and would push every other description off to the right.
+          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)
+            end
+            section(:examples, format.definitions(rows, format.column_for(rows)))
+          end
+
+          def aligned_rows
+            subcommand_rows + argument_rows + option_rows
+          end
+
+          def usage_arguments
+            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?
+          end
+
+          def subcommand_rows
+            @subcommand_rows ||= visible(command.subcommands).map do |name, node|
+              Row.new(term: name, text: describe_node(node))
+            end
+          end
+
+          def argument_rows
+            @argument_rows ||= command.arguments.map do |argument|
+              Row.new(term: argument_name(argument), text: describe(argument), term_style: :argument)
+            end
+          end
+
+          def option_rows
+            @option_rows ||= command.options.map do |option|
+              Row.new(term: option_term(option), text: describe(option), term_style: :option)
+            end
+          end
+
+          def argument_name(argument)
+            name = argument.name.to_s.upcase
+            argument.array? ? "#{name}..." : name
+          end
+
+          # Short aliases, then the option, then long aliases: "-f, --[no-]force".
+          def option_term(option)
+            name = option.name.to_s.downcase.gsub(/[[:space:]]|_/, "-")
+            main = if option.boolean? then "--[no-]#{name}"
+                   elsif option.flag? then "--#{name}"
+                   elsif option.array? then "--#{name}=VALUE1,VALUE2,.."
+                   else "--#{name}=VALUE"
+                   end
+            aliases = option.aliases.map { it.sub(/\A-{1,2}/, "") }.uniq
+            short, long = aliases.partition { it.length == 1 }
+            [*short.map { "-#{it}" }, main, *long.map { "--#{it}" }].join(", ")
+          end
+
+          # The description, then what a reader needs to use the value.
+          def describe(param)
+            notes = []
+            notes << "required" if param.required?
+            notes << "one of: #{param.values.join(', ')}" if param.values
+            notes << "default: #{param.default.inspect}" unless param.default.nil?
+            [param.options[:desc], ("(#{notes.join('; ')})" if notes.any?)].compact.join(" ")
+          end
+        end
+      end
+    end
+  end
+end