BMorearty-looksee 0.1.1

data/lib/looksee.rb

@@ -0,0 +1,403 @@
+require "rbconfig"
+require File.dirname(__FILE__) + "/../ext/looksee/looksee.#{Config::CONFIG['DLEXT']}"
+require "looksee/version"
+
+#
+# Looksee lets you inspect the method lookup path of an object.  There
+# are two ways to use it:
+#
+# 1. Keep all methods contained in the Looksee namespace:
+#
+#     require 'looksee'
+#
+# 2. Let it all hang out:
+#
+#     require 'looksee/shortcuts'
+#
+# The latter adds the following shortcuts to the built-in classes:
+#
+#   Object#lookup_path
+#   Object#dump_lookup_path
+#   Object#lp
+#   Object#lpi
+#   Object#lc
+#
+# See their docs.
+#
+# == Usage
+#
+# In irb:
+#
+#     require 'looksee/shortcuts'
+#     lp some_object
+#
+# +lp+ returns a LookupPath object, which has +inspect+ defined to
+# print things out pretty.  By default, it shows public, protected,
+# undefined, and overridden methods.  They're all colored, which makes
+# showing overridden methods not such a strange idea.
+#
+# Some examples of the other shortcuts:
+#
+#     lpi Array
+#     some_object.lookup_path
+#     foo.bar.baz.dump_lookup_path.and.more
+#
+# If you're being namespace-clean, you'll need to do:
+#
+#     require 'looksee'
+#     Looksee.lookup_path(thing)  # like "lp thing"
+#
+# If you want to remember what each color means:
+#
+#     lc  # shortcut mapping for Looksee.colors
+#
+# == Configuration
+#
+# Set these:
+#
+#     Looksee.default_lookup_path_options
+#     Looksee.default_width
+#     Looksee.styles
+#
+# See their docs.
+#
+module Looksee
+  class << self
+    #
+    # Return a collection of methods that +object+ responds to,
+    # according to the options given.  The following options are
+    # recognized:
+    #
+    # * +:public+ - include public methods
+    # * +:protected+ - include protected methods
+    # * +:private+ - include private methods
+    # * +:undefined+ - include undefined methods (see Module#undef_method)
+    # * +:overridden+ - include methods overridden by subclasses
+    #
+    # The default (if options is nil or omitted) is given by
+    # #default_lookup_path_options.
+    #
+    def lookup_path(object, *options)
+      normalized_options = Looksee.default_lookup_path_options.dup
+      hash_options = options.last.is_a?(Hash) ? options.pop : {}
+      options.each do |option|
+        normalized_options[option] = true
+      end
+      normalized_options.update(hash_options)
+      LookupPath.for(object, normalized_options)
+    end
+
+    #
+    # The default options passed to lookup_path.
+    #
+    # Default: <tt>{:public => true, :protected => true, :undefined =>
+    # true, :overridden => true}</tt>
+    #
+    attr_accessor :default_lookup_path_options
+
+    #
+    # The width to use for displaying output, when not available in
+    # the COLUMNS environment variable.
+    #
+    # Default: 80
+    #
+    attr_accessor :default_width
+
+    #
+    # The default styles to use for the +inspect+ strings.
+    #
+    # This is a hash with keys:
+    #
+    # * :module
+    # * :public
+    # * :protected
+    # * :private
+    # * :undefined
+    # * :overridden
+    #
+    # The values are format strings.  They should all contain a single
+    # "%s", which is where the name is inserted.
+    #
+    # Default:
+    #
+    #       {
+    #         :module     => "\e[1;37m%s\e[0m", # white
+    #         :public     => "\e[1;32m%s\e[0m", # green
+    #         :protected  => "\e[1;33m%s\e[0m", # yellow
+    #         :private    => "\e[1;31m%s\e[0m", # red
+    #         :undefined  => "\e[1;34m%s\e[0m", # blue
+    #         :overridden => "\e[1;30m%s\e[0m", # black
+    #       }
+    #
+    attr_accessor :styles
+
+    #
+    # Return the chain of classes and modules which comprise the
+    # object's method lookup path.
+    #
+    def lookup_modules(object)
+      modules = []
+      klass = Looksee.internal_class(object)
+      while klass
+        modules << Looksee.internal_class_to_module(klass)
+        klass = Looksee.internal_superclass(klass)
+      end
+      modules
+    end
+
+    #
+    # Return the color mappings.
+    #
+    def colors
+      Colors.new
+    end
+  end
+
+  self.default_lookup_path_options = {:public => true, :protected => true, :undefined => true, :overridden => true}
+  self.default_width = 80
+  self.styles = {
+    :module     => "\e[1;37m%s\e[0m", # white
+    :public     => "\e[1;32m%s\e[0m", # green
+    :protected  => "\e[1;33m%s\e[0m", # yellow
+    :private    => "\e[1;31m%s\e[0m", # red
+    :undefined  => "\e[1;34m%s\e[0m", # blue
+    :overridden => "\e[1;30m%s\e[0m", # black
+  }
+
+  class LookupPath
+    attr_reader :entries
+
+    def initialize(entries)
+      @entries = entries
+    end
+
+    #
+    # Create a LookupPath for the given object.
+    #
+    # Options may be given to restrict which visibilities are
+    # included.
+    #
+    #   :public
+    #   :protected
+    #   :private
+    #   :undefined
+    #   :overridden
+    #
+    def self.for(object, options={})
+      entries = entries_for(object, options)
+      new(entries)
+    end
+
+    #
+    # Return a new LookupPath which only contains names matching the
+    # given pattern.
+    #
+    def grep(pattern)
+      entries = self.entries.map do |entry|
+        entry.grep(pattern)
+      end
+      self.class.new(entries)
+    end
+
+    def inspect(options={})
+      options = normalize_inspect_options(options)
+      entries.map{|e| e.inspect(options)}.join("\n")
+    end
+
+    private  # -------------------------------------------------------
+
+    def self.entries_for(object, options)
+      seen = {}
+      Looksee.lookup_modules(object).map do |mod|
+        entry = Entry.for(mod, seen, options)
+        entry.methods.each{|m| seen[m] = true}
+        entry
+      end
+    end
+
+    def normalize_inspect_options(options)
+      options[:width] ||= ENV['COLUMNS'].to_i.nonzero? || Looksee.default_width
+      options
+    end
+
+    #
+    # An entry in the LookupPath.
+    #
+    # Contains a module and its methods, along with visibility
+    # information (public, private, etc.).
+    #
+    class Entry
+      def initialize(mod, methods=[], visibilities={})
+        @module = mod
+        @methods = methods
+        @visibilities = visibilities
+      end
+
+      def self.for(mod, seen, options)
+        entry = new(mod)
+        entry.initialize_for(seen, options)
+        entry
+      end
+
+      attr_reader :module, :methods
+
+      def initialize_for(seen, options)
+        add_methods(Looksee.internal_public_instance_methods(@module).map{|sym| sym.to_s}   , :public   , seen) if options[:public   ]
+        add_methods(Looksee.internal_protected_instance_methods(@module).map{|sym| sym.to_s}, :protected, seen) if options[:protected]
+        add_methods(Looksee.internal_private_instance_methods(@module).map{|sym| sym.to_s}  , :private  , seen) if options[:private  ]
+        add_methods(Looksee.internal_undefined_instance_methods(@module).map{|sym| sym.to_s}, :undefined, seen) if options[:undefined]
+        @methods.sort!
+      end
+
+      def grep(pattern)
+        methods = []
+        visibilities = {}
+        @methods.each do |name|
+          if name[pattern]
+            methods << name
+            visibilities[name] = @visibilities[name]
+          end
+        end
+        self.class.new(@module, methods, visibilities)
+      end
+
+      #
+      # Return the name of the class or module.
+      #
+      # Singleton classes are displayed in brackets.  Singleton class
+      # of singleton classes are displayed in double brackets.  But
+      # you'd never need that, would you?
+      #
+      def module_name
+        name = @module.to_s  # #name doesn't do singleton classes right
+        nil while name.sub!(/#<Class:(.*)>/, '[\\1]')
+        name
+      end
+
+      #
+      # Yield each method along with its visibility (:public,
+      # :private, :protected, :undefined, or :overridden).
+      #
+      def each
+        @methods.each do |name|
+          yield name, @visibilities[name]
+        end
+      end
+
+      include Enumerable
+
+      #
+      # Return a nice, pretty string for inspection.
+      #
+      # Contains the module name, plus the method names laid out in
+      # columns.  Pass a :width option to control the output width.
+      #
+      def inspect(options={})
+        string = styled_module_name << "\n" << Columnizer.columnize(styled_methods, options[:width])
+        string.chomp
+      end
+
+      private  # -----------------------------------------------------
+
+      def add_methods(methods, visibility, seen)
+        methods.each do |method|
+          @methods << method
+          @visibilities[method] = seen[method] ? :overridden : visibility
+        end
+      end
+
+      def styled_module_name
+        Looksee.styles[:module] % module_name
+      end
+
+      def styled_methods
+        map do |name, visibility|
+          Looksee.styles[visibility] % name
+        end
+      end
+    end
+  end
+
+  module Columnizer
+    class << self
+      #
+      # Arrange the given strings in columns, restricted to the given
+      # width.  Smart enough to ignore content in terminal control
+      # sequences.
+      #
+      def columnize(strings, width)
+        return '' if strings.empty?
+
+        num_columns = 1
+        layout = [strings]
+        loop do
+          break if layout.first.length <= 1
+          next_layout = layout_in_columns(strings, num_columns + 1)
+          break if layout_width(next_layout) > width
+          layout = next_layout
+          num_columns += 1
+        end
+
+        pad_strings(layout)
+        rectangularize_layout(layout)
+        layout.transpose.map do |row|
+          '  ' + row.compact.join('  ')
+        end.join("\n") << "\n"
+      end
+
+      private  # -----------------------------------------------------
+
+      def layout_in_columns(strings, num_columns)
+        strings_per_column = (strings.length / num_columns.to_f).ceil
+        (0...num_columns).map{|i| strings[i*strings_per_column...(i+1)*strings_per_column] || []}
+      end
+
+      def layout_width(layout)
+        widths = layout_column_widths(layout)
+        widths.inject(0){|sum, w| sum + w} + 2*layout.length
+      end
+
+      def layout_column_widths(layout)
+        layout.map do |column|
+          column.map{|string| display_width(string)}.max || 0
+        end
+      end
+
+      def display_width(string)
+        # remove terminal control sequences
+        string.gsub(/\e\[.*?m/, '').length
+      end
+
+      def pad_strings(layout)
+        widths = layout_column_widths(layout)
+        layout.each_with_index do |column, i|
+          column_width = widths[i]
+          column.each do |string|
+            padding = column_width - display_width(string)
+            string << ' '*padding
+          end
+        end
+      end
+
+      def rectangularize_layout(layout)
+        return if layout.length == 1
+        height = layout[0].length
+        layout[1..-1].each do |column|
+          column.length == height or
+            column[height - 1] = nil
+        end
+      end
+    end
+  end
+
+  class Colors
+    #
+    # Show the meaning of each color.
+    #
+    def inspect
+      "Looksee colors:\n " + Looksee.styles.map {|style,value| value % "#{style.to_s}"}.join(" ")
+    end
+  end
+end
+
+require 'looksee/wirble_compatibility'

data/looksee.gemspec

@@ -0,0 +1,44 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{looksee}
+  s.version = "0.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["George Ogata"]
+  s.date = %q{2009-08-20}
+  s.description = %q{Looksee lets you examine the method lookup path of objects in ways not
+possible in plain ruby.}
+  s.email = ["george.ogata@gmail.com"]
+  s.extensions = ["ext/looksee/extconf.rb"]
+  s.extra_rdoc_files = ["History.txt", "Manifest.txt"]
+  s.files = [".autotest", "History.txt", "Manifest.txt", "README.rdoc", "Rakefile", "ext/looksee/extconf.rb", "ext/looksee/looksee.c", "ext/looksee/node-1.9.h", "lib/looksee.rb", "lib/looksee/shortcuts.rb", "lib/looksee/version.rb", "lib/looksee/wirble_compatibility.rb", "looksee.gemspec", "script/console", "script/destroy", "script/generate", "spec/looksee_spec.rb", "spec/spec_helper.rb", "spec/wirble_compatibility_spec.rb", "tasks/extconf.rake", "tasks/extconf/looksee.rake"]
+  s.homepage = %q{http://github.com/oggy/looksee}
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.require_paths = ["lib", "ext/looksee"]
+  s.rubyforge_project = %q{looksee}
+  s.rubygems_version = %q{1.3.4}
+  s.summary = %q{Looksee lets you examine the method lookup path of objects in ways not possible in plain ruby.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<newgem>, [">= 1.5.2"])
+      s.add_development_dependency(%q<rspec>, [">= 1.2.7"])
+      s.add_development_dependency(%q<mocha>, [">= 0.9.5"])
+      s.add_development_dependency(%q<hoe>, [">= 2.3.2"])
+    else
+      s.add_dependency(%q<newgem>, [">= 1.5.2"])
+      s.add_dependency(%q<rspec>, [">= 1.2.7"])
+      s.add_dependency(%q<mocha>, [">= 0.9.5"])
+      s.add_dependency(%q<hoe>, [">= 2.3.2"])
+    end
+  else
+    s.add_dependency(%q<newgem>, [">= 1.5.2"])
+    s.add_dependency(%q<rspec>, [">= 1.2.7"])
+    s.add_dependency(%q<mocha>, [">= 0.9.5"])
+    s.add_dependency(%q<hoe>, [">= 2.3.2"])
+  end
+end

data/script/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# File: script/console
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs =  " -r irb/completion"
+# Perhaps use a console_lib to store any extra methods I may want available in the cosole
+# libs << " -r #{File.dirname(__FILE__) + '/../lib/console_lib/console_logger.rb'}"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/looksee.rb'}"
+puts "Loading looksee gem"
+exec "#{irb} #{libs} --simple-prompt"

data/script/destroy

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/destroy'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Destroy.new.run(ARGV)

data/script/generate

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/generate'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Generate.new.run(ARGV)