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 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].

== 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

• 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.