From bc7ddc00e91c3240d7fdf2cebf8b08b9aaef52c3 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 15 Jul 2025 18:09:26 -0500 Subject: [PATCH 01/60] Initial commit --- README.md | 106 ++++++--------- doc/for_contributors.md | 2 + doc/for_developers.md | 92 +++++++++++++ doc/for_users.md | 280 ++++++++++++++++++++++++++++++++++++++++ doc/reporting_bugs.md | 2 + 5 files changed, 412 insertions(+), 70 deletions(-) create mode 100644 doc/for_contributors.md create mode 100644 doc/for_developers.md create mode 100644 doc/for_users.md create mode 100644 doc/reporting_bugs.md diff --git a/README.md b/README.md index f4b4050651..d4da192178 100644 --- a/README.md +++ b/README.md @@ -1,94 +1,60 @@ [![Gem Version](https://badge.fury.io/rb/reline.svg)](https://badge.fury.io/rb/reline) [![CI](https://github.com/ruby/reline/actions/workflows/reline.yml/badge.svg)](https://github.com/ruby/reline/actions/workflows/reline.yml) -This is a screen capture of *IRB improved by Reline*. - -![IRB improved by Reline](https://raw.githubusercontent.com/wiki/ruby/reline/images/irb_improved_by_reline.gif) - # Reline -Reline is compatible with the API of Ruby's stdlib 'readline', GNU Readline and Editline by pure Ruby implementation. - -## Usage - -### Single line editing mode - -It's compatible with the readline standard library. - -See [the document of readline stdlib](https://ruby-doc.org/stdlib/exts/readline/Readline.html) or [bin/example](https://github.com/ruby/reline/blob/master/bin/example). +Module Reline is the Ruby library that supports: -### Multi-line editing mode +- Editing text on the command line: -```ruby -require "reline" + - Use Left-Arrow and Right-Arrow keys (`←` and `→`) to move the cursor within the text you've typed. + - Use Delete and Backspace keys to remove characters from the typed text. + - Type to insert text at the cursor. + - Use Tab key to invoke auto-completion. -prompt = 'prompt> ' -use_history = true +- Reviewing and re-using command-line history: -begin - while true - text = Reline.readmultiline(prompt, use_history) do |multiline_input| - # Accept the input until `end` is entered - multiline_input.split.last == "end" - end + - Use Up-Arrow and Down-Arrow keys (`↑` and `↓`) to scroll among previously typed commands. + - Use history index numbers to select and invoke commands from history. - puts 'You entered:' - puts text - end -# If you want to exit, type Ctrl-C -rescue Interrupt - puts '^C' - exit 0 -end -``` +## Your Reline -```bash -$ ruby example.rb -prompt> aaa -prompt> bbb -prompt> end -You entered: -aaa -bbb -end -``` +If you are the _user_ of a console application that uses Reline +(such as [IRB](https://ruby.github.io/irb/index.html)), +see [For Users](for_users.md); +see also [Reline in Action](rdoc-ref:README.md@Reline+in+Action) below. -See also: [test/reline/yamatanooroti/multiline_repl](https://github.com/ruby/reline/blob/master/test/reline/yamatanooroti/multiline_repl) +If you are the _developer_ of a console application that uses (or will use) Reline, +see [For Developers](for_developers.md). -## Documentation +If you want to _contribute_ to Reline code or documentation +(enhancements or bug fixes), +see [For Contributors](for_contributors.md). -### Reline::Face +If you want to _report_ a bug in Reline code or documentation, +see [Reporting Bugs](reporting_bugs.md). -You can modify the text color and text decorations in your terminal emulator. -See [doc/reline/face.md](./doc/reline/face.md) +## Reline in Action -## Contributing +Below is a screen capture of a brief session +in [IRB](https://ruby.github.io/irb/index.html) (Interactive Ruby), +which uses Reline: -Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/reline. +- The dark gray area of the window at the upper-right shows the keys that are being typed. +- The main part of the window shows the result of the typing. -### Run tests - -> **Note** -> Please make sure you have `libvterm` installed for `yamatanooroti` tests (integration tests). - -If you use Homebrew, you can install it by running `brew install libvterm`. - -```bash -WITH_VTERM=1 bundle install -WITH_VTERM=1 bundle exec rake test test_yamatanooroti -``` - -## Releasing - -```bash -rake release -gh release create vX.Y.Z --generate-notes -``` +![IRB improved by Reline](https://raw.githubusercontent.com/wiki/ruby/reline/images/irb_improved_by_reline.gif) ## License The gem is available as open source under the terms of the [Ruby License](https://www.ruby-lang.org/en/about/license.txt). -## Acknowledgments for [rb-readline](https://github.com/ConnorAtherton/rb-readline) +## Acknowledgment -In developing Reline, we have used some of the rb-readline implementation, so this library includes [copyright notice, list of conditions and the disclaimer](license_of_rb-readline) under the 3-Clause BSD License. Reline would never have been developed without rb-readline. Thank you for the tremendous accomplishments. +In developing Reline, we have used some of the implementation +of [rb-readline](https://github.com/ConnorAtherton/rb-readline), +so this library includes +[copyright notice, list of conditions and the disclaimer](../license_of_rb-readline) +under the 3-Clause BSD License. +Reline would never have been developed without rb-readline. +Thank you for the tremendous accomplishments. diff --git a/doc/for_contributors.md b/doc/for_contributors.md new file mode 100644 index 0000000000..2acc2588ee --- /dev/null +++ b/doc/for_contributors.md @@ -0,0 +1,2 @@ +# For Contributors + diff --git a/doc/for_developers.md b/doc/for_developers.md new file mode 100644 index 0000000000..83aa83e979 --- /dev/null +++ b/doc/for_developers.md @@ -0,0 +1,92 @@ +# For Developers + +This page is for the developer who wants to use `reline` +in a console application. + +Other pages: + +- Page [README](README.md) gives a general description + of `reline` and what it does. +- Page [For Users](for_users.md) + is for the user of a console application + that uses module `reline`. + + +The first thing to know about `reline` is that you make it available in your program with: + +``` +require 'reline' +``` + +## Usage + +### Single line editing mode + +It's compatible with the readline standard library. + +See [the document of readline stdlib](https://ruby-doc.org/stdlib/exts/readline/Readline.html) or [bin/example](https://github.com/ruby/reline/blob/master/bin/example). + +### Multi-line editing mode + +```ruby +require "reline" + +prompt = 'prompt> ' +use_history = true + +begin + while true + text = Reline.readmultiline(prompt, use_history) do |multiline_input| + # Accept the input until `end` is entered + multiline_input.split.last == "end" + end + + puts 'You entered:' + puts text + end +# If you want to exit, type Ctrl-C +rescue Interrupt + puts '^C' + exit 0 +end +``` + +```bash +$ ruby example.rb +prompt> aaa +prompt> bbb +prompt> end +You entered: +aaa +bbb +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) + +### Run tests + +> **Note** +> Please make sure you have `libvterm` installed for `yamatanooroti` tests (integration tests). + +If you use Homebrew, you can install it by running `brew install libvterm`. + +```bash +WITH_VTERM=1 bundle install +WITH_VTERM=1 bundle exec rake test test_yamatanooroti +``` + +## Releasing + +```bash +rake release +gh release create vX.Y.Z --generate-notes +``` + diff --git a/doc/for_users.md b/doc/for_users.md new file mode 100644 index 0000000000..18ddd247a5 --- /dev/null +++ b/doc/for_users.md @@ -0,0 +1,280 @@ +# For Users + +This page is for the user of a console application that uses module Reline, +such as Ruby's own: + +- [irb](https://ruby.github.io/irb/index.html): Interactive Ruby. +- [debug](https://github.com/ruby/debug): Ruby debugger. +- [ri](https://ruby.github.io/rdoc/RI_md.html) Ruby information. + +For other usages, see [Your Reline](rdoc-ref:README.md@Your+Reline). + +Note that the usages described here are the _default_ usages for Reline. +A console application that uses module Reline may have implemented different usages. + +## The Basics + +Reline lets you edit typed command-line text. + +Cursor-movement commands: + +- `Left-Arrow` or `Ctrl-b`: backward one character. +- `Right-Arrow` or `Ctrl-f`: forward one character. +- `Alt-b`: backward to the beginning of a word. +- `Alt-f`: forward to the end of a word. +- `Home` or `Ctrl-a`: backward to the beginning of the line. +- `End` or `Ctrl-e`: forward to the end of the line. + +Text-deletion commands: + +- `Delete` or `Ctrl-d`: remove the character to the right the cursor. +- `Backspace`: remove the character to the left the cursor. + +Text-insertion commands: + +- Printable characters: insert text at the cursor; + existing characters to the right of the cursor are move rightward. + +Other commands: + +- `Ctrl-_`: undo the last editing command. +- `Ctrl-l`: clear the screen and reprint the current line at the top. + +## Killing and Yanking + +Kill commands; each kills text beginning at the cursor: + +- `Ctrl-k`: kill to the end of the line. +- `Alt-d`: kill to the end of the current word, + or, if between words, to the end of the next word. +- `Alt-Delete`: kill to the start of the current word, + or, if between words, to the start of the previous word. +- `Ctrl-w`: kill to the previous whitespace.` + +Yank commands; each inserts killed text at the cursor: + +- `Ctrl-y`: yank the most recently killed text. +- `Alt-y`: rotate the kill-ring, and yank the new top. + Available only if the immediately preceding command was `Ctrl-y` or another `Alt-y`; + otherwise, does nothing. + +## Arguments + +[TODO] + +## History + +- `Ctrl-r`: search backward. +- `Ctrl-g`: abort search. +- `Ctrl-j`: abort search. +- `Up-Arrow`: scroll upward. +- `Down-Arrow`: scroll downward. + +## Init File + +When a Reline application starts, it reads a user-provided initialization file, +whose path is determined thus: + +- The path specified by `ENV['INPUTRC']` if defined. +- Otherwise, `~/.inputrc`, if that file exists. +- Otherwise, if `ENV['XDG_CONFIG_HOME']` is defined (call its value `path`), + `File.join(path, 'readline/inputrc')`. +- Otherwise, `'~/.config/readline/inputrc'`. +- Otherwise, no initialization file is read. + +The initialization file may contain _directives_, _bindings_, and _variables_. + +### Directives + +#### `$if`, `$else`, and `$endif` + +The initialization file may contain conditional directives, +each of which is an `$if/$endif` pair, +or an `$if/$else/$endif` triplet. + +The `$if` directive takes a single argument; +if the argument is: + +- `'mode=emacs'`: + if variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'emacs'`, + the settings in the $if section are applied; + otherwise the settings in the $else section (if any) are applied. +- `'mode=vi'`: + if variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'vi'`, + the settings in the $if section are applied; + otherwise the settings in the $else section (if any) are applied. +- `'Ruby'` or `'Reline'`: + the settings in the $if section are applied. +- Anything else: + the settings in the $else section are applied. + +The conditional directives may be nested. + +#### $include + +[TODO] + +### Bindings + +[TODO] + +### Variables + +### `completion-ignore-case` + +If set to `'on'`, Reline performs case-insensitive +filename matching and completion. + +The default setting is `'off'`. + +### `convert-meta` + +If set to `'on'`, affects 8-bit characters that have their high bits set +(i.e., characters whose values in range `128..255`). +Reline converts each such character by clearing the high bit +(which puts the character in range `0..127`) +and prefixing an `Escape` character. + +The default value is `'on'`, but Reline sets it to `'off'` +if the locale contains characters whose encodings may include bytes with the eighth bit set. + +### `disable-completion` + +If set to `'on'`, Reline inhibits word completion. +Completion characters (`Tab`, `Alt-?`, and `Alt-*`) lose their usual meanings, +and are inserted directly into the line. + +The default is `'off'`. + +### `editing-mode` + +If set to `'emacs'`, the default key bindings are similar to Emacs; +If set to `'vi'`, the default key bindings are similar to Vi. + +The default is `'emacs'`. + +### `emacs-mode-string` + +Specifies the mode string for Emacs mode; +see [Mode Strings](rdoc-ref:for_users.md@Mode+Strings). + +The default is `'@'`. + +### `enable-bracketed-paste` + +When set to `'On'`, Reline is in _bracketed-paste_ mode, +which means that it inserts each paste or yank +into the editing buffer as a single string of characters, +instead of treating each character as if it had been read from the keyboard. +This prevents Reline from executing any editing commands +bound to key sequences appearing in the pasted text. + +The default is `'on'`. + +### `history-size` + +Set the maximum number of entries saved in the history list: + +- Zero: existing history entries are deleted and no new entries are saved. +- Negative: the number of history entries is not limited. +- Non-numeric value: the maximum number of history entries is set to 500. + +Default value is `'-1'` + +### `isearch-terminators` + +Sets the strings of characters that terminate an incremental search +without subsequently executing the character as a command. + +Default: `Escape` and `Ctrl-j`. + +### `keymap` + +Sets the keymap for key binding commands. +Values are: + +- `'emacs'` (aliased as `'emacs-standard'`). +- `'emacs-ctlx'`. +- `'emacs-meta'`. +- `'vi-command'` (aliased as `'vi'` and `'vi-move'`). +- `'vi-insert'`. + +Default is `'emacs'`. +The value of variable [editing-mode](rdoc-ref:for_users.md@editing-mode) +also affects the default keymap. + +### `keyseq-timeout` + +Specifies the time (in milliseconds) that Reline will wait for further input +when reading an ambiguous key sequence +(i.e., one that can form a complete key sequence using the input read so far, +or can take additional input to complete a longer key sequence). + +If Reline doesn’t receive further input within the timeout, +it uses the shorter but complete key sequence. + +If this variable is set to a value less than or equal to zero, or to a non-numeric value, +Reline waits until another key is pressed to decide which key sequence to complete. + +The default `'500'`. + +### `show-all-if-ambiguous` + +If set to `'on'`, input that has more than one possible completion +cause the completions to be listed immediately (instead of ringing the bell). + +The default is `'off'`. + +### `show-mode-in-prompt` + +If set to `'on'`, prefixed the mode string to the displayed prompt; +see [Mode Strings](rdoc-ref:for_users.md@Mode+Strings). + +The default is `'off'`. + +### `vi-cmd-mode-string` + +Specifies the mode string for Vi command mode; +see [Mode Strings](rdoc-ref:for_users.md@Mode+Strings). + +The default is ‘(cmd)’. + +### `vi-ins-mode-string` + +Specifies the mode string for Vi insertion mode; +see [Mode Strings](rdoc-ref:for_users.md@Mode+Strings). + +The default is ‘(ins)’. + +### Mode Strings + +A _mode string_ is a string that is to be displayed immediately before the prompt string +when variable [show-mode-in-prompt](rdoc-ref:for_users.md@show-mode-in-prompt) is set to `'on'`. + +There are three mode strings: + +- Emacs mode string: + the value of variable [emacs-mode-string](rdoc-ref:for_users.md@emacs-mode-string); + effective when variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'emacs'`. + Default value is `'@'`. +- Vi command mode string: + the value of variable [vi-cmd-mode-string](rdoc-ref:for_users.md@vi-cmd-mode-string); + effective when variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'vi'` + and the editing is in command mode. + Default value is `'(cmd)'`. +- Vi insertion mode string: + the value of variable [vi-ins-mode-string](rdoc-ref:for_users.md@vi-ins-mode-string); + effective when variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'vi'` + and the editing is in insertion mode. + Default value is `'(ins)'`. + +The mode string may include [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code), +which can affect the color (foreground and background) and font (bold, italic, etc.) of the display. +The ANSI escape codes must be preceded by escape `\1` and followed by escape `\2`. + +Example (turns the mode string green): + +``` +"\1\e[32mabcd \e[0m\2" +``` + diff --git a/doc/reporting_bugs.md b/doc/reporting_bugs.md new file mode 100644 index 0000000000..fe8e35ae7d --- /dev/null +++ b/doc/reporting_bugs.md @@ -0,0 +1,2 @@ +# Reporting Bugs + From 636cda861fb181b2b829b254ad03b90b09d8c8f0 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 16 Jul 2025 06:41:55 -0500 Subject: [PATCH 02/60] More on conditional directives --- doc/for_users.md | 46 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 35 insertions(+), 11 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index 18ddd247a5..000af20eb7 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -92,23 +92,47 @@ The initialization file may contain conditional directives, each of which is an `$if/$endif` pair, or an `$if/$else/$endif` triplet. -The `$if` directive takes a single argument; -if the argument is: +- In the `$if/$endif` form, + the if-block consists of the lines between `$if` and `$endif`: + + ``` + $if + # If-block + #endif + ``` + +- In the `$if/$else/$endif` form, + the if-block consists of the lines between `$if` and `$else`, + and the else-block consists of the lines between `$else` and `$endif`: + + ``` + $if + # If-block + $else + # Else-block. + #endif + ``` + +The `$if` directive takes a single argument that expresses a condition. +If the condition evaluates to `true`, +the expressions in the `$if` block are evaluated; +if it evaluates to `false`, +the expressions in the `$else` block (if any) are evaluated. + +The arguments: - `'mode=emacs'`: - if variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'emacs'`, - the settings in the $if section are applied; - otherwise the settings in the $else section (if any) are applied. + evaluates to `true` if variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'emacs'`, + `false` otherwise. - `'mode=vi'`: - if variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'vi'`, - the settings in the $if section are applied; - otherwise the settings in the $else section (if any) are applied. + evaluates to `true` if variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'vi'`, + `false` otherwise. - `'Ruby'` or `'Reline'`: - the settings in the $if section are applied. + evaluates to `true`. - Anything else: - the settings in the $else section are applied. + evaluates to `false`. -The conditional directives may be nested. +Conditional directives may be nested. #### $include From 9bb47887b94581634328f6f47f9937a8995366b4 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 16 Jul 2025 06:45:29 -0500 Subject: [PATCH 03/60] More on conditional directives --- doc/for_users.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index 000af20eb7..70dff05530 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -93,7 +93,8 @@ each of which is an `$if/$endif` pair, or an `$if/$else/$endif` triplet. - In the `$if/$endif` form, - the if-block consists of the lines between `$if` and `$endif`: + the if-block consists of the lines between `$if` and `$endif`, + and there is no else-block: ``` $if @@ -115,9 +116,9 @@ or an `$if/$else/$endif` triplet. The `$if` directive takes a single argument that expresses a condition. If the condition evaluates to `true`, -the expressions in the `$if` block are evaluated; +the expressions in the if-block are evaluated; if it evaluates to `false`, -the expressions in the `$else` block (if any) are evaluated. +the expressions in the else-block (if any) are evaluated. The arguments: From ada8308b36408a6214685c726c9db978f20e6829 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 16 Jul 2025 07:02:45 -0500 Subject: [PATCH 04/60] More on inclusion directive --- doc/for_users.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index 70dff05530..2d9c95eae2 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -70,7 +70,7 @@ Yank commands; each inserts killed text at the cursor: - `Up-Arrow`: scroll upward. - `Down-Arrow`: scroll downward. -## Init File +## Initialization File When a Reline application starts, it reads a user-provided initialization file, whose path is determined thus: @@ -137,7 +137,19 @@ Conditional directives may be nested. #### $include -[TODO] +The `$include` directive takes a single argument, +which is the path to a file that is to be read and evaluated +as if it were part of the initialization file. + +Pro tip: You can use the `$include` directive to override (in full or in part) +another initialization file: + + ``` + $include + # Assignments and directives that will override. + # ... + ``` + ### Bindings From 02d69059c34403d3b23aaeab56337bd5716c8ed3 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 16 Jul 2025 08:57:42 -0500 Subject: [PATCH 05/60] Change notations: Ctrl => C; Alt => M --- doc/for_users.md | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index 2d9c95eae2..bfbcbc25cd 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -18,16 +18,16 @@ Reline lets you edit typed command-line text. Cursor-movement commands: -- `Left-Arrow` or `Ctrl-b`: backward one character. -- `Right-Arrow` or `Ctrl-f`: forward one character. -- `Alt-b`: backward to the beginning of a word. -- `Alt-f`: forward to the end of a word. -- `Home` or `Ctrl-a`: backward to the beginning of the line. -- `End` or `Ctrl-e`: forward to the end of the line. +- `Left-Arrow` or `C-b`: backward one character. +- `Right-Arrow` or `C-f`: forward one character. +- `M-b`: backward to the beginning of a word. +- `M-f`: forward to the end of a word. +- `Home` or `C-a`: backward to the beginning of the line. +- `End` or `C-e`: forward to the end of the line. Text-deletion commands: -- `Delete` or `Ctrl-d`: remove the character to the right the cursor. +- `Delete` or `C-d`: remove the character to the right the cursor. - `Backspace`: remove the character to the left the cursor. Text-insertion commands: @@ -37,25 +37,25 @@ Text-insertion commands: Other commands: -- `Ctrl-_`: undo the last editing command. -- `Ctrl-l`: clear the screen and reprint the current line at the top. +- `C-_`: undo the last editing command. +- `C-l`: clear the screen and reprint the current line at the top. ## Killing and Yanking Kill commands; each kills text beginning at the cursor: -- `Ctrl-k`: kill to the end of the line. -- `Alt-d`: kill to the end of the current word, +- `C-k`: kill to the end of the line. +- `M-d`: kill to the end of the current word, or, if between words, to the end of the next word. -- `Alt-Delete`: kill to the start of the current word, +- `M-Delete`: kill to the start of the current word, or, if between words, to the start of the previous word. -- `Ctrl-w`: kill to the previous whitespace.` +- `C-w`: kill to the previous whitespace.` Yank commands; each inserts killed text at the cursor: -- `Ctrl-y`: yank the most recently killed text. -- `Alt-y`: rotate the kill-ring, and yank the new top. - Available only if the immediately preceding command was `Ctrl-y` or another `Alt-y`; +- `C-y`: yank the most recently killed text. +- `M-y`: rotate the kill-ring, and yank the new top. + Available only if the immediately preceding command was `C-y` or another `M-y`; otherwise, does nothing. ## Arguments @@ -64,9 +64,9 @@ Yank commands; each inserts killed text at the cursor: ## History -- `Ctrl-r`: search backward. -- `Ctrl-g`: abort search. -- `Ctrl-j`: abort search. +- `C-r`: search backward. +- `C-g`: abort search. +- `C-j`: abort search. - `Up-Arrow`: scroll upward. - `Down-Arrow`: scroll downward. @@ -178,7 +178,7 @@ if the locale contains characters whose encodings may include bytes with the eig ### `disable-completion` If set to `'on'`, Reline inhibits word completion. -Completion characters (`Tab`, `Alt-?`, and `Alt-*`) lose their usual meanings, +Completion characters (`Tab`, `M-?`, and `M-*`) lose their usual meanings, and are inserted directly into the line. The default is `'off'`. @@ -223,7 +223,7 @@ Default value is `'-1'` Sets the strings of characters that terminate an incremental search without subsequently executing the character as a command. -Default: `Escape` and `Ctrl-j`. +Default: `Escape` and `C-j`. ### `keymap` From ca7b2902bc7d7a579169df4f8105165da4b0e061 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 16 Jul 2025 09:30:04 -0500 Subject: [PATCH 06/60] Add section Notations --- doc/for_users.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/doc/for_users.md b/doc/for_users.md index bfbcbc25cd..afa9321e41 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -12,6 +12,19 @@ For other usages, see [Your Reline](rdoc-ref:README.md@Your+Reline). Note that the usages described here are the _default_ usages for Reline. A console application that uses module Reline may have implemented different usages. +## Notations + +- The text `C-k` is read as "Control-k", and describes the character input produced + when the [Control key](https://en.wikipedia.org/wiki/Control_key) is depressed (held down) + the `k` key is then pressed, then both are released. + The `Control` key is often labelled `Ctrl`. +- The text `M-k` is read as "Meta-k" or "Alt-k", and describes the character input produced + when the [Alt key](https://en.wikipedia.org/wiki/Alt_key) is depressed (held down), + the `k` key is then pressed, then both are released. + The Meta key is often labelled `Alt` or `Option`. + On a keyboard with two keys labeled `Alt` (usually to either side of the space bar), + the `Alt` on the left side is generally set to work as a `Meta` key. + ## The Basics Reline lets you edit typed command-line text. From 532c7489a0eecaeaf172d840938acb6be21b147c Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 16 Jul 2025 14:58:57 -0500 Subject: [PATCH 07/60] More on keys --- doc/for_users.md | 105 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 75 insertions(+), 30 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index afa9321e41..7901d10e65 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -14,16 +14,45 @@ A console application that uses module Reline may have implemented different usa ## Notations -- The text `C-k` is read as "Control-k", and describes the character input produced - when the [Control key](https://en.wikipedia.org/wiki/Control_key) is depressed (held down) - the `k` key is then pressed, then both are released. - The `Control` key is often labelled `Ctrl`. -- The text `M-k` is read as "Meta-k" or "Alt-k", and describes the character input produced - when the [Alt key](https://en.wikipedia.org/wiki/Alt_key) is depressed (held down), - the `k` key is then pressed, then both are released. - The Meta key is often labelled `Alt` or `Option`. - On a keyboard with two keys labeled `Alt` (usually to either side of the space bar), - the `Alt` on the left side is generally set to work as a `Meta` key. +### Keys + +[Arrow Keys](https://en.wikipedia.org/wiki/Arrow_keys): + +- `←` denotes the left-arrow key. +- `→` denotes the right-arrow key. +- `↑` denotes the up-arrow key. +- `↓` denotes the down-arrow key. + +Other Keys + +- `Alt` denotes the [Alt key](https://en.wikipedia.org/wiki/Alt_key). +- `Bsp` denotes the [Backspace key](https://en.wikipedia.org/wiki/Backspace). +- `Ctrl` denotes the [Control key](https://en.wikipedia.org/wiki/Control_key). +- `Del` denotes the [Delete key](https://en.wikipedia.org/wiki/Delete_key) . +- `End` denotes the [End key](https://en.wikipedia.org/wiki/End_key). +- `Esc` denotes the [Escape key](https://en.wikipedia.org/wiki/Esc_key). +- `Home` denotes the [Home key](https://en.wikipedia.org/wiki/Home_key). +- `Ret` denotes the [Enter key](https://en.wikipedia.org/wiki/Enter_key). +- `Spc` denotes the [Space bar](https://en.wikipedia.org/wiki/Space_bar). +- `Tab` denotes the [Tab key](https://en.wikipedia.org/wiki/Tab_key). + +### Control Characters + +`C-k` (read as "Control-k") denotes the input produced +when `Ctrl` is depressed (held down), +then the `k` key is then pressed, and both are released. + +Almost any character can have a "control" version: +`C-a`, `C-{`, `C-]`, etc. + +### Meta Characters + +`M-k` (read as "Meta-k" or "Alt-k") denotes the input produced +when the `Alt` is depressed (held down), +then the `k` key is then pressed, and both are released. + +Almost any character can have "meta" version: +`M-c`, `M->`, `M-#`, etc. ## The Basics @@ -31,43 +60,59 @@ Reline lets you edit typed command-line text. Cursor-movement commands: -- `Left-Arrow` or `C-b`: backward one character. -- `Right-Arrow` or `C-f`: forward one character. -- `M-b`: backward to the beginning of a word. -- `M-f`: forward to the end of a word. -- `Home` or `C-a`: backward to the beginning of the line. -- `End` or `C-e`: forward to the end of the line. +- Character-by-character: + + - `←` or `C-b`: backward one character. + - `→` or `C-f`: forward one character. +Word-by-word: + + - `M-b`: backward to the beginning of a word. + - `M-f`: forward to the end of a word. + +Whole line: + + - `Home` or `C-a`: backward to the beginning of the line. + - `End` or `C-e`: forward to the end of the line. Text-deletion commands: -- `Delete` or `C-d`: remove the character to the right the cursor. -- `Backspace`: remove the character to the left the cursor. +- `Del` or `C-d`: remove the character to the right the cursor +- `Bsp`: remove the character to the left the cursor. + +In either case, existing characters to the right of the cursor are move leftward +to "close the gap." Text-insertion commands: -- Printable characters: insert text at the cursor; - existing characters to the right of the cursor are move rightward. +- Any printable character: insert the character at the cursor; + existing characters to the right of the cursor are move rightward to "make room." Other commands: -- `C-_`: undo the last editing command. +- `C-_`: undo the last editing command; + may be repeated until the original (unedited) line is restored. - `C-l`: clear the screen and reprint the current line at the top. ## Killing and Yanking -Kill commands; each kills text beginning at the cursor: +The _kill ring_ is a stack containing zero or more strings +that have been killed by kill commands. + +Kill commands; each kills text beginning at the cursor +and pushes that text onto the kill ring. - `C-k`: kill to the end of the line. - `M-d`: kill to the end of the current word, or, if between words, to the end of the next word. -- `M-Delete`: kill to the start of the current word, +- `M-Del`: kill to the start of the current word, or, if between words, to the start of the previous word. -- `C-w`: kill to the previous whitespace.` +- `C-w`: kill to the previous whitespace. -Yank commands; each inserts killed text at the cursor: +Yank commands; pops text from the kill ring +amd inserts the that text at the cursor. - `C-y`: yank the most recently killed text. -- `M-y`: rotate the kill-ring, and yank the new top. +- `M-y`: rotate the kill ring, and yank the new top. Available only if the immediately preceding command was `C-y` or another `M-y`; otherwise, does nothing. @@ -77,11 +122,11 @@ Yank commands; each inserts killed text at the cursor: ## History +- `↑`: scroll upward in history (if not already at the earliest history). +- `↓`: scroll downward in history (if not already at the current line). - `C-r`: search backward. - `C-g`: abort search. - `C-j`: abort search. -- `Up-Arrow`: scroll upward. -- `Down-Arrow`: scroll downward. ## Initialization File @@ -183,7 +228,7 @@ If set to `'on'`, affects 8-bit characters that have their high bits set (i.e., characters whose values in range `128..255`). Reline converts each such character by clearing the high bit (which puts the character in range `0..127`) -and prefixing an `Escape` character. +and prefixing `Esc`. The default value is `'on'`, but Reline sets it to `'off'` if the locale contains characters whose encodings may include bytes with the eighth bit set. @@ -236,7 +281,7 @@ Default value is `'-1'` Sets the strings of characters that terminate an incremental search without subsequently executing the character as a command. -Default: `Escape` and `C-j`. +Default: `Esc` and `C-j`. ### `keymap` From a1ee3c5ee4c70e8dcb08c5db006382e210eaecf6 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 16 Jul 2025 15:41:45 -0500 Subject: [PATCH 08/60] More on kill/yank --- doc/for_users.md | 55 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 40 insertions(+), 15 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index 7901d10e65..e3178620c6 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -95,25 +95,50 @@ Other commands: ## Killing and Yanking -The _kill ring_ is a stack containing zero or more strings -that have been killed by kill commands. +_Killing_ means deleting text from the current line +and saving it for potential later use. +Killed text is pushed onto the _kill ring_ +(a last-in, first-out [stack](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))). -Kill commands; each kills text beginning at the cursor -and pushes that text onto the kill ring. +_Yanking_ means inserting previously-killed text into the current line. +Yanked text is popped from the kill ring. -- `C-k`: kill to the end of the line. -- `M-d`: kill to the end of the current word, - or, if between words, to the end of the next word. -- `M-Del`: kill to the start of the current word, - or, if between words, to the start of the previous word. -- `C-w`: kill to the previous whitespace. +For a kill command that is preceded by another kill command, +the killed text is appended to the text already at the top of the kill ring. +Thus, any number of consecutive kills save text as one string. -Yank commands; pops text from the kill ring -amd inserts the that text at the cursor. +For a kill command that is _not_ preceded by another kill command, +the killed text is pushed onto the kill ring as a new entry. -- `C-y`: yank the most recently killed text. -- `M-y`: rotate the kill ring, and yank the new top. - Available only if the immediately preceding command was `C-y` or another `M-y`; +The kill ring is not line specific; +text killed from a the current line is available for yanking into a new, later, current line. + +### Kill Commands + +Each kill command pushes the killed text onto the kill ring. + +Kill forward; the cursor does not move: + +- `C-k`: Kill from the cursor position to the end of the line. +- `M-d`: Kill from the cursor to the end of the current word, + or, if between words, to the end of the next word; + word boundaries are the same as those used by M-f. + +Kill backward; the cursor moves leftward to "close the gap": + +- `M-Del`: Kill from the cursor to the start of the current word, + or, if between words, to the start of the previous word; + word boundaries are the same as those used by M-b. +- `C-w`: Kill from the cursor to the previous whitespace; + this is different from `M-Del` because the word boundaries are different. + +### Yank Commands + +Each yank command pops text from the kill ring. + +- `C-y`: Yank the most recently killed text at the cursor. +- `M-y`: Rotate the kill ring, and yank from the new top. + Effective only if the immediately preceding command was `C-y` or another `M-y`; otherwise, does nothing. ## Arguments From c70ddf11dbd5b222f7836747dd3827021f0ee2d2 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 16 Jul 2025 15:49:15 -0500 Subject: [PATCH 09/60] More on basics --- doc/for_users.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index e3178620c6..69295a994a 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -58,23 +58,24 @@ Almost any character can have "meta" version: Reline lets you edit typed command-line text. -Cursor-movement commands: +### Cursor-Movement Commands -- Character-by-character: +Character-by-character: + +- `←` or `C-b`: backward one character. +- `→` or `C-f`: forward one character. - - `←` or `C-b`: backward one character. - - `→` or `C-f`: forward one character. Word-by-word: - - `M-b`: backward to the beginning of a word. - - `M-f`: forward to the end of a word. +- `M-b`: backward to the beginning of a word. +- `M-f`: forward to the end of a word. Whole line: - - `Home` or `C-a`: backward to the beginning of the line. - - `End` or `C-e`: forward to the end of the line. +- `Home` or `C-a`: backward to the beginning of the line. +- `End` or `C-e`: forward to the end of the line. -Text-deletion commands: +### Text-Deletion Commands - `Del` or `C-d`: remove the character to the right the cursor - `Bsp`: remove the character to the left the cursor. @@ -82,12 +83,12 @@ Text-deletion commands: In either case, existing characters to the right of the cursor are move leftward to "close the gap." -Text-insertion commands: +### Text-Insertion Commands - Any printable character: insert the character at the cursor; existing characters to the right of the cursor are move rightward to "make room." -Other commands: +### Other Commands - `C-_`: undo the last editing command; may be repeated until the original (unedited) line is restored. From 5b4602485064d09c8144f898b45dd90ba6e687d4 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 16 Jul 2025 15:58:34 -0500 Subject: [PATCH 10/60] Add (empty) sections Macros and Auto-Completion --- doc/for_users.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/for_users.md b/doc/for_users.md index 69295a994a..e3a4642e84 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -154,6 +154,14 @@ Each yank command pops text from the kill ring. - `C-g`: abort search. - `C-j`: abort search. +## Macros + +[TODO] + +## Auto-Completion + +[TODO] + ## Initialization File When a Reline application starts, it reads a user-provided initialization file, From f0dac6440ab5d495aebd22b2a2c66e3c3e8a67d0 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 17 Jul 2025 17:34:56 -0500 Subject: [PATCH 11/60] Tweaks to For Users intro --- doc/for_users.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index e3a4642e84..0561bb4c37 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -1,17 +1,19 @@ # For Users -This page is for the user of a console application that uses module Reline, -such as Ruby's own: +This page is for the user of a console application that uses module Reline. +For other usages, see [Your Reline](rdoc-ref:README.md@Your+Reline). + +Note that this page describes the _default_ usages for Reline. +A console application that uses module Reline may have implemented different usages. + +## Reline in Ruby + +Ruby itself uses Reline in these: - [irb](https://ruby.github.io/irb/index.html): Interactive Ruby. - [debug](https://github.com/ruby/debug): Ruby debugger. - [ri](https://ruby.github.io/rdoc/RI_md.html) Ruby information. -For other usages, see [Your Reline](rdoc-ref:README.md@Your+Reline). - -Note that the usages described here are the _default_ usages for Reline. -A console application that uses module Reline may have implemented different usages. - ## Notations ### Keys From 02119f6eafc2379f9afa3df5f6baf7138db492d9 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 17 Jul 2025 17:40:16 -0500 Subject: [PATCH 12/60] Tweaks to kill/yank in For Users --- doc/for_users.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index 0561bb4c37..05422da7f8 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -118,7 +118,7 @@ text killed from a the current line is available for yanking into a new, later, ### Kill Commands -Each kill command pushes the killed text onto the kill ring. +Each kill command pushes the removed text onto the kill ring. Kill forward; the cursor does not move: @@ -137,7 +137,9 @@ Kill backward; the cursor moves leftward to "close the gap": ### Yank Commands -Each yank command pops text from the kill ring. +Each yank command pops text from the kill ring +and inserts it at the cursor; +the cursor is moved forward to the end of the inserted text. - `C-y`: Yank the most recently killed text at the cursor. - `M-y`: Rotate the kill ring, and yank from the new top. From 9d21af3d04ddd8cc325143727a818d89c869c9f8 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 18 Jul 2025 11:32:31 -0500 Subject: [PATCH 13/60] Remove section Macros --- doc/for_users.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index 05422da7f8..6d48d0c7fd 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -158,10 +158,6 @@ the cursor is moved forward to the end of the inserted text. - `C-g`: abort search. - `C-j`: abort search. -## Macros - -[TODO] - ## Auto-Completion [TODO] From 8f8c896d845d7928b07e8f1bb457e4722c920038 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 19 Jul 2025 08:03:49 -0500 Subject: [PATCH 14/60] More introduction --- doc/for_users.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/doc/for_users.md b/doc/for_users.md index 6d48d0c7fd..adf9b3a24b 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -6,6 +6,34 @@ For other usages, see [Your Reline](rdoc-ref:README.md@Your+Reline). Note that this page describes the _default_ usages for Reline. A console application that uses module Reline may have implemented different usages. +## Reline Application + +A _Reline application_ is a Ruby +[console application](https://en.wikipedia.org/wiki/Console_application) +that uses module Reline. + +Such an application typically implements +a [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) +(a read-evaluate-print loop) +that allows you to type a command, get a response, +type another command, get another response, and so on. + +A Reline application allows editing a partly-entered command by: + +- Moving the cursor within its text. +- Deleting text. +- Inserting text. +- "Killing" text (i.e., deleting and saving text). +- "Yanking" text (i.e., inserting previously killed text). + +A Reline application may also support: + +- [Command history](https://en.wikipedia.org/wiki/Command_history): + a store of previously entered commands that may be retrieved, edited, and re-used. +- [Command-line completion](https://en.wikipedia.org/wiki/Command-line_completion): + assistance in completing a partly-entered command, + or in choosing among possible completions. + ## Reline in Ruby Ruby itself uses Reline in these: @@ -146,7 +174,7 @@ the cursor is moved forward to the end of the inserted text. Effective only if the immediately preceding command was `C-y` or another `M-y`; otherwise, does nothing. -## Arguments +## Quantifiers [TODO] From 20912a8871e89cd1285734dc6694c3b3fc69e262 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 19 Jul 2025 16:23:56 -0500 Subject: [PATCH 15/60] History searching --- doc/for_users.md | 59 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 52 insertions(+), 7 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index adf9b3a24b..5befdbb842 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -30,7 +30,7 @@ A Reline application may also support: - [Command history](https://en.wikipedia.org/wiki/Command_history): a store of previously entered commands that may be retrieved, edited, and re-used. -- [Command-line completion](https://en.wikipedia.org/wiki/Command-line_completion): +- [Command completion](https://en.wikipedia.org/wiki/Command-line_completion): assistance in completing a partly-entered command, or in choosing among possible completions. @@ -60,9 +60,9 @@ Other Keys - `Ctrl` denotes the [Control key](https://en.wikipedia.org/wiki/Control_key). - `Del` denotes the [Delete key](https://en.wikipedia.org/wiki/Delete_key) . - `End` denotes the [End key](https://en.wikipedia.org/wiki/End_key). +- `Ent` denotes the [Enter key](https://en.wikipedia.org/wiki/Enter_key). - `Esc` denotes the [Escape key](https://en.wikipedia.org/wiki/Esc_key). - `Home` denotes the [Home key](https://en.wikipedia.org/wiki/Home_key). -- `Ret` denotes the [Enter key](https://en.wikipedia.org/wiki/Enter_key). - `Spc` denotes the [Space bar](https://en.wikipedia.org/wiki/Space_bar). - `Tab` denotes the [Tab key](https://en.wikipedia.org/wiki/Tab_key). @@ -178,15 +178,60 @@ the cursor is moved forward to the end of the inserted text. [TODO] -## History +## Command History + +A Reline application may support command history. + +An easy way to find out whether it does is (after entering one or more commands) pressing key `↑`: + +- Yes, if you now see the most recently entered command; read on. +- No, if you see no change; this section does not apply. + +You can browse the history: - `↑`: scroll upward in history (if not already at the earliest history). - `↓`: scroll downward in history (if not already at the current line). -- `C-r`: search backward. -- `C-g`: abort search. -- `C-j`: abort search. -## Auto-Completion +You can search the history using these commands: + +- `C-r`: Initiate reverse search. +- `C-g` or `C-j`: Abort search. + +To see history searching in action, +begin an [IRB](https://ruby.github.io/irb/index.html) session: + +``` +$ irb +'xyz' +# => "xyz" +'xy' +# => "xy" +'x' +# => "x" +``` + +In the table below: + +- Each input character is incremental (no intervening characters) + and is all on one editing line (does not generate a newline). +- Each result (still on that same line) is the immediate effect of that input. + +| Input | Result | Details | +|:------------:|---------------------------------------|-------------------------------------| +| C-r | (reverse-i-search)`': | New backward search. | +| 'x' | (reverse-i-search)`x''x' | First command matching 'x' | +| 'y' | (reverse-i-search)`xy''xy' | First command matching 'y' | +| 'z' | (reverse-i-search)`xyz''xyz' | First command matching 'z' | +| C-j | 'xyz' | Search aborted. | +| C-r | (reverse-i-search)`': | New backward search. | +| 'y' | (reverse-i-search)`y''xy' | First command matching 'y' | +| Ent | 'xy' | Command 'xy' ready. | + +In the last instance, command `xy` is displayed on the edit line, +and is ready for execution (via `Ent`), +or for editing (via cursor movement, insertion, deletion, killing, yanking). + +## Command Completion [TODO] From 503b6ea3bce17562f4ef9007e59cd8d75241ce87 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 20 Jul 2025 10:12:07 -0500 Subject: [PATCH 16/60] Change to reference-style links --- doc/for_users.md | 100 +++++++++++++++++++++++++++++------------------ 1 file changed, 63 insertions(+), 37 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index 5befdbb842..6c10374cea 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -1,7 +1,7 @@ # For Users This page is for the user of a console application that uses module Reline. -For other usages, see [Your Reline](rdoc-ref:README.md@Your+Reline). +For other usages, see [Your Reline][your reline]. Note that this page describes the _default_ usages for Reline. A console application that uses module Reline may have implemented different usages. @@ -9,11 +9,10 @@ A console application that uses module Reline may have implemented different usa ## Reline Application A _Reline application_ is a Ruby -[console application](https://en.wikipedia.org/wiki/Console_application) +[console application][console application] that uses module Reline. -Such an application typically implements -a [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) +Such an application typically implements a [REPL][repl] (a read-evaluate-print loop) that allows you to type a command, get a response, type another command, get another response, and so on. @@ -28,9 +27,9 @@ A Reline application allows editing a partly-entered command by: A Reline application may also support: -- [Command history](https://en.wikipedia.org/wiki/Command_history): +- [Command history][command history]: a store of previously entered commands that may be retrieved, edited, and re-used. -- [Command completion](https://en.wikipedia.org/wiki/Command-line_completion): +- [Command completion][command completion]: assistance in completing a partly-entered command, or in choosing among possible completions. @@ -38,15 +37,15 @@ A Reline application may also support: Ruby itself uses Reline in these: -- [irb](https://ruby.github.io/irb/index.html): Interactive Ruby. -- [debug](https://github.com/ruby/debug): Ruby debugger. -- [ri](https://ruby.github.io/rdoc/RI_md.html) Ruby information. +- [irb][irb]: Interactive Ruby. +- [debug][debug]: Ruby debugger. +- [ri][ri]: Ruby information. ## Notations ### Keys -[Arrow Keys](https://en.wikipedia.org/wiki/Arrow_keys): +[Arrow Keys][arrow keys]: - `←` denotes the left-arrow key. - `→` denotes the right-arrow key. @@ -55,16 +54,16 @@ Ruby itself uses Reline in these: Other Keys -- `Alt` denotes the [Alt key](https://en.wikipedia.org/wiki/Alt_key). -- `Bsp` denotes the [Backspace key](https://en.wikipedia.org/wiki/Backspace). -- `Ctrl` denotes the [Control key](https://en.wikipedia.org/wiki/Control_key). -- `Del` denotes the [Delete key](https://en.wikipedia.org/wiki/Delete_key) . -- `End` denotes the [End key](https://en.wikipedia.org/wiki/End_key). -- `Ent` denotes the [Enter key](https://en.wikipedia.org/wiki/Enter_key). -- `Esc` denotes the [Escape key](https://en.wikipedia.org/wiki/Esc_key). -- `Home` denotes the [Home key](https://en.wikipedia.org/wiki/Home_key). -- `Spc` denotes the [Space bar](https://en.wikipedia.org/wiki/Space_bar). -- `Tab` denotes the [Tab key](https://en.wikipedia.org/wiki/Tab_key). +- `Alt` denotes the [Alt key][alt key] +- `Bsp` denotes the [Backspace key][backspace key] +- `Ctrl` denotes the [Control key][control key] +- `Del` denotes the [Delete key][delete key] +- `End` denotes the [End key][end key] +- `Ent` denotes the [Enter key][enter key] +- `Esc` denotes the [Escape key][escape key] +- `Home` denotes the [Home key][home key] +- `Spc` denotes the [Space bar][space bar] +- `Tab` denotes the [Tab key][tab key] ### Control Characters @@ -129,7 +128,7 @@ to "close the gap." _Killing_ means deleting text from the current line and saving it for potential later use. Killed text is pushed onto the _kill ring_ -(a last-in, first-out [stack](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))). +(a last-in, first-out [stack][stack]). _Yanking_ means inserting previously-killed text into the current line. Yanked text is popped from the kill ring. @@ -198,7 +197,7 @@ You can search the history using these commands: - `C-g` or `C-j`: Abort search. To see history searching in action, -begin an [IRB](https://ruby.github.io/irb/index.html) session: +begin an [IRB][irb] session: ``` $ irb @@ -288,10 +287,10 @@ the expressions in the else-block (if any) are evaluated. The arguments: - `'mode=emacs'`: - evaluates to `true` if variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'emacs'`, + evaluates to `true` if variable [editing-mode][editing-mode] is `'emacs'`, `false` otherwise. - `'mode=vi'`: - evaluates to `true` if variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'vi'`, + evaluates to `true` if variable [editing-mode][editing-mode] is `'vi'`, `false` otherwise. - `'Ruby'` or `'Reline'`: evaluates to `true`. @@ -358,7 +357,7 @@ The default is `'emacs'`. ### `emacs-mode-string` Specifies the mode string for Emacs mode; -see [Mode Strings](rdoc-ref:for_users.md@Mode+Strings). +see [Mode Strings][mode strings]. The default is `'@'`. @@ -402,7 +401,7 @@ Values are: - `'vi-insert'`. Default is `'emacs'`. -The value of variable [editing-mode](rdoc-ref:for_users.md@editing-mode) +The value of variable [editing-mode][editing-mode] also affects the default keymap. ### `keyseq-timeout` @@ -430,47 +429,47 @@ The default is `'off'`. ### `show-mode-in-prompt` If set to `'on'`, prefixed the mode string to the displayed prompt; -see [Mode Strings](rdoc-ref:for_users.md@Mode+Strings). +see [Mode Strings][mode strings]. The default is `'off'`. ### `vi-cmd-mode-string` Specifies the mode string for Vi command mode; -see [Mode Strings](rdoc-ref:for_users.md@Mode+Strings). +see [Mode Strings][mode strings]. The default is ‘(cmd)’. ### `vi-ins-mode-string` Specifies the mode string for Vi insertion mode; -see [Mode Strings](rdoc-ref:for_users.md@Mode+Strings). +see [Mode Strings][mode strings]. The default is ‘(ins)’. ### Mode Strings A _mode string_ is a string that is to be displayed immediately before the prompt string -when variable [show-mode-in-prompt](rdoc-ref:for_users.md@show-mode-in-prompt) is set to `'on'`. +when variable [show-mode-in-prompt][show-mode-in-prompt] is set to `'on'`. There are three mode strings: - Emacs mode string: - the value of variable [emacs-mode-string](rdoc-ref:for_users.md@emacs-mode-string); - effective when variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'emacs'`. + the value of variable [emacs-mode-string][emacs-mode-string]; + effective when variable [editing-mode][editing-mode] is `'emacs'`. Default value is `'@'`. - Vi command mode string: - the value of variable [vi-cmd-mode-string](rdoc-ref:for_users.md@vi-cmd-mode-string); - effective when variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'vi'` + the value of variable [vi-cmd-mode-string][vi-cmd-mode-string]; + effective when variable [editing-mode][editing-mode] is `'vi'` and the editing is in command mode. Default value is `'(cmd)'`. - Vi insertion mode string: - the value of variable [vi-ins-mode-string](rdoc-ref:for_users.md@vi-ins-mode-string); - effective when variable [editing-mode](rdoc-ref:for_users.md@editing-mode) is `'vi'` + the value of variable [vi-ins-mode-string][vi-ins-mode-string]; + effective when variable [editing-mode][editing-mode] is `'vi'` and the editing is in insertion mode. Default value is `'(ins)'`. -The mode string may include [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code), +The mode string may include [ANSI escape codes][ansi escape codes] which can affect the color (foreground and background) and font (bold, italic, etc.) of the display. The ANSI escape codes must be preceded by escape `\1` and followed by escape `\2`. @@ -480,3 +479,30 @@ Example (turns the mode string green): "\1\e[32mabcd \e[0m\2" ``` +[alt key]: https://en.wikipedia.org/wiki/Alt_key +[ansi escape codes]: https://en.wikipedia.org/wiki/ANSI_escape_code +[arrow keys]: https://en.wikipedia.org/wiki/Arrow_keys +[backspace key]: https://en.wikipedia.org/wiki/Backspace +[command completion]: https://en.wikipedia.org/wiki/Command-line_completion +[command history]: https://en.wikipedia.org/wiki/Command_history +[console application]: https://en.wikipedia.org/wiki/Console_application +[control key]: https://en.wikipedia.org/wiki/Control_key +[debug]: https://github.com/ruby/debug +[delete key]: https://en.wikipedia.org/wiki/Delete_key +[editing-mode]: rdoc-ref:for_users.md@editing-mode +[emacs-mode-string]: rdoc-ref:for_users.md@emacs-mode-string +[end key]: https://en.wikipedia.org/wiki/End_key +[enter key]: https://en.wikipedia.org/wiki/Enter_key +[escape key]: https://en.wikipedia.org/wiki/Esc_key +[home key]: https://en.wikipedia.org/wiki/Home_key +[irb]: https://ruby.github.io/irb/index.html +[mode strings]: rdoc-ref:for_users.md@Mode+Strings +[repl]: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop +[ri]: https://ruby.github.io/rdoc/RI_md.html +[show-mode-in-prompt]: rdoc-ref:for_users.md@show-mode-in-prompt +[space bar]: https://en.wikipedia.org/wiki/Space_bar +[stack]: https://en.wikipedia.org/wiki/Stack_(abstract_data_type) +[tab key]: https://en.wikipedia.org/wiki/Tab_key +[vi-cmd-mode-string]: rdoc-ref:for_users.md@vi-cmd-mode-string +[vi-ins-mode-string]: rdoc-ref:for_users.md@vi-ins-mode-string +[your reline]: rdoc-ref:README.md@Your+Reline From 7695f015a49f6f9fab032a5fc00c16d4b2d79eac Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 20 Jul 2025 10:58:30 -0500 Subject: [PATCH 17/60] Adding Quantifiers --- doc/for_users.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/doc/for_users.md b/doc/for_users.md index 6c10374cea..88b671a1dc 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -175,7 +175,18 @@ the cursor is moved forward to the end of the inserted text. ## Quantifiers -[TODO] +Some Reline commands accept quantifiers. + +A quantifier is a positive integer repeat count `n` +that tells Reline to execute the command `n` times. + +The quantifier precedes the command, +and is typed as numeric characters in range `('0'..'9')` while holding down the `Alt` key. + +Examples: + +- `M-4` `←` moves the cursor four characters to the left. +- `M-1` `M-4` `←` moves the cursor fourteen characters to the left. ## Command History @@ -506,3 +517,8 @@ Example (turns the mode string green): [vi-cmd-mode-string]: rdoc-ref:for_users.md@vi-cmd-mode-string [vi-ins-mode-string]: rdoc-ref:for_users.md@vi-ins-mode-string [your reline]: rdoc-ref:README.md@Your+Reline + +[TODO] + +Resolve all C- and M- from Gnu doc. +Doc which commands accept arguments. From 06660baa0dfca91818cc48d35bb1eb37d2ebea3b Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 20 Jul 2025 11:01:23 -0500 Subject: [PATCH 18/60] Update TODOs --- doc/for_users.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index 88b671a1dc..35a4a4703d 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -520,5 +520,5 @@ Example (turns the mode string green): [TODO] -Resolve all C- and M- from Gnu doc. -Doc which commands accept arguments. +- Resolve all C- and M- from Gnu doc. +- Doc which commands accept arguments. From 829603008e02e9dd2bc6a179a5b01c34fa5ef4d1 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 20 Jul 2025 13:18:29 -0500 Subject: [PATCH 19/60] Added Command Completion --- doc/for_users.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 72 insertions(+), 1 deletion(-) diff --git a/doc/for_users.md b/doc/for_users.md index 35a4a4703d..fb176725de 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -243,7 +243,78 @@ or for editing (via cursor movement, insertion, deletion, killing, yanking). ## Command Completion -[TODO] +A Reline application may support command completion, +which is implemented as responses to the `Tab` command, +by providing a list of command words. + +Suppose an application just echoes whatever is typed to its prompt: + +``` +$ruby +echo> Hi! +You typed: 'Hi!'. +``` + +And suppose further that it has these command words: + +``` +['foo_foo', 'foo_bar', 'foo_baz', 'qux'] +``` + +Then typing a single character `'q'` does not do much; we just see the one typed character: + +``` +echo> q +``` + +Pressing `Tab` requests command completion; we see the complete word: + +``` +echo> qux +``` + +That's because the only possible command word beginning with `'q'` is `'qux'`. +Then typing `'f'` does not do much; we just see the one character typed: + +Adding `Ent` executes the command: + +``` +echo> qux +You typed: 'qux'. +echo> +``` + +Typing the single character `'f'`, as before, does not do much: +``` +echo> f +``` + +Pressing `Tab`, as before, requests command completion. +Because there are multiple command words starting with `'f'`, Reline cannot complete the command; +but because all command words starting with `'f'` also start with `'foo_'`, +Reline can partially complete the command: + +``` +echo> foo_ +``` + +Pressing `Tab` a second time requests possible completions: + +``` +echo> foo_ +foo_bar foo_baz foo_foo +``` + +Now typing `'f'`, `Tab`, and `Ent` completes and enters the command: + +``` +echo> foo_foo +You typed: 'foo_foo'. +echo> +``` + +Note that when the command line is empty, or when the typing so far does not match any command word, +`Tab` has no effect. ## Initialization File From 5eee0e0ac18a8d510e0ef60ff9b26481880139a7 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 20 Jul 2025 13:28:42 -0500 Subject: [PATCH 20/60] Reorder sections in Initialization File --- doc/for_users.md | 171 +++++++++++++++++++++++------------------------ 1 file changed, 85 insertions(+), 86 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index fb176725de..7f291a2606 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -330,87 +330,16 @@ whose path is determined thus: The initialization file may contain _directives_, _bindings_, and _variables_. -### Directives - -#### `$if`, `$else`, and `$endif` - -The initialization file may contain conditional directives, -each of which is an `$if/$endif` pair, -or an `$if/$else/$endif` triplet. - -- In the `$if/$endif` form, - the if-block consists of the lines between `$if` and `$endif`, - and there is no else-block: - - ``` - $if - # If-block - #endif - ``` - -- In the `$if/$else/$endif` form, - the if-block consists of the lines between `$if` and `$else`, - and the else-block consists of the lines between `$else` and `$endif`: - - ``` - $if - # If-block - $else - # Else-block. - #endif - ``` - -The `$if` directive takes a single argument that expresses a condition. -If the condition evaluates to `true`, -the expressions in the if-block are evaluated; -if it evaluates to `false`, -the expressions in the else-block (if any) are evaluated. - -The arguments: - -- `'mode=emacs'`: - evaluates to `true` if variable [editing-mode][editing-mode] is `'emacs'`, - `false` otherwise. -- `'mode=vi'`: - evaluates to `true` if variable [editing-mode][editing-mode] is `'vi'`, - `false` otherwise. -- `'Ruby'` or `'Reline'`: - evaluates to `true`. -- Anything else: - evaluates to `false`. - -Conditional directives may be nested. - -#### $include - -The `$include` directive takes a single argument, -which is the path to a file that is to be read and evaluated -as if it were part of the initialization file. - -Pro tip: You can use the `$include` directive to override (in full or in part) -another initialization file: - - ``` - $include - # Assignments and directives that will override. - # ... - ``` - - -### Bindings - -[TODO] - ### Variables -### `completion-ignore-case` +#### `completion-ignore-case` If set to `'on'`, Reline performs case-insensitive filename matching and completion. The default setting is `'off'`. -### `convert-meta` +#### `convert-meta` If set to `'on'`, affects 8-bit characters that have their high bits set (i.e., characters whose values in range `128..255`). @@ -421,7 +350,7 @@ and prefixing `Esc`. The default value is `'on'`, but Reline sets it to `'off'` if the locale contains characters whose encodings may include bytes with the eighth bit set. -### `disable-completion` +#### `disable-completion` If set to `'on'`, Reline inhibits word completion. Completion characters (`Tab`, `M-?`, and `M-*`) lose their usual meanings, @@ -429,21 +358,21 @@ and are inserted directly into the line. The default is `'off'`. -### `editing-mode` +#### `editing-mode` If set to `'emacs'`, the default key bindings are similar to Emacs; If set to `'vi'`, the default key bindings are similar to Vi. The default is `'emacs'`. -### `emacs-mode-string` +#### `emacs-mode-string` Specifies the mode string for Emacs mode; see [Mode Strings][mode strings]. The default is `'@'`. -### `enable-bracketed-paste` +#### `enable-bracketed-paste` When set to `'On'`, Reline is in _bracketed-paste_ mode, which means that it inserts each paste or yank @@ -454,7 +383,7 @@ bound to key sequences appearing in the pasted text. The default is `'on'`. -### `history-size` +#### `history-size` Set the maximum number of entries saved in the history list: @@ -464,14 +393,14 @@ Set the maximum number of entries saved in the history list: Default value is `'-1'` -### `isearch-terminators` +#### `isearch-terminators` Sets the strings of characters that terminate an incremental search without subsequently executing the character as a command. Default: `Esc` and `C-j`. -### `keymap` +#### `keymap` Sets the keymap for key binding commands. Values are: @@ -486,7 +415,7 @@ Default is `'emacs'`. The value of variable [editing-mode][editing-mode] also affects the default keymap. -### `keyseq-timeout` +#### `keyseq-timeout` Specifies the time (in milliseconds) that Reline will wait for further input when reading an ambiguous key sequence @@ -501,35 +430,35 @@ Reline waits until another key is pressed to decide which key sequence to comple The default `'500'`. -### `show-all-if-ambiguous` +#### `show-all-if-ambiguous` If set to `'on'`, input that has more than one possible completion cause the completions to be listed immediately (instead of ringing the bell). The default is `'off'`. -### `show-mode-in-prompt` +#### `show-mode-in-prompt` If set to `'on'`, prefixed the mode string to the displayed prompt; see [Mode Strings][mode strings]. The default is `'off'`. -### `vi-cmd-mode-string` +#### `vi-cmd-mode-string` Specifies the mode string for Vi command mode; see [Mode Strings][mode strings]. The default is ‘(cmd)’. -### `vi-ins-mode-string` +#### `vi-ins-mode-string` Specifies the mode string for Vi insertion mode; see [Mode Strings][mode strings]. The default is ‘(ins)’. -### Mode Strings +#### Mode Strings A _mode string_ is a string that is to be displayed immediately before the prompt string when variable [show-mode-in-prompt][show-mode-in-prompt] is set to `'on'`. @@ -561,6 +490,76 @@ Example (turns the mode string green): "\1\e[32mabcd \e[0m\2" ``` +### Bindings + +[TODO] + +### Directives + +#### `$if`, `$else`, and `$endif` + +The initialization file may contain conditional directives, +each of which is an `$if/$endif` pair, +or an `$if/$else/$endif` triplet. + +- In the `$if/$endif` form, + the if-block consists of the lines between `$if` and `$endif`, + and there is no else-block: + + ``` + $if + # If-block + #endif + ``` + +- In the `$if/$else/$endif` form, + the if-block consists of the lines between `$if` and `$else`, + and the else-block consists of the lines between `$else` and `$endif`: + + ``` + $if + # If-block + $else + # Else-block. + #endif + ``` + +The `$if` directive takes a single argument that expresses a condition. +If the condition evaluates to `true`, +the expressions in the if-block are evaluated; +if it evaluates to `false`, +the expressions in the else-block (if any) are evaluated. + +The arguments: + +- `'mode=emacs'`: + evaluates to `true` if variable [editing-mode][editing-mode] is `'emacs'`, + `false` otherwise. +- `'mode=vi'`: + evaluates to `true` if variable [editing-mode][editing-mode] is `'vi'`, + `false` otherwise. +- `'Ruby'` or `'Reline'`: + evaluates to `true`. +- Anything else: + evaluates to `false`. + +Conditional directives may be nested. + +#### $include + +The `$include` directive takes a single argument, +which is the path to a file that is to be read and evaluated +as if it were part of the initialization file. + +Pro tip: You can use the `$include` directive to override (in full or in part) +another initialization file: + + ``` + $include + # Assignments and directives that will override. + # ... + ``` + [alt key]: https://en.wikipedia.org/wiki/Alt_key [ansi escape codes]: https://en.wikipedia.org/wiki/ANSI_escape_code [arrow keys]: https://en.wikipedia.org/wiki/Arrow_keys From 339548c5ffdc30805c875a9d19da463f0ff596e0 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 21 Jul 2025 16:19:55 -0500 Subject: [PATCH 21/60] Key bindings --- doc/for_users.md | 82 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 77 insertions(+), 5 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index 7f291a2606..ef71a6bdb9 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -83,7 +83,7 @@ then the `k` key is then pressed, and both are released. Almost any character can have "meta" version: `M-c`, `M->`, `M-#`, etc. -## The Basics +## Reline Basics Reline lets you edit typed command-line text. @@ -318,6 +318,17 @@ Note that when the command line is empty, or when the typing so far does not mat ## Initialization File +A Reline application has default key bindings and variable definitions, +as determined by the application itself. + +You can customize the application's behavior by specifying key bindings and variable definitions +in an _initialization file_. +The initialization file may define: + +- [Key Bindings][key bindings]: Definitions relating keys to variables. +- [Variables][variables]: +- [Directives][directives]. + When a Reline application starts, it reads a user-provided initialization file, whose path is determined thus: @@ -328,10 +339,10 @@ whose path is determined thus: - Otherwise, `'~/.config/readline/inputrc'`. - Otherwise, no initialization file is read. -The initialization file may contain _directives_, _bindings_, and _variables_. - ### Variables +The initialization file may re-define certain variables. + #### `completion-ignore-case` If set to `'on'`, Reline performs case-insensitive @@ -490,9 +501,66 @@ Example (turns the mode string green): "\1\e[32mabcd \e[0m\2" ``` -### Bindings +### Key Bindings + +#### Key Sequences and Macros + +You can define a _macro_ by binding a _key sequence_ to some text. +The key sequence specifies a sequence of one or more keys that are to be mapped +to text that is to be inserted when the sequence is typed as input. + +This example binds a key sequence to the _macro_ text, +which means that in the application pressing `C-x` followed by `M-r` inserts the text `'Ruby!'`: + +``` +"\C-x\M-r": "Ruby!" +``` + +Note that: + +- The key sequence is in double-quotes. +- There is no space between the two key specifications. +- The key sequence is immediately followed by a colon (`':'`); no intervening whitespace. +- The colon may be separated from the following text by whitespace. +- The text is in double-quotes. +- The first key must be specified in an escaped notation + (not just a regular character). + + +More examples: + +``` +"\M-x": "Alt-x" # Single meta character. +"\C-a": "Ctrl-a" # Single control character. +"\C-x\C-y": "Ctrl-x, Ctrl-y" # Multiple keys. +"\C-xm": "Ctrl-x, m" # Control key followed by regular character. + +"\\": "Backslash" # Backslash character. +"\"": "Double-quote" # Double-quote character. +"\'": "Single-quote" # Single-quote character. + +"\a": "Bell" +"\b": "Backspace" +"\d": "Delete" +# Probably not a good idea to interfere with whitespace. +# "\f": "Form-feed" +# "\n": "Newline" +# "\r": "Carriage return" +# "\t": "Horizontal tab" +# "\v": "Vertical tab" + +"\001": "Ctrl-a" # Octal number. +"\x02": "Ctrl-b" # Hexadecimal number. +``` + +#### Key Sequences and Methods + + +#### Key Names + +Meta-L: " | less" +Meta-S: "sudo " -[TODO] ### Directives @@ -570,6 +638,7 @@ another initialization file: [control key]: https://en.wikipedia.org/wiki/Control_key [debug]: https://github.com/ruby/debug [delete key]: https://en.wikipedia.org/wiki/Delete_key +[directives]: rdoc-ref:for_users.md@Directives [editing-mode]: rdoc-ref:for_users.md@editing-mode [emacs-mode-string]: rdoc-ref:for_users.md@emacs-mode-string [end key]: https://en.wikipedia.org/wiki/End_key @@ -577,6 +646,7 @@ another initialization file: [escape key]: https://en.wikipedia.org/wiki/Esc_key [home key]: https://en.wikipedia.org/wiki/Home_key [irb]: https://ruby.github.io/irb/index.html +[key bindings]: rdoc-ref:for_users.md@Key+Bindings [mode strings]: rdoc-ref:for_users.md@Mode+Strings [repl]: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop [ri]: https://ruby.github.io/rdoc/RI_md.html @@ -584,6 +654,7 @@ another initialization file: [space bar]: https://en.wikipedia.org/wiki/Space_bar [stack]: https://en.wikipedia.org/wiki/Stack_(abstract_data_type) [tab key]: https://en.wikipedia.org/wiki/Tab_key +[variables]: rdoc-ref:for_users.md@Variables [vi-cmd-mode-string]: rdoc-ref:for_users.md@vi-cmd-mode-string [vi-ins-mode-string]: rdoc-ref:for_users.md@vi-ins-mode-string [your reline]: rdoc-ref:README.md@Your+Reline @@ -592,3 +663,4 @@ another initialization file: - Resolve all C- and M- from Gnu doc. - Doc which commands accept arguments. +- Multi-line editing. From 50fb3486097695c98ae41c6d682f8a3ae8881006 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 22 Jul 2025 14:54:54 -0500 Subject: [PATCH 22/60] More on bindings --- doc/for_users.md | 129 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 118 insertions(+), 11 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index ef71a6bdb9..74305b288f 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -518,11 +518,11 @@ which means that in the application pressing `C-x` followed by `M-r` inserts the Note that: -- The key sequence is in double-quotes. -- There is no space between the two key specifications. -- The key sequence is immediately followed by a colon (`':'`); no intervening whitespace. +- The key sequence must be enclosed by double-quotes. +- There may be no space between the two key specifications. +- The key sequence must be immediately followed by a colon (`':'`); no intervening whitespace. - The colon may be separated from the following text by whitespace. -- The text is in double-quotes. +- The text must be enclosed by double-quotes. - The first key must be specified in an escaped notation (not just a regular character). @@ -530,36 +530,143 @@ Note that: More examples: ``` +# Meta characters and control characters. "\M-x": "Alt-x" # Single meta character. "\C-a": "Ctrl-a" # Single control character. "\C-x\C-y": "Ctrl-x, Ctrl-y" # Multiple keys. "\C-xm": "Ctrl-x, m" # Control key followed by regular character. +# Escaped regular characters. "\\": "Backslash" # Backslash character. "\"": "Double-quote" # Double-quote character. "\'": "Single-quote" # Single-quote character. +# Special escapes for certain control characters. "\a": "Bell" -"\b": "Backspace" -"\d": "Delete" -# Probably not a good idea to interfere with whitespace. +# (Probably not a good idea to interfere with these.) +# "\b": "Backspace" +# "\d": "Delete" # "\f": "Form-feed" # "\n": "Newline" # "\r": "Carriage return" # "\t": "Horizontal tab" # "\v": "Vertical tab" -"\001": "Ctrl-a" # Octal number. -"\x02": "Ctrl-b" # Hexadecimal number. +# Other forms for the key sequence. +"\001": "Ctrl-a" # Octal number; begins with "\0". +"\x02": "Ctrl-b" # Hexadecimal number; begins with "\x". ``` #### Key Sequences and Methods +You can bind a key sequence to a Reline method, +so that the method is called when the key sequence is typed as input. -#### Key Names +This example binds a key sequence to the method `ed_clear_screen`, +which means that in the application pressing `Alt-x` clears the screen +and reprints the prompt at the top: +``` +"\M-x": ed_clear_screen +``` + +This binding is the same as the default binding for `C-l`. +Note that this new binding would override the old one, if any, for that key, +but does not disturb other bindings (`C-l` is still bound to `ed_clear_screen`). + +#### Methods + +These are the methods available for binding by a key or key sequence: + +- `ed_argument_digit(key)` +- `ed_beginning_of_history(key)` +- `ed_clear_screen(key)` +- `ed_delete_next_char(key, arg: 1)` +- `ed_delete_prev_char(key, arg: 1)` +- `ed_delete_prev_word(key)` +- `ed_digit(key)` +- `ed_end_of_history(key)` +- `ed_kill_line(key)` +- `ed_move_to_beg(key)` +- `ed_move_to_end(key)` +- `ed_newline(key)` +- `ed_next_char(key, arg: 1)` +- `ed_next_history(key, arg: 1)` +- `ed_prev_char(key, arg: 1)` +- `ed_prev_history(key, arg: 1)` +- `ed_prev_word(key)` +- `ed_search_next_history(key, arg: 1)` +- `ed_search_prev_history(key, arg: 1)` +- `ed_transpose_chars(key)` +- `ed_transpose_words(key)` +- `ed_unassigned(key) end # do nothing` +- `em_capitol_case(key)` +- `em_delete(key)` +- `em_delete_next_word(key)` +- `em_delete_or_list(key)` +- `em_delete_prev_char(key, arg: 1)` +- `em_exchange_mark(key)` +- `em_kill_line(key)` +- `em_kill_region(key)` +- `em_lower_case(key)` +- `em_next_word(key)` +- `em_set_mark(key)` +- `em_upper_case(key)` +- `em_yank(key)` +- `em_yank_pop(key)` +- `emacs_editing_mode(key)` +- `incremental_search_history(key)` +- `key_delete(key)` +- `key_newline(key)` +- `process_key(key, method_symbol)` +- `run_for_operators(key, method_symbol)` +- `search_next_char(key, arg, need_prev_char: false, inclusive: false)` +- `search_prev_char(key, arg, need_next_char = false)` +- `vi_add(key)` +- `vi_add_at_eol(key)` +- `vi_change_meta(key, arg: nil)` +- `vi_change_to_eol(key)` +- `vi_command_mode(key)` +- `vi_delete_meta(key, arg: nil)` +- `vi_delete_prev_char(key)` +- `vi_editing_mode(key)` +- `vi_end_big_word(key, arg: 1, inclusive: false)` +- `vi_end_word(key, arg: 1, inclusive: false)` +- `vi_first_print(key)` +- `vi_histedit(key)` +- `vi_insert(key)` +- `vi_insert_at_bol(key)` +- `vi_join_lines(key, arg: 1)` +- `vi_kill_line_prev(key)` +- `vi_list_or_eof(key)` +- `vi_next_big_word(key, arg: 1)` +- `vi_next_char(key, arg: 1, inclusive: false)` +- `vi_next_word(key, arg: 1)` +- `vi_paste_next(key, arg: 1)` +- `vi_paste_prev(key, arg: 1)` +- `vi_prev_big_word(key, arg: 1)` +- `vi_prev_char(key, arg: 1)` +- `vi_prev_word(key, arg: 1)` +- `vi_replace_char(key, arg: 1)` +- `vi_search_next(key)` +- `vi_search_prev(key)` +- `vi_to_column(key, arg: 0)` +- `vi_to_history_line(key)` +- `vi_to_next_char(key, arg: 1, inclusive: false)` +- `vi_to_prev_char(key, arg: 1)` +- `vi_yank(key, arg: nil)` +- `vi_zero(key)` + +#### Key Names, Macros, and Methods + +You can bind a single key to text or a method using its _key name_ +(instead of the key sequence notation): + +Control-b: ed_clear_screen Meta-L: " | less" -Meta-S: "sudo " + +#### Methods + ### Directives From 42ca88df4ed9a346af5a1ab3be8a8f0d534be0f3 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 22 Jul 2025 15:12:14 -0500 Subject: [PATCH 23/60] More on bindings --- doc/for_users.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index 74305b288f..14c0bce6a8 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -561,6 +561,7 @@ More examples: You can bind a key sequence to a Reline method, so that the method is called when the key sequence is typed as input. +See [Methods](rdoc-ref:for_users.md@Methods). This example binds a key sequence to the method `ed_clear_screen`, which means that in the application pressing `Alt-x` clears the screen @@ -574,6 +575,14 @@ This binding is the same as the default binding for `C-l`. Note that this new binding would override the old one, if any, for that key, but does not disturb other bindings (`C-l` is still bound to `ed_clear_screen`). +#### Key Names, Macros, and Methods + +You can bind a single key to text or a method using its _key name_ +(instead of the key sequence notation): + +Control-b: ed_clear_screen +Meta-L: " | less" + #### Methods These are the methods available for binding by a key or key sequence: @@ -657,15 +666,6 @@ These are the methods available for binding by a key or key sequence: - `vi_yank(key, arg: nil)` - `vi_zero(key)` -#### Key Names, Macros, and Methods - -You can bind a single key to text or a method using its _key name_ -(instead of the key sequence notation): - -Control-b: ed_clear_screen -Meta-L: " | less" - -#### Methods From 42014fd49d0c8234d7a8ccb178e97f7621cde7b8 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 22 Jul 2025 15:39:22 -0500 Subject: [PATCH 24/60] More on bindings --- doc/for_users.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/doc/for_users.md b/doc/for_users.md index 14c0bce6a8..a50767f1e8 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -503,9 +503,25 @@ Example (turns the mode string green): ### Key Bindings -#### Key Sequences and Macros +In brief: -You can define a _macro_ by binding a _key sequence_ to some text. +``` +"\C-x\M-r": "Ruby!" # Key sequence bound to text. +"\C-x\M-c": ed_clear_screen # Key sequence bound to method. +Meta-l: " | less" # Key name bound to text. +Control-b: ed_clear_screen # Key name bound method. +``` + +A key or key sequence may be bound to: + +- Text to be inserted when the key or key sequence is typed in: + in effect a [macro][macro]. +- A Reline method that is to be called when the key or key sequence is typed in: + in effect an alias. + +#### Key Sequences + +You can bind a key sequence to text, defining a macro. The key sequence specifies a sequence of one or more keys that are to be mapped to text that is to be inserted when the sequence is typed as input. @@ -519,12 +535,12 @@ which means that in the application pressing `C-x` followed by `M-r` inserts the Note that: - The key sequence must be enclosed by double-quotes. +- The first key must be specified in an escaped notation + (not just a regular character). - There may be no space between the two key specifications. - The key sequence must be immediately followed by a colon (`':'`); no intervening whitespace. - The colon may be separated from the following text by whitespace. - The text must be enclosed by double-quotes. -- The first key must be specified in an escaped notation - (not just a regular character). More examples: @@ -557,8 +573,6 @@ More examples: "\x02": "Ctrl-b" # Hexadecimal number; begins with "\x". ``` -#### Key Sequences and Methods - You can bind a key sequence to a Reline method, so that the method is called when the key sequence is typed as input. See [Methods](rdoc-ref:for_users.md@Methods). @@ -575,13 +589,15 @@ This binding is the same as the default binding for `C-l`. Note that this new binding would override the old one, if any, for that key, but does not disturb other bindings (`C-l` is still bound to `ed_clear_screen`). -#### Key Names, Macros, and Methods +#### Key Names You can bind a single key to text or a method using its _key name_ (instead of the key sequence notation): +``` Control-b: ed_clear_screen Meta-L: " | less" +``` #### Methods @@ -754,6 +770,7 @@ another initialization file: [home key]: https://en.wikipedia.org/wiki/Home_key [irb]: https://ruby.github.io/irb/index.html [key bindings]: rdoc-ref:for_users.md@Key+Bindings +[macro]: https://en.wikipedia.org/wiki/Macro_(computer_science) [mode strings]: rdoc-ref:for_users.md@Mode+Strings [repl]: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop [ri]: https://ruby.github.io/rdoc/RI_md.html From ffb2a85efbefd3e8df49d7eb787c7db14d2aa159 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 9 Aug 2025 12:02:36 -0500 Subject: [PATCH 25/60] More --- doc/for_users.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/for_users.md b/doc/for_users.md index a50767f1e8..e145a9a62a 100644 --- a/doc/for_users.md +++ b/doc/for_users.md @@ -43,6 +43,12 @@ Ruby itself uses Reline in these: ## Notations +Reline is basically a domain-specific language, +implemented via certain keys, control characters, and meta characters. + +To denote these here in the documentation, +we use certain notations. + ### Keys [Arrow Keys][arrow keys]: From a0fd2e5b4f436543126a507265344d902d36f3e3 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 3 Oct 2025 02:00:52 +0100 Subject: [PATCH 26/60] Reference maker --- doc/reference.rb | 155 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 doc/reference.rb diff --git a/doc/reference.rb b/doc/reference.rb new file mode 100644 index 0000000000..0c584d7fe9 --- /dev/null +++ b/doc/reference.rb @@ -0,0 +1,155 @@ +require 'rexml/document' + +include REXML + +Sections = { + 'Commands for Moving' => [ + %w[C-a beginning-of-line true], + %w[C-e end-of-line true], + %w[C-f forward-char true], + %w[C-b backward-char true], + %w[M-f forward-word true], + %w[M-b backward-word true], + %w[M-C-l clear-display true], + %w[C-l clear-screen false], + ], + 'Commands For Manipulating The History' => [ + ['Newline or Return', 'accept-line'], + %w[C-p previous-history], + %w[C-n next-history], + %w[M-< beginning-of-history], + %w[M-> end-of-history], + %w[C-r reverse-search-history], + %w[C-s forward-search-history], + %w[M-p non-incremental-reverse-search-history], + %w[M-n non-incremental-forward-search-history], + %w[M-C-y yank-nth-arg], + ['M-. or M-_', 'yank-last-arg'], + %w[C-o operate-and-get-next], + ], + 'Commands For Changing Text' => [ + ['usually C-d', 'end-of-file'], + %w[C-d delete-char], + %w[Rubout backward-delete-char], + ['C-q or C-v', 'quoted-insert'], + %w[M-TAB tab-insert], + ['a, b, A, 1, !, …', 'self-insert'], + %w[C-t transpose-chars], + %w[M-t transpose-words], + %w[M-u upcase-word], + %w[M-l downcase-word], + %w[M-c capitalize-word], + ], + 'Killing and Yanking' => [ + %w[C-k kill-line], + ['C-x Rubout', 'backward-kill-line'], + %w[C-u unix-line-discard], + %w[M-d kill-word], + %w[M-DEL backward-kill-word], + %w[C-w unix-word-rubout], + %w[C-y yank], + %w[M-y yank-pop], + ], + 'Specifying Numeric Arguments' => [ + ['M-0, M-1, … M--', 'digit-argument'] + ], + 'Letting Readline Type for You' => [ + %w[TAB complete], + %w[M-? possible-completions], + %w[M-* insert-completions], + ] +} +Headings = %w[ Keys Command reline debug irb ri ] + +def td_for(value) + td = Element.new('td') + td.add_attribute('align', 'center') + case value + when 'true' + font = Element.new('font') + font.add_attribute('color', 'green') + td.add_element(font) + td.text = 'Yes' + when 'false' + font = Element.new('font') + font.add_attribute('color', 'red') + td.add_element(font) + td.text = 'No' + when nil + font = Element.new('font') + font.add_attribute('color', 'gray') + td.add_element(font) + td.text = '?' + else + raise value.to_s + end + td +end + +# The order matters here. +Escapes = { + '_' => '_005f', # Must be first.. + '-' => '_002d', + '(' => '_0028', + ')' => '_0029', + '<' => '_003c', + '>' => '_003e', + '.' => '_002e', + ',' => '_002c', + '…' => '_2026', + '?' => '_003f', + '*' => '_002a', + '!' => '_0021', + ' ' => '-' # Must be last. +} + +def escape(keys, command) + s = "#{command} (#{keys})" + Escapes.each_pair do |old, new| + s.gsub!(old, new) + end + s +end + +doc = Document.new +doc.add_element(html = Element.new('html')) +html.add_element(head = Element.new('head')) +html.add_element(body = Element.new('body')) +Sections.each do |title, commands| + html.add_element(h2 = Element.new('h2')) + h2.text = title + html.add_element(table = Element.new('table')) + table.add_attribute('border', 1) + table.add_element(tr = Element.new('tr')) + Headings.each_with_index do |heading, i| + tr.add_element(th = Element.new('th')) + th.add_attribute('width', '10%') if i > 1 + th.text = heading + end + commands.each do |data| + keys, command, reline, debug, irb, ri = data + table.add_element(tr = Element.new('tr')) + # Cell for Keys. + tr.add_element(td = Element.new('td')) + td.add_attribute('align', 'center') + td.add_element(code = Element.new('code')) + code.text = keys + # Cell for Command. + tr.add_element(td = Element.new('td')) + td.add_element(a = Element.new('a')) + href = 'https://tiswww.case.edu/php/chet/readline/readline.html#index-' + + escape(keys, command) + a.add_attribute('href', href) + a.add_element(code = Element.new('code')) + code.text = command + + tr.add_element(td_for(reline)) + tr.add_element(td_for(debug)) + tr.add_element(td_for(irb)) + tr.add_element(td_for(ri)) + + end +end + +doc.write(indent: 2) + From 8431f88f8e029180f8a68584ce6d15a98887bba2 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 3 Oct 2025 02:32:57 +0100 Subject: [PATCH 27/60] Reference maker --- doc/reference.rb | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/reference.rb b/doc/reference.rb index 0c584d7fe9..ee49d00c8b 100644 --- a/doc/reference.rb +++ b/doc/reference.rb @@ -57,6 +57,27 @@ %w[TAB complete], %w[M-? possible-completions], %w[M-* insert-completions], + ], + 'Keyboard Macros' => [ + ['C-x (', 'start-kbd-macro'], + ['C-x )', 'end-kbd-macro'], + ['C-x e', 'call-last-kbd-macro'], + ], + 'Some Miscellaneous Commands' => [ + ['C-x C-r', 're-read-init-file'], + %w[C-g abort], + ['M-A, M-B, M-x, …', 'do-lowercase-version'], + %w[ESC prefix-meta], + ['C-_ or C-x C-u', 'undo'], + %w[M-r revert-line], + %w[M-~ tilde-expand], + %w[C-@ set-mark], + ['C-x C-x', 'exchange-point-and-mark'], + ['M-C-]', 'character-search-backward'], + %w[M-# insert-comment], + %w[M-x execute-named-command], + %w[C-e emacs-editing-mode], + %w[M-C-j vi-editing-mode], ] } Headings = %w[ Keys Command reline debug irb ri ] @@ -100,6 +121,10 @@ def td_for(value) '?' => '_003f', '*' => '_002a', '!' => '_0021', + ']' => '_005d', + '~' => '_007e', + '#' => '_0023', + '@' => '_0040', ' ' => '-' # Must be last. } From d29b8a9b18b78852ce3dbb1d81a1e137660f723e Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 3 Oct 2025 03:04:23 +0100 Subject: [PATCH 28/60] Reference maker --- doc/reference.rb | 110 +++++++++++++++++++++++------------------------ 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/doc/reference.rb b/doc/reference.rb index ee49d00c8b..9ab39a069f 100644 --- a/doc/reference.rb +++ b/doc/reference.rb @@ -10,77 +10,77 @@ %w[C-b backward-char true], %w[M-f forward-word true], %w[M-b backward-word true], - %w[M-C-l clear-display true], - %w[C-l clear-screen false], + %w[M-C-l clear-display false], + %w[C-l clear-screen true], ], 'Commands For Manipulating The History' => [ - ['Newline or Return', 'accept-line'], - %w[C-p previous-history], - %w[C-n next-history], - %w[M-< beginning-of-history], - %w[M-> end-of-history], - %w[C-r reverse-search-history], - %w[C-s forward-search-history], - %w[M-p non-incremental-reverse-search-history], - %w[M-n non-incremental-forward-search-history], - %w[M-C-y yank-nth-arg], - ['M-. or M-_', 'yank-last-arg'], - %w[C-o operate-and-get-next], + ['Newline or Return', 'accept-line', 'true'], + %w[C-p previous-history false], + %w[C-n next-history false], + %w[M-< beginning-of-history false], + %w[M-> end-of-history false], + %w[C-r reverse-search-history true], + %w[C-s forward-search-history false], + %w[M-p non-incremental-reverse-search-history true], + %w[M-n non-incremental-forward-search-history true], + %w[M-C-y yank-nth-arg false], + ['M-. or M-_', 'yank-last-arg', 'false'], + %w[C-o operate-and-get-next false], ], 'Commands For Changing Text' => [ - ['usually C-d', 'end-of-file'], - %w[C-d delete-char], - %w[Rubout backward-delete-char], - ['C-q or C-v', 'quoted-insert'], - %w[M-TAB tab-insert], - ['a, b, A, 1, !, …', 'self-insert'], - %w[C-t transpose-chars], - %w[M-t transpose-words], - %w[M-u upcase-word], - %w[M-l downcase-word], - %w[M-c capitalize-word], + ['usually C-d', 'end-of-file', 'true'], + %w[C-d delete-char true], + %w[Rubout backward-delete-char true], + ['C-q or C-v', 'quoted-insert', 'false'], + %w[M-TAB tab-insert false], + ['a, b, A, 1, !, …', 'self-insert', 'true'], + %w[C-t transpose-chars false], + %w[M-t transpose-words false], + %w[M-u upcase-word false], + %w[M-l downcase-word false], + %w[M-c capitalize-word false], ], 'Killing and Yanking' => [ - %w[C-k kill-line], - ['C-x Rubout', 'backward-kill-line'], - %w[C-u unix-line-discard], - %w[M-d kill-word], - %w[M-DEL backward-kill-word], - %w[C-w unix-word-rubout], - %w[C-y yank], - %w[M-y yank-pop], + %w[C-k kill-line true], + ['C-x Rubout', 'backward-kill-line', 'false'], + %w[C-u unix-line-discard false], + %w[M-d kill-word true], + %w[M-DEL backward-kill-word true], + %w[C-w unix-word-rubout true], + %w[C-y yank true], + %w[M-y yank-pop true], ], 'Specifying Numeric Arguments' => [ - ['M-0, M-1, … M--', 'digit-argument'] + ['M-0, M-1, … M--', 'digit-argument', 'false'] ], 'Letting Readline Type for You' => [ - %w[TAB complete], - %w[M-? possible-completions], - %w[M-* insert-completions], + %w[TAB complete true], + %w[M-? possible-completions false], + %w[M-* insert-completions false], ], 'Keyboard Macros' => [ - ['C-x (', 'start-kbd-macro'], - ['C-x )', 'end-kbd-macro'], - ['C-x e', 'call-last-kbd-macro'], + ['C-x (', 'start-kbd-macro', 'false'], + ['C-x )', 'end-kbd-macro', 'false'], + ['C-x e', 'call-last-kbd-macro', 'false'], ], 'Some Miscellaneous Commands' => [ - ['C-x C-r', 're-read-init-file'], - %w[C-g abort], - ['M-A, M-B, M-x, …', 'do-lowercase-version'], - %w[ESC prefix-meta], - ['C-_ or C-x C-u', 'undo'], - %w[M-r revert-line], - %w[M-~ tilde-expand], - %w[C-@ set-mark], - ['C-x C-x', 'exchange-point-and-mark'], - ['M-C-]', 'character-search-backward'], - %w[M-# insert-comment], - %w[M-x execute-named-command], - %w[C-e emacs-editing-mode], - %w[M-C-j vi-editing-mode], + ['C-x C-r', 're-read-init-file', 'false'], + %w[C-g abort true], + ['M-A, M-B, M-x, …', 'do-lowercase-version', 'false'], + %w[ESC prefix-meta true], + ['C-_ or C-x C-u', 'undo', 'false'], + %w[M-r revert-line false], + %w[M-~ tilde-expand false], + %w[C-@ set-mark false], + ['C-x C-x', 'exchange-point-and-mark', 'false'], + ['M-C-]', 'character-search-backward', 'false'], + %w[M-# insert-comment false], + %w[M-x execute-named-command false], + %w[C-e emacs-editing-mode true], + %w[M-C-j vi-editing-mode false], ] } -Headings = %w[ Keys Command reline debug irb ri ] +Headings = %w[ Keys Command reline irb ri debug] def td_for(value) td = Element.new('td') From 022031e3951fb0ebc1d7ff0e8b1fba4208f33077 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 3 Oct 2025 04:38:53 +0100 Subject: [PATCH 29/60] Reference maker --- doc/reference.rb | 52 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 12 deletions(-) diff --git a/doc/reference.rb b/doc/reference.rb index 9ab39a069f..16044c6fcd 100644 --- a/doc/reference.rb +++ b/doc/reference.rb @@ -2,6 +2,37 @@ include REXML +Style = <