tty 0.0.9 → 0.0.10

data/.rspec

@@ -1,2 +1,3 @@
 --color
--f s
+--format progress
+--order random

data/.travis.yml

@@ -2,18 +2,15 @@ language: ruby
 before_install:
   - gem install bundler
 rvm:
-  - 1.8.7
-  - 1.9.2
   - 1.9.3
+  - 2.0.0
   - ruby-head
-  - jruby-18mode
   - jruby-19mode
-  - rbx-18mode
   - rbx-19mode
-  - ree
   - jruby-head
+  - rbx-head
 matrix:
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head
-    - rvm: rbx-19mode
+    - rvm: rbx-head

data/README.md

@@ -2,10 +2,12 @@
 [![Gem Version](https://badge.fury.io/rb/tty.png)][gem]
 [![Build Status](https://secure.travis-ci.org/peter-murach/tty.png?branch=master)][travis]
 [![Code Climate](https://codeclimate.com/github/peter-murach/tty.png)][codeclimate]
+[![Coverage Status](https://coveralls.io/repos/peter-murach/tty/badge.png?branch=master)][coveralls]
 
 [gem]: http://badge.fury.io/rb/tty
 [travis]: http://travis-ci.org/peter-murach/tty
 [codeclimate]: https://codeclimate.com/github/peter-murach/tty
+[coveralls]: https://coveralls.io/r/peter-murach/tty
 
 Toolbox for developing CLI clients in Ruby. This library provides a fluid interface for working with terminals.
 
@@ -13,9 +15,9 @@ Toolbox for developing CLI clients in Ruby. This library provides a fluid interf
 
 Jump-start development of your command line app:
 
-* Table rendering with an easy-to-use API  [status: In Progress]
-* Terminal output colorization.            [status: ✔ ]
-* Terminal & System detection utilities.   [status: In Progress]
+* Table rendering with an easy-to-use API. [status: In Progress]
+* Terminal output colorization, paging.    [status: ✔ ]
+* System & command detection utilities.    [status: In Progress]
 * Text manipulation(wrapping/truncation)   [status: In Progress]
 * Shell user interface.                    [status: In Progress]
 * File diffs.                              [status: TODO]
@@ -47,75 +49,112 @@ Or install it yourself as:
 To instantiate table pass 2-dimensional array:
 
 ```ruby
-  table = TTY::Table[['a1', 'a2'], ['b1', 'b2']]
-  table = TTY::Table.new [['a1', 'a2'], ['b1', 'b2']]
-  table = TTY::Table.new rows: [['a1', 'a2'], ['b1', 'b2']]
-  table = TTY::Table.new ['h1', 'h2'], [['a1', 'a2'], ['b1', 'b2']]
-  table = TTY::Table.new header: ['h1', 'h2'], rows: [['a1', 'a2'], ['b1', 'b2']]
+table = TTY::Table[['a1', 'a2'], ['b1', 'b2']]
+table = TTY::Table.new [['a1', 'a2'], ['b1', 'b2']]
+table = TTY::Table.new rows: [['a1', 'a2'], ['b1', 'b2']]
+table = TTY::Table.new ['h1', 'h2'], [['a1', 'a2'], ['b1', 'b2']]
+table = TTY::Table.new header: ['h1', 'h2'], rows: [['a1', 'a2'], ['b1', 'b2']]
 ```
 
 or cross header with rows inside a hash like so
 
 ```ruby
-  table = TTY::Table.new [{'h1' => ['a1', 'a2'], 'h2' => ['b1', 'b2']}]
+table = TTY::Table.new [{'h1' => ['a1', 'a2'], 'h2' => ['b1', 'b2']}]
 ```
 
-Apart from `rows` and `header`, you can provide other customization options such as
+Table behaves like an Array so `<<`, `each` and familiar methods can be used
 
 ```ruby
-  column_widths   # array of maximum columns widths
-  column_aligns   # array of cell alignments out of :left, :center and :right
-  renderer        # enforce display type out of :basic, :color, :unicode, :ascii
-  orientation     # either :horizontal or :vertical
-  border          # hash of border properties out of :characters, :style, :separator keys
-  width           # constrain the table total width, otherwise dynamically calculated based on content and terminal size
+table << ['a1', 'a2', 'a3']
+table << ['b1', 'b2', 'b3']
+table << ['a1', 'a2'] << ['b1', 'b2']  # chain rows assignment
+
+table.each { |row| ... }  # iterate over rows
+table.each_with_index     # iterate over each element with row and column index
+table[i, j]               # return element at row(i) and column(j)
+table.row(i) { ... }      # return array for row(i)
+table.column(j) { ... }   # return array for column(j)
+table.column(name)        # return array for column(name), name of header
+table.row_size            # return row size
+table.column_size         # return column size
+table.size                # return an array of [row_size, column_size]
+table.border              # specify border properties
 ```
 
-Table behaves like an Array so `<<`, `each` and familiar methods can be used
+or pass your rows in a block
 
 ```ruby
-  table << ['a1', 'a2', 'a3']
-  table << ['b1', 'b2', 'b3']
-  table << ['a1', 'a2'] << ['b1', 'b2']  # chain rows assignment
-
-  table.each { |row| ... }  # iterate over rows
-  table.each_with_index     # iterate over each element with row and column index
-  table[i, j]               # return element at row(i) and column(j)
-  table.row(i) { ... }      # return array for row(i)
-  table.column(j) { ... }   # return array for column(j)
-  table.column(name)        # return array for column(name), name of header
-  table.row_size            # return row size
-  table.column_size         # return column size
-  table.size                # return an array of [row_size, column_size]
-  table.border              # specify border properties
+table = TTY::Table.new  do |t|
+  t << ['a1', 'a2', 'a3']
+  t << ['b1', 'b2', 'b3']
+end
 ```
 
-or pass your rows in a block
+#### Rendering
+
+Once you have an instance of `TTY::Table` you can print it out to the stdout by doing:
 
 ```ruby
-  table = TTY::Table.new  do |t|
-    t << ['a1', 'a2', 'a3']
-    t << ['b1', 'b2', 'b3']
-  end
+table.to_s
+
+a1  a2  a3
+b1  b2  b3
 ```
 
-And then to print do
+This will use so called `basic` renderer with default options.
+
+However, you can include other customization options such as
 
 ```ruby
-  table.to_s
+column_widths  # array of maximum columns widths
+column_aligns  # array of cell alignments out of :left, :center and :right, default :left
+width          # constrain the table total width, otherwise dynamically calculated based on content and terminal size
+renderer       # enforce display type out of :basic, :color, :unicode, :ascii
+border         # hash of border properties out of :characters, :style, :separator keys
+border_class   # a type of border to use
+multiline      # if true will wrap text at new line or column width, when false will escape special characters
+filter         # a proc object that is applied to every field in a row
+orientation    # either :horizontal or :vertical
+```
+
+#### Multiline
+
+Renderer options may include `multiline` parameter. The `true` value will cause the table fields wrap at their natural line breaks or in case when the column widths are set the content will wrap.
 
-  a1  a2  a3
-  b1  b2  b3
+```
+table = TTY::Table.new [ ["First", '1'], ["Multi\nLine\nContent", '2'], ["Third", '3']]
+table.render :ascii, multiline: true
+# =>
+  +-------+-+
+  |First  |1|
+  |Multi  |2|
+  |Line   | |
+  |Content| |
+  |Third  |3|
+  +-------+-+
+```
+
+When the `false` option is specified all the special characters will be escaped and if the column widths are set the content will be truncated like so
+
+```ruby
+table = TTY::Table.new [ ["First", '1'], ["Multiline\nContent", '2'], ["Third", '3']]
+table.render :ascii, multiline: false
+# =>
+  +------------------+-+
+  |First             |1|
+  |Multiline\nContent|2|
+  |Third             |3|
+  +------------------+-+
 ```
 
 #### Border
 
 To print border around data table you need to specify `renderer` type out of `basic`, `ascii`, `unicode`. By default `basic` is used. For instance, to output unicode border:
 
-```
-  table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2'], renderer: 'unicode'
-  table.to_s
-
+```ruby
+table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
+table.render :unicode
+# =>
   ┌───────┬───────┐
   │header1│header2│
   ├───────┼───────┤
@@ -127,25 +166,24 @@ To print border around data table you need to specify `renderer` type out of `ba
 You can also create your own custom border by subclassing `TTY::Table::Border` and implementing the `def_border` method using internal DSL methods like so:
 
 ```ruby
-  class MyBorder < TTY::Table::Border
-    def_border do
-      left         '$'
-      center       '$'
-      right        '$'
-      bottom       ' '
-      bottom_mid   '*'
-      bottom_left  '*'
-      bottom_right '*'
-    end
+class MyBorder < TTY::Table::Border
+  def_border do
+    left         '$'
+    center       '$'
+    right        '$'
+    bottom       ' '
+    bottom_mid   '*'
+    bottom_left  '*'
+    bottom_right '*'
   end
+end
 ```
 
-Next pass the border class to your instantiated table
+Next pass the border class to your table instance `render_with` method
 
 ```ruby
-  table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
-  table.renders_with MyBorder
-  table.to_s
+table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
+table.render_with MyBorder
 
   $header1$header2$
   $a1     $a2     $
@@ -155,13 +193,13 @@ Next pass the border class to your instantiated table
 Finally, if you want to introduce slight modifications to the predefined border types, you can use table `border` helper like so
 
 ```ruby
-  table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
-  table.border do
+table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
+table.render do |renderer|
+  renderer.border do
     mid          '='
     mid_mid      ' '
   end
-
-  table.to_s
+end
 
   header1 header2
   ======= =======
@@ -172,9 +210,10 @@ Finally, if you want to introduce slight modifications to the predefined border
 In addition to specifying border characters you can force table to render separator line on each row like:
 
 ```ruby
-  table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']]
-  table.border.separator = :each_row
-  table.to_s
+table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']]
+table.render do |renderer|
+  renderer.border.separator = :each_row
+end
 
   +-------+-------+
   |header1|header2|
@@ -188,7 +227,9 @@ In addition to specifying border characters you can force table to render separa
 Also to change the display color of your border do:
 
 ```ruby
-  table.border.style = :red
+table.render do |renderer|
+  renderer.border.style = :red
+end
 ```
 
 #### Alignment
@@ -196,24 +237,25 @@ Also to change the display color of your border do:
 All columns are left aligned by default. You can enforce per column alignment by passing `column_aligns` option like so
 
 ```ruby
-  rows = [['a1', 'a2'], ['b1', 'b2']
-  table = TTY::Table.new rows: rows, column_aligns: [:center, :right]
+rows = [['a1', 'a2'], ['b1', 'b2']
+table = TTY::Table.new rows: rows
+table.render column_aligns: [:center, :right]
 ```
 
 To align a single column do
 
 ```ruby
-  table.align_column(1, :right)
+table.align_column(1, :right)
 ```
 
 If you require a more granular alignment you can align individual fields in a row by passing `align` option
 
 ```ruby
-  table = TTY::Table.new do |t|
-    t << ['a1', 'a2', 'a3']
-    t << ['b1', {:value => 'b2', :align => :right}, 'b3']
-    t << ['c1', 'c2', {:value => 'c3', :align => :center}]
-  end
+table = TTY::Table.new do |t|
+  t << ['a1', 'a2', 'a3']
+  t << ['b1', {:value => 'b2', :align => :right}, 'b3']
+  t << ['c1', 'c2', {:value => 'c3', :align => :center}]
+end
 ```
 
 #### Style
@@ -221,7 +263,8 @@ If you require a more granular alignment you can align individual fields in a ro
 To format individual fields/cells do
 
 ```ruby
-  table = TTY::Table.new rows: rows, width: 40
+table = TTY::Table.new rows: rows
+table.render width: 40
 ```
 
 #### Filter
@@ -229,13 +272,16 @@ To format individual fields/cells do
 You can define filters that will modify individual table fields value before they are rendered. A filter can be a callable such as proc. Here's an example that formats
 
 ```ruby
-  table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
-  table.filter = Proc.new do |val, row_index, col_index|
+table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
+table.render do |renderer|
+  renderer.filter = Proc.new do |val, row_index, col_index|
     if col_index == 1 and !(row_index == 0)
       val.capitalize
+    else
+      val
     end
   end
-  table.to_s
+end
 
   +-------+-------+
   |header1|header2|
@@ -244,12 +290,17 @@ You can define filters that will modify individual table fields value before the
   +-------+-------+
   |b1     |B2     |
   +-------+-------+
-
 ```
 
 To add background color to even fields do
 
 ```ruby
+table.render do |renderer|
+  renderer.filter = Proc.new do |val, row_index, col_index|
+    if col_index % 2 == 1
+      TTY.color.set val, :red, :on_green
+  end
+end
 ```
 
 ### Terminal
@@ -257,19 +308,41 @@ To add background color to even fields do
 To read general terminal properties you can use on of the helpers
 
 ```ruby
-  term = TTY::Terminal.new
-  term.width              # => 140
-  term.height             # =>  60
-  term.color?             # => true or false
-  term.echo(false) { }    # switch off echo for the block
+term = TTY::Terminal.new
+term.width              # => 140
+term.height             # =>  60
+term.color?             # => true or false
+term.echo(false) { }    # switch off echo for the block
+term.page               # page terminal output, on non unix systems falls back to ruby implementation
 ```
 
 To colorize your output do
 
 ```ruby
-  term.color.set 'text...', :bold, :red, :on_green    # => red bold text on green background
-  term.color.remove 'text...'       # strips off ansi escape sequences
-  term.color.code :red              # ansi escape code for the supplied color
+term.color.set 'text...', :bold, :red, :on_green    # => red bold text on green background
+term.color.remove 'text...'       # strips off ansi escape sequences
+term.color.code :red              # ansi escape code for the supplied color
+```
+
+Available colors are:
+
+```ruby
+black
+red
+green
+yellow
+blue
+magenta
+cyan
+white
+```
+
+To supply background color simply prefix it with `on_`. For example a green background would be `on_green`.
+
+To page your output do
+
+```ruby
+term.page 'long text...'
 ```
 
 ### Shell
@@ -279,88 +352,113 @@ Main responsibility is to interact with the prompt and provide convenience metho
 Available methods are
 
 ```ruby
-  shell = TTY::Shell.new
-  shell.ask          # print question
-  shell.read         # read from stdin
-  shell.say          # print message to stdout
-  shell.confirm      # print message(s) in green
-  shell.warn         # print message(s) in yellow
-  shell.error        # print message(s) in red
-  shell.print_table  # print table to stdout
+shell = TTY::Shell.new
+shell.ask          # print question
+shell.read         # read from stdin
+shell.say          # print message to stdout
+shell.confirm      # print message(s) in green
+shell.warn         # print message(s) in yellow
+shell.error        # print message(s) in red
+shell.suggest      # print suggestion message based on possible matches
+shell.print_table  # print table to stdout
 ```
 
 In order to ask question and parse answers:
 
 ```ruby
-  shell  = TTY::Shell.new
-  answer = shell.ask("What is your name?").read_string
+shell  = TTY::Shell.new
+answer = shell.ask("What is your name?").read_string
 ```
 
 The library provides small DSL to help with parsing and asking precise questions
 
 ```ruby
-  argument    # :required or :optional
-  character   # turn character based input, otherwise line (default: false)
-  clean       # reset question
-  default     # default value used if none is provided
-  echo        # turn echo on and off (default: true)
-  mask        # mask characters i.e '****' (default: false)
-  modify      # apply answer modification :upcase, :downcase, :trim, :chomp etc..
-  range       # specify range '0-9', '0..9', '0...9' or negative '-1..-9'
-  validate    # regex against which stdin input is checked
-  valid       # a list of expected valid options
+argument    # :required or :optional
+character   # turn character based input, otherwise line (default: false)
+clean       # reset question
+default     # default value used if none is provided
+echo        # turn echo on and off (default: true)
+mask        # mask characters i.e '****' (default: false)
+modify      # apply answer modification :upcase, :downcase, :trim, :chomp etc..
+range       # specify range '0-9', '0..9', '0...9' or negative '-1..-9'
+validate    # regex against which stdin input is checked
+valid       # a list of expected valid options
 ```
 
 You can chain question methods or configure them inside a block
 
 ```ruby
-  shell.ask("What is your name?").argument(:required).default('Piotr').validate(/\w+\s\w+/).read_string
-
-  shell.ask "What is your name?" do
-    argument :required
-    default  'Piotr'
-    validate /\w+\s\w+/
-    valid    ['Piotr', 'Piotrek']
-    modify   :capitalize
-  end.read_string
+shell.ask("What is your name?").argument(:required).default('Piotr').validate(/\w+\s\w+/).read_string
+
+shell.ask "What is your name?" do
+  argument :required
+  default  'Piotr'
+  validate /\w+\s\w+/
+  valid    ['Piotr', 'Piotrek']
+  modify   :capitalize
+end.read_string
 ```
 
 Reading answers and converting them into required types can be done with custom readers
 
 ```ruby
-  read_bool       # return true or false for strings such as "Yes", "No"
-  read_date       # return date type
-  read_datetime   # return datetime type
-  read_email      # validate answer against email regex
-  read_float      # return decimal or error if cannot convert
-  read_int        # return integer or error if cannot convert
-  read_multiple   # return multiple line string
-  read_password   # return string with echo turned off
-  read_range      # return range type
-  read_string     # return string
+read_bool       # return true or false for strings such as "Yes", "No"
+read_date       # return date type
+read_datetime   # return datetime type
+read_email      # validate answer against email regex
+read_float      # return decimal or error if cannot convert
+read_int        # return integer or error if cannot convert
+read_multiple   # return multiple line string
+read_password   # return string with echo turned off
+read_range      # return range type
+read_string     # return string
 ```
 
 For example, if we wanted to ask a user for a single digit in given range
 
 ```ruby
-  ask("Provide number in range: 0-9") do
-    range '0-9'
-    on_error :retry
-  end.read_int
+ask("Provide number in range: 0-9") do
+  range '0-9'
+  on_error :retry
+end.read_int
 ```
 
 on the other hand, if we are interested in range answer then
 
 ```ruby
-  ask("Provide range of numbers?").read_range
+ask("Provide range of numbers?").read_range
+```
+
+To suggest possible matches for the user input use `suggest` method like so
+
+```ruby
+shell.suggest('sta', ['stage', 'stash', 'commit', 'branch'])
+# =>
+  Did you mean one of these?
+          stage
+          stash
 ```
 
 ### System
 
 ```ruby
-  TTY::System.unix?       # => true
-  TTY::System.windows?    # => false
-  TTY::System.which(cmd)  # full path to executable if found, nil otherwise
+TTY::System.unix?        # check if unix platform
+TTY::System.windows?     # check if windows platform
+TTY::System.which(cmd)   # full path to executable if found, nil otherwise
+TTY::System.exists?(cmd) # check if command is available
+TTY::System.editor       # provides access to system editor
+```
+
+To set preferred editor you can either use shell environment variables such as `EDITOR` and `VISUAL` or set the command(s) manually like so
+
+```ruby
+TTY::System.editor.command('vim')
+```
+
+To open a file in your editor of choice do
+
+```ruby
+TTY::System.editor.open('file path...')
 ```
 
 ## Contributing

data/lib/tty/plugins/plugin.rb

@@ -0,0 +1,56 @@
+# -*- encoding: utf-8 -*-
+
+module TTY
+
+  # A class responsible for plugin loading
+  class Plugin
+
+    attr_reader :name
+
+    attr_reader :gem
+
+    attr_reader :gem_name
+
+    attr_accessor :enabled
+
+    # Initialize a Plugin
+    #
+    # @param [String] name
+    #   the plugin name
+    #
+    # @param [Gem::Specification] gem
+    #   the rubygems gem
+    #
+    # @api public
+    def initialize(name, gem)
+      @name     = name
+      @gem      = gem
+      @gem_name = "tty-#{name}"
+      @enabled  = false
+    end
+
+    # Check if this plugin has been enabled
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def enabled?
+      !!enabled
+    end
+
+    # Load the plugin (require the gem)
+    #
+    # @api public
+    def load!
+      begin
+        require gem_name unless enabled?
+      rescue LoadError => error
+        TTY.shell.error("Unable to load plugin #{gem_name}.")
+      rescue => error
+        TTY.shell.error("require '#{gem_name}' failed with #{error}")
+      end
+      self.enabled = true
+    end
+
+  end # Plugin
+end # TTY