whats_up 1.1.4 → 1.2

data/.autotest

@@ -0,0 +1,4 @@
+if RUBY_PLATFORM =~ /darwin/
+  require "autotest/fsevent"
+  require "autotest/growl"
+end

data/.gitignore

@@ -2,4 +2,5 @@
 *.gem
 .bundle
 Gemfile.lock
+doc/*
 pkg/*

data/{README.md → README.rdoc}

@@ -1,12 +1,11 @@
-whats\_up
-=========
+= whats\_up
 
-This is a fork of Dr. Nic's excellent little `what_methods` utility, updated a bit to expand
+This is a fork of Dr. Nic's excellent little what_methods utility, updated a bit to expand
 functionality and bring syntax a bit more in line with the Ruby status quo. It's actually been
 batted around the internet for a while, with rough etchings dating to 2002. So this is my shot at
 it.
 
-**Dr. Nic says** (or is heard from echoes traversing the sands of time)**:**
+<b>Dr. Nic says</b> (or is heard from echoes traversing the sands of time)<b>:</b>
 
 This is from Dr. Nic.  See http://drnicwilliams.com/2006/10/12/my-irbrc-for-consoleirb/
 
@@ -49,20 +48,20 @@ Just what you need in the console.
 Notice the last example: you can pass parameters after the desired result. whats_up will tell you
 what method will return the desired result if you pass those parameters to it.
 
-**Bryan says:**
+<b>Bryan says:</b>
 
-This modest little update retains the original `what?` method, but that was from the halcyon days of
-2006, before the Ruby community had a rough consensus that `?` methods should be returning a true or
-false value (or at least something useable as such). I've aliased that method as `what_equals`.
+This modest little update retains the original +what?+ method, but that was from the halcyon days of
+2006, before the Ruby community had a rough consensus that +?+ methods should be returning a true or
+false value (or at least something useable as such). I've aliased that method as +what_equals+.
 
 You can add arguments by either supplying additional arguments after the expected result or by using
-the `given` method. So the following two queries are equivalent:
+the +given+ method. So the following two queries are equivalent:
 
     5.given(1).what_equals 6
     5.what_equals 6, 1
 
-Note also the addition of helpers like `whats_exactly`, which will only find exact matches, and
-`what_matches`, which will match a regular expression:
+Note also the addition of helpers like +whats_exactly+, which will only find exact matches, and
++what_matches+, which will match a regular expression:
 
     > 5.whats_exactly 5.0
     5.to_f == 5.0
@@ -77,8 +76,8 @@ Note also the addition of helpers like `whats_exactly`, which will only find exa
     "hello".oct      == 0
     => {:length=>5, :size=>5, :bytesize=>5, :to_i=>0, :hex=>0, :oct=>0}
 
-And if you just want to know everything, I've added `what_works_with` that lists the results of all
-current methods and `whats_not_blank_with` that ignores any false, falsy or empty values:
+And if you just want to know everything, I've added +what_works_with+ that lists the results of all
+current methods and +whats_not_blank_with+ that ignores any false, falsy or empty values:
 
     > "hello".what_works_with 2
     "hello" <=> 2   == nil
@@ -99,5 +98,5 @@ current methods and `whats_not_blank_with` that ignores any false, falsy or empt
     "hello".upto(2) == #<Enumerator: "hello":upto(2)>
     # ...
 
-In line with the original `what_methods` gem, you can `require "whats_up/classic"` to enable aliases
-like `what?`, `matches?`, `exactly?`, `works?` and `not_blank?`.
+In line with the original +what_methods+ gem, you can <tt>require "whats_up/classic"</tt> to enable
+aliases like +what?+, +matches?+, +exactly?+, +works?+ and +not_blank?+.

data/Rakefile

@@ -1 +1,20 @@
 require "bundler/gem_tasks"
+require "sdoc"
+
+# Quick hack until SDoc gets fixed
+class RDoc::Generator::SDoc; alias :basedir :base_dir; end
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = "doc/rdoc"
+  rdoc.title = "whats_up Documentation"
+
+  rdoc.options << "-f" << "sdoc"         # format with SDoc
+  rdoc.options << "-T" << "rails"        # use the Rails template
+  rdoc.options << "-c" << "utf-8"
+  rdoc.options << "-g"                   # link to GitHub
+  rdoc.options << "-m" << "README.rdoc"  # use README.rdoc as main file
+  rdoc.options << "-v"                   # verbose
+
+  rdoc.rdoc_files.include "README.rdoc"
+  rdoc.rdoc_files.include "lib/**/*.rb"
+end

data/lib/whats_up.rb

@@ -20,59 +20,14 @@
 #   http://www.doublegifts.com/pub/ruby/methodfinder.rb.html
 # * Checks permutations of arguments
 #   http://www.doublegifts.com/pub/ruby/methodfinder2.rb.html
-#
-# Last updated: 2006/05/20
-
-class Object
-  def given(*args)
-    if frozen?
-      WhatsUp::FrozenSection.new self, args: args
-    else
-      @args = args
-      self
-    end
-  end
-
-  def what_equals(expected_result, *args, &block)
-    show_methods expected_result, {}, *args, &block
-  end
-
-  def whats_exactly(expected_result, *args, &block)
-    show_methods expected_result, { force_exact: true }, *args, &block
-  end
-  
-  def what_matches(expected_result, *args, &block)
-    show_methods expected_result, { force_regex: true }, *args, &block
-  end
-
-  def what_works_with(*args, &block)
-    show_methods nil, { show_all: true }, *args, &block
-  end
-  alias :what_works :what_works_with
-
-  def whats_not_blank_with(*args, &block)
-    show_methods nil, { show_all: true, exclude_blank: true }, *args, &block
-  end
-  alias :whats_not_blank :whats_not_blank_with
-
-  # Make sure cloning doesn't cause anything to fail via type errors
-  alias_method :__clone__, :clone
-  def clone
-    __clone__
-  rescue TypeError
-    self
-  end
-
-  private
-
-  def show_methods(expected_result, opts = {}, *args, &block)
-    @args = args unless args.empty?
-    WhatsUp::MethodFinder.show(self, expected_result, opts, *@args, &block)
-  end
-end
-
 module WhatsUp
+  autoload :Classic,       "whats_up/classic"
   autoload :DummyOut,      "whats_up/dummy_out"
   autoload :FrozenSection, "whats_up/frozen_section"
   autoload :MethodFinder,  "whats_up/method_finder"
+  autoload :Methods,       "whats_up/methods"
+end
+
+class Object  # :nodoc:
+  include WhatsUp::Methods
 end

data/lib/whats_up/classic.rb

@@ -1,15 +1,25 @@
 require "whats_up"
 
-class Object
-  alias :what?      :what_equals
-  alias :exactly?   :whats_exactly
-  alias :matches?   :what_matches
-  alias :works?     :what_works_with
-  alias :not_blank? :whats_not_blank_with
-end
-
 module WhatsUp
-  class MethodFinder
-    @@blacklist += %w(what? exactly? matches? works? not_blank?)
+  # This module contains the original +what?+ method, as well as some aliases for newer methods. In
+  # line with the current expectation that a Ruby method ending in +?+ returns a true or false value
+  # (or at least something truthy or falsy), I've decided not to make +what?+ and it's brethren the
+  # default. You can include them by:
+  #
+  #   require "whats_up/classic"
+  #
+  # or, if whats_up is already loaded:
+  # 
+  #   WhatsUp::Classic  # which triggers whats_up/classic to autoload
+  module Classic
+    alias :what?      :what_equals
+    alias :exactly?   :whats_exactly
+    alias :matches?   :what_matches
+    alias :works?     :what_works_with
+    alias :not_blank? :whats_not_blank_with
   end
 end
+
+class Object  # :nodoc:
+  include WhatsUp::Classic
+end

data/lib/whats_up/dummy_out.rb

@@ -1,7 +1,10 @@
 module WhatsUp
   # A class to suppress anything that would normally output to $stdout
   class DummyOut
-    # Does nothing (instead of writing to $stdout)
-    def write(*args); end
+    # Does nothing (instead of writing to an IO stream)
+    def write(*args)
+    end
+    alias :print :write
+    alias :puts  :write
   end
 end

data/lib/whats_up/frozen_section.rb

@@ -1,5 +1,15 @@
 module WhatsUp
+  # A classic designed to allow variables to be stored along with a frozen object.
+  #
+  # Frozen objects can't have new instance variables added directly, so this prevents whats_up
+  # methods from being locked out of inspecting anything frozen. This proxy class should be
+  # initialized automatically if whats_up detects that the object it's to inspect is frozen.
   class FrozenSection
+    # The frozen object
+    attr_reader :object
+
+    # Creates a new FrozenSection object from the provided +object+ and a list of instance variables
+    # to store
     def initialize(object, vars = {})
       @object = object
       vars.each do |key, value|
@@ -9,9 +19,11 @@ module WhatsUp
 
     private
 
-    def show_methods
+    # An override of Methods#show_methods that passes the object stored in <tt>@object</tt> instead of
+    # +self+
+    def show_methods(expected_result, opts = {}, *args, &block)  # :doc:
       @args = args unless args.empty?
-      WhatsUp::MethodFinder.show(@object, expected_result, opts, *@args)
+      MethodFinder.show(@object, expected_result, opts, *@args)
     end
   end
 end

data/lib/whats_up/method_finder.rb

@@ -1,46 +1,60 @@
 module WhatsUp
+  # A singleton class used to iterate over the methods of an object trying to match any returned
+  # values with an expected result. ny matches will then be pretty printed to the console.
   class MethodFinder
-    @@blacklist = %w(daemonize display exec exit! fork sleep system syscall what_equals
-                     whats_exactly what_matches what_works_with what_works whats_not_blank_with
-                     whats_not_blank given ed emacs mate nano vi vim)
+    # A list of symbols indicated which methods to always ignore
+    @@blacklist = %w(daemonize debug debugger display ed emacs exactly? exec exit! fork given
+                     matches? mate nano not_blank? sleep stub stub! stub_chain syscall system unstub
+                     unstub! vi vim what? what_equals what_matches what_works what_works_with
+                     whats_exactly whats_not_blank whats_not_blank_with works?).map(&:to_sym)
+
+    # A list of symbols for infix operators for which Ruby has special syntax
     @@infixes   = %w(+ - * / % ** == != =~ !~ !=~ > < >= <= <=> === & | ^ << >>).map(&:to_sym)
-    @@prefixes  = %w(+@ -@ ~ !).map(&:to_sym)
     
-    def initialize(obj, *args)
-      @obj = obj
-      @args = args
-    end
-    def ==(val)
-      MethodFinder.show(@obj, val, *@args)
-    end
+    # A list of symbols for prefix operators for which Ruby has special syntax
+    @@prefixes  = %w(+@ -@ ~ !).map(&:to_sym)
     
     class << self
+      # Builds a lambda for checking against the provided +expected_result+ given a hash of options.
+      # Given the value of a method, the result of this lambda will determine whether that method
+      # and value are included in the output of a whats_up method.
+      #
+      # ==== Options
+      #
+      # * <tt>:exclude_blank</tt> - Exclude blank values
+      # * <tt>:force_exact</tt> - Force values to be exactly equal
+      # * <tt>:force_regex</tt> - Coerce the +expected_result+ into a regular expression for pattern
+      #   matching
+      # * <tt>:show_all</tt> - Show the results of all methods
       def build_check_lambda(expected_result, opts = {})
         if opts[:force_regex]
           expected_result = Regexp.new(expected_result.to_s) unless expected_result.is_a?(Regexp)
-          -> value { expected_result === value.to_s }
+          ->(value) { expected_result === value.to_s }
         elsif expected_result.is_a?(Regexp) && !opts[:force_exact]
-          -> value { expected_result === value.to_s }
+          ->(value) { expected_result === value.to_s }
         elsif opts[:force_exact]
-          -> value { expected_result.eql?(value) }
+          ->(value) { expected_result.eql?(value) }
         elsif opts[:show_all]
           if opts[:exclude_blank]
-            -> value { !value.nil? && !value.empty? }
+            ->(value) { !value.nil? && !(value.respond_to?(:empty?) && value.empty?) }
           else
-            -> value { true }
+            ->(value) { true }
           end
         else
-          -> value { expected_result == value }
+          ->(value) { expected_result == value }
         end
       end
 
-      # Find all methods on [an_object] which, when called with [args] return [expected_result]
+      # Find all methods on +an_object+ which, when called with +args+ return +expected_result+
       def find(an_object, expected_result, opts = {}, *args, &block)
         check_result    = build_check_lambda(expected_result, opts)
 
         # Prevent any writing to the terminal
         stdout, stderr = $stdout, $stderr
-        $stdout = $stderr = DummyOut.new
+        unless $stdout.is_a?(DummyOut)
+          $stdout = $stderr = DummyOut.new
+          restore_std = true
+        end
 
         # Use only methods with valid arity that aren't blacklisted
         methods = an_object.methods
@@ -48,8 +62,8 @@ module WhatsUp
 
         # Collect all methods equaling the expected result
         results = methods.inject({}) do |res, name|
+          stdout.print ""
           begin
-            stdout.print ""
             value = an_object.clone.method(name).call(*args, &block)
             res[name] = value if check_result.call(value)
           rescue
@@ -58,11 +72,11 @@ module WhatsUp
         end
 
         # Restore printing to the terminal
-        $stdout, $stderr = stdout, stderr
+        $stdout, $stderr = stdout, stderr if restore_std
         results
       end
       
-      # Pretty-prints the results of the previous method
+      # Pretty prints the results of #find
       def show(an_object, expected_result, opts = {}, *args, &block)
         opts = {
           exclude_blank: false,
@@ -71,13 +85,11 @@ module WhatsUp
           show_all:      false
         }.merge(opts)
 
-        found = find(an_object, expected_result, opts, *args, &block)
+        found      = find(an_object, expected_result, opts, *args, &block)
         prettified = prettify_found(an_object, found, *args)
         max_length = prettified.map { |k, v| k.length }.max
 
-        prettified.each do |key, value|
-          puts "#{key.ljust max_length} == #{value}"
-        end
+        prettified.each { |k, v| puts "#{k.ljust max_length} == #{v}" }
 
         found
       end
@@ -85,11 +97,9 @@ module WhatsUp
       private
 
       # Pretty prints a method depending on whether it's an operator, has arguments, is array/hash
-      # syntax, etc. For example:
-      #
-      #   
+      # syntax, etc.
       def prettify_found(an_object, found, *args)
-        args = args.map { |o| o.inspect }.join(", ")
+        args = args.map { |a| a.inspect }.join(", ")
         pretty_object = truncate_inspect(an_object, to: 40)
 
         found.map do |key, value|
@@ -119,7 +129,7 @@ module WhatsUp
 
         if full.length > max_length
           available_length = max_length - 5  # to account for the " ... "
-          left_cutoff      = available_length * 2 / 3.0
+          left_cutoff      = available_length * 2 / 3
           right_cutoff     = available_length - left_cutoff - 1
 
           "#{full[0..left_cutoff]} ... #{full[-right_cutoff..-1]}"

data/lib/whats_up/methods.rb

@@ -0,0 +1,67 @@
+module WhatsUp
+  # The methods added to all objects by whats_up
+  module Methods
+    # Provides a list of arguments that will be used when trying to find matching methods.
+    #
+    #   5.given(1).what_equals 6
+    #   # => 5 + 1 == 6
+    def given(*args)
+      if frozen?
+        FrozenSection.new self, args: args
+      else
+        @args = args
+        self
+      end
+    end
+
+    # Outputs a list of methods and their values that equal an +expected_result+, allowing for some
+    # coercion (e.g. <tt>5 == 5.0</tt>)
+    def what_equals(expected_result, *args, &block)
+      show_methods expected_result, {}, *args, &block
+    end
+
+    # Outputs a list of methods and their values that exactly equal an +expected_result+
+    def whats_exactly(expected_result, *args, &block)
+      show_methods expected_result, { force_exact: true }, *args, &block
+    end
+
+    # Outputs a list of methods and their values that match an +expected_result+, which is coerced
+    # into a regular expression if it's not already one
+    def what_matches(expected_result, *args, &block)
+      show_methods expected_result, { force_regex: true }, *args, &block
+    end
+
+    # Outputs a list of all methods and their values
+    def what_works_with(*args, &block)
+      show_methods nil, { show_all: true }, *args, &block
+    end
+    alias :what_works :what_works_with
+
+    # Outputs a list of all methods and their values, provided they are not blank (nil, false,
+    # undefined, empty)
+    def whats_not_blank_with(*args, &block)
+      show_methods nil, { show_all: true, exclude_blank: true }, *args, &block
+    end
+    alias :whats_not_blank :whats_not_blank_with
+
+    # Make sure cloning doesn't cause anything to fail via type errors
+    alias_method :__clone__, :clone
+
+    # Adds in a type error check to the default Object#clone method to prevent any interruptions while
+    # checking methods. If a TypeError is encountered, +self+ is returned
+    def clone
+      __clone__
+    rescue TypeError
+      self
+    end
+
+    private
+
+    # Called by all of the +what_+ methods, this tells MethodFinder to output the result for any methods
+    # matching an +expected_result+ for the #given arguments
+    def show_methods(expected_result, opts = {}, *args, &block)  # :doc:
+      @args = args unless args.empty?
+      MethodFinder.show(self, expected_result, opts, *@args, &block)
+    end
+  end
+end

data/lib/whats_up/version.rb

@@ -1,4 +1,4 @@
 module WhatsUp
   # The current version
-  VERSION = "1.1.4"
+  VERSION = "1.2"
 end

data/spec/classic_spec.rb

@@ -0,0 +1,12 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe "WhatsUp::Classic" do
+  it "should not have any classic methods without Classic loaded" do
+    "hello".should_not respond_to(:what?)
+  end
+
+  it "should have classic methods with Classic loaded" do
+    require "whats_up/classic"
+    "hello".should respond_to(:what?)
+  end
+end

data/spec/frozen_section_spec.rb

@@ -1,4 +1,3 @@
-# coding: utf-8
 require File.dirname(__FILE__) + "/spec_helper"
 
 describe FrozenSection do

data/spec/methods_spec.rb

@@ -0,0 +1,62 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe Methods do
+  before :all do
+    @stderr,  @stdout = $stderr, $stdout
+    $stderr = $stdout = DummyOut.new
+  end
+
+  after :all do
+    $stderr,  $stdout = @stderr, @stdout
+  end
+
+  describe "what_equals" do
+    it "should find the correct method without arguments" do
+      "hello ".what_equals("hello").should have_key(:rstrip)
+    end
+
+    it "should find the correct method with arguments" do
+      "hello".what_equals("e", 1).should have_key(:[])
+    end
+
+    it "should find the correct method with arguments using given" do
+      "hello".given(1).what_equals("e").should have_key(:[])
+    end
+  end
+
+  describe "what_matches" do
+    it "should find the correct method given a regular expression" do
+      5.what_matches(/5/).should have_key(:to_s)
+    end
+
+    it "should find the correct method by converting an arbitrary object to a regular expression" do
+      5.what_matches(5).should have_key(:to_s)
+    end
+  end
+
+  describe "whats_exactly" do
+    it "should fail to match inexact matches that would succeed with == type coercion" do
+      5.whats_exactly(5.0).should_not have_key(:to_i)
+    end
+
+    it "should succeed for exact matches" do
+      5.whats_exactly(5.0).should have_key(:to_f)
+    end
+  end
+
+  describe "whats_not_blank" do
+    it "should include only non-blank values" do
+      5.whats_not_blank.select { |n| !n || n.empty? }.should be_empty
+    end
+  end
+
+  describe "what_works" do
+    it "should produce all results found with whats_not_blank" do
+      works = 5.what_works
+
+      5.whats_not_blank.keys.each do |key|
+        works.should have_key(key)
+      end
+    end
+  end
+end

data/whats_up.gemspec

@@ -13,10 +13,17 @@ Gem::Specification.new do |s|
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   s.require_paths = ["lib"]
 
+  s.add_runtime_dependency "sdoc"
+  
   s.add_development_dependency "autotest"
   s.add_development_dependency "bundler"
   s.add_development_dependency "rspec"
+
+  if RUBY_PLATFORM =~ /darwin/
+    s.add_development_dependency "autotest-fsevent"
+    s.add_development_dependency "autotest-growl"
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whats_up
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: '1.2'
   prerelease: 
 platform: ruby
 authors:
@@ -10,8 +10,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-23 00:00:00.000000000 Z
+date: 2012-03-24 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: sdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: autotest
   requirement: !ruby/object:Gem::Requirement
@@ -60,6 +76,38 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: autotest-fsevent
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: autotest-growl
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Determine what methods can be called on an object that return a given
   value
 email:
@@ -73,15 +121,18 @@ files:
 - .gitignore
 - .rspec
 - Gemfile
-- README.md
+- README.rdoc
 - Rakefile
 - lib/whats_up.rb
 - lib/whats_up/classic.rb
 - lib/whats_up/dummy_out.rb
 - lib/whats_up/frozen_section.rb
 - lib/whats_up/method_finder.rb
+- lib/whats_up/methods.rb
 - lib/whats_up/version.rb
+- spec/classic_spec.rb
 - spec/frozen_section_spec.rb
+- spec/methods_spec.rb
 - spec/spec_helper.rb
 - whats_up.gemspec
 homepage: http://brymck.herokuapp.com/
@@ -109,5 +160,7 @@ signing_key:
 specification_version: 3
 summary: Determine what methods can be called on an object that return a given value
 test_files:
+- spec/classic_spec.rb
 - spec/frozen_section_spec.rb
+- spec/methods_spec.rb
 - spec/spec_helper.rb