typr 1.7.0 → 1.9.0

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
 
     ##
@@ -174,39 +189,57 @@ 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   # @start => rows - height
     #
-    #   stack.to_bottom
+    # @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
+    #   stack.up   # @start -= 1
+    #
+    # @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
 
@@ -230,7 +263,14 @@ module Typr
     #   stack.pick :column, 3     # pick a column in row 3
     #   stack.pick "rows"         # multi-select rows
     #
+    # Pressing Alt with a hint digit (ESC + digit) picks that hint row and
+    # sets +modifier+ to +:alt+ for the caller.
+    #
     # Mouse: left-click a row to pick it; wheel up/down scrolls the page.
+    #
+    # @param type [Symbol, String] picker type (table above)
+    # @param row [Integer] starting row for column/field hints
+    # @return [Integer, Array, nil] picked id(s), selection on confirm, or nil on abort
 
     def pick type = :row, row=0 #, key=nil
       type = type.to_s
@@ -298,6 +338,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