Tagaholic - Posts tagged 'ruby'

Tux - A Sinatra Console

2011-04-10T00:00:00-07:00

While working on a sinatra app recently, I noticed that sinatra has no rails equivalent to rails console. So here’s tux, dressing your sinatra app in a console.

Install and Try On

  $ gem install tux

In the directory of your sinatra app, try on tux:

  $ tux

  # If app's rack config file isn't config.ru, specify it with -c
  $ tux -c app.ru

  # ruby options like -I and -r are available to tux
  $ tux -h
  Usage: tux [COMMAND] [ARGS] [OPTIONS]

  Options:
    -f                  Suppress loading ~/.irbrc
    -F                  Suppress loading ~/.riplrc
    -d, --debug         Set $DEBUG to true (same as `ruby -d')
    -I PATH             Add to front of $LOAD_PATH. Delimit multiple paths with ':'
    -r, --require FILE  Require file (same as `ruby -r')
    -v, --version       Print version
    -h, --help          Print help
    -c, --config FILE   Set rack config file i.e. config.ru

Interact with App Methods

Tux provides the app object to interact with your app’s methods. For example, to interact with helpers:

  >> app.my_helper_method
  ...

Since app is an instance of Sintra::Base, it can interact with any built-in sinatra methods i.e. request and response specific helper methods:

  # depends on request
  >> app.uri '/'
  => "http://:/"

  # depends on response
  >> app.headers
  => {"Content-Type"=>"text/html"}

For the above to work, tux sets up default empty request and response objects. To use custom requests and responses:

  >> app.request = Sinatra::Request.new({})
  => ...
  >> app.response = Sinatra::Response.new
  => ...

Last but not least, use app to interact with views:

  >> app.erb :my_template
  => 'template rendered'

  # also
  >> app.haml
  >> app.markdown
  ...

Interact with App Responses

Tux let’s you make requests using http verbs thanks to rack-test. Use them to interact with your app’s response objects:

  >> get '/'
  => #<\Rack::MockResponse:0x13d452c @headers={"Content-Type"=>"text/html;charset=utf-8",
  "Content-Length"=>"4"}, @errors="127.0.0.1 - - [05/Apr/2011 02:22:27] \"GET / \" 200 4
  0.0015\n", @status=200, @original_headers={"Content-Type"=>"text/html;charset=utf-8",
  "Content-Length"=>"4"}, @body="dude">

  >> _.headers
  => {"Content-Type"=>"text/html;charset=utf-8", "Content-Length"=>"4"}

  # last_response saves the response of your last request
  >> puts last_response.body
  dude

  >> post '/create', :user => 'cow', :password => 'abunga'
  ...

All http verb methods can take optional params and request headers as rack-test reveals. To see the full list of rack-test actions you can make:

  >> rack.actions
  => [:request, :get, :post, :put, :delete, :head, :follow_redirect!, :header, :set_cookie,
  :clear_cookies, :authorize, :basic_authorize, :digest_authorize, :last_response, :last_request]

Commands and Configuration

Tux comes with commands to give you a good overview of your app:

  # Displays routes defined by HTTP verb and order they were defined
  >> routes
  HEAD  "/"
  HEAD  "/book/:id"
  GET   "/"
  GET   "/book/:id"

  # Displays app settings configured via sinatra's #set method
  >> settings
  absolute_redirects  true
  add_charset         [/^text\//, "application/javascript", "application/xml",
  "application/xhtml+xml"]
  app_file            "./sample.rb"
  bind                "0.0.0.0"
  default_encoding    "utf-8"
  dump_errors         true
  empty_path_info     nil
  environment         :development
  lock                false
  logging             false
  method_override     false
  port                4567
  prefixed_redirects  false
  public              "/my/path/public"
  raise_errors        false
  reload_templates    true
  root                "/my/path"
  run                 false
  running             false
  server              ["thin", "mongrel", "webrick"]
  session_secret      "XXX"
  sessions            false
  show_exceptions     true
  static              true
  views               "/my/path/views"

Since tux is a ripl shell, tux is highly configurable. You can create tux commands in the format tux-COMMAND and enhance your shell by adding ripl plugins to ~/.riplrc. Read ripl’s readme for more.

One9 - Upgrade to Ruby 1.9 Now

2011-03-05T00:00:00-08:00

So ruby 1.9.2 is the future and your still stuck on 1.8 at work. Why? It’s a pain … Well, let’s change that. Introducing one9 – a gem to find 1.9 method changes and make the upgrade process smoother.

Install

No surprises here.

  gem install one9

Well almost. If you’re using bundler (the default in rails3), add one9 to your Gemfile if your
tests are invoked by bundler i.e. one9 test, one9 test rake * or one9 test bundle exec *.

How it works

one9 runs your 1.8 test suite, spies on methods that have changed and saves the locations of their calls
for later viewing. If you have a supported editor, it drops into an editor to let you sequentially
view and possibly fix each change. Although one9 gives you a brief message for each change, I
recommend familiarizing yourself with 1.9 changes. To see what one9 knows about 1.9 changes:

  $ one9 changes
  +-----------------------------------+------------------------------------------------------------------+--------+
  | method                            | message                                                          | type   |
  +-----------------------------------+------------------------------------------------------------------+--------+
  | Module#constants                  | Returns array of symbols instead of array of strings             | change |
  | Module#public_methods             | Returns array of symbols instead of array of strings             | change |
  | Module#instance_methods           | Returns array of symbols instead of array of strings             | change |
  | Module#singleton_methods          | Returns array of symbols instead of array of strings             | change |
  | Module#public_instance_methods    | Returns array of symbols instead of array of strings             | change |
  | Module#protected_methods          | Returns array of symbols instead of array of strings             | change |
  ...

Run tests

First off, run your tests in the root directory of a gem or Rails app:

  # Runs `rake test` by default
  $ one9 test

  # To run any other test command, just prefix it with one9 test:
  # Run all cucumber specs
  $ one9 test cucumber

  # Only run model specs
  $ one9 test rspec spec/models

After your tests run, one9 prints a report. Here’s what it all looks like for boson:

  $ one9 test
  ...............................................................................................
  ...............................................................................................
  ...............................................................................................
  ...............
  Finished in 0.704555 seconds.

  300 tests, 580 assertions, 0 failures, 0 errors

  ** One9 Report **
  +---------------------------------+-------+--------------------------------------------------------------+--------+--------------------------------------------------------------+
  | method                          | count | message                                                      | type   | lines                                                        |
  +---------------------------------+-------+--------------------------------------------------------------+--------+--------------------------------------------------------------+
  | Module#instance_methods         | 5     | Returns array of symbols instead of array of strings         | change | lib/boson/util.rb:39:in `detect',lib/boson/util.rb:40:in ... |
  | Module#private_instance_methods | 2     | Returns array of symbols instead of array of strings         | change | lib/boson/inspectors/argument_inspector.rb:23:in `scrape_... |
  | Hash#to_s                       | 4     | An alias of #inspect instead of a spaceless join of the e... | change | lib/boson/loader.rb:87:in `initialize_library_module',lib... |
  | Hash#select                     | 4     | Returns a hash instead of an association array               | change | lib/boson/loader.rb:109:in `set_library_commands',lib/bos... |
  +---------------------------------+-------+--------------------------------------------------------------+--------+--------------------------------------------------------------+
  4 rows in set

As you can see the report lists changed methods, how many times they were
called and where they were called from. To reprint this list any time later, run one9 list.

Note: When you run one9 test it overwrites the previous one test result.

Edit Changes

Now that you have a list of changed method calls, editing those changes is easy:

  # Open all changes
  $ one9 edit

  # To only open a subset of changes:
  # Only open Hash changes
  $ one9 edit Hash

  # Only open Hash#to_s changes
  $ one9 edit Hash#to_s

Currently this opens the quickfix list in vim. (For vim noobs, navigate between changes with :cn
and :cp.) Patches for emacs and other editors welcome :)
Remember each change is a possible change. Only change the code if the new 1.9 behavior is going
to break the existing code.

For those without editing support, you can still view each line where there’s a method change:

  $ one9 lines
  +---------------------------------+---------------------------------------------------------------------+
  | method                          | line                                                                |
  +---------------------------------+---------------------------------------------------------------------+
  | Module#instance_methods         | lib/boson/util.rb:39:in `detect'                                    |
  | Module#instance_methods         | lib/boson/util.rb:40:in `detect'                                    |
  | Module#instance_methods         | lib/boson/loader.rb:101:in `check_for_method_conflicts'             |
  | Module#instance_methods         | lib/boson/util.rb:44:in `detect'                                    |
  | Module#instance_methods         | lib/boson/namespace.rb:28:in `boson_commands'                       |
  ...

Once you’ve fixed your changes, give your code a 1.9 test run. If tests are still broken, then jump
down to this section.

Rails Tips

Skip this section if you’re not on a Rails app.

So you’ve finished editing your code and tests pass. You’re done, right? Not in my opinion. My code
is only as good as the code it depends on. I’d check each of my app’s dependencies and check for any
1.9 breakages. For each gem:

1. cd to the gem: cd `bundle show $GEM`
2. Install the gem’s development dependencies: gem install $GEM --dev
3. Run tests with one9: one9 test WITH PROPER COMMAND
4. Edit gem’s changes : one9 edit
5. Verify tests pass on 1.9.
6. Fork, patch, pull as needed

Configure

one9 comes with a decent list of 1.9 changes and descriptions. If you’d like to add your
own changes, add them to your ~/.one9rc. For example:

  # For methods that have changed in 1.9
  change 'Class#instance_method', 'Some description'

  # For methods that have been deleted in 1.9
  delete 'Class.class_method', 'Some description'

For more examples, see the defaults that one9 defines. If I’ve missed an important 1.9 change, feel free to fork and pull.

Additional 1.9 Changes

So even if you’ve dealt with all changed methods, there are still other changes that could effect your code:

Encoding: Probably the most significant and thus well documented. See JEG’s thorough articles
scoping of block variables, splat operator and block arguments
files in $LOAD_PATH and $LOADED_FEATURES are expanded
using colon (:) instead of “then” in an if/unless/case is deprecated
retry in a loop or iterator is deprecated
$KCODE, $= and VERSION* constants are deprecated
?x now returns a single character string instead of an integer
For anything I may have missed see the official changelog or the unoffical one

Motivation

This gem aims to get the ruby community to seriously use 1.9.2 and to port as many of the 1.8 gems
to 1.9. Since this gem maintains a list of 1.9 changes, it could be used as a multi-purpose tool.
Some ideas for future commands:

grep command to grep code for changed methods. Basically for porting test-deprived code.
info command to explain a method’s change in detail with examples and possible solutions
rails command to ease porting a rails app and all its dependencies.
automating code changes like python’s 2to3

If you’re interested in implementing these or other such commands, please do contribute.

Conclusion

Ruby 1.9.2 isn’t the future, it’s already here. So why are you waiting?

One9 - Upgrade to Ruby 1.9 Now

2011-03-05T00:00:00-08:00

Install

No surprises here.

  gem install one9

Well almost. If you’re using bundler (the default in rails3), add one9 to your Gemfile if your
tests are invoked by bundler i.e. one9 test, one9 test rake * or one9 test bundle exec *.

How it works

  $ one9 changes
  +-----------------------------------+------------------------------------------------------------------+--------+
  | method                            | message                                                          | type   |
  +-----------------------------------+------------------------------------------------------------------+--------+
  | Module#constants                  | Returns array of symbols instead of array of strings             | change |
  | Module#public_methods             | Returns array of symbols instead of array of strings             | change |
  | Module#instance_methods           | Returns array of symbols instead of array of strings             | change |
  | Module#singleton_methods          | Returns array of symbols instead of array of strings             | change |
  | Module#public_instance_methods    | Returns array of symbols instead of array of strings             | change |
  | Module#protected_methods          | Returns array of symbols instead of array of strings             | change |
  ...

Run tests

First off, run your tests in the root directory of a gem or Rails app:

  # Runs `rake test` by default
  $ one9 test

  # To run any other test command, just prefix it with one9 test:
  # Run all cucumber specs
  $ one9 test cucumber

  # Only run model specs
  $ one9 test rspec spec/models

After your tests run, one9 prints a report. Here’s what it all looks like for boson:

  $ one9 test
  ...............................................................................................
  ...............................................................................................
  ...............................................................................................
  ...............
  Finished in 0.704555 seconds.

  300 tests, 580 assertions, 0 failures, 0 errors

  ** One9 Report **
  +---------------------------------+-------+--------------------------------------------------------------+--------+--------------------------------------------------------------+
  | method                          | count | message                                                      | type   | lines                                                        |
  +---------------------------------+-------+--------------------------------------------------------------+--------+--------------------------------------------------------------+
  | Module#instance_methods         | 5     | Returns array of symbols instead of array of strings         | change | lib/boson/util.rb:39:in `detect',lib/boson/util.rb:40:in ... |
  | Module#private_instance_methods | 2     | Returns array of symbols instead of array of strings         | change | lib/boson/inspectors/argument_inspector.rb:23:in `scrape_... |
  | Hash#to_s                       | 4     | An alias of #inspect instead of a spaceless join of the e... | change | lib/boson/loader.rb:87:in `initialize_library_module',lib... |
  | Hash#select                     | 4     | Returns a hash instead of an association array               | change | lib/boson/loader.rb:109:in `set_library_commands',lib/bos... |
  +---------------------------------+-------+--------------------------------------------------------------+--------+--------------------------------------------------------------+
  4 rows in set

As you can see the report lists changed methods, how many times they were
called and where they were called from. To reprint this list any time later, run one9 list.

Note: When you run one9 test it overwrites the previous one test result.

Edit Changes

Now that you have a list of changed method calls, editing those changes is easy:

  # Open all changes
  $ one9 edit

  # To only open a subset of changes:
  # Only open Hash changes
  $ one9 edit Hash

  # Only open Hash#to_s changes
  $ one9 edit Hash#to_s

For those without editing support, you can still view each line where there’s a method change:

  $ one9 lines
  +---------------------------------+---------------------------------------------------------------------+
  | method                          | line                                                                |
  +---------------------------------+---------------------------------------------------------------------+
  | Module#instance_methods         | lib/boson/util.rb:39:in `detect'                                    |
  | Module#instance_methods         | lib/boson/util.rb:40:in `detect'                                    |
  | Module#instance_methods         | lib/boson/loader.rb:101:in `check_for_method_conflicts'             |
  | Module#instance_methods         | lib/boson/util.rb:44:in `detect'                                    |
  | Module#instance_methods         | lib/boson/namespace.rb:28:in `boson_commands'                       |
  ...

Once you’ve fixed your changes, give your code a 1.9 test run. If tests are still broken, then jump
down to this section.

Rails Tips

Skip this section if you’re not on a Rails app.

Configure

one9 comes with a decent list of 1.9 changes and descriptions. If you’d like to add your
own changes, add them to your ~/.one9rc. For example:

  # For methods that have changed in 1.9
  change 'Class#instance_method', 'Some description'

  # For methods that have been deleted in 1.9
  delete 'Class.class_method', 'Some description'

For more examples, see the defaults that one9 defines. If I’ve missed an important 1.9 change, feel free to fork and pull.

Additional 1.9 Changes

So even if you’ve dealt with all changed methods, there are still other changes that could effect your code:

Encoding: Probably the most significant and thus well documented. See JEG’s thorough articles
scoping of block variables, splat operator and block arguments
files in $LOAD_PATH and $LOADED_FEATURES are expanded
using colon (:) instead of “then” in an if/unless/case is deprecated
retry in a loop or iterator is deprecated
$KCODE, $= and VERSION* constants are deprecated
?x now returns a single character string instead of an integer
For anything I may have missed see the official changelog or the unoffical one

Motivation

grep command to grep code for changed methods. Basically for porting test-deprived code.
info command to explain a method’s change in detail with examples and possible solutions
rails command to ease porting a rails app and all its dependencies.
automating code changes like python’s 2to3

If you’re interested in implementing these or other such commands, please do contribute.

Conclusion

Ruby 1.9.2 isn’t the future, it’s already here. So why are you waiting?

Documentation-Generated Irb Autocompletions With Bond and Yard

2010-05-19T00:00:00-07:00

Since it’s last release, bond has gained a number of features. The most novel of these is the ability to generate gem-specific autocompletions from a gem’s yard documentation. This release also lets gems ship with their own irb autocompletions and introduces bond to emacs’ inf-ruby mode.

Yard-Based Irb Autocompletions

Update: Yard functionality has been moved to bond-yard.

This feature generates autocompletions for a gem’s methods from a gem’s yard documentation. The only arguments it currently autocompletes are hash keys for a hash argument that has been documented with @option. Let’s take a look:

  $ gem install bond yard bond-yard

  $ irb
  >> require 'bond'; Bond.start
  => true

  # Load autocompletions for yard methods
  >> Bond.load_yard_gems 'yard'
  Bond: Building/loading yard's .yardoc database ...
  => ["yard"]

  # Let's see what yard methods we can autocomplete
  >> Bond.list_methods.grep /YARD/
  => ["YARD::CodeObjects::Base#format", "YARD::CodeObjects::ClassObject#constants", "YARD::CodeObjects::ClassObject#meths",   
  "YARD::CodeObjects::NamespaceObject#constants", "YARD::CodeObjects::NamespaceObject#included_meths", 
  "YARD::CodeObjects::NamespaceObject#meths", "YARD::Serializers::FileSystemSerializer.new", "YARD::Templates::Engine.render", 
  "YARD::Templates::Engine.set_default_options"]

  # Trying one of the above
  >> YARD::Templates::Engine.render :[TAB]
  :format    :template  :type
  >> YARD::Templates::Engine.render :f[TAB]
  >> YARD::Templates::Engine.render :format=>:html, :te[TAB]
  >> YARD::Templates::Engine.render :format=>:html, :template
  # ...

Are there any other gems besides yard that use yard documentation? Sure:

  # gem install spidr
  >> Bond.load_yard_gems 'spidr'
  Bond: Building/loading spidr's .yardoc database ...
  => ["spidr"]
  >> require 'spidr'
  => true

  >> Spidr::Agent.new :h[TAB]
  :history       :host          :host_header   :host_headers
  >> Spidr::Agent.new :hi[TAB]
  >> Spidr::Agent.new :history
  # ...

  # gem install haml
  >> Bond.load_yard_gems 'haml'
  Bond: Building/loading haml's .yardoc database ...
  => ["haml"]
  >> require 'haml/html'
  => true

  >> Haml::HTML.new :[TAB]
  :erb     :xhtml
  >> Haml::HTML.new :x[TAB]
  >> Haml::HTML.new :xhtml
  # ...

  # gem install rdf
  >> Bond.load_yard_gems 'rdf'
  Bond: Building/loading rdf's .yardoc database ...
  => ["rdf"]
  >> require 'rdf'
  => true

  >> RDF::Repository.new :[TAB]
  :title   :uri
  >> RDF::Repository.new :t[TAB]
  >> RDF::Repository.new :title
  # ...

For more gems that use yard documentation, see here.

Gems with Custom Autocompletions

If your gem doesn’t use yard documentation, no worries. You can still ship your gems with custom autocompletions. Completion files are under lib/bond/completions/ which is relative your gem’s base directory. For the format of a completion file, see here. For an example of a gem that ships with autocompletions, let’s use hirb:

  # Install latest hirb
  $ gem install hirb

  $ irb
  >> require 'bond'; Bond.start
  => true
  >> Bond.load_gems 'hirb'
  => ["hirb"]
  >> require 'hirb'
  => true

  # Autocomplete all options to hirb's tables
  >> puts Hirb::Helpers::AutoTable.render [1,2,3], :[TAB]
  :all_fields            :filter_any            :hide_empty            :table_class
  :change_fields         :filter_classes        :max_fields            :vertical
  :description           :filters               :max_width             
  :escape_special_chars  :header_filter         :number                
  :fields                :headers               :resize                
  >> puts Hirb::Helpers::AutoTable.render [1,2,3], :d[TAB]
  >> puts Hirb::Helpers::AutoTable.render [1,2,3], :description
  # ...

  # Let's use hirb's console methods
  >> extend Hirb::Console
  => main

  # Autocomplete all options to hirb's menus
  >> menu [1,2,3], :[TAB]
  :action         :command        :helper_class   :readline       
  :action_object  :default_field  :multi_action   :two_d          
  :ask            :directions     :prompt         
  >> menu [1,2,3], :p[TAB]
  >> menu [1,2,3], :prompt
  # ...

  # If you want to have gem completions defined at start up, just pass :gems to Bond.start.
  # Bond.start :gems=>%w{hirb}

Since this is the initial release of this feature, probably no other gems ship with bond’s irb autocompletions. So what can you do if you want to autocomplete your favorite gem’s methods? Just make your own completion files under ~/.bond/completions/. If you want to share your favorite gem’s completions with others, fork the gem, copy your completion file(s) to the gem’s lib/bond/completions/ directory and send the patch to the author.

Emacs Inf-Ruby and Bond

Bond can be used within emacs’ inf-ruby mode thanks to pd’s inf-ruby-bond. Since I don’t use emacs, I won’t try to go into an example. If any vim gurus are listening, a vim plugin to use bond within vim would be awesome :).

Final Thoughts

Although the idea of creating autocompletion functionality from documentation isn’t new, bond is probably the first to do so among ruby gems. This isn’t anything too special given that bond currently only autocompletes hash keys of hash arguments. But with yard’s excellent api, there isn’t anything stopping a future release from autocompleting any arguments to a method!

Although yard isn’t currently the commonly used documentation tool in the ruby world, this post shows the benefits it provides by letting gem authors easily associate meta-data per method. Yard makes it possible to ask: what gem-specific functionality can someone build from gem’s documentation? Bond’s irb autocompletions is one such answer. Perhaps in a future post another answer will be boson’s ability to make a command from any documented method and its options.

Screencast Of Argument Autocompletion for Methods in Irb

2010-05-07T00:00:00-07:00

Bond, a gem to improve irb’s autocompletion, just hit version 0.2.0. With this version comes a completion configuration system similar to bash/zsh, more fixes to irb’s incorrect completions and most importantly, any method can have its arguments autocompleted! The screencast demonstrates most of this.

Screencast

Bond – Argument Autocompletion for Methods in Irb from cldwalker.

Screencast Notes

Bond.list_methods: Lists all methods (80+) that have argument autocompletion.
Examples of methods with argument completion: Kernel#require, Array#delete, Hash#[], Module#const_get, Object#instance_variable_get
Object#send: Exemplifies an argument completion that varies per argument. Can be used to invoke argument completions for private methods.
Rails examples: ActiveRecord::Base.attr_accessible, ActiveRecord::Base.create, ActiveRecord::Base.where, ActiveRecord::Base.all
Basic argument completion example: Bond.complete(:method=>"Array#jump") { %w{foo bar baz} }

Install

Install the gem with:

    sudo gem install bond

In your irbrc, replace irb’s completion (require ‘irb/completion’) with :

  require 'bond'
  Bond.start
  #Bond.start replaces require 'bond/completion' from previous bond versions

If using wirble, place the above after wirble.

Lightning - Speed For The User

2010-04-09T00:00:00-07:00

The previous post explained what lightning does. This post explains how you, the user, can use and customize lightning to speed up your commandline experience.

Default Functions

After having installed lightning:

  # We'll use these aliases throughout this post
  $ alias lg=lightning
  $ alias lgr=lightning-reload

  # List available commands
  $ lg -h
  # ...

  # List default functions generated from install
  $ lg function
  cd-gem
  cd-local_ruby
  cd-ruby
  cd-wild
  echo-gem
  echo-local_ruby
  echo-ruby
  echo-wild

  # Lightning lets you abbreviate commands and subcommands
  # so the above can also be
  $ lg f

These functions are in the default format SHELL_COMMAND-BOLT. Lightning generates these defaults by combining the commands echo and cd with global bolts gem, ruby, local_ruby and wild. If you don’t want ruby-related functions, turn them off with: lg bolt global off gem ruby local_ruby.

The previous post had plenty of examples demonstrating the ruby and gem bolts. Let’s look at the other two default bolts, wild and local_ruby. These two bolts are different than the others:

  $ lg bolt show wild   # or lg b s wild
  globs: 
  - "**/*"
  global: true

  $ lg b s local_ruby
  globs: 
  - "**/*.rb"
  - bin/**
  global: true

What’s different about them is that their globs are local i.e. based on what’s in the current directory. Let’s try the wild bolt:

  # In the base directory of the lightning gem
  $ echo-wild [TAB]
  Display all 274 possibilities? (y or n)

  $ echo-wild comm[TAB]
  command_has_required_args_i.dat  commands                         commands_i.dat                   commands_util.rb                 
  command_usage_i.dat              commands.rb                      commands_test.rb                 common.css
  $ echo-wild command_h[TAB]
  $ echo-wild command_has_required_args_i.dat
  .yardoc/objects/Lightning/CommandsUtil/command_has_required_args_i.dat

  # Functions with an infinitely deep glob can be dangerous
  $ cd /
  # TAB if you feel like autocompleting your whole filesystem
  $ echo-wild [DARE_YA]

As you can see, the wild bolt can be wild. But if you use it in the right places, it can save you from navigating several directories.

The local_ruby bolt is a good example of a specialized local glob. It’s main purpose is let the user jump into any ruby related project and instantly command any ruby files regardless of their directory depth:

  # In the base directory of the lightning gem
  $ echo-local_ruby [TAB]
  bolt.rb//lib/lightning               commands_util.rb                     core.rb                              lightning                            test_helper.rb
  bolt.rb//lib/lightning/commands      completion.rb                        function.rb//lib/lightning           lightning-complete                   util.rb
  bolt_test.rb                         completion_map.rb                    function.rb//lib/lightning/commands  lightning-translate                  version.rb
  builder.rb                           completion_map_test.rb               function_test.rb                     lightning.rb                         
  builder_test.rb                      completion_test.rb                   generator.rb                         misc.rb                              
  commands.rb                          config.rb                            generator_test.rb                    ruby.rb                              
  commands_test.rb                     config_test.rb                       generators.rb                        shell_command.rb

  $ echo-local_ruby m[TAB]
  $ echo-local_ruby misc.rb
  lib/lightning/generators/misc.rb

Note how the local_ruby bolt makes autocompleting in this directory much more relevant than wild. If you’re a programmer, making a specialized local bolt for your language is only one command away: lg bolt create local_language '**/*.my_language_extension'.

Although these two bolts don’t do much with echo, they can, when combined with more useful commands i.e. vim, grep, less.

Create and Delete Functions

We can create and delete functions in three nonexclusive ways. The first way to create/delete a function is by individual combinations of one bolt and one shell command:

  $ lg function create cd gem && lgr
  Created function 'cd-gem'
  Created /Users/bozo/.lightning/functions.sh
  Loaded /Users/bozo/.lightning/functions.sh

  # Give it a spin
  $ cd-gem b[TAB]
  bacon-1.1.0    bond-0.1.4     builder-2.1.2  bundler-0.9.7
  $ cd-gem ba[TAB]
  $ cd-gem bacon-1.1.0
  $ pwd
  /Library/Ruby/Gems/1.8/gems/bacon-1.1.0

  # Delete it
  $ lg function delete cd-gem
  Deleted function 'cd-gem'

The second way is to use global commands and global bolts. When lightning generates functions, it combines each global command with each global bolt. For the default functions this means 2 commands * 4 bolts = 8 functions. Global commands are a great way of mass-assigning commands to a group of bolts.

To compare these two ways, say we have bolts python, clojure, ruby and want to combine them each with commands vim and grep:

  # The first and longer way
  $ lg function create vim python  # or lg f c vim python
  Created function 'vim-python'
  $ lg function create vim clojure
  Created function 'vim-clojure'
  # 4 more times ...

  # With global commands and bolts:
  # First make the bolts global since bolts aren't global by default
  $ lg bolt global on python clojure ruby
  Global on for bolts python, clojure, ruby

  # Then add the global commands
  $ lg shell_command create vim   # or lg s c create vim
  Created shell command 'vim'
  $ lg shell_command create grep
  Created shell command 'grep'
  $ lgr
  # ...

  # Expected functions show up
  $ lg f
  grep-clojure
  grep-python
  grep-ruby
  vim-clojure
  vim-python
  vim-ruby

  # If we want to create or delete global commands across global
  # bolts later, we can do that in one place:
  # Remove grep across global bolts
  $ lg shell_command delete grep
  Deleted shell command 'grep'

  # No more grep
  $ lg f
  vim-clojure
  vim-ruby
  vim-ru

The third and not usually recommended way is to edit lightning’s config file, ~/.lightningrc. Since ~/.lightningrc is YAML, it’s easy to read and modify. However, lightning depends on this file to function and will fail if the file has a syntax error. Modifying this file is recommended if you need to update existing bolts. Before doing this, read the docs on its format.

Aliases

As we’ve seen, function naming defaults to SHELL_COMMAND-BOLT. While this is fine for bolts and commands with short names, it can get annoying for long names i.e. echo-local_ruby. To shorten these defaults, you can alias bolts:

  $ lg function list --bolt=local_ruby  # or lg f l --bolt=local_ruby
  cd-local_ruby
  echo-local_ruby

  $ lg bolt alias local_ruby rb   # or lg b al local_ruby rb
  Aliased bolt 'local_ruby' to 'rb'
  $ lgr
  # ...

  $ lg f l --bolt=local_ruby
  cd-rb
  echo-rb

  # To list bolts with their aliases
  $ lg bolt list --alias  # or lg b l -a
  local_ruby      rb
  # ...

As you can see, the bolt alias is used in place of the bolt name when generating functions.

When creating global commands, you can alias them as well:

  $ lg shell_command create less l
  Created shell command 'less'

  $ lg function list --command=less   # or lg f l --command=less
  l-gem
  l-rb
  l-ruby
  l-wild

  # List commands and their aliases
  $ lg shell_command list --alias
  cd    cd
  echo  echo
  less  l

Note these aliases won’t effect functions that have an explicit function name.

Creating Your Own Bolt

To show you how to create your own bolt with its functions, I’ll show you one I made.

Being a programmer, I have a number of projects spread across directories that I go between several times a day. Here’s a tree view of the directories that organize my projects:

  ~/code/
  |-- fork
  |   |-- bacon/
  |   |-- ...
  |   `-- rip/
  |-- gems
  |   |-- hirb/
  |   |-- ...
  |   `-- my_core/
  |-- todo
  |   |-- gems
  |   |   |-- g-outline/
  |   |   `-- mp-tree/
  |   |-- ...
  |   `-- hooks.rb
  |-- repo
  |   |-- bin/
  |   |-- ...
  |   `-- queriac/
  # ....

There are only 2-3 levels of directories or 2-3 tabs to get to the point where I can autocomplete the project name. But as my number of projects grow, I find myself pausing more to remember which subdirectory a project is in. To me, this mental pause and doing 2-3 tabs is a waste of time. Enter lightning.

To create a bolt and its functions, here’s the steps I took:

Identify a group of paths that I use often.
Directories of coding projects
Create a bolt that represents those paths using globs.
lightning bolt create code '~/code/fork/*' ...
Create function(s) for that bolt.
lightning function create cd code c
Generate and load functions into my shell.
lightning-reload

Let’s see these steps played out in the shell:

  # Quote arguments to prevent file expansion
  $ lg bolt create code '~/code/fork/*' '~/code/gems/*' '~/code/todo/gems/*' '~/code/repo/*'
  Created bolt 'code'

  $ lg function create cd code c && lgr
  Created function 'c'
  Created /Users/bozo/.lightning/functions.sh
  Loaded /Users/bozo/.lightning/functions.sh

  # Test drive c
  $ c [TAB]
  19it                  console_update        github_user_page.js   local_gem             rip
  alias                 core                  has_machine_tags      machinetag.js         shellable
  bacon                 dm_rails3_app         heroku_twilio_app     mp_tree               snips
  # ...

  $ c h[TAB]
  has_machine_tags   heroku_twilio_app  hirb
  $ c hi[TAB]
  $ c hirb[ENTER]
  # Verify it worked
  $ pwd
  /Users/bozo/code/gems/hirb

Nice! If I want to add another command to this bolt, say grep, we know the drill:

  $ lg function create grep code && lgr
  Created function 'grep-code'
  Created /Users/bozo/.lightning/functions.sh
  Loaded /Users/bozo/.lightning/functions.sh

  $ grep-code -r attr li[TAB]
  $ grep-code -r attr lightning
  $ grep-code -r attr lightning/lib
  /Users/bozo/code/gems/lightning/lib/lightning/bolt.rb:    attr_reader :name, :aliases, :desc
  /Users/bozo/code/gems/lightning/lib/lightning/bolt.rb:    attr_accessor :globs, :commands
  /Users/bozo/code/gems/lightning/lib/lightning/completion_map.rb:    attr_accessor :map
  # ...

Generating Bolts

In the last post we saw how generators are implicitly used to create bolts and functions. But sometimes we need to use generators explicitly to generate bolts:

  # Let's use the gem generator with `lightning bolt generate` to generate bolts

  # Generates a bolt named ruby using the ruby generator
  # This is done implicitly for us with `lightning function create`
  $ lg bolt generate ruby    # or lg b g ruby
  Generated following globs for bolt 'ruby':
    /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/**/*.{rb,bundle,so,c}
    /Library/Ruby/Site/1.8/**/*.{rb,bundle,so,c}
  
  # Generates a bolt named ruby19 using the ruby generator
  $ lg bolt generate ruby19 ruby
  Generated following globs for bolt 'ruby19':
    /Users/bozo/.rvm/ruby-1.9.1-p378/lib/ruby/1.9.1/**/*.{rb,bundle,so,c}
    /Users/bozo/.rvm/ruby-1.9.1-p378/lib/ruby/site_ruby/1.9.1/**/*.{rb,bundle,so,c}

  # To test what a generator generates without making a bolt
  $ lg bolt generate ruby --test
  /Users/bozo/.rvm/ruby-1.9.1-p378/lib/ruby/1.9.1/**/*.{rb,bundle,so,c}
  /Users/bozo/.rvm/ruby-1.9.1-p378/lib/ruby/site_ruby/1.9.1/**/*.{rb,bundle,so,c}

As you can see, if you’re testing a generator or generating a bolt with a name different than the generator’s, use lightning bolt generate.

Miscellaneous

Some miscellaneous notes:

Make your own lightning commands i.e. lg YOUR_COMMAND with command plugins.
Use the translate lightning command to test the translation of arguments for a given function:

  # Command to test:
  $ cp-gem -r rubygems-update-1.3.6 .

  # Just prefix the above with lg t (lg translate)
  # Each argument is printed on a separate line
  $ lg t cp-gem -r rubygems-update-1.3.6 .
  -r
  /Library/Ruby/Gems/1.8/gems/rubygems-update-1.3.6
  .

Use the echo shell command combined with a bolt to pass a bolt’s translating ability to any command:

  $ echo-gem -r rubygems-update-1.3.6 .
  -r /Library/Ruby/Gems/1.8/gems/rubygems-update-1.3.6 .
  
  # Emulate cp-gem from the previous example
  $ cp `echo-gem -r rubygems-update-1.3.6 .`

Wrap Up

This post has been a thorough introduction to using lightning. For more about lightning, visit its homepage and docs. For questions about using lightning, feel free to leave a comment below or open an issue.

Lightning - Speed For Your Shell

2010-04-08T00:00:00-07:00

Introducing lightning, a commandline framework that could revolutionize how fast you are on the commandline. Lightning lets you easily define and generate shell functions which autocomplete and interpret paths (files and directories) by their basenames. With these functions you don’t have to ever type the full path to any file for any command again.

Overview

Intro
Install
Lightning Bolts
Everything is Local
Generators
Conclusion

Intro

Lightning generates shell functions which can interpret paths by their basenames. So instead of carpal-typing

  $ less /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/irb.rb

just type

  $ less-ruby irb.rb

less-ruby is a lightning function which wraps less with the ability to refer to system ruby files by their basenames. Being a lightning function, it can also autocomplete system ruby files:

  # 1112 available system ruby files
  $ less-ruby [TAB]
  Display all 1112 possibilities? (y or n)

  $ less-ruby a[TAB]
  abbrev.rb                  abstract.rb                abstract_index_builder.rb
  $ less-ruby abb[TAB]
  $ less-ruby abbrev.rb
  # Pages /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/abbrev.rb ...

  # Autocompletion works regardless of the number of arguments
  $ less-ruby -I abbrev.rb y[TAB]
  yaml.rb      yamlnode.rb  ypath.rb
  $ less-ruby -I abbrev.rb yp[TAB]
  $ less-ruby -I abbrev.rb ypath.rb
  # Pages /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/abbrev.rb and
    /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/yaml/ypath.rb ...

The ‘-I’ being passed to less-ruby demonstrates an important point. A lightning function only touches and translates the arguments it knows how to translate to full paths. This allows a lightning function to be used the same as the command it wraps i.e. with any mix of options, local files or non-file arguments.

Perhaps you noticed less-ruby can refer to 1112 files by basename. Are they all in one directory? Nope. They’re in 118 directories. So what happens when two files from different directories have the same basename? Lightning lets you pick the right file in an autocomplete-friendly way:

  $ less-ruby date[TAB]
  date.rb///System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8
  date.rb///System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/optparse
  date2.rb
  dateentry.rb
  datefield.rb///System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/tkextlib/iwidgets
  datefield.rb///System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/tkextlib/tcllib
  datetime.rb

  $ less-ruby date.rb[TAB]
  $ less-ruby date.rb///System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8
  date.rb///System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8
  date.rb///System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/optparse

  $ less-ruby date.rb///System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/[TAB]
  $ less-ruby date.rb///System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/optparse
  # Pages /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/optparse/date.rb ...

Note the format for displaying conflicting basenames is basename//directory.

This is cool but what if we want a grep-ruby, vim-ruby, or *-ruby to search, edit or do anything to our 1100+ system ruby files? No problem. It’s a one-liner: lightning function create grep ruby && lightning-reload. What if we want nothing to do with ruby files and want to define our own group of paths to autocomplete and type minimally? No problem. It’s really quite easy.

Install

Lightning works with bash or zsh shells and since it’s written in ruby, you’ll need ruby 1.8.6 or later. To install lightning, use rip or rubygems:

  $ rip install lightning
  # OR  
  $ sudo gem install yard # if you want lightning's documentation generated correctly
  $ sudo gem install lightning

If you’ve installed with rubygems and `time lightning` takes longer than 0.05 seconds, I strongly recommend installing with rip. rubygems is known to have a hefty startup lag with older versions of ruby. Since lightning’s autocompletion depends on this startup time, accepting this lag makes lightning slow as molasses.

Once lightning is installed, we need to do a one-time setup:

  # To see available install options
  $ lightning install -h

  # Installs lightning's core files and sources the needed lightning functions
  $ lightning install && source ~/.lightning/functions.sh
  Created ~/.lightningrc
  Created ~/.lightning/functions.sh for bash
  # Or for zsh
  $ lightning install --shell=zsh && source ~/.lightning/functions.sh

  # To have lightning's functionality loaded when your shell starts up
  echo source ~/.lightning/functions.sh >> ~/.bashrc
  # or for zsh
  echo source ~/.lightning/functions.sh >> ~/.zshrc

  # For all future examples I'll be using this alias
  $ alias lg=lightning

Updated: To install and view lightning’s man page:

  # If installed with rip, man pages are automatically installed
  $ man lightning

  # If installed with rubygems
  $ sudo gem install gem-man
  $ gem man lightning

Lightning Bolts

To create a function (less-ruby) from scratch that can autocomplete and access by basename 1112 files across 118 directories must take a lot of effort. Right? Not really:

  # These globs are specific to my filesystem
  # Arguments are quoted to prevent shell expansion
  $ lg bolt create ruby '/Library/Ruby/Site/1.8/**/*.{rb,bundle,so,c}'
    '/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/**/*.{rb,bundle,so,c}'
  Created bolt 'ruby'

  # Creates less-ruby and loads it into the shell
  $ lg function create less ruby && lightning-reload
  Created function 'less-ruby'
  Created /Users/bozo/.lightning/functions.sh
  Loaded /Users/bozo/.lightning/functions.sh

The first command creates the ‘ruby’ lightning bolt with two globs. This is all the information that a lightning function needs to know about the filesystem. The second command creates the lightning function by combining the bolt with the desired shell command, less in this case. lightning-reload creates and reloads lightning’s functions into the current shell session.

Although these steps are fairly easy, you may have noticed that the globs were specific to my system. Fortunately, lightning provides generators to generate fileysystem-specific globs for bolts. Since lightning has a generator for the ruby bolt, the previous example can be even shorter:

  $ lg function create less ruby && lightning-reload
  Generated following globs for bolt 'ruby':
    /Library/Ruby/Site/1.8/**/*.{rb,bundle,so,c}
    /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/**/*.{rb,bundle,so,c}
  Created function 'less-ruby'
  Created /Users/bozo/.lightning/functions.sh
  Loaded /Users/bozo/.lightning/functions.sh

Keep this one-liner in mind for following along with examples in this post. If you see a function you don’t have i.e. less-gem, create it: lg function create less gem && lightning-reload.

Lightning bolts aren’t limited to one shell command i.e. less. To make a lightning function which wraps around any shell command, just repeat the above one-liner. For example, let’s make a function that edits system ruby files:

  $ lg function create vim ruby && lightning-reload
  Created function 'vim-ruby'
  Created /Users/bozo/.lightning/functions.sh
  Loaded /Users/bozo/.lightning/functions.sh

  $ vim-ruby abbrev.rb
  # Opens /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/abbrev.rb in vim

In this section we’ve seen that a bolt takes globs and converts them to paths to be accessed locally by basename. Since bolts can be used with any command, we can think of a bolt as a virtual, local directory whose contents change depending on what its globs match. For more about bolts and globs, read here.

Everything is Local

If a bolt is a virtual, local directory, can we autocomplete and execute commands around any bolt path as if we were right there? Sure!

  # echo-ruby calls `echo` with the ruby bolt
  $ echo-ruby abbrev.rb
  /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/abbrev.rb

  # Note: This kind of completion doesn't work for zsh yet
  # Autocomplete the directory containing abbrev.rb
  $ echo-ruby abbrev.rb/../[TAB]
  Display all 136 possibilities? (y or n)
  $ echo-ruby abbrev.rb/../md[TAB]
  $ echo-ruby abbrev.rb/../md5.rb
  /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/md5.rb

  # Autocomplete multiple levels up or down
  $ echo-ruby abbrev.rb/../../[TAB]
  abbrev.rb/../../1.8/        abbrev.rb/../../gems/       abbrev.rb/../../site_ruby/  abbrev.rb/../../user-gems/
  $ echo-ruby abbrev.rb/../../../
  /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib
  $ echo-ruby abbrev.rb/../irb/ext/s[TAB]
  $ echo-ruby abbrev.rb/../irb/ext/save-history.rb
  /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/irb/ext/save-history.rb

Bolt paths that are directories can also autocomplete and execute this way:

  # less-gem calls `less` with the gem bolt (contains directories of rubygems)
  # less-gem ba[TAB]
  $ less-gem bacon-1.1.0
  $ less-gem bacon-1.1.0/l[TAB]
  $ less-gem bacon-1.1.0/lib/
  $ less-gem bacon-1.1.0/lib/b[TAB]
  $ less-gem bacon-1.1.0/lib/bacon.rb
  # Pages /Library/Ruby/Gems/1.8/gems/bacon-1.1.0/lib/bacon.rb ...

If we can use filename expansion on local paths, why not bolt paths?

  # Let's search in different versions of a gem for the use of method_missing()
  # grep-gem calls `grep` on the gem bolt
  $ grep-ruby -r def.*method_missing rai[TAB]
  rails-1.2.6  rails-2.1.0  rails-2.2.2  rails-2.3.4
  $ grep-ruby -r def.*method_missing rails-

  # Traditional filename expansion doesn't work
  $ grep-ruby -r def.*method_missing rails-*
  grep: rails-*: No such file or directory

  # Append '..' instead
  $ grep-ruby -r def.*method_missing rails-..
  /Library/Ruby/Gems/1.8/gems/rails-2.1.0/lib/initializer.rb:  def method_missing(name, *args)
  /Library/Ruby/Gems/1.8/gems/rails-2.1.0/lib/rails_generator/manifest.rb:      def method_missing(action, *args, &block)
  /Library/Ruby/Gems/1.8/gems/rails-2.1.0/lib/rails_generator/simple_logger.rb:        def method_missing(method, *args, &block)
  /Library/Ruby/Gems/1.8/gems/rails-2.2.2/lib/initializer.rb:  def method_missing(name, *args)
  # ...

  # Why not use '*' for lightning as well?
  # Say you use a liberal expansion:
  #   $ grep-ruby -r def.*method_missing r*
  # If there happens to be a local file starting with 'r' i.e. 'readme',
  # the shell expands 'r*' to 'readme' and lightning will never see 'r*'.

So lightning does filename expansion but only for arguments ending in ... When expanding matches, lightning treats everything before .. as a regular expression:

  $ grep-gem -r def.*method_missing rubygems-u[TAB]
  rubygems-update-1.3.1  rubygems-update-1.3.2  rubygems-update-1.3.5  rubygems-update-1.3.6
  $ grep-gem -r def.*method_missing rubygems-update-1.3.
  # Only search two versions
  $ grep-gem -r def.*method_missing rubygems-update-1.3.[56]..
  /Library/Ruby/Gems/1.8/gems/rubygems-update-1.3.5/lib/rubygems/package.rb:  def method_missing(meth, *args, &block)
  /Library/Ruby/Gems/1.8/gems/rubygems-update-1.3.5/lib/rubygems/specification.rb:  def method_missing(sym, *a, &b) # :nodoc:
  /Library/Ruby/Gems/1.8/gems/rubygems-update-1.3.5/lib/rubygems/test_utilities.rb:  def method_missing(meth, *args, &block)
  # ...

  # To search either rubygems or rails
  $ grep-gem -r def.*method_missing '(rails|rubygems)..'
  /Library/Ruby/Gems/1.8/gems/rails-2.1.0/lib/initializer.rb:  def method_missing(name, *args)
  /Library/Ruby/Gems/1.8/gems/rails-2.1.0/lib/rails_generator/manifest.rb:      def method_missing(action, *args, &block)
  /Library/Ruby/Gems/1.8/gems/rails-2.1.0/lib/rails_generator/simple_logger.rb:        def method_missing(method, *args, &block)
  /Library/Ruby/Gems/1.8/gems/rails-2.2.2/lib/initializer.rb:  def method_missing(name, *args)
  # ...

  # If you're unsure of what you're executing, test it with `lightning translate`
  # Prints arguments to be passed to grep, one per line
  $ lg translate grep-gem -r def.*method_missing '(rails|rubygems)..'
  -r
  def.*method_mis
  /Library/Ruby/Gems/1.8/gems/rails-2.1.0
  /Library/Ruby/Gems/1.8/gems/rubygems-update-1.3.1
  /Library/Ruby/Gems/1.8/gems/rubygems-update-1.3.2
  /Library/Ruby/Gems/1.8/gems/rubygems-update-1.3.5
  /Library/Ruby/Gems/1.8/gems/rubygems-update-1.3.6
  /Library/Ruby/Gems/1.8/gems/rails-2.2.2
  /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/gems/1.8/gems/rails-1.2.6
  /Library/Ruby/Gems/1.8/gems/rubygems-sing-1.0.0
  /Library/Ruby/Gems/1.8/gems/rails-2.3.4

Generators

Generators generate filesystem-specific bolts. When creating a function, this is done for us automatically if the bolt and generator have the same name. Let’s create a function with one of lightning’s default generators:

  # List default generators
  $ lg generator
  bin         Files in $PATH
  gem         Directories of gems
  local_ruby  *ALL* local ruby files. Careful where you do this.
  rails       Files in a rails project
  ruby        System ruby files
  test_ruby   Test or spec files in a ruby project
  wild        *ALL* files and directories under the current directory. Careful where you do this.

  # Try the test_ruby generator with the Test::Unit runner
  $ lg function create testrb test_ruby && lightning-reload
  Generated following globs for bolt 'test_ruby':
    {spec,test}/**/*_{test,spec}.rb
    {spec,test}/**/{test,spec}_*.rb
    spec/**/*.spec
  Created function 'testrb-test_ruby'
  Created /Users/bozo/.lightning/functions.sh
  Loaded /Users/bozo/.lightning/functions.sh

  # Runs any number of local ruby test files, no matter how many directories deep
  # $ testrb-test_ruby  ...

If you’re a rubyist, I highly recommend checking out all the ruby-related generators.

Since generators are important in distributing bolts that work for everyone, lightning lets users make their own generators and store them under ~/.lightning/generators. Read the docs to learn how to make generator plugins. What if we want to try out someone else’s generators? Not too hard:

  # Let's try out my mac-specific generators
  $ mkdir -p ~/.lightning/generators
  $ curl http://github.com/cldwalker/dotfiles/raw/master/.lightning/generators/mac.rb > ~/.lightning/generators/mac.rb

  $ lg generator
  app             Mac apps
  bin             Files in $PATH
  brew            Homebrew formulas under /usr/local
  # ...

  # Let's combine open with mac apps
  $ lg function create open app && lightning-reload
  Generated following globs for bolt 'app':
    /Applications/*.app
    /Applications/Utilities/*.app
  Created function 'open-app'
  Created /Users/bozo/.lightning/functions.sh
  Loaded /Users/bozo/.lightning/functions.sh

  # Let's open a mac app
  $ open-app Co[TAB]
  Cog.app                 Colloquy.app            ColorSync\ Utility.app  Console.app
  $ open-app Coll[TAB]
  $ open-app Colloquy.app
  # Opens Colloquy

To try out more generators, see my public ones.

Conclusion

Hopefully this post has shown that lightning can revolutionize how you interact with your filesystem on the commandline. By abstracting a group of paths to a bolt’s name and its globs, any group of paths is only a bolt’s name away from being used as if they were in the current directory. Although the examples have been specific to ruby paths, lightning can generate functions for any group of paths. Lightning’s generators provide a way for users to share their bolts and thus how they use their filesystem.

This post was mostly an introduction to lightning and what it’s capable of. The next post will cover using it in more depth. For more about lightning, visit its homepage and docs.

Hirb - And Tables for All

2010-03-11T00:00:00-08:00

Almost a year ago, hirb started as an itch to get mysql-like tables for Rails’ ActiveRecord models. Now, hirb 0.3.0 provides table views for ten additional database gems. Whether you use hirb with couch, mongo, riak or any of the databases supported by sequel or datamapper, hirb essentially turns irb into a database-agnostic database shell.

Database Gems

Here are the list of additional database gems and their modules/classes that now have table views:

datamapper: DataMapper::Resource
sequel: Sequel::Model
friendly: Friendly::Document
mongomapper: MongoMapper::Document, MongoMapper::EmbeddedDocument
mongoid: Mongoid::Document
couch_foo: CouchFoo::Base
couchrest: CouchRest::ExtendedDocument
couch_potato: CouchPotato::Persistence
ripple: Ripple::Document
dbi: DBI::Row

Examples

Here’s all you need in your ~/.irbrc for hirb to work with the above gems and the following examples:

  require 'rubygems'
  require 'hirb'
  Hirb.enable

Keep in mind that while that the following examples are simple, your models/tables can be as complex as you’d like and hirb will still render your tables cleanly.

Sequel

For this example, you need to have sqlite3 installed.

  $ sudo gem install sqlite3-ruby sequel
  $ irb -rubygems -rsequel

  # Setup db and a model
  >> DB = Sequel.sqlite
  => #< Sequel::SQLite::Database: "sqlite:/">
  >> DB.create_table(:urls) { primary_key :id; String :name }
  => []
  >> class Url < Sequel::Model; end
  => nil

  # Nicely formatted tables!
  >> Url.create :name=>'example.com'
  +----+-------------+
  | id | name        |
  +----+-------------+
  | 1  | example.com |
  +----+-------------+
  1 row in set
  # Same as above
  >> Url.all

DataMapper

For this example, you need to have sqlite3 installed.

  $ sudo gem install sqlite3-ruby dm-core do_sqlite3
  $ irb -rubygems -rdm-core

  # Setup db and a model
  >> DataMapper.setup(:default, 'sqlite3::memory:')
  => #< DataMapper::Adapters::Sqlite3Adapter:0x188ceac ... >
  >> class Url
  >>  include DataMapper::Resource
  >>  property :id, Serial
  >>  property :name, String
  >> end
  => #< DataMapper::Property @model=Url @name=:name>
  >> Url.auto_migrate!
  => true

  # Nicely formatted tables!
  >> Url.create :name=>'example.com'
  +----+-------------+
  | id | name        |
  +----+-------------+
  | 1  | example.com |
  +----+-------------+
  1 row in set
  # Same as above
  >> Url.all

MongoMapper

For this example you need to have MongoDB installed.

  $ sudo gem install mongo_mapper
  $ irb -rubygems -rmongo_mapper

  # Setup db and a model
  >> MongoMapper.connection = Mongo::Connection.new
  => #< Mongo::Connection:0x1123d28 ... >
  >> MongoMapper.database = 'test'
  => 'test'
  >> class Url
  >>   include MongoMapper::Document
  >>   key :name, String
  >> end
  => #< MongoMapper::Plugins::Keys::Key:0x5a3520 ... >

  # Nicely formatted tables!
  >> Url.create :name=>'example.com'
  +-------------+--------------------------+
  | name        | _id                      |
  +-------------+--------------------------+
  | example.com | 4b97cf2978c2ec2854000001 |
  +-------------+--------------------------+
  1 row in set
  # Same as above
  >> Url.all

CouchRest

For this example you need to have CouchDB installed.

  $ sudo gem install couchrest
  $ irb -rubygems -rcouchrest

  # Setup db and a model
  >> class Url < CouchRest::ExtendedDocument
  >>   property :name
  >>   view_by :name
  >> end
  => false
  >> Url.database = CouchRest.database("http://127.0.0.1:5984/urls")
  => #< CouchRest::Database:0x170541c ... >

  # Nicely formatted tables!
  >> Url.create :name=>'example.com'
  +----------------------------------+-------------+
  | _id                              | name        |
  +----------------------------------+-------------+
  | af990a562a9a96703dd6ef0442a73db8 | example.com |
  +----------------------------------+-------------+
  1 row in set
  # Same as above
  >> Url.all

Dynamic Views

Creating Them

All default views for the new database gems are due to hirb’s dynamic views. So what if you’re using a database gem that isn’t supported? Let’s answer this using friendly as an example (even though hirb already supports it):

Identify the module or class that the database gem uses to define models. For friendly, this module is Friendly::Document.
Determine what table options to pass to tables and how to generate them from the database gem’s model/table object. Although you can define as many options as you want, you must define the :fields option. To generate fields for a given friendly model object: model.attributes.keys
Using the last two steps, define a dynamic view using Hirb.add_dynamic_view that returns a hash of table options:

  Hirb.add_dynamic_view("Friendly::Document", :helper=>:auto_table) {|obj|
    {:fields=>obj.class.attributes.keys}
  }

Read the docs for more about dynamic views.

Submitting Them

If you’ve created a dynamic view for a somewhat popular database gem, feel free to fork and add it to hirb’s default dynamic views. Since hirb’s default dynamic views are in module form, read the docs to understand how to write them. Although I do appreciate any forking, I’m looking mainly to add default views for commonly used database gems.

Two Dimensional Console Menus with Hirb

2010-02-16T00:00:00-08:00

If you’re familiar with hirb, you know it’s good at displaying objects as tables. Hirb’s latest release takes a table’s usefulness a step further by turning them into two-dimensional menus, menus that can pick values from any table cell. Boson, in turn, provides these menus to any of its commands with a flick of the switch.

Intro

Hirb’s menus can be traditional one-dimensional menus. But what we’re interested in here are 2D menus:

  $ irb -rubygems -rhirb
  # import menu()
  >> extend Hirb::Console
  => self

  # Let's make a menu from the first ten local gemspecs.
  # We don't care what versions they are for simplicity sake.
  # Of course your list will be different
  >> menu Gem.source_index.gems.values[0,10], :fields=>[:name, :homepage], :two_d=>true
  +--------+-----------------------------------+------------------------------------------------------+
  | number | name                              | homepage                                             |
  +--------+-----------------------------------+------------------------------------------------------+
  | 1      | ruby-debug                        | http://rubyforge.org/projects/ruby-debug/            |
  | 2      | net-ssh-gateway                   | http://net-ssh.rubyforge.org/gateway                 |
  | 3      | mspec                             | http://rubyspec.org                                  |
  | 4      | yard                              | http://yardoc.org                                    |
  | 5      | rubyforge                         | http://codeforpeople.rubyforge.org/rubyforge/        |
  | 6      | midiator                          | http://projects.bleything.net/projects/show/midiator |
  | 7      | collectiveidea-awesome_nested_set | http://collectiveidea.com                            |
  | 8      | hirb                              | http://github.com/cldwalker/hirb                     |
  | 9      | boson                             | http://tagaholic.me/boson/                           |
  | 10     | linecache                         | http://rubyforge.org/projects/rocky-hacks/linecache  |
  +--------+-----------------------------------+------------------------------------------------------+
  10 rows in set
  Choose:
  # Possible answers from user ...

  # By default selections are applied to the first column, name in this case
  Choose: 1,4
  => ['ruby-debug', 'yard']

  # To choose from the homepage column simply append ':homepage' after choices
  Choose : 1,4:homepage  # or 1,4:h
  => ['http://rubyforge.org/projects/ruby-debug/', 'http://yardoc.org']

  # To select values from different columns, simply separate them with spaces
  Choose: 1-3 4:homepage  # or 1-3 4:h
  => ['ruby-debug', 'net-ssh-gateway', 'mspec', 'http://yardoc.org']

Nice! We can pick out values from table cell(s) simply by typing rows:column, where column is optional and can be abbreviated.

2D Action Menus

So why bother with a 2D menu? Well, for the above, we can perform different actions depending on the column:

  >> choices = menu Gem.source_index.gems.values[0,10], :fields=>[:name, :homepage], :two_d=>true
  +--------+-----------------------------------+------------------------------------------------------+
  | number | name                              | homepage                                             |
  +--------+-----------------------------------+------------------------------------------------------+
  | 1      | ruby-debug                        | http://rubyforge.org/projects/ruby-debug/            |
  | 2      | net-ssh-gateway                   | http://net-ssh.rubyforge.org/gateway                 |
  | 3      | mspec                             | http://rubyspec.org                                  |
  | 4      | yard                              | http://yardoc.org                                    |
  | 5      | rubyforge                         | http://codeforpeople.rubyforge.org/rubyforge/        |
  | 6      | midiator                          | http://projects.bleything.net/projects/show/midiator |
  | 7      | collectiveidea-awesome_nested_set | http://collectiveidea.com                            |
  | 8      | hirb                              | http://github.com/cldwalker/hirb                     |
  | 9      | boson                             | http://tagaholic.me/boson/                           |
  | 10     | linecache                         | http://rubyforge.org/projects/rocky-hacks/linecache  |
  +--------+-----------------------------------+------------------------------------------------------+
  10 rows in set
  Choose:
  # Possible answers from user ...

  # Choose some gems and uninstall them
  Choose: 5-6
  => ['rubyforge', 'midiator']
  >> system('sudo', 'gem', 'uninstall', *choices)
  => true

  # Choose some gems and open them in a browser
  Choose: 5-6:h
  => ['http://codeforpeople.rubyforge.org/rubyforge/', 'http://projects.bleything.net/projects/show/midiator']
  # works in mac osx
  >> system('open', *choices)
  => true

Okay. 2D menus seem like a good way to perform multiple actions from one menu. But is there a more natural way to do this? Yes. How about at the menu prompt?:

  # Let's make methods out of the actions we used above
  >> def uninstall(gems); system('sudo', 'gem', 'uninstall', *gems); end
  => nil
  >> def browser(urls); system('open', *urls); end
  => nil

  # Passing an :action option makes menu expect an action (method) with menu choices as the argument
  >> menu Gem.source_index.gems.values[0,10], :fields=>[:name, :homepage], :two_d=>true, :action=>true
  +--------+-----------------------------------+------------------------------------------------------+
  | number | name                              | homepage                                             |
  +--------+-----------------------------------+------------------------------------------------------+
  | 1      | ruby-debug                        | http://rubyforge.org/projects/ruby-debug/            |
  | 2      | net-ssh-gateway                   | http://net-ssh.rubyforge.org/gateway                 |
  | 3      | mspec                             | http://rubyspec.org                                  |
  | 4      | yard                              | http://yardoc.org                                    |
  | 5      | rubyforge                         | http://codeforpeople.rubyforge.org/rubyforge/        |
  | 6      | midiator                          | http://projects.bleything.net/projects/show/midiator |
  | 7      | collectiveidea-awesome_nested_set | http://collectiveidea.com                            |
  | 8      | hirb                              | http://github.com/cldwalker/hirb                     |
  | 9      | boson                             | http://tagaholic.me/boson/                           |
  | 10     | linecache                         | http://rubyforge.org/projects/rocky-hacks/linecache  |
  +--------+-----------------------------------+------------------------------------------------------+
  10 rows in set
  Choose:
  # Possible answers from user ...

  # Uninstall rubyforge + midiator using uninstall()
  Choose: uninstall 5-6
  => true

  # Open rubyforge and midiator urls using browser()
  Choose: browser 5-6:h
  => true

Note that by default, menu actions call top-level main methods and pass all to the choices to the method as one array. menu() can be configured to call another object’s methods and pass menu choices in different ways with additional options. See the documentation for more info.

Examples with Boson

Now that we understand how 2d menus are used, let’s look at some examples with boson. Boson’s integration with hirb allows menus to be invoked on any rendered commands with the flick of a switch (-m).

To follow along with these examples you’ll need to:

  $ gem install boson boson-more
  $ echo "require 'boson/more'" >> ~/.bosonrc
  # Note that --default rewrites your boson config to make menu_pipe a default library
  $ boson install https://github.com/cldwalker/irbfiles/raw/master/boson/commands/public/plugins/menu_pipe.rb --default

The Examples:

Chaining APIs
Opening and Editing Bookmarks within Rails
Playing Songs
Gemspecs Revisited

Chaining APIs

If you’re a rubyist, there’s a good chance your gems are on github and gemcutter. Using the github and gemcutter libraries, let’s look up a github user’s projects and then pass them to gemcutter to get their stats:

  # To follow along
  $ boson install https://github.com/cldwalker/irbfiles/raw/master/boson/commands/public/site/gemcutter.rb
  $ boson install https://github.com/cldwalker/irbfiles/raw/master/boson/commands/public/site/github.rb

  $ boson user_repos -u=wycats - -m  # or boson user_repos -u=wycats - --menu
  +--------+---------------------------+----------+-------+---------------------------------------+----------------------------------------------------------------------------------+--------------------+
  | number | name                      | watchers | forks | homepage                              | description                                                                      | url                |
  +--------+---------------------------+----------+-------+---------------------------------------+----------------------------------------------------------------------------------+--------------------+
  | 1      | bundler                   | 586      | 53    |                                       |                                                                                  | http://github.c... |
  | 2      | merb-core                 | 570      | 55    | http://www.merbivore.com              | Merb Core: All you need. None you don't.                                         | http://github.c... |
  | 3      | merb                      | 478      | 89    | http://www.merbivore.com              | master merb branch                                                               | http://github.c... |
  | 4      | thor                      | 429      | 34    | http://www.yehudakatz.com             | A scripting framework that replaces rake and sake                                | http://github.c... |
  | 5      | moneta                    | 323      | 24    | http://www.yehudakatz.com             | a unified interface to key/value stores                                          | http://github.c... |
  | 6      | merb-more                 | 295      | 30    | http://www.merbivore.com              | Merb More: The Full Stack. Take what you need; leave what you don't.             | http://github.c... |
  | 7      | merb-plugins              | 282      | 38    | http://www.merbivore.com              | Merb Plugins: Even more modules to hook up your Merb installation                | http://github.c... |
  | 8      | textmate                  | 134      | 8     | http://www.yehudakatz.com             | Command-line package manager for textmate                                        | http://github.c... |
  | 9      | jspec                     | 45       | 1     | http://www.yehudakatz.com             | A JavaScript BDD Testing Library                                                 | http://github.c... |
  | 10     | irb2                      | 44       | 1     |                                       |                                                                                  | http://github.c... |
  # ...
  38 rows in set
  Default command: browser
  Default field: url
  Choose:
  # Possible answers from user ...

  # To get gemcutter stats we use cuts()
  Choose: cuts 1-5:n
  Fetching gem 'bundler'
  Fetching gem 'merb-core'
  Fetching gem 'merb'
  Fetching gem 'thor'
  Fetching gem 'moneta'
  +-----------+-----------+-------------------------------------+------------------------------------------------------------+
  | name      | downloads | project_uri                         | info                                                       |
  +-----------+-----------+-------------------------------------+------------------------------------------------------------+
  | bundler   | 36890     | http://gemcutter.org/gems/bundler   | Bundles are fun                                            |
  | merb-core | 10281     | http://gemcutter.org/gems/merb-core | Merb. Pocket rocket web framework.                         |
  | merb      | 5923      | http://gemcutter.org/gems/merb      | (merb-core + merb-more + DM) == Merb stack                 |
  | thor      | 33921     | http://gemcutter.org/gems/thor      | A scripting framework that replaces rake, sake and rubigen |
  | moneta    | 1073      | http://gemcutter.org/gems/moneta    | A unified interface to key/value stores                    |
  +-----------+-----------+-------------------------------------+------------------------------------------------------------+
  5 rows in set

  # Since this is a 2d menu we could have done other actions like open repository urls
  # Notice that we don't have to pass a command since user_repos() already sets the default menu action to browser
  Choose: 1,3,5:u
  # Opens http://github.com/wycats/bundler, http://github.com/wycats/merb and http://github.com/wycats/moneta in browser

  # Or opened repository homepages
  Choose: 3,4:h
  # Opens http://www.merbivore.com and http://www.yehudakatz.com in browser

Nice! This is an easy way to see how popular (by downloads) a user’s gems are, as well as to open multiple projects quickly in a browser.

Opening and Editing Bookmarks within Rails

If you don’t use github or gemcutter much, perhaps menus used within a Rails project will be more interesting. Direct from tag-tree, my Rails bookmarking project:

  $ script/console

  # url_tagged_with() is a wrapper around a Url model's method to fetch records by machine tags
  # this fetches urls tagged as being articles with a class attribute
  >> url_tagged_with 'article:class --menu'   # or ut 'ar:cla -m'
  +--------+------+---------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
  | number | id   | name                                                          | description                                                   | quick_mode_tag_list                                           |
  +--------+------+---------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
  | 1      | 1877 | http://pivotallabs.com/users/jdean/blog/articles/911-equal... | explains what to override to have arrays of your objects e... | article:plang=ruby;class=array                                |
  | 2      | 1617 | http://blog.grayproductions.net/articles/understanding_m17n   | character encoding tutorial series                            | article:plang=ruby;class=string                               |
  | 3      | 1929 | http://yokolet.blogspot.com/2009/07/design-and-implementat... | decent overview of ruby's multilinguilization/encoding        | article:class=string                                          |
  | 4      | 1760 | http://timetobleed.com/5-things-you-dont-know-about-user-i... | explains why Process.euid is dangerous, decent intro to ni... | article:plang=ruby;class=process                              |
  | 5      | 1956 | http://www.engineyard.com/blog/2009/key-value-stores-in-ruby/ | decent intro to pstore from key/value perspective             | article:class=pstore                                          |
  | 6      | 1488 | http://redhanded.hobix.com/inspect/hoppingThroughPipesAndC... | piping with procs                                             | article:plang=ruby;class=proc                                 |
  | 7      | 1152 | http://innig.net/software/ruby/closures-in-ruby.rb            | closures in ruby                                              | article:plang=ruby;tutorial;class=proc                        |
  | 8      | 1278 | http://www.robertsosinski.com/2008/12/21/understanding-rub... | good overview of ruby lambdas +procs                          | article:plang=ruby;tutorial;class=proc                        |
  | 9      | 1292 | http://weblog.raganwald.com/2007/10/stringtoproc.html         | handy string proc method                                      | article:plang=ruby;class=proc                                 |
  | 10     | 2283 | http://yehudakatz.com/2010/02/07/the-building-blocks-of-ruby/ | nuanced but interesting blocks comparison w/ python           | article:class=proc                                            |
  | 11     | 2040 | http://blog.rubybestpractices.com/posts/rklemme/017-Struct... | points out some useful array + hash-like behavior for stru... | article:class=struct                                          |
  | 12     | 2056 | http://www.michaelharrison.ws/weblog/?p=163                   | easy lazy evaluation                                          | article:class=enumerator                                      |
  | 13     | 2079 | http://blog.rubybestpractices.com/posts/rklemme/018-Comple... | tips on common object overrides: equivalence,cloning,persi... | article:method=to_yaml_properties;method=eql;method=marsha... |
  | 14     | 2081 | http://blog.segment7.net/articles/2008/12/17/friendly-ruby... | common overrides for objects: marshal,pp,equality,exception   | article:class=object;method=exception;method=_dump            |
  +--------+------+---------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
  14 rows in set
  Default field: name
  Default command: browser
  Choose:
  # Possible answers from user ...

  # Opens last 3 urls in browser
  Choose: 12-14

  # Opens first five records in an editor to edit their attributes using console_update gem
  Choose: console_update 1-5:i

  # Add tag article:todo to urls 3-5
  Choose: ta 3-5 tag:todo

Playing Songs

This one is more for fun. I like to pick and play songs in the console using xmms2.

  # If you have xmms2 and want to follow along
  $ boson install https://github.com/cldwalker/irbfiles/raw/master/boson/commands/personal/xmms2.rb

  # Choose a directory to play
  $ boson play /mnt/m/rap

  # Search and choose a song
  $ boson search_songs Jay
  +--------+-------+----------------------------------------------------------------------+-------+
  | number | track | title                                                                | time  |
  +--------+-------+----------------------------------------------------------------------+-------+
  | 1      | 8     | Memphis Bleek ft. Jay Z - Is That Your Bitch                         | 04:38 |
  | 2      | 10    | Jay-Z - December 4Th                                                 | 04:34 |
  | 3      | 40    | Jay-Z - Kingdom Come (Produced By Just Blaze)                        | 04:24 |
  | 4      | 62    | Jay-Z - Big Pimpin                                                   | 04:43 |
  | 5      | 63    | Jay-Z - Lucifer                                                      | 03:12 |
  | 6      | 81    | Jay-Z - Lost Ones (Feat. Chrissette Michelle) (Produced By Dr. Dre)  | 03:44 |
  +--------+-------+----------------------------------------------------------------------+-------+
  Default field: track
  Default command: play_track
  Choose: 6
  # Starts playing last song

Gemspecs Revisited

Now that we’ve seen some menu examples, let’s make a boson command that can take a menu option using the above gemspecs example:

# You can just drop this in a local Bosonfile
module Bosonfile
  # @render_options :fields=>{:values=>[:name, :summary, :homepage, :authors], :default=>[:name, :homepage]}
  # @options :limit=>50
  # @config :menu=>{:command=>'browser', :default_field=>:homepage}
  def gemspecs(options={})
    ::Gem.source_index.gems.values[0,options[:limit]]
  end
end

As you can see, render_options takes the :fields option we were passing to menu(). I also added an optional gemspec limit. Notice the configuration for menu, which will come in handy soon. Let’s give this command a shot:

  # By default this displays the same table as before
  $ boson gemspecs
  +-----------------------------------+------------------------------------------------------+
  | name                              | homepage                                             |
  +-----------------------------------+------------------------------------------------------+
  | ruby-debug                        | http://rubyforge.org/projects/ruby-debug/            |
  | net-ssh-gateway                   | http://net-ssh.rubyforge.org/gateway                 |
  | mspec                             | http://rubyspec.org                                  |
  | yard                              | http://yardoc.org                                    |
  | rubyforge                         | http://codeforpeople.rubyforge.org/rubyforge/        |
  # ...
  50 rows in set

  # Now let's turn on a menu
  $ boson gemspecs -m
  +--------+-----------------------------------+------------------------------------------------------+
  | number | name                              | homepage                                             |
  +--------+-----------------------------------+------------------------------------------------------+
  | 1      | ruby-debug                        | http://rubyforge.org/projects/ruby-debug/            |
  | 2      | net-ssh-gateway                   | http://net-ssh.rubyforge.org/gateway                 |
  | 3      | mspec                             | http://rubyspec.org                                  |
  | 4      | yard                              | http://yardoc.org                                    |
  | 5      | rubyforge                         | http://codeforpeople.rubyforge.org/rubyforge/        |
  # ...
  50 rows in set
  Default field: homepage
  Default command: browser
  Choose:

  # Notice that the menu config set the menu's defaults.
  # With these defaults, we can open urls simply:
  # Open first five urls
  Choose: 1-5
  # To commit browser suicide by opening all homepages
  Choose: *

Final Thoughts

As we’ve seen, hirb’s 2D menus provide a useful way of picking multiple values from table cells. Combining this with menu actions makes for a quick and interactive way to pass values between methods. Boson takes advantage of all this by allowing any of its commands to pipe values to any other command. From the gemspec example, we saw that no extra code is required to give a boson command access to this powerful menu system. If you’re interested in playing with more menu-based commands, try the github library. With it you can use menus to perform actions on user gists, user and repository searches, repository commit lists, repository networks and more.

Using Gemcutter's Api from the Commandline

2010-02-03T00:00:00-08:00

Gemcutter recently added a sweet search call to its API. With gemcutter’s API and boson, we’ll see how to search gems, get a gem’s information and compare multiple gems on the commandline. Also, I’ll explain how some of this was done so you’re able to make commands for any API.

If you’re more interested in how this library is built, skip to here.

To use this boson library:

  $ gem install boson boson-more
  $ echo "require 'boson/more'" >> ~/.bosonrc
  $ boson install https://github.com/cldwalker/irbfiles/raw/master/boson/commands/public/site/gemcutter.rb

Usage

This gemcutter CLI comes with three commands. The first command is gem_search:

  # basic search
  bash> boson gem_search command
  +---------------------+-----------+---------------------------------------------------------------------------------------+---------------------------------------------------------------+
  | name                | downloads | info                                                                                  | authors                                                       |
  +---------------------+-----------+---------------------------------------------------------------------------------------+---------------------------------------------------------------+
  | rubyforge           | 70823     | A script which automates a limited set of rubyforge operations.\n\n* Run 'rubyforg... | Ryan Davis, Eric Hodel, Ara T Howard, Tom Copeland            |
  | gemcutter           | 69607     | Adds several commands to RubyGems for managing gems and more on Gemcutter.org.        | Nick Quaranto                                                 |
  | hoe                 | 68058     | Hoe is a rake/rubygems helper for project Rakefiles. It helps you\nmanage and main... | Ryan Davis                                                    |
  | capistrano          | 55740     | Capistrano is a utility and framework for executing commands in parallel on multip... | Jamis Buck, Lee Hambley                                       |
  # ...
  30 rows in set

  # Let's go the second page of the previous query
  bash> boson gem_search command -p2
  +--------------+-----------+------------------------------------------------------------------------------------------+--------------------------------------------------------------+
  | name         | downloads | info                                                                                     | authors                                                      |
  +--------------+-----------+------------------------------------------------------------------------------------------+--------------------------------------------------------------+
  | vlad         | 2173      | Vlad the Deployer is pragmatic application deployment automation,\nwithout mercy. Muc... | Ryan Davis, Eric Hodel, Wilson Bilkovich                     |
  | sys-uname    | 2161      |     The sys-uname library provides an interface for gathering information\n    about ... | Daniel J. Berger                                             |
  | cmdparse     | 1943      | cmdparse provides classes for parsing commands on the command line; command line opti... | Thomas Leitner                                               |
  | backup       | 1862      | \n                            Backup is a Ruby Gem written for Unix and Rails environ... | Michael van Rooijen                                          |
  # ...
  30 rows in set

  # multi word search
  bash> boson gem_search rails plugin
  +--------------------------------+-----------+--------------------------------------------------------------------------------+--------------------------------------------------------------------------------+
  | name                           | downloads | info                                                                           | authors                                                                        |
  +--------------------------------+-----------+--------------------------------------------------------------------------------+--------------------------------------------------------------------------------+
  | will_paginate                  | 42886     | The will_paginate library provides a simple, yet powerful and extensible AP... | Mislav Marohnić, PJ Hyett                                                      |
  | aasm                           | 7638      | AASM is a continuation of the acts as state machine rails plugin, built for... | Scott Barron, Scott Petersen, Travis Tilley                                    |
  | after_commit                   | 7016      | \n    A Ruby on Rails plugin to add an after_commit callback. This can be u... | Nick Muerdter, David Yip, Pat Allan                                            |
  | rails_datamapper               | 2124      | Rails Plugin for DataMapper                                                    | Tom Malone                                                                     |
  # ...
  30 rows in set
  
  # with no search term, defaults to all-time top-downloaded gems
  # no surprises here
  bash> boson gem_search
  +-----------------+-----------+----------------------------------------------------------------------------------------+----------------------------------------------------+
  | name            | downloads | info                                                                                   | authors                                            |
  +-----------------+-----------+----------------------------------------------------------------------------------------+----------------------------------------------------+
  | activesupport   | 319341    | Utility library which carries commonly used classes and goodies from the Rails fram... | David Heinemeier Hansson                           |
  | activerecord    | 293266    | Implements the ActiveRecord pattern (Fowler, PoEAA) for ORM. It ties database table... | David Heinemeier Hansson                           |
  | actionpack      | 287332    | Eases web-request routing, handling, and response as a half-way front, half-way pag... | David Heinemeier Hansson                           |
  | rails           | 287005    |     Rails is a framework for building web-application using CGI, FCGI, mod_ruby, or... | David Heinemeier Hansson                           |
  | rack            | 285612    | Rack provides minimal, modular and adaptable interface for developing\nweb applicat... | Christian Neukirchen                               |
  # ...
  30 rows in set

If you’re not familiar with boson, you may be surprised with how many options are available by default to control how and what you see:

  # Only see the name and info fields
  bash> boson gem_search tag -f=n,i   # or --fields=name,info
 +---------------------+------------------------------------------------------------------------------------------------------------------------------+
  | name                | info                                                                                                                         |
  +---------------------+------------------------------------------------------------------------------------------------------------------------------+
  | haml                |       Haml (HTML Abstraction Markup Language) is a layer on top of XHTML or XML\n      that's designed to express the str... |
  | libxml-ruby         | The Libxml-Ruby project provides Ruby language bindings for the GNOME Libxml2 XML toolkit. It is free software, released ... |
  | win32-api           |       The Win32::API library is meant as a replacement for the Win32API\n      library that ships as part of the standard... |
  | haml-edge           |       Haml (HTML Abstraction Markup Language) is a layer on top of XHTML or XML\n      that's designed to express the str... |
   # ...
   30 rows in set
  
   # Sort by authors
   bash> boson gem_search tag -s=a   # or --sort=authors
   +---------------------+-----------+--------------------------------------------------------+--------------------------------------------------------+
   | name                | downloads | info                                                   | authors                                                |
   +---------------------+-----------+--------------------------------------------------------+--------------------------------------------------------+
   | calais              | 489       | A Ruby interface to the Calais Web Service             | Abhay Kumar                                            |
   | stage               | 506       | Code template generator for Rails and Merb that DRY... | Andrew Stone                                           |
   | tagz                | 779       |         tagz.rb is generates html, xml, or any sgml... | Ara T. Howard                                          |
   | dm-tags             | 1985      | This package brings tagging to DataMapper.  It is i... | Bobby Calderwood                                       |
   | libxml-ruby         | 21789     | The Libxml-Ruby project provides Ruby language bind... | Charlie Savage                                         |
   | win32-api           | 14810     |       The Win32::API library is meant as a replacem... | Daniel J. Berger, Park Heesob                          |
   # ...
   30 rows in set

  # Show all fields, displaying a paged vertical table
  bash> boson gem_search tag -f=* -V
  ************************* 1. row *************************
            authors: Nathan Weizenbaum, Hampton Catlin
       dependencies: {"development"=>[{"name"=>"maruku", "requirements"=>">= 0.5.9"}, {"name"=>"yard", "requirements"=>">= 0.4.0"}], "runtime"=>[]}
          downloads: 85590
            gem_uri: http://gemcutter.org/gems/haml-2.2.17.gem
               info:       Haml (HTML Abstraction Markup Language) is a layer on top of XHTML or XML
        that's designed to express the structure of XHTML or XML documents
        in a non-repetitive, elegant, easy way,
        using indentation rather than closing tags
        and allowing Ruby to be embedded with ease.
        It was originally envisioned as a plugin for Ruby on Rails,
        but it can function as a stand-alone templating engine.

               name: haml
        project_uri: http://gemcutter.org/gems/haml
            version: 2.2.17
  version_downloads: 25104
  ************************* 2. row *************************
  # Remaining records are paged ...

  # To get more help on this command
  bash> boson gem_search -hv
  # ...

The second command we’ll look at is cut, which displays gemcutter’s information on a gem:

  bash> boson cut rails
  +-------------------+--------------------------------------------------------------------------------------------------------------------------------+
  | field             | value                                                                                                                          |
  +-------------------+--------------------------------------------------------------------------------------------------------------------------------+
  | name              | "rails"                                                                                                                        |
  | downloads         | 287086                                                                                                                         |
  | info              | "    Rails is a framework for building web-application using CGI, FCGI, mod_ruby, or WEBrick\n    on top of either MySQL, P... |
  | version           | "2.3.5"                                                                                                                        |
  | project_uri       | "http://gemcutter.org/gems/rails"                                                                                              |
  | gem_uri           | "http://gemcutter.org/gems/rails-2.3.5.gem"                                                                                    |
  | version_downloads | 189219                                                                                                                         |
  | authors           | "David Heinemeier Hansson"                                                                                                     |
  | dependencies      | {"development"=>[], "runtime"=>[{"name"=>"activeresource", "requirements"=>"= 2.3.5"}, {"name"=>"actionmailer", "requiremen... |
  +-------------------+--------------------------------------------------------------------------------------------------------------------------------+
  9 rows in set

The third command is cuts, which lists multiple gems. This command is perfect for comparing gems i.e. mocking gems:

  bash> boson cuts rr mocha flexmock facon
  Fetching gem 'rr'
  Fetching gem 'mocha'
  Fetching gem 'flexmock'
  Fetching gem 'facon'
  +----------+-----------+------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
  | name     | downloads | project_uri                        | info                                                                                                                                              |
  +----------+-----------+------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
  | rr       | 4973      | http://gemcutter.org/gems/rr       | RR (Double Ruby) is a double framework that features a rich selection of double techniques and a terse syntax. http://xunitpatterns.com/Test%2... |
  | mocha    | 19703     | http://gemcutter.org/gems/mocha    |       Mocking and stubbing library with JMock/SchMock syntax, which allows mocking and stubbing of methods on real (non-mock) classes.\n          |
  | flexmock | 4527      | http://gemcutter.org/gems/flexmock | FlexMock is a extremely simple mock object class compatible with the Test::Unit framework.  Although the FlexMock's  interface is simple, it i... |
  | facon    | 291       | http://gemcutter.org/gems/facon    | A mocking library in the spirit of the Bacon spec library. Small, compact, and works with Bacon.                                                  |
  +----------+-----------+------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
  4 rows in set

Now, if you want to use these commands but with shorter command names or different default fields displayed, you should read up on boson.

So how hard was it to create this CLI? Not hard at all …

Explanation

To understand this console interface to gemcutter, let’s look at creating the gem_search command.

First, as gemcutter’s api docs explain, a search request looks like /api/v1/search.(json|xml)?query=[QUERY]. Let’s consider what we’ll do with this api call:

1. Make a get request to get back a string.
2. Convert the string into a ruby object by parsing the format (xml or json).
3. Display the ruby object in a well-formatted, useful way.

Step 1 can be done with the standard library net/http i.e. Net::HTTP.get(URI.parse(url)). We’ll just use boson’s get() command which wraps around this. For step 2, we’ll parse json using JSON.parse. If you’re on 1.9, you should already have the json library. Otherwise, sudo gem install json should set you up. For step 3, we’ll use hirb’s handy tables which integrate nicely with boson.

Taking the first two steps, the boson command looks like this:

require 'json'

module Gemcutter
  def gem_search(query)
    JSON.parse get("http://gemcutter.org/api/v1/search.json?query=#{query}")
  end
end

Pretty straightforward. To try this command, drop it in a local Bosonfile and …

  # Knowing nothing about the returned data structure, boson attempts to format it
  bash> boson gem_search tag
  +---------------------------+---------------------------+-----------+---------------------------+---------------------------+---------------------+---------------------------+-----------+-------------------+
  | authors                   | dependencies              | downloads | gem_uri                   | info                      | name                | project_uri               | version   | version_downloads |
  +---------------------------+---------------------------+-----------+---------------------------+---------------------------+---------------------+---------------------------+-----------+-------------------+
  | Nathan Weizenbaum, Ham... | developmentnamemarukur... | 85521     | http://gemcutter.org/g... |       Haml (HTML Abstr... | haml                | http://gemcutter.org/g... | 2.2.17    | 25048             |
  | Charlie Savage            | developmentruntime        | 21769     | http://gemcutter.org/g... | The Libxml-Ruby projec... | libxml-ruby         | http://gemcutter.org/g... | 1.1.3     | 18167             |
  | Daniel J. Berger, Park... | developmentnametest-un... | 14794     | http://gemcutter.org/g... |       The Win32::API l... | win32-api           | http://gemcutter.org/g... | 1.4.5     | 3973              |
  # ...
  # It's a mess.

  # Knowing that we're supposed to be getting back an array of gems
  # let's inspect one of the results
  bash> boson -e "p gem_search('tag')[0]"
  {"name"=>"haml", "downloads"=>85525, "info"=>"      Haml (HTML Abstraction Markup Language) is a layer on top of XHTML or XML\n      
  that's designed to express the structure of XHTML or XML documents\n      in a non-repetitive, elegant, easy way,\n      using indentation 
  rather than closing tags\n      and allowing Ruby to be embedded with ease.\n      It was originally envisioned as a plugin for Ruby on 
  Rails,\n      but it can function as a stand-alone templating engine.\n", "version"=>"2.2.17", 
  "project_uri"=>"http://gemcutter.org/gems/haml", "gem_uri"=>"http://gemcutter.org/gems/haml-2.2.17.gem", "version_downloads"=>25052, 
  "authors"=>"Nathan Weizenbaum, Hampton Catlin", "dependencies"=>{"development"=>[{"name"=>"maruku", "requirements"=>">= 0.5.9"}, 
  {"name"=>"yard", "requirements"=>">= 0.4.0"}], "runtime"=>[]}}

  # Ok, a gem is a hash. But with what fields?
  bash> boson -e "p gem_search('tag')[0].keys"
  ["name", "downloads", "info", "version", "project_uri", "gem_uri", "version_downloads", "authors", "dependencies"]

Now for the third step. Let’s configure the table fields rendered for our api call with render_options(). In keeping with boson’s philosophy, we’ll write it in commented form:

require 'json'

module Gemcutter
  # @render_options :fields=>{:default=>%w{name downloads info authors},
  #  :values=>%w{name authors version_downloads info project_uri gem_uri version downloads dependencies} },
  #  :filters=>{:default=>{'dependencies'=>:inspect}}
  # Search gemcutter
  def gem_search(query)
    JSON.parse get("http://gemcutter.org/api/v1/search.json?query=#{query}")
  end
end

Note that we passed two keys to render_options: :fields and :filters. For :fields we pass :default to specify default fields and :values to specify all values for :fields. Now let’s give this command a test drive:

  bash> boson gem_search tagging
  +---------------------------------+-----------+---------------------------------------------------------------------+--------------------------------+
  | name                            | downloads | info                                                                | authors                        |
  +---------------------------------+-----------+---------------------------------------------------------------------+--------------------------------+
  | dm-tags                         | 1989      | This package brings tagging to DataMapper.  It is inspired by Ac... | Bobby Calderwood               |
  | sup                             | 1840      | Sup is a console-based email client for people with a lot of ema... | William Morgan                 |
  | tagomatic                       | 634       | = tagomatic\n\nSimple command-line mp3 tagger based on mp3info g... | Daniel Lukic                   |
  | CachedSupermodel                | 610       | Based on cached_model by <a href="http://dev.robotcoop.c... | adocca Entertainment AB        |
  # ...
  30 rows in set

  # Having specified available fields above, we can use aliased versions of fields
  # when referring to them.

  # Let's only see the numerical fields
  bash> boson gem_search tag -f=n,do,version_d,v  # or --fields=name,downloads,version_downloads,version
  +---------------------+-----------+-------------------+-----------+
  | name                | downloads | version_downloads | version   |
  +---------------------+-----------+-------------------+-----------+
  | haml                | 85579     | 25097             | 2.2.17    |
  | libxml-ruby         | 21784     | 18180             | 1.1.3     |
  | win32-api           | 14809     | 3978              | 1.4.5     |
  | haml-edge           | 11241     | 3555              | 2.3.100   |
  # ...
  30 rows in set

Success! How about the pagination option and multi-word search we saw above? Source code says it all.

Wrap Up

As we’ve seen with the gemcutter API, boson makes it dead easy to interface to an API from the commandline. If you’re interested in more boson-wrapped APIs, I’d recommend github or anything under here. And if you don’t already know, we can use any of these api commands in irb thanks to boson’s shell/irb duality.

Typing Less in Irb with method_missing

2010-01-26T00:00:00-08:00

First off, Happy New Year! Now back to our regularly scheduled program.

Being the console-efficient prick I am, let’s look at a method_missing that let’s us type less where underscored methods are involved. This means that instead of typing some_really_long_ass_method we can type the shortcut method s_r_l_a_s. Instant aliasing! As you can see this works by typing the beginning letter of each word separated by underscores.

So why do this if we have autocompletion? For starters, try typing the Object method instance_variable_get in five keystrokes (tabs included). Or for more inefficiency, try typing ActiveRecord class methods that start with before_* and validate_*.

Explanation

To write this method_missing, we’re going to need a method that finds methods given a shortcut method we type:

  def underscore_search(input, list)
    if input.include?("_")
      underscore_regex = input.split('_').map {|e| Regexp.escape(e) }.join("([^_]+)?_")
      list.select {|e| e.to_s =~ /^#{underscore_regex}/ }
    else
      escaped_input = Regexp.escape(input)
      list.select {|e| e.to_s =~ /^#{escaped_input}/ }
    end
  end

If you try this out in irb, it works as follows:

  # Doing the same as autocompletion would
  >> underscore_search 'si', %w{set_trace_func singleton_methods select}%
  => ['singleton_methods']

  # Doing something autocompletion can't do
  >> underscore_search 'i_v_g', %w{instance_of? instance_variables instance_variable_get instance_eval}%
  => ['instance_variable_get']

  # If our shortcut method is too broad we get multiple results
  >> underscore_search 'i_v', %w{instance_of? instance_variables instance_variable_get instance_eval}%
  => ['instance_variables', 'instance_variable_get']

  # Multiple letters can be typed per underscore
  >> underscore_search 're_o_ag', %w{reflect_on_aggregation reflect_on_association raise_on_association}
  => ['reflect_on_aggregation']

Now that we have a way of querying underscore methods, let’s wrap a method_missing around it:

  def method_missing(meth, *args, &block)
    possible_methods = self.methods.map {|e| e.to_s }.sort
    meths = underscore_search(meth.to_s, possible_methods)

    if meths.size > 1
      puts "Multiple methods match: #{meths.join(', ')}"
    elsif (meths.size == 1)
      send(meths[0], *args, &block)
    else
      super
    end
  end

After pasting method_missing() and underscore_search() in irb:

  # Calls private_methods()
  >> pri_m
  => [...]

  # Method queries that match multiple methods don't get executed
  >> pr_m
  Multiple methods match: private_methods, protected_methods
  => nil

  # method_missing works as normal for method queries that don't match anything
  >> blah
  NameError: undefined local variable or method `blah' for main:Object
          from /Users/bozo/.boson/commands/public/underscore_alias.rb:57:in `method_missing'
          from (irb):8

Finished Snippet

To make this snippet easy to apply to any object or class of objects, I wrapped method_missing
into a module and did a little more meta programming. The result is this
module.
If you use boson to manage your ruby snippets: boson install https://github.com/cldwalker/irbfiles/raw/master/boson/commands/public/underscore_alias.rb.

Here’s how I use the finished snippet in a Rails console session:

  bash> script/console

  # Load UnderscoreAlias
  >> load 'path/to/underscore_alias.rb'
  # If using boson
  >> load_library 'underscore_alias'

  # Let's give an ActiveRecord model class (i.e. Url) underscore aliasing abilities
  >> Url.extend UnderscoreAlias
  => Url

  # Call Url.original_table_name
  >> Url.o_t
  => 'urls'

  # Call Url.columns_hash
  >> Url.col_h
  => {"name"=> #< ActiveRecord::ConnectionAdapters::MysqlColumn:0x23766d8 @type=:string, @precision=nil ...>,
  "updated_at"=> ...}

  # Now let's give ActiveRecord objects underscore aliasing abilities
  >> Url.send :include, UnderscoreAlias
  => Url

  # Call Url#to_json
  >> Url.first.t_j
  => "{\"url\":{\"name\":\"http://github.com\", ... }"

  # Call Url#clear_association_cache
  >> Url.first.c_as
  => [...]

  # Call Url#has_attribute?
  >> Url.first.h_a 'name'
  => true

When using the above snippet, you may find it annoying that sometimes a shortcut method results in a multiple choices that vary only by ending i.e. updated_at? updated_at updated_at=. If only there was a way to autocomplete like this … Actually, bond accomplished this a while ago.

Now a general question to you all: Would you find it useful to apply this same instant aliasing technique to your rake/thor commandline tasks? For example, typing r:u:s instead of rails:update:scripts? I have found this instant aliasing technique to be quite handy with boson’s commands, arguments and options.

Boson - Command Your Ruby Universe - Part Deux

2009-11-21T00:00:00-08:00

With the latest release of Boson, there are a slew of new features that need some explaining. Yes, there is a changelog and documentation, but some of these features are novel enough that a good intro is in order.

Overview

Here’s an overview of features:

Command Options
- Pipe Options
- Query Option
Libraries
Option Parser
- Option to Object Mapper
- Custom Option Types
Miscellaneous

Command Options

Boson is unique among command frameworks for providing commands with global options. Global options are options that are common to all commands (that enable options). There are three types of global options: basic options, render options and pipe options. The first two were covered in this previous post. Now let’s a take a look at the newcomer, pipe options.

Pipe Options

Whereas render options generate different views from a command’s return value, pipe options pipe a command’s return value to command(s). Since a pipe option maps directly to a command, using piping options is much like piping between unix commands but asynchronously.

For example, say we have pipe options --browser and --copy which given a url, open it in a browser and copy it to clipboard respectively:

  bash> irb
  # Assume a command generate_url which returns a url string
  >> generate_url
  => 'http://example.com'

  # With the assumed global pipe options, let's apply them to the return value of generate_url
  >> generate_url '-bC'   #  or generate_url '--browser --copy'
  => 'http://example.com'

  # The above one liner is functionally equivalent to the following three lines
  >> url = generate_url
  >> browser(url)
  >> copy(url)

  # In a unix shell assuming boson commands are shell commands we could do the above as
  bash> generate_url | browser
  bash> generate_url | copy

Now that you understand what pipe options do, here’s how you set it up:

  # Let's set up the commands for mac osx:
  # browser() already ships with boson.

  # Drop this in a library that gets loaded with :defaults config key
  def copy(str)
    IO.popen('pbcopy', 'w+') {|clipboard| clipboard.write(str)}
  end

  # Configure them in ~/.boson/config/boson.yml
  :pipe_options:
    :browser:
      :type: :boolean
      :desc: Open in browser
    :copy:
      :type: :boolean
      :desc: Copy to clipboard

As you’ve noticed, pipe options are returning the command’s original return value. To have pipe options behave like unix pipes (i.e. the return value changes per pipe), add a :filter: true to a pipe option’s config. See here for more pipe docs.

Query Option

As explained at the end of a previous post, this option used to be --query_fields. This option is a default pipe option that queries an array of anything with a search hash. Since this option is a :hash option type, check the docs for a syntax overview. Some examples with default commands:

  # A query field is delimited from its query value with ':'
  # Like arrays, hash keys can be aliased if the field keys are known.
  bash> boson commands -q=f:lib     # or commands --query=full_name:lib

  # With the new format all fields can be queried using a '*'.
  # Searches library fields: gems,dependencies,commands,loaded,module,name,namespace,indexed_namespace,library_type
  bash> boson libraries -q=*:core   # or libraries --query=*:core

  # Multiple searches to be joined together by ','. This query searches for libraries that
  # have the name matching core or a library_type matching gem.
  bash> boson libraries -q=n:core,l:gem   # or libraries --query=name:core,library_type:gem

For examples of the different kinds of arrays that query can search, see the previous post.

Libraries

Boson’s libraries, which are just modules, are loaded by being included in main ‘s eigenclass. During its loading process, a module’s include callbacks are called i.e. included as well as boson-specific ones i.e. after_included. Read the docs for an explanation of these callbacks.

Local Libraries

Like most command frameworks, Boson now supports local command libraries. For just one library, simply create a Bosonfile and write commands as you would for any Boson::FileLibrary. For multiple libraries, create the directory lib/boson/commands or .boson/commands and place libraries under the directory. For more, see the docs.

Directory-Spaced Libraries

Like Thor, Boson has a central repository for its libraries so that the user can invoke commands from any directory. For Boson, these libraries are stored at ~/.boson/commands/. With this release, any subdirectory in this directory is automatically namespaced when loaded. What this means for the user is that they can create any number/depth of directories without worry that a module in one directory will conflict with a module in another. As an example say that I use the module Misc in two different directories, ~/.boson/commands/public and ~/.boson/commands/personal. Boson will load Misc as Boson::Commands::Public::Misc and Boson::Commands::Personal::Misc respectively. This makes it very convenient to collect and organize a large number of libraries. If it means anything, my main repository’s current count is 87 libraries and 284 commands.

Social Libraries

As I explained before, Boson’s libraries are easy to share with others. Simply give a url to a plain text version of your library and other users can install it. What I didn’t explain was that you can customize any attribute of the library and its commands without touching the installed library.

For this example, we’ll use the github library. To install it:

  bash> boson install https://github.com/cldwalker/irbfiles/raw/master/boson/commands/public/site/github.rb
  Saved to /Users/bozo/.boson/commands/github.rb

  # How one of the library's commands looks before we customize
  bash> boson commands user_repo
  +------------+--------+-------+------------------------------------------------+--------------------------------+
  | full_name  | lib    | alias | usage                                          | description                    |
  +------------+--------+-------+------------------------------------------------+--------------------------------+
  | user_repos | github |       | [--user=cldwalker] [--fork_included] [--stats] | Displays a user's repositories |
  +------------+--------+-------+------------------------------------------------+--------------------------------+
  1 row in set

Let’s add an alias and change the options and description of the above user_repos command:

  # Add entry under the :libraries key of config file ~/.boson/config/boson.yml
  :libraries:
    github:
      :commands:
        user_repos:
          :alias: guser
          :description: Github user page
          :options:
            :user: rails
    
  # Reindex library to pick up the config change
  bash> boson -i=github commands user_repo  # or --index=github commands user_repo
  Indexing the following libraries: github
  Loaded library github
  +------------+--------+-------+--------------------------------------------+------------------+
  | full_name  | lib    | alias | usage                                      | description      |
  +------------+--------+-------+--------------------------------------------+------------------+
  | user_repos | github | guser | [--user=rails] [--fork_included] [--stats] | Github user page |
  +------------+--------+-------+--------------------------------------------+------------------+
  1 row in set

  # Calls user_repos defaulting to rails user
  bash> boson guser
  +-------------------------+----------+-------+-----------------------------------+-------------------------------------------+
  | name                    | watchers | forks | homepage                          | description                               |
  +-------------------------+----------+-------+-----------------------------------+-------------------------------------------+
  | rails                   | 4468     | 718   | http://rubyonrails.org            | Ruby on Rails                             |
  | account_location        | 82       | 2     | http://rubyonrails.org            | Account Location Plugin                   |
  | acts_as_list            | 251      | 28    | http://rubyonrails.org            | ActsAsList plugin                         |
  | acts_as_nested_set      | 43       | 7     | http://rubyonrails.org            | ActsAsNestedSet                           |
  # ...

You’ve just seen how Boson can customize command invocation via :alias and functionality via :options without modifying the command’s source. Since commands are functionally equivalent to scripts, this has interesting implications for scripting. This basically allows us to use and preserve third-party scripts without being bound to the author’s naming/aliasing of commands and options. By preserving a script’s source, we can update our third-party scripts when new versions come out. Perhaps Boson’s script/command configuration will make scripting more social.

Invoking Commands

If you don’t already know, Boson’s commands are just methods on main, Ruby’s top-level object. What this means is that the self inside of any Boson command is main. Once a command is loaded, it’s available across libraries as a top-level method. For example:

  # Drop this in ~/.boson/commands/input.rb
  module Input
    def ask(prompt)
      print prompt + ' '
      gets.strip
    end
  end

  # Now let's use this in another library
  module Quarantine
    # A boson callback to specify a library's configuration
    def self.config
      {:dependencies=>['input']}
    end

    # Opens a reddit url in browser. Is it really worth it?
    def reddit(url)
      if ask("Are you sure you want to do this to yourself? (y/N)")[/^y/i]
        browser(url)
      end
    end
  end

As you can see, there is no Rake::Task['reddit'].invoke(url) or Quarantine.new.invoke(:reddit, url) as with Rake and Thor respectively. Invoking commands from different libraries is done in plain ruby per Boson’s philosophy. With this philosophy, you can still use these commands without Boson.

  >> obj = Object.new.extend(Input).extend(Quarantine)
  >> obj.reddit('lovely reddit url')

Library Dependencies

In the above command invocation example, you probably noticed that the quarantine library depends on the input library. Boson supports libraries depending on other libraries. This begins to show the collaborative and swappable nature of Boson libraries. Swappable in that you could swap one library for another as a dependency as long as it implements the same methods and api. Collaborative in that the functionality defined in one library can be made available to any another without modifying any code. Personally, this is is an improvement over having a directory full of scripts that can’t communicate and depend on each other.

Plugin Libraries

While Boson has a number of features, you may want to add/modify some of them. No problem. Boson’s config file has a :defaults key to load up specified Boson libraries at startup. From the Invoking Commands section, if we wanted to make the ask method available to all libraries, we would specify the input library under :defaults. For more examples, see my plugins.

Option Parser

With this release, Boson’s option parser is available for any Ruby scripts. For example:

#!/usr/bin/env ruby

require 'rubygems'
require 'boson'

# Define options and parse them from ARGV into a hash
options = Boson::OptionParser.parse(:verbose=>:boolean, :times=>:numeric, :help=>:boolean)
return puts("$0 #{Boson::OptionParser.usage}") if options[:help]

# Process remaining args in ARGV ...

Since Boson has dependencies, I’d consider making Boson’s OptionParser a separate gem if requested.

Option to Object Mapper

With this release, Boson’s option parser has become an option-to-object mapper. To understand what that means, let’s see Boson’s five default option types and the Ruby objects they create. First, we create a library:

  # Drop in ~/.boson/commands/option_test.rb
  module OptionTest
    options :a=>:array, :b=>:hash, :c=>:string, :d=>:numeric, :e=>:boolean
    def testin(options={})
      p options
      p options.each {|k,v| options[k] = v.class }
    end

    # The default for :hash has to be passed as a :default attribute since hashes
    # are already reserved for setting option attributes.
    options :a=>[1,2], :b=>{:default=>{:a=>1}}, :c=>'yo', :d=>1.3, :e=>false
    def testin2(options={})
      p options
      p options.each {|k,v| options[k] = v.class }
    end
  end

Then, back in the shell:

  # Each option type maps to a different ruby object. The classes of most of these objects
  # match directly to the option type's name.
  bash> boson testin -a=1,2 -b a:b,c:d -c=hey -d 1 -e
  {:e=>true, :d=>1, :b=>{"a"=>"b", "c"=>"d"}, :c=>"hey", :a=>["1", "2"]}
  {:e=>TrueClass, :d=>Fixnum, :b=>Hash, :c=>String, :a=>Array}

  # Each option type has an expected format it uses for converting to an object as indicated
  # by the usage.
  bash> boson testin -h
  testin [-c=C] [-d=N] [-e] [-a=A,B,C] [-b=A:B,C:D]

  # When options are defined with default values, the parser uses the default value's class to determine
  # the appropriate option type.
  # As expected, whatever option isn't set has its default value set.
  bash> boson testin2 -b=z:y -d=2.1
  {:e=>false, :d=>2.1, :b=>{"z"=>"y"}, :c=>"yo", :a=>[1, 2]}
  {:e=>FalseClass, :d=>Float, :b=>Hash, :c=>String, :a=>Array}

As you can see, an option type maps to objects of one or more Ruby classes i.e. :array → Array and :numeric → Float or Fixnum. But what if you want to create objects of other classes?

Custom Option Types

To define an option type that creates objects of your choice, you only need to define the method that creates the object. Here’s a basic example to create a :date option type that creates Date objects:

  # Drop this in ~/.boson/commands/date.rb
  # Then make this library a plugin by putting it
  # under :defaults key in the main config
  module ::Boson::Options::Date
    def create_date(value)
     Date.parse(value + "/#{Date.today.year}")
    end
  end

  ::Boson::OptionParser.send :include, ::Boson::Options::Date

  # ====
  # Now in any library we can use the :date option type ...
  # Drop this in ~/.boson/commands/date_test.rb
  module DateTest
    options :day=>:date
    def day_of_week(options={})
      puts "#{options[:day]} falls on a #{Date::DAYNAMES[options[:day].cwday]}"
    end
    # to define :day with a default we could modify options to be:
    # options :day=>Date.today
  end

Now to try day_of_week:

  bash> boson day_of_week -d 12/25   # or day_of_week --date 12/25
  2009-12-25 falls on a Friday

  # Default usage for new option type
  bash> boson day_of_week -h
  day_of_week [--day=:date]

As you saw, simply creating a method with the name create_@type in the option parser made the option type available. If you want to add validation or custom usage for a new option type, see the docs. When creating your own option types, you may find it cleaner to define your options in a plugin library.

Miscellaneous

Now for some miscellaneous features.

Custom Consoles

Being able to start irb around certain setups you use often can be quite handy. Good examples of this are Rails’ script/console and the more recent racksh. Boson makes it easy to start irb with specified Boson libraries loaded:

  # Assuming you have a library github
  bash> boson -l=g -c   # or boson --load=github --console

  # Assuming you have libraries misc and ruby_ref
  bash> boson -l=m,r -c  # or boson --load=misc,ruby_ref --console
  
  # Irb can require libraries in a more verbose way but it *doesn't*
  # load Boson libraries as commands
  bash> irb -I ~/.boson/commands -r misc -r ruby_ref

Powerful One-Liners

Much like ruby -e, you can do a boson -e with any ruby code. The big difference is that any Boson command is available and loaded lazily automatically:

  # Drop in ~/.boson/commands/objects.rb
  module Objects
    def objects(klass)
      object = []
      ObjectSpace.each_object(klass) {|e| object.push(e) }
      object
    end
  end

  # Prints number of String objects
  bash> boson -e 'p objects(String).size'  # or boson --execute 'p objects(String).size'
  56573

  # Prints default classes not including its defaults
  bash> boson -e 'p objects(Class).select {|e| e.to_s !~ /^(Boson|Alias|Hirb)/ }'
  [Gem::LoadError, Struct::Group, Struct::Passwd, SizedQueue, Queue, ConditionVariable, Mutex, Gem::Builder, Gem::SourceIndex, Binding,
   UnboundMethod, Method, Proc, SystemStackError, LocalJumpError, Struct::Tms, Process::Status, Time, Dir, File::Stat, File, IO, EOFError,
   IOError, Range, MatchData, Regexp, RegexpError, Struct, Hash, Array, Errno::EDQUOT, Errno::ESTALE, Errno::EINPROGRESS, Errno::EALREADY
  # ...

Method Commandification

This feature redefines a method to act like a shell command using Boson::Scientist.commandify. This means that a method can take any number of arguments and options as one string. Since Boson commands already do this automatically, this feature is for those who want to give this functionality to any method:

  >> def checkit(*args); args; end
  => nil
  >> Boson::Scientist.commandify(self, :name=>'checkit', :options=>{:verbose=>:boolean, :num=>:numeric})
  => ['checkit']
  # regular invocation
  >> checkit 'one', 'two', :num=>13, :verbose=>true
  => ["one", "two", {:num=>13, :verbose=>true}]
  # commandline invocation
  >> checkit 'one two -v -n=13'
  => ["one", "two", {:num=>13, :verbose=>true}]

Ruby Reference Commands With Boson

2009-11-07T00:00:00-08:00

Continuing where this post left off, we’ll look at more examples of the unique command and view framework interaction that Boson and Hirb have. In particular, we’ll look at commands that are useful references to your current Ruby environment. Since Boson’s commands are just methods in a module, any of these commands work fine in irb without Boson.

Game Plan

We’ll be looking at my ruby_ref library and commands that reference:

Global variables
Loaded paths and their respective full paths
Gems and their versions
Any object’s instance variables
RbConfig

For all these commands, I will only show the original ruby method. To see the Boson configuration for each, see the library source.

To follow along with the examples using boson:

  $ gem install boson boson-more
  $ echo "require 'boson/more'" >> ~/.bosonrc
  $ boson install https://github.com/cldwalker/irbfiles/raw/master/boson/commands/public/ruby_ref.rb

Global Variables

As we all know, Ruby comes with predefined global variables. Using the Kernel method global_variables to retrieve them, here’s a simple method to list global variables and their values:

  def global_var
    global_variables.sort.map {|e| [e, (eval e).inspect] }
  end

When Boson commandifies this method here’s what happens:

  bash> boson global_var
  +---------------------------+----------------------------------------------------------------------------------------------------+
  | variable                  | value                                                                                              |
  +---------------------------+----------------------------------------------------------------------------------------------------+
  | $!                        | nil                                                                                                |
  | $"                        | ["rubygems/defaults.rb", "thread.bundle", "thread.rb", "etc.bundle", "rbconfig.rb", "rubygems/e... |
  | $$                        | 33292                                                                                              |
  | $&                        | nil                                                                                                |
  | $'                        | nil                                                                                                |
  | $*                        | []                                                                                                 |
  # ...
  48 rows in set

  # Alphabetical sort on the value column
  bash> boson global_var '-s=val'   # global_var '--sort=value'
  +---------------------------+----------------------------------------------------------------------------------------------------+
  | variable                  | value                                                                                              |
  +---------------------------+----------------------------------------------------------------------------------------------------+
  | $FILENAME                 | "-"                                                                                                |
  | $0                        | "/usr/bin/boson"                                                                                   |
  | $PROGRAM_NAME             | "/usr/bin/boson"                                                                                   |
  | $-K                       | "UTF8"                                                                                             |
  | $KCODE                    | "UTF8"                                                                                             |
  | $/                        | "\n"                                                                                               |
  | $-0                       | "\n"                                                                                               |  
  # ...
  48 rows in set

  # Boson has a new global command option --query which allows us to search inside of a table's fields
  bash> boson global_var '-q=var:load'   # global_var '--query=variable:load'
  +------------------+-------------------------------------------------------------------------------------------------------------+
  | variable         | value                                                                                                       |
  +------------------+-------------------------------------------------------------------------------------------------------------+
  | $LOADED_FEATURES | ["rubygems/defaults.rb", "thread.bundle", "thread.rb", "etc.bundle", "rbconfig.rb", "rubygems/exceptions... |
  | $LOAD_PATH       | ["/Users/bozo/code/gems/bond/lib", "/Users/bozo/code/gems/boson/lib", "/Users/bozo/code/gems/alias/lib",... |
  +------------------+-------------------------------------------------------------------------------------------------------------+
  2 rows in set

  # If you're new to Boson, we can do any of the above from irb as well
  bash> irb
  >> global_var '-q=var:load'   # global_var '--query=variable:load'
  +------------------+-------------------------------------------------------------------------------------------------------------+
  | variable         | value                                                                                                       |
  +------------------+-------------------------------------------------------------------------------------------------------------+
  | $LOADED_FEATURES | ["rubygems/defaults.rb", "thread.bundle", "thread.rb", "etc.bundle", "rbconfig.rb", "rubygems/exceptions... |
  | $LOAD_PATH       | ["/Users/bozo/code/gems/bond/lib", "/Users/bozo/code/gems/boson/lib", "/Users/bozo/code/gems/alias/lib",... |
  +------------------+-------------------------------------------------------------------------------------------------------------+
  2 rows in set
  => true

As you can see, Boson took a simple one-line method and made it a useful command that searches, sorts and displays global variables and their values.

Loaded Paths

$LOADED_FEATURES ($") and $LOAD_PATH ($:) are handy global variables that give us required paths and the directories we can require from. Although we don’t know the full paths to the required files, it’s easy to calculate them with these global variables:

  def loaded_paths
    hash = {}
    $".each {|file|
      $:.each {|dir|
        if test(?e, File.join(dir, file))
          hash[file] = File.join(dir, file)
          break
        end
      }
    }
    hash
  end

This method gives us a hash mapping the required paths to their full paths. Let’s see what Boson does with this:

  >> loaded_paths '-s=req'  # loaded_paths '--sort=require_path'
  +----------------------------------------------------+---------------------------------------------------------------------------+
  | require_path                                       | full_path                                                                 |
  +----------------------------------------------------+---------------------------------------------------------------------------+
  | alias.rb                                           | /Users/bozo/code/gems/alias/lib/alias.rb                                  |
  | alias/console.rb                                   | /Users/bozo/code/gems/alias/lib/alias/console.rb                          |
  | alias/creator.rb                                   | /Users/bozo/code/gems/alias/lib/alias/creator.rb                          |
  | alias/creators/any_to_instance_method_creator.rb   | /Users/bozo/code/gems/alias/lib/alias/creators/any_to_instance_method_... |
  | alias/creators/class_method_creator.rb             | /Users/bozo/code/gems/alias/lib/alias/creators/class_method_creator.rb    |
  | alias/creators/class_to_instance_method_creator.rb | /Users/bozo/code/gems/alias/lib/alias/creators/class_to_instance_metho... |
  | alias/creators/constant_creator.rb                 | /Users/bozo/code/gems/alias/lib/alias/creators/constant_creator.rb        |
  | alias/creators/instance_method_creator.rb          | /Users/bozo/code/gems/alias/lib/alias/creators/instance_method_creator.rb |
  | alias/manager.rb                                   | /Users/bozo/code/gems/alias/lib/alias/manager.rb                          |
  # ...
  128 rows in set
  => true

  >> loaded_paths '-q=req:bundle   # loaded_paths '--query=require_path:bundle'
  +-----------------------------+---------------------------------------------------------------------------------------------------------------+
  | require_path                | full_path                                                                                                     |
  +-----------------------------+---------------------------------------------------------------------------------------------------------------+
  | digest.bundle               | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/universal-darwin9.0/digest.bundle     |
  | digest/md5.bundle           | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/universal-darwin9.0/digest/md5.bundle |
  | etc.bundle                  | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/universal-darwin9.0/etc.bundle        |
  | readline.bundle             | /Library/Ruby/Site/1.8/universal-darwin9.0/readline.bundle                                                    |
  | readline_line_buffer.bundle | /Users/bozo/code/gems/bond/lib/readline_line_buffer.bundle                                                    |
  | stringio.bundle             | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/universal-darwin9.0/stringio.bundle   |
  | syck.bundle                 | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/universal-darwin9.0/syck.bundle       |
  | thread.bundle               | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/universal-darwin9.0/thread.bundle     |
  +-----------------------------+---------------------------------------------------------------------------------------------------------------+
  8 rows in set
  => true

  # We can always toggle rendering on a command to get the method's return value with --render
  >> load_path('--render').values.slice(0,5)
  => ["/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/universal-darwin9.0/syck.bundle",
   "/Users/bozo/code/gems/bond/lib/bond/missions/default_mission.rb", "/Users/bozo/code/gems/boson/lib/boson/libraries/file_library.rb",
   "/Users/bozo/code/gems/hirb/lib/hirb/menu.rb", "/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/ostruct.rb"]

Gem Versions

For any number of reasons, it can be handy to know the versions of the gems you’re using. Since most gems don’t come with a VERSION constant, the easiest way to get their version is from their loaded gemspec. But since not everything we use nowadays comes as a gem i.e. rip packages, we could also extract the versions from $LOAD_PATH. Here’s a command that can do either one of these depending on the presence of a :loaded_path option:

  def gem_versions(options={})
    if options[:loaded_path]
      $:.map {|e| e =~ /\/([\w-]+)-(\d\.\d(\.\d)?)\/lib/ ? [$1,$2] : nil }.compact.uniq
    else
      Gem.loaded_specs.values.map {|e| [e.name, e.version] }
    end
  end

Let’s see it in action:

  # Using gemspecs to get the versions
  >> gem_versions
  +-----------------------+---------+
  | name                  | version |
  +-----------------------+---------+
  | matthew-method_lister | 0.2.3   |
  | mynyml-every          | 0.6     |
  | local_gem             | 0.1.1   |
  | duration              | 0.1.0   |
  +-----------------------+---------+
  4 rows in set
  => true

  # Using $: to get the versions
  >> gem_versions '-l'  # gem_versions '--loaded_path'  or gem_versions :loaded_path=>true
  +-----------------------+---------+
  | name                  | version |
  +-----------------------+---------+
  | local_gem             | 0.1.1   |
  | matthew-method_lister | 0.2.3   |
  | duration              | 0.1.0   |
  | mynyml-every          | 0.6     |
  +-----------------------+---------+
  4 rows in set
  => true

  # How does this command look inside a Rails' irb session?
  >> gem_versions '-s=n'   # gem_versions '--sort=name'
  +----------------------------+---------+
  | name                       | version |
  +----------------------------+---------+
  | RedCloth                   | 4.2.1   |
  | actionmailer               | 2.2.2   |
  | actionpack                 | 2.2.2   |
  | activerecord               | 2.2.2   |
  | activeresource             | 2.2.2   |
  | activesupport              | 2.2.2   |
  | alias                      | 0.2.1   |
  | cldwalker-has_machine_tags | 0.1.3   |
  | duration                   | 0.1.0   |
  | hirb                       | 0.2.7   |
  | local_gem                  | 0.1.1   |
  | matthew-method_lister      | 0.2.3   |
  | mynyml-every               | 0.6     |
  | rails                      | 2.2.2   |
  | rake                       | 0.8.7   |
  +----------------------------+---------+
  15 rows in set
  => true

Object Instance Variables

Whether you’re getting acquainted with a new class of objects or just trying to figure an object’s current state, looking at an object’s instance variables can be useful. Here’s a command that gives us any object’s instance variables and their values:

  def instance_var(obj)
    obj.instance_variables.map {|e| [e, obj.instance_variable_get(e)] }
  end

Using this with Boson:

  # Let's start with a Boson::Command object
  >> instance_var Boson.commands[0]
  +-------------------+-------------------------------+
  | instance          | value                         |
  +-------------------+-------------------------------+
  | @lib              | "core"                        |
  | @name             | "usage"                       |
  | @options          | {[:verbose, :V]=>:boolean}    |
  | @args             | [["name"], ["options", "{}"]] |
  | @file_parsed_args | true                          |
  | @description      | "Print a command's usage"     |
  +-------------------+-------------------------------+
  6 rows in set
  => true

  # How about the bigger Gem::Specification object?
  >> instance_var Gem.loaded_specs.values[0], '-s=i'  #  or '--sort=instance'
  +----------------------------+-----------------------------------------------------------------------------------------------------------------------+
  | instance                   | value                                                                                                                 |
  +----------------------------+-----------------------------------------------------------------------------------------------------------------------+
  | @authors                   | ["Matthew O'Connor"]                                                                                                  |
  | @autorequire               | nil                                                                                                                   |
  | @bindir                    | "bin"                                                                                                                 |
  | @cert_chain                | []                                                                                                                    |
  | @date                      | Mon Oct 27 00:00:00 -0400 2008                                                                                        |
  | @default_executable        | nil                                                                                                                   |
  | @dependencies              | []                                                                                                                    |
  | @description               | nil                                                                                                                   |
  | @email                     | "matthew @nospam@ canonical.org"                                                                                      |
  | @executables               | []                                                                                                                    |
  | @extensions                | []                                                                                                                    |
  | @extra_rdoc_files          | ["README.markdown"]                                                                                                   |
  | @files                     | ["lib/method_lister/color_display.rb", "lib/method_lister/find_result.rb", "lib/method_lister/finder.rb", "lib/met... |
  | @has_rdoc                  | true                                                                                                                  |
  | @homepage                  | "http://github.com/matthew/method_lister/tree/master"                                                                 |
  | @licenses                  | []                                                                                                                    |
 # ...
 35 rows in set
 => true

 #  Search instances containing files
 >> instance_var Gem.loaded_specs.values[0], '-q=i:files'   #  or '--query=instance:files'
 +-------------------+--------------------------------------------------------------------------------------------------------------------------------+
 | instance          | value                                                                                                                          |
 +-------------------+--------------------------------------------------------------------------------------------------------------------------------+
 | @files            | ["lib/method_lister/color_display.rb", "lib/method_lister/find_result.rb", "lib/method_lister/finder.rb", "lib/method_liste... |
 | @test_files       | ["spec/color_display_spec.rb", "spec/find_result_spec.rb", "spec/finder_spec.rb", "spec/ruby_ext_spec.rb", "spec/simple_dis... |
 | @extra_rdoc_files | ["README.markdown"]                                                                                                            |
 +-------------------+--------------------------------------------------------------------------------------------------------------------------------+
 3 rows in set
 => true

 # So what if want to see everything inside the value field?
 >> instance_var Gem.loaded_specs.values[0], '-q=i:files -V'   # or '--query=instance:files --vertical'
 ************ 1. row ************
 instance: @files
    value: ["lib/method_lister/color_display.rb", "lib/method_lister/find_result.rb", "lib/method_lister/finder.rb",
  "lib/method_lister/ruby_ext.rb", "lib/method_lister/simple_display.rb", "lib/method_lister.rb", "spec/color_display_spec.rb",
  "spec/find_result_spec.rb", "spec/finder_spec.rb", "spec/helpers/matchers/list_methods.rb",
  "spec/helpers/object_mother/find_result.rb", "spec/helpers/object_mother/find_scenario.rb", "spec/rcov.opts", "spec/ruby_ext_spec.rb",
  "spec/scenarios/class_with_inheritance.rb", "spec/scenarios/class_with_inheritance_and_modules.rb", "spec/scenarios/eigenclass.rb",
  "spec/scenarios/eigenclass_with_modules.rb", "spec/scenarios/filters_results_without_methods.rb",
  "spec/scenarios/mixed_visibility_methods.rb", "spec/scenarios/object_without_eigenclass.rb", "spec/scenarios/overloaded_methods.rb"
  "spec/scenarios/overloaded_methods_with_modules_mixed_in.rb", "spec/scenarios/private_methods.rb", "spec/scenarios/single_class.rb",
  "spec/scenarios/single_class_with_module_mixed_in.rb", "spec/simple_display_spec.rb", "spec/spec.opts", "spec/spec_helper.rb",
   "README.markdown"]
 ************ 2. row ************
 instance: @test_files
    value: ["spec/color_display_spec.rb", "spec/find_result_spec.rb", "spec/finder_spec.rb", "spec/ruby_ext_spec.rb",
  "spec/simple_display_spec.rb"]
 ************ 3. row ************
 instance: @extra_rdoc_files
    value: ["README.markdown"]
 3 rows in set
 => true

The pp method from the standard library is another good alternative for displaying an object’s instance variables. Personally, I find the fact that any class can customize their pp output to be a strength but also a weakness. The weakness lies in that formatting of objects become inconsistent across classes and there’s no guarantee that pp will give you all instance variables. Also, to get a good overview of an object I think it helps to stick to one instance variable per line.

RbConfig

If you have ever had to ensure a gem works across multiple platforms, you’ve probably encountered RbConfig. This module, which is generated by mkconfig.rb when your ruby is built, contains a hash constant, CONFIG, containing platform-specific configuration. So let’s make a command that simply points to this config hash:

  def rbconfig
    require 'rbconfig'
    RbConfig::CONFIG
  end

From the above, we already know we can display, search and sort data structures pretty easily. So let’s just focus on searching features that have been dormant til now:

  # We know we can search in a field
  bash> boson rbconfig -q=n:arch    # or --query=name:arch
  +-------------+---------------------------------------------------------------------------------------------+
  | name        | value                                                                                       |
  +-------------+---------------------------------------------------------------------------------------------+
  | archdir     | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/universal-darwin9.0 |
  | sitearch    | universal-darwin9.0                                                                         |
  | arch        | universal-darwin9.0                                                                         |
  | sitearchdir | /Library/Ruby/Site/1.8/universal-darwin9.0                                                  |
  | ARCHFILE    |                                                                                             |
  | ARCH_FLAG   |                                                                                             |
  +-------------+---------------------------------------------------------------------------------------------+
  6 rows in set

  # But you can also search in all fields with '*'
  bash> boson rbconfig -q=*:arch    # or --query=name,value:arch
  +------------------+---------------------------------------------------------------------------------------------+
  | name             | value                                                                                       |
  +------------------+---------------------------------------------------------------------------------------------+
  | archdir          | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/universal-darwin9.0 |
  | sitearch         | universal-darwin9.0                                                                         |
  | arch             | universal-darwin9.0                                                                         |
  | sitearchdir      | /Library/Ruby/Site/1.8/universal-darwin9.0                                                  |
  | ARCHFILE         |                                                                                             |
  | ARCH_FLAG        |                                                                                             |
  | LDSHARED         | cc -arch ppc -arch i386 -pipe -bundle -undefined dynamic_lookup                             |
  | LDFLAGS          | -L. -arch ppc -arch i386                                                                    |
  | LIBRUBY_LDSHARED | cc -arch ppc -arch i386 -pipe -dynamiclib                                                   |
  | CFLAGS           | -arch ppc -arch i386 -Os -pipe -fno-common                                                  |
  +------------------+---------------------------------------------------------------------------------------------+
  10 rows in set

  # Searches are regular expressions
  bash> boson rbconfig -q=n:ruby$   # or --query=name:ruby$
  +----------+--------------------------------------------------+
  | name     | value                                            |
  +----------+--------------------------------------------------+
  | LIBRUBY  | libruby.1.dylib                                  |
  | MINIRUBY | ./miniruby                                       |
  | RUNRUBY  | ./miniruby $(srcdir)/runruby.rb --extout=.ext -- |
  +----------+--------------------------------------------------+
  3 rows in set

  # Multiple searches can be joined together by a comma
  bash> boson rbconfig -q=n:ruby$,v:package  # or --query=name:ruby$,value:package
  +----------+---------------------------------------------------------------------------------+
  | name     | value                                                                           |
  +----------+---------------------------------------------------------------------------------+
  | LIBRUBY  | libruby.1.dylib                                                                 |
  | MINIRUBY | ./miniruby                                                                      |
  | RUNRUBY  | ./miniruby $(srcdir)/runruby.rb --extout=.ext --                                |
  | docdir   | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/share/doc/$(PACKAGE) |
  | dvidir   | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/share/doc/$(PACKAGE) |
  | psdir    | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/share/doc/$(PACKAGE) |
  | htmldir  | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/share/doc/$(PACKAGE) |
  | pdfdir   | /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/share/doc/$(PACKAGE) |
  +----------+---------------------------------------------------------------------------------+
  8 rows in set

Game Over

As you can see, Boson does a decent job of turning simple methods into useful commands. In these examples, we saw the return values of these commands converted into well-formatted, sortable and searchable tables without adding any code. If you look at the library source you will see commented render_options calls for each command. These are what hooked into Boson to give us all this functionality. To understand how this all works and create your own similar commands, check out the Boson docs and the Hirb table docs. If you want to check out more libraries like this, there are plenty. If you have ruby reference commands/methods, feel free to share them below.

How Boson Enhances Your Irb Experience

2009-10-19T00:00:00-07:00

In previous posts, Boson was introduced as a command framework, usable from the commandline and irb. In this post, we’ll focus on how Boson enhances irb by treating methods like shell commands.

Preface

If you’re an avid irb user like me, your ~/.irbrc is littered with methods. These methods are sometimes favorite tweaks to Ruby’s core libraries and sometimes interfaces to gems. But regardless of what they represent, when you use them they’re just like shell commands. With this user in mind, Boson aims to give methods command-like functionality. This means giving a method the ability to have simple yet powerful options. This means aliasing and annotating methods are commonplace. This means searching and sharing your commands with others are easy to do. And if you want, you can even give a method instant views.

Here’s the order we’ll be covering using Boson with irb:

Setup
Organization and Philosophy
Core Commands
Boson Libraries
Migrating Your Irb Commands

Setup

To use Boson in irb, drop this in your ~/.irbrc. For any other ruby console application the setup is the same:

  require 'boson'
  Boson.start

Boson.start comes with some options. If you don’t like that Boson tells you every library it loads, set :verbose=>false.

Organization and Philosophy

When Boson starts, it loads libraries of commands. Boson libraries are just Ruby modules and Boson commands are just methods in those modules. Most libraries are in their own file under ~/.boson/commands. Each library can have an optional namespace defined in a config file. With this organization commands are independent of Boson. There are no namespace dsl methods as with Rake and no required Thor subclassing as with Thor. This is on purpose. Boson strives to allow all of its functionality to be written in plain ruby. This way you are free to easily test your commands and use them with other applications independent of Boson. Also, if you decided to stop using Boson, all libraries you’ve built for it can still be used in irb without modifying them. To do this you would simply extend your library’s modules into Ruby’s top-level object main.

Core Commands

Boson comes with a handful of core commands but let’s focus on three you’ll probably use the most: commands, libraries and load_library. Since these commands have options, you should familiarize yourself with the default global options they have. Also, you should be aware that option values can be aliased.

commands

This command searches your commands in a myriad of ways.

  # With no arguments commands() lists all loaded commands
  >> commands
  +------------------------+----------------------+-------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
  | full_name              | lib                  | alias | usage                                                                     | description                                                               |
  +------------------------+----------------------+-------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
  | usage                  | core                 |       | [name][--verbose]                                                         | Print a command's usage                                                   |
  | libraries              | core                 | lib   | [query=''][--index] [--query_fields=name]                                 | List or search libraries                                                  |
  | render                 | core                 | v     | [object] [options={}]                                                     | Render any object using Hirb                                              |
  | load_library           | core                 | ll    | [library][--verbose] [--reload]                                           | Load/reload a library                                                     |
  | commands               | core                 | com   | [query=''][--index] [--query_fields=full_name]                            | List or search commands                                                   |
  | menu                   | core                 |       | [output] [options={}] [&block]                                            | Provide a menu to multi-select elements from a given array                |
  # ...

  # By default searches in a command's full_name
  >> commands 'usa'
  +-----------+------+-------+-------------------+-------------------------+
  | full_name | lib  | alias | usage             | description             |
  +-----------+------+-------+-------------------+-------------------------+
  | usage     | core |       | [name][--verbose] | Print a command's usage |
  +-----------+------+-------+-------------------+-------------------------+
  1 row in set

  # Since searches are regular expressions, we can search multiple terms
  >> commands 'usa|lib'
  +--------------------+-------+-------+-------------------------------------------+---------------------------------------------+
  | full_name          | lib   | alias | usage                                     | description                                 |
  +--------------------+-------+-------+-------------------------------------------+---------------------------------------------+
  | usage              | core  |       | [name][--verbose]                         | Print a command's usage                     |
  | libraries          | core  | lib   | [query=''][--index] [--query_fields=name] | List or search libraries                    |
  | load_library       | core  | ll    | [library][--verbose] [--reload]           | Load/reload a library                       |
  +--------------------+-------+-------+-------------------------------------------+---------------------------------------------+
  3 rows in set
  => true

  # Before we can use a command's options we have to know what options it has
  >> commands '-h'  # or commands '--help'
  commands [query=''][--index]
  => nil
  # another way of getting a command's usage
  >> usage 'commands'

  # To search full_name and description fields for 'lib'
  >> commands 'full_name,description:lib'
  +--------------------+----------+-------+-------------------------------------------------------------------------------+-----------------------------------------------------------------------------+
  | full_name          | lib      | alias | usage                                                                         | description                                                                 |
  +--------------------+----------+-------+-------------------------------------------------------------------------------+-----------------------------------------------------------------------------+
  | libraries          | core     | lib   | [query=''][--index] [--query_fields=name]                                     | List or search libraries                                                    |
  | load_library       | core     | ll    | [library][--verbose] [--reload]                                               | Load/reload a library                                                       |
  | install            | web_core |       | [url][--force] [--module_wrap] [--name=NAME] [--method_wrap]                  | Installs a library by url. Library should then be loaded with load_library. |  
 +--------------------+----------+-------+-------------------------------------------------------------------------------+-----------------------------------------------------------------------------+
  3 rows in set
  => true

  # With option name and value aliasing, the above can also be
  >> commands 'lib -q=f,d'

Since commands() comes with Boson’s global rendering options, commands can be sorted by command attribute and have only certain attributes displayed.

  # Before sorting and selecting command attributes, we need to know what attributes we can choose from in our options.
  # Let's call up verbose help:
  >> commands '-hv'    # or commands '--help --verbose'
  commands [query=''][--index]

  COMMAND OPTIONS
  +----------------+-------+---------+-------------------+------------------------------------------------------------------------+
  | Option         | Alias | type    | Description       | Values                                                                 |
  +----------------+-------+---------+-------------------+------------------------------------------------------------------------+
  | --index        | -i    | boolean | Searches index    |                                                                        |
  +----------------+-------+---------+-------------------+------------------------------------------------------------------------+

  GLOBAL/RENDER OPTIONS
  +----------------+-------+---------+-----------------------------------------------------------+------------------------------------------------------------------------+
  | Option         | Alias | type    | Description                                               | Values                                                                 |
  +----------------+-------+---------+-----------------------------------------------------------+------------------------------------------------------------------------+
  | --class        | -c    | string  | Hirb helper class which renders                           |                                                                        |
  | --fields       | -f    | array   | Displays fields in the order given                        | name,lib,alias,description,options,args,usage,full_name,render_options |
  | --help         | -h    | boolean | Display a command's help                                  |                                                                        |
  | --max_width    | -m    | numeric | Max width of a table                                      |                                                                        |
  | --pretend      | -p    | boolean | Display what a command would execute without executing it |                                                                        |
  | --render       | -r    | boolean | Toggle a command's default rendering behavior             |                                                                        |
  | --reverse_sort | -R    | boolean | Reverse a given sort                                      |                                                                        |
  | --sort         | -s    | string  | Sort by given field                                       | name,lib,alias,description,options,args,usage,full_name,render_options |
  | --verbose      | -v    | boolean | Increase verbosity for help, errors, etc.                 |                                                                        |
  | --vertical     | -V    | boolean | Display a vertical table                                  |                                                                        |
  +----------------+-------+---------+-----------------------------------------------------------+------------------------------------------------------------------------+
  => nil

  # Looking under values column, we can see the available values for --sort and --fields i.e.
  # name,lib,alias,description,options,args,usage,full_name,render_options
  # To sort by library
  >> commands '--sort=lib'     # or commands '-s=l'
  +--------------+----------+-------+--------------------------------------------------------------+-----------------------------------------------------------------------------+
  | full_name    | lib      | alias | usage                                                        | description                                                                 |
  +--------------+----------+-------+--------------------------------------------------------------+-----------------------------------------------------------------------------+
  | usage        | core     |       | [name][--verbose]                                            | Print a command's usage                                                     |
  | libraries    | core     | lib   | [query=''][--index] [--query_fields=name]                    | List or search libraries                                                    |
  | render       | core     | v     | [object] [options={}]                                        | Render any object using Hirb                                                |
  | load_library | core     | ll    | [library][--verbose] [--reload]                              | Load/reload a library                                                       |
  | commands     | core     | com   | [query=''][--index] [--query_fields=full_name]               | List or search commands                                                     |
  | menu         | core     |       | [output] [options={}] [&block]                               | Provide a menu to multi-select elements from a given array                  |
  | get          | web_core |       | [url] [options={}]                                           | Gets the body of a url                                                      |
  # ...

  # To reverse sort
  >> commands '--sort=lib --reverse_sort'     # or commands '-s=l -R'
  +--------------+----------+-------+--------------------------------------------------------------+-----------------------------------------------------------------------------+
  | full_name    | lib      | alias | usage                                                        | description                                                                 |
  +--------------+----------+-------+--------------------------------------------------------------+-----------------------------------------------------------------------------+
  | browser      | web_core |       | [*urls]                                                      | Opens urls in a browser on a Mac                                            |
  | install      | web_core |       | [url][--force] [--module_wrap] [--name=NAME] [--method_wrap] | Installs a library by url. Library should then be loaded with load_library. |
  | post         | web_core |       | [url] [options={}]                                           | Posts to url                                                                |
  | get          | web_core |       | [url] [options={}]                                           | Gets the body of a url                                                      |
  | menu         | core     |       | [output] [options={}] [&block]                               | Provide a menu to multi-select elements from a given array                  |
  # ...

  # To only display command attributes full_name and description
  >> commands '--fields=full_name,description    # or commands '-f=f,d'
  +--------------+-----------------------------------------------------------------------------+
  | full_name    | description                                                                 |
  +--------------+-----------------------------------------------------------------------------+
  | usage        | Print a command's usage                                                     |
  | libraries    | List or search libraries                                                    |
  | render       | Render any object using Hirb                                                |
  | load_library | Load/reload a library                                                       |
  | commands     | List or search commands                                                     |
  | menu         | Provide a menu to multi-select elements from a given array                  |
  | get          | Gets the body of a url                                                      |
  | post         | Posts to url                                                                |
  | install      | Installs a library by url. Library should then be loaded with load_library. |
  | browser      | Opens urls in a browser on a Mac                                            |
  +--------------+-----------------------------------------------------------------------------+
  10 rows in set
  => true

  # Don't forget that rendering can be switched off to give us the actual command objects. Any of the above
  # examples could yield command objects if prefixed with --render.
  >> commands('--render usa|lib').size   # or commands '-r usa|lib'
  => 3

libraries

Like commands, libraries can be searched, sorted and displayed with a number of library attributes:

  # These examples are specific to my libraries.
  
  # To find out valid library attributes and option values
  >> libraries '-hv'
  # ...

  # Sort by name
  >> libraries '--sort=name'     # or libraries '-s=n'
  +----------------------+----------+-----------------------+--------------+
  | name                 | commands | gems                  | library_type |
  +----------------------+----------+-----------------------+--------------+
  | alias                | 6        |                       | file         |
  | boson                | 10       |                       | file         |
  | boson_method_missing | 3        |                       | file         |
  | completion           | 3        |                       | file         |
  # ...

  # See the module for each library
  >> libraries '--fields=name,module'  # or libraries '-f=n,m'
  +----------------------+-------------------------------------+
  | name                 | module                              |
  +----------------------+-------------------------------------+
  | core                 | Boson::Commands::Core               |
  | web_core             | Boson::Commands::WebCore            |
  | boson_method_missing | Boson::Commands::BosonMethodMissing |
  | completion           | Boson::Commands::Completion         |
  | alias                | Boson::Commands::AliasLib           |
  # ...
  
  # Search inside all libraries (that Boson has indexed)
  # for libraries of type gem
  >> libraries 'library_type:gem --index'  # or libraries 'l:gem -i'
  +---------------+----------+--------------------------------------------+--------------+
  | name          | commands | gems                                       | library_type |
  +---------------+----------+--------------------------------------------+--------------+
  | httparty      | 2        | httparty,crack                             | gem          |
  | method_lister | 3        | matthew-method_lister                      | gem          |
  | sketches      | 5        | sketches                                   | gem          |
  | andand        | 4        | andand                                     | gem          |
  | local_gem     | 2        | local_gem                                  | gem          |
  | what_methods  | 2        | what_methods                               | gem          |
  | unroller      | 1        | colored,unroller,quality_extensions,facets | gem          |
  | restclient    | 1        | adamwiggins-rest-client                    | gem          |
  +---------------+----------+--------------------------------------------+--------------+
  8 rows in set
  => true

load_library

This command loads a library and its commands. This allows you to load the bare minimum functionality you need in irb and then load commands as needed.

  # Verify the desired ri command doesn't exist yet
  >> ri 'method_mis'
  NameError: undefined local variable or method `ri' for main:Object
          from (irb):1

  # Load my ri library and its commands
  >> load_library 'ri'
  Loaded library ri
  => true

  >> ri 'method_mis'
  +--------+------------------------------------+
  | number | full_name                          |
  +--------+------------------------------------+
  | 1      | DRb::DRbObject#method_missing      |
  | 2      | Delegator#method_missing           |
  | 3      | Kernel#method_missing              |
  | 4      | REXML::Functions::method_missing   |
  | 5      | REXML::QuickPath::method_missing   |
  | 6      | SOAP::SOAPReference#method_missing |
  +--------+------------------------------------+
  6 rows in set
  Choose:
  # ...

To make your life even easier, you can put Boson in a mode where unloaded commands are automatically loaded once they’re executed. How does this work? Since commands are just methods on main, Boson redefines main ’s method_missing …

  # To enable this you need to modify your ~/.irbrc:
  # Boson.start :autoload_libraries=>true

  # Assuming irb doesn't have the ri command again
  >> ri 'method_mes'
  Loaded library 'ri'
  +--------+------------------------------------+
  | number | full_name                          |
  +--------+------------------------------------+
  | 1      | DRb::DRbObject#method_missing      |
  | 2      | Delegator#method_missing           |
  | 3      | Kernel#method_missing              |
  | 4      | REXML::Functions::method_missing   |
  | 5      | REXML::QuickPath::method_missing   |
  | 6      | SOAP::SOAPReference#method_missing |
  +--------+------------------------------------+
  6 rows in set
  Choose:
  # ...

Boson Libraries

Up to now, Boson libraries have been described as a module sitting in a file. While this type of library, a Boson::FileLibrary is the most common and functionally-rich, there are other library types.

Gem Library

Boson::GemLibrary makes commands from a gem. Let’s see this library in action by loading the sketches gem:

  # Without any configuration, let's load sketches as a library
  >> load_library 'sketches'
  Loaded library sketches
  => true

  # Let's see what commands Boson picked up
  >> commands 'l:sket'   # or commands 'lib:sket'
  +-------------+----------+-------+-------+-------------+
  | full_name   | lib      | alias | usage | description |
  +-------------+----------+-------+-------+-------------+
  | sketch_from | sketches |       |       |             |
  | name_sketch | sketches |       |       |             |
  | save_sketch | sketches |       |       |             |
  | sketches    | sketches |       |       |             |
  | sketch      | sketches |       |       |             |
  +-------------+----------+-------+-------+-------------+
  5 rows in set

  # Begin sketching
  >> sketch
  # ...

Is sketches already built to work with Boson? Not quite. Rather, this demonstrates how Boson safeguards main by tracking what gems dump in Object and Kernel. Unfortunately this is all too common with irb-related gems. Now let’s use a gem that doesn’t dump methods on us:

  # Create commands put and delete from HTTParty's API.
  # Values of :class_commands hash can point to any ruby code ending with a method call.
  >> load_library 'httparty', :class_commands=>{'put'=>'HTTParty.put', 'delete'=>'HTTParty.delete' }
  => true

  >> commands 'l:http'  # or commands 'lib:http'
  +-----------+----------+-------+-------+-------------+
  | full_name | lib      | alias | usage | description |
  +-----------+----------+-------+-------+-------------+
  | blank?    | httparty |       |       |             |
  | dclone    | httparty |       |       |             |
  | delete    | httparty |       |       |             |
  | put       | httparty |       |       |             |
  +-----------+----------+-------+-------+-------------+
  4 rows in set
  => true

  # Well, we spoke to soon. blank? and dclone are again monkeypatched methods.
  # If you'd rather have Boson not detect these methods for you:
  # load_library 'httparty', :object_methods=>false, :class_commands ...

  # To avoid typing out configurations for each gem you use, save them in the config file
  # ~/.boson/config/boson.yml under the :libraries key :
  #
  # :libraries:
  #   httparty:
  #     :class_commands:
  #       put: HTTParty.put
  #       delete: HTTParty.delete

  # Next irb session we can just load httparty and use our preconfigured commands
  bash> irb
  >> load_library 'httparty'
  => true

  >> put 'http://blah/blah'
  # ...

Require Library

Boson::RequireLibrary makes its commands centered around any require-able library (i.e. standard libraries and rip packages):

  # Let's make a command from the standard library abbrev
  >> load_library 'abbrev', :class_commands=>{'abbrev'=>'Abbrev.abbrev'}, :command_aliases=>{'abbrev'=>'ab'}
  => true

  # abbrev() shows a hash of all unique strings that abbreviate an array
  >> abbrev %w{awesome audacious asinine}
  => {"audacious"=>"audacious", "asini"=>"asinine", "aw"=>"awesome", "asi"=>"asinine", "awesome"=>"awesome", "awe"=>"awesome",
    "aweso"=>"awesome", "asin"=>"asinine", "aud"=>"audacious", "audaci"=>"audacious", "asinin"=>"asinine", "audacio"=>"audacious",
    "awesom"=>"awesome", "as"=>"asinine", "audac"=>"audacious", "audaciou"=>"audacious", "awes"=>"awesome", "asinine"=>"asinine",
    "au"=>"audacious", "auda"=>"audacious"}

  # Even though we haven't hooked up abbrev() to Boson/Hirb rendering
  # we can still use it with the default command render
  >> render ab(%w{awesome audacious asinine}).sort
  +-----------+-----------+
  | 0         | 1         |
  +-----------+-----------+
  | as        | asinine   |
  | asi       | asinine   |
  | asin      | asinine   |
  | asini     | asinine   |
  | asinin    | asinine   |
  | asinine   | asinine   |
  # ...

  # Let's make irb feel more like a shell with fileutils
  >> load_library 'fileutils', :class_commands=>%w{cd cp ln mv chmod}.inject({}) {|h,e| h[e] = "FileUtils.#{e}"; h}
  => true

  # Let's see what commands we have now
  >> commands 'l:fileu'   # or commands 'lib:fileu'
  +-----------+-----------+-------+-------+-------------+
  | full_name | lib       | alias | usage | description |
  +-----------+-----------+-------+-------+-------------+
  | chmod     | fileutils |       |       |             |
  | ln        | fileutils |       |       |             |
  | cd        | fileutils |       |       |             |
  | cp        | fileutils |       |       |             |
  | mv        | fileutils |       |       |             |
  +-----------+-----------+-------+-------+-------------+
  5 rows in set
  => true

Module Library

Boson::ModuleLibrary simply makes commands from a module’s class methods:

  >> load_library Math, :commands=>%w{sin cos tan}
  => true

  >> commands 'l:math'    # or commands 'lib:math'
  +-----------+------+-------+-------+-------------+
  | full_name | lib  | alias | usage | description |
  +-----------+------+-------+-------+-------------+
  | cos       | math |       |       |             |
  | sin       | math |       |       |             |
  | tan       | math |       |       |             |
  +-----------+------+-------+-------+-------------+
  3 rows in set

  # Let's brush up on ol trig
  >> sin (Math::PI/2)
  => 1.0
  >> tan (Math::PI/4)
  => 1.0
  # Close enough :)
  >> cos (Math::PI/2)
  => 6.12323399573677e-17

Migrating Your Irb Commands

Before migrating your methods or irb commands, remember Boson’s philosophy. Whatever time you spend organizing your irbrc isn’t in vain. You can always take what you’ve made and use it without Boson.

The easiest way to migrate is to simply wrap all your irbrc methods in a module and explicitly pass that module to Boson.start:

  # in ~/.irbrc
  module Easy
    def command1
    end
    # ...
  end

  require 'boson'
  Boson.start :libraries=>[Easy]

The downside to this is that your commands don’t have options or views

If you want those features and still want the simplest thing possible, put all your methods in a module and drop that module into a file under ~/.boson/commands/.

If you’re serious about organizing your irbrc, you should break your methods up into libraries. If any of your methods are simply wrappers around a gem or a require-able library, consider making a gem library or a require library. Otherwise make each library by wrapping it in a module and placing it in under ~/.boson/commands/.

Next you should consider adding aliases and descriptions to your commands. Command aliasing is explained here. To add a command description, simply add a comment directly above it. If your description spans multiple lines than use the desc method attribute:

  #@desc My description spans multiple lines
  #  because I have a lot to say and
  #  not enough space to say it
  def talk
    # ...
  end

Lastly, you should decide which libraries to load at startup. The default is to load all libraries. You’ll probably want to change that once your libraries load multiple gems. To specify these libraries, open up Boson’s main config file at ~/.boson/config/boson.yml. Add a :console_defaults key and give it an array of libraries. See my config file as an example.

Postface

In this post, we’ve seen how Boson treats methods like shell commands. In doing so, it makes irb (or any ruby console) a simple yet powerful method-based shell. For more traditional ruby shell implementations, see rubish, rush and pope. If you’re interested in giving autocompletion to your commands, check out Bond.

Boson And Hirb Interactions

2009-10-15T00:00:00-07:00

In the last post, I introduced Boson and its options for commands. What I didn’t mention was that Boson also gives those commands default options. Among them are ones to control rendering a command’s output with Hirb and even toggle rendering. At the flick of a switch, Boson commands (Ruby methods) can have Hirb’s views.

Hirb’s Handy Tables

Back in an old post, I concluded with a mention that Hirb’s table() can handle arrays of about any object (responding to to_s). Unless you read the docs or tests, that probably didn’t register much. So let’s see it in action:

  bash> irb
  >> require 'hirb'; extend Hirb::Console
  => main

  # Basic array or anything that responds to :to_a
  >> table 1..3
  +-------+
  | value |
  +-------+
  | 1     |
  | 2     |
  | 3     |
  +-------+
  3 rows in set
  => true

  # Array of arrays
  >> table (1..5).map {|e| [e, Math.sqrt(e)] }
  +----+------------------+
  | 0  | 1                |
  +----+------------------+
  | 1  | 1.0              |
  | 2  | 1.4142135623731  |
  | 3  | 1.73205080756888 |
  | 4  | 2.0              |
  | 5  | 2.23606797749979 |
  +----+------------------+
  5 rows in set
  => true

  # Array of hashes
  >> table [{:name=>'Brain', :occupation=>'Take over the world'}, {:name=>'Batman', :occupation=>'Save the world'},
    {:name=>'Joker', :occupation=>'Destroy the world'}, {:name=>'Pinky', :occupation=>'Annoy Brain'}]
  +--------+---------------------+
  | name   | occupation          |
  +--------+---------------------+
  | Brain  | Take over the world |
  | Batman | Save the world      |
  | Joker  | Destroy the world   |
  | Pinky  | Annoy Brain         |
  +--------+---------------------+
  4 rows in set
  => true

  # Choose only certain keys of hashes with :fields
  >> table [{:name=>'Brain', :occupation=>'Take over the world'}, {:name=>'Batman', :occupation=>'Save the world'},
    {:name=>'Joker', :occupation=>'Destroy the world'}, {:name=>'Pinky', :occupation=>'Annoy Brain'}],
    :fields=>[:name]
  +--------+
  | name   |
  +--------+
  | Brain  |
  | Batman |
  | Joker  |
  | Pinky  |
  +--------+
  4 rows in set
  => true

  # Array of Date objects, stringified by to_s()
  >> table (1..5).map {|e| Date.today + e }
  +------------+
  | 0          |
  +------------+
  | 2009-10-15 |
  | 2009-10-16 |
  | 2009-10-17 |
  | 2009-10-18 |
  | 2009-10-19 |
  +------------+
  5 rows in set
  => true

  # Passing :fields on any object simply calls its methods
  # Comparing Date formats:
  >> table (1..5).map {|e| Date.today + e }, :fields=>[:to_s, :ajd, :civil, :jd, :mjd]
  +------------+-----------+----------+---------+-------+
  | to_s       | ajd       | civil    | jd      | mjd   |
  +------------+-----------+----------+---------+-------+
  | 2009-10-15 | 4910239/2 | 20091015 | 2455120 | 55119 |
  | 2009-10-16 | 4910241/2 | 20091016 | 2455121 | 55120 |
  | 2009-10-17 | 4910243/2 | 20091017 | 2455122 | 55121 |
  | 2009-10-18 | 4910245/2 | 20091018 | 2455123 | 55122 |
  | 2009-10-19 | 4910247/2 | 20091019 | 2455124 | 55123 |
  +------------+-----------+----------+---------+-------+
  5 rows in set
  => true

Keep Hirb’s handy tables in mind as you see Boson make use of them.

To Render or Not To Render

In the previous post, I demonstrated adding options to commands. Let’s create another such command but this time to explore Boson’s default options:

  # Drop this in ~/.boson/commands/pinky.rb
  module Pinky
    #@options :count=>:numeric
    # Give Pinky a voice
    def speak(*args)
      options = args[-1].is_a?(Hash) ? args.pop : {}
      puts "Hey Brain! #{args.join(' ')}"
      if options[:count]
        puts "Brain, I can count to #{options[:count]}!"
        1..options[:count]
      end
    end
  end

Let Pinky do his thing:

  bash> irb
  >> speak "What does this do?"
  Hey Brain! What does this do?
  => nil

  # Give Pinky a number to count to
  >> speak 'La-di-da -c5'
  Hey Brain! La-di-da
  Brain, I can count to 5!
  => 1..5

  # Turn on Hirb rendering for return value
  >> speak 'La-di-da --render -c5'
  Hey Brain! La-di-da
  Brain, I can count to 5!
  +-------+
  | value |
  +-------+
  | 1     |
  | 2     |
  | 3     |
  | 4     |
  | 5     |
  +-------+
  5 rows in set
  => true

  # Pass Hirb's rendering a :fields option
  >> speak 'Brain!!! -r -f to_s,to_f -c3'
  Hey Brain! Brain!!!
  Brain, I can count to 3!
  +------+------+
  | to_s | to_f |
  +------+------+
  | 1    | 1.0  |
  | 2    | 2.0  |
  | 3    | 3.0  |
  +------+------+
  3 rows in set
  => true

Nice! Simply by passing an option, Boson converted our command’s return value into a well-formatted Hirb table. Although Boson uses Hirb’s table rendering by default, you can use any Hirb helper class, especially ones you’ve made. So what are the implications of this? Any Boson command can have any view generated from its return value without adding view code to the method. If you’re wondering how this is possible, see Boson::Scientist which redefines a command’s method to have a Hirb rendering engine appended to it. For a more compelling example see the github library below.

A Boson Command’s Global Options

Each Boson command with options, or an option command, comes with global command options for rendering, sorting, etc. For now, these global options must come before a command’s options. So let’s see what they are:

  # Call up an option command's verbose help
  >> speak '-hv'
  speak [text][--count=N]

  COMMAND OPTIONS
  +---------+-------+---------+
  | Option  | Alias | type    |
  +---------+-------+---------+
  | --count | -c    | numeric |
  +---------+-------+---------+

  GLOBAL/RENDER OPTIONS
  +----------------+-------+---------+-----------------------------------------------------------+
  | Option         | Alias | type    | Description                                               |
  +----------------+-------+---------+-----------------------------------------------------------+
  | --class        | -c    | string  | Hirb helper class which renders                           |
  | --fields       | -f    | array   | Displays fields in the order given                        |
  | --help         | -h    | boolean | Display a command's help                                  |
  | --max_width    | -m    | numeric | Max width of a table                                      |
  | --pretend      | -p    | boolean | Display what a command would execute without executing it |
  | --render       | -r    | boolean | Toggle a command's default rendering behavior             |
  | --reverse_sort | -R    | boolean | Reverse a given sort                                      |
  | --sort         | -s    | string  | Sort by given field                                       |
  | --verbose      | -v    | boolean | Increase verbosity for help, errors, etc.                 |
  | --vertical     | -V    | boolean | Display a vertical table                                  |
  +----------------+-------+---------+-----------------------------------------------------------+
  => true

  # Use --pretend to see what arguments are being passed to your command without running it.
  # Useful when debugging options and aliased option values
  >> speak '--pretend -r -c3 Testing'
  Arguments: ["Testing", {:count=>3}]
  Global options: {:pretend=>true, :render=>true}
  => true

  # Use --vertical to convert a table to a vertical one.
  # Useful for database record tables
  >> speak '-rV -c3 Que pasa!'
  Hey Brain! Que pasa!
  Brain, I can count to 3!
  ******* 1. row *******
  value: 1
  ******* 2. row *******
  value: 2
  ******* 3. row *******
  value: 3
  3 rows in set
  => true

  # Resize a table's maximum width to 7 characters
  >> speak '-r -m7 -c3 Blah blah!'
  Hey Brain! Blah blah!
  Brain, I can count to 3!
  +-----+
  | val |
  +-----+
  | 1   |
  | 2   |
  | 3   |
  +-----+
  3 rows in set
  => true

  # When a global option conflicts with a command's options, pass them at the
  # end separated by a '-'
  >> speak 'What year is it? -r -c3 - -c=auto_table'
  Hey Brain! What year is it?
  Brain, I can count to 3!
  +-------+
  | value |
  +-------+
  | 1     |
  | 2     |
  | 3     |
  +-------+
  3 rows in set
  => true
  # the above could also have been:
  >> speak '--class=auto_table -r -c3 What year is it?'
  
  # We'll demonstrate --sort and --reverse_sort soon enough ...

A Github Boson Library

Using Pinky was fun to annoy Brain but let’s dig into a more useful example. Consider this command to view a github user’s repositories using the repository API:

  # Drop in ~/.boson/commands/github_example.rb
  module GithubExample
    # @render_options :fields=>{:default=>[:name, :watchers, :forks, :homepage, :description],
    #  :values=>[:homepage, :name, :forks, :private, :watchers, :fork, :url, :description, :owner, :open_issues]}
    # @options :user=>'cldwalker'
    # Displays a github user's repositories
    def repos(options={})
      YAML::load(get("http://github.com/api/v2/yaml/repos/show/#{options[:user]}"))['repositories']
    end
  end

Some points:

The output of repos() is an array of hashes, perfect for Hirb’s tables.
The get() method is a default Boson command which does a get request on a url and returns the response body.
render_options
- Unlike Pinky’s speak(), this command defaults to rendering with Hirb because render_options is present.
- render_options, like options, takes a hash of options which are passed to a Hirb helper.
- Can take existing global options or new options specific to your Hirb helper.
- The above commented render_options could also have been a method call, as was shown with options.
The :values option attribute of the :fields option let’s us do sweet aliasing of option values for :fields and :sort options.

Let’s try it out:

  bash> irb
  >> repos '-u defunkt'
  +---------------------------+----------+-------+-------------------------------------------------------------------+-----------------------------------------------------------------------------------+
  | name                      | watchers | forks | homepage                                                          | description                                                                       |
  +---------------------------+----------+-------+-------------------------------------------------------------------+-----------------------------------------------------------------------------------+
  | grit                      | 10       | 1     |                                                                   |                                                                                   |
  | exception_logger          | 214      | 31    |                                                                   |                                                                                   |
  | ambition                  | 158      | 3     | http://defunkt.github.com/ambition                                | include Enumerable                                                                |
  | starling                  | 54       | 0     | http://rubyforge.org/projects/starling                            |                                                                                   |
  | subtlety                  | 6        | 1     | http://subtlety.errtheblog.com/                                   | Subtlety: SVN => RSS, hAtom => Atom                                               |
  | zippy                     | 8        | 1     |                                                                   | Zippy lil’ zipcode lib.                                                           |
  | cache_fu                  | 265      | 34    | http://errtheblog.com                                             | Everyone's favorite memcached plugin for ActiveRecord.                            |
  | mofo                      | 65       | 9     | http://mofo.rubyforge.org/                                        | Mofo is a fast and simple microformat parser, based on a concise DSL and Hpricot. |
  # ...

  # We can toggle rendering off by passing --render and get back the original return value
  >> repos('-r -u defunkt').size
  => 89

  # Oh the good ol days of inspect
  >> repos('-r -u defunkt').slice(0,2)
  => [{:forks=>1, :url=>"http://github.com/defunkt/grit", :name=>"grit", :watchers=>10, :private=>false, :owner=>"defunkt", :fork=>true,
    :open_issues=>0}, {:forks=>31, :url=>"http://github.com/defunkt/exception_logger", :name=>"exception_logger", :watchers=>214,
    :private=>false, :description=>"", :owner=>"defunkt", :fork=>false, :open_issues=>0, :homepage=>""}]
  
  # Remembering we can pass rendering options, let's only view a couple of fields
  >> repos '-f n,w,op -u defunkt'  # or '--fields name,watchers,open_issues --user defunkt'
  +---------------------------+----------+-------------+
  | name                      | watchers | open_issues |
  +---------------------------+----------+-------------+
  | grit                      | 10       | 0           |
  | exception_logger          | 214      | 0           |
  | ambition                  | 158      | 0           |
  | starling                  | 54       | 0           |
  | subtlety                  | 6        | 0           |
  | zippy                     | 8        | 0           |
  | cache_fu                  | 265      | 2           |
  | mofo                      | 65       | 1           |
  # ...

  # What about global sorting options?
  # Let's see wycats least popular repositories
  >> repos '-s=w -u wycats' # or '--sort=watchers --user=wycats'
  +---------------------------+----------+-------+------------------------------------------+---------------------------------------------------------------------------------------------+
  | name                      | watchers | forks | homepage                                 | description                                                                                 |
  +---------------------------+----------+-------+------------------------------------------+---------------------------------------------------------------------------------------------+
  | rails-shared-benches      | 0        | 0     |                                          | Some Rails benches that work across Rails versions and can be used to compare perf progress |
  | rails                     | 0        | 7     | http://rubyonrails.org                   | Ruby on Rails                                                                               |
  | serialize_location_header | 1        | 0     |                                          | Serialize the location header if it exists                                                  |
  | ufo_book                  | 2        | 0     |                                          | Uses the flying_saucer jruby gem to compile books                                           |
  | ruby-mozjs                | 2        | 0     |                                          | Mozilla JavaScript Engine (SpiderMonkey) bindings for Ruby                                  |
  | rack                      | 3        | 0     | http://rack.rubyforge.org/               | a modular Ruby webserver interface                                                          |
  | lonestar                  | 3        | 0     |                                          |                                                                                             |
 # ...

 # And most popular repositories
 >> repos '-s=w -R -u wycats' # or '--sort=watchers --reverse_sort --user=wycats'
 +---------------------------+----------+-------+------------------------------------------+---------------------------------------------------------------------------------------------+
 | name                      | watchers | forks | homepage                                 | description                                                                                 |
 +---------------------------+----------+-------+------------------------------------------+---------------------------------------------------------------------------------------------+
 | merb-core                 | 611      | 59    | http://www.merbivore.com                 | Merb Core: All you need. None you don't.                                                    |
 | merb                      | 508      | 102   | http://www.merbivore.com                 | master merb branch                                                                          |
 | thor                      | 330      | 26    | http://www.yehudakatz.com                | A scripting framework that replaces rake and sake                                           |
 | merb-more                 | 316      | 32    | http://www.merbivore.com                 | Merb More: The Full Stack. Take what you need; leave what you don't.                        |
 | merb-plugins              | 313      | 42    | http://www.merbivore.com                 | Merb Plugins: Even more modules to hook up your Merb installation                           |
 | moneta                    | 264      | 28    | http://www.yehudakatz.com                | a unified interface to key/value stores                                                     |
 | bundler                   | 228      | 20    |                                          |                                                                                             |
 # ...

 # Of course you can do all of the above from the commandline with the boson command.
 # Even manipulating the command's return value with ruby:
 #
 # bash> boson -e "p repos('-r -u defunkt').size"
 # Loaded library github
 # 89
 #
 # bash> boson -e "p repos('-r -u defunkt').slice(0,2)"
 # Loaded library github
 # [{:forks=>1, :url=>"http://github.com/defunkt/grit", :name=>"grit", :watchers=>10, :private=>false, :owner=>"defunkt", :fork=>true,
 #  :open_issues=>0}, {:forks=>31, :url=>"http://github.com/defunkt/exception_logger", :name=>"exception_logger", :watchers=>214,
 #  :private=>false, :description=>"", :owner=>"defunkt", :fork=>false, :open_issues=>0, :homepage=>""}]

As you can see, writing a Boson command to interact with the Github API is pretty easy. If you liked this sample command, install and try my Github Boson library :

  bash> boson install https://github.com/cldwalker/irbfiles/raw/master/boson/commands/public/site/github.rb
  Saved to /Users/bozo/.boson/commands/github.rb.

  # List the commands that come with the github library
  bash> boson commands -q=l github
 +---------------+--------+-------+------------------------------------------------+-----------------------------------------------------------------------+
  | full_name     | lib    | alias | usage                                          | description                                                           |
  +---------------+--------+-------+------------------------------------------------+-----------------------------------------------------------------------+
  | checkout      | github |       | [url]                                          | Clones a github repo and opens in textmate                            |
  | user_search   | github |       | [query]                                        | Search users                                                          |
  | repo          | github |       | [_search(query]                                | Opens a repo with an optional path in a browser                       |
  | repo_search   | github |       | [query]                                        | Search repositories                                                   |
  | commit_list   | github |       | [user_repo][--branch=master]                   | List commits of a given user-repo                                     |
  | user_repos    | github |       | [--user=cldwalker] [--fork_included] [--stats] | Displays a user's repositories                                        |
  | raw_file      | github |       | [file_url]                                     | Downloads the raw form of a github repo file url                      |
  | repo_network  | github |       | [user_repo][--user=cldwalker]                  | Displays network of a given user-repo i.e. wycats-thor or defunkt/rip |
  | repos_watched | github |       | [user]                                         | Lists repos watched by user                                           |
  | user_follows  | github |       | [user]                                         | List users a user follows                                             |
  +---------------+--------+-------+------------------------------------------------+-----------------------------------------------------------------------+

  # Let's do a repository search
  bash> boson repo_search tagging -s=f  #or tagging --sort=followers
  +------------------------------+---------------+-----------+------------+----------------------+------------+-----------------------------------------------------------------+
  | name                         | username      | followers | language   | pushed               | score      | description                                                     |
  +------------------------------+---------------+-----------+------------+----------------------+------------+-----------------------------------------------------------------+
  | acts-as-taggable-on          | mbleigh       | 633       | Ruby       | 2009-10-14T15:16:26Z | 0.46670222 | A tagging plugin for Rails applications that allows for cust... |
  | is_taggable                  | giraffesoft   | 201       | Ruby       | 2009-08-19T16:03:36Z | 0.3879375  | Tagging that doesn't want to be on steroids. It's skinny and... |
  | acts_as_taggable_on_steroids | jviney        | 118       | Ruby       | 2009-06-12T06:15:45Z | 0.57809234 | Tagging for Ruby on Rails                                       |
  | acts_as_taggable_redux       | geemus        | 100       | Ruby       | 2009-10-05T20:30:11Z | 0.46670222 | Allows for user owned tags to be added to multiple classes, ... |
  | prettyPrint.js               | jamespadolsey | 99        | JavaScript | 2009-06-07T10:17:55Z | 0.3879375  | An in-browser JavaScript variable dumper, similar in functio... |
  | django-uni-form              | pydanny       | 79        | Python     | 2009-09-12T23:47:49Z | 0.31662944 | Django forms are easily rendered as tables, paragraphs, and ... |
  | odf-report                   | sandrods      | 74        | Ruby       | 2009-09-24T03:49:09Z | 0.4354762  | Generates ODF files, given a template (.odt) and data, repla... |
  | prawn-format                 | jamis         | 64        | Ruby       | 2009-03-24T15:30:25Z | 0.3403988  | An extension to the Prawn PDF generation library that allows... |
  # ...

  # Latest commits for a given project in format :user/:repo
  bash> boson commit_list wycats/bundler
  | id                                       | authored_date             | message                                                                              |
  +------------------------------------------+---------------------------+--------------------------------------------------------------------------------------+
  | 8795746808647860b7b44bbb23bf3c64423eb1c8 | 2009-10-06T17:30:31-07:00 | Always generate bin files no matter what.                                            |
  | 87201c825ff487077c4e1b55d449202007be1a42 | 2009-10-06T15:15:41-07:00 | Bump up the version number to 0.7.0.pre                                              |
  | 53c589e1d440c2874ce57ee80047b54af2e8a646 | 2009-10-06T15:15:26-07:00 | Fix branches and #git with block calls                                               |
  | 5bbb5740f3d576f57bd1c7b5c5557b781c22189b | 2009-10-06T12:15:24-07:00 | Add a glob option to directories                                                     |
  | 6f263a435645a2fb76874d0c7f2c83d59eef8e92 | 2009-10-06T00:06:34-07:00 | Add a test that tests overwriting existing bin files                                 |
  | a3694bf09ac8d3093c2ce1a744992e590ab50b5e | 2009-10-05T23:34:39-07:00 | It handles the simple git method as a block                                          |
  # ...

  # List network of a given :user/:repo sorted by most watched
  bash> boson repo_network rails/rails -s=w -R  # or rails/rails --sort=watchers --reverse_sort
  +-----------------------+----------+-------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
  | owner                 | watchers | forks | homepage                    | description                                                                                                                          |
  +-----------------------+----------+-------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
  | rails                 | 4308     | 702   | http://rubyonrails.org      | Ruby on Rails                                                                                                                        |
  | josh                  | 35       | 4     | http://rubyonrails.org      | Ruby on Rails                                                                                                                        |
  | relevance             | 13       | 0     | http://rubyonrails.org      | Ruby on Rails                                                                                                                        |
  | miloops               | 11       | 0     | http://rubyonrails.org      | Ruby on Rails                                                                                                                        |
  | revolutionhealth      | 10       | 0     | http://rubyonrails.org      | Ruby on Rails                                                                                                                        |
  | xing                  | 10       | 0     | http://rubyonrails.org      | Ruby on Rails                                                                                                                        |
  | 37signals             | 9        | 0     | http://rubyonrails.org      | Ruby on Rails                                                                                                                        |
 # ...

Conclusion

As you’ve seen, Boson-Hirb interactions can lead to some novel and useful Ruby commands. Hirb’s instant views, controlled by Boson commands, can make one think of Boson as a commandline MVC framework with an optional V. To learn more about Boson, read it’s docs. I’m eager to see what useful Boson libraries others will come up with. To try out Boson gem install boson boson-more.

Boson - Command Your Ruby Universe

2009-10-14T00:00:00-07:00

Introducing Boson, a command/task framework that could change how you collect and execute your ruby code. Sure, there’s rake, thor and a dozen other gems. But how many will let you create a universe of ruby commands you can run from the commandline and irb?

Spinning On

Feel free to follow Boson on the Hub and to install it:

  $ gem install boson boson-more
  $ echo "require 'boson/more'" >> ~/.bosonrc

To get an idea of Boson’s features, here’s an outline:

Shell and Irb Duality
Creating Commands
Commands With Options
Just Alias It
Using Third Party Commands
Namespaces

Shell and Irb Duality

Like traditional command frameworks, Boson executes commands(tasks) from the commandline:

  # Let's list boson's default libraries
  bash> boson libraries
  +----------+----------+------+--------------+
  | name     | commands | gems | library_type |
  +----------+----------+------+--------------+
  | core     | 6        |      | module       |
  | web_core | 3        |      | module       |
  +----------+----------+------+--------------+
  2 rows in set

  # And default commands
  bash> boson commands
  +--------------+----------+-------+--------------------------------------------+-----------------------------------------------------------------------------+
  | full_name    | lib      | alias | usage                                      | description                                                                 |
  +--------------+----------+-------+--------------------------------------------+-----------------------------------------------------------------------------+
  | usage        | core     |       | [name][--verbose]                          | Print a command's usage                                                     |
  | libraries    | core     |       | [query=''][--index] [--query_fields=A,B,C] | List or search libraries                                                    |
  | render       | core     |       | [object] [options={}]                      | Render any object using Hirb                                                |
  | load_library | core     |       | [library][--verbose] [--reload]            | Load/reload a library                                                       |
  | commands     | core     |       | [query=''][--index] [--query_fields=A,B,C] | List or search commands                                                     |
  | menu         | core     |       | [output] [options={}] [&block]             | Provide a menu to multi-select elements from a given array                  |
  | get          | web_core |       | [url]                                      | Gets the body of a url                                                      |
  | install      | web_core |       | [url][--force] [--name=NAME]               | Installs a library by url. Library should then be loaded with load_library. |
  | browser      | web_core |       | [*urls]                                    | Opens urls in a browser                                                     |
  +--------------+----------+-------+--------------------------------------------+-----------------------------------------------------------------------------+
  9 rows in set
  => true

But unlike others, you can do the same in the ruby console:

  bash> irb
  # You could drop this line in your irbrc
  >> require 'boson'; Boson.start
  Loaded library core
  Loaded library web_core
  => nil

  >> libraries
  +----------+----------+------+--------------+
  | name     | commands | gems | library_type |
  +----------+----------+------+--------------+
  | core     | 6        |      | module       |
  | web_core | 3        |      | module       |
  +----------+----------+------+--------------+
  2 rows in set
  => true

  >> commands
  # same as above ...

How is this done? Commands are simply methods on Ruby’s top level object, main. You provide the methods and Boson manages and empowers them. Even with more complex command usage, the shell/irb duality holds:

  # Print basic command usage in irb
  irb>> commands '-h'
  commands [query=''][--index]
  => nil
  # Or in your shell
  bash> boson commands -h
  # same as above ...
  
  # Search command fields full_name and description for 'lib' and sort by full_name
  irb>> commands 'full_name,description:lib --sort full_name'
  +--------------+----------+-------+-------------------------------------------+-----------------------------------------------------------------------------+
  | full_name    | lib      | alias | usage                                     | description                                                                 |
  +--------------+----------+-------+-------------------------------------------+-----------------------------------------------------------------------------+
  | install      | web_core |       | [url][--force] [--name=NAME]              | Installs a library by url. Library should then be loaded with load_library. |
  | libraries    | core     | lib   | [query=''][--index] [--query_fields=name] | List or search libraries                                                    |
  | load_library | core     | ll    | [library][--verbose] [--reload]           | Load/reload a library                                                       |
  +--------------+----------+-------+-------------------------------------------+-----------------------------------------------------------------------------+
  3 rows in set
  => true

  # In your shell
  bash> boson commands full_name,description:lib --sort full_name
  # same as above ...

  # Using option aliases
  bash> boson commands lib -s f -q=f,d
  # same as above ...

  # Execute a command repo_search under namespace github in irb
  irb>> github.repo_search 'crazy'
  # or in a shell
  bash> boson github.repo_search crazy

Creating Commands

Creating a Boson command is as easy as opening a module and defining a method:

  # Drop this in ~/.boson/commands/brain.rb
  # The module name can be anything but it makes sense to name it the same as the file.
  # The module is evaluated under Boson::Commands
  module Brain
    # Help Brain live his dream
    def take_over(destination)
      puts "Pinky, it's time to take over the #{destination}!"
    end
  end

Let’s give the new command a spin:

  # Unfortunately Brain can't do much right now
  bash> boson take_over farm
  Pinky, it's time to take over the farm!

  # Of course we now have a brain library
  bash> boson libraries
  +----------+----------+------+--------------+
  | name     | commands | gems | library_type |
  +----------+----------+------+--------------+
  | core     | 6        |      | module       |
  | web_core | 3        |      | module       |
  | brain    | 1        |      | file         |
  +----------+----------+------+--------------+
  3 rows in set

  # And a take_over command
  bash> boson commands take
  +-----------+-------+-------+---------------+---------------------------+
  | full_name | lib   | alias | usage         | description               |
  +-----------+-------+-------+---------------+---------------------------+
  | take_over | brain |       | [destination] | Help Brain live his dream |
  +-----------+-------+-------+---------------+---------------------------+
  1 row in set

  # And of course you can execute this all from irb ...

As you can see, Boson lets you write your libraries and commands in plain ruby. Module-method DSLs be damned. If you want more commands for the brain library, add more methods to Brain in the file. Also notice that Boson automatically generates a command’s usage and description from the method’s arguments and the comment above it.

So that’s cool. Boson’s libraries are just modules and its commands just methods. But if this is all the functionality Boson offers, why bother with it at all?

Commands With Options

Borrowing from Thor, Boson commands can have simple yet powerful options. Let’s add some to take_over():

  module Brain
    options :execute=>:boolean, :countdown=>:numeric
    # Help Brain live his dream
    def take_over(destination, options={})
      puts "Pinky, it's time to take over the #{destination}!"
      sleep(options[:countdown]) if options[:countdown]
      system("/home/brain/take_over/#{destination}") if options[:execute]
    end
  end

Brain always has the best of intentions:

  bash> boson take_over world --execute --countdown=3
  Pinky, it's time to take over the world!
  # program sleeps 3 seconds
  # executes `/home/brain/take_over/world`

  # Thanks to auto-generated option aliases
  bash> boson take_over world -e -c3
  # same as above ...

  # Boson still holds true to its irb duality
  bash> irb
  >> take_over 'world -e -c3'
  # same as above ...

  # And if you want, call your command in plain ruby
  >> take_over 'world', :execute=>true, :countdown=>3

A few points:

options() takes a hash of options with names mapping to option types
Short flags or option aliases are automatically generated based on the first letter of the option name.
Options have plenty of functionality.
Commands with options must expect their last argument to be an options hash.

So it’s great that options can be defined concisely, but whatever happened to just writing commands in plain ruby? Well, Boson actually lets you but it’s gonna cost you 2 more characters:

  module Brain
    #@options :execute=>:boolean, :countdown=>:numeric
    # Help Brain live his dream
    def take_over(destination, options={})
    # ....
  end

As you can see, I commented out the DSL method and prepended ‘options’ with ‘@’. This command still has the same functionality while still keeping it all in plain ruby.

Just Alias It

Built with the power user in mind, Boson encourages aliasing of commands, options and even option values. Let’s take a look at each.

Aliasing Commands

Aliasing commands is done through Boson’s main config file at ~/.boson/config/boson.yml. For an example config file, see mine. Let’s add command aliases for the default command commands and our example command take_over:

  # Drop this in ~/.boson/config/boson.yml
  :command_aliases:
    commands: com
    take_over: take

  # Back in the shell
  # List commands with 'com' or 'take in its name:
  bash> boson -l=brain com com\|take
  +-----------+-------+-------+------------------------------------------------+---------------------------+
  | full_name | lib   | alias | usage                                          | description               |
  +-----------+-------+-------+------------------------------------------------+---------------------------+
  | commands  | core  | com   | [query=''][--index] [--query_fields=full_name] | List or search commands   |
  | take_over | brain | take  | [destination]                                  | Help Brain live the dream |
  +-----------+-------+-------+------------------------------------------------+---------------------------+
  2 rows in set

  # And if we wanted to execute take_over with the new alias
  bash> boson take world -e -c3

Aliasing Options

As explained above, options automatically have aliases generated for them. But if you want, specify your own aliases in options():

  # Let's add some aliases to the execute option
  
  module Brain
    #@options [:execute, :conquer, :x]=>:boolean, :countdown=>:numeric
    # ...
  end

  # The execute option can now be called with -x and --conquer

Aliasing Option Values

Aliasing option values is possible for option types :string and :array. But unlike the other aliases, you specify a unique string that a value starts with rather than define explicit aliases. Let’s redo take_over() to take a :string option with some expected values:

  module Brain
    #@options :destination=>{:type=>:string, :values=>%w{world farm fjord}},
    # :execute=>:boolean, :countdown=>:numeric
    # Help Brain live his dream
    def take_over(options={})
      puts "Pinky, it's time to take over the #{options[:destination]}!"
      sleep(options[:countdown]) if options[:countdown]
      system("/home/brain/take_over/#{options[:destination]}") if options[:execute]
    end
  end

As you can see we added a :destination option with a :values attribute. With this attribute, the :destination option is able to instantly alias those values. For more about the :values attribute see here. Let’s see this aliasing in action:

  # 'f' will match 'farm' over 'fjord' since values are searched alphabetically
  bash> boson take -d=f
  Pinky, it's time to take over the farm!

  # It's still easy to get fjord
  bash> boson take -d=fj
  Pinky, it's time to take over the fjord!

  # This is what Brain really wants to do
  bash> boson take -d=w -e
  Pinky, it's time to take over the world!

  # If at any time you need to remember your option's values
  bash> boson -hv take
  Loaded library core
  Loaded library web_core
  Loaded library brain
  take [--execute] [--destination=DESTINATION] [--countdown=N]

  COMMAND OPTIONS
  +---------------+-------+---------+------------------+
  | Option        | Alias | type    | Values           |
  +---------------+-------+---------+------------------+
  | --countdown   | -c    | numeric |                  |
  | --destination | -d    | string  | world,farm,fjord |
  | --execute     | -e    | boolean |                  |
  +---------------+-------+---------+------------------+
  # ...

You may be pleased to know that the default commands libraries and commands come with all this goodness:

  bash> irb
  >> commands '-hv'
  commands [query=''][--index]

  COMMAND OPTIONS
  +----------------+-------+---------+----------------+------------------------------------------------------------------------+
  | Option         | Alias | type    | Description    | Values                                                                 |
  +----------------+-------+---------+----------------+------------------------------------------------------------------------+
  | --index        | -i    | boolean | Searches index |                                                                        |
  +----------------+-------+---------+----------------+------------------------------------------------------------------------+

  GLOBAL/RENDER OPTIONS
  +----------------+-------+---------+-----------------------------------------------------------+------------------------------------------------------------------------+
  | Option         | Alias | type    | Description                                               | Values                                                                 |
  +----------------+-------+---------+-----------------------------------------------------------+------------------------------------------------------------------------+
  | --class        | -c    | string  | Hirb helper class which renders                           |                                                                        |
  | --fields       | -f    | array   | Displays fields in the order given                        | name,lib,alias,description,options,args,usage,full_name,render_options |
  | --help         | -h    | boolean | Display a command's help                                  |                                                                        |
  | --max_width    | -m    | numeric | Max width of a table                                      |                                                                        |
  | --pretend      | -p    | boolean | Display what a command would execute without executing it |                                                                        |
  | --render       | -r    | boolean | Toggle a command's default rendering behavior             |                                                                        |
  | --reverse_sort | -R    | boolean | Reverse a given sort                                      |                                                                        |
  | --sort         | -s    | string  | Sort by given field                                       | name,lib,alias,description,options,args,usage,full_name,render_options |
  | --verbose      | -v    | boolean | Increase verbosity for help, errors, etc.                 |                                                                        |
  | --vertical     | -V    | boolean | Display a vertical table                                  |                                                                        |
  +----------------+-------+---------+-----------------------------------------------------------+------------------------------------------------------------------------+
 => true

  # Don't worry about the other options. To be covered in another blog post :p

So yes, you can search commands and libraries while choosing which fields to search, sort and display with aliased options and option values!

Using Third Party Commands

Boson makes it dead easy to install someone else’s commands:

  # Let's download a library which explains irb's default commands
  bash> boson install https://github.com/cldwalker/irbfiles/raw/master/boson/commands/public/irb_core.rb
  Saved to /Users/bozo/.boson/commands/irb_core.rb

  # Let's see the commands in irb
  bash> irb
  >> commands '-q=l irb_core'
  +-------------------------------+----------+------------+-------+-----------------------------------------------------------------------------+
  | full_name                     | lib      | alias      | usage | description                                                                 |
  +-------------------------------+----------+------------+-------+-----------------------------------------------------------------------------+
  | irb_pop_workspace             | irb_core | popws      |       | Pops current workspace and changes to next workspace in context             |
  | irb_require                   | irb_core |            |       | Evals file like require line by line                                        |
  | public                        | irb_core |            |       | Works same as module#public                                                 |
  | private                       | irb_core |            |       | Works same as module#private                                                |
  | irb                           | irb_core |            |       | Starts a new workspace/subsession                                           |
  | irb_push_workspace            | irb_core | pushws     |       | Creates a workspace for given object and pushes it into the current context |
  | irb_load                      | irb_core |            |       | Evals file like load line by line                                           |
  | irb_change_workspace          | irb_core | cws        |       | Changes current workspace to given object                                   |
  | irb_source                    | irb_core | source     |       | Evals full path file line by line                                           |
  | irb_jobs                      | irb_core | jobs       |       | List workspaces/subsessions                                                 |
  | irb_fg                        | irb_core | fg         |       | Switch to a workspace/subsession                                            |
  | irb_help                      | irb_core | help       |       | Ri based help                                                               |
  | irb_kill                      | irb_core | kill       |       | Kills a given workspace/subsession                                          |
  | include                       | irb_core |            |       | Works same as module#include                                                |
  | irb_exit                      | irb_core | exit       |       | Kills the current workspace/subsession                                      |
  | irb_workspaces                | irb_core | workspaces |       | Array of workspaces for current context                                     |
  | irb_context                   | irb_core | conf       |       | Displays configuration for current workspace/subsession                     |
  | install_alias_method          | irb_core |            |       | Aliases given method, allows lazy loading of dependent file                 |
  | irb_current_working_workspace | irb_core | cwws       |       | Prints current workspace                                                    |
  +-------------------------------+----------+------------+-------+-----------------------------------------------------------------------------+
  19 rows in set
  => true

  # Sweet! Now we have a list and description of commands that come with irb.

If you remember, Boson’s libraries are just modules. So any url that points to a ruby module now offers you a library of Boson commands. You can even have the installer automatically wrap ruby code in a method and a module to make it a valid Boson library.
For example, take this gist for displaying authors on a git repository:

Let’s commandify it:

  bash> boson install https://gist.github.com/raw/203861/c063260bef7f004c9db4c2a7719ff649b59d3ade/git-authors -m
  Saved to /Users/bozo/.boson/commands/git_authors.rb.
  
  # Verify we have the command
  bash> boson commands auth
  +-------------+-------------+-------+-------+-------------+
  | full_name   | lib         | alias | usage | description |
  +-------------+-------------+-------+-------+-------------+
  | git_authors | git_authors |       |       |             |
  +-------------+-------------+-------+-------+-------------+
  1 row in set

  # Running this in my local repo of http://github.com/wycats/thor
  bash> boson git_authors
  * José Valim
  * Nathan Weizenbaum
  * Yehuda Katz
  * Brian Donovan
  * Fabien Franzen
  * Mislav Marohnić
  * James Herdman
  * Charles Jolley
  * Markus Prinz
  * Luis Lavena
  * Damian Janowski
  * Jack Dempsey
  * valodzka
  * Gabriel Horner
  * Edwin Moss

To try some third-party Boson libraries, here are some of mine I recommend.

Namespaces

If you’re familiar with rake and thor, you may be surprised that there has been no mention of namespaces. That’s because by default they’re optional. Boson, like Ruby, assumes you’re grown up enough to balance power and peril. To aid with keeping the default namespace clean, Boson doesn’t load a library if it introduces a command which will conflict with existing commands. This conflict detector will even catch third-party gems who pollute the default namespace by monkeypatching Kernel or Object. You can turn off the conflict detector per library as needed. If Boson’s conflict detector isn’t comforting enough, no worries. You can configure any library to have a namespace. And if you yearn for namespacing by default, simply drop :auto_namespace: true into your ~/.boson/config/boson.yml.

Spinning Off

Although we’ve covered most of Boson’s basics, we still haven’t touched on how Boson integrates with Hirb. That’s for the next post.

And for all you physics geeks out there:

  >> Boson.higgs.instance_eval("class << self; self end").ancestors[1]
  => Boson::Universe

UPDATE: The format for querying commands and libraries has changed since this was posted. The above examples have been updated to reflect this. Examples:

  # With the old format fields to query were passed to --query_fields
  bash> boson commands lib --query_fields=full_name --sort=full_name   # or commands lib -q=f -s=f

  # With the new format, fields are placed before a query with a ':'
  # --query_fields doesn't exist
  bash> boson commands full_name:lib --sort=full_name     # or commands f:lib -s=f

  # The new format still maintains the old format of querying with an implicit query field.
  # The implicit field is 'name' for libraries.
  bash> boson libraries core     # same as libraries name:core

  # With the new format all fields can be queried using a '*'
  # Searches library fields: gems,dependencies,commands,loaded,module,name,namespace,indexed_namespace,library_type
  bash> boson libraries *:core

  # The new format allows for multiple searches to be joined together by ','
  # This query searches for libraries that have the name matching core or a library_type matching gem
  bash> boson libraries name:core,library_type:gem

Tagaholic - Posts tagged 'ruby'

Tux - A Sinatra Console

Install and Try On

Interact with App Methods

Interact with App Responses

Commands and Configuration

One9 - Upgrade to Ruby 1.9 Now

Install

How it works

Run tests

Edit Changes

Rails Tips

Configure

Motivation

Conclusion

One9 - Upgrade to Ruby 1.9 Now

Install

How it works

Run tests

Edit Changes

Rails Tips

Configure

Motivation

Conclusion

Documentation-Generated Irb Autocompletions With Bond and Yard

Screencast Of Argument Autocompletion for Methods in Irb

Screencast

Screencast Notes

Install

Further Reading

Lightning - Speed For The User

Overview

Wrap Up

Lightning - Speed For Your Shell

Overview

Hirb - And Tables for All

Database Gems

Examples

Dynamic Views

Creating Them

Submitting Them

Two Dimensional Console Menus with Hirb

Intro

2D Action Menus

Chaining APIs

Opening and Editing Bookmarks within Rails

Playing Songs

Gemspecs Revisited

Final Thoughts

Using Gemcutter's Api from the Commandline

Usage

Wrap Up

Typing Less in Irb with method_missing

Explanation

Finished Snippet

Boson - Command Your Ruby Universe - Part Deux

Overview

Ruby Reference Commands With Boson

Game Plan

Game Over

How Boson Enhances Your Irb Experience

Preface

Postface

Boson And Hirb Interactions

Conclusion

Boson - Command Your Ruby Universe

Spinning On

Spinning Off