listpager 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9d70bf27f951f700d53cc6fb25c3c62d652ae150
+  data.tar.gz: 8483fcf02b0b1373a10c4d1f5ef0585ef202cc60
+SHA512:
+  metadata.gz: 25c7f7684495706aad4efe72393af0228c02c2a00a258b5c00fdcc1a4b1740a40fe8f7a5e841c9fa2ddc6b7fc6521cfd001e2e5f9ffafe3ca4e9d8fbeabf2027
+  data.tar.gz: 22e83c69890005484f1e75cac5332965f24992c646bdddab4b81aa5d2ccbcce2392515266fa10b924763ec5cd14578b2c20f45a06c6c0ec8f846155369491bdd

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in listpager.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Mike Owens <mike@meter.md>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,111 @@
+# listpager
+
+## Introduction
+listpager is a terminal listbox.  It reads `stdin` for a list of items, goes all
+interactive, and writes events to `stdout` as the user interacts with it.
+
+![listpager in action](./doc/screenshot.png)
+
+*listpager is in the left-hand panel*
+
+listpager has proportional scroll bars, and can handle lists of any length.  It
+handles terminal resizing just fine.
+
+listpager was written as a component of [Cult][1], a fleet management tool.  Cult's
+interactive mode is a specially-crafted tmux session consisting of tools that
+talk to each other.  listpager is the node selection widget.
+
+So basically, you may want to `popen` listpager, print a list of somethings to
+its `stdin`, and listen on its `stdout`.
+
+```ruby
+listpager = IO.popen('listpager', 'r+')
+
+# You don't want buffered IO
+listpager.sync = true
+
+50.times do |i|
+  listpager.puts "Item #{i}"
+end
+
+# Enter command mode.
+listpager.puts "%%"
+listpager.puts "select 35"
+```
+
+If you want to play with the protocol, it's easiest to use two terminals and
+`socat` (some implementations of `nc`/`netcat` do weird FD juggling which
+ends up sending raw keyboard character input back to the client.).
+
+Set up one like:
+
+```bash
+socat TCP-LISTEN:4500,reuseaddr EXEC:'listpager'
+```
+
+And a "client", like:
+```bash
+socat TCP:localhost:4500 -
+```
+
+Add some items on your keyboard, then enter `%%` to enter command mode.  Another
+`%%` will put you back in command mode.  If you need a literal `%%` list item,
+escape it with `\%%`.  If you need a literal `\\%%`, you're out of luck, because
+complete escaping isn't available yet.
+
+There are a lot of obvious things the protocol could do, that it doesn't
+currently.  It's way low-hanging fruit for any contributors (`clear`, `rename`,
+`move`, etc.)
+
+## Protocol
+listpager reads each item from stdin, and it becomes a list item.  As the user
+arrows through the list, it outputs messages like:
+
+`select 21 apples` where `21` is the index into the list, and `abacate` is the
+caption.  Any other keys pressed on an item are written out like
+`keypress enter apples`.
+
+listpager stops considering input bulk list items once it sees: `%%`, where it
+enters command mode.  Currently, command mode does nothing, but in the future,
+it will allow the calling program to instruct listpager to select certain items,
+ask for statuses, manipulate the list, add badges, change captions, etc.
+
+
+## Dependencies and Installation
+Install listpager with `gem install listpager`.  It has few dependencies:
+currently only `ncurses-ruby`.
+
+
+## Implementation Notes
+curses is terrible but portable.  'curses' doesn't expose enough to be useful,
+'ncurses-ruby' is about as good as you'll do in Ruby.
+
+
+## Upcoming Features
+Right now, listpager does exactly what Cult needs, and nothing more.  For it to
+be more functional, I'd like to add a few features:
+
+  * `listpager -1`, for displaying a list, and just outputting the first item
+    the user selected with enter, ala Zenity/dialog.
+  * A search/filter activated with the `/` key
+  * Mouse support, with scroll wheels.
+  * Checkboxes
+  * Extend command mode
+
+
+## Contributing
+~~I'm trying to keep listpager a single-file, small project, preferably under
+500 lines of code.~~ I've given up on the idea that this can be functional,
+correct, and maintainable in a single file that can be copied to a bin
+directory. If you use listpager and know Ruby, please dig in and PR at its
+github: https://github.com/mieko/listpager
+
+
+## License
+listpager is released under the MIT license.  Check out LICENSE.txt
+
+
+## Authors
+listpager was written by Mike A. Owens at meter.md.  mike@meter.md
+
+[1]: https://github.com/metermd/cult "Cult"

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "listpager"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/listpager

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+require 'listpager/client_terminal'
+
+[$stdin, $stdout].each do |io|
+  io.sync = true
+  io.reopen('/dev/null') if io.tty?
+end
+
+begin
+  Listpager::ClientTerminal.new.run
+rescue Interrupt
+  $stdout.puts "interrupt"
+  $stdout.flush
+rescue SystemCallError => e
+  $stderr.puts "#{$0}: #{e.message}"
+  exit 1
+end

data/lib/listpager/client_terminal.rb

@@ -0,0 +1,182 @@
+require 'ncurses'
+require 'shellwords'
+require 'optparse'
+require 'io/console'
+
+require 'listpager/color'
+require 'listpager/list'
+
+module Listpager
+  class ClientTerminal
+    attr_reader :tty
+    attr_reader :self_pipe
+    attr_reader :list
+    attr_reader :mode
+
+    def initialize
+      @tty = File.open('/dev/tty', 'r+')
+      @self_pipe = IO.pipe
+
+      [@tty, *self_pipe].each do |io|
+        io.sync = true
+      end
+
+      initialize_curses
+
+      @list = List.new(Ncurses.stdscr)
+      @mode = :append
+      @buffer = ''
+    end
+
+    def initialize_curses
+      screen = Ncurses.newterm(nil, @tty, @tty)
+      Ncurses.set_term(screen)
+      Ncurses.start_color
+      Color.init
+      Ncurses.use_default_colors
+      Ncurses.cbreak
+      Ncurses.stdscr.scrollok(false)
+      Ncurses.stdscr.keypad(true)
+      Ncurses.curs_set(0)
+      Ncurses.noecho
+      Ncurses.timeout(0)
+    end
+
+    def deinitialize
+      Ncurses.echo
+      Ncurses.nocbreak
+      Ncurses.nl
+      Ncurses.endwin
+      @tty.close
+    end
+
+    def append_mode?
+      @mode == :append
+    end
+
+    def process_command(line)
+      if append_mode?
+        case line
+        when '\%%'
+          list.values.push('%%')
+          list.dirty!
+        when '%%'
+          @mode = :command
+        else
+          list.values.push(line)
+          list.dirty!
+        end
+      else
+        cmd, *args = Shellwords.split(line)
+        begin
+          case cmd
+            when '%%', 'append-mode'
+              @mode = :append
+            when 'get-selected'
+              list.selection_changed
+            when 'select'
+              list.selected = args.fetch(0).to_i
+            when 'get-item'
+              puts ["item", args.fetch(0), list.values[args.fetch(0).to_i]].join ' '
+            when 'quit'
+              raise Interrupt
+          end
+        rescue IndexError => e
+          puts "error bad-command #{line}"
+        end
+      end
+    end
+
+    def consume_stdin(handles, fd)
+      loop do
+        begin
+          @buffer << fd.read_nonblock(512)
+        rescue EOFError
+          handles.delete(fd)
+          break
+        rescue IO::WaitReadable
+          break
+        end
+      end
+
+      unless @buffer.empty?
+        used = 0
+        StringIO.new(@buffer).each_line do |line|
+          if line[-1] == "\n"
+            process_command(line.chomp)
+            used += line.size
+          else
+            break
+          end
+        end
+        @buffer = @buffer[used...-1]
+      end
+    end
+
+    def consume_tty(handles, fd)
+      while (ch = Ncurses.getch) != -1
+        list.key_input(ch)
+      end
+    end
+
+    # We get a character from self_pipe here telling us the window
+    # has resized.
+    def consume_self_pipe(handles, fd)
+      code = fd.read(1)
+      case code
+        when 'R'
+          new_size = IO.console.winsize
+          Ncurses.resizeterm(*new_size)
+          Ncurses.stdscr.clear
+          list.dirty!
+          list.render
+          Ncurses.refresh
+      end
+    end
+
+    def dispatch_fd(handles, fd)
+      case fd
+        when $stdin
+          consume_stdin(@handles, fd)
+        when tty
+          consume_tty(@handles, fd)
+        when self_pipe[0]
+          consume_self_pipe(@handles, fd)
+      end
+    end
+
+    def process_events
+      @handles ||= [$stdin, tty, self_pipe[0]]
+
+      return if @handles.empty?
+
+      res = IO.select(@handles)
+      if res && (readers = res[0])
+        readers.each do |fd|
+          dispatch_fd(@handles, fd)
+        end
+      end
+    end
+
+    def run
+      trap 'WINCH' do
+        self_pipe[1].tap do |fd|
+          fd.write 'R'
+          fd.flush
+        end
+      end
+
+      begin
+        loop do
+          process_events
+          if list.render
+            Ncurses.redrawwin(list.window)
+            Ncurses.refresh
+          end
+        end
+      ensure
+        deinitialize
+      end
+    end
+  end
+end

data/lib/listpager/color.rb

@@ -0,0 +1,33 @@
+require 'ncurses'
+
+module Listpager
+  class Color
+    VALUES = {
+      list_default: 0,
+      list_selected: 1,
+      scroll_track: 2,
+      scroll_thumb: 3,
+      scroll_arrow: 4,
+    }.freeze
+
+    def self.curses_lookup(c)
+      Ncurses.const_get(c)
+    end
+
+    def self.init_color(c, fg, bg)
+      fail "Invalid color: #{c.inspect}" if VALUES[c].nil?
+      Ncurses.init_pair(VALUES[c], curses_lookup(fg), curses_lookup(bg))
+    end
+
+    def self.init
+      init_color(:list_selected, :COLOR_BLACK, :COLOR_WHITE)
+      init_color(:scroll_track, :COLOR_BLACK, :COLOR_BLACK)
+      init_color(:scroll_thumb, :COLOR_WHITE, :COLOR_WHITE)
+      init_color(:scroll_arrow, :COLOR_WHITE, :COLOR_BLACK)
+    end
+
+    def self.[](name)
+      VALUES[name] or fail "invalid color name: #{name.inspect}"
+    end
+  end
+end

data/lib/listpager/list.rb

@@ -0,0 +1,150 @@
+require 'ncurses'
+
+require 'listpager/color'
+require 'listpager/scrollbar'
+
+module Listpager
+  class List
+    INDICATOR    = ' ➤ '
+    NO_INDICATOR = '   '
+
+    # U+2003 "EM SPACE".  Ncurses' range-combining "optimizations" fuck up normal
+    # and non-breaking spaces.  For display, this is fine.  For copying, you'd
+    # have a scrollbar in the way anyway.  I fear newer releases of ncurses will
+    # get smarter and also consider this "blank" for optimizations.
+    BLANK_SPACE  = ' '
+
+    def on_select_change
+      puts "select #{selected} #{values[selected]}"
+    end
+
+    def on_key_press(k)
+      puts "keypress #{key_name(k)} #{selected} #{values[selected]}"
+    end
+
+    attr_reader :window
+    attr_accessor :values
+    attr_reader :selected
+    attr_reader :offset
+    attr_reader :scrollbar
+
+    def initialize(window)
+      @window = window
+      @values = []
+      @selected = 0
+      @offset = 0
+      @dirty = true
+      @scrollbar = Scrollbar.new(self)
+    end
+
+    def dirty!(value = true)
+      @dirty = value
+    end
+
+    def dirty?
+      @dirty
+    end
+
+    def offset=(v)
+      dirty! if v != @offset
+      @offset = v
+    end
+
+    attr_reader :selected
+    def selected=(v)
+      maxx, maxy = getmaxxy
+
+      v = [0, v, values.size - 1].sort[1]
+      self.offset = [v - maxy + 1, offset, v].sort[1]
+
+      if v != @selected
+        dirty!
+        on_select_change
+      end
+
+      return (@selected = v)
+    end
+
+    def key_name(v)
+      @m ||= {
+        27  => 'esc',
+        10  => 'enter',
+        260 => 'left',
+        261 => 'right',
+        127 => 'backspace',
+        330 => 'delete',
+        ' ' => 'space',
+      }
+      @m[v] || (v < 255 && v.chr.match(/[[:print:]]/) ? v.chr : "\##{v}")
+    end
+
+    def key_input(value)
+      maxx, maxy = getmaxxy
+
+      case value
+        when Ncurses::KEY_UP
+          self.selected -= 1
+        when Ncurses::KEY_DOWN
+          self.selected += 1
+        when Ncurses::KEY_PPAGE
+          self.selected -= maxy - 1
+        when Ncurses::KEY_NPAGE
+          self.selected += maxy - 1
+        else
+          on_key_press(value)
+      end
+    end
+
+    def dirty!(v = true)
+      @dirty = v
+    end
+
+    def normalize(s)
+      s.gsub(/[^[:print:]]/, '')
+    end
+
+    def getmaxxy
+      maxx, maxy = [], []
+      window.getmaxyx(maxy, maxx)
+      [maxx[0], maxy[0]]
+    end
+
+    def render
+      return false if ! dirty?
+
+      maxx, maxy = getmaxxy
+
+      (0...maxy).each do |i|
+        window.color_set(Color[:list_default], nil)
+
+        list_index = offset + i
+        window.move(i, 0)
+        indicator = nil
+
+        fixed_len = maxx - scrollbar.width
+
+        if list_index == selected
+          window.color_set(Color[:list_selected], nil)
+          indicator = INDICATOR
+        else
+          indicator = NO_INDICATOR
+        end
+
+        string = values[list_index] || ''
+        string = normalize(string)
+        string = indicator + string
+
+        if string.size < fixed_len
+          string += (BLANK_SPACE * (fixed_len - string.size))
+        elsif string.size > fixed_len
+          string = string[0...fixed_len]
+        end
+        window.addstr(string)
+      end
+
+      scrollbar.render
+      dirty!(false)
+      return true
+    end
+  end
+end

data/lib/listpager/scrollbar.rb

@@ -0,0 +1,107 @@
+require 'listpager/color'
+
+module Listpager
+  class Scrollbar
+    UP_ARROW   = '▴'
+    DOWN_ARROW = '▾'
+
+    attr_reader :list
+
+    def initialize(list)
+      @list = list
+      @memo_keys = nil
+      @memo_val = nil
+    end
+
+    def width
+      1
+    end
+
+    def scroll_thumb_range
+      maxx, maxy = getmaxxy
+
+      # We memoize these based on the inputs that effect the output
+      memo_keys = [list.values.size, list.offset, maxy]
+      return @memo_val if @memo_keys == memo_keys
+
+      # Ref: http://csdgn.org/inform/scrollbar-mechanics
+      #  using original camelCasedVariableNames for clarity with the source.
+      contentSize = list.values.size.to_f
+      windowSize = maxy.to_f
+      trackSize = windowSize - 2
+      windowContentRatio = windowSize / contentSize
+      gripSize = trackSize * windowContentRatio
+
+      minimalGripSize = 1.0
+      if gripSize < minimalGripSize
+        gripSize = minimalGripSize
+      end
+
+      windowScrollAreaSize = contentSize - windowSize
+      windowPosition = list.offset.to_f
+      windowPositionRatio = windowPosition / windowScrollAreaSize
+
+      trackScrollAreaSize = trackSize - gripSize
+      gripPositionOnTrack = trackScrollAreaSize * windowPositionRatio
+
+      st = 1 + gripPositionOnTrack.floor.to_i
+      e = (st + gripSize.ceil).to_i
+
+      st = 1 if st < 1
+      e = maxy - 1 if e > maxy - 1
+
+      @memo_keys = memo_keys
+      return (@memo_val = st ... e)
+    end
+
+    def window
+      list.window
+    end
+
+    def getmaxxy
+      list.getmaxxy
+    end
+
+    def render
+      maxx, maxy = getmaxxy
+      x = maxx - self.width
+
+      # If we don't need a scroll bar...
+      return if list.values.size <= maxy
+
+      # Both arrows
+      window.color_set(Color[:scroll_arrow], nil)
+      window.move(0, x)
+      window.addstr(UP_ARROW)
+      window.move(maxy - 1, x)
+      window.addstr(DOWN_ARROW)
+
+      # The full track
+      window.color_set(Color[:scroll_track], nil)
+      (1 ... maxy - 1).each do |y|
+        window.move(y, x)
+        window.addstr(' ')
+      end
+
+      # Scroll thumb on top of it
+      window.color_set(Color[:scroll_thumb], nil)
+      scroll_thumb_range.each do |y|
+        window.move(y, x)
+        window.addstr(' ')
+      end
+
+      # Set our drawing cursor at the origin
+      window.color_set(Color[:list_default], nil)
+      window.move(0, 0)
+    end
+
+    def can_scroll_up?
+      list.offset > 0
+    end
+
+    def can_scroll_down?
+      _, maxy = getmaxxy
+      list.values.size > list.offset + maxy
+    end
+  end
+end

data/lib/listpager/version.rb

@@ -0,0 +1,3 @@
+module Listpager
+  VERSION = "1.0"
+end

data/lib/listpager.rb

@@ -0,0 +1,5 @@
+require "listpager/version"
+
+module Listpager
+  # Your code goes here...
+end

data/listpager.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'listpager/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "listpager"
+  spec.version       = Listpager::VERSION
+  spec.authors       = ["Mike Owens"]
+  spec.email         = ["mike@meter.md"]
+
+  spec.summary       = "Interactive terminal pager for lists"
+  spec.description   = "Ncurses list pager, controllable via stdin and stdout"
+  spec.homepage      = "https://github.com/mieko/listpager"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org/"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "ncurses-ruby", "~> 1.2.4"
+  spec.add_development_dependency "bundler", "~> 1.12"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: listpager
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Mike Owens
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-08-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ncurses-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.4
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: Ncurses list pager, controllable via stdin and stdout
+email:
+- mike@meter.md
+executables:
+- listpager
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- doc/screenshot.png
+- exe/listpager
+- lib/listpager.rb
+- lib/listpager/client_terminal.rb
+- lib/listpager/color.rb
+- lib/listpager/list.rb
+- lib/listpager/scrollbar.rb
+- lib/listpager/version.rb
+- listpager.gemspec
+homepage: https://github.com/mieko/listpager
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org/
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Interactive terminal pager for lists
+test_files: []