Chrononaut-hirb 0.2.1

data/CHANGELOG.rdoc

@@ -0,0 +1,19 @@
+== 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.
+
+== 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,164 @@
+== 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.  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. Hirb also sports a nice selection menu, Hirb::Menu.
+
+== Install
+
+Install the gem with:
+
+    sudo gem install cldwalker-hirb --source http://gems.github.com
+
+== 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.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.formatter_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.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.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 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:
+
+  # 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=>: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:
+  # 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=>: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.
+  irb>> :blah
+  =>:blah
+
+  # Go back to printing Hirb views to STDOUT.
+  irb>> Hirb::View.reset_render_method
+
+== 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
+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/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
+* 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

@@ -0,0 +1,50 @@
+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.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}/**/*"]
+  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 @@
+--- 
+:patch: 2
+:major: 0
+:minor: 2

data/lib/hirb.rb

@@ -0,0 +1,56 @@
+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'
+require 'hirb/formatter'
+require 'hirb/pager'
+require 'hirb/menu'
+
+# Most of Hirb's functionality currently resides in Hirb::View.
+# 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:
+# [: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
+      @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
+
+    def config(reload=false)
+      @config = (@config.nil? || reload) ? read_config_file : @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:
+  #    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={})
+      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/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