looksee 0.0.1

data/.autotest

@@ -0,0 +1,9 @@
+Autotest.add_hook :initialize do |at|
+  at.add_mapping(/ext\/.*\/(.*)\.[ch]/) do |_, m|
+        ["test/test_#{m[1]}_extn.rb"]
+      end
+end
+
+Autotest.add_hook :run_command do |at|
+  system "rake compile"
+end

data/History.txt

@@ -0,0 +1,3 @@
+== 0.0.1 2009-07-05
+
+* Hi.

data/Manifest.txt

@@ -0,0 +1,18 @@
+.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
+script/console
+script/destroy
+script/generate
+spec/looksee_spec.rb
+spec/spec_helper.rb
+tasks/extconf.rake
+tasks/extconf/looksee.rake

data/README.rdoc

@@ -0,0 +1,118 @@
+= Looksee
+
+* http://github.com/oggy/looksee
+
+== DESCRIPTION
+
+Looksee lets you examine the method lookup path of objects in ways not
+possible in plain ruby.
+
+== SYNOPSIS
+
+Pop this in your .irbrc :
+
+    require 'looksee/shortcuts'
+
+This defines a method +lp+ ("lookup path") which lets you do:
+
+    irb(main):001:0> lp []
+    => Array
+      &            concat      frozen?      push          taguri
+      *            count       hash         rassoc        taguri=
+      +            cycle       include?     reject        take
+      -            delete      index        reject!       take_while
+      <<           delete_at   indexes      replace       to_a
+      <=>          delete_if   indices      reverse       to_ary
+      ==           drop        insert       reverse!      to_s
+      []           drop_while  inspect      reverse_each  to_yaml
+      []=          each        join         rindex        transpose
+      assoc        each_index  last         select        uniq
+      at           empty?      length       shift         uniq!
+      choice       eql?        map          shuffle       unshift
+      clear        fetch       map!         shuffle!      values_at
+      collect      fill        nitems       size          yaml_initialize
+      collect!     find_index  pack         slice         zip
+      combination  first       permutation  slice!        |
+      compact      flatten     pop          sort
+      compact!     flatten!    product      sort!
+    Enumerable
+      all?        each_slice       first     min        reverse_each
+      any?        each_with_index  grep      min_by     select
+      collect     entries          group_by  minmax     sort
+      count       enum_cons        include?  minmax_by  sort_by
+      cycle       enum_slice       inject    none?      take
+      detect      enum_with_index  map       one?       take_while
+      drop        find             max       partition  to_a
+      drop_while  find_all         max_by    reduce     zip
+      each_cons   find_index       member?   reject
+    Object
+      taguri  taguri=  to_yaml  to_yaml_properties  to_yaml_style
+    Kernel
+      ==        hash                        object_id
+      ===       id                          private_methods
+      =~        inspect                     protected_methods
+      __id__    instance_eval               public_methods
+      __send__  instance_exec               respond_to?
+      class     instance_of?                send
+      clone     instance_variable_defined?  singleton_methods
+      display   instance_variable_get       taint
+      dup       instance_variable_set       tainted?
+      enum_for  instance_variables          tap
+      eql?      is_a?                       to_a
+      equal?    kind_of?                    to_enum
+      extend    method                      to_s
+      freeze    methods                     type
+      frozen?   nil?                        untaint
+
+It'll also color the methods according to whether they're public,
+protected, private, or overridden.  So pretty.  You gotta try it.
+
+By default, it shows public and protected methods.  Add private ones
+like so:
+
+    lp [], :private => true
+    lp [], :private          # shortcut
+
+Or if you don't want protected:
+
+    lp [], :protected => false
+
+There are variations too.  And you can configure things.  And you can
+use it as a library without polluting the built-in classes.  See:
+
+    $ ri Looksee
+
+Enjoy!
+
+== INSTALL
+
+  gem install looksee
+
+== FEATURES/PROBLEMS
+
+* Currently only does MRI 1.8, 1.9.
+
+== LICENSE
+
+(The MIT License)
+
+Copyright (c) 2009 George Ogata
+
+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/Rakefile

@@ -0,0 +1,38 @@
+require 'rubygems'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+
+require './lib/looksee/version'
+
+Hoe.plugin :newgem
+Hoe.plugin :cucumberfeatures
+
+$hoe = Hoe.spec 'looksee' do
+  self.developer 'George Ogata', 'george.ogata@gmail.com'
+  self.rubyforge_name       = self.name # TODO this is default value
+  self.description_sections = %w'description synopsis'
+  # self.extra_deps         = [['activesupport','>= 2.0.2']]
+  self.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"],
+    ['rspec', '>= 1.2.7'],
+    ['mocha', '>= 0.9.5'],
+  ]
+end
+
+# Configure the clean and clobber tasks.
+require 'rake/clean'
+require 'rbconfig'
+CLEAN.include('**/*.o')
+CLOBBER.include("ext/looksee/looksee.#{Config::CONFIG['DLEXT']}")
+
+require 'newgem/tasks' # loads /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+desc "Rebuild the gem from scratch."
+task :regem => [:clobber, :gem]
+
+# Force build before running specs.
+Rake::Task['spec'].prerequisites << 'extconf:compile'
+
+task :default => :spec

data/ext/looksee/extconf.rb

@@ -0,0 +1,6 @@
+require 'mkmf'
+
+$CPPFLAGS << " -DRUBY_VERSION=#{RUBY_VERSION.tr('.', '')}"
+dir_config("looksee")
+
+create_makefile("looksee")

data/ext/looksee/looksee.c

@@ -0,0 +1,126 @@
+#include "ruby.h"
+
+#if RUBY_VERSION >= 190
+#  include "node-1.9.h"
+#  include "ruby/st.h"
+#else
+#  include "node.h"
+#  include "st.h"
+#endif
+
+#if RUBY_VERSION < 187
+#  define RCLASS_IV_TBL(c) (RCLASS(c)->iv_tbl)
+#  define RCLASS_M_TBL(c) (RCLASS(c)->m_tbl)
+#  define RCLASS_SUPER(c) (RCLASS(c)->super)
+#endif
+
+/*
+ * Return the internal superclass of this class.
+ *
+ * This is either a Class or "IClass."  IClasses represent Modules
+ * included in the ancestry, and should be treated as opaque objects
+ * in ruby space. Convert the IClass to a Module using #iclass_to_module
+ * before using it in ruby.
+ */
+VALUE Looksee_internal_superclass(VALUE self, VALUE internal_class) {
+  VALUE super = RCLASS_SUPER(internal_class);
+  if (!super)
+    return Qnil;
+  return super;
+}
+
+/*
+ * Return the internal class of the given object.
+ *
+ * This is either the object's singleton class, if it exists, or the
+ * object's birth class.
+ */
+VALUE Looksee_internal_class(VALUE self, VALUE object) {
+  return RBASIC(object)->klass;
+}
+
+/*
+ * Return the class or module that the given internal class
+ * represents.
+ *
+ * If a class is given, this is the class.  If an iclass is given,
+ * this is the module it represents in the lookup chain.
+ */
+VALUE Looksee_internal_class_to_module(VALUE self, VALUE internal_class) {
+  if (!SPECIAL_CONST_P(internal_class)) {
+    switch (BUILTIN_TYPE(internal_class)) {
+    case T_ICLASS:
+      return RBASIC(internal_class)->klass;
+    case T_CLASS:
+      return internal_class;
+    }
+  }
+  rb_raise(rb_eArgError, "not an internal class: %s", RSTRING_PTR(rb_inspect(internal_class)));
+}
+
+typedef struct add_method_if_matching_arg {
+  VALUE names;
+  int visibility;
+} add_method_if_matching_arg_t;
+
+#if RUBY_VERSION < 190
+#  define VISIBILITY(node) ((node)->nd_noex & NOEX_MASK)
+#else
+#  define VISIBILITY(node) ((node)->nd_body->nd_noex & NOEX_MASK)
+#endif
+
+static int add_method_if_matching(ID method_name, NODE *body, add_method_if_matching_arg_t *arg) {
+  /* This entry is for the internal allocator function. */
+  if (method_name == ID_ALLOCATOR)
+    return ST_CONTINUE;
+
+  /* Module#undef_method sets body->nd_body to NULL. */
+  if (!body || !body->nd_body)
+    return ST_CONTINUE;
+
+  if (VISIBILITY(body) == arg->visibility)
+    rb_ary_push(arg->names, ID2SYM(method_name));
+  return ST_CONTINUE;
+}
+
+static VALUE internal_instance_methods(VALUE klass, long visibility) {
+  add_method_if_matching_arg_t arg;
+  arg.names = rb_ary_new();
+  arg.visibility = visibility;
+  st_foreach(RCLASS_M_TBL(klass), add_method_if_matching, (st_data_t)&arg);
+  return arg.names;
+}
+
+/*
+ * Return the list of public instance methods (as Symbols) of the
+ * given internal class.
+ */
+VALUE Looksee_internal_public_instance_methods(VALUE self, VALUE klass) {
+  return internal_instance_methods(klass, NOEX_PUBLIC);
+}
+
+/*
+ * Return the list of protected instance methods (as Symbols) of the
+ * given internal class.
+ */
+VALUE Looksee_internal_protected_instance_methods(VALUE self, VALUE klass) {
+  return internal_instance_methods(klass, NOEX_PROTECTED);
+}
+
+/*
+ * Return the list of private instance methods (as Symbols) of the
+ * given internal class.
+ */
+VALUE Looksee_internal_private_instance_methods(VALUE self, VALUE klass) {
+  return internal_instance_methods(klass, NOEX_PRIVATE);
+}
+
+void Init_looksee(void) {
+  VALUE mLooksee = rb_define_module("Looksee");
+  rb_define_singleton_method(mLooksee, "internal_superclass", Looksee_internal_superclass, 1);
+  rb_define_singleton_method(mLooksee, "internal_class", Looksee_internal_class, 1);
+  rb_define_singleton_method(mLooksee, "internal_class_to_module", Looksee_internal_class_to_module, 1);
+  rb_define_singleton_method(mLooksee, "internal_public_instance_methods", Looksee_internal_public_instance_methods, 1);
+  rb_define_singleton_method(mLooksee, "internal_protected_instance_methods", Looksee_internal_protected_instance_methods, 1);
+  rb_define_singleton_method(mLooksee, "internal_private_instance_methods", Looksee_internal_private_instance_methods, 1);
+}

data/ext/looksee/node-1.9.h

@@ -0,0 +1,35 @@
+/* MRI 1.9 does not install node.h.  This is the part we need. */
+
+typedef struct RNode {
+    unsigned long flags;
+    char *nd_file;
+    union {
+	struct RNode *node;
+	ID id;
+	VALUE value;
+	VALUE (*cfunc)(ANYARGS);
+	ID *tbl;
+    } u1;
+    union {
+	struct RNode *node;
+	ID id;
+	long argc;
+	VALUE value;
+    } u2;
+    union {
+	struct RNode *node;
+	ID id;
+	long state;
+	struct global_entry *entry;
+	long cnt;
+	VALUE value;
+    } u3;
+} NODE;
+
+#define nd_body  u2.node
+#define nd_noex  u3.id
+
+#define NOEX_PUBLIC    0x00
+#define NOEX_PRIVATE   0x02
+#define NOEX_PROTECTED 0x04
+#define NOEX_MASK      0x06

data/lib/looksee.rb

@@ -0,0 +1,332 @@
+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
+#
+# 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,
+# 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"
+#
+# == 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
+    # * +:overridden+ - include methods overridden by subclasses
+    #
+    # The default (if options is nil or omitted) is [:public].
+    #
+    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.new(object, normalized_options)
+    end
+
+    #
+    # The default options passed to lookup_path.
+    #
+    # Default: <tt>{:public => true, :protected => 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
+    # * :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",
+    #         :public     => "\e[1;32m%s\e[0m",
+    #         :protected  => "\e[1;33m%s\e[0m",
+    #         :private    => "\e[1;31m%s\e[0m",
+    #         :overridden => "\e[1;30m%s\e[0m",
+    #       }
+    #
+    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
+  end
+
+  self.default_lookup_path_options = {:public => true, :protected => true, :overridden => true}
+  self.default_width = 80
+  self.styles = {
+    :module     => "\e[1;37m%s\e[0m",
+    :public     => "\e[1;32m%s\e[0m",
+    :protected  => "\e[1;33m%s\e[0m",
+    :private    => "\e[1;31m%s\e[0m",
+    :overridden => "\e[1;30m%s\e[0m",
+  }
+
+  class LookupPath
+    attr_reader :entries
+
+    #
+    # Create a LookupPath for the given object.
+    #
+    # Options may be given to restrict which visibilities are
+    # included.
+    #
+    #   :public
+    #   :protected
+    #   :private
+    #   :overridden
+    #
+    def initialize(object, options={})
+      @entries = []
+      seen = {}
+      Looksee.lookup_modules(object).each do |mod|
+        entry = Entry.new(mod, seen, options)
+        entry.methods.each{|m| seen[m] = true}
+        @entries << entry
+      end
+    end
+
+    def inspect(options={})
+      options = normalize_inspect_options(options)
+      entries.map{|e| e.inspect(options)}.join
+    end
+
+    private  # -------------------------------------------------------
+
+    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
+      #
+      # Don't call me, silly.  I'm just part of a LookupPath.
+      #
+      def initialize(mod, seen, options)
+        @module = mod
+        @methods = []
+        @visibilities = {}
+        add_methods(Looksee.internal_public_instance_methods(mod).map{|sym| sym.to_s}   , :public   , seen) if options[:public   ]
+        add_methods(Looksee.internal_protected_instance_methods(mod).map{|sym| sym.to_s}, :protected, seen) if options[:protected]
+        add_methods(Looksee.internal_private_instance_methods(mod).map{|sym| sym.to_s}  , :private  , seen) if options[:private  ]
+        @methods.sort!
+      end
+
+      attr_reader :module, :methods
+
+      #
+      # 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, 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={})
+        styled_module_name << "\n" << Columnizer.columnize(styled_methods, options[:width])
+      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)
+        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
+end