fatty 0.99.8 → 0.99.8.2

data/README.md

@@ -1,111 +1,115 @@
-- [Introduction](#orgc5a13d2)
-- [Quick Start](#org6313195)
-  - [Installing](#org2ab7619)
-  - [Trying it Out with the \`fatty\` Demo](#orgbb6efa2)
-    - [Builtin commands](#org6a3da85)
-    - [Screenshots](#org03c4f60)
-      - [Command line editing](#org7f8b501)
-      - [Searchable Output](#orge6a2a61)
-      - [Paging Markdown](#org98556a8)
-      - [Popup Selection](#org87e5076)
-- [Usage](#org12e2b74)
-  - [Launching a Fatty Terminal](#org0be8165)
-    - [`on_accept`](#orgf42a055)
-      - [Parameters to `on_accept`](#orga5d3390)
-      - [The `line` parameter to `on_accept`](#org18111d5)
-      - [The callback parameter to `on_accept`](#org246af2b)
-      - [Output ordering](#org210dcba)
-      - [Long-running callbacks and interruption](#org5093875)
-      - [ANSI colors in output](#orgcf17f3b)
-    - [Other parameters to `Terminal.new`](#org825992c)
-  - [The Callback API](#org7874847)
-    - [`append(text, follow: true, role: nil)`](#org3a8e5be)
-    - [`append_now(text, follow: true, mode: nil, role: nil)`](#orga261846)
-    - [`markdown(text)`](#org2c6117a)
-    - [`status(text, role: :info)`](#org80d267c)
-    - [`good(text, replace: false, render: true)`](#orgb6de417)
-    - [`info(text, replace: false, render: true)`](#org63d40a7)
-    - [`warn(text, replace: false, render: true)`](#org1e44b90)
-    - [`error(text, replace: false, render: true)`](#orga6187bb)
-    - [`oops(text, replace: false, render: true)`](#orga75943f)
-    - [`alert(text, role: :info)`](#orgc92ba6a)
-    - [`prompt(prompt, initial: "", cancel_value: nil, history_key: nil, save_history: true)`](#orgfc95c42)
-    - [`check_interrupt!`](#orgc6a9c07)
-    - [`add_progress(label:, total: nil, style: :percent, role: :info, width: 40)`](#org68c4685)
-      - [Initialization `add_progress(label:, style: :percent, total: nil, role: :info, width: 40)`](#orgaf54268)
-      - [Update `update(current: nil, indicator: nil, render: false)`](#org63766b4)
-      - [Finish](#org489dabd)
-      - [Clear](#org499367c)
-    - [`choose(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)`](#org88dd294)
-    - [`choose_multi(prompt, choices:, cancel_value: nil)`](#org7cfc6fb)
-    - [`confirm(prompt, yes_label: "Yes", no_label: "No", cancel_value: false)`](#org24552a8)
-    - [`menu(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)`](#orgc7a266a)
-    - [`environment`](#org04ee12a)
-- [Default Interaction](#orgacd5f7c)
-  - [Parts of the Screen](#org11ef010)
-    - [Input Field](#org98aa3ba)
-    - [Output Pane](#orge520676)
-    - [Status Area](#org2582262)
-    - [Alert Area](#orgc32c00f)
-  - [Command-line Editing](#org4dfe709)
-    - [Input Context](#orga183f84)
-      - [Cursor Motion](#org81087f8)
-      - [Clearing](#org37f216d)
-      - [Undo and Redo](#org3ffee42)
-      - [Deletion and Killing](#org930cee7)
-      - [Yanking, Mark, and Region](#org324c2f6)
-      - [Count Prefix](#orgd8ab4ab)
-      - [History Navigation](#orgb63d0d0)
-      - [Completion](#org1732f5c)
-      - [Accept or Cancel](#orgf829904)
-    - [Paging Context](#orgf7f860e)
-    - [Searching Output](#orgb329bbd)
-      - [String and Regex Search](#orgc3fcc69)
-      - [Incremental Search](#org53d4559)
-- [Configuration](#orga0e6a57)
-  - [General Configuration `config.yml`](#org2d08557)
-    - [`word_char_re`](#org0df073b)
-    - [`esc_delay`](#org4288158)
-    - [`history`](#org973b5fe)
-      - [`file`](#orga1dcc95)
-      - [`max`](#org5f744d4)
-    - [`theme`](#org64941b1)
-    - [`truecolor`](#orge751b35)
-    - [`log`](#orgd56b3fd)
-      - [`file`](#org60dc0ba)
-      - [`level`](#orgeb194d3)
-      - [`tags`](#org823d99d)
-  - [Key code definitions `keydefs.yml`](#orge3d84e5)
-  - [Key bindings  `keybindings.yml`](#org2a9d985)
-    - [Key Names](#org47f10de)
-      - [Printable Keys](#orge517d82)
-      - [Curses and Fatty Named Keys](#org515f394)
-      - [Possibly Invisible Keys](#org3fa3e38)
-      - [Unnamed but Recognized Keys](#org96ea9b2)
-    - [Mouse Events](#org8888baf)
-    - [Modifiers](#org2ce52a8)
-    - [Contexts](#orgc4d7ddc)
-    - [Actions](#orgd327240)
-      - [Input buffer actions](#org0a51d38)
-      - [Input field actions](#org0156270)
-      - [Shell session actions](#org49f5b2c)
-      - [Pager actions](#org51e582e)
-      - [Pager search actions](#org9c6e828)
-      - [Popup actions](#orgf26b607)
-      - [Prompt popup actions](#org5abe8ab)
-      - [Utility Actions](#orgb190c08)
-  - [Themes `themes/`](#org19a3e32)
-    - [Distributed Themes](#orge0db426)
-    - [Custom Themes](#org23d543d)
-      - [Theme Name](#orgc7d4f2a)
-      - [Inheritance from Another Theme](#org7186f3f)
-      - [Inheritance within a Theme](#org85b6b26)
-      - [Theme Roles](#org6741eee)
-      - [Role Colors and Attributes and Frame Style](#org33b14c5)
-
-
-
-<a id="orgc5a13d2"></a>
+- [Introduction](#orgc090857)
+- [Quick Start](#org844168e)
+  - [Installing](#orge9b8048)
+  - [Trying it Out with the \`fatty\` Demo](#org9284335)
+    - [Builtin commands](#orga9c3071)
+    - [Screenshots](#org0e411f4)
+      - [Command line editing](#org68abe96)
+      - [Searchable Output](#orgca94584)
+      - [Paging Markdown](#org458ad81)
+      - [Popup Selection](#orgfb3da2e)
+- [Usage](#orgf00946d)
+  - [Launching a Fatty Terminal](#orgc5ba25f)
+    - [`on_accept`](#orgb046bd4)
+      - [Parameters to `on_accept`](#orgd3107f2)
+      - [The `line` parameter to `on_accept`](#orga7ac101)
+      - [The callback parameter to `on_accept`](#org7590a60)
+      - [Output ordering](#org640dc41)
+      - [Long-running callbacks and interruption](#org34665cc)
+      - [ANSI colors in output](#org103299f)
+    - [Other parameters to `Terminal.new`](#org456c2ad)
+  - [The Callback API](#org5f103bb)
+    - [`append(text, follow: true, role: nil)`](#orgf90a804)
+    - [`append_now(text, follow: true, mode: nil, role: nil)`](#org96421ae)
+    - [`markdown(text)`](#orge61ad54)
+    - [`status(text, role: :info)`](#org8d20d95)
+    - [`good(text, replace: false, render: true)`](#org4430a3b)
+    - [`info(text, replace: false, render: true)`](#org60083e9)
+    - [`warn(text, replace: false, render: true)`](#org98a2b3c)
+    - [`error(text, replace: false, render: true)`](#orgd4f04ac)
+    - [`oops(text, replace: false, render: true)`](#org807c2ce)
+    - [`alert(text, role: :info)`](#org96063bb)
+    - [`prompt(prompt, initial: "", cancel_value: nil, history_key: nil, save_history: true)`](#org7bb5b38)
+    - [`check_interrupt!`](#orga338e63)
+    - [`add_progress(label:, total: nil, style: :percent, role: :info, width: 40)`](#orgcb79368)
+      - [Initialization `add_progress(label:, style: :percent, total: nil, role: :info, width: 40)`](#org789160a)
+      - [Update `update(current: nil, indicator: nil, render: false)`](#orge7cfc41)
+      - [Finish](#orgf7533d1)
+      - [Clear](#orgede5f40)
+    - [`choose(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)`](#org5994004)
+    - [`choose_multi(prompt, choices:, cancel_value: nil)`](#orgd82f0ec)
+    - [`confirm(prompt, yes_label: "Yes", no_label: "No", cancel_value: false)`](#orga06503c)
+    - [`menu(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)`](#org6463694)
+    - [`suspend(&block)`](#org5fe1480)
+    - [`environment`](#orgd5bf8ee)
+  - [Terminal Methods](#org1c1d3fc)
+    - [`Teminal#suspend(&block)`](#org5e187ea)
+- [Default Interaction](#org47f52fd)
+  - [Parts of the Screen](#orga27a6ad)
+    - [Input Field](#orgbd88b45)
+    - [Output Pane](#orge98ad82)
+    - [Status Area](#org9831bf4)
+    - [Alert Area](#org5d9a3d5)
+  - [Command-line Editing](#orge76ca34)
+    - [Input Context](#org2aaff21)
+      - [Cursor Motion](#org14d68c9)
+      - [Clearing](#orgd13c620)
+      - [Undo and Redo](#org54d5f7a)
+      - [Deletion and Killing](#orgcf696da)
+      - [Yanking, Mark, and Region](#orga7f73fe)
+      - [Count Prefix](#org29d1c16)
+      - [History Navigation](#org511da2c)
+      - [Completion](#org1648a2a)
+      - [Accept or Cancel](#org9afdcdd)
+    - [Paging Context](#org8c38312)
+    - [Searching Output](#org567c0c0)
+      - [String and Regex Search](#orgbf77d1b)
+      - [Incremental Search](#orgda99c8d)
+- [Configuration](#orgfd272b4)
+  - [General Configuration `config.yml`](#org8e3d563)
+    - [`word_char_re`](#org773e7d4)
+    - [`esc_delay`](#org8229289)
+    - [`history`](#org5789fd5)
+      - [`file`](#org1959b2c)
+      - [`max`](#orgbb18fb6)
+    - [`theme`](#org8a3ecd9)
+    - [`truecolor`](#org9ba735f)
+    - [`log`](#org13b974b)
+      - [`file`](#orgb93c9b8)
+      - [`level`](#org0fb9a08)
+      - [`tags`](#org2247ba8)
+  - [Key code definitions `keydefs.yml`](#org11c2491)
+  - [Key bindings  `keybindings.yml`](#orgab7252d)
+    - [Key Names](#org370c8e8)
+      - [Printable Keys](#org3a580c2)
+      - [Curses and Fatty Named Keys](#org1e9bcad)
+      - [Possibly Invisible Keys](#orgec1f50a)
+      - [Unnamed but Recognized Keys](#org56d8cd7)
+    - [Mouse Events](#org0eda788)
+    - [Modifiers](#orgbffc2cf)
+    - [Contexts](#org0662dd0)
+    - [Actions](#org55e8a55)
+      - [Input buffer actions](#org5c651ab)
+      - [Input field actions](#orga37809c)
+      - [Shell session actions](#org5bd909b)
+      - [Pager actions](#orgcba2897)
+      - [Pager search actions](#org2e0b296)
+      - [Popup actions](#org76791bc)
+      - [Prompt popup actions](#org6b1188d)
+      - [Utility Actions](#orgf63740e)
+  - [Themes `themes/`](#org3856a84)
+    - [Distributed Themes](#org88b0217)
+    - [Custom Themes](#org8769885)
+      - [Theme Name](#orgd425d6c)
+      - [Inheritance from Another Theme](#org1e1695f)
+      - [Inheritance within a Theme](#org8557acf)
+      - [Theme Roles](#org76e4687)
+      - [Role Colors and Attributes and Frame Style](#orge738a22)
+    - [The `themer` helper](#orgdd1744c)
+
+
+
+<a id="orgc090857"></a>
 
 # Introduction
 
@@ -133,12 +137,12 @@ In other words, fatty allows you to write a terminal-based REPL of your choosing
 `Fatty` is *not* a terminal emulator but runs on top of one.
 
 
-<a id="org6313195"></a>
+<a id="org844168e"></a>
 
 # Quick Start
 
 
-<a id="org2ab7619"></a>
+<a id="orge9b8048"></a>
 
 ## Installing
 
@@ -149,7 +153,7 @@ $ gem install fatty
 ```
 
 
-<a id="orgbb6efa2"></a>
+<a id="org9284335"></a>
 
 ## Trying it Out with the \`fatty\` Demo
 
@@ -158,7 +162,7 @@ Once installed, you can try out `fatty` with the included program called `fatty`
 Once inside `fatty` you will be prompted with a prompt that names your current directory. Type `help` to get a summary of the builtin commands available to you. If you type anything other than a builtin command, `fatty` attempts to run it as a shell command and displays the output.
 
 
-<a id="org6a3da85"></a>
+<a id="orga9c3071"></a>
 
 ### Builtin commands
 
@@ -192,12 +196,12 @@ Here are the commands builtin to `fatty`
 | colors                      | Display ANSI, 256-color, and X11 color diagnostics                      |
 
 
-<a id="org03c4f60"></a>
+<a id="org0e411f4"></a>
 
 ### Screenshots
 
 
-<a id="org7f8b501"></a>
+<a id="org68abe96"></a>
 
 #### Command line editing
 
@@ -206,7 +210,7 @@ Here is the command line, mid-edit showing a region selected and, in dim text to
 ![img](images/input_editing.png "Input editing showing region and predictive completion.")
 
 
-<a id="orge6a2a61"></a>
+<a id="orgca94584"></a>
 
 #### Searchable Output
 
@@ -215,7 +219,7 @@ While paging output, you can search for words, as here the user searches for the
 ![img](images/search_output.png "Searching for instances of `tty` in the output.")
 
 
-<a id="org98556a8"></a>
+<a id="org458ad81"></a>
 
 #### Paging Markdown
 
@@ -224,7 +228,7 @@ The `fatty` demo running the `markdown` command and paging the output. It shows
 ![img](images/page_markdown.png "Running the `fatty` demo `markdown` command.")
 
 
-<a id="org87e5076"></a>
+<a id="orgfb3da2e"></a>
 
 #### Popup Selection
 
@@ -233,17 +237,17 @@ One of the many "widgets" available through `fatty` is the ability to present th
 ![img](images/choose_popup.png "Running the `fatty` demo `choose` command.")
 
 
-<a id="org12e2b74"></a>
+<a id="orgf00946d"></a>
 
 # Usage
 
 
-<a id="org0be8165"></a>
+<a id="orgc5ba25f"></a>
 
 ## Launching a Fatty Terminal
 
 
-<a id="orgf42a055"></a>
+<a id="orgb046bd4"></a>
 
 ### `on_accept`
 
@@ -276,14 +280,14 @@ When a `fatty` application runs, `fatty` installs a few files if they do not exi
     -   `themes`, a directory of pre-defined theme definitions that you can choose from and add to by adding your own themes.
 
 
-<a id="orga5d3390"></a>
+<a id="orgd3107f2"></a>
 
 #### Parameters to `on_accept`
 
 The `on_accept` proc passed to an instance of `Fatty::Terminal` can take one or two parameters: (1) `line`, the edited line as it exists when the user types `RETURN` and (2) an optional callback parameter that you can use to access the facilities of `fatty`.
 
 
-<a id="org18111d5"></a>
+<a id="orga7ac101"></a>
 
 #### The `line` parameter to `on_accept`
 
@@ -324,7 +328,7 @@ Fatty::Terminal.new(
 ```
 
 
-<a id="org246af2b"></a>
+<a id="org7590a60"></a>
 
 #### The callback parameter to `on_accept`
 
@@ -349,7 +353,7 @@ Fatty::Terminal.new(
 The callback parameter responds to several methods that allow your application to interact with the user. They are documented below.
 
 
-<a id="org210dcba"></a>
+<a id="org640dc41"></a>
 
 #### Output ordering
 
@@ -374,7 +378,7 @@ Calls to `append_now` are different. They append text and immediately render a f
 At the end of the callback, `Fatty` finishes the command and updates the pager state. Output produced with `append_now` may therefore appear during the callback, while output from `append`, `markdown`, and the callback's return value appears after the callback returns.
 
 
-<a id="org5093875"></a>
+<a id="org34665cc"></a>
 
 #### Long-running callbacks and interruption
 
@@ -413,14 +417,14 @@ end
 ```
 
 
-<a id="orgcf17f3b"></a>
+<a id="org103299f"></a>
 
 #### ANSI colors in output
 
 Text passed to `append`, `append_now`, `status`, and `alert` may contain ANSI SGR color/style sequences. Fatty interprets those sequences relative to the current theme role, so an ANSI reset returns to the active Fatty role rather than to the terminal's physical default colors. `fatty` includes the nice [`Rainbow` gem](https://github.com/ku1ik/rainbow) for colorizing text as a convenience.
 
 
-<a id="org825992c"></a>
+<a id="org456c2ad"></a>
 
 ### Other parameters to `Terminal.new`
 
@@ -447,14 +451,14 @@ Fatty::Terminal.new(
 With that setup, commands entered in `~/src/byr` are favored when the terminal is again in `~/src/byr`, while commands entered elsewhere remain available as fallback history.
 
 
-<a id="org7874847"></a>
+<a id="org5f103bb"></a>
 
 ## The Callback API
 
 Here are the details on the messages that you can send to the callback parameter to the `on_accept` proc.
 
 
-<a id="org3a8e5be"></a>
+<a id="orgf90a804"></a>
 
 ### `append(text, follow: true, role: nil)`
 
@@ -463,7 +467,7 @@ Add the given text to the output pane. After a full page of output is produced,
 You can specify a "role" of `:good`, `:info`, `:warn`, or `:error` to color the output according to the current theme's coloring scheme for those roles. Those role names can be symbols or strings.
 
 
-<a id="orga261846"></a>
+<a id="org96421ae"></a>
 
 ### `append_now(text, follow: true, mode: nil, role: nil)`
 
@@ -474,7 +478,7 @@ Setting the mode to `:scrolling` or `:paging` determines whether the output is s
 You can specify a "role" of `:good`, `:info`, `:warn`, or `:error` to color the output according to the current theme's coloring scheme for those roles. Those role names can be symbols or strings.
 
 
-<a id="org2c6117a"></a>
+<a id="orge61ad54"></a>
 
 ### `markdown(text)`
 
@@ -494,7 +498,7 @@ and this should appear on the next line.
 ```
 
 
-<a id="org80d267c"></a>
+<a id="org8d20d95"></a>
 
 ### `status(text, role: :info)`
 
@@ -506,49 +510,49 @@ Display the text in the "status" area, the lines immediately above the input fie
 -   **:error:** colored something to suggest danger, usually some tone of red.
 
 
-<a id="orgb6de417"></a>
+<a id="org4430a3b"></a>
 
 ### `good(text, replace: false, render: true)`
 
 Display the text in the status area with the role :good.
 
 
-<a id="org63d40a7"></a>
+<a id="org60083e9"></a>
 
 ### `info(text, replace: false, render: true)`
 
 Display the text in the status area with the role :info.
 
 
-<a id="org1e44b90"></a>
+<a id="org98a2b3c"></a>
 
 ### `warn(text, replace: false, render: true)`
 
 Display the text in the status area with the role :warn.
 
 
-<a id="orga6187bb"></a>
+<a id="orgd4f04ac"></a>
 
 ### `error(text, replace: false, render: true)`
 
 Display the text in the status area with the role :error.
 
 
-<a id="orga75943f"></a>
+<a id="org807c2ce"></a>
 
 ### `oops(text, replace: false, render: true)`
 
 An alias for `error(text)`
 
 
-<a id="orgc92ba6a"></a>
+<a id="org96063bb"></a>
 
 ### `alert(text, role: :info)`
 
 Display the text in the one-line alert panel just below the input field. In the alert panel, the role only controls the foreground color, not the background.
 
 
-<a id="orgfc95c42"></a>
+<a id="org7bb5b38"></a>
 
 ### `prompt(prompt, initial: "", cancel_value: nil, history_key: nil, save_history: true)`
 
@@ -578,7 +582,7 @@ The `prompt` input has its own history facility separate from the history in the
 `prompt` returns whatever the user typed and returns `nil` if the user cancels with C-c or C-g unless you specify an alternative `cancel_value`.
 
 
-<a id="orgc6a9c07"></a>
+<a id="orga338e63"></a>
 
 ### `check_interrupt!`
 
@@ -589,7 +593,7 @@ The polling is throttled, so `check_interrupt!` may be called frequently. It sho
 Fatty catches `Fatty::Interrupt` at the callback boundary, finishes the current command, restores the terminal state, and resumes the normal input loop.
 
 
-<a id="org68c4685"></a>
+<a id="orgcb79368"></a>
 
 ### `add_progress(label:, total: nil, style: :percent, role: :info, width: 40)`
 
@@ -605,7 +609,7 @@ Display a progress widget in the status area to show the user that the system is
 -   **:trail:** display an "indicator" on each call of `update(indicator: <string>)`
 
 
-<a id="orgaf54268"></a>
+<a id="org789160a"></a>
 
 #### Initialization `add_progress(label:, style: :percent, total: nil, role: :info, width: 40)`
 
@@ -616,7 +620,7 @@ Display a progress widget in the status area to show the user that the system is
 -   **`width`:** The number of characters for the full widget display: it is only relevant for the bar styles and the trail style; otherwise it is ignored.
 
 
-<a id="org63766b4"></a>
+<a id="orge7cfc41"></a>
 
 #### Update `update(current: nil, indicator: nil, render: false)`
 
@@ -722,21 +726,21 @@ Fatty::Terminal.new(
 ```
 
 
-<a id="org489dabd"></a>
+<a id="orgf7533d1"></a>
 
 #### Finish
 
 As the prior examples illustrate, you can issue an ending message at the end of the process by calling `#finish` on the Progress object.
 
 
-<a id="org499367c"></a>
+<a id="orgede5f40"></a>
 
 #### Clear
 
 And, if you have occasion, you can clear the Progress by calling `#clear` on the Progress object.
 
 
-<a id="org88dd294"></a>
+<a id="org5994004"></a>
 
 ### `choose(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)`
 
@@ -802,7 +806,7 @@ Fatty::Terminal.new(
 ```
 
 
-<a id="org7cfc6fb"></a>
+<a id="orgd82f0ec"></a>
 
 ### `choose_multi(prompt, choices:, cancel_value: nil)`
 
@@ -820,7 +824,7 @@ Present a set of `choices:`, which can either be
 The `prompt` String (by default "Choose Many") can guide the user about the purpose of the choices.
 
 
-<a id="org24552a8"></a>
+<a id="orga06503c"></a>
 
 ### `confirm(prompt, yes_label: "Yes", no_label: "No", cancel_value: false)`
 
@@ -831,7 +835,7 @@ Present the user with a simple Yes/No choice using your choice of ways to expres
 `confirm` will return `false` on cancellation with C-c or C-g unless you provide an alternative `cancel_value:`, in which case it returns that.
 
 
-<a id="orgc7a266a"></a>
+<a id="org6463694"></a>
 
 ### `menu(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)`
 
@@ -878,7 +882,24 @@ If you want to set one of the choices as the initial choice, set `initial_choice
 If you want a value associated with the user's cancellation of the chooser with C-c or C-g, set `cancel_value:` to that value.
 
 
-<a id="org04ee12a"></a>
+<a id="org5fe1480"></a>
+
+### `suspend(&block)`
+
+The `suspend` method temporarily gives control of the terminal to the application while the supplied block runs. When the block finishes, Fatty restores its terminal state and redraws the interface.
+
+This is useful for running interactive terminal programs such as editors, debuggers, shells, or other programs that need direct access to the terminal.
+
+```ruby
+env.suspend do
+  system(ENV.fetch("EDITOR", "vi"), filename)
+end
+```
+
+The value of the block is returned by `suspend`. Terminal state is restored even if the block exits by raising an exception.
+
+
+<a id="orgd5bf8ee"></a>
 
 ### `environment`
 
@@ -915,59 +936,71 @@ The environment report also includes a nested `:curses` hash:
 | `:can_change_color` | Whether curses can redefine color values             |
 
 
-<a id="orgacd5f7c"></a>
+<a id="org1c1d3fc"></a>
+
+## Terminal Methods
+
+
+<a id="org5e187ea"></a>
+
+### `Teminal#suspend(&block)`
+
+Return control to the launching terminal, execute the given block, and return.
+
+
+<a id="org47f52fd"></a>
 
 # Default Interaction
 
 
-<a id="org11ef010"></a>
+<a id="orga27a6ad"></a>
 
 ## Parts of the Screen
 
 
-<a id="org98aa3ba"></a>
+<a id="orgbd88b45"></a>
 
 ### Input Field
 
 Just above the bottom of the screen where all the action takes place: it is a line for editing the input. It displays a prompt followed by an area in which you build the command line using `fatty's` editing facilities.
 
 
-<a id="orge520676"></a>
+<a id="orge98ad82"></a>
 
 ### Output Pane
 
 Most of the top part of the screen is reserved for displaying whatever output is sent to it with the `on_accept` callback to the `Terminal`. It can render colored ANSI-encoded strings and will page long output so you can view it a page at a time and even search the output.
 
 
-<a id="org2582262"></a>
+<a id="org9831bf4"></a>
 
 ### Status Area
 
 The one to four lines just above the Input Field that displays output to the user that is out of band for the Output Pane. Brief messages of confirmation, warning, or error can be displayed there so as to get the user's immediate attention. Progress bars also render there where their visibility is made prominent.
 
 
-<a id="orgc32c00f"></a>
+<a id="org5d9a3d5"></a>
 
 ### Alert Area
 
 Alerts are short-lived, non-scrolling messages shown below the input field. They are intended for user-visible conditions that require attention. `Fatty` uses this area to warn the user of unrecognized key codes and of unbound key presses.
 
 
-<a id="org4dfe709"></a>
+<a id="orge76ca34"></a>
 
 ## Command-line Editing
 
 `fatty` aims to have a full-featured command-line editor for editing a single line of text that is sent to the `on_accept` proc for the `Terminal`. The default keybindings are based on Emacs keybindings, but they are fully customizable. Implementing `vim`-like keybindings is not currently possible because `fatty` has no notion of editing "modes" as would be required for any kind of a modal editor&#x2014;at least not yet. Maybe some day.
 
 
-<a id="orga183f84"></a>
+<a id="org2aaff21"></a>
 
 ### Input Context
 
 When editing the input line or text input for widgets like the \`prompt\`, \`fatty\` provides emacs-like editing keybindings by default. Many of these commands can take a count prefix argument to repeat the command count times. For example, \`M-8 M-0 #\` will insert 80 '#' characters at the cursor.
 
 
-<a id="org81087f8"></a>
+<a id="org14d68c9"></a>
 
 #### Cursor Motion
 
@@ -991,7 +1024,7 @@ When editing the input line or text input for widgets like the \`prompt\`, \`fat
 | C-:left  | move cursor left one word         |
 
 
-<a id="org37f216d"></a>
+<a id="orgd13c620"></a>
 
 #### Clearing
 
@@ -1002,7 +1035,7 @@ This is one action that does not affect the input buffer but the output pane. It
 | C-l | clear the output pane |
 
 
-<a id="org3ffee42"></a>
+<a id="org54d5f7a"></a>
 
 #### Undo and Redo
 
@@ -1016,7 +1049,7 @@ This is one action that does not affect the input buffer but the output pane. It
 | M-/   | redo        |
 
 
-<a id="org930cee7"></a>
+<a id="orgcf696da"></a>
 
 #### Deletion and Killing
 
@@ -1036,7 +1069,7 @@ When the region is active, destructive editing commands kill the region rather t
 | M-t        | transpose words                |
 
 
-<a id="org324c2f6"></a>
+<a id="orga7f73fe"></a>
 
 #### Yanking, Mark, and Region
 
@@ -1064,7 +1097,7 @@ Notice that commands that normally delete characters or words, kill the region i
 | M-w        | copy the region                                   |
 
 
-<a id="orgd8ab4ab"></a>
+<a id="org29d1c16"></a>
 
 #### Count Prefix
 
@@ -1080,7 +1113,7 @@ Fatty follows the emacs convention of making `C-u` multiply the count prefix by
 | M-<digit> | accumulate a count argument                        |
 
 
-<a id="orgb63d0d0"></a>
+<a id="org511da2c"></a>
 
 #### History Navigation
 
@@ -1103,7 +1136,7 @@ You can navigate history items with the `up` and `down` keys as you would expect
 | C-r   | search the history in a popup                |
 
 
-<a id="org1732f5c"></a>
+<a id="org1648a2a"></a>
 
 #### Completion
 
@@ -1149,7 +1182,7 @@ You can navigate history items with the `up` and `down` keys as you would expect
     Just as with command line completion, you can invoke a popup of completions with `M-TAB` and a popup of possible file names will appear within which you may filter the candidates down by narrowing. Unlike other forms of completion, the file name completion popup allows you to fill out the path by navigating directories within the popup by hitting `TAB` or `right` to descend into a sub-directory or `S-TAB` or `left` to ascend to the parent directory. The popup title shows the path so far.
 
 
-<a id="orgf829904"></a>
+<a id="org9afdcdd"></a>
 
 #### Accept or Cancel
 
@@ -1165,7 +1198,7 @@ You can end a `fatty` session with `C-c` at the command line, or (only if the bu
 | C-d      | quit \`fatty\` only if the input line is empty         |
 
 
-<a id="orgf7f860e"></a>
+<a id="org8c38312"></a>
 
 ### Paging Context
 
@@ -1222,7 +1255,7 @@ You can add line numbers to the display while paging by using the `=` key.
 You can also "narrow" the output with `<`, which will prompt you for one or more terms to match. The output will then show only lines that match all the terms typed. To return to the full output, "widen" with `>`.
 
 
-<a id="orgb329bbd"></a>
+<a id="org567c0c0"></a>
 
 ### Searching Output
 
@@ -1231,21 +1264,21 @@ While paging, you can initiate a search of the output as indicated in the above
 After a search session has ended, `fatty` returns to paging but remembers the last search term and allows navigation among them with `n` and `N`: `n` searches in the direction of the last search and `N` searches in the opposite direction. Notice that the current search term and direction are added to the paging bar after the information on your location within the output.
 
 
-<a id="orgc3fcc69"></a>
+<a id="orgbf77d1b"></a>
 
 #### String and Regex Search
 
 `/` and `?` prompt for a fixed string and search forward or backward. `C-M-s` (or `C-/`) and `C-M-r` (or `C-?`) perform the corresponding regular-expression searches. Accepting the search leaves the selected match active for later navigation with `n` and `N`.
 
 
-<a id="org53d4559"></a>
+<a id="orgda99c8d"></a>
 
 #### Incremental Search
 
 `C-s` and `C-r` begin forward or backward incremental search. The output moves to matching text as the search term is edited. Accepting commits the match; canceling restores the output position from before the search began.
 
 
-<a id="orga0e6a57"></a>
+<a id="orgfd272b4"></a>
 
 # Configuration
 
@@ -1263,7 +1296,7 @@ The default user-specific configuration directory follows `XDG_CONFIG_HOME` if i
 In addition to the user-specific configuration, fatty will read app-specific configuration files from `~/.config/fatty/apps/<app_name>` if `Terminal` was given an `app_name` parameter. It will use a different directory of your choosing if `Terminal` was given an `app_config_dir` directory name.
 
 
-<a id="org2d08557"></a>
+<a id="org8e3d563"></a>
 
 ## General Configuration `config.yml`
 
@@ -1286,7 +1319,7 @@ truecolor: auto
 ```
 
 
-<a id="org0df073b"></a>
+<a id="org773e7d4"></a>
 
 ### `word_char_re`
 
@@ -1309,7 +1342,7 @@ word_char_re: "[[:alnum:]_.:-]"
 ```
 
 
-<a id="org4288158"></a>
+<a id="org8229289"></a>
 
 ### `esc_delay`
 
@@ -1320,26 +1353,26 @@ esc_delay: 0
 ```
 
 
-<a id="org973b5fe"></a>
+<a id="org5789fd5"></a>
 
 ### `history`
 
 
-<a id="orga1dcc95"></a>
+<a id="org1959b2c"></a>
 
 #### `file`
 
 The path to the history file to use, by default `~/.fatty_history`
 
 
-<a id="org5f744d4"></a>
+<a id="orgbb18fb6"></a>
 
 #### `max`
 
 The maximum number of lines of history retained, by default 10,000.
 
 
-<a id="org64941b1"></a>
+<a id="org8a3ecd9"></a>
 
 ### `theme`
 
@@ -1350,7 +1383,7 @@ theme: nordic
 ```
 
 
-<a id="orge751b35"></a>
+<a id="org9ba735f"></a>
 
 ### `truecolor`
 
@@ -1361,7 +1394,7 @@ truecolor: auto
 ```
 
 
-<a id="orgd56b3fd"></a>
+<a id="org13b974b"></a>
 
 ### `log`
 
@@ -1383,14 +1416,14 @@ tags:
 ```
 
 
-<a id="org60dc0ba"></a>
+<a id="orgb93c9b8"></a>
 
 #### `file`
 
 The path to the log file to use.
 
 
-<a id="orgeb194d3"></a>
+<a id="org0fb9a08"></a>
 
 #### `level`
 
@@ -1402,7 +1435,7 @@ Can be one of the following
 -   **`debug`:** detailed messages to assist debugging `fatty` plus all of the above.
 
 
-<a id="org823d99d"></a>
+<a id="org2247ba8"></a>
 
 #### `tags`
 
@@ -1420,7 +1453,7 @@ tags:
 ```
 
 
-<a id="orge3d84e5"></a>
+<a id="org11c2491"></a>
 
 ## Key code definitions `keydefs.yml`
 
@@ -1558,7 +1591,7 @@ konsole:
 After installing that keydefs, I find that the PageDown variants are all recognized by name and modifiers (except for the strange failure of `terminator` to recognize `C-PageDown`!).
 
 
-<a id="org2a9d985"></a>
+<a id="orgab7252d"></a>
 
 ## Key bindings  `keybindings.yml`
 
@@ -1585,7 +1618,7 @@ A keybinding names a key chord, the context in which it applies, and the Fatty a
 ```
 
 
-<a id="org47f10de"></a>
+<a id="org370c8e8"></a>
 
 ### Key Names
 
@@ -1599,7 +1632,7 @@ A keybinding uses the unmodified key name under the `key` field:
 ```
 
 
-<a id="orge517d82"></a>
+<a id="org3a580c2"></a>
 
 #### Printable Keys
 
@@ -1615,7 +1648,7 @@ Most printable keys can be written as the character itself. Quote keys that YAML
 ```
 
 
-<a id="org515f394"></a>
+<a id="org1e9bcad"></a>
 
 #### Curses and Fatty Named Keys
 
@@ -1640,7 +1673,7 @@ Some terminals can report application-keypad sequences such as `keypad_divide`,
 -   `space`
 
 
-<a id="org3fa3e38"></a>
+<a id="orgec1f50a"></a>
 
 #### Possibly Invisible Keys
 
@@ -1649,7 +1682,7 @@ Some physical keys may never reach Fatty at all. They may be handled by the keyb
 Use `keytest` to check. If Fatty sees a key as a raw numeric code, you can name it in `keydefs.yml` and bind it. If `keytest` shows nothing, the key is being intercepted before Fatty receives it.
 
 
-<a id="org96ea9b2"></a>
+<a id="org56d8cd7"></a>
 
 #### Unnamed but Recognized Keys
 
@@ -1674,7 +1707,7 @@ Then bind it in `keybindings.yml`:
 Fatty does not require custom key names to come from a fixed registry. A custom name only needs to be used consistently between `keydefs.yml` and `keybindings.yml`.
 
 
-<a id="org8888baf"></a>
+<a id="org0eda788"></a>
 
 ### Mouse Events
 
@@ -1709,7 +1742,7 @@ scroll_down
 ```
 
 
-<a id="org2ce52a8"></a>
+<a id="orgbffc2cf"></a>
 
 ### Modifiers
 
@@ -1722,7 +1755,7 @@ shift: true
 ```
 
 
-<a id="orgc4d7ddc"></a>
+<a id="org0662dd0"></a>
 
 ### Contexts
 
@@ -1756,7 +1789,7 @@ The available contexts are:
 The \`:terminal\` context is the lowest-priority fallback context for terminal-wide commands. It is where Fatty puts bindings that are not specific to text editing, paging, search, or popup selection, such as theme selection, key testing, and quitting. Because \`:terminal\` is searched last, any more specific context can override a terminal-wide binding.
 
 
-<a id="orgd327240"></a>
+<a id="org55e8a55"></a>
 
 ### Actions
 
@@ -1784,7 +1817,7 @@ Most movement, deletion, history, completion, paging, and popup-navigation actio
 Use \`keytest\` to check what action is currently bound to a key. If a key is bound, \`keytest\` reports the matching context, action name, arguments, and the object that handles the action.
 
 
-<a id="org0a51d38"></a>
+<a id="org5c651ab"></a>
 
 #### Input buffer actions
 
@@ -1827,7 +1860,7 @@ Terminology notes:
 | yank\_pop              | Yes    | Copy next kill ring item and replace prior |
 
 
-<a id="org0156270"></a>
+<a id="orga37809c"></a>
 
 #### Input field actions
 
@@ -1840,7 +1873,7 @@ Input field actions operate on an editable input field. An input field occurs at
 | history\_next | No     | Insert the next relevant history item in the input field  |
 
 
-<a id="org49f5b2c"></a>
+<a id="org5bd909b"></a>
 
 #### Shell session actions
 
@@ -1861,7 +1894,7 @@ Shell session actions operate at the session level around the main command input
 | universal\_argument  | No     | Set the numeric argument to 4 or multiply the current one by 4   |
 
 
-<a id="org51e582e"></a>
+<a id="orgcba2897"></a>
 
 #### Pager actions
 
@@ -1883,7 +1916,7 @@ Pager actions navigate output when the output area is in paging mode. They move
 | quit\_paging          | No     | Quit paging and return control to the input line |
 
 
-<a id="org9c6e828"></a>
+<a id="org2e0b296"></a>
 
 #### Pager search actions
 
@@ -1912,7 +1945,7 @@ While the search session is active, accepting commits the current match and canc
 | isearch\_cancel                | No     | Cancel the active incremental search and restore its starting point |
 
 
-<a id="orgf26b607"></a>
+<a id="org76791bc"></a>
 
 #### Popup actions
 
@@ -1932,7 +1965,7 @@ Popup actions control selection and narrowing popups such as choose, menu, compl
 | popup\_toggle\_selected | No     | In multi-select, toggle the selection of the current item |
 
 
-<a id="org5abe8ab"></a>
+<a id="org6b1188d"></a>
 
 #### Prompt popup actions
 
@@ -1945,7 +1978,7 @@ Prompt popup actions control prompt dialogs that collect a string from the user.
 | prompt\_cancel\_if\_empty | No     | Cancel only if the input buffer is empty             |
 
 
-<a id="orgb190c08"></a>
+<a id="orgf63740e"></a>
 
 #### Utility Actions
 
@@ -1960,12 +1993,12 @@ Some actions exist to support `Fatty`'s own input machinery and are not normally
 | paste        | str  | No     | Insert pasted text at point        |
 
 
-<a id="org19a3e32"></a>
+<a id="org3856a84"></a>
 
 ## Themes `themes/`
 
 
-<a id="orge0db426"></a>
+<a id="org88b0217"></a>
 
 ### Distributed Themes
 
@@ -2001,12 +2034,12 @@ Here are the builtin themes:
 | wordperfect       | Nostalgic nod to the good old word processor       |
 
 
-<a id="org23d543d"></a>
+<a id="org8769885"></a>
 
 ### Custom Themes
 
 
-<a id="orgc7d4f2a"></a>
+<a id="orgd425d6c"></a>
 
 #### Theme Name
 
@@ -2017,7 +2050,7 @@ name: nordic
 ```
 
 
-<a id="org7186f3f"></a>
+<a id="org1e1695f"></a>
 
 #### Inheritance from Another Theme
 
@@ -2034,7 +2067,7 @@ fg: "#eeeeee"
 This means that all the theme setting from the `nordic` theme apply except to the extent changed by the rest of the `my_nordic` theme file.
 
 
-<a id="org85b6b26"></a>
+<a id="org8557acf"></a>
 
 #### Inheritance within a Theme
 
@@ -2054,7 +2087,7 @@ output:
 This means that the input field will have the same coloring and attributes as the output pane.
 
 
-<a id="org6741eee"></a>
+<a id="org76e4687"></a>
 
 #### Theme Roles
 
@@ -2101,7 +2134,7 @@ Here is a listing of what roles act as the parent for each of the roles, their p
 | `markdown_hrule`        | Markdown horizontal rules.                | `output`              |
 
 
-<a id="org33b14c5"></a>
+<a id="orge738a22"></a>
 
 #### Role Colors and Attributes and Frame Style
 
@@ -2222,3 +2255,75 @@ Each role can have assigned to it a foreground color (`fg:`), a background color
         bg: navy
         attrs: [underline]
     ```
+
+
+<a id="orgdd1744c"></a>
+
+### The `themer` helper
+
+Choosing readable colors for the semantic roles---`good`, `info`, `warn`, and `error`&#x2014;is not trivial. The `themer` utility can suggest suitable foreground colors based on a theme's output background.
+
+For an existing theme, `themer` also reports the contrast of the current role colors and flags those that fall below its target contrast.
+
+Pass it either the name of an existing theme:
+
+```sh
+themer nordic
+```
+
+```
+Theme: nordic
+Output background: #2e3440
+
+Current semantic roles:
+
+good   #22ee00  contrast 7.91  OK
+info   #33deff  contrast 7.75  OK
+warn   #d78700  contrast 4.37  LOW
+error  #d700af  contrast 2.68  LOW
+
+Suggested semantic roles:
+
+good   #28bd41  contrast 5.02
+info   #74abe2  contrast 5.15
+warn   #caa22b  contrast 5.18
+error  #e78d8d  contrast 5.11
+```
+
+or a hexadecimal background color when developing a new theme:
+
+```sh
+themer '#2e3440'
+```
+
+```
+Background: #2e3440
+Output background: #2e3440
+
+Suggested semantic roles:
+
+good   #28bd41  contrast 5.02
+info   #74abe2  contrast 5.15
+warn   #caa22b  contrast 5.18
+error  #e78d8d  contrast 5.11
+```
+
+You can get the suggestions in YAML form by giving the `--yaml` flag:
+
+```sh
+themer --yaml '#2e3440'
+```
+
+```
+good:
+  fg: "#28bd41"
+
+info:
+  fg: "#74abe2"
+
+warn:
+  fg: "#caa22b"
+
+error:
+  fg: "#e78d8d"
+```