/hirb

A mini view framework for console/irb that's easy to use, even while under its influence. Console goodies include a no-wrap table, auto-pager, tree and menu.

Primary LanguageRubyMIT LicenseMIT

To read a linked version of this README, click here.

Description

Hirb provides a mini view framework for console applications and uses it to improve ripl(irb)‘s default inspect output. Given an object or array of objects, hirb renders a view based on the object’s class and/or ancestry. Hirb offers reusable views in the form of helper classes. The two main helpers, Hirb::Helpers::Table and Hirb::Helpers::Tree, provide several options for generating ascii tables and trees. Using Hirb::Helpers::AutoTable, hirb has useful default views for at least ten popular database gems i.e. Rails’ ActiveRecord::Base. Other than views, hirb offers a smart pager and a console menu. The smart pager only pages when the output exceeds the current screen size. The menu is used in conjunction with tables to offer two dimensional menus.

Install

Install the gem with:

gem install hirb

For people using full-width unicode characters, install hirb-unicode:

gem install hirb-unicode

View Tutorials

Printing Ascii Tables

To print ascii tables from an array of arrays, hashes or any objects:

puts Hirb::Helpers::AutoTable.render(ARRAY_OF_OBJECTS)

Hirb will intelligently pick up on field names from an array of hashes and create properly-aligned fields from an array of arrays. See here for examples.

Rails Example

Let’s load and enable the view framework:

$ rails console
Loading local environment (Rails 3.0.3)
>> require 'hirb'
=> true
>> 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.

>> Hirb::Formatter.dynamic_config['ActiveRecord::Base']
=> {:class=>Hirb::Helpers::AutoTable, :ancestor=>true}

# Tag is a model class and descendant of ActiveRecord::Base
>> 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

>> Hirb::Formatter.dynamic_config['String']
=> nil
>> 'plain ol irb'
=> 'plain ol irb'
>> Hirb::Formatter.dynamic_config['Symbol']
=> nil
>> :blah
=> :blah

From above you can see there are no views configured for a String or a Symbol so Hirb defaults to irb’s echo mode. On the other hand, Tag has a view thanks to being a descendant of ActiveRecord::Base and there being an :ancestor option.

Having seen hirb display views based on an output object’s class, let’s see it handle an array of objects:

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

>> Hirb.disable
=> nil
>> 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.
>> Hirb.disable
=> nil

# Imports table() and view()
>> extend Hirb::Console
=> main

# Create a unicode table
>> table [[:a, :b, :c]], :unicode => true
┌───┬───┬───┐
│ 0 │ 1 │ 2 │
├───┼───┼───┤
│ a ╎ b ╎ c │
└───┴───┴───┘
1 row in set

# Creates github-markdown
>> table [[:a, :b, :c]], :markdown => true
| 0 | 1 | 2 |
|---|---|---|
| a | b | c |

# Create a table of Dates comparing them with different formats.
>> 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.
>> 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.
>> require 'hirb/import_object'
=> true
# Yields same table as above examples.
>> [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'.
>> 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.
>> view [Date.today, Date.today.next_month], :class=>:object_table,
  :fields=>[:to_s, :ld, :ajd, :amjd, :asctime]

# Doesn't write to file because Symbol doesn't have a view and thus defaults to irb's echo mode.
>> :blah
=> :blah

# Go back to printing Hirb views to STDOUT.
>> Hirb::View.reset_render_method

Pager

Hirb has both pager and formatter functionality enabled by default. Note - if you copy and paste into your ruby console and think that one of your lines will kick off the pager, be aware that subsequent characters will go to your pager and could cause side effects like saving a file.

If you want to turn off the functionality of either pager or formatter, 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

Sharing Helpers and Views

If you have tested helpers you’d like to share, fork Hirb and put them under lib/hirb/helpers. To share views for certain classes, put them under lib/hirb/views. Please submit views for gems that have a nontrivial number of users.

Limitations

If using Wirble and irb, 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.

  • janlelis for unicode table helper.

  • technogeeky and FND for markdown table helper.

  • hsume2, crafterm, spastorino, xaviershay, bogdan, asanghi, vwall, maxmeyer, jimjh, ddoherty03, rochefort and joshua for patches.

Bugs/Issues

Please report them on github.

Contributing

See here