hairballs 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4d0f86e9c3d02f22b832c4b3edce907001d0db2f
+  data.tar.gz: 7ddc281fd14c1d9c673b59bd6ca1f218e1722f2a
+SHA512:
+  metadata.gz: 0ed4bf7812d457c37d006c4b6b065a6a05df37aba2991f77fa261aa2939bc51ef1df35a55d861a75b5fc93ffe556d4a102a618f99f84dc4126a174679fa4311b
+  data.tar.gz: 11bf1690a4fd0c528223c4608bbc757a17720f64dfdc137ffe58abae6e505499c790e32c711203f2d768fabfe09900b6c0f6b9872dbb5da9539e50164f211c53

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hairballs.gemspec
+gemspec

data/History.md

@@ -0,0 +1,3 @@
+### 0.0.1 / 2014-12-19
+
+* Happy Birthday!

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Steve Loveless
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,250 @@
+hairballs
+=========
+
+Aka, "haIRBalls".  Like [oh-my-zsh](http://ohmyz.sh), but for IRB.
+
+wat
+---
+
+haIRBalls is a framework for managing your IRB configuration.
+
+Installation
+------------
+
+For non-Bundlered apps, install it yourself as:
+
+    $ gem install hairballs
+
+For Bundlered apps, you have a couple options:
+
+1. Add `gem 'hairballs'` to your Gemfile.
+1. Manually add `hairballs` to the load path:
+
+    ```ruby
+    hairballs_path = Dir.glob("#{Gem.dir}/gems/hairballs-*/lib")
+    $LOAD_PATH.unshift(hairballs_path.first) unless hairballs_path.empty?
+    require 'hairballs'
+    ```
+
+Usage
+-----
+
+Hairballs provides you with methods and such for creating "themes" and "plugins"
+that you add in to your IRB sessions.
+
+### Themes ###
+
+Initially *themes* are for defining an IRB prompt using a cleaner API than the
+one provide by IRB.  They are a) reusable and b) can be switched on the fly,
+without requiring a reload of IRB.  Hairballs also provides methods for dealing
+with dependencies and getting those dependencies to play nice with Bundler.
+
+**Example: A Rails Theme**
+
+This:
+
+```ruby
+# ~/.irbrc
+
+# Specify dependencies.
+libraries = %w[irb/completion awesome_print wirble looksee]
+
+libraries += case RUBY_PLATFORM
+  when /mswin32|mingw32/
+    %w[win32console]
+  when /darwin/
+    %w[terminal-notifier]
+  else
+    []
+
+# Only setup prompt if Rails.
+if ENV['RAILS_ENV'] || defined? Rails
+  # Allow non-Gemfile deps to work with Rails.
+  if defined?(::Bundler)
+    all_global_gem_paths = Dir.glob("#{Gem.dir}/gems/*")
+
+    all_global_gem_paths.each do |p|
+      gem_path = "#{p}/lib"
+      $:.unshift(gem_path)
+    end
+  end
+
+  # Setup the prompt.
+  rails_root = File.basename(Dir.pwd)
+
+  IRB.conf[:PROMPT][:RAILS] = {
+    AUTO_INDENT: true,
+    PROMPT_I: "#{rails_root}> ",
+    PROMPT_S: "#{rails_root}❊%l> ",
+    PROMPT_C: "#{rails_root}⇥ %i> ",
+    PROMPT_N: "#{rails_root}⇥ %i> ",
+    RETURN:   "➥ %s\n"
+  }
+  IRB.conf[:PROMPT_MODE] = :RAILS
+end
+
+# Require/install dependencies.
+libraries.each do |lib|
+  retry_count = 0
+
+  begin
+    break if retry_count == 2
+    puts "Requiring library: #{lib}"
+    require lib
+  rescue LoadError
+    puts "#{lib} not installed; installing now..."
+    Gem.install lib
+    retry_count += 1
+    retry
+  end
+end
+```
+
+...becomes this:
+
+```ruby
+# hairballs/themes/turboladen_rails.rb
+Hairballs.add_theme(:turboladen_rails) do |theme|
+  theme.libraries do
+    libs_to_require = %w(irb/completion looksee wirble awesome_print)
+
+    libs_to_require +
+      case RUBY_PLATFORM
+      when /mswin32|mingw32/
+        %w(win32console)
+      when /darwin/
+        %w(terminal-notifier)
+      else
+        []
+      end
+  end
+
+  theme.extend_bundler = true
+
+  theme.prompt do |prompt|
+    preface = Hairballs.project_name
+
+    prompt.auto_indent          = true
+    prompt.normal               = "#{preface}> "
+    prompt.continued_string     = "#{preface}❊%l> "
+    prompt.continued_statement  = "#{preface}⇥ %i> "
+    prompt.indented_code        = "#{preface}⇥ %i> "
+    prompt.return_format        = "➥ %s\n"
+  end
+end
+
+# ~/.irbrc
+require 'hairballs/themes/turboladen_rails'
+
+if Hairballs.rails?
+  Hairballs.use_theme(:turboladen_rails)
+end
+```
+
+In the end, your .irbrc is cleaned up and the theme used there can be reused and
+maintained separately.  Check out the `Hairballs::Theme` docs and existing
+themes under lib/hairballs/themes/ for more details and ideas.
+
+### Plugins ###
+
+*Plugins* are similar to *themes* in that they let you abstract away some code
+from your .irbrc, thus making it cleaner and more maintainable.  The essence of
+plugins, however, is to allow you to change the behavior of or add behavior to
+IRB; this could mean things like:
+
+* Installing and configuring dependencies for IRB use.
+* Adding helper methods to your IRB session.
+* Adding methods to certain objects, say, for debugging.
+* Changing how certain objects are displayed when returned from methods.
+
+**Example: Wirble**
+
+Wirble has been around for years and I still like it for colorizing returned
+objects in IRB.  Using a Hairballs plugin for wrapping this a) ensures wirble
+is installed any time I want to use it, and b) runs the initializing of wirble
+but keeps the code for doing so outside of my .irbrc.
+
+```ruby
+# hairballs/plugins/wirble.rb
+Hairballs.add_plugin(:wirble) do |plugin|
+  plugin.libraries %w(wirble)
+
+  plugin.on_load do
+    Wirble.init
+    Wirble.colorize
+  end
+end
+
+# ~/.irbrc
+require 'hairballs/plugins/wirble'
+
+Hairballs.load_plugin(:wirble)
+```
+
+Check out the Hairballs::Plugin docs and existing plugins under
+lib/hairballs/plugins/ for more details and ideas.
+
+I've got my `.irbrc` (using Hairballs) stored on the interwebs
+[here](https://github.com/turboladen/config_files/blob/master/.irbrc) if
+that's of any help or interest.
+
+But whyyyy?
+--------
+
+There's some similar tools out there, but they seemed overly complicated.  IRB
+is a tool for doing development and those, in my opinion, should be as simple
+and straightforward as possible.
+
+**tl:dr**
+
+I wanted to...
+
+* abstract away some of IRB's weirdness.
+* manage IRB dependencies based on my preferences.
+* for Bundler apps, use gems in IRB without having to add them to your Gemfile.
+* keep `.irbrc` clean.  Make helpers reusable.
+
+**Moar explain.**
+
+Some problems I faced:
+
+* Rails console loads ~/.irbrc.  If you have gem dependencies in there, you
+  have to add them to your Gemfile to add them to the bundle.
+    * This doesn't make sense to me.  You shouldn't make the others that are
+      developing that app with you use gems for *your* IRB configuration.
+    * *Solution:* `Hairballs::LibraryHelpers#libraries` and
+      `Hairballs::LibraryHelpers#require_libraries`, which are available to *Themes*
+      and *Plugins*.
+* I want different prompt styles for regular ol' IRB vs Rails console.
+    * *Solution:* `Hairballs::Theme`s.
+* Customizing my prompt(s) felt so clunky!
+    * *Solution:* `Hairballs::Theme`s.
+* Installing and using new Rubies then running IRB meant I had to exit out and
+  manually install them all.
+    * zzzzzzzz...
+    * *Solution:* `Hairballs::LibraryHelpers#libraries` and
+      `Hairballs::LibraryHelpers#require_libraries`.
+* I kept having problems with IRB and history getting all out of order--usually
+  with Rails.  I was using `'irb/history'`, but trying to figure out what was
+  wrong was difficult since my .irbrc had become a sprawling mass of one-off
+  methods and blocks.
+    * *Solution:* `hairballs/plugins/irb_history`.  This sets up IRB to use its
+      `*HISTORY*` settings properly and cleanly.
+* Specifying gems as IRB dependencies for different Ruby interpreters is simple
+  but can clutter up your .irbrc.
+    * Putting the deps with the plugin or theme that needs them keeps everything
+      together and out of the .irbrc.
+    * *Solution:* *Themes* and *Plugins* let you specify only the gems you need
+      for those items.  Logic surrounding that (ex. platform-specific) is kept
+      out of your .irbrc.
+
+Contributing
+------------
+
+Your themes and plugins are welcome!
+
+1. Fork it ( https://github.com/turboladen/hairballs/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,4 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new

data/hairballs.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hairballs/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'hairballs'
+  spec.version       = Hairballs::VERSION
+  spec.authors       = ['Steve Loveless']
+  spec.email         = ['steve.loveless@gmail.com']
+  spec.summary       = 'Like oh-my-zsh, but for IRB.'
+  spec.description   = 'Some tools for making customizing your IRB sessions a little easier.'
+  spec.homepage      = 'https://github.com/turboladen/hairballs'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(spec)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.1'
+end

data/lib/hairballs/exceptions.rb

@@ -0,0 +1,22 @@
+class Hairballs
+  class PluginNotFound < RuntimeError
+    def initialize(plugin_name)
+      message = "Plugin not found: :#{plugin_name}."
+      super(message)
+    end
+  end
+
+  class PluginLoadFailure < RuntimeError
+    def initialize(plugin_name)
+      message = "Unable to load plugin: :#{plugin_name}."
+      super(message)
+    end
+  end
+
+  class ThemeUseFailure < RuntimeError
+    def initialize(theme_name)
+      message = "Theme not found: :#{theme_name}."
+      super(message)
+    end
+  end
+end

data/lib/hairballs/ext/kernel_vputs.rb

@@ -0,0 +1,7 @@
+module Kernel
+  # Does a puts only if IRB is in verbose mode.
+  def vputs(*messages)
+    messages.map! { |m| "[Hairballs] #{m}" }
+    puts(*messages) if defined?(::IRB) && ::IRB.conf[:VERBOSE]
+  end
+end

data/lib/hairballs/library_helpers.rb

@@ -0,0 +1,85 @@
+class Hairballs
+  # Helpers specifying and requiring dependencies for Themes and Plugins.
+  module LibraryHelpers
+    # @param libs [Array<String>]
+    def libraries(libs=nil)
+      return @libraries if @libraries && libs.nil?
+
+      @libraries = block_given? ? yield : libs
+
+      unless @libraries.is_a?(Array)
+        fail ArgumentError,
+          "Block must return an Array but returned #{@libraries}."
+      end
+
+      @libraries
+    end
+
+    # Requires #libraries on load.  If they're not installed, install them.  If
+    # it can't be installed, move on to the next.
+    def require_libraries
+      return if @libraries.nil?
+
+      @libraries.each do |lib|
+        retry_count = 0
+
+        begin
+          next if retry_count == 2
+          vputs "Requiring library: #{lib}"
+          require lib
+        rescue LoadError
+          puts "#{lib} not installed; installing now..."
+          Gem.install lib
+
+          if Hairballs.rails?
+            installed_gem = find_latest_gem(lib)
+            $LOAD_PATH.unshift("#{installed_gem}/lib")
+          end
+
+          require lib
+          retry_count += 1
+          retry
+        end
+      end
+    end
+
+    def find_latest_gem(gem_name)
+      the_gem = Dir.glob("#{Gem.dir}/gems/#{gem_name}-*")
+
+      the_gem.empty? ? nil : the_gem.first
+    end
+
+    # Add all gems in the global gemset to the $LOAD_PATH so they can be used
+    # even in places like 'rails console'.
+    #
+    # TODO: Use #find_latest_gem for each of #libraries.
+    def do_bundler_extending
+      if defined?(::Bundler)
+        all_global_gem_paths = Dir.glob("#{Gem.dir}/gems/*")
+
+        all_global_gem_paths.each do |p|
+          gem_path = "#{p}/lib"
+          $LOAD_PATH.unshift(gem_path)
+        end
+      else
+        vputs 'Bundler not defined.  Skipping.'
+      end
+    end
+
+    # Undo the stuff that was done in #do_bundler_extending.
+    #
+    # TODO: Use #find_latest_gem for each of #libraries.
+    def undo_bundler_extending
+      if defined?(::Bundler)
+        all_global_gem_paths = Dir.glob("#{Gem.dir}/gems/*")
+
+        all_global_gem_paths.each do |p|
+          gem_path = "#{p}/lib"
+          $LOAD_PATH.delete(gem_path)
+        end
+      else
+        vputs 'Bundler not defined.  Skipping.'
+      end
+    end
+  end
+end

data/lib/hairballs/plugin.rb

@@ -0,0 +1,75 @@
+require_relative 'library_helpers'
+
+class Hairballs
+  # Plugins provide means for adding functionality to your IRB sessions.  They
+  # can be as simple as requiring other gems, or as complex as you want them to
+  # be.
+  #
+  # One benefit of making a simple plugin for requiring other deps is
+  # Hairballs::LibraryHelpers#require_libraries method.  When used in conjunction with
+  # Hairballs::LibraryHelpers#libraries, you don't have to worry about installing the
+  # gems before using IRB.  This is particularly helpful when using a Ruby
+  # manager (RVM, rbenv, etc) and you install a new Ruby; if you don't think
+  # ahead to install your IRB deps, your IRB session won't behave like you
+  # want; well, not until you `exit` and fix the problem.  This simple pattern
+  # helps alleviate that small headache.
+  #
+  # Next, Hairballs Plugins are lazily loaded; `require`ing their source files
+  # doesn't mean the methods and such that you add there will do anything; it's
+  # not until you `Hairballs.load_plugin(:blargh)` that the code that defines
+  # your plugin will get executed.
+  class Plugin
+    include LibraryHelpers
+
+    # @return [Symbol]
+    attr_reader :name
+
+    # @param name [Symbol]
+    # @param attributes [Hash] These become attributes (with reader and writer
+    #   methods) of the Plugin.  It's really just a mechanism for defining
+    #   available attributes and their default values.
+    def initialize(name, **attributes)
+      @name = name
+      @irb_configuration = nil
+
+      attributes.each do |k, v|
+        define_singleton_method(k) do
+          instance_variable_get("@#{k}".to_sym)
+        end
+
+        define_singleton_method("#{k}=") do |new_value|
+          instance_variable_set("@#{k}".to_sym, new_value)
+        end
+
+        instance_variable_set("@#{k}".to_sym, v)
+      end
+    end
+
+    # Everything in the +block+ given here will be the last code to get
+    # evaluated when #load! is called.  This is where you define code that makes
+    # up your plugin.
+    def on_load(&block)
+      @on_load = block
+    end
+
+    # Loads the plugin using the +attributes+ values.  The keys in +attributes+
+    # must match attributes that were given when the Plugin was defined.
+    # Attribute values given here will override the defaults that were given
+    # when the Plugin was defined.
+    def load!(**attributes)
+      attributes.each do |k, v|
+        send("#{k}=".to_sym, v)
+      end
+
+      require_libraries
+
+      if @on_load
+        if @on_load.kind_of?(Proc)
+          @on_load.call
+        else
+          fail PluginLoadFailure, self.name
+        end
+      end
+    end
+  end
+end

data/lib/hairballs/plugins/awesome_print.rb

@@ -0,0 +1,9 @@
+require_relative '../../hairballs'
+
+Hairballs.add_plugin(:awesome_print) do |plugin|
+  plugin.libraries %w(awesome_print)
+
+  plugin.on_load do
+    AwesomePrint.irb!
+  end
+end

data/lib/hairballs/plugins/colorize_json.rb

@@ -0,0 +1,30 @@
+require_relative '../../hairballs'
+
+# When any value is returned by evaluating some Ruby, this will check if it is
+# JSON (by parsing it).  If it's JSON-like, it will get formatted prettily and
+# using the +color+ given when calling +Hairballs.load_plugin(:colorize_json)+.
+#
+# This *must* get used/loaded after the :wirble plugin to work.
+#
+# TODO: fix to work with using/loading before Wirble.
+Hairballs.add_plugin(:colorize_json, color: :blue) do |plugin|
+  plugin.libraries %w(json colorize)
+
+  plugin.on_load do
+    IRB::Irb.class_eval do
+      alias_method :old_output_value, :output_value
+
+      define_method :output_value do
+        is_json = JSON.parse(@context.last_value) rescue nil
+
+        if is_json
+          vputs "[#{plugin.name}] Return value is JSON-like"
+          printf @context.return_format,
+            JSON.pretty_generate(JSON.parse(@context.last_value)).colorize(plugin.color)
+        else
+          old_output_value
+        end
+      end
+    end
+  end
+end

data/lib/hairballs/plugins/interesting_methods.rb

@@ -0,0 +1,22 @@
+require_relative '../../hairballs'
+
+# Returns only the methods not present on basic Objects.
+#
+# @see http://stackoverflow.com/a/873371/172106
+Hairballs.add_plugin(:interesting_methods) do |plugin|
+  plugin.on_load do
+    Object.class_eval do
+      # @return [Array<Symbol>]
+      def interesting_methods
+        case self.class
+        when Class
+          public_methods.sort - Object.public_methods
+        when Module
+          public_methods.sort - Module.public_methods
+        else
+          public_methods.sort - Object.new.public_methods
+        end
+      end
+    end
+  end
+end

data/lib/hairballs/plugins/irb_history.rb

@@ -0,0 +1,37 @@
+require_relative '../../hairballs'
+
+Hairballs.add_plugin(:irb_history, save_history: 1000, eval_history: 20, global_history_file: true) do |plugin|
+  plugin.libraries %w(irb/ext/save-history)
+
+  plugin.on_load do
+    IRB.conf[:SAVE_HISTORY] = plugin.save_history
+    IRB.conf[:EVAL_HISTORY] = plugin.eval_history
+
+    unless plugin.global_history_file
+      IRB.conf[:HISTORY_FILE] = "#{Dir.home}/.irb_history-#{Hairballs.project_name}"
+    end
+
+    Object.class_eval do
+      # All of the ruby lines of code that have been executed.
+      def history
+        0.upto(Readline::HISTORY.size - 1) do |i|
+          printf "%5d %s\n", i, Readline::HISTORY[i]
+        end
+      end
+
+      # Execute one or many lines of Ruby from +history+.
+      #
+      # @param command_numbers [Fixnum,Range]
+      def _!(command_numbers)
+        cmds =
+          if command_numbers.is_a? Range
+            command_numbers.to_a.map { |i| Readline::HISTORY[i] }
+          else
+            [Readline::HISTORY[command_numbers]]
+          end
+
+        cmds.each { |cmd| send(cmd) }
+      end
+    end
+  end
+end

data/lib/hairballs/plugins/object_ri.rb

@@ -0,0 +1,20 @@
+require_relative '../../hairballs'
+
+# Directly lifted from rbates/dotfiles!  Adds +#ri+ to all Objects, letting you
+# get ri docs from within your IRB session.
+Hairballs.add_plugin(:object_ri) do |plugin|
+  plugin.libraries %w(rdoc)
+
+  plugin.on_load do
+    Object.class_eval do
+      def ri(method=nil)
+        unless method && method =~ /^[A-Z]/ # if class isn't specified
+          klass = self.kind_of?(Class) ? name : self.class.name
+          method = [klass, method].compact.join('#')
+        end
+
+        system 'ri', method.to_s
+      end
+    end
+  end
+end

data/lib/hairballs/plugins/quick_benchmark.rb

@@ -0,0 +1,18 @@
+require_relative '../../hairballs'
+
+# Quick and dirty benchmarking of whatever block you pass to the method.
+#
+# @see http://stackoverflow.com/a/123834/172106
+Hairballs.add_plugin(:quick_benchmark) do |plugin|
+  plugin.libraries %w(benchmark)
+
+  plugin.on_load do
+    Kernel.module_eval do
+      def quick_benchmark(repetitions=100, &block)
+        Benchmark.bmbm do |b|
+          b.report { repetitions.times(&block) }
+        end
+      end
+    end
+  end
+end