debug-bar 1.0.0

data/.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+Gemfile.lock
+*.swp
+*.swo
+pkg/
+rdoc/

data/.rbenv-version

@@ -0,0 +1 @@
+ruby-1.9.2

data/.rspec

@@ -0,0 +1 @@
+--color --format documentation spec

data/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'gemtools'
+
+group :development do
+  gem 'rake'
+  gem 'ruby-debug19', :require => 'ruby-debug'
+end
+
+group :test do
+  gem 'rspec'
+  gem 'vcr'
+  gem 'webmock'
+end

data/README.rdoc

@@ -0,0 +1,192 @@
+= Overview
+
+DebugBar offers an easy way to show developer/debugging information on a a web
+page in an unobtrustive way.  It features keyboard shortcuts for showing/hiding
+the bar (Ctrl-~), and memory (through cookies) of which information to show.
+
+DebugBar uses a modular architecture utilizing callback lambdas to produce
+the contents of the DebugBar.
+
+DebugBar::Base is the base debug bar, suitable for use in any application, and
+comes without any pre-added callbacks.
+
+DebugBar::Default is a default debug bar suitible for a typical Rails application,
+and includes several default callbacks meaningful in such an environment.
+
+= Installation
+
+To use DebugBar, your application must include jQuery in rendered pages.
+
+Typically, Rails applications create a debug_bar initializer that defines a
+DEBUG_BAR constant which refers to the configured DebugBar instance.  Customization
+and setup are typically done in this file.
+
+= Examples
+
+== Basic Usage
+
+Typically the debug bar is added to your layout template with the following code
+  DebugBar::Default.new.render(binding)
+though it is typically better to pre-instantiate your debug bar instance as a
+constant in an initializer, and then reference it in your layout, like so:
+
+  # In your initializer
+  DEBUG_BAR = DebugBar::Default.new do |debug_bar|
+    # Do additional setup, such as registering custom recipe books and callbacks here.
+  end
+
+  # In your layout view template
+  DEBUG_BAR.render(binding)
+
+Additionally, it is common to include code that controls the optional rendering
+of the debug bar based on environement and/or parameters; for example
+  DEBUG_BAR.render(binding) if Rails.env=='development' || params.include?(:debugger)
+could be used in Rails.
+
+== Custom Callbacks
+
+While there are a basic set of callbacks available, the real power of DebugBar
+is the ability to add custom callbacks.
+
+In the context of a Rails application, custom callbacks are typically added
+to the config/initializer where the debug_bar is instantiated.
+
+=== Basic
+
+Custom callbacks are typically Proc objects that take an evaluation binding
+context as an argument, and produce an array of the form of two to three elements:
+
+[title] The display title for this callback box.
+[body] The raw HTML string to render.
+[opts] A hash of options to pass to the renderer, usually used to control box layout options.  This is optional.
+
+Thus, if one wanted a debug box to display the time, one might do
+  debug_bar.add {|binding| ['Time', Time.now.to_s]}
+
+A more complex example would to output the params hash.  Note that since the output
+is raw HTML, we must replace all instances of '<' with '&lt;'.  (A proper implementation
+would escape all escapable entities.)
+  debug_bar.add do |binding|
+    body = binding.eval('params').inspect.gsub('<','&lt;')
+    ['Params', body]
+  end
+
+Note that we using binding.eval to extract variable names from the binding by
+executing snippets of code.  This raises two points:
+* Any code can be evaluated in the binding in this
+  manor, thus choice of render binding has a major impact on the information
+  available for display.
+* As a convenience, variables can be extracted from the binding with the <code>[]</code> method,
+  thus
+    body = binding[:params].inspect
+  could be substituted for
+    body = binding.eval('params').inspect
+
+
+=== Rails Render
+
+If rendering the DebugBar from within a Rails template (e.g. the application
+layout), you can use Rails render commands in the callback via a binding.eval
+to render any template and output the results to the debug bar.  This is
+convenient way to render any input, though the use of custom recipe books
+should be considered if you do this often.
+
+=== Options
+
+Callbacks may provide the following options:
+
+[:id] The HTML id for the callback for use with custom javascript hooks, and remembered settings.
+[:hidden] Controls default state of disclosure arrow for the callback's content.
+          Note that if an :id is provided, the state can be remembered between requests.
+
+=== UI Tools
+
+Note that debug-bar callbacks can use the 'toggle-switch' and 'toggle-content'
+classes to drive toggleable hide/show behavior inside of the debug-bar.  To
+do so, add the 'toggle-switch' class to the link that causes toggle, and the
+'toggle-content' class to the <i>sibling</i> element that will toggle.
+
+For example:
+
+  <div>
+    <a href="" class="toggle-switch">Details</a>
+    <div class="toggle-content" style="display:none">
+      Lot's of content here.
+    </div>
+  </div>
+
+This would present a "Details" link that would reveal the content div.
+
+== Custom Recipes
+
+While it is convenient to define one-off callbacks directly via add, it is
+often both cleaner and more useful to create re-usable callback recipes in
+RecipeBooks.  Additionally, RecipeBooks provide some convenience methods not
+available in your own initializers.
+
+Essentially, subclasses of RecipeBook::Base are factory classes that contain
+instance methods that generate Proc objects that are used as callbacks.  What
+makes RecipeBook special over any random factory class is the convenience
+methods it gives and the tight integration with DebugBar::Base instances.
+
+=== Setup
+
+One can manually add a RecipeBook by class or instance using the +add_recipe_book+
+method.  For example
+  debug_bar.add_recipe_book(DebugBar::RecipeBook::Default)
+or
+  book = DebugBar::RecipeBook::Default.new
+  debug_bar.add_recipe_book(book)
+
+=== Creating Your Own
+
+To create your own recipe book, simply subclass another recipe book and add
+recipe generation inatance methods that follow a few simple rules:
+1. They must be the recipe name suffixed with `_recipe'.
+2. They must be able to support being called with no elements to support
+   short-hand addition of a recipe.  (This does no preclude supporting optional
+   arguments and manual addition of the generated block.
+
+Recipes in a RecipeBook::Base subclass get access to special functionality, such
+as being able to use templates at class-defined locations.
+
+= Contact
+
+Jeff Reinecke <jreinecke@whitepages.com>
+Keith Stone <kstone@whitepages.com>
+
+= Feature Roadmap
+
+* No future features expected at this time.
+
+= Version History
+
+[1.0.0 - 2012-Jul-13] Initial Release.
+
+= License
+
+  Copyright (c) 2012, WhitePages, Inc.
+  All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are met:
+      * Redistributions of source code must retain the above copyright
+        notice, this list of conditions and the following disclaimer.
+      * Redistributions in binary form must reproduce the above copyright
+        notice, this list of conditions and the following disclaimer in the
+        documentation and/or other materials provided with the distribution.
+      * Neither the name of the company nor the
+        names of its contributors may be used to endorse or promote products
+        derived from this software without specific prior written permission.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+  DISCLAIMED. IN NO EVENT SHALL WHITEPAGES, INC. BE LIABLE FOR ANY
+  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/Rakefile

@@ -0,0 +1,27 @@
+#!/usr/bin/env rake
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../Gemfile", Pathname.new(__FILE__).realpath)
+require 'rubygems'
+require 'bundler/setup'
+require 'gemtools/rake_task'
+
+require 'rake/dsl_definition'
+require "rspec/core/rake_task"
+ 
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.rspec_opts = ['--backtrace']
+end
+
+Bundler::GemHelper.install_tasks
+Gemtools::RakeTask.install_tasks
+
+task :default => :spec
+
+require 'rake/rdoctask'
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.rdoc_files.add "lib/**/*.rb", "README.rdoc"
+end

data/debug-bar.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'debug-bar/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'debug-bar'
+  s.version     = DebugBar::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Jeff Reinecke', 'Keith Stone']
+  s.email       = ['jreinecke@whitepages.com', 'kstone@whitepages.com']
+  s.homepage    = 'https://github.com/whitepages/debug-bar'
+  s.summary     = 'Debug Bar'
+  s.description = 'Base generic debug bar implementation.'
+  s.licenses    = ['BSD']
+
+  s.add_dependency 'erubis'
+  s.add_dependency 'activesupport'
+  s.add_dependency 'awesome_print'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/debug-bar/base.rb

@@ -0,0 +1,208 @@
+require 'active_support/all'
+require 'pathname'
+require 'erubis'
+
+
+require_relative 'ext'
+
+# DebugBar is the module namespace for this gem.  For the DebugBar base class,
+# see DebugBar::Base.
+module DebugBar
+  # = Overview
+  #
+  # DebugBar::Base provides the base methods for all debug bars.
+  #
+  # At it's core, a DebugBar is instantiated with +initialize+, gets callbacks
+  # added with +add_callback+, and then is rendered with +render+.
+  #
+  # Additionally, RecipeBook classes or instance may be added to the DebugBar
+  # via +add_recipe_book+ so that pre-made callbacks may be easily added to the
+  # DebugBar instance via add_callbacks.
+  #
+  # See the README for example usage.
+  #
+  # = Subclassing
+  #
+  # This class is often subclassed to give DebugBars with special behaviors.
+  # If you make a subclass, define <b>private</b> overrides to these methods:
+  # [+default_recipe_books+] Provide a list of recipe books to make available to all instances.
+  # [+default_recipes+] Add a list of recipe callbacks to all instances.
+  # [+template_search_paths+] Override the default formatting template search path.
+  class Base
+
+    # The search path for formatting templates, such as the layout and callback box.
+    # NOTE: This is separate from templates that are used in recipes!
+    TEMPLATE_SEARCH_PATHS = [
+      (Pathname.new(__FILE__).dirname + '../templates')
+    ].map {|path| path.expand_path}
+
+    # Initialize a new debug bar.  This may optionally take
+    # one or more recipe symbols as arguments.
+    def initialize(*recipes)
+      #Initialize registration variables.
+      @callbacks = []
+      @recipe_books = []
+      # Register defaults.
+      default_recipe_books.each {|book| add_recipe_book(book)}
+      default_recipes.each {|recipe| add_recipe(recipe)}
+      # Give a chance for custom configuration, including addition of books.
+      yield self if block_given?
+      # Now we can add user listed recipes.
+      recipes.each {|recipe| add_recipe(recipe)}
+    end
+
+    # Returns a copy of the raw list of callbacks.
+    attr_reader :callbacks
+
+    # Returns a copy of the list of recipe book instances.
+    attr_reader :recipe_books
+
+    # Adds a recipe book class or instance to the recipe book list for
+    # this debug bar.
+    #
+    # Returns self to support functional programming styles.
+    def add_recipe_book(book)
+      @recipe_books << (book.kind_of?(Class) ? book.new : book)
+      return self
+    end
+    alias_method :add_book, :add_recipe_book
+
+    # Returns the list of recipes recognized by this debug bar.
+    def recipes
+      return @recipe_books.inject([]) {|list,book| list | book.recipes}
+    end
+
+    # Returns the most recently added occurance of the given recipe.
+    def recipe_callback(recipe, *args, &block)
+      book = @recipe_books.reverse.find {|book| book.include?(recipe)}
+      raise ArgumentError, "Could not find recipe #{recipe.inspect}", caller if book.nil?
+      return book.recipe(recipe, *args, &block)
+    end
+
+    # Adds a callback.
+    #
+    # Takes either a recipe (by symbol) or a block.
+    #
+    # The block takes a single argument, the binding of the render context,
+    # and should return either a string, or an array of [title, content, opts].
+    #
+    # Advanced users can call a recipe by name, and provide additional arguments
+    # to configure the recipe further.  These arguments are defined by the
+    # recipe factory method, but usually are via an options hash and/or a block.
+    #
+    # Returns self to support functional programming styles.
+    def add_callback(recipe=nil, *args, &callback)
+      callback_proc = recipe.nil? ? callback : recipe_callback(recipe, *args, &callback)
+      raise ArgumentError, "Expected callback to respond to `call': #{callback_proc.inspect}", caller unless callback_proc.respond_to?(:call)
+      @callbacks << callback_proc
+      return self
+    end
+    alias_method :add_recipe, :add_callback
+    alias_method :add, :add_callback
+
+    # Renders the debug bar with the given binding.
+    def render(eval_binding)
+      # Decorate the binding here (NOT in private methods where we don't want automatic behavior)!
+      eval_binding.extend(DebugBar::Ext::Binding)
+      return render_layout(eval_binding)
+    end
+
+    private
+
+    # An initialization callback for adding default recipe books to instances;
+    # this should return an array of recipe book classes or instances.
+    #
+    # On the base class, this returns an empty array; subclasses should override this.
+    def default_recipe_books
+      return []
+    end
+
+    # An initialization callback for adding default recipes to the callbacks
+    # array.
+    #
+    # On the base class, this returns an empty array; subclasses should override this.
+    def default_recipes
+      return []
+    end
+
+    # Returns the template search paths for this instance.
+    #
+    # Paths should be Pathname instances
+    #
+    # Subclasses may override this to change the search path for the formatting
+    # templates such as the layout and callback_box templates.
+    def template_search_paths
+      return TEMPLATE_SEARCH_PATHS
+    end
+
+    # Looks for the given remplate name within the template search paths, and
+    # returns a string containing its contents.  The name may be a symbol or string.
+    #
+    # Template names automatically have '.html.erb' appended to them, so call
+    #   read_template(:foo)
+    # instead of
+    #   read_template('foo.html.erb')
+    def read_template(template)
+      template_name = "#{template}.html.erb"
+      template_path = template_search_paths.map {|base_path| (base_path + template_name).expand_path}.find {|p| p.exist? && p.file?}
+      raise ArgumentError, "Unknown template #{template_name.inspect}.  Not in #{template_search_paths.inspect}", caller if template_path.nil?
+      return template_path.read
+    end
+
+    # Renders the callbacks and then renders the layout--all in the given
+    # binding--inserting the callbacks into the layout; returns an html_safe string.
+    def render_layout(eval_binding)
+      content = render_callbacks(@callbacks, eval_binding)
+      return Erubis::Eruby.new(read_template(:layout)).result(:content => content).html_safe
+    end
+
+    # Returns the contactinated set of rendered callbacks usnig the given binding.
+    def render_callbacks(callbacks, eval_binding)
+      return @callbacks.map {|callback| render_callback(callback, eval_binding)}.join("\n")
+    end
+
+    # Renders the given callback in the given binding.
+    def render_callback(callback, eval_binding)
+      # Get the result of the callback
+      obj = begin
+              callback.respond_to?(:call) ? callback.call(eval_binding) : callback
+            rescue Exception => error
+              render_error_callback(error)
+            end
+
+      # Extract the title, content, and opts from the result
+      title, content, opts = case obj
+      when Array
+        obj
+      else
+        ['Debug', obj.to_s, {}]
+      end
+      opts ||= {}
+
+      # reverse merge the opts
+      default_hidden = opts[:id].nil? ? false : !cookie_include?(opts[:id], eval_binding)
+      opts = {:hidden => default_hidden}.merge(opts||{})
+
+      # Render the callback in a box
+      return Erubis::Eruby.new( read_template(:callback_box) ).result(:title => title, :content => content, :opts => opts).html_safe
+    end
+
+    def render_error_callback(error, opts={})
+      return [
+        opts.fetch(:title, '**ERROR'),
+        Erubis::Eruby.new(read_template(:error)).result(:error => error).html_safe,
+        {}
+      ]
+    end
+
+    # A helper method that--if the eval_binding defines a cookies hash, and
+    # that hash has a :debug_bar key, returns true if it contains the given
+    # id; otherwise it returns false.
+    #
+    # TODO: This code should be refactored to support more use cases as they appear.
+    def cookie_include?(id, eval_binding)
+      debug_bar = eval_binding.eval("defined?(cookies) && cookies[:debug_bar]")
+      debug_bar.nil? ? false : debug_bar.split(',').include?(id)
+    end
+  end
+end

data/lib/debug-bar/default.rb

@@ -0,0 +1,26 @@
+module DebugBar
+  # A default DebugBar implementation suitable for use in a Ruby On Rails
+  # application layout template.
+  #
+  # This, of course, may be customized, typically by creating an initializer
+  # file at config/initializers/debug_bar.rb, and populating like so:
+  #
+  #   DEBUG_BAR = DebugBar::Default.new do |bar|
+  #     bar.add {|b| ['Time', Time.now]}
+  #   end
+  class Default < Base
+
+    private
+
+    # Override superclass method to provide the necessary cookbook.
+    def default_recipe_books
+      return [RecipeBook::Default]
+    end
+
+    # The recipes added to this debug bar by default.
+    def default_recipes
+      return [:params, :session]
+    end
+
+  end
+end

data/lib/debug-bar/ext/binding.rb

@@ -0,0 +1,17 @@
+module DebugBar
+  module Ext
+    # Binding extensions that are decorated onto bindings passed into callbacks.
+    module Binding
+      # A regex for matching only valid local, instance, class, and global variables, as well as constatns.
+      VARIABLE_PATTERN = /^(@{1,2}|\$)?([_a-zA-Z]\w*)$/
+
+      # Returns the value of the given variable symbol within the binding.
+      # Supports local, instance, class, or global variables, as well as constants.
+      def [](var)
+        raise NameError, "#{var.inspect} is not a valid variable name" unless var.to_s =~ VARIABLE_PATTERN
+        return self.eval(var.to_s)
+      end
+
+    end
+  end
+end

data/lib/debug-bar/ext/object.rb

@@ -0,0 +1,20 @@
+require 'awesome_print'
+
+module DebugBar
+  module Ext
+    module Object
+
+      def awesome_print(opts={})
+        return self.ai(opts)
+      end
+
+      def awesome_print_html
+        return self.awesome_print(:html => true, :indent => -3)
+      end
+
+    end
+  end
+end
+
+
+Object.send(:include, DebugBar::Ext::Object)

data/lib/debug-bar/ext/string.rb

@@ -0,0 +1,18 @@
+require 'cgi'
+
+module DebugBar
+  module Ext
+    module String
+
+      def html_escape
+        return CGI.escapeHTML(self)
+      end
+
+    end
+  end
+end
+
+
+unless( String.methods.include?(:html_escape) )
+  String.send(:include, DebugBar::Ext::String)
+end

data/lib/debug-bar/ext.rb

@@ -0,0 +1,3 @@
+require_relative 'ext/binding'
+require_relative 'ext/object'
+require_relative 'ext/string'

data/lib/debug-bar/recipe_book/base.rb

@@ -0,0 +1,104 @@
+require 'pathname'
+
+module DebugBar
+  # RecipeBook is the module namespace for the RecipeBooks provided in this
+  # gem.  For the base RecipeBook, see RecipeBook::Base.
+  module RecipeBook
+    # The base class for all recipe subclasses.  Provides common convenience
+    # methods for recipe use.  Essentially, these are factory methods that
+    # lazy generate common configurable callbacks on demand.
+    #
+    # Subclasses need only to define factory instance methods that meet the
+    # following rules:
+    # 1. The method name must be the recipe name suffixed with `_recipe'.  So
+    #    the recipe
+    #      :foo
+    #    would have method name
+    #      foo_recipe
+    # 2. Recipe factory methods <b>MUST</b> return a valid callback when no arguments
+    #    are given, that is
+    #      book.foo_recipe()
+    #    must work.
+    # 3. The result of a recipe factory method must be a Proc object that
+    #    conforms to the requirements of the Procs registered with +add_callback+
+    #    on the DebugBar::Base class.
+    # 4. Recipe methods <i>may</i> take an additional argument, which is an
+    #    options hash for special configuration when using +add_callback+ on
+    #    DebugBar::Base instances.  For example, one can then us
+    #
+    # For example, the following recipe renders the params hash from the given
+    # binding:
+    #
+    #   def params_recipe(opts={})
+    #     Proc.new do |b|
+    #       body = (opts[:formatter] == :pretty_inspect) ? b[:params].pretty_inspect : b[:params].inspect
+    #       ['Params', body.gsub('<','&lt;'), :hidden => (body.length>160)]
+    #     end
+    #   end
+    #
+    # It could then be added to the DebugBar like so:
+    #
+    #   debug_bar.add(:params)
+    #   debug_bar.add(:params, :formatter => :pretty_inspect)
+    class Base
+
+      # Returns a list of recipes known to this class.
+      def recipes
+        return self.methods.select {|m| m.to_s =~ /_recipe$/}.map {|m| m.to_s.gsub(/_recipe$/,'').to_sym}
+      end
+
+      # Returns true if the given recipe is known.
+      def include?(recipe)
+        return self.respond_to?("#{recipe}_recipe")
+      end
+      alias_method :has_recipe?, :include?
+
+      # Generates the given recipe.
+      # All recipes are expected to accept no arguments, but may optionally
+      # take more.  Optional arguments given to this method are passed through
+      # to the recipe method.
+      def recipe(recipe, *args, &block)
+        return self.send("#{recipe}_recipe", *args, &block)
+      end
+      alias_method :[], :recipe
+
+      # Retrieves the template search paths for this recipe instance as
+      # fully expanded Pathname instances.
+      #
+      # While subclasses <i>may</i> override this method, it is preferrable
+      # for them to use the setter (+template_search_paths=+) during instance
+      # initialization, as the setter sanitizes the input.
+      def template_search_paths
+        return @template_search_paths ||= []
+      end
+
+      # Sets the template search paths for this recipe instance, converting
+      # to pathname objects as necessary.
+      def template_search_paths=(paths)
+        @template_search_paths = paths.map {|path| Pathname.new(path.to_s).expand_path }
+      end
+
+      private
+
+      # Renders the first matching template found in the search paths.  Passed
+      # symbols/names are automatically suffixed with 'html.erb'.  The template
+      # name may be a symbol or string.
+      #
+      # Optionally, one can pass in :locals, which is a hash of local variables
+      # to render in the template.
+      def render_template(template, opts={})
+        return Erubis::Eruby.new( read_template(template) ).result( opts.fetch(:locals, {}) ).html_safe
+      end
+
+      # Reads the given template and returns the string of its contents.
+      # The template name may be either a symbol or string.
+      def read_template(template)
+        template_name = "#{template}.html.erb"
+        template_path = template_search_paths.map {|base_path| (base_path + template_name).expand_path}.find {|p| p.exist? && p.file?}
+        raise ArgumentError, "Unknown template #{template_name.inspect}.  Not in #{template_search_paths.inspect}", caller if template_path.nil?
+        return template_path.read
+      end
+
+    end
+  end
+end