cldwalker / hirb

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 hirb

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.

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 gist.github.com/72234 and my console app's needs.

Credits

• Chrononaut for vertical table helper.
• crafterm, spastorino, xaviershay and joshua for bug fixes.

Bugs/Issues

Please report them on github.

Links

• tagaholic.me/2009/03/13/hirb-irb-on-the-good-stuff.html
• tagaholic.me/2009/03/18/ruby-class-trees-rails-plugin-trees-with-hirb.html
• 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.