hirb 0.1.2

data/CHANGELOG.rdoc

@@ -0,0 +1,9 @@
+== 0.1.2
+* Added tree views.
+* Added output_method option to Hirb::View.render_output.
+
+== 0.1.1
+* Fixed bug when rendering table with many fields.
+
+== 0.1.0
+* Initial release

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT LICENSE
+
+Copyright (c) 2009 Gabriel Horner
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,231 @@
+== 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::Helpers::Tree) and table views (see Hirb::Helpers::Table). By default Hirb displays Rails'
+model classes as tables.
+
+== Install
+
+Install the gem with:
+
+    sudo gem install cldwalker-hirb --source http://gems.github.com
+
+== Rails 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
+  => 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
+  => {"ActiveRecord::Base"=>{:class=>"Hirb::Views::ActiveRecord_Base", :ancestor=>true}}
+
+  # Tag is a model class and descendant of ActiveRecord::Base
+  irb>> Tag.last
+  +-----+-------------------------+-------------+---------------+-----------+-----------+-------+
+  | id  | created_at              | description | name          | namespace | predicate | value |
+  +-----+-------------------------+-------------+---------------+-----------+-----------+-------+
+  | 907 | 2009-03-06 21:10:41 UTC |             | gem:tags=yaml | gem       | tags      | yaml  |
+  +-----+-------------------------+-------------+---------------+-----------+-----------+-------+
+  1 row in set
+
+  irb>> 'plain ol irb'
+  => 'plain ol irb'
+  irb>> :blah
+  => :blah
+
+From above you can see there were no views configured for a String or a Symbol so Hirb defaulted to
+irb's echo mode. Also note that Tag was able to inherit its view from the ActiveRecord::Base config
+because it had an :ancestor option.
+
+Now that you understand that Hirb displays views based on an output object's class,
+you may appreciate it also detects configured output objects in an array:
+
+  irb>> Tag.all :limit=>3, :order=>"id DESC"
+  +-----+-------------------------+-------------+-------------------+-----------+-----------+----------+
+  | id  | created_at              | description | name              | namespace | predicate | value    |
+  +-----+-------------------------+-------------+-------------------+-----------+-----------+----------+
+  | 907 | 2009-03-06 21:10:41 UTC |             | gem:tags=yaml     | gem       | tags      | yaml     |
+  | 906 | 2009-03-06 08:47:04 UTC |             | gem:tags=nomonkey | gem       | tags      | nomonkey |
+  | 905 | 2009-03-04 00:30:10 UTC |             | article:tags=ruby | article   | tags      | ruby     |
+  +-----+-------------------------+-------------+-------------------+-----------+-----------+----------+
+  3 rows in set
+
+At any time you can disable Hirb if you really like irb's lovely echo mode:
+  irb>> Hirb::View.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",
+  namespace: "gem", predicate: "tags", value: "yaml">, #<Tag id: 906, name: "gem:tags=nomonkey",
+  description: nil, created_at: "2009-03-06 08:47:04", namespace: "gem", predicate: "tags", value:
+  "nomonkey">, #<Tag id: 905, name: "article:tags=ruby", description: nil, created_at: "2009-03-04
+  00:30:10", namespace: "article", predicate: "tags", value: "ruby">]
+
+== Views: Anytime, Anywhere
+While preconfigured tables are great for database records, sometimes you just want to create
+tables/views for any output object:
+  
+  #These examples don't need to have Hirb::View enabled.
+  irb>>Hirb::View.disable
+  =>nil
+
+  # Imports table() and view()
+  irb>>extend Hirb::Console
+  =>main
+
+  # Create a table of Dates comparing them with different formats.
+  irb>> table [Date.today, Date.today.next_month], :fields=>[:to_s, :ld, :ajd, :amjd, :asctime]
+  +------------+--------+-----------+-------+--------------------------+
+  | to_s       | ld     | ajd       | amjd  | asctime                  |
+  +------------+--------+-----------+-------+--------------------------+
+  | 2009-03-11 | 155742 | 4909803/2 | 54901 | Wed Mar 11 00:00:00 2009 |
+  | 2009-04-11 | 155773 | 4909865/2 | 54932 | Sat Apr 11 00:00:00 2009 |
+  +------------+--------+-----------+-------+--------------------------+
+  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,
+    :fields=>[:to_s, :ld, :ajd, :amjd, :asctime]
+
+If these console methods weren't convenient enough, try:
+
+  # Imports view() to all objects.
+  irb>> require 'hirb/import_object'
+  =>true
+  # Yields same table as above examples.
+  irb>> [Date.today, Date.today.next_month].view :class=>Hirb::Helpers::ObjectTable,
+    :fields=>[:to_s, :ld, :ajd, :amjd, :asctime]
+
+Although views by default are printed to STDOUT, they can be easily modified to write anywhere:
+  # Setup views to write to file 'console.log'.
+  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,
+    :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.
+  irb>> :blah
+  =>:blah
+
+  # 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/.
+
+== 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) }
+
+== 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
+
+== 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
+
+== 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.
+* Provides helper methods to all view classes.
+* Consider adding a template system as needed.

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+begin
+  require 'rcov/rcovtask'
+
+  Rcov::RcovTask.new do |t|
+    t.libs << 'test'
+    t.test_files = FileList['test/**/*_test.rb']
+    t.rcov_opts = ["-T -x '/Library/Ruby/*'"]
+    t.verbose = true
+  end
+rescue LoadError
+  puts "Rcov not available. Install it for rcov-related tasks with: sudo gem install rcov"
+end
+
+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.email = "gabriel.horner@gmail.com"
+    s.homepage = "http://github.com/cldwalker/hirb"
+    s.authors = ["Gabriel Horner"]
+    s.has_rdoc = true
+    s.extra_rdoc_files = ["README.rdoc", "LICENSE.txt"]
+    s.files = FileList["[A-Z]*", "{bin,lib,test}/**/*"]
+  end
+
+rescue LoadError
+  puts "Jeweler not available. Install it for jeweler-related tasks with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'test'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :default => :test

data/VERSION.yml

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

data/lib/hirb.rb

@@ -0,0 +1,31 @@
+current_dir = File.dirname(__FILE__)
+$:.unshift(current_dir) unless $:.include?(current_dir) || $:.include?(File.expand_path(current_dir))
+require 'hirb/util'
+require 'hirb/hash_struct'
+require 'hirb/helpers'
+require 'hirb/view'
+require 'hirb/views/activerecord_base'
+require 'hirb/console'
+
+# Most of Hirb's functionality currently resides in Hirb::View.
+# 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.
+module Hirb
+  class <<self
+    # 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"))
+    end
+
+    #:stopdoc:
+    def read_config_file(file=config_file)
+      File.exists?(file) ? YAML::load_file(file) : {}
+    end
+
+    def config(reload=false)
+      @config = (@config.nil? || reload) ? read_config_file : @config
+    end
+    #:startdoc:
+  end
+end

data/lib/hirb/console.rb

@@ -0,0 +1,17 @@
+module Hirb
+  # This class 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
+    # 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"))
+    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)
+    end
+  end
+end

data/lib/hirb/hash_struct.rb

@@ -0,0 +1,17 @@
+require 'ostruct'
+
+class Hirb::HashStruct < OpenStruct #:nodoc:
+  def self.block_to_hash(block=nil)
+    config = self.new
+    if block
+      block.call(config)
+      config.to_hash
+    else
+      {}
+    end
+  end
+
+  def to_hash
+    @table
+  end
+end

data/lib/hirb/helpers.rb

@@ -0,0 +1,7 @@
+module Hirb
+  module Helpers #:nodoc:
+  end
+end
+%w{table object_table active_record_table auto_table tree parent_child_tree}.each do |e|
+  require "hirb/helpers/#{e}"
+end

data/lib/hirb/helpers/active_record_table.rb

@@ -0,0 +1,17 @@
+class Hirb::Helpers::ActiveRecordTable < Hirb::Helpers::ObjectTable
+  # Rows are Rails' ActiveRecord::Base objects.
+  # Takes same options as Hirb::Helpers::Table.render except as noted below.
+  #
+  # Options:
+  #   :fields- Can be any attribute, column or not. If not given, this defaults to the database table's columns.
+  def self.render(rows, options={})
+    rows = [rows] unless rows.is_a?(Array)
+    options[:fields] ||= 
+      begin
+        fields = rows.first.attribute_names
+        fields.unshift(fields.delete('id')) if fields.include?('id')
+        fields.map {|e| e.to_sym }
+      end
+    super(rows, options)
+  end
+end

data/lib/hirb/helpers/auto_table.rb

@@ -0,0 +1,14 @@
+# Attempts to autodetect the table class the output represents and delegates rendering to it.
+class Hirb::Helpers::AutoTable
+  # Same options as Hirb::Helpers::Table.render.
+  def self.render(output, options={})
+    klass = if ((output.is_a?(Array) && output[0].is_a?(ActiveRecord::Base)) or output.is_a?(ActiveRecord::Base) rescue false)
+      Hirb::Helpers::ActiveRecordTable
+    elsif options[:fields]
+      Hirb::Helpers::ObjectTable
+    else
+      Hirb::Helpers::Table
+    end
+    klass.render(output, options)
+  end
+end

data/lib/hirb/helpers/object_table.rb

@@ -0,0 +1,15 @@
+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 which are represented as columns in the table. Required option.
+  #     All method values are converted to strings via to_s.
+  def self.render(rows, options ={})
+    raise(ArgumentError, "Option 'fields' is required.") unless options[:fields]
+    rows = [rows] unless rows.is_a?(Array)
+    item_hashes = rows.inject([]) {|t,item|
+      t << options[:fields].inject({}) {|h,f| h[f] = item.send(f).to_s; h}
+    }
+    super(item_hashes, options)
+  end
+end