hirb 0.1.2

data/lib/hirb/helpers/parent_child_tree.rb

@@ -0,0 +1,22 @@
+class Hirb::Helpers::ParentChildTree < Hirb::Helpers::Tree
+  class <<self
+    # Starting with the given node, this builds a tree by recursively calling a children method.
+    # Takes same options as Hirb::Helper::Table.render with some additional ones below.
+    # ==== Options:
+    # [:value_method] Method to call to display as a node's value. If not given, uses :name if node
+    #                 responds to :name or defaults to :object_id.
+    # [:children_method] Method to call to obtain a node's children. Default is :children.
+    def render(root_node, options={})
+      @value_method = options[:value_method] || (root_node.respond_to?(:name) ? :name : :object_id)
+      @children_method = options[:children_method] || :children
+      @nodes = []
+      build_node(root_node, 0)
+      super(@nodes, options)
+    end
+
+    def build_node(node, level) #:nodoc:
+      @nodes << {:value=>node.send(@value_method), :level=>level}
+      node.send(@children_method).each {|e| build_node(e, level + 1)}
+    end
+  end
+end

data/lib/hirb/helpers/table.rb

@@ -0,0 +1,175 @@
+# Base Table class from which other table classes inherit.
+# By default, a table is constrained to a default width but this can be adjusted
+# via options as well as Hirb:Helpers::Table.max_width.
+# Rows can be an array of arrays or an array of hashes.
+#
+# An array of arrays ie [[1,2], [2,3]], would render:
+#   +---+---+
+#   | 0 | 1 |
+#   +---+---+
+#   | 1 | 2 |
+#   | 2 | 3 |
+#   +---+---+
+#
+# By default, the fields/columns are the numerical indices of the array.
+# 
+# An array of hashes ie [{:age=>10, :weight=>100}, {:age=>80, :weight=>500}], would render:
+#   +-----+--------+
+#   | age | weight |
+#   +-----+--------+
+#   | 10  | 100    |
+#   | 80  | 500    |
+#   +-----+--------+
+#
+# By default, the fields/columns are the keys of the first hash.
+#--
+# derived from http://gist.github.com/72234
+class Hirb::Helpers::Table
+  DEFAULT_MAX_WIDTH = 150
+  class TooManyFieldsForWidthError < StandardError; end
+  class << self
+    attr_accessor :max_width
+    
+    # Main method which returns a formatted table.
+    # ==== Options:
+    # [:fields] An array which overrides the default fields and can be used to indicate field order.
+    # [:headers] A hash of fields and their header names. Fields that aren't specified here default to their name.
+    #            This option can also be an array but only for array rows.
+    # [:field_lengths] A hash of fields and their maximum allowed lengths. If a field exceeds it's maximum
+    #                  length than it's truncated and has a ... appended to it. Fields that aren't specified here have no maximum allowed
+    #                  length.
+    # [:max_width] The maximum allowed width of all fields put together. This option is enforced except when the field_lengths option is set.
+    #              This doesn't count field borders as part of the total.
+    # Examples:
+    #    Hirb::Helpers::Table.render [[1,2], [2,3]]
+    #    Hirb::Helpers::Table.render [[1,2], [2,3]], :field_lengths=>{0=>10}
+    #    Hirb::Helpers::Table.render [{:age=>10, :weight=>100}, {:age=>80, :weight=>500}]
+    #    Hirb::Helpers::Table.render [{:age=>10, :weight=>100}, {:age=>80, :weight=>500}], :headers=>{:weight=>"Weight(lbs)"}
+    def render(rows, options={})
+      new(rows,options).render
+    end
+  end
+  
+  #:stopdoc:
+  def initialize(rows, options={})
+    @options = options
+    @fields = options[:fields] || ((rows[0].is_a?(Hash)) ? rows[0].keys.sort {|a,b| a.to_s <=> b.to_s} : 
+      rows[0].is_a?(Array) ? (0..rows[0].length - 1).to_a : [])
+    @rows = setup_rows(rows)
+    @headers = @fields.inject({}) {|h,e| h[e] = e.to_s; h}
+    if options.has_key?(:headers)
+      @headers = options[:headers].is_a?(Hash) ? @headers.merge(options[:headers]) : 
+        (options[:headers].is_a?(Array) ? array_to_indices_hash(options[:headers]) : options[:headers])
+    end
+  end
+  
+  def setup_rows(rows)
+    rows ||= []
+    rows = [rows] unless rows.is_a?(Array)
+    if rows[0].is_a?(Array)
+      rows = rows.inject([]) {|new_rows, row|
+        new_rows << array_to_indices_hash(row)
+      }
+    end
+    validate_values(rows)
+    rows
+  end
+  
+  def render
+    body = []
+    unless @rows.length == 0
+      setup_field_lengths
+      body += @headers ? render_header : [render_border]
+      body += render_rows
+      body << render_border
+    end
+    body << render_table_description
+    body.join("\n")
+  end
+  
+  def render_header
+    title_row = '| ' + @fields.map {|f|
+      format_cell(@headers[f], @field_lengths[f])
+    }.join(' | ') + ' |'
+    [render_border, title_row, render_border]
+  end
+  
+  def render_border
+    '+-' + @fields.map {|f| '-' * @field_lengths[f] }.join('-+-') + '-+'
+  end
+  
+  def format_cell(value, cell_width)
+    text = value.length > cell_width ? 
+      (
+      (cell_width < 5) ? value.slice(0,cell_width) : value.slice(0, cell_width - 3) + '...'
+      ) : value
+    sprintf("%-#{cell_width}s", text)
+  end
+  
+  def render_rows
+    @rows.map do |row|
+      row = '| ' + @fields.map {|f|
+        format_cell(row[f], @field_lengths[f])
+      }.join(' | ') + ' |'
+    end
+  end
+  
+  def render_table_description
+    (@rows.length == 0) ? "0 rows in set" :
+      "#{@rows.length} #{@rows.length == 1 ? 'row' : 'rows'} in set"
+  end
+  
+  def setup_field_lengths
+    @field_lengths = default_field_lengths
+    if @options[:field_lengths]
+      @field_lengths.merge!(@options[:field_lengths])
+    else
+      table_max_width = Hirb::Helpers::Table.max_width || DEFAULT_MAX_WIDTH
+      table_max_width = @options[:max_width] if @options.has_key?(:max_width)
+      restrict_field_lengths(@field_lengths, table_max_width)
+    end
+  end
+  
+  # Simple algorithm which given a max width, allows smaller fields to be displayed while
+  # restricting longer fields at an average_long_field_length.
+  def restrict_field_lengths(field_lengths, max_width)
+    total_length = field_lengths.values.inject {|t,n| t += n}
+    if max_width && total_length > max_width
+      min_field_length = 3
+      raise TooManyFieldsForWidthError if @fields.size > max_width.to_f / min_field_length
+      average_field_length = total_length / @fields.size.to_f
+      long_lengths = field_lengths.values.select {|e| e > average_field_length}
+      total_long_field_length = (long_lengths.inject {|t,n| t += n}) * max_width/total_length
+      average_long_field_length = total_long_field_length / long_lengths.size
+      field_lengths.each {|f,length|
+        field_lengths[f] = average_long_field_length if length > average_long_field_length
+      }
+    end
+  end
+
+  # find max length for each field; start with the headers
+  def default_field_lengths
+    field_lengths = @headers ? @headers.inject({}) {|h,(k,v)| h[k] = v.length; h} : {}
+    @rows.each do |row|
+      @fields.each do |field|
+        len = row[field].length
+        field_lengths[field] = len if len > field_lengths[field].to_i
+      end
+    end
+    field_lengths
+  end
+
+  def validate_values(rows)
+    rows.each {|row|
+      @fields.each {|f|
+        row[f] = row[f].to_s || ''
+      }
+    }
+  end
+  
+  # Converts an array to a hash mapping a numerical index to its array value.
+  def array_to_indices_hash(array)
+    array.inject({}) {|hash,e|  hash[hash.size] = e; hash }
+  end
+  #:startdoc:
+end

data/lib/hirb/helpers/tree.rb

@@ -0,0 +1,177 @@
+# 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.
+    #  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'
+      render_directory
+    when 'number'
+      render_number
+    else
+      render_basic
+    end
+  end
+
+  def render_directory
+    mark_last_nodes_per_level
+    new_nodes = []
+    @nodes.each_with_index {|e, i|
+      value = ''
+      unless e.root?
+        value << e.render_parent_characters
+        value << (e[:last_node] ? "`-- " : "|-- ")
+      end
+      value << e[:value]
+      new_nodes << value
+    }
+    new_nodes.join("\n")
+  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]}. "
+    }
+    @nodes.map {|e| @indent * e[:level] + e[:pre_value] + e[:value]}.join("\n")
+  end
+  
+  def render_basic
+    @nodes.map {|e| @indent * e[:level] + e[:value]}.join("\n")
+  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 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 }.to_s
+    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/import_object.rb

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

data/lib/hirb/util.rb

@@ -0,0 +1,29 @@
+module Hirb
+  module Util
+    extend self
+    # Returns a constant like const_get() no matter what namespace it's nested in.
+    # Returns nil if the constant is not found.
+    def any_const_get(name)
+      return name if name.is_a?(Module)
+      begin
+        klass = Object
+        name.split('::').each {|e|
+          klass = klass.const_get(e)
+        }
+        klass
+      rescue
+         nil
+      end
+    end
+    
+    # Recursively merge hash1 with hash2.
+    def recursive_hash_merge(hash1, hash2)
+      hash1.merge(hash2) {|k,o,n| (o.is_a?(Hash)) ? recursive_hash_merge(o,n) : n}
+    end
+
+    # from Rails ActiveSupport
+    def camelize(string)
+      string.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
+    end
+  end
+end

data/lib/hirb/view.rb

@@ -0,0 +1,201 @@
+module Hirb
+  # This class contains one method, render_output, which formats and renders the output its given from a console application.
+  # However, this only happens for output classes that are configured to do so or if render_output is explicitly given
+  # a view formatter. The hash with the following keys are valid for Hirb::View.config as well as the :view key mentioned in Hirb:
+  # [:output] This hash is saved to output_config. It maps output classes to hashes that are passed to render_output. Thus these hashes
+  #           take the same options as render_output. In addition it takes the following keys:
+  #           * :ancestor- Boolean which if true allows all subclasses of the configured output class to inherit this config.
+  # 
+  #           Example: {'String'=>{:class=>'Hirb::Helpers::Table', :ancestor=>true, :options=>{:max_width=>180}}}
+  module View
+    class<<self
+      attr_accessor :config, :render_method
+
+      # Overrides irb's output method with Hirb::View.render_output. Takes an optional
+      # block which sets the view config.
+      # Examples:
+      #   Hirb.enable
+      #   Hirb.enable {|c| c.output = {'String'=>{:class=>'Hirb::Helpers::Table'}} }
+      def enable(&block)
+        return puts("Already enabled.") if @enabled
+        @enabled = true
+        load_config(Hirb::HashStruct.block_to_hash(block))
+        ::IRB::Irb.class_eval do
+          alias :non_hirb_render_output  :output_value
+          def output_value #:nodoc:
+            Hirb::View.render_output(@context.last_value) || non_hirb_render_output
+          end
+        end
+      end
+      
+      # Disable's Hirb's output by reverting back to irb's.
+      def disable
+        @enabled = false
+        ::IRB::Irb.class_eval do
+          alias :output_value :non_hirb_render_output
+        end
+      end
+      
+      # This is the main method of this class. This method searches for the first formatter it can apply
+      # to the object in this order: local block, method option, class option. If a formatter is found it applies it to the object
+      # and returns true. Returns false if no formatter found.
+      # ==== Options:
+      # [:method] Specifies a global (Kernel) method to do the formatting.
+      # [:class] Specifies a class to do the formatting, using its render() class method. The render() method's arguments are the output and 
+      #          an options hash.
+      # [:output_method] Specifies a method to call on output before passing it to a formatter.
+      # [:options] Options to pass the formatter method or class.
+      def render_output(output, options={}, &block)
+        if block && block.arity > 0
+          formatted_output = block.call(output)
+          render_method.call(formatted_output)
+          true
+        elsif (formatted_output = format_output(output, options))
+          render_method.call(formatted_output)
+          true
+        else
+          false
+        end
+      end
+
+      # A lambda or proc which handles the final formatted object.
+      # Although this puts the object by default, it could be set to do other things
+      # ie write the formatted object to a file.
+      def render_method
+        @render_method ||= default_render_method
+      end
+
+      def reset_render_method
+        @render_method = default_render_method
+      end
+
+      # Config hash which maps classes to view hashes. View hashes are the same as the options hash of render_output().
+      def output_config
+        config[:output]
+      end
+
+      def output_config=(value)
+        @config[:output] = value
+      end
+      
+      # Needs to be called for config changes to take effect. Reloads Hirb::Views classes and registers
+      # most recent config changes.
+      def reload_config
+        current_config = self.config.dup.merge(:output=>output_config)
+        load_config(current_config)
+      end
+      
+      # A console version of render_output which takes its same options but allows for some shortcuts.
+      # Examples:
+      #   console_render_output output, :tree, :type=>:directory
+      #   # is the same as:
+      #   render_output output, :class=>"Hirb::Helpers::Tree", :options=> {:type=>:directory}
+      #
+      def console_render_output(*args, &block)
+        load_config unless @config
+        output = args.shift
+        if args[0].is_a?(Symbol) && (view = args.shift)
+          symbol_options = find_view(view)
+        end
+        options = args[-1].is_a?(Hash) ? args[-1] : {}
+        options.merge!(symbol_options) if symbol_options
+        # iterates over format_output options that aren't :options
+        real_options = [:method, :class, :output_method].inject({}) do |h, e|
+          h[e] = options.delete(e) if options[e]; h
+        end
+        render_output(output, real_options.merge(:options=>options), &block)
+      end
+
+      #:stopdoc:
+      def find_view(name)
+        name = name.to_s
+        if (view_method = output_config.values.find {|e| e[:method] == name })
+          {:method=>view_method[:method]}
+        elsif (view_class = Hirb::Helpers.constants.find {|e| e == Util.camelize(name)})
+          {:class=>"Hirb::Helpers::#{view_class}"}
+        else
+          {}
+        end
+      end
+
+      def format_output(output, options={})
+        output_class = determine_output_class(output)
+        options = Util.recursive_hash_merge(output_class_options(output_class), options)
+        output = options[:output_method] ? (output.is_a?(Array) ? output.map {|e| e.send(options[:output_method])} : 
+          output.send(options[:output_method]) ) : output
+        args = [output]
+        args << options[:options] if options[:options] && !options[:options].empty?
+        if options[:method]
+          new_output = send(options[:method],*args)
+        elsif options[:class] && (view_class = Util.any_const_get(options[:class]))
+          new_output = view_class.render(*args)
+        end
+        new_output
+      end
+
+      def determine_output_class(output)
+        if output.is_a?(Array)
+          output[0].class
+        else
+          output.class
+        end
+      end
+
+      def load_config(additional_config={})
+        self.config = Util.recursive_hash_merge default_config, additional_config
+        true
+      end
+
+      # Stores all view config. Current valid keys:
+      #   :output- contains value of output_config
+      def config=(value)
+        reset_cached_output_config
+        @config = value
+      end
+      
+      def reset_cached_output_config
+        @cached_output_config = nil
+      end
+      
+      # Internal view options built from user-defined ones. Options are built by recursively merging options from oldest
+      # ancestors to the most recent ones.
+      def output_class_options(output_class)
+        @cached_output_config ||= {}
+        @cached_output_config[output_class] ||= 
+          begin
+            output_ancestors_with_config = output_class.ancestors.map {|e| e.to_s}.select {|e| output_config.has_key?(e)}
+            @cached_output_config[output_class] = output_ancestors_with_config.reverse.inject({}) {|h, klass|
+              (klass == output_class.to_s || output_config[klass][:ancestor]) ? h.update(output_config[klass]) : h
+            }
+          end
+        @cached_output_config[output_class]
+      end
+      
+      def cached_output_config; @cached_output_config; end
+
+      def default_render_method
+        lambda {|output| puts output}
+      end
+
+      def default_config
+        Hirb::Util.recursive_hash_merge({:output=>default_output_config}, Hirb.config[:view] || {} )
+      end
+
+      def default_output_config
+        Hirb::Views.constants.inject({}) {|h,e|
+          output_class = e.to_s.gsub("_", "::")
+          if (views_class = Hirb::Views.const_get(e)) && views_class.respond_to?(:render)
+            default_options = views_class.respond_to?(:default_options) ? views_class.default_options : {}
+            h[output_class] = default_options.merge({:class=>"Hirb::Views::#{e}"})
+          end
+          h
+        }
+      end
+      #:startdoc:
+    end
+  end
+  
+  # Namespace for autoloaded views
+  module Views
+  end
+end