Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 232 lines (186 sloc) 9.582 kB
35ac793 @cldwalker more docs, rakefile,license + readme
cldwalker authored
1 == Description
2
046f646 @cldwalker gemspec + tweaks
cldwalker authored
3 Hirb currently provides a mini view framework for console applications, designed with irb in mind.
37779ed @cldwalker readme tweak
cldwalker authored
4 Given the output of a console application, it renders a view if there is one configured, based on
5 the output's class. The framework encourages reusing views by letting you package them in classes
a2cb3ef @cldwalker changed filesystem tree to directory tree, fixed bug in directory tre…
cldwalker authored
6 and associate them with any number of output classes. Hirb comes with tree views (see
29d5c46 @cldwalker readme tweak
cldwalker authored
7 Hirb::Helpers::Tree) and table views (see Hirb::Helpers::Table). By default Hirb displays Rails'
8 model classes as tables.
35ac793 @cldwalker more docs, rakefile,license + readme
cldwalker authored
9
10 == Install
11
12 Install the gem with:
13
a2cb3ef @cldwalker changed filesystem tree to directory tree, fixed bug in directory tre…
cldwalker authored
14 sudo gem install cldwalker-hirb --source http://gems.github.com
35ac793 @cldwalker more docs, rakefile,license + readme
cldwalker authored
15
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
16 == Rails Example
35ac793 @cldwalker more docs, rakefile,license + readme
cldwalker authored
17
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
18 Let's load and enable the view framework:
19 bash> script/console
20 Loading local environment (Rails 2.2.2)
35ac793 @cldwalker more docs, rakefile,license + readme
cldwalker authored
21 irb>> require 'hirb'
22 => true
23 irb>> Hirb::View.enable
24 => nil
25
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
26 The default configuration provides table views for ActiveRecord::Base descendants.
27 If a class isn't configured, Hirb reverts to irb's default echo mode.
28 irb>> Hirb::View.output_config
29 => {"ActiveRecord::Base"=>{:class=>"Hirb::Views::ActiveRecord_Base", :ancestor=>true}}
30
31 # Tag is a model class and descendant of ActiveRecord::Base
32 irb>> Tag.last
33 +-----+-------------------------+-------------+---------------+-----------+-----------+-------+
34 | id | created_at | description | name | namespace | predicate | value |
35 +-----+-------------------------+-------------+---------------+-----------+-----------+-------+
36 | 907 | 2009-03-06 21:10:41 UTC | | gem:tags=yaml | gem | tags | yaml |
37 +-----+-------------------------+-------------+---------------+-----------+-----------+-------+
38 1 row in set
39
40 irb>> 'plain ol irb'
41 => 'plain ol irb'
42 irb>> :blah
43 => :blah
44
45 From above you can see there were no views configured for a String or a Symbol so Hirb defaulted to
46 irb's echo mode. Also note that Tag was able to inherit its view from the ActiveRecord::Base config
47 because it had an :ancestor option.
48
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
49 Now that you understand that Hirb displays views based on an output object's class,
50 you may appreciate it also detects configured output objects in an array:
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
51
52 irb>> Tag.all :limit=>3, :order=>"id DESC"
53 +-----+-------------------------+-------------+-------------------+-----------+-----------+----------+
54 | id | created_at | description | name | namespace | predicate | value |
55 +-----+-------------------------+-------------+-------------------+-----------+-----------+----------+
56 | 907 | 2009-03-06 21:10:41 UTC | | gem:tags=yaml | gem | tags | yaml |
57 | 906 | 2009-03-06 08:47:04 UTC | | gem:tags=nomonkey | gem | tags | nomonkey |
58 | 905 | 2009-03-04 00:30:10 UTC | | article:tags=ruby | article | tags | ruby |
59 +-----+-------------------------+-------------+-------------------+-----------+-----------+----------+
60 3 rows in set
61
62 At any time you can disable Hirb if you really like irb's lovely echo mode:
63 irb>> Hirb::View.disable
35ac793 @cldwalker more docs, rakefile,license + readme
cldwalker authored
64 => nil
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
65 irb>> Tag.all :limit=>3, :order=>"id DESC"
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
66 => [#<Tag id: 907, name: "gem:tags=yaml", description: nil, created_at: "2009-03-06 21:10:41",
67 namespace: "gem", predicate: "tags", value: "yaml">, #<Tag id: 906, name: "gem:tags=nomonkey",
68 description: nil, created_at: "2009-03-06 08:47:04", namespace: "gem", predicate: "tags", value:
69 "nomonkey">, #<Tag id: 905, name: "article:tags=ruby", description: nil, created_at: "2009-03-04
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
70 00:30:10", namespace: "article", predicate: "tags", value: "ruby">]
71
72 == Views: Anytime, Anywhere
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
73 While preconfigured tables are great for database records, sometimes you just want to create
74 tables/views for any output object:
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
75
76 #These examples don't need to have Hirb::View enabled.
77 irb>>Hirb::View.disable
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
78 =>nil
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
79
80 # Imports table() and view()
81 irb>>extend Hirb::Console
82 =>main
83
84 # Create a table of Dates comparing them with different formats.
85 irb>> table [Date.today, Date.today.next_month], :fields=>[:to_s, :ld, :ajd, :amjd, :asctime]
86 +------------+--------+-----------+-------+--------------------------+
87 | to_s | ld | ajd | amjd | asctime |
88 +------------+--------+-----------+-------+--------------------------+
89 | 2009-03-11 | 155742 | 4909803/2 | 54901 | Wed Mar 11 00:00:00 2009 |
90 | 2009-04-11 | 155773 | 4909865/2 | 54932 | Sat Apr 11 00:00:00 2009 |
91 +------------+--------+-----------+-------+--------------------------+
92 2 rows in set
93
94 # Same table as the previous method. However view() will be able to call any view created.
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
95 irb>> view [Date.today, Date.today.next_month], :class=>Hirb::Helpers::ObjectTable,
96 :fields=>[:to_s, :ld, :ajd, :amjd, :asctime]
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
97
98 If these console methods weren't convenient enough, try:
99
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
100 # Imports view() to all objects.
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
101 irb>> require 'hirb/import_object'
102 =>true
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
103 # Yields same table as above examples.
104 irb>> [Date.today, Date.today.next_month].view :class=>Hirb::Helpers::ObjectTable,
105 :fields=>[:to_s, :ld, :ajd, :amjd, :asctime]
106
107 Although views by default are printed to STDOUT, they can be easily modified to write anywhere:
108 # Setup views to write to file 'console.log'.
109 irb>> Hirb::View.render_method = lambda {|output| File.open("console.log", 'w') {|f| f.write(output) } }
110
111 # Writes to file with same table output as above example.
112 irb>> view [Date.today, Date.today.next_month], :class=>Hirb::Helpers::ObjectTable,
113 :fields=>[:to_s, :ld, :ajd, :amjd, :asctime]
114
115 # Doesn't write to file because Symbol isn't configured to use Hirb::View and thus defaults to irb's echo mode.
116 irb>> :blah
117 =>:blah
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
118
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
119 # Go back to printing Hirb views to STDOUT.
120 irb>> Hirb::View.reset_render_method
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
121
122 == Create and Configure Views
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
123 Let's create a simple view and configure it in different ways to be Hash's default view:
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
124
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
125 === Setup
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
126 irb>> require 'hirb'
127 =>true
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
128 irb>> Hirb::View.enable
129 =>nil
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
130 irb>> require 'yaml'
131 =>true
132
133 === Configure As View Method
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
134 A view method is the smallest reuseable view.
135 # Create yaml view method
136 irb>> def yaml(output); output.to_yaml; end
137 =>nil
138
139 # Configure view and reload it
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
140 irb>>Hirb::View.output_config = {"Hash"=>{:method=>:yaml}}
141 =>{"Hash"=>{:method=>:yaml}}
142 irb>>Hash::View.reload_config
143 =>true
144
145 # Hashes now appear as yaml
146 irb>>{:a=>1, :b=>{:c=>3}}
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
147 ---
148 :a : 1
149 :b :
150 :c : 3
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
151 => true
152
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
153 === Configure As View Class
154 A view class is suited for more complex views. View classes can be under any namespace
155 and are expected to provide a render method. However, if a class is under the Hirb::Views namespace,
156 it will be automatically loaded with no configuration. Something to think about when
157 sharing views with others.
158
159 # Create yaml view class
12bcf1e @cldwalker doc tweaks and table tweak
cldwalker authored
160 irb>> class Hirb::Views::Hash; def self.render(output, options={}); output.to_yaml; end ;end
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
161 =>nil
162 # Just reload since no configuration is necessary
163 irb>>Hirb::View.reload_config
164
165 # Hashes now appear as yaml ...
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
166
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
167 Although the Hirb::Views namespace is great for quick classes that just plug and play, you
168 often want view classes that can be reused with multiple outputs. For this case, it's recommended to
169 use the Hirb::Helpers namespace.
170
171 # Create yaml view class
12bcf1e @cldwalker doc tweaks and table tweak
cldwalker authored
172 irb>> class Hirb::Helpers::Yaml; def self.render(output, options={}); output.to_yaml; end ;end
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
173 =>nil
174
175 # Configure view and reload it
176 irb>>Hirb::View.output_config = {"Hash"=>{:class=>"Hirb::Helpers::Yaml"}}
177 =>{"Hash"=>{:class=>"Hirb::Helpers::Yaml"}}
178 irb>>Hirb::View.reload_config
179
180 # Hashes now appear as yaml ...
181
182 === Configure At Startup
046f646 @cldwalker gemspec + tweaks
cldwalker authored
183 Once you know what views are associated with what output classes, you can configure
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
184 them at startup by passing Hirb::View.enable a block:
185 # In .irbrc
186 require 'hirb'
187 # View class needs to come before enable()
12bcf1e @cldwalker doc tweaks and table tweak
cldwalker authored
188 class Hirb::Helpers::Yaml; def self.render(output, options={}); output.to_yaml; end ;end
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
189 Hirb::View.enable {|conf| conf.output = {"Hash"=>{:class=>"Hirb::Helpers::Yaml"}} }
190
191 Or by creating a config file at config/hirb.yml or ~/.hirb.yml:
192 # The config file for the yaml example would look like:
193 # ---
194 # :view :
195 # :output :
196 # Hash :
197 # :class : Hirb::Helpers::Yaml
198
199 # In .irbrc
200 require 'hirb'
201 # View class needs to come before enable()
12bcf1e @cldwalker doc tweaks and table tweak
cldwalker authored
202 class Hirb::Helpers::Yaml; def self.render(output, options={}); output.to_yaml; end ;end
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
203 Hirb::View.enable
204
12bcf1e @cldwalker doc tweaks and table tweak
cldwalker authored
205 == Contributing Views
206 If you have views of your own you'd like to share, fork Hirb and put your views under
207 the Hirb::Helpers namespace and the view files under lib/hirb/helpers/.
208
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
209 == Limitations
210 Although Hirb preserves Wirble colorizing irb's default echo mode, it doesn't colorize its own views.
211 This is mainly because colorizing caused table classes to render incorrectly. If you can get tables
212 and colors to work nicely, please fork. To colorize your Hirb output:
213 Hirb::View.render_method = lambda {|output| puts Wirble::Colorize.colorize(output) }
35ac793 @cldwalker more docs, rakefile,license + readme
cldwalker authored
214
8535d1b @cldwalker readme tweak
cldwalker authored
215 == Motivation
216 Table code from http://gist.github.com/72234 and {my console
a2cb3ef @cldwalker changed filesystem tree to directory tree, fixed bug in directory tre…
cldwalker authored
217 app's needs}[http://github.com/cldwalker/tag-tree].
8535d1b @cldwalker readme tweak
cldwalker authored
218
6a7ec42 @cldwalker added bugs/tickets link
cldwalker authored
219 == Bugs
220 Please report them as tickets here: http://cldwalker.lighthouseapp.com/projects/27735-hirb/tickets
221
37779ed @cldwalker readme tweak
cldwalker authored
222 == Links
223 * http://tagaholic.me/2009/03/13/hirb-irb-on-the-good-stuff.html
91584ff @cldwalker some doc tweaks
cldwalker authored
224 * http://tagaholic.me/2009/03/18/ruby-class-trees-rails-plugin-trees-with-hirb.html
37779ed @cldwalker readme tweak
cldwalker authored
225
42fbcc4 @cldwalker decent readme, more tweaks + tests
cldwalker authored
226 == Todo
80a9f67 @cldwalker readme tweak
cldwalker authored
227 * Configurable max height, which if exceeded activates a pager.
a2cb3ef @cldwalker changed filesystem tree to directory tree, fixed bug in directory tre…
cldwalker authored
228 * Possibly add non-view irb goodies ie command manager.
229 * Consider applying multiple views/filters to output.
1bfd96b @cldwalker more docs + reset_render_method
cldwalker authored
230 * Provides helper methods to all view classes.
231 * Consider adding a template system as needed.
Something went wrong with that request. Please try again.