diff options
Diffstat (limited to 'doc/reline/face.md')
| -rw-r--r-- | doc/reline/face.md | 111 |
1 files changed, 111 insertions, 0 deletions
diff --git a/doc/reline/face.md b/doc/reline/face.md new file mode 100644 index 0000000000..1fa916123b --- /dev/null +++ b/doc/reline/face.md @@ -0,0 +1,111 @@ +# 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"}}} +``` + +## 256-Color and TrueColor + +Reline will automatically detect if your terminal emulator supports truecolor with `ENV['COLORTERM] in 'truecolor' | '24bit'`. When this env is not set, Reline will fallback to 256-color. +If your terminal emulator supports truecolor but does not set COLORTERM env, add this line to `.irbrc`. +```ruby +Reline::Face.force_truecolor +``` |