= irbtools
The irbtools gem is a meta gem that installs handy and useful irb gems and provides an appealing ready-to-use irb configuration. It has a modular structure and supports multiple library-loading mechanisms, e.g. via <tt>autoload</tt> or threads.

== Setup

  gem install irbtools
  
* On Linux, you need +xclip+ or +xsel+ to use the clipboard: sudo <tt>apt-get install xclip</tt>
* On Windows, you need ansicon[https://github.com/adoxa/ansicon] to enjoy all the colors
* On MacOS, you need growl, to use the +g+ gem.

== Usage
To use *irbtools*, put the following in your <tt>~/.irbrc</tt> file (this file is loaded every time you start irb):

  require 'rubygems' unless defined? Gem # rubygems is only needed in 1.8
  require 'irbtools'

If the file does not exist, just create a new one. See further below on how to customize loaded libraries.

=== Rails notes
To integrate irbtools into a rails console, you can either add <tt>irbtools</tt> to your Gemfile:

  gem 'irbtools', :require => false

Another way is to add a debundle hack on top of your <tt>~/.irbrc</tt>:

  # modified from https://github.com/ConradIrwin/pry-debundle/pull/5
  if defined?(Gem.post_reset_hooks)
    Gem.post_reset_hooks.reject!{ |hook| hook.source_location.first =~ %r{/bundler/} }
    Gem::Specification.reset
    load 'rubygems/custom_require.rb'
    alias gem require                                                              
  end

See {this blog post}[http://rbjl.net/49-railsrc-rails-console-snippets] for some Rails integration features.

=== Yesterday's Ruby versions

*irbtools* focuses on Ruby 1.9 support. To get it working with 1.8.7, use the following line in your Gemfile:

  gem 'irbtools', :git => "git://github.com/janlelis/irbtools.git", :branch => 'legacy', :require => false

=== This is irbtools "light"

When installing *irbtools*, some gems won't be installed to keep windows support, e.g. better auto-completion or the looksee gem. These are packaged in the {irbtools-more}[https://github.com/janlelis/irbtools-more] gem. To use them, you need to change your <tt>.irbrc</tt> to:

  require 'irbtools/configure'
  Irbtools.add_package :more
  Irbtools.start

=== Included gems and libraries

See http://rbjl.net/40-irbtools-release-the-power-of-irb or read the commented source files to get some examples of what you can do with irbtools.

[wirb[https://github.com/janlelis/wirb/]]                  Colorizes Ruby objects (used for the results)
[paint[https://github.com/janlelis/paint/]]                Provides easily to use terminal colors
[hirb[http://tagaholic.me/2009/03/13/hirb-irb-on-the-good-stuff.html]]
                                                           Custom views for specific objects, e.g. tables for ActiveRecord
[fancy_irb[https://github.com/janlelis/fancy_irb]]         Hash rockets for results and colorful error messages
[every_day_irb[https://github.com/janlelis/irbtools/tree/master/lib/every_day_irb.rb]]
                                                           Contains helper methods that might be useful in every-day irb usage, see below for details
[clipboard[http://github.com/janlelis/clipboard]]          Easy clipboard access
[interactive_editor[https://github.com/jberkel/interactive_editor]]
                                                           Lets you open vim from within irb to hack something that gets loaded into the current session, also possible: yaml object editing
[sketches[http://sketches.rubyforge.org/]]                 Another, more flexible "start editor and it gets loaded into your irb session" plugin
[zucker[http:/rubyzucker.info]]                            Nice debug printing (<tt>q</tt>, <tt>o</tt>, <tt>c</tt>, <tt>Object#m</tt>, <tt>Object#d</tt>) and useful pseudo-constants (<tt>Info</tt>, <tt>OS</tt>, <tt>RubyVersion</tt>, <tt>RubyEngine</tt>)
[ap[https://github.com/michaeldv/awesome_print]]           Nice debug printing commands (<tt>ap</tt>) [also possible: <tt>wp</tt> from wirb/wp]
[coderay[http://coderay.rubychan.de/]]                     Colorizes Ruby code (<tt>colorize</tt>, <tt>ray</tt>)
[boson[http://tagaholic.me/boson/]]                        "A command/task framework similar to rake and thor that opens your ruby universe to the commandline and irb."
[methodfinder[https://github.com/citizen428/methodfinder]] Interesting method finder (<tt>mf</tt>)
[ori[https://github.com/dadooda/ori]]                      Adds an <tt>Object#ri</tt> method
[method_locator[https://github.com/ryanlecompte/method_locator]] Provides <tt>Object#method_lookup_path</tt> (improved version of <tt>Module#ancestors</tt>) and <tt>Object#methods_for</tt> (get this method from all ancestors)
[method_source[https://github.com/banister/method_source]] <tt>Object#src</tt> can be shown for Ruby methods
[bond[http://tagaholic.me/bond/]]                          <b>irbtools-more:</b> Improves irb tab-completion
[looksee[https://github.com/oggy/looksee]]                 <b>irbtools-more:</b> Great load path inspector: <tt>Object#l</tt> (Extended version of <tt>Object#m</tt>), also provides the ability to <tt>Object#edit</tt> methods.
[drx[http://drx.rubyforge.org/]]                           <b>irbtools-more:</b> A tk object inspector, defines <tt>Object#see</tt>
[*fileutils* (stdlib)]                                     Includes file system utility methods: <tt>cd</tt>, <tt>pwd</tt>, <tt>ln_s</tt>, <tt>mv</tt>, <tt>rm</tt>, <tt>mkdir</tt>, <tt>touch</tt>, ... ;)

=== Not included anymore

[guessmethod[http://guessmethod.rubyforge.org/]] Automatically tries to corrects typos in method names
[rvm_loader] RVM helpers

=== Irbtools methods

The following general helper methods are defined by <b>every_day_irb</b> (which belongs to *irbtools*)

[ls]     Returns an array with the directory's content
[cat]    Shortcut for <tt>File.read</tt>
[rq]     Shortcut for <tt>require library.to_s</tt> (allows concise syntax like <tt>rq:mathn</tt>)
[ld]     Shortcut for <tt>load library.to_s + '.rb'</tt>
[rrq/rerequire] Little hack for rerequiring a library (it's really hack and not reliable, but works in most cases)
[reset!] Restarts irb
[clear]  Clears your irb terminal (<tt>system "clear"</tt>)
[session_history] Returns all issued commands as string

Irbtools also defines some more helpers in combination with the loaded gems:

[cd]     Improves the cd that is already provided by *FileUtils* (try <tt>cd '-'</tt>)
[rv]     Displays RubyVersion (*zucker*)
[re]     Displays RubyEngine (*zucker*)
[colorize] Syntax highlights a ruby string using *CodeRay*
[ray]    Syntax highlights a ruby file using *CodeRay*
[copy]   Shortcut for <tt>Clipboard.copy</tt>
[paste]  Shortcut for <tt>Clipboard.paste</tt>
[copy_input]  Copies the session_history to the clipboard
[copy_output] Copies this session's results to the clipboard
[mf]     Shortcut for using the *methodfinder*

These are the custom public +Object+ methods renamed/patched for some gems

[ri]     Patching the +ri+ provided by *ori* to also allow default ri syntax on toplevel
[src]    Shortcut for displaying the method source using *method_source* and *coderay*
[l/ll]   Alternative method name to trigger the *looksee* gem (<b>irbtools-more</b>)


=== How to load more or less libraries

It's possible to modify, which libraries should get loaded:

  # don't require 'irbtools', but:
  require 'irbtools/configure'
  # here you can modify the libraries using the methods below
  Irbtools.start

If you don't want to load the default set of irbtools gems, you will have to use <tt>require 'irbtools/minimal'</tt> instead of <tt>configure</tt>.

You have the following methods:
* <tt>Irbtools.add_library(lib, options_hash, &block)</tt>
* <tt>Irbtools.remove_library(lib)</tt>

The <tt>options_hash</tt> defines the way in which Irbtools loads the library. Following options are possible
[(no options)/<tt>:start</tt>] The library is required on startup before doing anything else (before displaying the prompt)
[<tt>:thread => identifier</tt>] After loading everything else, the library is required in a thread (while continuing loading). You can choose any identifier, but if you take the same one for multiple libraries, they will be loaded in the same thread (in the order that you define)
[<tt>:late => true</tt>] The library is required just before showing the prompt (note: loading threads might still be in process)
[<tt>:late_thread => identifier</tt>] Same as <tt>:thread</tt>, but after loading late libraries.
[<tt>:sub_session => true</tt>] The library is loaded every time a sub-session starts (using <tt>IRB.conf[:IRB_RC]</tt>). In ripl[https://github.com/cldwalker/ripl], <tt>ripl-after_rc</tt> is used.
[<tt>:autoload => :Constant</tt>] Use Ruby's <tt>autoload</tt> feature. It loads the library as soon as the constant is encountered.

You can also apply a block that gets executed after the library is loaded (except for autoload, the code will executed on startup in this case). You can also just add callback block by using the <tt>Irbtools.add_library_callback</tt> or the <tt>Irbtools.replace_library_callback</tt> method.

When adding a new library, you should firstly consider some way to load it via <tt>:autoload</tt>.
If not possible, try loading via thread.
If that is not possible either, fallback to the default loading.

== Troubleshooting: Unicode caused Wrong display widths?
When using double-width unicode chars, you need to paste the following snippet to your <tt>.irbrc</tt>.

  Irbtools.replace_library_callback :fancy_irb do
    FancyIrb.start :east_asian_width => true
  end

This setting is deactivated by default because of performance issues.

== Hint: Faster start-up

You can get an about a second faster start-up time by changing the loading methods for wirb and fancy_irb to <tt>:thread</tt> (drawback: the hash rocket will not be used for the first result):

  require 'irbtools/configure'
  Irbtools.remove_library :paint
  Irbtools.remove_library :fancy_irb
  Irbtools.add_library :paint, :late => true do Wirb.load_schema :classic_paint if defined? Wirb end
  Irbtools.add_library :fancy_irb, :thread => -1 do FancyIrb.start end
  Irbtools.start

== Welcome message
The welcome message can be customized with <tt>Irbtools.welcome_message=</tt>

== Packages
There are irbtools extension packages, which can be modified via:
* <tt>Irbtools.add_package(pkg)</tt>
* <tt>Irbtools.remove_package(pkg)</tt>

These packages add/modify the libraries to be loaded. For an example, see {irbtools-more}[https://github.com/janlelis/irbtools-more].

== Copyright
Copyright (c) 2010-2012 Jan Lelis, http://rbjl.net, released under the MIT license.

== J-_-L