fatty 0.99.0 → 0.99.3

data/help/help.md

@@ -0,0 +1,233 @@
+- [Fatty Help](#org245a92e)
+  - [The `fatty` demo command](#orgffe615f)
+  - [Builtin commands](#orgd27e40e)
+  - [Keybindings](#orgab9d7b6)
+    - [Input Context](#org68708fa)
+    - [Paging Context](#org7729d50)
+    - [Popup Context](#org684d15c)
+    - [Prompt Context](#org741e059)
+
+
+<a id="org245a92e"></a>
+
+# Fatty Help
+
+
+<a id="orgffe615f"></a>
+
+## The `fatty` demo command
+
+When you run `fatty`, it operates as a simple demo of the `fatty` gem by presenting an editable command-line using emacs key bindings. It has several builtin commands to demonstrate `fatty` features, and any command it does not recognize is handed off to the shell.
+
+
+<a id="orgd27e40e"></a>
+
+## Builtin commands
+
+Here are the commands builtin to `fatty`
+
+| Command                      | Description                                                                |
+|---------------------------- |-------------------------------------------------------------------------- |
+| cd                           | Change the current directory used by the shell                             |
+| colors                       | Display all available colors, names and rgb codes                          |
+| choose                       | Present a series of choices in a popup window                              |
+| choose\_multi                | Present choices with a "checkbox" for selecting multiple values            |
+| choosevals                   | Also present choices in a popup window but return an associated value      |
+| choosevals\_multi            | Also present a checkbox but return associated values                       |
+| environment                  | Print out the environment detected by Fatty                                |
+| good                         | Display a "good" message colored to indicate success                       |
+| help                         | Display this file on the output pane                                       |
+| info                         | Display an "info" message on the status line                               |
+| keytest                      | Enter key diagnostic mode report keycodes, key names, and bindings         |
+| markdown <file.md>           | Render the markdown file to the output pane; defaults to a demo file       |
+| markdown\_org                | Render the markdown file exported from org mode with ofx-gfm package       |
+| menu                         | Present a menu of labeled routines to run                                  |
+| oops                         | Display an "oops" message colored to indicate failure                      |
+| progress bar                 | Show progress by a filling bar using ASCII characters                      |
+| progress braille\_bar        | Same, but using braille characters                                         |
+| progress count <N>           | Display an animated progress indicator counting up to 40 or the given N    |
+| progress percent <N>         | Same but also show the percent complete                                    |
+| progress simple\_percent <N> | Same but show only the percent complete                                    |
+| progress spinner             | Animate a "spinner" showing a busy state                                   |
+| progress trail               | Show progress by displaying an "indicator" character for each step         |
+| progress unicode\_bar        | Same, but using unicode characters                                         |
+| prompt                       | Popup a text box for entering a value in response to a prompt              |
+| <shell\_command>             | Anything else is treated as a shell command, run, and its output displayed |
+| warn                         | Display a "warn" message colored to indicate caution                       |
+
+
+<a id="orgab9d7b6"></a>
+
+## Keybindings
+
+The following tables explain the keybindings available in \`fatty\` in different contexts. Named keys are indicated by \`:name\` and key categories, such as \`<digits>\` are indicated with brackets.
+
+
+<a id="org68708fa"></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.
+
+| Key        | Description                                            |
+|---------- |------------------------------------------------------ |
+| C-a        | move to the beginning of the line                      |
+| :home      | move to the beginning of the line                      |
+| C-e        | move to the end of the line                            |
+| :end       | move to the end of the line                            |
+| C-f        | move cursor right one character                        |
+| :right     | move cursor right one character                        |
+| C-b        | move cursor left one character                         |
+| :left      | move cursor left one character                         |
+| M-f        | move cursor right one word                             |
+| M-:right   | move cursor right one word                             |
+| C-:right   | move cursor right one word                             |
+| M-b        | move cursor left one word                              |
+| M-:left    | move cursor left one word                              |
+| C-:left    | move cursor left one word                              |
+| C-t        | transpose characters                                   |
+| M-t        | transpose words                                        |
+|            |                                                        |
+| C-d        | delete character at cursor                             |
+| :delete    | delete character at cursor                             |
+| :backspace | delete character before cursor                         |
+| M-d        | kill word at cursor                                    |
+| C-w        | kill word before cursor                                |
+| C-k        | kill to end of line                                    |
+|            |                                                        |
+| C-/        | undo                                                   |
+| C-\_       | undo                                                   |
+| C-M-/      | redo                                                   |
+| M-/        | redo                                                   |
+|            |                                                        |
+| C-:space   | set the mark at the current cursor position            |
+| C-@        | set the mark at the current cursor position            |
+| C-g        | clear the mark                                         |
+| C-w        | kill the region                                        |
+| M-w        | copy the region                                        |
+|            |                                                        |
+| C-y        | yank last kill at cursor                               |
+| M-y        | replace last yank with next in kill ring               |
+|            |                                                        |
+| C-u        | universal count argument (time 4 each press)           |
+| M-<digit>  | accumulate count argument                              |
+|            |                                                        |
+| C-p        | replace the line with the prior history item           |
+| :up        | replace the line with the prior history item           |
+| C-n        | replace the line with the next history item            |
+| :down      | replace the line with the prior history item           |
+| C-r        | search the history in a popup                          |
+|            |                                                        |
+| :enter     | feed the line to the on\_accept proc and page output   |
+| M-:enter   | feed the line to the on\_accept proc and scroll output |
+| C-c        | quit \`fatty\`                                         |
+| C-d        | quit \`fatty\` only if the input line is empty         |
+| C-l        | clear the output pane                                  |
+|            |                                                        |
+| :tab       | Suggest the next completion                            |
+| S-:tab     | Suggest the prior completion                           |
+| M-:tab     | Popup all completions based on input-so-far            |
+|            |                                                        |
+
+
+<a id="org7729d50"></a>
+
+### Paging Context
+
+By default, \`fatty\` sends output to the large output pane, and if the output is more than one screen long presents a paging environment for viewing and searching the environment.
+
+| Key         | Description                            |
+|----------- |-------------------------------------- |
+| :up         | move output one line up                |
+| k           | move output one line up                |
+| :down       | move output one line down              |
+| j           | move output one line down              |
+|             |                                        |
+| :space      | move to next page                      |
+| :page\_down | move to next page                      |
+| C-v         | move to next page                      |
+| d           | move to next page                      |
+| :backspace  | move to prior page                     |
+| :page\_up   | move to prior page                     |
+| M-v         | move to prior page                     |
+| u           | move to prior page                     |
+|             |                                        |
+| `/`         | initiate a forward string search       |
+| ?           | initiate a backward string search      |
+|             |                                        |
+| C-/         | initiate a forward regex search        |
+| C-M-S       | initiate a forward regex search        |
+|             |                                        |
+| C-s         | initiate a forward incremental search  |
+| C-r         | initiate a backward incremental search |
+|             |                                        |
+| C-c         | cancel the search                      |
+| C-g         | cancel the search                      |
+|             |                                        |
+| :return     | use the typed string for the search    |
+| :enter      | use the typed string for the search    |
+|             |                                        |
+| n           | find the next match                    |
+| N           | find the prior match                   |
+|             |                                        |
+
+
+<a id="org684d15c"></a>
+
+### Popup Context
+
+Certain keys cause a popup, such as C-r to bring up history items and M-:tab to bring up completions.
+
+| Key            | Description                                                           |
+|-------------- |--------------------------------------------------------------------- |
+| <search terms> | typing text narrows to those items matching all space-separated words |
+| C-c            | cancel the popup with no return                                       |
+| C-g            | cancel the popup with no return                                       |
+| :escape        | cancel the popup with no return                                       |
+|                |                                                                       |
+| :enter         | select the current item                                               |
+| :return        | select the current item                                               |
+|                |                                                                       |
+| :up            | select the prior item                                                 |
+| C-p            | select the prior item                                                 |
+| :down          | select the next item                                                  |
+| C-n            | select the next item                                                  |
+|                |                                                                       |
+| :page\_up      | display prior page of items                                           |
+| M-v            | display prior page of items                                           |
+| :page\_down    | display next page of items                                            |
+| C-v            | display next page of items                                            |
+|                |                                                                       |
+| :home          | display first page of items                                           |
+| M-<            | display first page of items                                           |
+| :end           | display last page of items                                            |
+| M->            | display last page of items                                            |
+|                |                                                                       |
+| C-l            | re-center display on current item                                     |
+|                |                                                                       |
+| :space         | if popup allows multiple selections, add current item to selections   |
+|                |                                                                       |
+
+
+<a id="org741e059"></a>
+
+### Prompt Context
+
+Fatty can popup a prompt for getting text from the user by presenting a prompt together with an input field. The input field has all the line-editing capabilities of the primary input context.
+
+| Key     | Description                       |
+|------- |--------------------------------- |
+| C-c     | cancel with no input              |
+| C-g     | cancel with no input              |
+| :escape | cancel with no input              |
+|         |                                   |
+| :return | return with current input         |
+| :enter  | return with current input         |
+| C-j     | return with current input         |
+|         |                                   |
+| C-p     | display prior prompt history item |
+| :up     | display prior prompt history item |
+| C-n     | display next prompt history item  |
+| :down   | display next prompt history item  |
+|         |                                   |
+|         |                                   |

data/lib/fatty/action.rb

@@ -71,7 +71,7 @@ module Fatty
     end
 
     def self.call(name, env, *args, **kwargs)
-      arg_str = "name: #{name}, env: #{env}, args: #{args}, kwargs: #{kwargs}"
+      arg_str = "name: #{name}, session: #{env.session.id}, #{env}, args: #{args}, kwargs: #{kwargs}"
       Fatty.debug("Action.call(#{arg_str})", tag: :action)
       key = name.to_sym
       defn = @defs[key] or raise ActionError, "Unknown action: #{key}"
@@ -79,7 +79,6 @@ module Fatty
       target = env.public_send(defn[:on])
       raise ActionError, "env.#{defn[:on]} is nil for action #{key}" unless target
 
-      # Inject count: from env.counter when the target accepts it.
       if env.counter&.active? && !kwargs.key?(:count)
         meth = target.method(defn[:method])
         params = meth.parameters
@@ -88,12 +87,9 @@ module Fatty
           params.any? { |(kind, pname)| kind == :key && pname == :count } ||
           params.any? { |(kind, _pname)| kind == :keyrest }
 
-        if accepts_count
-          kwargs = kwargs.merge(count: env.counter.consume(default: 1))
-        end
+        kwargs = kwargs.merge(count: env.counter.consume(default: 1)) if accepts_count
       end
-
-      target.public_send(defn[:method], *args, **kwargs)
+      target.__send__(defn[:method], *args, **kwargs)
     end
 
     def self.registered?(name)

data/lib/fatty/actionable.rb

@@ -59,6 +59,8 @@ module Fatty
 
       private
 
+      # simplecov:disable
+
       def infer_action_target
         base = name.split("::").last
         return :buffer   if base == "InputBuffer"

data/lib/fatty/alert.rb

@@ -2,84 +2,99 @@
 
 module Fatty
   class Alert
-    DETAIL_ORDER = %i[terminal key ctrl meta shift].freeze
-
-    attr_reader :level, :message, :details
+    attr_reader :role, :text, :details
 
     # Return a new Alert object
     #
     # @param message [String]
-    # @param level [:info, :warn, :error]
+    # @param role [:good, :info, :warn, :error]
     # @param details [Hash|String]
     # @param sticky [Boolean]
     # @return [Alert]
-    def initialize(message:, level: :info, details: nil, sticky: false)
-      @message = message
-      @level = level.to_sym
+    def initialize(text:, role: :info, details: nil, sticky: false)
+      @text = text
+      @role = role.to_sym
       @details = details
       @sticky  = !!sticky
     end
 
-    # Return a new Alert object at level info
+    def inspect
+      txt = +"Alert: "
+      txt << "text: #{@text}; " if @text
+      txt << "role: #{@role}; " if @role
+      txt << "details: #{@details}; " if @details
+      txt << "sticky: #{@sticky}."
+    end
+
+    # Return a new Alert object at role good
+    #
+    # @param msg [String]
+    # @return [Alert] with role :good
+    def self.good(msg)
+      new(text: msg, role: :good)
+    end
+
+    # Return a new Alert object at role :info
     #
     # @param msg [String]
-    # @return [Alert] with level info
+    # @return [Alert] with role :info
     def self.info(msg)
-      new(message: msg, level: :info)
+      new(text: msg, role: :info)
     end
 
-    # Return a new Alert object at level warn
+    # Return a new Alert object at role :warn
     #
     # @param msg [String]
-    # @return [Alert] with level warn
+    # @return [Alert] with role :warn
     def self.warn(msg)
-      new(message: msg, level: :warn)
+      new(text: msg, role: :warn)
     end
 
-    # Return a new Alert object at level error
+    # Return a new Alert object at role error
     #
     # @param msg [String]
-    # @return [Alert] with level error
+    # @return [Alert] with role :error
     def self.error(msg)
-      new(message: msg, level: :error)
+      new(text: msg, role: :error)
     end
 
     # Translate the "level" to a "role" used by the renderers. The returned
     # roles are "composite" roles in the resolver in that they take the
-    # background ot the alert panel and apply a foreground color based on
+    # background of the alert panel and apply a foreground color based on
     # severity.
     #   @param level [:info, :warn, :error]
     #   @return [Symbol] composite or semantic role
     # used by renderer (e.g., alert_good, :alert_info, :alert_warn, :alert_error)
-    def role
-      case level
-      when :good then :alert_good
-      when :warn then :alert_warn
-      when :error then :alert_error
-      else :alert_info
-      end
-    end
+    # def role
+    #   case level
+    #   when :good then :alert_good
+    #   when :warn then :alert_warn
+    #   when :error then :alert_error
+    #   else :alert_info
+    #   end
+    # end
 
     # Build a string version of the Alert suitable for display to the user.
     def format
       icon =
-        case level
-        when :warn then "⚠"
-        when :error then "✖"
-        else "ℹ"
+        case role
+        when :good then " ✔ "
+        when :info then " ℹ "
+        when :warn then " ⚠ "
+        when :error then " ✖ "
+        else "   "
         end
-      msg = message.to_s
-      details_str = ""
-      if details.respond_to?(:empty?) ? !details.empty? : !!details
-        details_str = if details.is_a?(Hash)
-          " (" +
-            DETAIL_ORDER.filter_map { |k| "#{k}=#{details[k]}" if details.key?(k) }.join(" ") +
-            ")"
+      details_str =
+        if details.nil? || details.empty?
+          ""
         else
-          " (#{details})"
+          key_strs = []
+          detail_key_order.each do |k|
+            key_strs << "#{k}=#{details[k]}"
+          end
+          " (#{key_strs.join(' ')})"
         end
-      end
-      "#{icon} #{msg}#{details_str}"
+      "#{icon} #{text}#{details_str}"
     end
 
     # Return whether this Alert is sticky, meaning that it should not be
@@ -89,5 +104,16 @@ module Fatty
     def sticky?
       @sticky
     end
+
+    def detail_key_order
+      keys = []
+      keys << :terminal if details.key?(:terminal)
+      keys << :key if details.key?(:key)
+      keys << :shift if details.key?(:shift)
+      keys << :ctrl if details.key?(:ctrl)
+      keys << :meta if details.key?(:meta)
+      other_keys = details.keys - [:terminal, :key, :shift, :ctrl, :meta]
+      keys + other_keys.sort
+    end
   end
 end

data/lib/fatty/ansi/renderer.rb

@@ -14,12 +14,23 @@ module Fatty
         return unless spec
 
         msg = text.to_s.tr("\r\n", " ")
-        msg = Fatty::Ansi.truncate_visible(msg, width)
-        visible = Fatty::Ansi.visible_length(msg)
-        pad = width - visible
-        sgr = sgr_for_spec(spec)
-        padding = pad.positive? ? " " * pad : ""
-        write_ansi("#{CSI}#{row + 1};#{col + 1}H", sgr, msg, sgr, padding, reset)
+
+        segments = Fatty::Ansi.segment(msg).map do |segment_text, style|
+          {
+            text: segment_text,
+            role: role,
+            style: style,
+          }
+        end
+
+        render_segments_line(
+          row: row,
+          col: col,
+          width: width,
+          segments: segments,
+          palette: palette,
+          fill_role: role,
+        )
       end
 
       def render_segments_line(row:, col:, width:, segments:, palette:, fill_role: :output)
@@ -73,6 +84,15 @@ module Fatty
         @io || $stdout
       end
 
+      def show_cursor
+        "#{CSI}?25h"
+      end
+
+      def hide_cursor
+        "#{CSI}?25l"
+      end
+
+      # simplecov:disable
       private
 
       def save_cursor

data/lib/fatty/ansi.rb

@@ -346,6 +346,7 @@ module Fatty
       out
     end
 
+    # simplecov:disable
     private_class_method :consume_escape!, :parse_params, :apply_sgr!
     private_class_method :merge_adjacent_segments, :same_style?, :sgr_for
   end

data/lib/fatty/api/alert.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Fatty
+  ###########################################################################################
+  # Public API convenience methods for use by the library user
+  ###########################################################################################
+  module AlertApi
+    # Display text in the status area with the given "role", which determines
+    # the coloring of the displayed text via themeing.
+    def alert(text, role: :info)
+      terminal.apply_command(Command.session(:alert, :show, text: text, role: role))
+      nil
+    end
+  end
+end

data/lib/fatty/api/choose.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Fatty
+  module ChooseApi
+    # The consumer can call #choose to cause an interactive popup session to
+    # present the user with a series of choices to select from.
+    def choose(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)
+      items = normalize_choices(choices)
+      raise ArgumentError, "choices must not be empty" if items.empty?
+
+      labels = items.map(&:first)
+      popup = PopUpSession.new(
+        source: labels,
+        kind: :terminal_choose,
+        title: "Choose",
+        message: prompt,
+        prompt: "Narrow: ",
+        current: :top,
+        show_counts: false,
+        validate_unique_labels: true,
+        history: terminal.history,
+        history_kind: :popup_filter,
+        history_ctx: { kind: :popup_filter, popup: :choose, prompt: prompt.to_s },
+      )
+      popup.instance_variable_set(:@current, initial_choice_idx.to_i.clamp(0, labels.length - 1))
+
+      done = false
+      result = nil
+
+      acc_proc = ->(payload) do
+        item = payload[:item]
+        idx = labels.index(item)
+        result = idx ? items[idx][1] : cancel_value
+        done = true
+      end
+      cancel_proc = -> do
+        result = cancel_value
+        done = true
+      end
+      owner = Terminal::PopupOwner.new(on_result: acc_proc, on_cancel: cancel_proc)
+
+      begin
+        terminal.apply_command(Fatty::Command.terminal(:push_modal, session: popup, owner: owner))
+        terminal.render_frame
+
+        while !done && terminal.running?
+          dirty = false
+          command = terminal.event_source.next_event
+
+          if command
+            terminal.apply_command(command)
+            dirty = true
+          end
+
+          begin
+            dirty ||= !!terminal.tick_active_session
+          rescue StandardError => e
+            Fatty.error("PromptApi#choose tick failed: #{e.class}: #{e.message}", tag: :terminal)
+            dirty = true
+          end
+
+          terminal.render_frame if dirty
+        end
+      ensure
+        terminal.render_frame
+      end
+      result
+    end
+
+    # A simple Yes/No chooser.
+    def confirm(prompt, yes_label: "Yes", no_label: "No", cancel_value: false)
+      choose(
+        prompt,
+        choices: { yes_label => true, no_label => false },
+        cancel_value: cancel_value,
+      )
+    end
+
+    # The consumer can call #choose_multi to cause an interactive popup session to
+    # present the user with a series of choices to select from.
+    def choose_multi(prompt, choices:, cancel_value: nil)
+      items = normalize_choices(choices)
+      raise ArgumentError, "choices must not be empty" if items.empty?
+
+      labels = items.map(&:first)
+      popup = PopUpSession.new(
+        source: labels,
+        kind: :terminal_choose_multi,
+        title: "Choose Many",
+        message: prompt,
+        prompt: "> ",
+        current: :top,
+        show_counts: true,
+        selection_mode: :multiple,
+        validate_unique_labels: true,
+        history: terminal.history,
+        history_kind: :popup_filter,
+        history_ctx: { kind: :popup_filter, popup: :choose_multi, prompt: prompt.to_s },
+      )
+      done = false
+      result = nil
+
+      label_to_value = items.to_h
+      acc_proc = ->(payload) do
+        selected = payload[:items] || {}
+        result =
+          selected.each_with_object({}) do |(label, _), h|
+          h[label] = label_to_value.fetch(label, cancel_value)
+        end
+        done = true
+      end
+      cancel_proc = -> do
+        result = cancel_value
+        done = true
+      end
+      owner = Terminal::PopupOwner.new(on_result: acc_proc, on_cancel: cancel_proc)
+
+      begin
+        terminal.apply_command(Fatty::Command.terminal(:push_modal, session: popup, owner: owner))
+        terminal.render_frame
+
+        while !done && terminal.running?
+          dirty = false
+          command = terminal.event_source.next_event
+          if command
+            terminal.apply_command(command)
+            dirty = true
+          end
+
+          begin
+            dirty ||= !!terminal.tick_active_session
+          rescue StandardError => e
+            Fatty.error("Terminal#choose_multi tick failed: #{e.class}: #{e.message}", tag: :terminal)
+            dirty = true
+          end
+
+          terminal.render_frame if dirty
+        end
+      ensure
+        terminal.render_frame
+      end
+      result
+    end
+  end
+end

data/lib/fatty/api/environment.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Fatty
+  module EnvironmentApi
+    def environment
+      h = Fatty::Env.detect
+      h[:truecolor_enabled] = terminal.ctx.truecolor_enabled?
+      h[:curses] = terminal.ctx.environment if terminal.ctx
+      h
+    end
+  end
+end

data/lib/fatty/api/keytest.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Fatty
+  module KeytestApi
+    def keytest
+      queue(Command.terminal(:push_modal, session: Fatty::KeyTestSession.new))
+      queue(Command.session(:alert, :clear))
+      nil
+    end
+  end
+end