Introduce a new class Reline::Face to configure character attributes

.gitignore

@@ -2,7 +2,6 @@
 /.yardoc
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
 /spec/reports/
 /tmp/

Gemfile

@@ -12,5 +12,6 @@ end
 gem 'bundler'
 gem 'rake'
 gem 'test-unit'
+gem 'test-unit-rr'
 
 gem 'racc'

README.md

@@ -55,6 +55,13 @@ end
 
 See also: [test/reline/yamatanooroti/multiline_repl](https://github.com/ruby/reline/blob/master/test/reline/yamatanooroti/multiline_repl)
 
+## Documentation
+
+### Reline::Face
+
+You can modify the text color and text decorations in your terminal emulator.
+See [doc/reline/face.md](./doc/reline/face.md)
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/reline.

doc/reline/face.md

@@ -0,0 +1,108 @@
+# Face
+
+With the `Reline::Face` class, you can modify the text color and text decorations in your terminal emulator.
+This is primarily used to customize the appearance of the method completion dialog in IRB.
+
+## Usage
+
+### ex: Change the background color of the completion dialog cyan to blue
+
+```ruby
+Reline::Face.config(:completion_dialog) do |conf|
+ conf.define :default, foreground: :white, background: :blue
+ # ^^^^^ `:cyan` by default
+ conf.define :enhanced, foreground: :white, background: :magenta
+ conf.define :scrollbar, foreground: :white, background: :blue
+end
+```
+
+If you provide the above code to an IRB session in some way, you can apply the configuration.
+It's generally done by writing it in `.irbrc`.
+
+Regarding `.irbrc`, please refer to the following link: [https://docs.ruby-lang.org/en/master/IRB.html](https://docs.ruby-lang.org/en/master/IRB.html)
+
+## Available parameters
+
+`Reline::Face` internally creates SGR (Select Graphic Rendition) code according to the block parameter of `Reline::Face.config` method.
+
+| Key | Value | SGR Code (numeric part following "\e[")|
+|:------------|:------------------|-----:|
+| :foreground | :black | 30 |
+| | :red | 31 |
+| | :green | 32 |
+| | :yellow | 33 |
+| | :blue | 34 |
+| | :magenta | 35 |
+| | :cyan | 36 |
+| | :white | 37 |
+| | :bright_black | 90 |
+| | :gray | 90 |
+| | :bright_red | 91 |
+| | :bright_green | 92 |
+| | :bright_yellow | 93 |
+| | :bright_blue | 94 |
+| | :bright_magenta | 95 |
+| | :bright_cyan | 96 |
+| | :bright_white | 97 |
+| :background | :black | 40 |
+| | :red | 41 |
+| | :green | 42 |
+| | :yellow | 43 |
+| | :blue | 44 |
+| | :magenta | 45 |
+| | :cyan | 46 |
+| | :white | 47 |
+| | :bright_black | 100 |
+| | :gray | 100 |
+| | :bright_red | 101 |
+| | :bright_green | 102 |
+| | :bright_yellow | 103 |
+| | :bright_blue | 104 |
+| | :bright_magenta | 105 |
+| | :bright_cyan | 106 |
+| | :bright_white | 107 |
+| :style | :reset | 0 |
+| | :bold | 1 |
+| | :faint | 2 |
+| | :italicized | 3 |
+| | :underlined | 4 |
+| | :slowly_blinking | 5 |
+| | :blinking | 5 |
+| | :rapidly_blinking | 6 |
+| | :negative | 7 |
+| | :concealed | 8 |
+| | :crossed_out | 9 |
+
+- The value for `:style` can be both a Symbol and an Array
+ ```ruby
+ # Single symbol
+ conf.define :default, style: :bold
+ # Array
+ conf.define :default, style: [:bold, :negative]
+ ```
+- The availability of specific SGR codes depends on your terminal emulator
+- You can specify a hex color code to `:foreground` and `:background` color like `foreground: "#FF1020"`. Its availability also depends on your terminal emulator
+
+## Debugging
+
+You can see the current Face configuration by `Reline::Face.configs` method
+
+Example:
+
+```ruby
+irb(main):001:0> Reline::Face.configs
+=>
+{:default=>
+ {:default=>{:style=>:reset, :escape_sequence=>"\e[0m"},
+ :enhanced=>{:style=>:reset, :escape_sequence=>"\e[0m"},
+ :scrollbar=>{:style=>:reset, :escape_sequence=>"\e[0m"}},
+ :completion_dialog=>
+ {:default=>{:foreground=>:white, :background=>:cyan, :escape_sequence=>"\e[0m\e[37;46m"},
+ :enhanced=>{:foreground=>:white, :background=>:magenta, :escape_sequence=>"\e[0m\e[37;45m"},
+ :scrollbar=>{:foreground=>:white, :background=>:cyan, :escape_sequence=>"\e[0m\e[37;46m"}}}
+```
+
+## Backlog
+
+- Support for 256-color terminal emulator. Fallback hex color code such as "#FF1020" to 256 colors
+

lib/reline.rb

@@ -7,6 +7,7 @@
 require 'reline/line_editor'
 require 'reline/history'
 require 'reline/terminfo'
+require 'reline/face'
 require 'rbconfig'
 
 module Reline
@@ -36,10 +37,8 @@ def match?(other)
  DialogRenderInfo = Struct.new(
  :pos,
  :contents,
- :bg_color,
- :pointer_bg_color,
- :fg_color,
- :pointer_fg_color,
+ :face,
+ :bg_color, # For the time being, this line should stay here for the compatibility with IRB.
  :width,
  :height,
  :scrollbar,
@@ -260,10 +259,7 @@ def get_screen_size
  contents: result,
  scrollbar: true,
  height: [15, preferred_dialog_height].min,
- bg_color: 46,
- pointer_bg_color: 45,
- fg_color: 37,
- pointer_fg_color: 37
+ face: :completion_dialog
  )
  }
  Reline::DEFAULT_DIALOG_CONTEXT = Array.new
@@ -606,4 +602,6 @@ def self.update_iogate
  io
 end
 
+Reline::Face.load_initial_configs
+
 Reline::HISTORY = Reline::History.new(Reline.core.config)

lib/reline/face.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+class Reline::Face
+ SGR_PARAMETERS = {
+ foreground: {
+ black: 30,
+ red: 31,
+ green: 32,
+ yellow: 33,
+ blue: 34,
+ magenta: 35,
+ cyan: 36,
+ white: 37,
+ bright_black: 90,
+ gray: 90,
+ bright_red: 91,
+ bright_green: 92,
+ bright_yellow: 93,
+ bright_blue: 94,
+ bright_magenta: 95,
+ bright_cyan: 96,
+ bright_white: 97
+ },
+ background: {
+ black: 40,
+ red: 41,
+ green: 42,
+ yellow: 43,
+ blue: 44,
+ magenta: 45,
+ cyan: 46,
+ white: 47,
+ bright_black: 100,
+ gray: 100,
+ bright_red: 101,
+ bright_green: 102,
+ bright_yellow: 103,
+ bright_blue: 104,
+ bright_magenta: 105,
+ bright_cyan: 106,
+ bright_white: 107,
+ },
+ style: {
+ reset: 0,
+ bold: 1,
+ faint: 2,
+ italicized: 3,
+ underlined: 4,
+ slowly_blinking: 5,
+ blinking: 5,
+ rapidly_blinking: 6,
+ negative: 7,
+ concealed: 8,
+ crossed_out: 9
+ }
+ }.freeze
+
+ class Config
+ ESSENTIAL_DEFINE_NAMES = %i(default enhanced scrollbar).freeze
+ RESET_SGR = "\e[0m".freeze
+
+ def initialize(name, &block)
+ @definition = {}
+ block.call(self)
+ ESSENTIAL_DEFINE_NAMES.each do |name|
+ @definition[name] ||= { style: :reset, escape_sequence: RESET_SGR }
+ end
+ end
+
+ attr_reader :definition
+
+ def define(name, **values)
+ values[:escape_sequence] = format_to_sgr(values.to_a).freeze
+ @definition[name] = values
+ end
+
+ def [](name)
+ @definition.dig(name, :escape_sequence) or raise ArgumentError, "unknown face: #{name}"
+ end
+
+ private
+
+ def sgr_rgb(key, value)
+ return nil unless rgb_expression?(value)
+ case key
+ when :foreground
+ "38;2;"
+ when :background
+ "48;2;"
+ end + value[1, 6].scan(/../).map(&:hex).join(";")
+ end
+
+ def format_to_sgr(ordered_values)
+ sgr = "\e[" + ordered_values.map do |key_value|
+ key, value = key_value
+ case key
+ when :foreground, :background
+ case value
+ when Symbol
+ SGR_PARAMETERS[key][value]
+ when String
+ sgr_rgb(key, value)
+ end
+ when :style
+ [ value ].flatten.map do |style_name|
+ SGR_PARAMETERS[:style][style_name]
+ end.then do |sgr_parameters|
+ sgr_parameters.include?(nil) ? nil : sgr_parameters
+ end
+ end.then do |rendition_expression|
+ unless rendition_expression
+ raise ArgumentError, "invalid SGR parameter: #{value.inspect}"
+ end
+ rendition_expression
+ end
+ end.join(';') + "m"
+ sgr == RESET_SGR ? RESET_SGR : RESET_SGR + sgr
+ end
+
+ def rgb_expression?(color)
+ color.respond_to?(:match?) and color.match?(/\A#[0-9a-fA-F]{6}\z/)
+ end
+ end
+
+ private_constant :SGR_PARAMETERS, :Config
+
+ def self.[](name)
+ @configs[name]
+ end
+
+ def self.config(name, &block)
+ @configs ||= {}
+ @configs[name] = Config.new(name, &block)
+ end
+
+ def self.configs
+ @configs.transform_values(&:definition)
+ end
+
+ def self.load_initial_configs
+ config(:default) do |conf|
+ conf.define :default, style: :reset
+ conf.define :enhanced, style: :reset
+ conf.define :scrollbar, style: :reset
+ end
+ config(:completion_dialog) do |conf|
+ conf.define :default, foreground: :white, background: :cyan
+ conf.define :enhanced, foreground: :white, background: :magenta
+ conf.define :scrollbar, foreground: :white, background: :cyan
+ end
+ end
+
+ def self.reset_to_initial_configs
+ @configs = {}
+ load_initial_configs
+ end
+end

lib/reline/line_editor.rb

@@ -831,27 +831,24 @@ def add_dialog_proc(name, p, context = nil)
  dialog.column = 0
  dialog.width = @screen_size.last
  end
+ face = Reline::Face[dialog_render_info.face || :default]
+ scrollbar_sgr = face[:scrollbar]
+ default_sgr = face[:default]
+ enhanced_sgr = face[:enhanced]
  dialog.contents = contents.map.with_index do |item, i|
- if i == pointer
- fg_color = dialog_render_info.pointer_fg_color
- bg_color = dialog_render_info.pointer_bg_color
- else
- fg_color = dialog_render_info.fg_color
- bg_color = dialog_render_info.bg_color
- end
+ line_sgr = i == pointer ? enhanced_sgr : default_sgr
  str_width = dialog.width - (scrollbar_pos.nil? ? 0 : @block_elem_width)
  str = padding_space_with_escape_sequences(Reline::Unicode.take_range(item, 0, str_width), str_width)
- colored_content = "\e[#{bg_color}m\e[#{fg_color}m#{str}"
+ colored_content = "#{line_sgr}#{str}"
  if scrollbar_pos
- color_seq = "\e[37m"
  if scrollbar_pos <= (i * 2) and (i * 2 + 1) < (scrollbar_pos + bar_height)
- colored_content + color_seq + @full_block
+ colored_content + scrollbar_sgr + @full_block
  elsif scrollbar_pos <= (i * 2) and (i * 2) < (scrollbar_pos + bar_height)
- colored_content + color_seq + @upper_half_block
+ colored_content + scrollbar_sgr + @upper_half_block
  elsif scrollbar_pos <= (i * 2 + 1) and (i * 2) < (scrollbar_pos + bar_height)
- colored_content + color_seq + @lower_half_block
+ colored_content + scrollbar_sgr + @lower_half_block
  else
- colored_content + color_seq + ' ' * @block_elem_width
+ colored_content + scrollbar_sgr + ' ' * @block_elem_width
  end
  else
  colored_content

test/reline/helper.rb

@@ -4,6 +4,7 @@
 
 require 'reline'
 require 'test/unit'
+require 'test/unit/rr'
 
 begin
  require 'rbconfig'