hsume2-hirb 0.6.0.beta.1

data/lib/hirb/helpers/tree.rb

@@ -0,0 +1,181 @@
+# Base tree class which given an array of nodes produces different types of trees.
+# The types of trees currently are:
+# * basic:
+#    0
+#      1
+#        2
+#        3
+#      4
+# 
+# * directory:
+#    0
+#    |-- 1
+#    |   |-- 2
+#    |   `-- 3
+#    `-- 4
+# 
+# * number:
+#    1. 0
+#      1. 1
+#        1. 2
+#        2. 3
+#      2. 4 
+# 
+# Tree nodes can be given as an array of arrays or an array of hashes.
+# To render the above basic tree with an array of hashes:
+#   Hirb::Helpers::Tree.render([{:value=>0, :level=>0}, {:value=>1, :level=>1}, {:value=>2, :level=>2}, 
+#     {:value=>3, :level=>2}, {:value=>4, :level=>1}])
+# Note from the hash keys that :level refers to the depth of the tree while :value refers to the text displayed
+# for a node.
+#
+# To render the above basic tree with an array of arrays:
+#   Hirb::Helpers::Tree.render([[0,0], [1,1], [2,2], [2,3], [1,4]])
+# Note that the each array pair consists of the level and the value for the node.
+class Hirb::Helpers::Tree
+  class ParentlessNodeError < StandardError; end
+
+  class <<self
+    # Main method which renders a tree.
+    # ==== Options:
+    # [:type] Type of tree. Either :basic, :directory or :number. Default is :basic.
+    # [:validate] Boolean to validate tree. Checks to see if all nodes have parents. Raises ParentlessNodeError if
+    #             an invalid node is found. Default is false.
+    # [:indent] Number of spaces to indent between levels for basic + number trees. Default is 4.
+    # [:limit] Limits the level or depth of a tree that is displayed. Root node is level 0.
+    # [:description] Displays brief description about tree ie how many nodes it has.
+    # [:multi_line_nodes] Handles multi-lined nodes by indenting their newlines. Default is false.
+    #  Examples:
+    #     Hirb::Helpers::Tree.render([[0, 'root'], [1, 'child']], :type=>:directory)
+    def render(nodes, options={})
+      new(nodes, options).render
+    end
+  end
+
+  # :stopdoc:
+  attr_accessor :nodes
+  
+  def initialize(input_nodes, options={})
+    @options = options
+    @type = options[:type] || :basic
+    if input_nodes[0].is_a?(Array)
+      @nodes = input_nodes.map {|e| Node.new(:level=>e[0], :value=>e[1]) }
+    else
+      @nodes = input_nodes.map {|e| Node.new(e)}
+    end
+    @nodes.each_with_index {|e,i| e.merge!(:tree=>self, :index=>i)}
+    @nodes.each {|e| e[:value] = e[:value].to_s }
+    validate_nodes if options[:validate]
+    self
+  end
+
+  def render
+    body = render_tree
+    body += render_description if @options[:description]
+    body
+  end
+  
+  def render_description
+    "\n\n#{@nodes.length} #{@nodes.length == 1 ? 'node' : 'nodes'} in tree"
+  end
+
+  def render_tree
+    @indent = ' ' * (@options[:indent] || 4 )
+    @nodes = @nodes.select {|e| e[:level] <= @options[:limit] } if @options[:limit]
+    case @type.to_s
+    when 'directory' then render_directory
+    when 'number'    then render_number
+    else render_basic
+    end
+  end
+
+  def render_nodes
+    value_indent = @options[:multi_line_nodes] ? @indent : nil
+    @nodes.map {|e| yield(e) + e.value(value_indent) }.join("\n")
+  end
+
+  def render_directory
+    mark_last_nodes_per_level
+    render_nodes {|e|
+      value = ''
+      unless e.root?
+        value << e.render_parent_characters
+        value << (e[:last_node] ? "`-- " : "|-- ")
+      end
+      value
+    }
+  end
+  
+  def render_number
+    counter = {}
+    @nodes.each {|e|
+      parent_level_key = "#{(e.parent ||{})[:index]}.#{e[:level]}"
+      counter[parent_level_key] ||= 0
+      counter[parent_level_key] += 1
+      e[:pre_value] = "#{counter[parent_level_key]}. "
+    }
+    render_nodes {|e| @indent * e[:level] + e[:pre_value] }
+  end
+
+  def render_basic
+    render_nodes {|e| @indent * e[:level] }
+  end
+
+  def validate_nodes
+    @nodes.each do |e|
+      raise ParentlessNodeError if (e[:level] > e.previous[:level]) && (e[:level] - e.previous[:level]) > 1
+    end
+  end
+  
+  # walks tree accumulating last nodes per unique parent+level
+  def mark_last_nodes_per_level
+    @nodes.each {|e| e.delete(:last_node)}
+    last_node_hash = @nodes.inject({}) {|h,e|
+      h["#{(e.parent ||{})[:index]}.#{e[:level]}"] = e; h
+    }
+    last_node_hash.values.uniq.each {|e| e[:last_node] = true}
+  end
+  #:startdoc:
+  class Node < ::Hash #:nodoc:
+    class MissingLevelError < StandardError; end
+    class MissingValueError < StandardError; end
+    
+    def initialize(hash)
+      super
+      raise MissingLevelError unless hash.has_key?(:level)
+      raise MissingValueError unless hash.has_key?(:value)
+      replace(hash)
+    end
+
+    def value(indent=nil)
+      indent ? self[:value].gsub("\n", "\n#{indent * self[:level]}") : self[:value]
+    end
+
+    def parent
+      self[:tree].nodes.slice(0 .. self[:index]).reverse.detect {|e| e[:level] < self[:level]}
+    end
+
+    def next
+      self[:tree].nodes[self[:index] + 1]
+    end
+
+    def previous
+      self[:tree].nodes[self[:index] - 1]
+    end
+
+    def root?; self[:level] == 0; end
+
+    # refers to characters which connect parent nodes 
+    def render_parent_characters
+      parent_chars = []
+      get_parents_character(parent_chars)
+      parent_chars.reverse.map {|level| level + ' ' * 3 }.join('')
+    end
+
+    def get_parents_character(parent_chars)
+      if self.parent
+        parent_chars << (self.parent[:last_node] ? ' ' : '|') unless self.parent.root?
+        self.parent.get_parents_character(parent_chars)
+      end
+    end
+  end
+end

data/lib/hirb/helpers/unicode_table.rb

@@ -0,0 +1,15 @@
+# -*- encoding : utf-8 -*-
+class Hirb::Helpers::UnicodeTable < Hirb::Helpers::Table
+  CHARS = {
+    :top => {:left => '┌', :center => '┬', :right => '┐', :horizontal => '─',
+      :vertical => {:outside => '│', :inside => '│'} },
+    :middle => {:left => '├', :center => '┼', :right => '┤', :horizontal => '─'},
+    :bottom => {:left => '└', :center => '┴', :right => '┘', :horizontal => '─',
+      :vertical => {:outside => '│', :inside => '╎'} }
+  }
+
+  # Renders a unicode table
+  def self.render(rows, options={})
+    new(rows, options).render
+  end
+end

data/lib/hirb/helpers/vertical_table.rb

@@ -0,0 +1,37 @@
+class Hirb::Helpers::VerticalTable < Hirb::Helpers::Table
+
+  # Renders a vertical table using the same options as Hirb::Helpers::Table.render except for the ones below
+  # and :max_fields, :vertical and :max_width which aren't used.
+  # ==== Options:
+  # [:hide_empty] Boolean which hides empty values (nil or '') from being displayed. Default is false.
+  def self.render(rows, options={})
+    new(rows, {:escape_special_chars=>false, :resize=>false}.merge(options)).render
+  end
+
+  #:stopdoc:
+  def setup_field_lengths
+    @field_lengths = default_field_lengths
+  end
+
+  def render_header; []; end
+  def render_footer; []; end
+
+  def render_rows
+    i = 0
+    longest_header = Hirb::String.size @headers.values.sort_by {|e| Hirb::String.size(e) }.last
+    stars = "*" * [(longest_header + (longest_header / 2)), 3].max
+    @rows.map do |row|
+      row = "#{stars} #{i+1}. row #{stars}\n" +
+      @fields.map {|f|
+        if !@options[:hide_empty] || (@options[:hide_empty] && !row[f].empty?)
+          "#{Hirb::String.rjust(@headers[f], longest_header)}: #{row[f]}"
+        else
+          nil
+        end
+      }.compact.join("\n")
+      i+= 1
+      row
+    end
+  end
+  #:startdoc:
+end

data/lib/hirb/helpers.rb

@@ -0,0 +1,18 @@
+module Hirb
+  module Helpers #:nodoc:
+    @helper_classes ||= {}
+    def self.helper_class(klass)
+      @helper_classes[klass.to_s] ||= begin
+        if (helper_class = constants.find {|e| e.to_s == Util.camelize(klass.to_s)})
+          klass = "Hirb::Helpers::#{helper_class}"
+        end
+        Util.any_const_get(klass)
+      end
+    end
+  end
+end
+
+%w{table object_table auto_table tree parent_child_tree vertical_table
+  unicode_table tab_table}.each do |e|
+  require "hirb/helpers/#{e}"
+end

data/lib/hirb/import_object.rb

@@ -0,0 +1,10 @@
+module Hirb
+  module ObjectMethods
+    # Takes same options as Hirb::View.render_output.
+    def view(*args)
+      Hirb::Console.render_output(*(args.unshift(self)))
+    end
+  end
+end
+
+Object.send :include, Hirb::ObjectMethods

data/lib/hirb/menu.rb

@@ -0,0 +1,238 @@
+module Hirb
+  # This class provides a menu using Hirb's table helpers by default to display choices.
+  # Menu choices (syntax at Hirb::Util.choose_from_array) refer to rows. However, when in
+  # two_d mode, choices refer to specific cells by appending a ':field' to a choice.
+  # A field name can be an abbreviated. Menus can also have an action mode, which turns the
+  # menu prompt into a commandline that executes the choices as arguments and uses methods as
+  # actions/commands.
+  class Menu
+    class Error < StandardError; end
+
+    # Detects valid choices and optional field/column
+    CHOSEN_REGEXP = /^(\d([^:]+)?)(?::)?(\S+)?/
+    CHOSEN_ARG = '%s'
+    ALL_ARG = '*'
+    DIRECTIONS = "Specify individual choices (4,7), range of choices (1-3) or all choices (*)."
+
+
+    # This method will return an array unless it's exited by simply pressing return, which returns nil.
+    # If given a block, the block will yield if and with any menu items are chosen.
+    # All options except for the ones below are passed to render the menu.
+    #
+    # ==== Options:
+    # [*:helper_class*]  Helper class to render menu. Helper class is expected to implement numbering given a :number option.
+    #                    To use a very basic menu, set this to false. Defaults to Hirb::Helpers::AutoTable.
+    # [*:prompt*]  String for menu prompt. Defaults to "Choose: ".
+    # [*:ask*] Always ask for input, even if there is only one choice. Default is true.
+    # [*:directions*] Display directions before prompt. Default is true.
+    # [*:readline*] Use readline to get user input if available. Input strings are added to readline history. Default is false.
+    # [*:two_d*] Turn menu into a 2 dimensional (2D) menu by allowing user to pick values from table cells. Default is false.
+    # [*:default_field*] Default field for a 2D menu. Defaults to first field in a table.
+    # [*:action*] Turn menu into an action menu by letting user pass menu choices as an argument to a method/command.
+    #             A menu choice's place amongst other arguments is preserved. Default is false.
+    # [*:multi_action*] Execute action menu multiple times iterating over the menu choices. Default is false.
+    # [*:action_object*] Object that takes method/command calls. Default is main.
+    # [*:command*] Default method/command to call when no command given.
+    # [*:reopen*] Reopens $stdin with given file or with /dev/tty when set to true. Use when
+    #             $stdin is already reading in piped data.
+    # Examples:
+    #     >> extend Hirb::Console
+    #     => self
+    #     >> menu [1,2,3], :prompt=> "So many choices, so little time: "
+    #     >> menu [{:a=>1, :b=>2}, {:a=>3, :b=>4}], :fields=>[:a,b], :two_d=>true)
+    def self.render(output, options={}, &block)
+      new(options).render(output, &block)
+    rescue Error=>e
+      $stderr.puts "Error: #{e.message}"
+    end
+
+    #:stopdoc:
+    def initialize(options={})
+      @options = {:helper_class=>Hirb::Helpers::AutoTable, :prompt=>"Choose: ", :ask=>true,
+        :directions=>true}.merge options
+      @options[:reopen] = '/dev/tty' if @options[:reopen] == true
+    end
+
+    def render(output, &block)
+      @output = Array(output)
+      return [] if @output.size.zero?
+      chosen = choose_from_menu
+      block.call(chosen) if block && chosen.size > 0
+      @options[:action] ? execute_action(chosen) : chosen
+    end
+
+    def get_input
+      prompt = pre_prompt + @options[:prompt]
+      prompt = DIRECTIONS+"\n"+prompt if @options[:directions]
+      $stdin.reopen @options[:reopen] if @options[:reopen]
+
+      if @options[:readline] && readline_loads?
+        get_readline_input(prompt)
+      else
+        print prompt
+        $stdin.gets.chomp.strip
+      end
+    end
+
+    def get_readline_input(prompt)
+      input = Readline.readline prompt
+      Readline::HISTORY << input
+      input
+    end
+
+    def pre_prompt
+      prompt = ''
+      prompt << "Default field: #{default_field}\n" if @options[:two_d] && default_field
+      prompt << "Default command: #{@options[:command]}\n" if @options[:action] && @options[:command]
+      prompt
+    end
+
+    def choose_from_menu
+      return unasked_choice if @output.size == 1 && !@options[:ask]
+
+      if (helper_class = Util.any_const_get(@options[:helper_class]))
+        View.render_output(@output, :class=>@options[:helper_class], :options=>@options.merge(:number=>true))
+      else
+        @output.each_with_index {|e,i| puts "#{i+1}: #{e}" }
+      end
+
+      parse_input get_input
+    end
+
+    def unasked_choice
+      return @output unless @options[:action]
+      raise(Error, "Default command and field required for unasked action menu") unless default_field && @options[:command]
+      @new_args = [@options[:command], CHOSEN_ARG]
+      map_tokens([[@output, default_field]])
+    end
+
+    def execute_action(chosen)
+      return nil if chosen.size.zero?
+      if @options[:multi_action]
+        chosen.each {|e| invoke command, add_chosen_to_args(e) }
+      else
+        invoke command, add_chosen_to_args(chosen)
+      end
+    end
+
+    def invoke(cmd, args)
+      action_object.send(cmd, *args)
+    end
+
+    def parse_input(input)
+      if (@options[:two_d] || @options[:action])
+        tokens = input_to_tokens(input)
+        map_tokens(tokens)
+      else
+        Util.choose_from_array(@output, input)
+      end
+    end
+
+    def map_tokens(tokens)
+      if return_cell_values?
+        @output[0].is_a?(Hash) ? map_hash_of_tokens(tokens) : map_array_of_tokens(tokens)
+      else
+        map_all_args(tokens) { |arr, f| arr[0] }
+      end
+    end
+
+    def return_cell_values?
+      @options[:two_d]
+    end
+
+    def map_all_args(tokens)
+      tokens.map { |t| t == ALL_ARG ? @output : t }
+      tokens.map { |arr,f|
+        arr == ALL_ARG ? @output : yield(arr, f)
+      }.flatten
+    end
+
+    def map_hash_of_tokens(tokens)
+      map_all_args(tokens) { |arr,f| arr.map {|e| e[f]} }
+    end
+
+    def map_array_of_tokens(tokens)
+      map_all_args(tokens) { |arr,f| arr.map {|e| e.is_a?(Array) && f.is_a?(Integer) ? e[f] : e.send(f) } }
+    end
+
+    def input_to_tokens(input)
+      @new_args = []
+      tokens = (@args = split_input_args(input)).map {|word| parse_word(word) }.compact
+      cleanup_new_args
+      tokens
+    end
+
+    def parse_word(word)
+      if word[CHOSEN_REGEXP]
+        @new_args << CHOSEN_ARG
+        field = $3 ? unalias_field($3) : default_field ||
+          raise(Error, "No default field/column found. Fields must be explicitly picked.")
+        [Util.choose_from_array(@output, word), field ]
+      elsif word.index(ALL_ARG)
+        @new_args << CHOSEN_ARG
+        ALL_ARG
+      else
+        @new_args << word
+        nil
+      end
+    end
+
+    def cleanup_new_args
+      if @new_args.all? {|e| e == CHOSEN_ARG }
+        @new_args = [CHOSEN_ARG]
+      elsif @new_args.index(ALL_ARG)
+      else
+        i = @new_args.index(CHOSEN_ARG) || raise(Error, "No rows chosen")
+        @new_args.delete(CHOSEN_ARG)
+        @new_args.insert(i, CHOSEN_ARG)
+      end
+    end
+
+    def add_chosen_to_args(items)
+      args = @new_args.dup
+      args[args.index(CHOSEN_ARG)] = items
+      args
+    end
+
+    def command
+      @command ||= begin
+        cmd = (@new_args == [CHOSEN_ARG]) ? nil : @new_args.shift
+        cmd ||= @options[:command] || raise(Error, "No command given for action menu")
+      end
+    end
+
+    def action_object
+      @options[:action_object] || eval("self", TOPLEVEL_BINDING)
+    end
+
+    def split_input_args(input)
+      input.split(/\s+/)
+    end
+
+    def default_field
+      @default_field ||= @options[:default_field] || fields[0]
+    end
+
+    # Has to be called after displaying menu
+    def fields
+      @fields ||= @options[:fields] || (@options[:ask] && table_helper_class? && Helpers::Table.last_table ?
+        Helpers::Table.last_table.fields[1..-1] : [])
+    end
+
+    def table_helper_class?
+      @options[:helper_class].is_a?(Class) && @options[:helper_class] < Helpers::Table
+    end
+
+    def unalias_field(field)
+      fields.sort_by {|e| e.to_s }.find {|e| e.to_s[/^#{field}/] } || raise(Error, "Invalid field '#{field}'")
+    end
+
+    def readline_loads?
+      require 'readline'
+      true
+    rescue LoadError
+      false
+    end
+    #:startdoc:
+  end
+end

data/lib/hirb/pager.rb

@@ -0,0 +1,105 @@
+module Hirb
+  # This class provides class methods for paging and an object which can conditionally page given a terminal size that is exceeded.
+  class Pager
+    class<<self
+      # Pages using a configured or detected shell command.
+      def command_pager(output, options={})
+        basic_pager(output) if valid_pager_command?(options[:pager_command])
+      end
+
+      def pager_command(*commands) #:nodoc:
+        @pager_command = (!@pager_command.nil? && commands.empty?) ? @pager_command : 
+          begin
+            commands = [ENV['PAGER'], 'less', 'more', 'pager'] if commands.empty?
+            commands.compact.uniq.find {|e| Util.command_exists?(e[/\w+/]) }
+          end
+      end
+
+      # Pages with a ruby-only pager which either pages or quits.
+      def default_pager(output, options={})
+        pager = new(options[:width], options[:height])
+        while pager.activated_by?(output, options[:inspect])
+          puts pager.slice!(output, options[:inspect])
+          return unless continue_paging?
+        end
+        puts output
+        puts "=== Pager finished. ==="
+      end
+
+      #:stopdoc:
+      def valid_pager_command?(cmd)
+        cmd ? pager_command(cmd) : pager_command
+      end
+
+      private
+      def basic_pager(output)
+        pager = IO.popen(pager_command, "w")
+        begin
+          save_stdout = STDOUT.clone
+          STDOUT.reopen(pager)
+          STDOUT.puts output
+        rescue Errno::EPIPE
+        ensure
+         STDOUT.reopen(save_stdout)
+         save_stdout.close
+         pager.close
+        end
+      end
+
+      def continue_paging?
+        puts "=== Press enter/return to continue or q to quit: ==="
+        !$stdin.gets.chomp[/q/i]
+      end
+      #:startdoc:
+    end
+
+    attr_reader :width, :height
+
+    def initialize(width, height, options={})
+      resize(width, height)
+      @pager_command = options[:pager_command] if options[:pager_command]
+    end
+
+    # Pages given string using configured pager.
+    def page(string, inspect_mode)
+      if self.class.valid_pager_command?(@pager_command)
+        self.class.command_pager(string, :pager_command=>@pager_command)
+      else
+        self.class.default_pager(string, :width=>@width, :height=>@height, :inspect=>inspect_mode)
+      end
+    end
+
+    def slice!(output, inspect_mode=false) #:nodoc:
+      effective_height = @height - 2 # takes into account pager prompt
+      if inspect_mode
+        sliced_output = String.slice(output, 0, @width * effective_height)
+        output.replace String.slice(output, char_count(sliced_output), String.size(output))
+        sliced_output
+      else
+        # could use output.scan(/[^\n]*\n?/) instead of split
+        sliced_output = output.split("\n").slice(0, effective_height).join("\n")
+        output.replace output.split("\n").slice(effective_height..-1).join("\n")
+        sliced_output
+      end
+    end
+
+    # Determines if string should be paged based on configured width and height.
+    def activated_by?(string_to_page, inspect_mode=false)
+      inspect_mode ? (String.size(string_to_page) > @height * @width) : (string_to_page.count("\n") > @height)
+    end
+
+    if String.method_defined? :chars
+      def char_count(string) #:nodoc:
+        string.chars.count
+      end
+    else
+      def char_count(string) #:nodoc:
+        String.size(string)
+      end
+    end
+
+    def resize(width, height) #:nodoc:
+      @width, @height = View.determine_terminal_size(width, height)
+    end
+  end
+end

data/lib/hirb/string.rb

@@ -0,0 +1,44 @@
+module Hirb
+  # Provides string helpers to deal with UTF-8 and ruby 1.8.x
+  module String
+    extend self
+    # :stopdoc:
+    if RUBY_VERSION < '1.9'
+      def size(string)
+        string.scan(/./).length
+      end
+
+      def ljust(string, desired_length)
+        leftover = desired_length - size(string)
+        leftover > 0 ? string + " " * leftover : string
+      end
+
+      def rjust(string, desired_length)
+        leftover = desired_length - size(string)
+        leftover > 0 ? " " * leftover + string : string
+      end
+
+      def slice(string, start, finish)
+        string.scan(/./).slice(start, finish).join('')
+      end
+    else
+      def size(string)
+        string.length
+      end
+
+      def ljust(string, desired_length)
+        string.ljust(desired_length)
+      end
+
+      def rjust(string, desired_length)
+        string.rjust(desired_length)
+      end
+
+      def slice(*args)
+        string = args.shift
+        string.slice(*args)
+      end
+    end
+    #:startdoc:
+  end
+end