rich-ri 0.1.0

data/lib/rich_ri/formatter.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module RichRI
+  class MethodList < RDoc::Markup::IndentedParagraph
+    def accept(visitor)
+      visitor.respond_to?(:accept_method_list) ? visitor.accept_method_list(self) : super
+    end
+  end
+
+  class Formatter < RDoc::Markup::ToAnsi
+    REFERENCES = /(?<!\w)(?:[A-Z]\w*(?:::\w+)*(?:[#.]\w+[!?=]?)?|\#\w+[!?=]?)/
+
+    def initialize(color: true, classes: {}, theme: Theme.new, bat_theme: ENV.fetch("BAT_THEME", "base16"),
+                   shell_theme: "ansi")
+      super()
+      @color = color
+      @classes = classes
+      @theme = theme
+      @highlighter = Highlighter.new(color, theme:, bat_theme:, shell_theme:)
+    end
+
+    def paint(text, *roles)
+      @theme.paint(text, *roles, enabled: @color)
+    end
+
+    def start_accepting
+      super
+      @res = []
+      @first_heading = true
+    end
+
+    def accept_heading(heading)
+      role = if @first_heading && heading.level == 1
+               :title
+             elsif heading.level <= 2
+               :heading
+             else
+               :subheading
+             end
+      @first_heading = false
+      text = "#{'=' * heading.level} #{RichRI.plain(attributes(heading.text))}"
+      wrap paint(text, role)
+    end
+
+    def accept_rule(_rule)
+      use_prefix or @res << (" " * @indent)
+      @res << paint("-" * [@width - @indent, 1].max, :muted) << "\n"
+    end
+
+    def accept_paragraph(paragraph)
+      text = paragraph.text(@hard_break)
+      if text.start_with?("(from ")
+        wrap paint(RichRI.plain(attributes(text)), :muted)
+      else
+        super
+      end
+    end
+
+    def accept_verbatim(verbatim)
+      text = @highlighter.highlight(verbatim.text, verbatim.format)
+      text.each_line do |line|
+        @res << (" " * (@indent + 2)) unless line == "\n"
+        @res << line
+      end
+      @res << "\n" unless text.end_with?("\n")
+      @res << "\n"
+    end
+
+    def accept_raw(raw)
+      # Markdown HTML blocks bypass the inline visitors in RDoc.
+      @res << RichRI.sanitize(raw.parts.join("\n"))
+    end
+
+    def accept_method_list(list)
+      @indent += list.indent
+      wrap paint(RichRI.sanitize(list.text(@hard_break)), :reference)
+      @indent -= list.indent
+    end
+
+    def accept_list_item_start(item)
+      super
+      return unless @prefix
+
+      role = %i[NOTE LABEL].include?(@list_type.last) ? :label : :reference
+      @prefix = paint(RichRI.plain(@prefix), role)
+    end
+
+    def accept_list_item_end(item)
+      # ToAnsi 8.1 uses byte length for numbered prefixes; ours contain SGRs.
+      RDoc::Markup::ToRdoc.instance_method(:accept_list_item_end).bind_call(self, item)
+    end
+
+    def add_text(text)
+      text = RichRI.sanitize(text)
+      attrs = @attributes.keys
+      roles = []
+      roles << :bold if attrs.include?(:BOLD)
+      roles << :emphasis if attrs.include?(:EM)
+      roles << :strike if attrs.include?(:STRIKE)
+      roles << :code if attrs.include?(:TT)
+      text = if roles.empty?
+               text.gsub(REFERENCES) do |reference|
+                 klass = reference.split(/[.#]/, 2).first
+                 reference.start_with?("#") || @classes.key?(klass) ? paint(reference, :reference) : reference
+               end
+             else
+               paint(text, *roles)
+             end
+      emit_inline(text)
+    end
+
+    def handle_TIDYLINK(children, url)
+      start = @inline_output.length
+      traverse_inline_nodes(children)
+      label = RichRI.plain(@inline_output.slice!(start..))
+      emit_inline(paint(label, :link))
+      # Internal RDoc addresses are implementation details, not useful terminal
+      # URLs. External destinations remain visible and can be opened/copied.
+      return if url.start_with?("rdoc-", "#") || url == label
+
+      emit_inline(" (#{paint(RichRI.sanitize(url), :reference)})")
+    end
+
+    def calculate_text_width(text)
+      RichRI.width(text)
+    end
+
+    def wrap(text)
+      return if text.nil? || text.empty?
+
+      limit = [@width - @indent, 12].max
+      prefix = @prefix || (" " * @indent)
+      @prefix = nil
+      line = +""
+      pending_space = ""
+      flush = lambda do
+        @res << prefix << line
+        @res << RESET if @color
+        @res << "\n"
+        prefix = " " * @indent
+        line = +""
+      end
+
+      text.scan(/(?:\e\[[\d;]*m|[^\s\e])+|[^\S\n]+|\n/).each do |word|
+        if word == "\n"
+          flush.call
+          pending_space = ""
+        elsif word.match?(/\A\s+\z/)
+          pending_space = " " unless line.empty?
+        else
+          if !line.empty? && RichRI.width(line + pending_space + word) > limit
+            flush.call
+            pending_space = ""
+          end
+          # Split long URLs/identifiers using terminal cell widths, never SGR
+          # bytes or the middle of a wide Unicode character.
+          chunks = Reline::Unicode.split_by_width(word, limit).first
+          chunks.pop while chunks.length > 1 && RichRI.plain(chunks.last).empty?
+          chunks.each_with_index do |chunk, index|
+            flush.call if index.positive?
+            line << pending_space << chunk
+            pending_space = ""
+          end
+        end
+      end
+      flush.call unless line.empty?
+    end
+  end
+end

data/lib/rich_ri/highlighter.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module RichRI
+  class Highlighter
+    SHELL_FORMATS = %i[sh bash zsh shell].freeze
+    SESSION_FORMATS = %i[console shell-session shell_session sh-session].freeze
+
+    def initialize(enabled, theme: Theme.new, bat_theme: ENV.fetch("BAT_THEME", "base16"), shell_theme: "ansi")
+      @enabled = enabled
+      @theme = theme
+      @bat_theme = bat_theme
+      @shell_theme = shell_theme
+      @bat = Bat.new
+      @cache = {}
+    end
+
+    def highlight(text, format = nil)
+      text = RichRI.sanitize(text)
+      return text unless @enabled
+
+      @cache[[text, format]] ||= if %i[ruby rb rich_ri_signature].include?(format)
+                                   ruby(text, signature: format == :rich_ri_signature)
+                                 elsif format.nil?
+                                   shell_session(text) || (ruby?(text) ? ruby(text) : text)
+                                 elsif SHELL_FORMATS.include?(format)
+                                   shell_session(text) || other_language(text, format, theme: @shell_theme)
+                                 elsif SESSION_FORMATS.include?(format)
+                                   shell_session(text) || text
+                                 elsif %i[c cpp javascript js json yaml yml diff sql rbs].include?(format)
+                                   other_language(text, format)
+                                 else
+                                   text
+                                 end
+    end
+
+    def shell_prompt(line)
+      match = /\A(?<indent>[ \t]*)(?<prompt>\$[ \t]+)(?<command>[^\r\n]+)(?<ending>\r?\n)?\z/.match(line)
+      return unless match
+
+      # Shellwords only tokenizes text; examples are never evaluated. Accept a
+      # command name/path, optionally preceded by environment assignments.
+      words = Shellwords.shellsplit(match[:command])
+      # A here-document can contain literal "$ command" lines. Leave this
+      # ambiguous, multi-line shell input alone rather than invent prompts.
+      return if words.any? { |word| word.start_with?("<<") }
+
+      words.shift while words.first&.match?(/\A[A-Za-z_]\w*=/)
+      executable = words.first
+      return unless executable&.match?(%r{\A(?:[A-Za-z_][\w.+-]*|(?:/|\./|\.\./|~/)\S+)\z})
+
+      match
+    rescue ArgumentError
+      # Unclosed quotes and other ambiguous examples stay unclassified.
+      nil
+    end
+
+    def shell_session(text)
+      lines = text.lines
+      first = lines.find { |line| !line.strip.empty? }
+      initial = first && shell_prompt(first)
+      return unless initial
+
+      # Require the first meaningful line to be a prompt. This avoids treating
+      # "$ command" inside a Ruby string/heredoc or ordinary prose as a shell.
+      indent = initial[:indent]
+      prompts = lines.map { |line| shell_prompt(line) }
+      prompt_start = /\A#{Regexp.escape(indent)}\$[ \t]+/
+      return if lines.zip(prompts).any? { |line, prompt| line.match?(prompt_start) && !prompt }
+
+      output = +""
+      index = 0
+      while index < lines.length
+        prompt = prompts[index]
+        unless prompt && prompt[:indent] == indent
+          output << lines[index]
+          index += 1
+          next
+        end
+
+        command, index = shell_command(lines, index, prompt)
+        output << command
+      end
+      output
+    end
+
+    def shell_command(lines, index, prompt)
+      prefixes = [prompt[:indent] + @theme.paint(prompt[:prompt], :code)]
+      commands = [prompt[:command] + prompt[:ending].to_s]
+      index += 1
+      # Secondary prompts belong to input only after an explicit continuation.
+      while index < lines.length && commands.last.sub(/\r?\n\z/, "")[/\\+\z/].to_s.length.odd?
+        continuation = /\A(#{Regexp.escape(prompt[:indent])})(>[ \t]+)?(.*?)(\r?\n)?\z/.match(lines[index])
+        break unless continuation && !continuation[3].empty?
+
+        prefixes << (continuation[1] + @theme.paint(continuation[2].to_s, :code))
+        commands << (continuation[3] + continuation[4].to_s)
+        index += 1
+      end
+      source = commands.join
+      highlighted = (@cache[[source, :shell_command]] ||= other_language(source, :bash, theme: @shell_theme))
+      colored_lines = highlighted.lines
+      colored_lines = commands unless colored_lines.length == commands.length
+      [prefixes.zip(colored_lines).map(&:join).join, index]
+    end
+
+    def ruby?(text)
+      # A bare word or a prose-like command can also parse as a Ruby call.
+      return false unless text.match?(/[=\[\]{}'":.@]|\b(?:def|class|module|do|end|nil|true|false|require)\b/)
+
+      Prism.parse_success?(text)
+    end
+
+    def ruby(text, signature: false)
+      root, tokens = Prism.parse_lex(text).value
+      roles = ruby_roles(root)
+      tokens = tokens.map(&:first).reject { |token| token.type == :EOF }
+      # Heredoc tokens need source order. Byte offsets preserve Unicode and all
+      # un-tokenized whitespace, including deliberately incomplete examples.
+      tokens.sort_by! { |token| token.location.start_offset }
+      output = +""
+      offset = 0
+      previous = nil
+      tokens.each_with_index do |token, index|
+        start = token.location.start_offset
+        finish = token.location.end_offset
+        next if start < offset
+
+        output << text.byteslice(offset...start)
+        location, role = roles.bsearch { |candidate, _role| candidate.end_offset > start }
+        role = nil unless location && location.start_offset <= start && finish <= location.end_offset
+        role ||= token_role(token, previous, tokens[index + 1], signature)
+        output << (role ? @theme.paint(token.value, role) : token.value)
+        offset = finish
+        previous = token unless %i[NEWLINE IGNORED_NEWLINE COMMENT].include?(token.type)
+      end
+      output << text.byteslice(offset..)
+    rescue ArgumentError, EncodingError
+      text
+    end
+
+    def ruby_roles(root)
+      roles = []
+      pending = [root]
+      until pending.empty?
+        node = pending.pop
+        case node
+        when Prism::DefNode
+          roles << [node.name_loc, :method]
+        when Prism::CallNode
+          # Infix operators and indexing are also calls in Ruby's AST. Only
+          # named calls and explicit receivers such as obj.+ use method colors.
+          if node.message_loc && (node.call_operator_loc || node.name.to_s.match?(/\A[[:alpha:]_]/))
+            roles << [node.message_loc, :method]
+          end
+        when Prism::SymbolNode
+          roles << [node.location, :symbol]
+        end
+        pending.concat(node.compact_child_nodes)
+      end
+      roles.sort_by { |location, _role| location.start_offset }
+    end
+
+    def token_role(token, previous, following, signature)
+      type = token.type.to_s
+      return :comment if type.start_with?("COMMENT", "EMBDOC")
+      return :symbol if type.start_with?("SYMBOL", "LABEL") || previous&.type == :SYMBOL_BEGIN
+      return :code if %w[KEYWORD_NIL KEYWORD_TRUE KEYWORD_FALSE KEYWORD_SELF].include?(type)
+      return :keyword if type.start_with?("KEYWORD_")
+      return :number if type.match?(/INTEGER|FLOAT|RATIONAL|IMAGINARY/)
+      return :constant if type == "CONSTANT"
+      return :string if type.match?(/STRING|HEREDOC|REGEXP|PERCENT_(?:LOWER|UPPER)_|CHARACTER_LITERAL|BACKTICK/)
+      return :code if type.match?(/VARIABLE|REFERENCE|EMBEXPR|EMBVAR/)
+      return :method if type == "METHOD_NAME"
+
+      # Signatures and incomplete examples can lack a complete syntax tree.
+      if (type == "IDENTIFIER") && (signature || %i[DOT AMPERSAND_DOT COLON_COLON
+                                                    KEYWORD_DEF].include?(previous&.type) || following&.value == "(")
+        return :method
+      end
+
+      :operator if ruby_operator?(token)
+    end
+
+    def ruby_operator?(token)
+      %i[PERCENT PERCENT_EQUAL].include?(token.type) ||
+        %w[= => -> + - * / ** == === != =~ !~ < > <= >= <=> && || ! ~ & | ^
+           << >> += -= *= /= **= &= |= ^= <<= >>= &&= ||= .. ... ? :].include?(token.value)
+    end
+
+    def other_language(text, format, theme: @bat_theme)
+      language = { sh: "bash", shell: "bash", js: "javascript", yml: "yaml" }.fetch(format, format.to_s)
+      @bat.highlight(text, language:, theme:) || text
+    end
+  end
+end

data/lib/rich_ri/manual.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RichRI
+  # RubyGems ships manuals inside the gem; installation into man(1)'s search
+  # path is an explicit user action so gem installation never changes the shell.
+  class Manual
+    PAGER_SETTINGS = %w[MANPAGER PAGER MANROFFOPT GROFF_NO_SGR].freeze
+
+    def path
+      File.expand_path("../../man/man1/rich-ri.1", __dir__)
+    end
+
+    def show(color:, theme: Theme.new)
+      result = system(pager_environment(color:, theme:), "man", path)
+      raise ArgumentError, "man(1) not found; install it or run rich-ri --help" if result.nil?
+
+      result ? 0 : 1
+    end
+
+    def install(target = nil)
+      directory = install_directory(target)
+      destination = File.join(directory, "rich-ri.1")
+      raise ArgumentError, "refusing to replace a symbolic link: #{destination}" if File.symlink?(destination)
+      if File.exist?(destination) && !File.file?(destination)
+        raise ArgumentError, "manual destination is not a regular file: #{destination}"
+      end
+
+      FileUtils.mkdir_p(directory)
+      FileUtils.cp(path, destination)
+      puts "Installed #{RichRI.sanitize(destination)}"
+      puts "If man rich-ri cannot find the page, add the setting for your shell:"
+      puts "Bash/Zsh:"
+      puts "  export MANPATH=#{Shellwords.escape(File.dirname(directory))}:\"${MANPATH:-}\""
+      puts "Fish:"
+      puts "  set -gx MANPATH #{Shellwords.escape(File.dirname(directory))} $MANPATH ''"
+      puts "Run rich-ri --install-man again after upgrading the gem."
+      0
+    end
+
+    private
+
+    def install_directory(target)
+      raise ArgumentError, "--install-man=DIR must not be empty" if target && target.strip.empty?
+
+      data = ENV.fetch("XDG_DATA_HOME", nil)
+      data = File.join(Dir.home, ".local/share") unless data&.start_with?("/")
+      directory = File.expand_path(target || File.join(data, "man/man1"))
+      if directory.match?(/[[:cntrl:]]/) || RichRI.sanitize(directory) != directory
+        raise ArgumentError, "manual destination must not contain control characters"
+      end
+      unless File.basename(directory) == "man1"
+        raise ArgumentError, "manual destination must be a man1 directory, such as ~/.local/share/man/man1"
+      end
+      if File.exist?(directory) && !File.directory?(directory)
+        raise ArgumentError, "manual destination is not a directory: #{directory}"
+      end
+
+      directory
+    end
+
+    def pager_environment(color:, theme:)
+      return {} unless color
+      return {} if ENV.any? do |key, value|
+        !value.empty? && (PAGER_SETTINGS.include?(key) || key.start_with?("LESS_TERMCAP_"))
+      end
+
+      { "GROFF_NO_SGR" => "1", "LESS_TERMCAP_md" => "\e[#{theme.sgr(:heading)}m",
+        "LESS_TERMCAP_me" => RESET, "LESS_TERMCAP_us" => "\e[#{theme.sgr(:link)}m", "LESS_TERMCAP_ue" => RESET,
+        "LESS_TERMCAP_so" => "\e[7m", "LESS_TERMCAP_se" => RESET }
+    end
+  end
+end

data/lib/rich_ri/options.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module RichRI
+  # One option parser supplies both the CLI and completion descriptions.
+  class Options
+    include ConfigurationOptions
+
+    attr_reader :parser, :driver_options, :color, :action
+
+    def initialize
+      @driver_options = Driver.default_options
+      @color = "auto"
+      @action = nil
+      @parser = OptionParser.new
+      # Configuration selection and completion inspect flags before parsing.
+      # Require the same full option names throughout those paths.
+      @parser.require_exact = true
+      @parser.banner = "Usage: rich-ri [options] [Class | Class#method | Class.method | gem:page ...]"
+      configuration_options
+      presentation_options
+      lookup_options
+      source_options
+      utility_options
+      @parser.separator ""
+      @parser.separator "Run without a name for interactive lookup and Tab completion."
+      @parser.separator "Write long options in full; abbreviations are not accepted."
+      @parser.separator "Examples: rich-ri Array#map; rich-ri ruby:syntax/pattern_matching"
+      @parser.separator "Pager keys: / search, n next match, Space next page, q quit."
+      @parser.separator "Defaults: RI options < config file < environment < explicit arguments."
+      @parser.separator "File: $XDG_CONFIG_HOME/rich-ri/config.yml or ~/.config/rich-ri/config.yml."
+      @parser.separator "RICH_RI_CONFIG selects another file; --no-config skips it."
+      @parser.separator "Environment overrides: RICH_RI_THEME, RICH_RI_COLOR, RICH_RI_COLOR_DEPTH,"
+      @parser.separator "  RICH_RI_WIDTH, RICH_RI_BAT_THEME, RICH_RI_SHELL_THEME."
+      @parser.separator "RICH_RI_STYLE_<ROLE> overrides one style; --style takes precedence."
+      @parser.separator "RI_PAGER/PAGER choose the pager; LESS sets its preferences."
+      @parser.separator "NO_COLOR and TERM=dumb disable automatic color; COLORTERM helps detect RGB."
+      @parser.separator "Styles: ANSI name, 0-255, #RRGGBB or fg=COLOR:bg=COLOR:bold:italic."
+      @parser.separator "Also supported: dim, underline, strike, reverse; none disables a role."
+      @parser.separator "Style roles:"
+      Theme::ROLES.each_slice(6) { |roles| @parser.separator "  #{roles.join(', ')}" }
+      @parser.separator "See rich-ri --man or docs/configuration.md for all settings and examples."
+      @parser.separator "Ruby highlighting is built in; bat optionally highlights other languages."
+    end
+
+    def parse(argv, defaults: ENV.fetch("RI", ""), configuration: true)
+      names = configured_defaults(argv, defaults, configuration)
+      args = argv.dup
+      @parser.parse!(args)
+      @driver_options[:names] = names + args
+      @driver_options[:use_stdout] ||= !$stdout.tty? || @driver_options[:interactive]
+      @theme = Theme.new(name: @theme_name, styles: @styles, depth: @color_depth)
+      self
+    end
+
+    def self.formats
+      RDoc::Markup.constants.grep(/^To[A-Z][a-z]+$/)
+                  .map { |name| name.to_s.delete_prefix("To").downcase }.sort - %w[html label test]
+    end
+
+    def entries
+      @parser.top.list.flat_map do |switch|
+        next [] unless switch.respond_to?(:long)
+
+        (switch.short + switch.long).flat_map do |flag|
+          flags = flag.include?("[no-]") ? [flag.sub("[no-]", ""), flag.sub("[no-]", "no-")] : [flag]
+          flags.map { |name| [name == "--color" ? "--color=" : name, switch.desc.join(" ")] }
+        end
+      end
+    end
+
+    private
+
+    def presentation_options
+      @parser.separator ""
+      @parser.separator "Presentation:"
+      @parser.on("--color[=MODE]", %w[auto always never],
+                 "Color: auto (TTY, respects NO_COLOR), always or never.") do |mode|
+        @color = mode || "always"
+      end
+      @parser.on("--no-color", "Plain text with the same page layout.") { @color = "never" }
+      @parser.on("--[no-]pager", "Display through a pager (automatically disabled in pipes).") do |value|
+        @pager_enabled = value
+        @driver_options[:use_stdout] = !value
+      end
+      @parser.on("-T", "Write directly to stdout.") do
+        @pager_enabled = false
+        @driver_options[:use_stdout] = true
+      end
+      @parser.on("-w", "--width=WIDTH", Integer, "Text width in terminal columns (at least 20).") do |width|
+        raise OptionParser::InvalidArgument, "width must be at least 20" if width < 20
+
+        @driver_options[:width] = width
+      end
+      @parser.on("-f", "--format=NAME", self.class.formats,
+                 "Select an original RDoc formatter: #{self.class.formats.join(', ')}.") do |name|
+        @driver_options[:formatter] = RDoc::Markup.const_get("To#{name.capitalize}")
+      end
+    end
+
+    def lookup_options
+      @parser.separator ""
+      @parser.separator "Lookup:"
+      { "interactive" => ["-i", :interactive, "Repeated lookup with Tab completion."],
+        "all" => ["-a", :show_all, "Include all methods in a class page."],
+        "list" => ["-l", :list, "List known classes and modules."] }.each do |name, (short, key, desc)|
+        @parser.on(short, "--[no-]#{name}", desc) { |value| @driver_options[key] = value }
+      end
+      @parser.on("--[no-]expand-refs", "Expand RDoc references at the end of a page.") do |value|
+        @driver_options[:expand_refs] = value
+      end
+      @parser.on("--server[=PORT]", Integer, "Serve RDoc in a browser (port: 8214; requires webrick).") do |port|
+        @driver_options[:server] = port || 8214
+      end
+    end
+
+    def source_options
+      @parser.separator ""
+      @parser.separator "Documentation sources:"
+      @parser.on("-d", "--doc-dir=DIRS", "Read RI stores from these directories; repeatable.") do |value|
+        # Prefer an existing literal path, including commas, over RI's list form.
+        directories = File.directory?(value) ? [value] : value.split(",")
+        directories.each do |dir|
+          raise OptionParser::InvalidArgument, "#{dir} is not a directory" unless File.directory?(dir)
+
+          @driver_options[:extra_doc_dirs] << File.expand_path(dir)
+        end
+      end
+      @parser.on("--no-standard-docs", "Use only directories provided with --doc-dir.") do
+        %i[system site home gems].each { |key| @driver_options[:"use_#{key}"] = false }
+      end
+      %w[system site home gems].each do |source|
+        @parser.on("--[no-]#{source}", "Include #{source} documentation (default: enabled).") do |value|
+          @driver_options[:"use_#{source}"] = value
+        end
+      end
+      @parser.on("--[no-]list-doc-dirs", "List the directories searched for RI documentation.") do |value|
+        @driver_options[:list_doc_dirs] = value
+      end
+    end
+
+    def utility_options
+      @parser.separator ""
+      @parser.separator "Tools:"
+      @parser.on("--completion=SHELL", %w[bash zsh fish], "Print a completion script for bash, zsh or fish.") do |shell|
+        @action = [:completion, shell]
+      end
+      @parser.on("--man", "Open the bundled manual with man.") { @action = [:man] }
+      @parser.on("--man-path", "Print the path to the bundled manual.") { @action = [:man_path] }
+      @parser.on("--install-man[=DIR]", "Install or update the manual in a user man1 directory.") do |directory|
+        @action = [:install_man, directory]
+      end
+      @parser.on("--dump=CACHE", "Inspect a trusted RI cache file.") { |path| @driver_options[:dump_path] = path }
+      @parser.on("--[no-]profile", "Run Ruby's profiler (requires the profile gem).") do |value|
+        @driver_options[:profile] = value
+      end
+      @parser.on("-h", "--help", "Show this help.") { @action = [:help] }
+      @parser.on("-v", "--version", "Show the rich-ri version.") { @action = [:version] }
+    end
+  end
+end

data/lib/rich_ri/style.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "color"
+
+module RichRI
+  # Parse a small declarative style language, never arbitrary ANSI sequences.
+  class Style
+    ATTRIBUTES = { "bold" => "1", "dim" => "2", "italic" => "3", "underline" => "4",
+                   "reverse" => "7", "strike" => "9" }.freeze
+
+    def initialize(value)
+      unless value.is_a?(String) && !value.empty? && RichRI.sanitize(value) == value
+        raise ArgumentError, "style must be a nonempty string without control characters"
+      end
+
+      @parts = []
+      return if value == "none"
+
+      seen = {}
+      value.split(":", -1).each do |token|
+        key, part = parse_token(token)
+        raise ArgumentError, "duplicate #{key} in style #{value.inspect}" if seen[key]
+
+        seen[key] = true
+        @parts << [key, part]
+      end
+    end
+
+    def sgr(depth)
+      @parts.map do |key, part|
+        part.is_a?(Color) ? part.sgr(depth, background: key == "bg") : part
+      end.join(";")
+    end
+
+    private
+
+    def parse_token(token)
+      return [token, ATTRIBUTES.fetch(token)] if ATTRIBUTES.key?(token)
+
+      key, value = token.include?("=") ? token.split("=", 2) : ["fg", token]
+      unless %w[fg bg].include?(key)
+        raise ArgumentError, "unknown style property #{key.inspect}; use fg, bg or a text attribute"
+      end
+
+      [key, Color.new(value)]
+    end
+  end
+end