hirb 0.1.2 → 0.2.2

data/CHANGELOG.rdoc

@@ -1,3 +1,19 @@
+== 0.2.2
+* Added a friendlier default (a vertical table) to incorrectly configured tables.
+* Added vertical table helper thanks to chrononaut.
+* Added detection of :select option from ActiveRecord queries in ActiveRecordTable helper.
+* Added handling anything that responds to :to_a in AutoTable helper.
+
+== 0.2.1
+* Fixed typo in Hirb::Console.view
+
+== 0.2.0
+* Major refactoring with bug fixes and better tests.
+* Improved table algorithm to ensure that tables don't wrap.
+* Added a pager which detects if output should be paged, Hirb::Pager.
+* Added a selection menu, Hirb::Menu
+* Following API changes: Hirb::Helpers::Table.max_width removed and config files don't use
+  the :view key anymore.
 == 0.1.2
 * Added tree views.
 * Added output_method option to Hirb::View.render_output.

data/README.rdoc

@@ -1,11 +1,12 @@
 == Description
 
-Hirb currently provides a mini view framework for console applications, designed with irb in mind.
-Given the output of a console application, it renders a view if there is one configured, based on
-the output's class. The framework encourages reusing views by letting you package them in classes
-and associate them with any number of output classes.  Hirb comes with tree views (see
+Hirb currently provides a mini view framework for console applications, designed to improve irb's default output.
+Hirb improves console output by providing a smart pager and auto-formatting output. The smart pager detects when an output exceeds
+a screenful and thus only pages output as needed. Auto-formatting adds a view to an output's class. This is helpful in separating
+views from content (MVC anyone?). The framework encourages reusing views by letting you
+package them in classes and associate them with any number of output classes.  Hirb comes with tree views (see
 Hirb::Helpers::Tree) and table views (see Hirb::Helpers::Table). By default Hirb displays Rails'
-model classes as tables.
+model classes as tables. Hirb also sports a nice selection menu, Hirb::Menu.
 
 == Install
 
@@ -13,19 +14,36 @@ Install the gem with:
 
     sudo gem install cldwalker-hirb --source http://gems.github.com
 
-== Rails Example
+== Pager
+
+Hirb has both pager and formatter functionality enabled by default.
+If you want to turn off the functionality of either you can pass that in at startup:
+
+  Hirb.enable :pager=>false
+  Hirb.enable :formatter=>false
+
+or toggle their state at runtime:
+
+  Hirb::View.toggle_pager
+  Hirb::View.toggle_formatter
+
+== Create and Configure Views
+
+If you'd like to learn how to create and configure views, {read the docs}[http://tagaholic.me/hirb/doc/classes/Hirb/Formatter.html].
+
+== Rails Formatter Example
 
 Let's load and enable the view framework:
   bash> script/console
   Loading local environment (Rails 2.2.2)
   irb>> require 'hirb'
   => true
-  irb>> Hirb::View.enable
+  irb>> Hirb.enable
   => nil
 
 The default configuration provides table views for ActiveRecord::Base descendants.
 If a class isn't configured, Hirb reverts to irb's default echo mode.
-  irb>> Hirb::View.output_config
+  irb>> Hirb::View.formatter_config
   => {"ActiveRecord::Base"=>{:class=>"Hirb::Views::ActiveRecord_Base", :ancestor=>true}}
 
   # Tag is a model class and descendant of ActiveRecord::Base
@@ -60,7 +78,7 @@ you may appreciate it also detects configured output objects in an array:
   3 rows in set
 
 At any time you can disable Hirb if you really like irb's lovely echo mode:
-  irb>> Hirb::View.disable
+  irb>> Hirb.disable
   => nil
   irb>> Tag.all :limit=>3, :order=>"id DESC"
   => [#<Tag id: 907, name: "gem:tags=yaml", description: nil, created_at: "2009-03-06 21:10:41",
@@ -74,7 +92,7 @@ While preconfigured tables are great for database records, sometimes you just wa
 tables/views for any output object:
   
   #These examples don't need to have Hirb::View enabled.
-  irb>>Hirb::View.disable
+  irb>>Hirb.disable
   =>nil
 
   # Imports table() and view()
@@ -91,8 +109,8 @@ tables/views for any output object:
   +------------+--------+-----------+-------+--------------------------+
   2 rows in set
 
-  # Same table as the previous method. However view() will be able to call any view created.
-  irb>> view [Date.today, Date.today.next_month], :class=>Hirb::Helpers::ObjectTable,
+  # Same table as the previous method. However view() will be able to call any helper.
+  irb>> view [Date.today, Date.today.next_month], :class=>:object_table,
     :fields=>[:to_s, :ld, :ajd, :amjd, :asctime]
 
 If these console methods weren't convenient enough, try:
@@ -101,7 +119,7 @@ If these console methods weren't convenient enough, try:
   irb>> require 'hirb/import_object'
   =>true
   # Yields same table as above examples.
-  irb>> [Date.today, Date.today.next_month].view :class=>Hirb::Helpers::ObjectTable,
+  irb>> [Date.today, Date.today.next_month].view :class=>:object_table,
     :fields=>[:to_s, :ld, :ajd, :amjd, :asctime]
 
 Although views by default are printed to STDOUT, they can be easily modified to write anywhere:
@@ -109,7 +127,7 @@ Although views by default are printed to STDOUT, they can be easily modified to
   irb>> Hirb::View.render_method = lambda {|output| File.open("console.log", 'w') {|f| f.write(output) } }
 
   # Writes to file with same table output as above example.
-  irb>> view [Date.today, Date.today.next_month], :class=>Hirb::Helpers::ObjectTable,
+  irb>> view [Date.today, Date.today.next_month], :class=>:object_table,
     :fields=>[:to_s, :ld, :ajd, :amjd, :asctime]
 
   # Doesn't write to file because Symbol isn't configured to use Hirb::View and thus defaults to irb's echo mode.
@@ -119,113 +137,31 @@ Although views by default are printed to STDOUT, they can be easily modified to
   # Go back to printing Hirb views to STDOUT.
   irb>> Hirb::View.reset_render_method
 
-== Create and Configure Views
-Let's create a simple view and configure it in different ways to be Hash's default view:
-
-=== Setup
-  irb>> require 'hirb'
-  =>true
-  irb>> Hirb::View.enable
-  =>nil
-  irb>> require 'yaml'
-  =>true
-
-=== Configure As View Method
-A view method is the smallest reuseable view.
-  # Create yaml view method
-  irb>> def yaml(output); output.to_yaml; end
-  =>nil
-
-  # Configure view and reload it
-  irb>>Hirb::View.output_config = {"Hash"=>{:method=>:yaml}}
-  =>{"Hash"=>{:method=>:yaml}}
-  irb>>Hash::View.reload_config
-  =>true
-
-  # Hashes now appear as yaml
-  irb>>{:a=>1, :b=>{:c=>3}}
-  ---
-  :a : 1
-  :b : 
-    :c : 3
-  => true
-
-=== Configure As View Class
-A view class is suited for more complex views. View classes can be under any namespace
-and are expected to provide a render method. However, if a class is under the Hirb::Views namespace,
-it will be automatically loaded with no configuration. Something to think about when
-sharing views with others.
-
-  # Create yaml view class
-  irb>> class Hirb::Views::Hash; def self.render(output, options={}); output.to_yaml; end ;end
-  =>nil
-  # Just reload since no configuration is necessary
-  irb>>Hirb::View.reload_config
-
-  # Hashes now appear as yaml ...
-
-Although the Hirb::Views namespace is great for quick classes that just plug and play, you
-often want view classes that can be reused with multiple outputs. For this case, it's recommended to
-use the Hirb::Helpers namespace.
-  
-  # Create yaml view class
-  irb>> class Hirb::Helpers::Yaml; def self.render(output, options={}); output.to_yaml; end ;end
-  =>nil
-
-  # Configure view and reload it
-  irb>>Hirb::View.output_config = {"Hash"=>{:class=>"Hirb::Helpers::Yaml"}}
-  =>{"Hash"=>{:class=>"Hirb::Helpers::Yaml"}}
-  irb>>Hirb::View.reload_config
-
-  # Hashes now appear as yaml ...
-
-=== Configure At Startup
-Once you know what views are associated with what output classes, you can configure
-them at startup by passing Hirb::View.enable a block:
-  # In .irbrc
-  require 'hirb'
-  # View class needs to come before enable()
-  class Hirb::Helpers::Yaml; def self.render(output, options={}); output.to_yaml; end ;end
-  Hirb::View.enable {|conf| conf.output = {"Hash"=>{:class=>"Hirb::Helpers::Yaml"}} }
-  
-Or by creating a config file at config/hirb.yml or ~/.hirb.yml:
-  # The config file for the yaml example would look like:
-  # ---
-  # :view :
-  #  :output :
-  #    Hash :
-  #      :class : Hirb::Helpers::Yaml
-
-  # In .irbrc
-  require 'hirb'
-  # View class needs to come before enable()
-  class Hirb::Helpers::Yaml; def self.render(output, options={}); output.to_yaml; end ;end
-  Hirb::View.enable
-
-== Contributing Views
-If you have views of your own you'd like to share, fork Hirb and put your views under
-the Hirb::Helpers namespace and the view files under lib/hirb/helpers/.
+== Sharing Views
+If you have tested views you'd like to share, fork Hirb and put your views under
+the lib/hirb/views/ and/or helpers files under lib/hirb/helpers/. If not tested, feel free to share
+them on the wiki.
 
 == Limitations
-Although Hirb preserves Wirble colorizing irb's default echo mode, it doesn't colorize its own views.
-This is mainly because colorizing caused table classes to render incorrectly. If you can get tables
-and colors to work nicely, please fork. To colorize your Hirb output:
-  Hirb::View.render_method = lambda {|output| puts Wirble::Colorize.colorize(output) }
+If using Wirble, you should call Hirb after it since they both override irb's default output.
 
 == Motivation
 Table code from http://gist.github.com/72234 and {my console
 app's needs}[http://github.com/cldwalker/tag-tree].
 
-== Bugs
-Please report them as tickets here: http://cldwalker.lighthouseapp.com/projects/27735-hirb/tickets
+== Credits
+Chrononaut for vertical table helper.
+
+== Bugs/Issues
+Please report them {on github}[http://github.com/cldwalker/hirb/issues].
 
 == Links
 * http://tagaholic.me/2009/03/13/hirb-irb-on-the-good-stuff.html
 * http://tagaholic.me/2009/03/18/ruby-class-trees-rails-plugin-trees-with-hirb.html
+* http://tagaholic.me/2009/06/19/page-irb-output-and-improve-ri-with-hirb.html
 
 == Todo
-* Configurable max height, which if exceeded activates a pager.
-* Possibly add non-view irb goodies ie command manager.
 * Consider applying multiple views/filters to output.
+* Consider mapping a class' methods to their own views.
 * Provides helper methods to all view classes.
 * Consider adding a template system as needed.

data/Rakefile

@@ -18,11 +18,12 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |s|
     s.name = "hirb"
-    s.description = "A mini view framework for console/irb that's easy to use, even while under its influence."
-    s.summary = s.description
+    s.summary = "A mini view framework for console/irb that's easy to use, even while under its influence."
+    s.description = "Hirb currently provides a mini view framework for console applications, designed to improve irb's default output.  Hirb improves console output by providing a smart pager and auto-formatting output. The smart pager detects when an output exceeds a screenful and thus only pages output as needed. Auto-formatting adds a view to an output's class. This is helpful in separating views from content (MVC anyone?). The framework encourages reusing views by letting you package them in classes and associate them with any number of output classes."
     s.email = "gabriel.horner@gmail.com"
     s.homepage = "http://github.com/cldwalker/hirb"
     s.authors = ["Gabriel Horner"]
+    s.rubyforge_project = 'tagaholic'
     s.has_rdoc = true
     s.extra_rdoc_files = ["README.rdoc", "LICENSE.txt"]
     s.files = FileList["[A-Z]*", "{bin,lib,test}/**/*"]

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
-:minor: 1
+:minor: 2
 :patch: 2

data/lib/hirb.rb

@@ -6,19 +6,44 @@ require 'hirb/helpers'
 require 'hirb/view'
 require 'hirb/views/activerecord_base'
 require 'hirb/console'
+require 'hirb/formatter'
+require 'hirb/pager'
+require 'hirb/menu'
 
 # Most of Hirb's functionality currently resides in Hirb::View.
-# Hirb has an optional yaml config file defined by config_file. This config file
+# For an in-depth tutorial on creating and configuring views see Hirb::Formatter.
+# Hirb has an optional yaml config file defined by config_file(). This config file
 # has the following top level keys:
-# [:view] See Hirb::View for the value of this entry.
+# [:output] This hash is used by the formatter object. See Hirb::Formatter.config for its format.
+# [:width]  Width of the terminal/console. Defaults to DEFAULT_WIDTH or possibly autodetected when Hirb is enabled.
+# [:height]  Height of the terminal/console. Defaults to 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.
+#
+
 module Hirb
   class <<self
+    # Enables view functionality. See Hirb::View.enable for details.
+    def enable(options={}, &block)
+      View.enable(options, &block)
+    end
+
+    # Disables view functionality. See Hirb::View.disable for details.
+    def disable
+      View.disable
+    end
     # Default is config/hirb.yml or ~/hirb.yml in that order.
     def config_file
-      File.exists?('config/hirb.yml') ? 'config/hirb.yml' : File.expand_path(File.join("~",".hirb.yml"))
+      @config_file ||= File.exists?('config/hirb.yml') ? 'config/hirb.yml' : File.expand_path(File.join(ENV["HOME"],".hirb.yml"))
     end
 
     #:stopdoc:
+    def config_file=(value)
+      @config_file = value
+    end
+
     def read_config_file(file=config_file)
       File.exists?(file) ? YAML::load_file(file) : {}
     end

data/lib/hirb/console.rb

@@ -1,17 +1,43 @@
 module Hirb
-  # This class is meant to be extended to provide methods for use in a console/irb shell.
+  # This module is meant to be extended to provide methods for use in a console/irb shell.
   # For example:
   #    irb>> extend Hirb::Console
   #    irb>> view 'some string', :class=>Some::String::Formatter
   #    irb>> 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={})
-      Hirb::View.console_render_output(output, options.merge(:class=>"Hirb::Helpers::AutoTable"))
+      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 any specified view for the given object. Takes same options as Hirb::View.console_render_output.
-    def view(*args)
-      Hirb::View.console_render_output(*args)
+
+    # 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/formatter.rb

@@ -0,0 +1,199 @@
+module Hirb
+=begin rdoc
+  This class is format an output into a string using Hirb::Helpers::*, Hirb::Views::* or any user-created views.
+  The formatter object looks for an output's class config in Hirb::Formatter.config and if found applies a helper to the output.
+
+  == Create and Configure Views
+  Let's create a simple view and configure it in different ways to be Hash's default view:
+
+  === Setup
+    irb>> require 'hirb'
+    =>true
+    irb>> Hirb.enable
+    =>nil
+    irb>> require 'yaml'
+    =>true
+
+  === Configure As View Method
+  A view method is the smallest reuseable view.
+    # Create yaml view method
+    irb>> def yaml(output); output.to_yaml; end
+    =>nil
+
+    # Configure view
+    irb>>Hirb::View.format_class Hash, :method=>:yaml
+    =>true
+
+    # Hashes now appear as yaml
+    irb>>{:a=>1, :b=>{:c=>3}}
+    ---
+    :a : 1
+    :b : 
+      :c : 3
+    => true
+
+  === Configure As View Class
+  A view class is suited for more complex views. View classes can be under any namespace
+  and are expected to provide a render method. However, if a class is under the Hirb::Views namespace,
+  it will be automatically loaded with no configuration. Something to think about when
+  sharing views with others.
+
+    # Create yaml view class
+    irb>> class Hirb::Views::Hash; def self.render(output, options={}); output.to_yaml; end ;end
+    =>nil
+    # Just reload since no configuration is necessary
+    irb>>Hirb::View.formatter.reload
+
+    # Hashes now appear as yaml ...
+
+  Although the Hirb::Views namespace is great for quick classes that just plug and play, you
+  often want view classes that can be reused with multiple outputs. For this case, it's recommended to
+  use the Hirb::Helpers namespace.
+
+    # Create yaml view class
+    irb>> class Hirb::Helpers::Yaml; def self.render(output, options={}); output.to_yaml; end ;end
+    =>nil
+
+    # Configure view and reload it
+    irb>>Hirb::View.format_class Hash, :class=>"Hirb::Helpers::Yaml"
+    =>true
+
+    # Hashes now appear as yaml ...
+
+    == Configure At Startup
+    Once you know what views are associated with what output classes, you can configure
+    them at startup by passing Hirb.enable an options hash:
+      # In .irbrc
+      require 'hirb'
+      # View class needs to come before enable()
+      class Hirb::Helpers::Yaml; def self.render(output, options={}); output.to_yaml; end ;end
+      Hirb.enable :output=>{"Hash"=>{:class=>"Hirb::Helpers::Yaml"}}
+
+    Or by creating a config file at config/hirb.yml or ~/.hirb.yml:
+      # The config file for the yaml example would look like:
+      # ---
+      # :output :
+      #   Hash :
+      #    :class : Hirb::Helpers::Yaml
+
+      # In .irbrc
+      require 'hirb'
+      # View class needs to come before enable()
+      class Hirb::Helpers::Yaml; def self.render(output, options={}); output.to_yaml; end ;end
+      Hirb.enable
+=end 
+  
+  class Formatter
+    def initialize(additional_config={})
+      @klass_config = {}
+      @config = Util.recursive_hash_merge default_config, additional_config || {}
+    end
+
+    # A hash of Ruby class strings mapped to helper config hashes. A helper config hash must have at least a :method, :output_method
+    # or :class option for a helper to be applied to an output. A helper config 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}}
+    def config
+      @config
+    end
+
+    # Sets the helper config for the given output class.
+    def format_class(klass, helper_config)
+      @klass_config.delete(klass)
+      @config[klass.to_s] = helper_config
+      true
+    end
+
+    # Reloads autodetected Hirb::Views
+    def reload
+      @config = Util.recursive_hash_merge default_config, @config
+    end
+
+    # This is the main method of this class. The formatter looks for the first helper in its config for the given output class.
+    # If a helper is found, the output is converted by the helper into a string and returned. If not, nil is returned. The options
+    # this class takes are a helper config hash as described in config. These options will be merged with any existing helper config hash
+    # an output class has in 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)
+      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]
+        new_output = send(options[:method],*args)
+      elsif options[:class] && (helper_class = determine_helper_class(options[:class]))
+        new_output = helper_class.render(*args, &block)
+      elsif options[:output_method]
+        new_output = output
+      end
+      new_output
+    end
+
+    #:stopdoc:
+    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
+      real_options
+    end
+
+    def determine_helper_class(klass)
+      if klass.is_a?(Symbol) && (helper_class = Helpers.constants.find {|e| e == Util.camelize(klass.to_s)})
+        klass = "Hirb::Helpers::#{helper_class}"
+      end
+      Util.any_const_get(klass)
+    end
+
+    def determine_output_class(output)
+      if output.is_a?(Array)
+        output[0].class
+      else
+        output.class
+      end
+    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] ||= begin
+        output_ancestors_with_config = output_class.ancestors.map {|e| e.to_s}.select {|e| @config.has_key?(e)}
+        @klass_config[output_class] = output_ancestors_with_config.reverse.inject({}) {|h, klass|
+          (klass == output_class.to_s || @config[klass][:ancestor]) ? h.update(@config[klass]) : h
+        }
+      end
+    end
+
+    def reset_klass_config
+      @klass_config = {}
+    end
+
+    def default_config
+      Views.constants.inject({}) {|h,e|
+        output_class = e.to_s.gsub("_", "::")
+        if (views_class = 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