typr 1.1.4 → 1.2.0

data/lib/terminal.rb

@@ -1,10 +1,16 @@
 require 'io/console'
-require 'readline'
 require 'unicode/display_width'
 
+## Terminal control: raw key input, line editing, cursor movement, ANSI colors
+# and terminal geometry. Widgets get the instance helpers via `include Typr`;
+# class-level helpers (Typr.width, Typr.read_key, ...) drive the whole screen.
+
 module Typr
 
+  # Raw /dev/tty used for key input; falls back to $stdin when unavailable.
   INPUT = (IO.new IO.sysopen("/dev/tty", "r")) rescue $stdin
+
+  # KEY_* escape sequences come from the terminfo database (infocmp -L1).
   `infocmp -L1`.split.each{ |info| key,value = info[0..-2].split("=")
     if value
       value.gsub! '\E', '\e'
@@ -12,15 +18,27 @@ module Typr
       eval "%s=\"%s\"" % [key.upcase,value] if key
     end }
 
+  # Common key aliases and the line-erase escape sequence.
+  ERASE_LINE = "\e[K"
   KEY_ESCAPE = "\e"
   KEY_RETURN = CARRIAGE_RETURN
   KEY_TAB = "\t"
   KEY_PAGEDOWN = KEY_NPAGE
   KEY_PAGEUP = KEY_PPAGE
 
+  # Text attributes (reset, bold, italic, ...) and named 8/256-color tables.
   MODES =  %i[ reset bold italic underline slow fast invert ]
   COLORS = %i[ black red green yellow blue magenta cyan white ]
+  COLOR_MAP = {
+    brown: 130, orange: 208, lime: 118, pink: 218,
+    maroon: 52, navy: 18, teal: 30, olive: 100,
+    coral: 203, tan: 180,
+    dark_red: 88, dark_green: 22, dark_yellow: 58,
+    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
@@ -30,7 +48,7 @@ module Typr
           width -= str[stop..-1][/^\x1b\[[^m]+m|/].size-1
           stop += 1
         elsif (cwidth = (c.ascii_only? ? 1 : Unicode::DisplayWidth.of(c))) +
-          width >= max
+          width > max
           break
         else width += cwidth; stop += 1 end
       end
@@ -40,12 +58,55 @@ module Typr
       str.reverse! if align == :right
       str.join
     else
-      str = str[side == :left ? -max..-1 : 0..max-1]
+      str = clip str, max, side
       str = fade str, side, fade if fade
       return str
     end
   end
 
+  # Truncate +str+ to at most +max+ cells, keeping ANSI color tokens intact
+  # and clipping from +side+ (:left/:right).
+  def clip str, max, side
+    tokens = str.scan(/(\e\[[0-9;]*m)|([^\e]+)/).flatten.compact
+    tokens.reverse! if side == :left
+    kept, used = [], 0
+    tokens.each do |token|
+      if token[0] == ?\e
+        if side == :left
+          kept << token unless kept.empty?
+          break if used >= max
+        else
+          kept << token if used < max
+        end
+        next
+      end
+      break if used >= max
+      size = Unicode::DisplayWidth.of token
+      if used + size <= max
+        kept << token
+        used += size
+      elsif used < max
+        need = max - used
+        chars = token.chars
+        chars.reverse! if side == :left
+        width = 0
+        out = ""
+        chars.each do |char|
+          width += Unicode::DisplayWidth.of char
+          break if width > need
+          out << char
+        end
+        out.reverse! if side == :left
+        kept << out
+        used = max
+      end
+    end
+    kept.reverse!.join if side == :left
+    kept.join
+  end
+
+  # Blend the first (or last) +num+ characters of +str+ into greys to hint
+  # at clipping; +side+ selects which end fades.
   def fade str, side=:left, num=3
     isleft = side == :left
     chars = str[ isleft ? 0..num : -num..-1 ]
@@ -57,9 +118,14 @@ module Typr
       str[0..-num-1] + chars )
   end
 
+  # Strip ANSI escape sequences from +str+.
   def printables str; str.gsub(/\x1b\[[^m]+m|/,'') end
+
+  # Display width of +str+ after stripping ANSI escapes.
   def real_size str; Unicode::DisplayWidth.of( printables(str) ) end
 
+  # Coerce a string into Integer, Float, or Boolean when it matches those
+  # forms (yes/no, true/false); otherwise return it unchanged.
   def coerce_type value
     s = value.to_s
     return nil if s.empty? or /\A(?:nil|NULL)\z/i.match(s)
@@ -74,12 +140,19 @@ module Typr
     end
   end
 
-  def move x=0,y=0; show move_code( x, y ) end
+  # Move the cursor to column +x+, row +y+ (0-based); move_code returns the
+  # escape sequence without writing it.
+  def move x=0,y=0; draw move_code( x, y ) end
   def move_code x=0,y=0; "\e[%i;%if" % [ y+1, x+1 ] end
 
-  def mode name; show mode_code(name) end
+  # Apply a text attribute (+mode+); mode_code returns the escape sequence
+  # without writing it.
+  def mode name; draw mode_code(name) end
   def mode_code name; if id = MODES.index(name.to_s) 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.
   def color_code color, bg=false
     color = color.to_sym if color.is_a? String
     case color
@@ -87,6 +160,8 @@ module Typr
         if id = COLORS.index(color); "\e[#{ id + (bg ? 40 : 30) }m"
         elsif color[/^gr[ae]y\d{,2}$/]
           "\e[%i;5;%im" % [bg ? 48 : 38, 232 + (color[/\d+/].to_f/100*23).to_i]
+        elsif id = COLOR_MAP[color]
+          "\e[%i;5;%im" % [bg ? 48 : 38, id]
         end
       when Integer; "\e[%i;5;%im" % [ bg ? 48 : 38, color]
       when Array; case color.count
@@ -96,31 +171,111 @@ module Typr
     end
   end
 
+  # Read the current background/foreground color pair.
   def get_background; $color[1] end
   def get_foreground; $color[0] end
-  def foreground c=$default[0]; $color[0]=c; show color_code(c) end
-  def background c=$default[1]; $color[1]=c; show color_code(c,true) end
+
+  # Set and apply the foreground/background color; +color+ sets both from a
+  # [fg, bg] pair, a single color, or the module default.
+  def foreground c=$default[0]; $color[0]=c; draw color_code(c) end
+  def background c=$default[1]; $color[1]=c; draw color_code(c,true) end
   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
 
-  def show str; $>.print str end
+  # Write raw +str+ to stdout.
+  def draw str; $>.print str end
+
+  # Clear the whole screen (:screen) or just the current line (:line).
   def self.clear mode=:screen
-    $>.print( { screen: CLEAR_SCREEN, line: DELETE_LINE }[mode]  )
+    $>.print( { screen: CLEAR_SCREEN, line: ERASE_LINE }[mode]  )
   end
 
-  def self.read obj, prompt=''
-    case obj
-      when :key
-        return INPUT.raw{ |tty| tty.sysread 6 } rescue nil unless INPUT.tty?
-        INPUT.raw{ |tty| tty.sysread 6 } rescue return
-      when :line
-        $stdin.tty? ? (line=Readline.readline prompt; print CURSOR_INVISIBLE; line) : $stdin.gets&.chomp
+  ## Reads a single keypress in raw mode.
+  #
+  # Returns the key sequence as a String (e.g. "a" or "\e[A" for up-arrow),
+  # or nil when stdin is not a tty or input is unavailable.
+
+  def self.read_key
+    return INPUT.raw{ |tty| tty.sysread 6 } rescue nil unless INPUT.tty?
+    INPUT.raw{ |tty| tty.sysread 6 } rescue return
+  end
+
+  ## Interactive line editor used for string prompts (search, %str, ...).
+  #
+  # Renders +prompt+ and the query at (left, top) and edits it with
+  # arrow keys, ctrl-arrow word jumps, home/end, delete and backspace.
+  # Returns the query on enter, nil on escape. A block may inspect each
+  # keypress after it is applied; a non-nil return short-circuits the
+  # editor and becomes its return value. When stdin is not a tty, the
+  # query is read from a single line of piped input instead.
+  #
+  #   Typr.read_line "/" do |key, query, cursor|
+  #     filter query
+  #     nil
+  #   end
+
+  def self.read_line prompt='', left: 0, top: 0, initial: '', &block
+    return $stdin.gets&.chomp unless $stdin.tty?
+    query, cursor = initial.dup, initial.length
+    loop do
+      $>.print "\e[%i;%if" % [ top + 1, left + 1 ]
+      $>.print ERASE_LINE
+      $>.print prompt + query
+      $>.print "\e[%i;%if" % [ top + 1, left + 1 +
+        text_width( prompt + query[0...cursor] ) ]
+      key = read_key
+      return nil if key.nil? or key == KEY_ESCAPE
+      return query if key == KEY_RETURN or key == "\n"
+      case key
+        when KEY_LEFT, "\e[D";    cursor -= 1 if cursor > 0
+        when KEY_RIGHT, "\e[C";   cursor += 1 if cursor < query.length
+        when "\e[1;5D", "\eOd";   cursor = word_prev query, cursor
+        when "\e[1;5C", "\eOc";   cursor = word_next query, cursor
+        when KEY_HOME;            cursor = 0
+        when KEY_END;             cursor = query.length
+        when KEY_DC, "\e[3~";     query.slice!(cursor, 1) if cursor < query.length
+        when KEY_BACKSPACE, "\b"
+          if cursor > 0
+            query.slice!(cursor - 1, 1)
+            cursor -= 1
+          end
+        else
+          if key.is_a?(String) and key.each_char.all?{ |char| char.ord.between?(32, 126) }
+            query.insert(cursor, key)
+            cursor += key.length
+          end
+      end
+      cursor = 0 if cursor < 0
+      cursor = query.length if cursor > query.length
+      result = block.call( key, query, cursor ) if block
+      return result unless result.nil?
     end
   end
 
+  # Display width of +str+ after stripping ANSI escapes.
+  def self.text_width str
+    Unicode::DisplayWidth.of( str.gsub(/\x1b\[[^m]+m/, '') )
+  end
+
+  # Move the cursor back to the start of the previous word in +str+.
+  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+.
+  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
+
+  # Query the terminal for the current [row, column] via DSR; [0, 0] when
+  # stdin is not a tty.
   def self.position
     return [0, 0] unless $stdin.tty?
     result = ''
@@ -134,21 +289,31 @@ 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.
   def self.size; IO.console&.winsize || [24, 80] end
   def self.width; size.last-1 end
   def self.height; size.first - 1 end
+
+  # Current cursor row/column (see position).
   def self.row; position.first end
   def self.column; position.last end
+
+  # Call +block+ whenever the terminal is resized (SIGWINCH).
   def self.on_resize &block
     trap(:WINCH, &block)
   end
+  # Enter interactive mode: seed the default colors, hide the cursor and
+  # enable key-mode (application) escapes when stdin is a tty.
   def self.init default=[ :white, :black  ]
-    $color = $default = default
+    $default = default.dup
+    $color = $default.dup
     if $stdin.tty?
       print CURSOR_INVISIBLE
       system "tput smkx"
     end
   end
+  # Restore the terminal: show the cursor, reset colors and clear the screen.
   def self.exit;
   extend self
     if $stdin.tty?
@@ -174,10 +339,10 @@ begin
         foreground color.to_sym;
         background colors[x].to_sym;
         move x*slice,y
-        show chars
+        draw chars
       }
     }
-    (0...256).each{ |i| background i; show ' ' }
+    (0...256).each{ |i| background i; draw ' ' }
 
     move 0, Typr.height
     color [:white, :black]
@@ -185,7 +350,7 @@ begin
     move 15, Typr.height
     color [fg,bg]
     print "     %s / %s     " % [fg,bg]
-    key = Typr.read(:key)
+    key = Typr.read_key
     case key
       when KEY_UP; fg+=1
       when KEY_DOWN; fg-=1

data/lib/text.rb

@@ -4,7 +4,7 @@ require_relative 'stack.rb'
 module Typr
 
   # A vertically scrollable text viewer with word-wrapping, header bar,
-  # row selection via hint characters, and search.
+  # row selection via hint characters, and pager-style search (/ n p).
   #
   # Accepts String, IO, or StringIO input. Content is split into display
   # rows by newlines and line width, then rendered as a sliding window.
@@ -17,8 +17,8 @@ module Typr
   #     top: 2, left: 0.1, right: 0.9, bottom: -4,
   #     border: :round,
   #     colors: { header: [:yellow, :grey30] }
-  #   )
-  #   text.draw
+#   )
+#   text.show
 
   class Text < Stack
 
@@ -68,6 +68,7 @@ module Typr
         end
       end
       @lines << @data.length unless @lines.last == @data.length
+      highlight if @re
     end
     alias :<< :build
 
@@ -80,7 +81,14 @@ module Typr
     def print row=nil
       header = ( row == :header )
       return super unless row and @lines[ row + 1 ] unless header
-      show prepare( ( header ? @header : @page[ row-@start ] ), width )
+      text = ( header ? @header : @page[ row-@start ] )
+      if row.is_a?(Integer) and @search[:matches].include? row
+        background @colors[:search]
+        draw prepare( text, width )
+        background
+      else
+        draw prepare( text, width )
+      end
     end
 
     # Returns word-boundary column offsets for a given page row.
@@ -95,9 +103,9 @@ module Typr
     # Full draw cycle: rebuilds on resize, computes visible lines,
     # and renders the viewport with borders and hints.
     #
-    #   text.draw
+    #   text.show
 
-    def draw
+    def show
       (build; @lastwidth = width) if width != @lastwidth
       range = @lines[@start..@start+height]
       page = StringIO.new @data[range.first..range.last]
@@ -111,6 +119,62 @@ module Typr
 
     def rows; @lines.count end
 
+    ##
+    # Pager-style search over the buffer, modeled after less/vim.
+    #
+    # With a +query+ (String, matched literally, or Regexp) it stores the
+    # pattern, highlights every matching line, and scrolls to the first
+    # match from the current position. +dir+ is +:forward+ or +:backward+.
+    # Returns the matched line id, or nil when nothing matches.
+    #
+    # With no argument it prompts interactively for a pattern at the bottom
+    # of the screen (pressing Return searches, Escape aborts).
+    #
+    # Matching is smart-case: lowercase queries are case-insensitive;
+    # a query containing an uppercase letter is case-sensitive.
+    #
+    #   text.search "needle"    # => 12 (or nil)
+    #   text.search /^TODO/     # => 3
+    #   text.search "needle", :backward   # search upward
+
+    def search query=nil, dir=:forward
+      return search_prompt if query.nil?
+      @search[:pattern] = query
+      @search[:dir] = dir
+      @search[:last] = nil
+      @re = query.is_a?(Regexp) ? query :
+        Regexp.new( Regexp.escape( query ),
+          ( query[/[A-Z]/] ? 0 : Regexp::IGNORECASE ) )
+      highlight
+      step
+    end
+
+    ## Jump to the next match of the last search (wrap-around). Returns its line id or nil.
+
+    def search_next; @search[:dir] = :forward; step end
+
+    ## Jump to the previous match of the last search (wrap-around). Returns its line id or nil.
+
+    def search_prev; @search[:dir] = :backward; step end
+
+    ## Recompute the set of lines containing the current pattern.
+
+    def highlight
+      @search[:matches] = @re ?
+        @lines[0...-1].each_index.select{ |i|
+          @data[ @lines[i] ... @lines[i+1] ][ @re ] } : []
+      return
+    end
+
+    ## Clear the search pattern and all match highlights.
+
+    def highlight_clear
+      @re = @search[:pattern] = nil
+      @search[:matches] = []
+      @search[:last] = nil
+      return
+    end
+
     # Creates a new Text widget.
     #
     #   text = Typr::Text.new(input: "hello", header: "Title")
@@ -119,11 +183,62 @@ module Typr
     def initialize args={}
       @tabspace = 2
       @data, @lines, @tail = "", [0], ""
+      @search = { pattern: nil, dir: :forward, last: nil, matches: [] }
       super args
-      @colors = { header: :yellow }.merge( @colors || {} )
+      @colors = { header: :yellow, search: :grey20 }.merge( @colors || {} )
+      @keymap = { search: ?/, search_next: ?n, search_prev: ?p }.merge @keymap
       @lastwidth = width
       self << @input
     end
+
+    def reset type=:all
+      case type
+        when :search; highlight_clear
+        when :all; reset [:position, :selection, :search]; return
+      end
+      super
+    end
+
+    private
+
+    def live_search query
+      query.empty? ? highlight_clear : search(query)
+    end
+
+    def step
+      matches = @search[:matches]
+      return nil if matches.empty?
+      last = @search[:last]
+      if @search[:dir] == :backward
+        id = matches.reverse.find{ |m| last and m < last }
+        id ||= ( last ? matches.last : matches.reverse.find{ |m| m <= @start } || matches.last )
+      else
+        id = matches.find{ |m| last and m > last }
+        id ||= ( last ? matches.first : matches.find{ |m| m >= @start } || matches.first )
+      end
+      @search[:last] = id
+      @start = id
+      return id
+    end
+
+    def search_prompt
+      query = @search[:pattern].is_a?(String) ? @search[:pattern].dup : ''
+      saved = { re: @re, pattern: @search[:pattern],
+        matches: @search[:matches].dup, last: @search[:last], start: @start }
+      result = Typr.read_line '/', left: left, top: Typr.height - 1, initial: query,
+        &->(key, query, _) {
+          live_search query
+          nil
+        }
+      if result
+        return search(result) unless result.empty?
+        return search(@search[:pattern]) if @search[:pattern]
+      end
+      @re = saved[:re]; @search[:pattern] = saved[:pattern]
+      @search[:matches] = saved[:matches]; @search[:last] = saved[:last]
+      @start = saved[:start]
+      return
+    end
   end
 
 end

data/lib/typr.rb

@@ -1,6 +1,5 @@
 # typr is a Ruby library for building interactive terminal-based user interfaces.
-# It provides layout primitives, widgets, and event-driven interaction built on
-# top of curses.
+# It provides layout primitives, widgets, and event-driven interaction.
 #
 # == Widgets
 #
@@ -16,8 +15,8 @@
 #   Typr.init               # Initialize terminal (hide cursor, enable key mode)
 #   Typr.clear              # Clear entire screen
 #   Typr.clear :line        # Clear current line only
-#   key = Typr.read(:key)   # Read a single keypress
-#   line = Typr.read(:line) # Read a line of text input
+#   key = Typr.read_key      # Read a single keypress
+#   line = Typr.read_line "> " # Edit a line of text (enter to accept, esc to abort)
 #   Typr.exit               # Restore terminal state
 #
 # == Layout Properties
@@ -38,8 +37,8 @@
 #     header: ['Name', 'Age'],
 #     format: [:max, :right]
 #   )
-#   grid.draw
-#   key = Typr.read(:key)
+#   grid.show
+#   key = Typr.read_key
 #   Typr.exit
 #
 # == Installation