facets 2.8.4 → 2.9.0.pre.1

data/lib/core/facets/kernel/temporarily.rb

@@ -0,0 +1,23 @@
+module Kernel
+
+  # Temporarily set variables while yielding a block, then return the
+  # variables to their original settings when complete.
+  #
+  #   temporarily('$VERBOSE'=>false) do
+  #     $VERBOSE.assert == false
+  #   end
+  #
+  def temporarily(settings) #:yield:
+    cache = {}
+    settings.each do |var, val|
+      cache[var] = eval("#{var}")
+      eval("proc{ |v| #{var} = v }").call(val)
+    end
+    yield
+  ensure
+    cache.each do |var, val|
+      eval("proc{ |v| #{var} = v }").call(val)
+    end
+  end
+
+end

data/lib/core/facets/kernel/try.rb

@@ -1,25 +1,58 @@
+require 'facets/functor'
+
 module Kernel
 
-  # Try a method.
+  # Invokes the method identified by the symbol +method+, passing it any
+  # arguments  and/or the block specified, just like the regular Ruby
+  # <tt>Object#send</tt> does.
   #
-  #   @person ? @person.name : nil
-  # vs
+  # *Unlike* that method however, a +NoMethodError+ exception will *not*
+  # be raised and +nil+ will be returned instead, if the receiving object
+  # is a +nil+ object or NilClass.
   #
-  #   @person.try(:name)
+  # For example, without try
   #
-  # CREDIT: Chris Wanstrath
-
-  def try(method, default=nil)
-    if respond_to? method
-      send method
+  #   @example = Struct.new(:name).new("bob")
+  #
+  #   @example && @example.name
+  #
+  # or:
+  #
+  #   @example? @example.name : nil
+  #
+  # But with try
+  #
+  #   @example.try(:name)  #=> "bob"
+  #
+  # or
+  #
+  #   @example.try.name  #=> "bob"
+  #
+  # It also accepts arguments and/or a block, for the method it is trying:
+  #
+  #   @people.try(:collect){ |p| p.name }
+  #
+  def try(method=nil, *args, &block)
+    if method
+      __send__(method, *args, &block)
     else
-      default
+      self
     end
   end
 
 end
 
 
+class NilClass
 
+  # See Kernel#try.
+  def try(method=nil, *args)
+    if method
+      nil
+    else
+      Functor.new{ nil }
+    end
+  end
 
+end
 

data/lib/core/facets/kernel/try_dup.rb

@@ -1,13 +1,16 @@
 module Kernel
   # Override this in a child class if it cannot be dup'ed.
   #
+  #   obj1 = Object.new
+  #   obj2 = obj1.try_dup
+  #   obj2.equal?(obj1)    #=> false
+  #
   # CREDIT: Dan Kubb (extlib)
   def try_dup
     dup
   end
 
   # Alternative name for #try_dup.
-  # This will eventually be deprecated.
   def dup!
     try_dup
   end
@@ -16,6 +19,9 @@ end
 class TrueClass
   # Since TrueClass is immutable it cannot be duplicated.
   # For this reason #try_dup returns +self+.
+  #
+  #   true.try_dup  #=> true
+  #
   def try_dup
     self
   end
@@ -24,6 +30,9 @@ end
 class FalseClass
   # Since FalseClass is immutable it cannot be duplicated.
   # For this reason #try_dup returns +self+.
+  #
+  #   false.try_dup  #=> false
+  #
   def try_dup
     self
   end
@@ -32,6 +41,9 @@ end
 class NilClass
   # Since NilClass is immutable it cannot be duplicated.
   # For this reason #try_dup returns +self+.
+  #
+  #   nil.try_dup  #=> nil
+  #
   def try_dup
     self
   end
@@ -40,6 +52,9 @@ end
 class Numeric
   # Since Numeric is immutable it cannot be duplicated.
   # For this reason #try_dup returns +self+.
+  #
+  #   1.try_dup  #=> 1
+  #
   def try_dup
     self
   end
@@ -48,16 +63,11 @@ end
 class Symbol
   # Since Symbol is immutable it cannot be duplicated.
   # For this reason #try_dup returns +self+.
+  #
+  #   :a.try_dup  #=> :a
+  #
   def try_dup
     self
   end
 end
 
-#class Module
-#  # Since Module is immutable it cannot be duplicated.
-#  # For this reason #try_dup returns +self+.
-#  def try_dup
-#    self
-#  end
-#end
-

data/lib/core/facets/kernel/writers.rb

@@ -0,0 +1,91 @@
+module Kernel
+
+  # Returns an Array of methods ending in '='.
+  #
+  #   class WritersExample
+  #     attr_reader :a, :b
+  #     attr_accessor :x, :y
+  #     private
+  #     def q=(q); @q=q; end
+  #   end
+  #
+  #   w = WritersExample.new
+  #
+  #   syms = w.writers      # [:x=, :y=]
+  #
+  #   syms.include?(:x=)    #=> true
+  #   syms.include?(:y=)    #=> true
+  #
+  # If the +chomp+ option is true, then the trailing '=' will be removed.
+  #
+  #   syms = w.writers(:chomp=>true)
+  #
+  #   syms.include?(:x)     #=> true
+  #   syms.include?(:y)     #=> true
+  #
+  # By default #writers only includes public methods. To see private or
+  # protected methods use the +:access+ option.
+  #
+  #   w.writers(:access=>:private)  #=> [:q=]
+  #
+  # Or multiple access options,
+  #
+  #   syms = w.writers(:access=>[:public,:private])    # [:q=,:x=,:y=]
+  #
+  #   syms.include?(:q=)    #=> true
+  #   syms.include?(:x=)    #=> true
+  #   syms.include?(:y=)    #=> true
+  #
+  # You can simply supply `:all` to get all method regardless accessibility.
+  #
+  # Also, by default this method excludes all writers defined in Object 
+  # or Kernel. To include these set +ancestors+ to Object or Kernel.
+  #
+  #   w.writers(Object)
+  #
+  # TODO: Create Module#instance_writers.
+
+  def writers(*ancestors_and_options)
+    options   = (Hash === ancestors_and_options.last ? ancestors_and_options.pop : {})
+    chomp     = options[:chomp]
+    access    = options[:access] || []
+    ancestors = ancestors_and_options.first
+
+    access = [access].flatten
+    if access.include?(:all)
+      access.concat([:public, :protected, :private])
+    end
+    access << :public if access.empty?
+
+    writers = []
+
+    if access.include?(:private)
+      writers += private_methods(ancestors).select{ |m| /=$/ =~ m.to_s  }
+    end
+
+    if access.include?(:protected)
+      writers += protected_methods(ancestors).select{ |m| /=$/ =~ m.to_s  }
+    end
+
+    if access.include?(:public)
+      writers += public_methods(ancestors).select{ |m| /=$/ =~ m.to_s  }
+    end
+
+    if ancestors == Kernel
+      exclude = nil
+    elsif ancestors == Object
+      exclude = Kernel
+    else
+      exclude = Object
+    end
+
+    if exclude
+      kernel_writers = exclude.instance_methods.select{ |m| /=$/ =~ m.to_s  }
+      writers = writers - kernel_writers
+    end
+
+    writers = writers.map{ |w| w.to_s.chomp('=') } if chomp
+    writers.map{ |w| w.to_sym }
+  end
+
+end

data/lib/core/facets/matchdata/matchset.rb

@@ -3,8 +3,8 @@ class MatchData
   # Returns [ pre_match, matchtree, post_match ]. (see matchtree)
   #
   #   md = /(bb)(cc(dd))(ee)/.match "XXaabbccddeeffXX"
-  #   md.to_a      #=> ["XXaabbccddeeffXX", "bb", "ccdd", "dd", "ee"]
-  #   md.matchset  #=> ["XXaa", [["bb"], ["cc", ["dd"]], "ee"], "ffXX"]
+  #   md.to_a      #=> ["bbccddee", "bb", "ccdd", "dd", "ee"]
+  #   md.matchset  #=> ["XXaa", [["bb"], ["cc", ["dd"]], ["ee"]], "ffXX"]
   #
   # CREDIT: Trans
 
@@ -16,8 +16,8 @@ class MatchData
   # order corresponding with the regular expression.
   #
   #   md = /(bb)(cc(dd))(ee)/.match "XXaabbccddeeffXX"
-  #   md.to_a       #=> ["XXaabbccddeeffXX", "bb", "ccdd", "dd", "ee"]
-  #   md.matchtree  #=> [["bb"], ["cc", ["dd"]], "ee"]
+  #   md.to_a       #=> ["bbccddee", "bb", "ccdd", "dd", "ee"]
+  #   md.matchtree  #=> [["bb"], ["cc", ["dd"]], ["ee"]]
   #
   # CREDIT: Trans
 

data/lib/core/facets/method.rb

@@ -0,0 +1,6 @@
+dir, base = *File.split(__FILE__)
+base = base.chomp('.rb')
+Dir[File.join(dir, base, '*')].each do |lib|
+  require "facets/#{base}/#{File.basename(lib)}"
+end
+

data/lib/core/facets/module/abstract.rb

@@ -3,19 +3,22 @@ class Module
   # Create an abstract method. If it is not overridden, it will
   # raise a TypeError when called.
   #
-  #   class C
+  #   class AbstractExample
   #     abstract :a
   #   end
   #
-  #   c = C.new
-  #   c.a  #=> Error: undefined abstraction #a
+  #   c = AbstractExample.new
+  #
+  #   expect TypeError do
+  #     c.a
+  #   end
   #
   # CREDIT: Trans
 
-  def abstract( *sym )
-    sym.each { |s|
-      define_method( s ) { raise TypeError, "undefined abstraction ##{s}" }
-    }
+  def abstract(*sym)
+    sym.each do |s|
+      define_method(s){ raise TypeError, "undefined abstraction ##{s}" }
+    end
   end
 
 end

data/lib/core/facets/module/alias_method_chain.rb

@@ -1,21 +1,39 @@
 class Module
 
-  # Encapsulates the common pattern of:
+  # Encapsulates the common pattern of ...
   #
   #   alias_method :foo_without_feature, :foo
   #   alias_method :foo, :foo_with_feature
   #
-  # With this, you simply do:
+  # With this, you simply do ...
   #
   #   alias_method_chain :foo, :feature
   #
+  # For example
+  #
+  #   class AliasMethodChainExample
+  #     def foo 
+  #       "foo"
+  #     end
+  #
+  #     def foo_with_feature
+  #       "foo!"
+  #     end
+  #
+  #     alias_method_chain :foo, :feature
+  #   end
+  #
   # And both aliases are set up for you.
   #
-  # Query and bang methods (foo?, foo!) keep the same punctuation:
+  #   example = AliasMethodChainExample.new
+  #   example.foo #=> "foo!"
+  #   example.foo_without_feature #=> "foo"
+  #
+  # Query and bang methods (foo?, foo!) keep the same punctuation ...
   #
   #   alias_method_chain :foo?, :feature
   #
-  # is equivalent to
+  # is equivalent to ...
   #
   #   alias_method :foo_without_feature?, :foo?
   #   alias_method :foo?, :foo_with_feature?

data/lib/core/facets/module/alias_module_function.rb

@@ -6,20 +6,20 @@ class Module
   # a module function. The typical #alias_method
   # does not do this.
   #
-  #   module Demo
+  #   module AliasExample
   #     module_function
   #     def hello
   #       "Hello"
   #     end
   #   end
   #
-  #   Demo.hello    #=> Hello
+  #   AliasExample.hello  #=> 'Hello'
   #
-  #   module Demo
+  #   module AliasExample
   #     alias_module_function( :hi , :hello )
   #   end
   #
-  #   Demo.hi       #=> Hello
+  #   AliasExample.hi     #=> 'Hello'
   #
   def alias_module_function(new, old)
     alias_method(new, old)

data/lib/core/facets/module/all_instance_methods.rb

@@ -0,0 +1,19 @@
+class Module
+
+  # List all instance methods, equivalent to
+  #
+  #   public_instance_methods +
+  #   protected_instance_methods +
+  #   private_instance_methods
+  #
+  # TODO: Better name for #all_instance_methods?
+  #
+  # CREDIT: Trans
+
+  def all_instance_methods(include_super=true)
+    public_instance_methods(include_super) +
+    protected_instance_methods(include_super) +
+    private_instance_methods(include_super)
+  end
+
+end

data/lib/core/facets/module/ancestor.rb

@@ -9,7 +9,7 @@ class Module
   #   X.ancestor?(Y)
   #
   def ancestor?( mod )
-    ancestors.include? mod
+    ancestors.include?(mod)
   end
 
 end

data/lib/core/facets/module/anonymous.rb

@@ -0,0 +1,25 @@
+class Module
+
+  # A module may or may not have a name.
+  #
+  # module M; end
+  # M.name # => "M"
+  #
+  # m = Module.new
+  # m.name # => ""
+  #
+  # A module gets a name when it is first assigned to a constant. Either
+  # via the +module+ or +class+ keyword or by an explicit assignment:
+  #
+  # m = Module.new # creates an anonymous module
+  # M = m # => m gets a name here as a side-effect
+  # m.name # => "M"
+  #
+  def anonymous?
+    # The name of an anonymous class is an empty
+    # string in 1.8, and nil in 1.9.
+    name.nil? || name.empty?
+  end
+
+end
+