dry-cli-help 0.1.0

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module Help
+      module Screens
+        # The help printed for a registry level: `mycli`, `mycli -h`, and a group
+        # such as `mycli db` whose node has no command of its own.
+        class Listing < Base
+          SECTIONS = %i[banner usage commands options epilogue].freeze
+
+          # @param result [Dry::CLI::CommandRegistry::LookupResult] the level to list
+          def initialize(result:, **)
+            super(**)
+            @result = result
+          end
+
+          private
+
+          attr_reader :result
+
+          def top_level?
+            result.names.empty?
+          end
+
+          def banner?
+            top_level? || config.banner_on_subcommands
+          end
+
+          def epilogue?
+            top_level?
+          end
+
+          def render_usage
+            program = format.paint(ProgramName.call(result.names), :command)
+            section(:usage, ["#{INDENT}#{program} COMMAND [OPTIONS]"])
+          end
+
+          def render_commands
+            blocks = []
+            ungrouped = command_rows.except(*grouped).values
+            blocks << section(:commands, definitions(ungrouped)) if ungrouped.any?
+
+            config.groups.each do |name, paths|
+              rows = paths.filter_map { command_rows[it] }
+              blocks << [format.title(name), *definitions(rows)] if rows.any?
+            end
+
+            blocks.inject { |above, below| above + [""] + below }
+          end
+
+          def render_options
+            section(:options, definitions([HELP, *option_rows]))
+          end
+
+          def aligned_rows
+            command_rows.values + option_rows
+          end
+
+          def grouped
+            @grouped ||= config.groups.flat_map(&:last)
+          end
+
+          # Commands keyed by full path, so a group can name "db migrate".
+          def command_rows
+            @command_rows ||= entries.each_with_object({}) do |(name, node, aliases), rows|
+              next if name.start_with?("-")
+
+              term = [name, *aliases.reject { it.start_with?("-") }].join(", ")
+              rows[[*result.names, name].join(" ")] = Row.new(term:, text: describe_node(node))
+            end
+          end
+
+          # A command reachable as `--version` or `-v` reads as an option, so it
+          # lists under Options by its dashed names.
+          def option_rows
+            @option_rows ||= entries.filter_map do |name, node, aliases|
+              dashed = [name, *aliases].select { it.start_with?("-") }
+              next if dashed.empty?
+
+              term = dashed.sort_by { [it.length, it] }.join(", ")
+              Row.new(term:, text: describe_node(node), term_style: :option)
+            end
+          end
+
+          def entries
+            @entries ||= visible(result.children).map do |name, node|
+              [name, node, aliases_of(node)]
+            end
+          end
+
+          # dry-cli files an alias on the parent node, pointing at the child.
+          def aliases_of(node)
+            node.parent.aliases.filter_map { |name, target| name if target.equal?(node) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Dry
+  class CLI
+    module Help
+      # The width of the terminal help prints to.
+      module Terminal
+        FALLBACK_WIDTH = 80
+
+        module_function
+
+        # `COLUMNS` wins over the console, so a user or a test can pin the width.
+        #
+        # @param env [Hash, ENV]
+        # @param console [IO, nil] the controlling terminal, nil without one
+        # @return [Integer]
+        def width(env: ENV, console: IO.console)
+          from_env(env) || from_console(console) || FALLBACK_WIDTH
+        end
+
+        # @return [Integer, nil]
+        def from_env(env)
+          columns = Integer(env.fetch("COLUMNS", ""), exception: false)
+          columns if columns&.positive?
+        end
+
+        # @return [Integer, nil]
+        def from_console(console)
+          columns = console&.winsize&.last
+          columns if columns&.positive?
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module Help
+      # Word wrapping for descriptions, epilogues and anything else a user writes.
+      module Text
+        module_function
+
+        # Split text into lines no wider than `width`.
+        #
+        # Paragraphs split on blank lines and reflow, so a heredoc wraps to the
+        # terminal instead of keeping the line breaks of the editor it was
+        # written in. A line starting with whitespace prints verbatim, which
+        # keeps indented lists and code intact. Consecutive blank lines collapse
+        # to one. A word longer than `width` gets a line to itself.
+        #
+        # @param text [String, nil]
+        # @param width [Integer, nil] nil keeps every line as written
+        # @return [Array<String>] lines, with "" between paragraphs
+        def lines(text, width)
+          source = text.to_s.sub(/\A(?:[ \t]*\n)+/, "").rstrip
+          return source.lines(chomp: true) if width.nil?
+
+          reflow(source, width)
+        end
+
+        # @return [Array<String>]
+        def reflow(source, width)
+          output = []
+          paragraph = []
+          flush = lambda do
+            output.concat(fill(paragraph.join(" "), width)) unless paragraph.empty?
+            paragraph.clear
+          end
+
+          source.each_line(chomp: true) do |line|
+            if line.strip.empty?
+              flush.call
+              output << "" unless output.last == ""
+            elsif line.start_with?(" ", "\t")
+              flush.call
+              output << line.rstrip
+            else
+              paragraph << line.strip
+            end
+          end
+          flush.call
+          output
+        end
+
+        # Greedy fill of one paragraph.
+        # @return [Array<String>]
+        def fill(text, width)
+          text.split.each_with_object([]) do |word, lines|
+            if lines.empty? || lines.last.length + 1 + word.length > width
+              lines << word.dup
+            else
+              lines.last << " " << word
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Dry
+  # Reopened rather than defined: dry-cli declares `class CLI`, not a module,
+  # and getting that wrong raises TypeError the moment both are loaded.
+  #
+  # Declared here without requiring dry-cli, because the gemspec loads this
+  # file at build time when the dependency may not be installed. dry-cli's CLI
+  # inherits from Object, so an empty reopening is compatible either way.
+  class CLI
+    module Help
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/dry/cli/help.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require "pastel"
+
+require_relative "help/version"
+require_relative "help/colors"
+require_relative "help/terminal"
+require_relative "help/text"
+require_relative "help/configuration"
+require_relative "help/formatter"
+require_relative "help/screens/base"
+require_relative "help/screens/listing"
+require_relative "help/screens/command"
+require_relative "help/integration"
+
+module Dry
+  class CLI
+    # 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.
+    module Help
+      class << self
+        # @yieldparam config [Configuration] the process-wide settings
+        # @return [Configuration]
+        def configure
+          yield config
+          config
+        end
+
+        # @return [Configuration] the process-wide settings
+        def config
+          @config ||= Configuration.new
+        end
+
+        # Forget every process-wide setting.
+        # @return [void]
+        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)

data/lib/dry-cli-help.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "dry/cli/help"

data/sig/dry/cli/help.rbs

@@ -0,0 +1,88 @@
+module Dry
+  class CLI
+    module Help
+      VERSION: String
+
+      def self.configure: () { (Configuration) -> void } -> Configuration
+      def self.config: () -> Configuration
+      def self.reset!: () -> void
+      def self.config_for: (untyped registry) -> Configuration
+
+      module Colors
+        STYLES: Array[Symbol]
+        SETTINGS: Array[bool | Symbol]
+
+        def self.enabled: () -> (bool | Symbol)
+        def self.enabled=: (bool | Symbol) -> void
+        def self.pastel: () -> untyped
+        def self.enabled_for?: (bool | Symbol setting, untyped io) -> bool
+
+        def pastel: () -> untyped
+      end
+
+      module Terminal
+        FALLBACK_WIDTH: Integer
+
+        def self.width: (?env: Hash[String, String], ?console: untyped) -> Integer
+      end
+
+      module Text
+        def self.lines: (String? text, Integer? width) -> Array[String]
+      end
+
+      class Configuration
+        SECTIONS: Array[Symbol]
+        HEADINGS: Hash[Symbol, String]
+        STYLES: Hash[Symbol, Array[Symbol]]
+        DEFAULTS: Hash[Symbol, untyped]
+        MIN_WIDTH: Integer
+
+        def initialize: (?Hash[Symbol, untyped] values) -> void
+
+        def title: (?String? value) -> String?
+        def title=: (String?) -> void
+        def description: (?String? value) -> String?
+        def description=: (String?) -> void
+        def epilogue: (?String? value) -> String?
+        def epilogue=: (String?) -> void
+        def color: (?(bool | Symbol) value) -> (bool | Symbol)
+        def color=: (bool | Symbol) -> void
+        def wrap: (?bool value) -> bool
+        def wrap=: (bool) -> void
+        def width: (?(Integer | Symbol) value) -> (Integer | Symbol)
+        def width=: (Integer | Symbol) -> void
+        def margin: (?Integer value) -> Integer
+        def margin=: (Integer) -> void
+        def exit_code_without_arguments: (?Integer value) -> Integer
+        def exit_code_without_arguments=: (Integer) -> void
+        def banner_on_subcommands: (?bool value) -> bool
+        def banner_on_subcommands=: (bool) -> void
+        def heading_case: (?Symbol value) -> Symbol
+        def heading_case=: (Symbol) -> void
+        def command_order: (?Symbol value) -> Symbol
+        def command_order=: (Symbol) -> void
+
+        def heading: (Symbol section, String text) -> String
+        def headings: () -> Hash[Symbol, String]
+        def style: (Symbol element, *Symbol names) -> Array[Symbol]
+        def styles: () -> Hash[Symbol, Array[Symbol]]
+        def group: (String name, *(String | Array[String]) commands) -> Array[[String, Array[String]]]
+        def groups: () -> Array[[String, Array[String]]]
+        def sections: (*Symbol names) -> Array[Symbol]
+        def sections=: (Array[Symbol]) -> void
+        def hide: (*Symbol names) -> Array[Symbol]
+        def hidden: () -> Array[Symbol]
+        def visible_sections: () -> Array[Symbol]
+        def wrap_width: (Integer terminal_width) -> Integer?
+        def merge: (Configuration other) -> Configuration
+      end
+
+      module Integration
+        module RegistryMethods
+          def help: () ?{ (Configuration) -> void } -> Configuration
+          def help_config: () -> Configuration?
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: dry-cli-help
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Konstantin Gredeskoul
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: Adds a title, description, epilogue, command groups, section ordering,
+  terminal-width wrapping and ANSI colors to the help dry-cli prints, configured through
+  a help block on the registry.
+email:
+- kigster@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- SPECIFICATION.md
+- lib/dry-cli-help.rb
+- lib/dry/cli/help.rb
+- lib/dry/cli/help/colors.rb
+- lib/dry/cli/help/configuration.rb
+- lib/dry/cli/help/formatter.rb
+- lib/dry/cli/help/integration.rb
+- lib/dry/cli/help/screens/base.rb
+- lib/dry/cli/help/screens/command.rb
+- lib/dry/cli/help/screens/listing.rb
+- lib/dry/cli/help/terminal.rb
+- lib/dry/cli/help/text.rb
+- lib/dry/cli/help/version.rb
+- sig/dry/cli/help.rbs
+homepage: https://github.com/kigster/dry-cli-help
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/kigster/dry-cli-help
+  source_code_uri: https://github.com/kigster/dry-cli-help
+  changelog_uri: https://github.com/kigster/dry-cli-help/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Configurable, wrapped, colored help screens for dry-cli applications
+test_files: []