hirber 0.8.0

data/lib/bond/completions/hirb.rb

@@ -0,0 +1,15 @@
+complete(:methods=>%w{Hirb::View.enable Hirb.enable}) {
+  %w{config_file output_method output width height formatter pager pager_command}
+}
+complete(:methods=>%w{Hirb::Helpers::Table.render table}) {
+  %w{fields headers max_fields max_width resize number change_fields}+
+  %w{filters header_filter filter_any filter_classes vertical all_fields}+
+  %w{description escape_special_chars table_class hide_empty unicode grep_fields}
+}
+complete(:method=>"Hirb::Helpers::Tree.render") {
+  %w{type validate indent limit description multi_line_nodes value_method children_method}
+}
+complete(:methods=>%w{Hirb::Menu.render menu}) {
+  %w{helper_class prompt ask directions readline two_d default_field action multi_action} +
+    %w{action_object command reopen}
+}

data/lib/hirb.rb

@@ -0,0 +1,84 @@
+# Needed by Hirb::String to handle multibyte characters
+$KCODE = 'u' if RUBY_VERSION < '1.9'
+
+require 'yaml'
+require 'hirb/util'
+require 'hirb/string'
+require 'hirb/formatter' # must come before helpers/auto_table
+require 'hirb/dynamic_view'
+require 'hirb/helpers'
+require 'hirb/views'
+require 'hirb/view'
+require 'hirb/console'
+require 'hirb/pager'
+require 'hirb/menu'
+require 'hirb/version'
+
+# Most of Hirb's functionality is in Hirb::View.
+# For a tutorial  on configuring and creating views see Hirb::View. For a tutorial on dynamic views see Hirb::DynamicView.
+#
+# == Config Files
+# Hirb can have multiple config files defined by config_files(). These config files
+# have the following top level keys:
+# [*:output*] This hash is used by the formatter object. See Hirb::Formatter.config for its format.
+# [*:width*]  Width of the terminal/console. Defaults to Hirb::View::DEFAULT_WIDTH or possibly autodetected when Hirb is enabled.
+# [*:height*]  Height of the terminal/console. Defaults to Hirb::View::DEFAULT_HEIGHT or possibly autodetected when Hirb is enabled.
+# [*:formatter*] Boolean which determines if the formatter is enabled. Defaults to true.
+# [*:pager*] Boolean which determines if the pager is enabled. Defaults to true.
+# [*:pager_command*] Command to be used for paging. Command can have options after it i.e. 'less -r'.
+#                    Defaults to common pagers i.e. less and more if detected.
+# [*:ignore_errors*] Boolean which ignores internal view errors and continues with original view
+#                    (i.e. #inspect for irb). Defaults to false.
+module Hirb
+  class <<self
+    attr_accessor :config_files, :config
+
+    # Enables view functionality. See Hirb::View.enable for details.
+    def enable(options={})
+      View.enable(options)
+    end
+
+    # Disables view functionality. See Hirb::View.disable for details.
+    def disable
+      View.disable
+    end
+
+    # Adds views. See Hirb::View.add for details.
+    def add_view(view, options)
+      View.add(view, options)
+    end
+
+    # Adds views. See Hirb::DynamicView.add for details.
+    def add_dynamic_view(view, options, &block)
+      DynamicView.add(view, options, &block)
+    end
+
+    # Array of config files which are merged sequentially to produce config.
+    # Defaults to config/hirb.yml and ~/.hirb_yml
+    undef :config_files
+    def config_files
+      @config_files ||= default_config_files
+    end
+
+    #:stopdoc:
+    def default_config_files
+      [File.join(Util.find_home, ".hirb.yml")] +
+        (File.exist?('config/hirb.yml') ? ['config/hirb.yml'] : [])
+    end
+
+    def read_config_file(file=config_file)
+      File.exist?(file) ? YAML.load_file(file) : {}
+    end
+
+    undef :config
+    def config(reload=false)
+      if (@config.nil? || reload)
+        @config = config_files.inject({}) {|acc,e|
+          Util.recursive_hash_merge(acc,read_config_file(e))
+        }
+      end
+      @config
+    end
+    #:startdoc:
+  end
+end

data/lib/hirb/console.rb

@@ -0,0 +1,43 @@
+module Hirb
+  # This module is meant to be extended to provide methods for use in a console/irb shell.
+  # For example:
+  #    >> extend Hirb::Console
+  #    >> view 'some string', :class=>Some::String::Formatter
+  #    >> table [[:row1], [:row2]]
+  module Console
+    class<<self
+      # A console version of render_output() which takes its same options but allows for shorthand. All options are passed to
+      # the helper except for the formatter options. Formatter options are :class, :method and :output_method.
+      # Examples:
+      #   render_output output, :class=>:tree :type=>:directory
+      #   # is the same as:
+      #   render_output output, :class=>:tree, :options=> {:type=>:directory}
+      #
+      def render_output(output, options={})
+        View.load_config unless View.config_loaded?
+        View.render_output(output, options.merge(:console=>true))
+      end
+
+      # Takes same arguments and options as render_output() but returns formatted output instead of rendering it.
+      def format_output(output, options={}, &block)
+        View.load_config unless View.config_loaded?
+        View.formatter.format_output(output, options.merge(:console=>true), &block)
+      end
+    end
+
+    # Renders a table for the given object. Takes same options as Hirb::Helpers::Table.render.
+    def table(output, options={})
+      Console.render_output(output, options.merge(:class=>"Hirb::Helpers::AutoTable"))
+    end
+
+    # Renders any specified view for the given object. Takes same options as Hirb::View.render_output.
+    def view(output, options={})
+      Console.render_output(output, options)
+    end
+
+    # Renders a menu given an array using Hirb::Menu.render.
+    def menu(output, options={}, &block)
+      Console.format_output(output, options.merge(:class=>"Hirb::Menu"), &block)
+    end
+  end
+end

data/lib/hirb/dynamic_view.rb

@@ -0,0 +1,113 @@
+module Hirb
+  # This module extends a Helper with the ability to have dynamic views for configured output classes.
+  # After a Helper has extended this module, it can use it within a render() by calling
+  # dynamic_options() to get dynamically generated options for the object it's rendering. See Hirb::Helpers::AutoTable as an example.
+  #
+  # == Dynamic Views
+  # Whereas normal views are generated from helpers with static helper options, dynamic views are generated from helpers and
+  # dynamically generated helper options. Let's look at an example for Rails' ActiveRecord classes:
+  #
+  #   Hirb.add_dynamic_view("ActiveRecord::Base", :helper=>:auto_table) {|obj|
+  #    {:fields=>obj.class.column_names} }
+  #
+  # From this dynamic view definition, _any_ ActiveRecord model class will render a table with the correct fields, since the fields
+  # are extracted from the output object's class at runtime. Note that dynamic view definitions should return a hash of helper options.
+  #
+  # To define multiple dynamic views, create a Views module where each method ending in '\_view' maps to a class/module:
+  #
+  #   module Hirb::Views::ORM
+  #     def data_mapper__resource_view(obj)
+  #       {:fields=>obj.class.properties.map {|e| e.name }}
+  #     end
+  #
+  #     def sequel__model_view(obj)
+  #       {:fields=>obj.class.columns}
+  #     end
+  #   end
+  #
+  #   Hirb.add_dynamic_view Hirb::Views::ORM, :helper=>:auto_table
+  #
+  # In this example, 'data_mapper__resource_view' maps to DataMapper::Resource and 'sequel__model_view' maps to Sequel::Model.
+  # Note that when mapping method names to class names, '__' maps to '::' and '_' signals the next letter to be capitalized.
+  module DynamicView
+    # Add dynamic views to output class(es) for a given helper. If defining one view, the first argument is the output class
+    # and a block defines the dynamic view. If defining multiple views, the first argument should be a Views::* module where
+    # each method in the module ending in _view defines a view for an output class. To map output classes to method names in
+    # a Views module, translate'::' to '__' and a capital letter translates to a '_' and a lowercase letter.
+    # ==== Options:
+    # [*:helper*] Required option. Helper class that view(s) use to format. Hirb::Helpers::AutoTable is the only valid
+    #             helper among default helpers. Can be given in aliased form i.e. :auto_table -> Hirb::Helpers::AutoTable.
+    #
+    # Examples:
+    #    Hirb.add_dynamic_view Hirb::Views::ORM, :helper=>:auto_table
+    #    Hirb.add_dynamic_view("ActiveRecord::Base", :helper=>:auto_table) {|obj| {:fields=>obj.class.column_names} }
+    def self.add(view, options, &block)
+      raise ArgumentError, ":helper option is required" unless options[:helper]
+      helper = Helpers.helper_class options[:helper]
+      unless helper.is_a?(Module) && class << helper; self.ancestors; end.include?(self)
+        raise ArgumentError, ":helper option must be a helper that has extended DynamicView"
+      end
+      mod = block ? generate_single_view_module(view, &block) : view
+      raise ArgumentError, "'#{mod}' must be a module" unless mod.is_a?(Module)
+      helper.add_module mod
+    end
+
+    def self.generate_single_view_module(output_mod, &block) #:nodoc:
+      meth = class_to_method output_mod.to_s
+      view_mod = meth.capitalize
+      Views::Single.send(:remove_const, view_mod) if Views::Single.const_defined?(view_mod)
+      mod = Views::Single.const_set(view_mod, Module.new)
+      mod.send(:define_method, meth, block)
+      mod
+    end
+
+    def self.class_to_method(mod) #:nodoc:
+      mod.gsub(/(?!^)([A-Z])/) {|e| '_'+e }.gsub('::_', '__').downcase + '_view'
+    end
+
+    # Returns a hash of options based on dynamic views defined for the object's ancestry. If no config is found returns nil.
+    def dynamic_options(obj)
+      view_methods.each do |meth|
+        if obj.class.ancestors.map {|e| e.to_s }.include?(method_to_class(meth))
+          begin
+            return send(meth, obj)
+          rescue
+            raise "View failed to generate for '#{method_to_class(meth)}' "+
+              "while in '#{meth}' with error:\n#{$!.message}"
+          end
+        end
+      end
+      nil
+    end
+
+    #:stopdoc:
+    def add_module(mod)
+      new_methods = mod.instance_methods.select {|e| e.to_s =~ /_view$/ }.map {|e| e.to_s}
+      return if new_methods.empty?
+      extend mod
+      view_methods.replace(view_methods + new_methods).uniq!
+      update_config(new_methods)
+    end
+
+    def update_config(meths)
+      output_config = meths.inject({}) {|t,e|
+        t[method_to_class(e)] = {:class=>self, :ancestor=>true}; t
+      }
+      Formatter.dynamic_config.merge! output_config
+    end
+
+    def method_to_class(meth)
+      view_method_classes[meth] ||= Util.camelize meth.sub(/_view$/, '').gsub('__', '/')
+    end
+
+    def view_method_classes
+      @view_method_classes ||= {}
+    end
+    #:startdoc:
+
+    # Stores view methods that a Helper has been given via DynamicView.add
+    def view_methods
+      @view_methods ||= []
+    end
+  end
+end

data/lib/hirb/formatter.rb

@@ -0,0 +1,126 @@
+module Hirb
+  # A Formatter object formats an output object (using Formatter.format_output) into a string based on the views defined
+  # for its class and/or ancestry.
+  class Formatter
+    class<<self
+      # This config is used by Formatter.format_output to lazily load dynamic views defined with Hirb::DynamicView.
+      # This hash has the same format as Formatter.config.
+      attr_accessor :dynamic_config
+
+      # Array of classes whose objects respond to :to_a and allow the first
+      # element of the converted array to determine the output class.
+      attr_accessor :to_a_classes
+    end
+    self.dynamic_config = {}
+    self.to_a_classes = %w{Array Set ActiveRecord::Relation}
+
+    def initialize(additional_config={}) #:nodoc:
+      @klass_config = {}
+      @config = additional_config || {}
+    end
+
+    # A hash of Ruby class strings mapped to view hashes. A view hash must have at least a :method, :output_method
+    # or :class option for a view to be applied to an output. A view hash has the following keys:
+    # [*:method*] Specifies a global (Kernel) method to do the formatting.
+    # [*:class*] Specifies a class to do the formatting, using its render() class method. If a symbol it's converted to a corresponding
+    #            Hirb::Helpers::* class if it exists.
+    # [*:output_method*] Specifies a method or proc to call on output before passing it to a helper. If the output is an array, it's applied
+    #                    to every element in the array.
+    # [*:options*] Options to pass the helper method or class.
+    # [*:ancestor*] Boolean which when true causes subclasses of the output class to inherit its config. This doesn't effect the current
+    #               output class. Defaults to false. This is used by ActiveRecord classes.
+    #
+    #   Examples:
+    #     {'WWW::Delicious::Element'=>{:class=>'Hirb::Helpers::ObjectTable', :ancestor=>true, :options=>{:max_width=>180}}}
+    #     {'Date'=>{:class=>:auto_table, :ancestor=>true}}
+    #     {'Hash'=>{:method=>:puts}}
+    def config
+      @config
+    end
+
+    # Adds the view for the given class and view hash config. See Formatter.config for valid keys for view hash.
+    def add_view(klass, view_config)
+      @klass_config.delete(klass)
+      @config[klass.to_s] = view_config
+      true
+    end
+
+    # This method looks for an output object's view in Formatter.config and then Formatter.dynamic_config.
+    # If a view is found, a stringified view is returned based on the object. If no view is found, nil is returned. The options this
+    # class takes are a view hash as described in Formatter.config. These options will be merged with any existing helper
+    # config hash an output class has in Formatter.config. Any block given is passed along to a helper class.
+    def format_output(output, options={}, &block)
+      output_class = determine_output_class(output)
+      options = parse_console_options(options) if options.delete(:console)
+      options = Util.recursive_hash_merge(klass_config(output_class), options)
+      _format_output(output, options, &block)
+    end
+
+    #:stopdoc:
+    def to_a_classes
+      @to_a_classes ||= self.class.to_a_classes.map {|e| Util.any_const_get(e) }.compact
+    end
+
+    def _format_output(output, options, &block)
+      output = options[:output_method] ? (output.is_a?(Array) ?
+        output.map {|e| call_output_method(options[:output_method], e) } :
+        call_output_method(options[:output_method], output) ) : output
+      args = [output]
+      args << options[:options] if options[:options] && !options[:options].empty?
+      if options[:method]
+        send(options[:method],*args)
+      elsif options[:class] && (helper_class = Helpers.helper_class(options[:class]))
+        helper_class.render(*args, &block)
+      elsif options[:output_method]
+        output
+      end
+    end
+
+    def parse_console_options(options) #:nodoc:
+      real_options = [:method, :class, :output_method].inject({}) do |h, e|
+        h[e] = options.delete(e) if options[e]; h
+      end
+      real_options.merge! :options=>options
+    end
+
+    def determine_output_class(output)
+      output.respond_to?(:to_a) && to_a_classes.any? {|e| output.is_a?(e) } ?
+        Array(output)[0].class : output.class
+    end
+
+    def call_output_method(output_method, output)
+      output_method.is_a?(Proc) ? output_method.call(output) : output.send(output_method)
+    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 klass_config(output_class)
+      @klass_config[output_class] ||= build_klass_config(output_class)
+    end
+
+    def build_klass_config(output_class)
+      output_ancestors = output_class.ancestors.map {|e| e.to_s}.reverse
+      output_ancestors.pop
+      hash = output_ancestors.inject({}) {|h, ancestor_klass|
+        add_klass_config_if_true(h, ancestor_klass) {|c, klass| c[klass] && c[klass][:ancestor] }
+      }
+      add_klass_config_if_true(hash, output_class.to_s) {|c, klass| c[klass] }
+    end
+
+    def add_klass_config_if_true(hash, klass)
+      if yield(@config, klass)
+        Util.recursive_hash_merge hash, @config[klass]
+      elsif yield(self.class.dynamic_config, klass)
+        @config[klass] = self.class.dynamic_config[klass].dup # copy to local
+        Util.recursive_hash_merge hash, self.class.dynamic_config[klass]
+      else
+        hash
+      end
+    end
+
+    def reset_klass_config
+      @klass_config = {}
+    end
+    #:startdoc:
+  end
+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
+  markdown_table unicode_table tab_table}.each do |e|
+  require "hirb/helpers/#{e}"
+end

data/lib/hirb/helpers/auto_table.rb

@@ -0,0 +1,24 @@
+# This helper wraps around the other table helpers i.e. Hirb::Helpers::Table while
+# providing default helper options via Hirb::DynamicView. Using these default options, this
+# helper supports views for the following modules/classes:
+# ActiveRecord::Base, CouchFoo::Base, CouchPotato::Persistence, CouchRest::ExtendedDocument,
+# DBI::Row, DataMapper::Resource, Friendly::Document, MongoMapper::Document, MongoMapper::EmbeddedDocument,
+# Mongoid::Document, Ripple::Document, Sequel::Model.
+class Hirb::Helpers::AutoTable < Hirb::Helpers::Table
+  extend Hirb::DynamicView
+
+  # Takes same options as Hirb::Helpers::Table.render except as noted below.
+  #
+  # ==== Options:
+  # [:table_class] Explicit table class to use for rendering. Defaults to
+  #                Hirb::Helpers::ObjectTable if output is not an Array or Hash. Otherwise
+  #                defaults to Hirb::Helpers::Table.
+  def self.render(output, options={})
+    output = Array(output)
+    (defaults = dynamic_options(output[0])) && (options = defaults.merge(options))
+    klass = options.delete(:table_class) || (
+      !(output[0].is_a?(Hash) || output[0].is_a?(Array)) ?
+      Hirb::Helpers::ObjectTable : Hirb::Helpers::Table)
+    klass.render(output, options)
+  end
+end

data/lib/hirb/helpers/markdown_table.rb

@@ -0,0 +1,14 @@
+# Creates a markdown table for github
+class Hirb::Helpers::MarkdownTable < 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 => ' | '} }
+  }
+
+  def self.render(rows, options={})
+    new(rows, options).render
+  end
+end

data/lib/hirb/helpers/object_table.rb

@@ -0,0 +1,14 @@
+class Hirb::Helpers::ObjectTable < Hirb::Helpers::Table
+  # Rows are any ruby objects. Takes same options as Hirb::Helpers::Table.render except as noted below.
+  #
+  # ==== Options:
+  # [:fields] Methods of the object to represent as columns. Defaults to [:to_s].
+  def self.render(rows, options ={})
+    options[:fields] ||= [:to_s]
+    options[:headers] ||= {:to_s=>'value'} if options[:fields] == [:to_s]
+    item_hashes = options[:fields].empty? ? [] : Array(rows).inject([]) {|t,item|
+      t << options[:fields].inject({}) {|h,f| h[f] = item.__send__(f); h}
+    }
+    super(item_hashes, options)
+  end
+end