typr 1.8.0 → 1.9.2

data/lib/line.rb

@@ -12,6 +12,17 @@ module Typr
 #   line.ask([ ["Name?", :line], ["Age?", :line] ])
 
 class Line < Space
+  ##
+  # Line state: +default+ (a String, Proc, or Space) restored by {#reset},
+  # +prompt+ (a single char, +>?+ by default) shown before answers,
+  # +bindings+ the clickable keybinding labels, +data+ the currently
+  # rendered text, +align+ (:left/:right) horizontal alignment,
+  # +trim+ (:left/:right) the side clipped on overflow.
+  #
+  #   line.default = "status: ok"
+  #   line.prompt  = "?"
+  #   line.align   = :left
+
   attr_accessor :default, :prompt, :bindings, :data, :align, :trim
 
   # Render +msg+ (String, Proc, or Space) on this line.
@@ -36,7 +47,7 @@ class Line < Space
   #   line.append " world"   #=> "hello world"
   #   line << "!"            #=> "hello world!"
 
-  def append(str); show @data+str end
+  def append(str); show @data+str; @data end
   alias :<< :append
 
   # The keybinding list as a clickable grid of the line's own bindings. It
@@ -92,16 +103,26 @@ class Line < Space
   #   Array - interactive pick via <widget>.pick(<type>); an optional third
   #           element renders the chosen row's field into the line, and an
   #           optional fourth element is passed as pick keyword arguments
-  #           (e.g. { column: 0 } to open the pick in / search mode)
+  #           (e.g. { column: 0 } to open the pick in / search mode).
+  #           Special case: [:line, { initial: "text" }] opens the inline
+  #           editor via Typr.read_line prefilled with +initial+ instead
+  #           of a widget pick.
   #   :key  - a single keypress via Typr.read_key
   #   :line - interactive line editor via Typr.read_line at the cursor
   #
+  # Every entry — including a trailing +with:+ — is simply another
+  # question in order (a +with:+ entry is labeled "with" when drawn), so
+  # +ask(pick: [grid, :row], with: :line)+ first picks, then reads
+  # free text. Hash order is insertion order.
+  #
   # Pressing the exit key (@keymap[:exit], Escape by default) aborts the
   # remaining questions and returns nil.
   #
   #   line.ask(name: :line)                  #=> "Alice"
   #   line.ask(keys: :key)                   #=> "a"
   #   line.ask(open: [grid, :row, :name])    #=> 2   (picked row id)
+  #   line.ask(nick: [:line, { initial: "bob" }])  #=> edited string
+  #   line.ask(pick: [grid, :row], with: :line)  #=> [2, "typed text"]
   #   line.ask([ ["Name?", :line], ["Ok?", :key] ])  #=> ["Alice", "a"]
 
   def ask sentence
@@ -149,15 +170,26 @@ class Line < Space
     return ( answer.one? ? answer.first : answer )
   end
 
-  # Prompt for a single command line at the cursor: +prompt+ rendered in the
-  # line's default color, typed input in the answer color. When +completions+
-  # is truthy, TAB matches the current word against the shell (commands,
-  # options, files) and replaces it through the pick grid. Regions of the
-  # typed input matching @colors[:regex] are colored as they are typed
-  # (with the :shell scheme: the first word red, double-dash options blue).
+  ##
+  # Prompt for a single command line at the cursor: +prompt+ rendered in
+  # the line's default color, typed input in the answer color. TAB
+  # matches the current word against the shell (commands, options, files)
+  # and replaces it through the pick grid. Regions of the typed input
+  # matching @colors[:regex] are colored as they are typed (with the
+  # :shell scheme: the first word red, double-dash options blue).
+  #
+  # +history+ is an Array whose entries Up/Down walk; +prefixes+ lists
+  # command-start characters stripped before completion matching;
+  # +redraw+ repaints the caller's screen after a completion pick;
+  # +regex+ overrides @colors[:regex] for this prompt.
   #
   #   line.cli "> ", initial: "cp %name"
   #   #=> "cp source.txt" (or nil on Escape)
+  #   line.cli "> ", history: @recent, prefixes: "$>"
+  #
+  # @param prompt [String] rendered before the typed input
+  # @param initial [String] prefilled input
+  # @return [String, nil] the accepted command, or nil on Escape
 
   def cli prompt, initial: '', redraw: nil, history: nil, prefixes: nil, regex: nil
     re = /\A[#{Regexp.escape(prefixes || '|+=!')}]/
@@ -197,6 +229,16 @@ class Line < Space
 
   public
 
+  ##
+  # Construct a Line. Position via the {Space} boundaries; +default+ sets
+  # the text shown after {#reset}, +bindings+ the keybinding labels.
+  #
+  #   line = Typr::Line.new(top: -1, left: 0,
+  #     default: "(f)ilter, (s)ort, [esc] quit")
+  #
+  # @param args [Hash] boundary and display options (see {Space#initialize})
+  # @return [Line]
+
   def initialize args
     @right= -1
     @align = :left

data/lib/space.rb

@@ -16,7 +16,21 @@ class Space
 include Typr
 
 %w[left top right bottom].each{ |name| method = <<STR
-  def %s_setting; @%s; end  
+  ##
+  # Raw +%s+ value as passed to the constructor, before resolution
+  # (nil, Integer, Float, or Proc). Useful for introspection.
+  #
+  #   space.%s_setting   #=> 0
+  #
+  def %s_setting; @%s; end
+  ##
+  # Resolved +%s+ edge: Integer (absolute position), Float (fraction of
+  # the terminal), Proc (evaluated each layout pass), or a negative
+  # Integer (offset from the opposite edge, -1 = last). Defaults to the
+  # widget's natural extent when unset.
+  #
+  #   space.%s   #=> 4
+  #
   def %s
     max=Typr.#{ name[/left|right/] ? 'width' : 'height' }
     if !@%s;[max, #{ case name
@@ -30,9 +44,18 @@ else 'top+[(respond_to?(:rows) ? rows : 0), 1].max-1+(respond_to?(:headspace) ?
     else @%s end
   end
 STR
-eval( method % ([name]*11) ) }
+eval( method % ([name]*15) ) }
+
+  ##
+  # Deep-convert String keys to Symbols so string-keyed config (e.g. YAML)
+  # is honored. Non-Hash values pass through untouched.
+  #
+  #   space.symbolize "colors" => { "border" => :red }
+  #   #=> {colors: {border: :red}}
+  #
+  # @param obj [Object] hash or value to convert
+  # @return [Object] converted copy, or the value itself when not a Hash
 
-  # Deep-convert String keys to Symbols so string-keyed config (e.g. YAML) is honored.
   def symbolize obj
     case obj
     when Hash
@@ -41,12 +64,44 @@ eval( method % ([name]*11) ) }
     else obj end
   end
 
+  ##
+  # Viewport edges, readable and assignable. Each accepts an Integer
+  # (absolute position), a Float (fraction of the terminal), a Proc
+  # (evaluated each layout pass), or a negative Integer (offset from the
+  # opposite edge, -1 = last row/column); unset edges fall back to the
+  # widget's natural extent. +left_setting+ and friends return the raw
+  # constructor value before resolution.
+  #
+  #   space.left = 0
+  #   space.right = 0.5
+  #   space.bottom = -1
+  #   space.right_setting   #=> 0.5
   attr_writer :left, :top, :right, :bottom
+  ##
+  # +margin+ is the left-edge padding string, +colors+ the per-part color
+  # hash, +interval+ the redraw period in seconds for {#start}, and
+  # +borders+ the raw edge characters (prefer {#border=}).
+  #
+  #   space.margin = "  "
+  #   space.interval = 2
   attr_accessor :margin, :colors, :interval, :borders
 
+  ##
   # Viewport width in cells (right - left + 1).
+  #
+  #   space.width   #=> 80
+  #
+  # @return [Integer]
+
   def width; right - left + 1 end
+
+  ##
   # Viewport height in cells (bottom - top + 1).
+  #
+  #   space.height  #=> 24
+  #
+  # @return [Integer]
+
   def height; bottom - top + 1 end
 
   ##
@@ -60,7 +115,7 @@ eval( method % ([name]*11) ) }
   def data_at x, y; nil end
 
   ##
-  # The trigger key for a binding label like "[h]elp" or "[/]:search", or nil
+  # The trigger key for a binding label like "[h]elp" or "[/]:narrow", or nil
   # for named keys ("[up]", "[esc]") which stay keyboard-only.
   #
   #   line.extract_key "[R]ecurse"   # => "R"
@@ -70,18 +125,48 @@ eval( method % ([name]*11) ) }
     key if key and key.size == 1
   end
 
+  ##
   # Redraw every +interval+ seconds from a background thread.
+  #
+  #   space.interval = 1
+  #   space.start     #=> #<Thread>
+  #   space.stop      # terminates it
+  #
+  # @return [Thread]
+
   def start; @updater = Thread.new{ loop{show; sleep @interval }} end
-  # Stop the background refresh thread.
+
+  ##
+  # Stop the background refresh thread started by {#start}.
+  #
+  #   space.stop   #=> #<Thread> (terminated)
+  #
+  # @return [Thread]
+
   def stop; @updater.terminate end
 
+  ##
   # Draw a border char at screen (x, y); skips nil and off-screen positions.
+  #
+  #   space.draw_border 0, 0, "┌"   #=> nil
+  #
+  # @param x [Integer] column (0-based)
+  # @param y [Integer] row (0-based)
+  # @param char [String, nil] character to draw
+  # @return [nil]
+
   def draw_border x,y,char
     draw move_code(x, y) + char unless not char or
       x < 0 or x > Typr.width or y < 0 or y > Typr.height
   end
 
+  ##
   # Draw the widget's border box (no-op when no borders are set).
+  #
+  #   space.show   #=> nil
+  #
+  # @return [nil]
+
   def show
     return if @borders.empty?
     color @colors[:border]
@@ -97,8 +182,19 @@ eval( method % ([name]*11) ) }
     draw_border(right + 1, bottom + 1, @borders[:bottom_right])
   end
 
-  # Set border style: :light/:heavy/:double/:round, a char repeated across
-  # the box, or nil for none.
+  ##
+  # Set border style: +:light+/:heavy+/:double+/:round+, a single char
+  # repeated across the box, an 8-char string (top, bottom, left, right,
+  # top-left, top-right, bottom-left, bottom-right), or nil for none.
+  #
+  #   space.border = :round
+  #   space.border = "─"          # one char for every edge
+  #   space.border = "──││┌┐└┘"   # explicit edges, same as :light
+  #   space.border = nil          # remove the border
+  #
+  # @param border [Symbol, String, nil]
+  # @return [void]
+
   def border=(border)
     chars = case border
       when Symbol
@@ -111,8 +207,17 @@ eval( method % ([name]*11) ) }
       bottom_right ].map.with_index{ |part,id| [part.to_sym, chars[id]] }.to_h if chars
   end
 
+  ##
   # Build a widget from boundary (left/top/right/bottom), border, margin,
-  # colors, interval, and keymap.
+  # colors, interval, and keymap. Every keyword becomes an instance
+  # variable (+border:+ is applied through {#border=}).
+  #
+  #   box = Typr::Space.new(left: 0, top: 2, right: 0.5, bottom: -4,
+  #     border: :round, colors: { border: :grey50 }, interval: 2)
+  #
+  # @param args [Hash] boundary and visual options (see the class example)
+  # @return [Space]
+
   def initialize args={}
     @max, @keymap, @colors, @margin = 0, {}, {}, '  '
     @left, @top, @interval, @borders = 0, 0, 1, {}

data/lib/stack.rb

@@ -17,10 +17,25 @@ module Typr
   #   KEY_HOME / KEY_END           (jump to first or last pageable row)
 
   class Stack < Space
-    ## Widget configuration. +left+, +top+, +right+, +bottom+ set the viewport; see {Space}.
-    ## +alternate+ toggles striped rows (+:grey10+ background alternating with the default bg).
+    ##
+    # Widget configuration and state: +left+/+top+/+right+/+bottom+ set
+    # the viewport (see {Space}), +alternate+ toggles striped rows
+    # (+:grey10+ against the default bg), +start+ is the scroll offset,
+    # +keymap+ maps key sequences to methods, +selected+ holds picked ids
+    # per type, and +header+ is the top-bar label.
+    #
+    #   stack.start = 3
+    #   stack.header = "Title"
 
     attr_accessor :start, :keymap, :selected, :header
+    ##
+    # +separator+ is the gap between columns, +hints+ the hint characters,
+    # +hints_start+ the offset of the current hint chunk ({#cycle}), and
+    # +modifier+ is +:alt+ after an Alt-digit hint press, +nil+ otherwise.
+    #
+    #   stack.hints = "1234567890"
+    #   stack.modifier   #=> :alt  (after picking with Alt+digit)
+
     attr_accessor :separator, :hints, :hints_start, :modifier
 
     ##
@@ -80,7 +95,9 @@ module Typr
     #   stack.reset              # resets position and selection
     #   stack.reset :position    # only scrolls back to top
     #   stack.reset :selection   # clears all selected rows/columns/fields
-    #   stack.reset [:display, :format]
+    #   stack.reset [:position, :selection]
+    #
+    # @param type [:all, :position, :selection, Array<Symbol>] anything else is ignored
 
     def reset type=:all
       case type
@@ -150,10 +167,16 @@ module Typr
 
     ##
     # Dispatches a key from the terminal to its semantic action and clamps the current page
-    # offset.
+    # offset. Unknown keys only clamp. +confirm+ dispatches to a +confirm+
+    # method, which only Browser defines.
+    #
+    #   stack.send Typr::KEY_DOWN   # scrolls down one row
     #
-    #   stack.send Typr::KEY_UP      # scrolls up one row
-    #   stack.send Typr::KEY_RETURN   # confirms selection
+    # Mouse: wheel scrolls (+:scroll+), a click that misses is +:outside+,
+    # a left/right press on a row returns its id.
+    #
+    # @param key [String, Typr::Mouse] key sequence or mouse event
+    # @return [Object] the keymap action's result; +:scroll+/:outside+/row id for mouse
 
     def send key#, map=nil
       if key.is_a?(Typr::Mouse)
@@ -174,63 +197,100 @@ module Typr
       return response
     end
 
-    ## Scroll to the top of the dataset.
+    ##
+    # Scroll to the top of the dataset.
     #
-    #   stack.to_top
+    #   stack.to_top   # @start => 0
+    #
+    # @return [nil]
 
     def to_top; @start = 0; return end
 
-    ## Scroll to the bottom pageable position (last row minus viewport height).
+    ##
+    # Scroll to the bottom pageable position (last row minus viewport height).
     #
-    #   stack.to_bottom
+    #   stack.to_bottom   # @start => rows - height
+    #
+    # @return [nil]
 
     def to_bottom; @start = rows - height; return end
 
-    ## Step down by one row.
+    ##
+    # Step down by one row.
+    #
+    #   stack.down   # @start += 1
     #
-    #   stack.down
+    # @return [nil]
 
     def down; @start += 1; return end
 
-    ## Step up by one row.
+    ##
+    # Step up by one row.
+    #
+    #   stack.up   # @start -= 1
     #
-    #   stack.up
+    # @return [nil]
 
     def up; @start -= 1; return end
 
-    ## Jump down by one viewport of rows.
+    ##
+    # Jump down by one viewport of rows.
+    #
+    #   stack.page_down   # @start += height
     #
-    #   stack.page_down
+    # @return [nil]
 
     def page_down; @start += height; return end
 
-    ## Jump up by one viewport of rows.
+    ##
+    # Jump up by one viewport of rows.
+    #
+    #   stack.page_up   # @start -= height
     #
-    #   stack.page_up
+    # @return [nil]
 
     def page_up; @start -= height; return end
 
     ##
-    # Blocks the calling thread and lets the user interactively pick items from the current
-    # page using hint characters or arrow keys. After selection, the user must press Return to
-    # confirm (or Escape to abort).
+    # Blocks the calling thread for an interactive pick from the current
+    # page with hint characters or arrow keys. Single picks return the
+    # moment they're made; multi (+...+s+) picks toggle until Return
+    # confirms the selection (Escape aborts, and confirming an empty
+    # selection returns nil).
     #
     # The +type+ argument controls what kind of picker is shown:
     #
-    #   Symbol/String type           | Purpose
-    #   -----------------------------|-------------------------------------------
-    #   +:row, +"file"+              | Pick a single row id
-    #   +"rows"+                     | Multi-select rows
-    #   +:column, +"field"+          | Nested: pick a row then a column
-    #   +:fields+                    | Multi-select fields
-    #   +:none+                      | Navigation-only mode
-    #   anything with +relative_|    | Returns the internal integer index
+    #   Type               | Picks
+    #   -------------------|------------------------------------------------
+    #   +:row+             | Single row id
+    #   +:rows+            | Multi-select row ids (Return confirms)
+    #   +:column+          | One column of the given row (Grid: real index, Text: word offset)
+    #   +:columns+         | Multi-select columns (Return confirms)
+    #   +:field+           | One [row, column] pair, picked row-then-column
+    #   +:fields+          | Multi-select [row, column] pairs
+    #   +:relative_row+    | Viewport-absolute row index (0-based)
+    #   +:none+            | Navigation only; always returns nil
+    #
+    # +:column+, +:columns+, +:field+ (+:fields+) and +:none+ need row
+    # positions, so they only work on Grid and Text — a bare Stack
+    # supports +:row+ and +:rows+. (The +"file"+ type belongs to
+    # {Browser#pick}.)
     #
     #   stack.pick                # single row picker
-    #   stack.pick :column, 3     # pick a column in row 3
-    #   stack.pick "rows"         # multi-select rows
+    #   stack.pick :column, 3     # column of the 4th visible row (page index, not id)
+    #   stack.pick :rows          # multi-select rows
+    #   stack.pick :relative_row  # 0-based index into the viewport
     #
-    # Mouse: left-click a row to pick it; wheel up/down scrolls the page.
+    # Pressing Alt with a hint digit (ESC + digit) picks that hint row and
+    # sets +modifier+ to +:alt+ for the caller. The Return and Escape keys
+    # come from +@keymap+ (+confirm+/+exit+, Return/Escape by default).
+    #
+    # Mouse: left-click a row to pick it (row pickers only); wheel up/down
+    # scrolls the page; clicking outside cancels like Escape.
+    #
+    # @param type [Symbol, String] picker type (table above; symbols documented)
+    # @param row [Integer] page-relative row for +:column+ hints (ignored otherwise)
+    # @return [Integer, Array, nil] row id, [row, column], confirmed selection, or nil
 
     def pick type = :row, row=0 #, key=nil
       type = type.to_s
@@ -298,6 +358,14 @@ module Typr
       return
     end
 
+    ##
+    # Walk the hint characters backwards by one chunk (mirror of {#cycle}),
+    # wrapping to the last full chunk before the start of the list.
+    #
+    #   stack.cycle_back   # hints_start -= hints.size (wraps at 0)
+    #
+    # @return [nil]
+
     def cycle_back
       max = [height-1, rows-1+headspace].min
       @hints_start -= @hints.size
@@ -312,11 +380,15 @@ module Typr
     #
     #   Option          | Default | Description
     #   ----------------|---------|-------------------------------------------
-    #   +keysyms+       | {}      | Custom key-to-method mappings
-    #   +hints+         | +"1234..."+ | Characters used in the hint overlay
+    #   +keymap+        | {}      | Custom name-to-key mappings (override navigation defaults)
+    #   +hints+         | +"1234567890"+ | Characters used in the hint overlay
     #   +alternate+     | true    | Striped row backgrounds
     #   +header+        | nil     | Label shown in a header bar
     #   +separator+     | +" "+   | String drawn between columns (used by Grid)
+    #   +colors+        | {}      | Per-part colors (+hints+, +header+, +selected+, +alternate+, +rows+)
+    #   +selected+      | {}      | Pre-picked ids per type (+rows+, +columns+, +fields+)
+    #
+    #   stack = Typr::Stack.new(keymap: { exit: "q" })   # quit on q instead
 
     def initialize args={}
       @keymap, @separator, @selected = {}, " ", {}