looksee 0.2.1 → 1.0.0

data/lib/looksee/adapter.rb

@@ -0,0 +1,10 @@
+require 'rbconfig'
+
+module Looksee
+  module Adapter
+    autoload :Base, 'looksee/adapter/base'
+    autoload :MRI, "looksee/mri.#{Config::CONFIG['DLEXT']}"
+    autoload :JRuby, 'looksee/JRuby.jar'
+    autoload :Rubinius, "looksee/adapter/rubinius"
+  end
+end

data/lib/looksee/adapter/base.rb

@@ -0,0 +1,100 @@
+module Looksee
+  module Adapter
+    class Base
+      #
+      # Return the chain of classes and modules which comprise the
+      # object's method lookup path.
+      #
+      def lookup_modules(object)
+        modules = []
+        klass = internal_class(object)
+        while klass
+          modules << internal_class_to_module(klass)
+          klass = internal_superclass(klass)
+        end
+        modules
+      end
+
+      #
+      # Return a description of the given module.
+      #
+      # This is used for the module labels in the Inspector output.
+      #
+      def describe_module(mod)
+        num_brackets = 0
+        object = mod
+        while singleton_class?(object)
+          num_brackets += 1
+          object = singleton_instance(object)
+        end
+
+        if object.is_a?(Module)
+          description = module_name(object)
+          if description.empty?
+            description = "unnamed #{object.is_a?(Class) ? 'Class' : 'Module'}"
+          end
+        else
+          description = "#{module_name(object.class)} instance"
+        end
+
+        if num_brackets == 0
+          description
+        else
+          "#{'['*num_brackets}#{description}#{']'*num_brackets}"
+        end
+      end
+
+      def internal_superclass(klass)
+        raise NotImplementedError, "abstract"
+      end
+
+      def internal_class(object)
+        raise NotImplementedError, "abstract"
+      end
+
+      def internal_class_to_module(internal_class)
+        raise NotImplementedError, "abstract"
+      end
+
+      def internal_public_instance_methods(mod)
+        raise NotImplementedError, "abstract"
+      end
+
+      def internal_protected_instance_methods(mod)
+        raise NotImplementedError, "abstract"
+      end
+
+      def internal_private_instance_methods(mod)
+        raise NotImplementedError, "abstract"
+      end
+
+      def internal_undefined_instance_methods(mod)
+        raise NotImplementedError, "abstract"
+      end
+
+      def singleton_class?(object)
+        raise NotImplementedError, "abstract"
+      end
+
+      def singleton_instance(singleton_class)
+        raise NotImplementedError, "abstract"
+      end
+
+      def module_name(mod)
+        raise NotImplementedError, "abstract"
+      end
+
+      if RUBY_VERSION >= '1.9.0' || Looksee.ruby_engine == 'rbx'
+        def source_location(method)
+          method.is_a?(UnboundMethod) or
+            raise TypeError, "expected UnboundMethod, got #{method.class}"
+          method.source_location
+        end
+      else
+        def source_location(method)
+          raise NotImplementedError, 'abstract'
+        end
+      end
+    end
+  end
+end

data/lib/looksee/adapter/rubinius.rb

@@ -0,0 +1,73 @@
+require 'looksee/adapter/base'
+require 'looksee/rbx'
+
+module Looksee
+  module Adapter
+    class Rubinius < Base
+      def internal_superclass(klass)
+        klass.direct_superclass
+      end
+
+      def internal_class_to_module(internal_class)
+        if internal_class.is_a?(::Rubinius::IncludedModule)
+          internal_class.module
+        else
+          internal_class
+        end
+      end
+
+      def internal_public_instance_methods(mod)
+        mod.method_table.public_names
+      end
+
+      def internal_protected_instance_methods(mod)
+        mod.method_table.protected_names
+      end
+
+      def internal_private_instance_methods(mod)
+        mod.method_table.private_names
+      end
+
+      def internal_undefined_instance_methods(mod)
+        names = []
+        mod.method_table.each_entry do |entry|
+          names << entry.name if entry.visibility.equal?(:undef)
+        end
+        names
+      end
+
+      def singleton_class?(object)
+        object.is_a?(Class) && object.__metaclass_object__
+      end
+
+      def singleton_instance(singleton_class)
+        singleton_class?(singleton_class) or
+          raise TypeError, "expected singleton class, got #{singleton_class.class}"
+        singleton_class.__metaclass_object__
+      end
+
+      def module_name(mod)
+        mod.is_a?(Module) or
+          raise TypeError, "expected module, got #{mod.class}"
+        mod.__name__
+      end
+
+      def source_location(method)
+        method.is_a?(UnboundMethod) or
+          raise TypeError, "expected UnboundMethod, got #{method.class}"
+        source_location = method.source_location and
+          return source_location
+
+        # #source_location doesn't always work. If it returns nil, try
+        # a little harder.
+        case (executable = method.executable)
+        when ::Rubinius::BlockEnvironment::AsMethod
+          method = executable.instance_variable_get(:@block_env).method
+          [method.file.to_s, method.lines[1]]
+        when ::Rubinius::DelegatedMethod
+          executable.instance_variable_get(:@receiver).source_location
+        end
+      end
+    end
+  end
+end

data/lib/looksee/clean.rb

@@ -0,0 +1,122 @@
+require "rbconfig"
+
+require 'set'
+
+module Looksee
+  autoload :VERSION, 'looksee/version'
+  autoload :Adapter, 'looksee/adapter'
+  autoload :Columnizer, 'looksee/columnizer'
+  autoload :Editor, 'looksee/editor'
+  autoload :Help, 'looksee/help'
+  autoload :Inspector, 'looksee/inspector'
+  autoload :LookupPath, 'looksee/lookup_path'
+  autoload :WirbleCompatibility, 'looksee/wirble_compatibility'
+
+  class << self
+    #
+    # The default options passed to #ls.
+    #
+    # Default: <tt>[:public, :protected, :private, :undefined,
+    # :overridden]</tt>
+    #
+    attr_accessor :default_specifiers
+
+    #
+    # 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
+
+    #
+    # The editor command, used for Object#edit.
+    #
+    # This string should contain a "%f", which is replaced with the
+    # file name, and/or "%l" which is replaced with the line number. A
+    # "%%" is replaced with "%".
+    #
+    # If the LOOKSEE_EDITOR environment variable is set, it is used as
+    # the default. Otherwise, we use the following heuristic:
+    #
+    # If EDITOR is set, we use that. If it looks like vi, emacs, or
+    # textmate, we also append options to position the cursor on the
+    # appropriate line. If EDITOR is not set, we use "vi +%l %f".
+    #
+    attr_accessor :editor
+
+    #
+    # The interpreter adapter.
+    #
+    # Encapsulates the interpreter-specific functionality.
+    #
+    attr_accessor :adapter
+
+    #
+    # Wrapper around RUBY_ENGINE that's always defined.
+    #
+    attr_accessor :ruby_engine
+
+    #
+    # Show a quick reference.
+    #
+    def help
+      Help.new
+    end
+  end
+
+  self.default_specifiers = [:public, :protected, :private, :undefined, :overridden]
+  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
+  }
+  self.editor = ENV['LOOKSEE_EDITOR'] || ENV['EDITOR'] || 'vi'
+
+  if Object.const_defined?(:RUBY_ENGINE)
+    self.ruby_engine = RUBY_ENGINE
+  else
+    self.ruby_engine = 'ruby'
+  end
+
+  case ruby_engine
+  when 'jruby'
+    self.adapter = Adapter::JRuby.new
+  when 'rbx'
+    self.adapter = Adapter::Rubinius.new
+  else
+    self.adapter = Adapter::MRI.new
+  end
+end

data/lib/looksee/columnizer.rb

@@ -0,0 +1,73 @@
+module Looksee
+  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
+end

data/lib/looksee/core_ext.rb

@@ -0,0 +1,59 @@
+module Looksee
+  module ObjectMixin
+    #
+    # Return a Looksee::Inspector for this object.
+    #
+    # +args+ is an optional list of specifiers.
+    #
+    #   * +:public+ - include public methods
+    #   * +:protected+ - include public methods
+    #   * +:private+ - include public methods
+    #   * +:undefined+ - include public methods (see Module#undef_method)
+    #   * +:overridden+ - include public methods
+    #   * +:nopublic+ - include public methods
+    #   * +:noprotected+ - include public methods
+    #   * +:noprivate+ - include public methods
+    #   * +:noundefined+ - include public methods (see Module#undef_method)
+    #   * +:nooverridden+ - include public methods
+    #   * a string - only include methods containing this string (may
+    #     be used multiple times)
+    #   * a regexp - only include methods matching this regexp (may
+    #     be used multiple times)
+    #
+    # The default (if options is nil or omitted) is given by
+    # #default_lookup_path_options.
+    #
+    def ls(*args)
+      options = {:visibilities => Set[], :filters => Set[]}
+      (Looksee.default_specifiers + args).each do |arg|
+        case arg
+        when String, Regexp
+          options[:filters] << arg
+        when :public, :protected, :private, :undefined, :overridden
+          options[:visibilities].add(arg)
+        when :nopublic, :noprotected, :noprivate, :noundefined, :nooverridden
+          visibility = arg.to_s.sub(/\Ano/, '').to_sym
+          options[:visibilities].delete(visibility)
+        else
+          raise ArgumentError, "invalid specifier: #{arg.inspect}"
+        end
+      end
+      lookup_path = LookupPath.new(self)
+      Inspector.new(lookup_path, options)
+    end
+
+    #
+    # Open an editor at the named method's definition.
+    #
+    # Uses Looksee.editor to determine the editor command to run.
+    #
+    # Only works for methods for which file and line numbers are
+    # accessible.
+    #
+    def edit(name)
+      Editor.new(Looksee.editor).edit(self, name)
+    end
+  end
+
+  Object.send :include, ObjectMixin
+end

data/lib/looksee/editor.rb

@@ -0,0 +1,58 @@
+require 'shellwords'
+
+module Looksee
+  class Editor
+    def initialize(command)
+      @command = command.dup
+      infer_arguments
+    end
+
+    attr_reader :command
+
+    #
+    # Run the editor command for the +method_name+ of +object+.
+    #
+    def edit(object, method_name)
+      method = LookupPath.new(object).find(method_name.to_s) or
+        return
+      file, line = Looksee.adapter.source_location(method)
+      run(file, line) unless line.nil?
+    end
+
+    #
+    # Run the editor command for the given file and line.
+    #
+    def run(file, line)
+      system *command_for(file, line)
+    end
+
+    #
+    # Return the editor command for the given file and line.
+    #
+    # This is an array of the command with its arguments.
+    #
+    def command_for(file, line)
+      line = line.to_s
+      words = Shellwords.shellwords(command)
+      words.map! do |word|
+        word.gsub!(/%f/, file)
+        word.gsub!(/%l/, line)
+        word.gsub!(/%%/, '%')
+        word
+      end
+    end
+
+    private
+
+    def infer_arguments
+      return if command =~ /%[fl]/
+
+      case command[/\S+/]
+      when /\A(?:g?vim?|.*macs|pico|nano)\z/
+        command << " +%l %f"
+      when 'mate'
+        command << " -l%l %f"
+      end
+    end
+  end
+end