typr 1.8.0 → 1.9.2

data/lib/terminal.rb

@@ -46,41 +46,71 @@ module Typr
     const_set cap.upcase, entry[cap] || seq
   end
 
-  # Common key aliases and the line-erase escape sequence.
+  # Line-erase escape sequence (used by {Typr.clear} :line).
   ERASE_LINE = "\e[K"
   # Reset foreground/background to the terminal defaults.
   ORIG_COLORS = "\e[39;49m"
+  # Escape: abort a pick or prompt.
   KEY_ESCAPE = "\e"
+  # Enter: confirm a pick (alias of CARRIAGE_RETURN).
   KEY_RETURN = CARRIAGE_RETURN
+  # Tab: cycle hint chunks; completes the word in {Typr.read_line}.
   KEY_TAB = "\t"
+  # Shift+Tab: cycle hint chunks backwards.
   KEY_BACK_TAB = "\e[Z"
+  # Alt+Backspace: delete the word before the cursor.
   KEY_ALT_BACKSPACE = "\e\x7f"
+  # Alt+Left: move the cursor to the start of the previous word.
   KEY_ALT_LEFT = "\e[1;3D"
+  # Alt+Right: move the cursor to the start of the next word.
   KEY_ALT_RIGHT = "\e[1;3C"
+  # Page down: jump one viewport (alias of KEY_NPAGE).
   KEY_PAGEDOWN = KEY_NPAGE
+  # Page up: jump one viewport backwards (alias of KEY_PPAGE).
   KEY_PAGEUP = KEY_PPAGE
 
-  # Enable/disable mouse reporting. Universal private modes, independent of
-  # terminfo: 1000 = button press/release/wheel, 1006 = SGR coordinates.
+  # Enable mouse reporting (buttons + wheel): 1000 press/release, 1006 SGR coordinates.
   MOUSE_ON = "\e[?1000h\e[?1006h"
+  # Disable mouse reporting.
   MOUSE_OFF = "\e[?1000l\e[?1006l"
+  # Enter the alternate screen buffer.
   ALT_SCREEN_ON  = "\e[?1049h"
+  # Leave the alternate screen buffer.
   ALT_SCREEN_OFF = "\e[?1049l"
 
   # A mouse event decoded from the input stream. +x+ / +y+ are 1-based
   # terminal coordinates; +button+ is 0=left, 1=middle, 2=right, or 4-7 for
   # the wheel (up/down/left/right); +modifiers+ holds the SGR shift/alt/ctrl
   # bits. Non-widget code can test `key.is_a?(Typr::Mouse)`.
+  #
+  #   Typr::Mouse.new(0, 10, 5, :press, 0)
+  #   m = Typr.decode_mouse "\e[<0;10;5M"
+  #   m.press?    #=> true
+  #   m.left?     #=> true
+  #   m.alt?      #=> true   (with the SGR alt bit set)
+  #   m.to_s      #=> "press button=0 x=10 y=5"
+  # +action+ is +:press+, +:release+, or +:motion+ (move with a button held).
   Mouse = Struct.new(:button, :x, :y, :action, :modifiers) do
+    # True on button press (the moment to pick a row).
     def press?;   action == :press end
+    # True on button release.
     def release?; action == :release end
+    # True for any wheel button (4-7).
     def wheel?;   button.between?(4, 7) end
+    # True for wheel-up (button 4); scrolls a picker up.
     def wheel_up?;   button == 4 end
+    # True for wheel-down (button 5); scrolls a picker down.
     def wheel_down?; button == 5 end
+    # True for the left button; pickers treat it as a hint-digit press.
     def left?;   button == 0 end
+    # True for the middle button.
     def middle?; button == 1 end
+    # True for the right button.
     def right?;  button == 2 end
+    # True when the SGR alt/meta bit is set — callers may treat an
+    # Alt+click like a right-click.
     def alt?;     ( modifiers & 8 ) != 0 end
+    # Human-readable one-line summary.
     def to_s; "%s button=%i x=%i y=%i%s" % [ action, button, x, y,
       ( modifiers > 0 ? " modifiers=#{modifiers}" : "" ) ] end
   end
@@ -88,7 +118,9 @@ module Typr
   # Text attributes (reset, bold, italic, ...) and named 8/256-color tables.
   MODES =  %i[ reset bold dim italic underline slow fast invert ]
   MODES[25] = :steady
+  # The eight basic color names accepted by {#color_code}.
   COLORS = %i[ black red green yellow blue magenta cyan white ]
+  # Named colors mapped to 8-bit palette ids (used by {#color_code}).
   COLOR_MAP = {
     brown: 130, orange: 208, lime: 118, pink: 218,
     maroon: 52, navy: 18, teal: 30, olive: 100,
@@ -97,35 +129,41 @@ module Typr
     dark_blue: 18, dark_magenta: 89, dark_cyan: 30
   }
 
-  # Pad or clip +str+ to exactly +max+ cells, honoring +align+ (:left/:right),
-  # trimming from +side+, with an optional trailing +fade+.
-  def prepare str, max, align=:left, side=:right, fade=false
-    stop = width = real_size( str )
-    unless str.ascii_only? and width == str.size
-      stop = width = 0
-      str.each_char do |c|
-        if c == ?\e
-          width -= str[stop..-1][/^\x1b\[[^m]+m|/].size-1
-          stop += 1
-        elsif (cwidth = (c.ascii_only? ? 1 : Unicode::DisplayWidth.of(c))) +
-          width > max
-          break
-        else width += cwidth; stop += 1 end
-      end
-    end
-    if ( space = ( max - width ) ) > 0
-      str = [ str[0..stop-1], " " * space ]
-      str.reverse! if align == :right
-      str.join
-    else
-      str = clip str, max, side
-      str = fade str, side, fade if fade
-      return str
-    end
+  ##
+  # Fit +str+ to exactly +max+ cells: pad the shortfall with spaces
+  # (before the text when +align+ is :right), or truncate the overflow
+  # from +side+, keeping ANSI escapes intact.
+  #
+  #   space.prepare "ab", 5            #=> "ab   "
+  #   space.prepare "ab", 5, :right    #=> "   ab"
+  #   space.prepare "long text", 4     #=> "long"  (clipped)
+  #   space.prepare "\e[31mRED\e[0m", 5 #=> "\e[31mRED\e[0m  "
+  #
+  # @param str [String] text; ANSI escapes count as zero width
+  # @param max [Integer] target width in cells
+  # @param align [Symbol] :left pads after, :right pads before
+  # @param side [Symbol] truncation side, :left keeps the tail
+  # @return [String]
+
+  def prepare str, max, align=:left, side=:right
+    str = clip str, max, side if real_size(str) >= max
+    pad = " " * (max - real_size(str))
+    align == :right ? pad + str : str + pad
   end
 
+  ##
   # Truncate +str+ to at most +max+ cells, keeping ANSI color tokens intact
   # and clipping from +side+ (:left/:right).
+  #
+  #   space.clip "abcdef", 4, :right   #=> "abcd"
+  #   space.clip "abcdef", 4, :left    #=> "cdef"
+  #   space.clip "\e[31mlongtext\e[0m", 4, :left   #=> "\e[31mtext"
+  #
+  # @param str [String] text possibly containing ANSI escapes
+  # @param max [Integer] maximum width in cells
+  # @param side [Symbol] :left keeps the tail, :right keeps the head
+  # @return [String]
+
   def clip str, max, side
     tokens = str.scan(/(\e\[[0-9;]*m)|([^\e]+)/).flatten.compact
     tokens.reverse! if side == :left
@@ -165,8 +203,17 @@ module Typr
     kept.join
   end
 
+  ##
   # Blend the first (or last) +num+ characters of +str+ into greys to hint
   # at clipping; +side+ selects which end fades.
+  #
+  #   space.fade "longtext", :right   #=> "long" + grey(e,x,t)
+  #
+  # @param str [String] already-clipped text
+  # @param side [Symbol] :left or :right (which end fades)
+  # @param num [Integer] number of characters to fade
+  # @return [String]
+
   def fade str, side=:left, num=3
     isleft = side == :left
     chars = str[ isleft ? 0..num : -num..-1 ]
@@ -178,19 +225,44 @@ module Typr
       str[0..-num-1] + chars )
   end
 
+  ##
   # Strip ANSI escape sequences and control characters (except \n, \t)
   # from shell-generated text, leaving only printable content.
+  #
+  #   space.sanitize "\e[31mred\e[0m plain"   #=> "red plain"
+  #
+  # @param str [String] raw text
+  # @return [String]
+
   def sanitize str
     str.scrub
        .gsub(/\e(?:\[[0-9;?]*[ -\/]*[@-~]|\][^\a\e]*(?:\a|\e\\)|[()=><0A])/, '')
        .gsub(/[\x00-\x08\x0b-\x1f\x7f]/, '')
   end
 
+  ##
   # Display width of +str+ after stripping ANSI escapes and control chars.
+  #
+  #   space.real_size "\e[31mabc\e[0m"   #=> 3
+  #
+  # @param str [String] text possibly containing ANSI escapes
+  # @return [Integer] width in cells
+
   def real_size str; Unicode::DisplayWidth.of( sanitize(str) ) end
 
+  ##
   # Coerce a string into Integer, Float, or Boolean when it matches those
-  # forms (yes/no, true/false); otherwise return it unchanged.
+  # forms (yes/no, true/false); otherwise return it unchanged. Empty
+  # strings and +nil+/+NULL+ become nil.
+  #
+  #   space.coerce_type "42"     #=> 42
+  #   space.coerce_type "3.14"   #=> 3.14
+  #   space.coerce_type "yes"    #=> true
+  #   space.coerce_type "hello"  #=> "hello"  (unchanged)
+  #
+  # @param value [Object] cell value (usually a String)
+  # @return [Integer, Float, Boolean, nil, Object]
+
   def coerce_type value
     s = value.to_s
     return nil if s.empty? or /\A(?:nil|NULL)\z/i.match(s)
@@ -205,19 +277,67 @@ module Typr
     end
   end
 
-  # Move the cursor to column +x+, row +y+ (0-based); move_code returns the
-  # escape sequence without writing it.
+  ##
+  # Move the cursor to column +x+, row +y+ (0-based); move_code returns
+  # the escape sequence without writing it.
+  #
+  #   space.move 0, 0      # prints "\e[1;1f"
+  #   space.move_code 0, 0 #=> "\e[1;1f"
+  #
+  # @param x [Integer] column (0-based)
+  # @param y [Integer] row (0-based)
+  # @return [void] / [String] move_code returns the sequence
+
   def move x=0,y=0; draw move_code( x, y ) end
+
+  ##
+  # The escape sequence for {#move}, without writing it.
+  #
+  #   space.move_code 0, 0   #=> "\e[1;1f"
+  #
+  # @param x [Integer] column (0-based)
+  # @param y [Integer] row (0-based)
+  # @return [String]
+
   def move_code x=0,y=0; "\e[%i;%if" % [ y+1, x+1 ] end
 
+  ##
   # Apply a text attribute (+mode+); mode_code returns the escape sequence
   # without writing it.
+  #
+  #   space.mode :bold      # prints "\e[1m"
+  #   space.mode_code :bold #=> "\e[1m"
+  #
+  # @param name [Symbol] one of +MODES+ (:bold, :underline, :invert, ...)
+  # @return [void] / [String] mode_code returns the sequence
+
   def mode name; draw mode_code(name) end
+
+  ##
+  # The escape sequence for {#mode}, without writing it.
+  #
+  #   space.mode_code :bold   #=> "\e[1m"
+  #
+  # @param name [Symbol] one of +MODES+
+  # @return [String, nil] nil for unknown attributes
+
   def mode_code name; if id = MODES.index(name.to_s.to_sym) then "\e[#{ id }m" end end
 
+  ##
   # Build the ANSI code for +color+ (a Symbol name, greyN, Integer palette id,
   # or [r,g,b] / [fg,bg] Array), optionally as a background; when false the
   # color is emitted as a foreground.
+  #
+  #   space.color_code :red            #=> "\e[31m"
+  #   space.color_code :red, true      #=> "\e[41m"   (background)
+  #   space.color_code :grey50         #=> "\e[38;5;243m"
+  #   space.color_code [10, 200, 30]   #=> "\e[38;2;10;200;30m"
+  #   space.color_code [:cyan, :black] #=> "\e[36m\e[40m"  (fg, bg pair)
+  #
+  # @param color [Symbol, Integer, Array] color name, palette id, RGB, or pair
+  # @param bg [Boolean] emit as background when true
+  # @return [String, nil] ANSI escape sequence (nil for unknown names)
+
   def color_code color, bg=false
     color = color.to_sym if color.is_a? String
     case color
@@ -288,43 +408,102 @@ module Typr
     }.join
   end
 
+  ##
   # Read the current background/foreground color pair.
+  #
+  #   space.get_foreground   #=> :white
+  #   space.get_background   #=> :black
+  #
+  # @return [Object] the active color value
+
   def get_background; $color[1] end
+
+  ##
+  # The currently applied foreground color.
+  #
+  #   space.get_foreground   #=> :white
+  #
+  # @return [Object] the active color value
+
   def get_foreground; $color[0] end
 
+  ##
   # Set and apply the foreground/background color; +color+ sets both from a
   # [fg, bg] pair, a single color, or the module default.
+  #
+  #   space.foreground :red     # print in red
+  #   space.background :blue    # paint the background blue
+  #   space.color [:cyan, :black]  # set both
+  #   space.color               # restore the default pair
+  #
+  # @param c [Symbol, Integer, Array, nil] color or [fg, bg] pair
+  # @return [void]
+
   def foreground c=$default[0]; $color[0]=c; draw color_code(c) end
+
+  ##
+  # Paint the background with +c+ (see {#foreground}).
+  #
+  #   space.background :blue
+  #
+  # @param c [Symbol, Integer, Array, nil] background color
+  # @return [void]
+
   def background c=$default[1]; $color[1]=c; draw color_code(c,true) end
+
+  ##
+  # Set both foreground and background: a [fg, bg] pair, a single color
+  # applied to both, or no argument to restore the module default pair.
+  #
+  #   space.color [:cyan, :black]
+  #   space.color               # default pair back
+  #
+  # @param c [Symbol, Integer, Array, nil] color or [fg, bg] pair
+  # @return [void]
+
   def color c=$default
     c = [c] unless c.is_a? Array and c.count == 2
     foreground c[0] if c[0]
     background c[1] if c[1]
   end
 
+  ##
   # Write raw +str+ to stdout.
+  #
+  #   space.draw "hi"   # prints hi at the cursor
+  #
+  # @param str [String] escape sequences and text to emit
+  # @return [nil]
+
   def draw str; $>.print str end
 
+  ##
   # Clear the whole screen (:screen) or just the current line (:line).
+  #
+  #   Typr.clear         # clear the screen
+  #   Typr.clear :line   # clear the current line
+  #
+  # @param mode [:screen, :line]
+  # @return [nil]
+
   def self.clear mode=:screen
     $>.print( { screen: CLEAR_SCREEN, line: ERASE_LINE }[mode]  )
   end
 
-  ## Reads a single keypress in raw mode.
+  ##
+  # Reads a single keypress in raw mode.
   #
   # Returns the key sequence as a String (e.g. "a" or "\e[A" for up-arrow),
   # or a Typr::Mouse for a mouse report, or nil when stdin is not a tty or
-  # input is unavailable.
+  # input is unavailable. Keys arriving inside an overtype quiet window
+  # ({#suppress_keys}) are discarded first.
+  #
+  #   key = Typr.read_key   #=> "s" | "\e[A" | #<Typr::Mouse> | nil
+  #
+  # @return [String, Typr::Mouse, nil]
 
   def self.read_key
-    if quiet_window?
-      loop do
-        remaining = @suppress_until - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        break if remaining <= 0
-        break unless IO.select([INPUT], nil, nil, remaining)
-        begin INPUT.read_nonblock(1024) rescue break end
-      end
-    end
+    drain_quiet
     read = ->(tty) do
       str = tty.sysread 6
       if str.start_with?("\e[M") and str.size < 6
@@ -344,9 +523,16 @@ module Typr
     decode_mouse(raw) || raw
   end
 
-  ## Decode a raw input string into a {Typr::Mouse} event, or nil when +raw+
+  ##
+  # Decode a raw input string into a {Typr::Mouse} event, or nil when +raw+
   # is not a mouse report. Handles both SGR (CSI < b ; x ; y M/m) and the
   # legacy X10 (CSI M + three bytes) encodings.
+  #
+  #   Typr.decode_mouse "\e[<0;10;5M"   #=> #<struct button=0 x=10 y=5 action=:press modifiers=0>
+  #   Typr.decode_mouse "abc"           #=> nil
+  #
+  # @param raw [String] raw bytes read from the terminal
+  # @return [Typr::Mouse, nil]
 
   def self.decode_mouse raw
     if (m = raw.match(/\A\e\[<(\d+);(\d+);(\d+)([Mm])\z/))
@@ -392,18 +578,53 @@ module Typr
   # subprocess handoff via +flush_overtype+.
   OVERTYPE_QUIET = 0.5
 
+  ##
+  # Arm the overtype quiet window: every key arriving in the next
+  # +timeout+ seconds is discarded by {Typr.read_key}, so a double-tapped
+  # Enter or trailing characters after an auto-confirmed pick cannot
+  # re-trigger anything. Called by +Grid#pick+ on auto-return.
+  #
+  #   Typr.suppress_keys          # 0.5s window (OVERTYPE_QUIET)
+  #   Typr.suppress_keys 1.0      # custom window in seconds
+  #
+  # @param timeout [Numeric] window length in seconds
+  # @return [Numeric] the monotonic deadline
+
   def self.suppress_keys timeout=OVERTYPE_QUIET
+    @suppress_quiet = timeout
     @suppress_until = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
   end
 
-  def self.quiet_window?
-    @suppress_until and $stdin.tty? and
+  ##
+  # Wait out an armed overtype window: switch to raw mode (canonical-
+  # buffered keystrokes are invisible to select) and discard arrivals
+  # until a full window passes with none — each arrival restarts it.
+  # No-op unless armed by {Typr.suppress_keys}. Best-effort: never raises.
+  #
+  #   Typr.suppress_keys          # arm a 0.5s window
+  #   Typr.send(:drain_quiet)     # wait it out, swallowing arrivals
+  #
+  # @return [nil]
+
+  def self.drain_quiet
+    return unless @suppress_until and $stdin.tty? and
       @suppress_until > Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    INPUT.raw do
+      loop do
+        wait = @suppress_until - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        break if wait <= 0
+        break unless IO.select([INPUT], nil, nil, wait)
+        begin INPUT.read_nonblock(1024)
+        rescue IO::WaitReadable then break end
+        @suppress_until = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @suppress_quiet
+      end
+    end
+    nil
+  rescue StandardError
+    nil
   end
 
-  def self.flush_overtype
-    drain_input if quiet_window?
-  end
+  private_class_method :drain_quiet
 
   ## Interactive line editor used for string prompts (search, %str, ...).
   #
@@ -418,15 +639,31 @@ module Typr
   # of candidates; TAB then replaces the word through a pick grid. Each
   # candidate is either a plain String or [text, color-pair] to tint the
   # pick entry. The callable's content is arbitrary - shells, tags, ...
+  # It takes the text before the cursor and returns an Array of candidates.
   #
   # +regex+ is a Hash of Regexp => color (see {.paint}) applied to the
   # query as it is rendered; matched regions restore the prompt's trailing
   # color code.
   #
+  # +history+ is an Array of previous queries recalled with Up/Down;
+  # +redraw+ repaints the caller's screen after a completion pick.
+  #
   #   Typr.read_line "/" do |key, query, cursor|
   #     filter query
   #     nil
   #   end
+  #   Typr.read_line "> ", initial: "ls ", history: @recent   #=> "ls -l"
+
+  # @param prompt [String] text rendered before the query (keep a color code trailing)
+  # @param left [Integer] screen column (0-based)
+  # @param top [Integer] screen row (0-based)
+  # @param initial [String] prefilled query
+  # @param completions [#call, nil] +->(prefix) { candidates }+ or nil
+  # @param redraw [#call, nil] zero-arg repaint after a completion pick
+  # @param regex [Hash, Symbol, nil] paint map or scheme (see {.paint})
+  # @param history [Array<String>, nil] previous queries for Up/Down
+  # @param block [Proc] +->(key, query, cursor)+ inspector (non-nil short-circuits)
+  # @return [Object, nil] the query, a block short-circuit, or nil on Escape
 
   def self.read_line prompt='', left: 0, top: 0, initial: '', completions: nil, redraw: nil, regex: nil, history: nil, &block
     return $stdin.gets&.chomp unless $stdin.tty?
@@ -525,14 +762,30 @@ module Typr
     end
   end
 
+  ##
   # Display width of +str+ after stripping ANSI escapes.
+  #
+  #   Typr.text_width "\e[31mabc\e[0m"   #=> 3
+  #
+  # @param str [String] text possibly containing ANSI escapes
+  # @return [Integer] width in cells
+
   def self.text_width str
     Unicode::DisplayWidth.of( str.gsub(/\x1b\[[^m]+m/, '') )
   end
 
+  ##
   # Visible substring of +str+ starting at display-width +offset+, at most
   # +width+ cells wide. ANSI escapes are zero-width and carried through so
   # color state applies inside the window.
+  #
+  #   Typr.slice_width "hello world", 6, 5   #=> "world"
+  #
+  # @param str [String] text possibly containing ANSI escapes
+  # @param offset [Integer] display-width start of the window
+  # @param width [Integer] window size in cells
+  # @return [String]
+
   def self.slice_width str, offset, width
     vis = 0
     slice = +""
@@ -552,22 +805,46 @@ module Typr
     slice
   end
 
+  ##
   # Move the cursor back to the start of the previous word in +str+.
+  #
+  #   Typr.word_prev "foo bar baz", 8   #=> 4
+  #
+  # @param str [String] the text being edited
+  # @param cursor [Integer] current cursor position
+  # @return [Integer] new cursor position
+
   def self.word_prev str, cursor
     cursor -= 1 while cursor > 0 and str[cursor - 1] == ' '
     cursor -= 1 while cursor > 0 and str[cursor - 1] != ' '
     cursor
   end
 
+  ##
   # Move the cursor forward to the start of the next word in +str+.
+  #
+  #   Typr.word_next "foo bar baz", 4   #=> 7
+  #
+  # @param str [String] the text being edited
+  # @param cursor [Integer] current cursor position
+  # @return [Integer] new cursor position
+
   def self.word_next str, cursor
     cursor += 1 while cursor < str.length and str[cursor] == ' '
     cursor += 1 while cursor < str.length and str[cursor] != ' '
     cursor
   end
 
+  private_class_method :slice_width, :word_prev, :word_next
+
+  ##
   # Query the terminal for the current [row, column] via DSR; [0, 0] when
-  # stdin is not a tty.
+  # stdin is not a tty. Blocks until the terminal answers \e[6n.
+  #
+  #   Typr.position   #=> [12, 40]  (row, column)
+  #
+  # @return [Array<Integer>] [row, column]
+
   def self.position
     return [0, 0] unless $stdin.tty?
     result = ''
@@ -581,22 +858,78 @@ module Typr
     result[/[\d;]+/].split(?;).map &:to_i
   end
 
-  # Terminal [rows, cols] (defaults to 24x80 when undetectable); width/height
-  # return the usable last column/row.
+  ##
+  # Terminal [rows, cols] (defaults to 24x80 when undetectable);
+  # +width+/+height+ return the usable last column/row.
+  #
+  #   Typr.size     #=> [24, 80]
+  #   Typr.width    #=> 79
+  #   Typr.height   #=> 23
+  #
+  # @return [Array<Integer>] [rows, cols]
+
   def self.size; IO.console&.winsize || [24, 80] end
+
+  ##
+  # Usable last column (terminal width minus one).
+  #
+  #   Typr.width   #=> 79
+  #
+  # @return [Integer]
+
   def self.width; size.last-1 end
+
+  ##
+  # Usable last row (terminal height minus one).
+  #
+  #   Typr.height   #=> 23
+  #
+  # @return [Integer]
+
   def self.height; size.first - 1 end
 
-  # Current cursor row/column (see position).
+  ##
+  # Current cursor row/column (see {position}).
+  #
+  #   Typr.row      #=> 12
+  #   Typr.column   #=> 40
+  #
+  # @return [Integer]
+
   def self.row; position.first end
+
+  ##
+  # Current cursor column (see {position}).
+  #
+  #   Typr.column   #=> 40
+  #
+  # @return [Integer]
+
   def self.column; position.last end
 
+  ##
   # Call +block+ whenever the terminal is resized (SIGWINCH).
+  #
+  #   Typr.on_resize { grid.show }
+  #
+  # @param block [Proc] handler invoked on resize
+  # @return [Integer] the signal handler (trap's return)
+
   def self.on_resize &block
     trap(:WINCH, &block)
   end
-  # Enter interactive mode: seed the default colors, hide the cursor, enable
-  # key-mode (application) escapes and mouse reporting when stdin is a tty.
+
+  ##
+  # Enter interactive mode: seed the default colors, hide the cursor,
+  # enable key-mode (application) escapes and mouse reporting when stdin
+  # is a tty.
+  #
+  #   Typr.init                    # default [:white, :black]
+  #   Typr.init [:cyan, :grey10]    # custom default pair
+  #
+  # @param default [Array<Symbol>] initial [fg, bg] pair
+  # @return [void]
+
   def self.init default=[ :white, :black  ]
     $default = default.dup
     $color = $default.dup
@@ -606,8 +939,13 @@ module Typr
       print MOUSE_ON
     end
   end
-  # Restore the terminal: show the cursor, reset keypad/colors, disable mouse
-  # reporting and clear.
+  ##
+  # Restore the terminal: show the cursor, reset keypad/colors, disable
+  # mouse reporting, and clear.
+  #
+  #   Typr.exit   # => nil
+  #
+  # @return [nil]
   def self.exit;
   extend self
     if $stdin.tty?