facets 3.0.0 → 3.2.0

data/lib/core/facets/enumerable/with_position.rb

@@ -0,0 +1,58 @@
+
+module Enumerable
+	class Position
+		def initialize
+			@first = true
+			@last = false
+		end
+		
+		def after_first!
+			@first = false
+		end
+		
+		def at_end!
+			@last = true
+		end
+		
+		def first?
+			@first
+		end
+		
+		def middle?
+			not (@first or @last)
+		end
+		
+		def last?
+			@last
+		end
+	end
+	
+	# Allows one to know the position of the enumeration easily.
+	#
+	#    5.times.collect.with_position do |i, position|
+	#        $stdout.write "#{i}#{position.middle? ? ',' : ''}"
+	#    end
+	#
+	# Where this becomes more useful, is when it's easy to determine the position of elements, e.g.
+	#
+	#    10.times.select(&:odd?).with_position{|n,p| ... }
+	#
+	def with_position
+		return to_enum(:with_position) unless block_given?
+		
+		position = Position.new
+		
+		while item = self.next
+			begin
+				self.peek
+			rescue StopIteration
+				position.at_end!
+			end
+			
+			yield item, position.dup
+			
+			position.after_first!
+		end
+	rescue StopIteration
+	end
+end

data/lib/core/facets/enumerator.rb

@@ -1,75 +1,2 @@
-if RUBY_VERSION < '1.9'
-
-  require 'enumerator'
-
-  # for Ruby 1.8 -> 1.9 transition
-  Enumerator = Enumerable::Enumerator unless defined?(::Enumerator)
-
-  class Enumerator
-
-    private
-
-    alias :old_initialize :initialize
-
-    # Provides the ruby-1.9 block form of Enumerator, where you can write:
-    #
-    #    obj = Enumerator.new do |yielder|
-    #      # ...
-    #      yielder.yield(data)  # or: yielder << data
-    #      # ...
-    #    end
-    #
-    # When obj.each is called, the block is run once. It should call
-    # yielder.yield with each item it wishes to generate.
-    #
-    # Example:
-    #
-    #   fib = Enumerator.new { |y|
-    #     a = b = 1
-    #     loop {   
-    #       y << a
-    #       a, b = b, a + b
-    #     }
-    #   }  
-    #
-    #   fib.take(10)  #=> [1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
-    #                                                 
-    def initialize(*args, &block)
-      if block
-        @body = block
-        old_initialize(self, :_start)
-      else
-        old_initialize(*args)
-      end
-    end
-
-    def _start(*args,&receiver) #:nodoc:
-      @body.call(Yielder.new(&receiver), *args)
-    end
-
-    # Wrapper to allow yielder.yield(output) or yielder << output
-    # in the same way as ruby-1.9
-    #
-    # TODO: Why can't Yielder take a block instead of a proc argument?
-
-    class Yielder #:nodoc:
-      def initialize(&proc)
-        @proc = proc
-      end
-      def yield(*args)
-        @proc[*args]
-      end
-      alias :<< :yield
-    end
-
-  end
-
-end
-
-path = __FILE__.chomp('.rb')
-base = File.basename(path)
-Dir[File.join(path, '*.rb')].each do |lib|
-  #require lib # why is this so much slower?
-  require "facets/#{base}/#{File.basename(lib)}"
-end
-
+require_relative 'enumerator/fx'
+require_relative 'enumerator/lazy/squeeze'

data/lib/core/facets/exception/error_print.rb

@@ -1,80 +1,15 @@
 class Exception
 
-  # Formats the Exception so that it looks *familiar*,
-  # i.e. exactly like your interpreter does it.
-  #
-  # Port of MRI native `error_print` function.
-  #
-  # @author Evgeniy Dolzhenko
-
+  # @deprecated Use Exception#full_message instead (built-in since Ruby 2.5).
   def self.error_print(e)
-    warn_print = ""
-    backtrace = e.backtrace
-    backtrace = [ backtrace ] if backtrace.is_a?(String) # 1.9 returns single String for SystemStackError
-
-    warn_print << backtrace[0]
-    if e.is_a?(RuntimeError) && e.message.empty?
-      warn_print << ": unhandled exception\n"
-    else
-      if e.message.empty?
-        warn_print << ": #{ e.class.name }\n"
-      else
-        split_message = e.message.split("\n")
-        warn_print << ": "
-        if split_message.size == 1
-          warn_print << "#{ e.message } (#{ e.class.name })\n"
-        else
-          warn_print << split_message[0]
-          warn_print << " (#{ e.class.name })\n"
-          warn_print << split_message[1..-1].join("\n").chomp << "\n"
-        end
-      end
-    end
-
-    len = backtrace.size
-
-    ## int skip = eclass == rb_eSysStackError;
-    skip = e.is_a?(SystemStackError)
-
-    ## #define TRACE_MAX (TRACE_HEAD+TRACE_TAIL+5)
-    ## #define TRACE_HEAD 8
-    ## #define TRACE_TAIL 5
-    trace_head = 8
-    trace_tail = 5
-    trace_max = (trace_head + trace_tail + 5)
-    ##
-    ##	for (i = 1; i < len; i++) {
-    i = 1
-    while i < len
-      ##	    if (TYPE(ptr[i]) == T_STRING) {
-      ##		warn_printf("\tfrom %s\n", RSTRING_PTR(ptr[i]));
-      ##	    }
-      warn_print << "\tfrom %s\n" % e.backtrace[i]
-
-      ##	    if (skip && i == TRACE_HEAD && len > TRACE_MAX) {
-      if skip && i == trace_head && len > trace_max
-      ##		warn_printf("\t ... %ld levels...\n",
-      ##			    len - TRACE_HEAD - TRACE_TAIL);
-        warn_print << "\t ... %d levels...\n" % (len - trace_head - trace_tail)
-      ##		i = len - TRACE_TAIL;
-        i = len - trace_tail
-      ##	    }
-      end
-      ##	}
-      i += 1
-    end
-    warn_print
+    warn "Exception.error_print is deprecated. Use Exception#full_message instead.", uplevel: 1
+    e.full_message
   end
 
-  # Formats the Exception so that it looks *familiar*,
-  # i.e. exactly like your interpreter does it.
-  #
-  # @author Evgeniy Dolzhenko
-  #
-  # @todo Anyone have a better name for this method?
+  # @deprecated Use Exception#full_message instead (built-in since Ruby 2.5).
   def error_print
-    Exception.error_print(self)
+    warn "Exception#error_print is deprecated. Use Exception#full_message instead.", uplevel: 1
+    full_message
   end
 
 end
-

data/lib/core/facets/file/atomic_open.rb

@@ -12,7 +12,7 @@ class File
   #
   def self.atomic_open(file_name, mode="r", temp_dir=nil, &block)
     temp_dir  = temp_dir || Dir.tmpdir
-    temp_file = Tempfile.new("#{aomtic_id}-" + basename(file_name), temp_dir)
+    temp_file = Tempfile.new("#{atomic_id}-" + basename(file_name), temp_dir)
 
     if File.exist?(file_name)
       FileUtils.cp(file_name, temp_file)

data/lib/core/facets/file/null.rb

@@ -1,21 +1,9 @@
 class File
 
-  # Platform dependent null device.
-  #
-  # CREDIT: Daniel Burger
-
+  # @deprecated Use File::NULL constant instead (built-in since Ruby 1.9.3).
   def self.null
-    case RUBY_PLATFORM
-    when /mswin/i
-      'NUL'
-    when /amiga/i
-      'NIL:'
-    when /openvms/i
-      'NL:'
-    else
-      '/dev/null'
-    end
+    warn "File.null is deprecated. Use File::NULL instead.", uplevel: 1
+    File::NULL
   end
 
 end
-

data/lib/core/facets/file/read_binary.rb

@@ -1,18 +1,9 @@
 class File
 
-  # Read in a file as binary data.
-  #
-  # Assuming we had a binary file 'binary.dat'.
-  #
-  #   File.read_binary('binary.dat')
-  #
-  # CREDIT: George Moschovitis
-
+  # @deprecated Use File.binread instead (built-in since Ruby 1.9.3).
   def self.read_binary(fname)
-    open(fname, 'rb') do |f|
-      return f.read
-    end
+    warn "File.read_binary is deprecated. Use File.binread instead.", uplevel: 1
+    binread(fname)
   end
 
 end
-

data/lib/core/facets/hash/except.rb

@@ -1,10 +1,15 @@
 class Hash
 
-  # Returns a new hash less the given keys.
-  def except(*less_keys)
-    hash = dup
-    less_keys.each{ |k| hash.delete(k) }
-    hash
+  # Replaces hash with new hash less the given keys.
+  #
+  #   h = {:a=>1, :b=>2, :c=>3}
+  #   h.except!(:a)  #=> {:b=>2,:c=>3}
+  #   h              #=> {:b=>2,:c=>3}
+  #
+  # Returns the hash.
+  def except!(*rejected)
+    rejected.each{ |k| delete(k) }
+    self
   end
 
   # Replaces hash with new hash less the given keys.
@@ -15,7 +20,7 @@ class Hash
   #   h              #=> {:b=>2,:c=>3}
   #
   # Returns a Hash of the removed pairs.
-  def except!(*rejected)
+  def remove!(*rejected)
     removed = {}
     rejected.each{ |k| removed[k] = delete(k) }
     removed

data/lib/core/facets/hash/fetch_nested.rb

@@ -1,18 +1,17 @@
 class Hash
 
-  # Similar to Hash#fetch but supports nested lookup and is `nil` safe.
+  # @deprecated Use Hash#dig instead (built-in since Ruby 2.3).
   #
-  #     {}.fetch_nested('anything','at','all')  #=> nil
+  # Similar to Hash#dig but supports a block for missing keys,
+  # like Hash#fetch does. Ruby's #dig does not support a block.
   #
-  #     h = {'hello'=>{'world'=>42}}
-  #     h.fetch_nested(*['hello','world'])  #=> 42
+  # TODO: Consider proposing block support for Hash#dig to Ruby core.
   #
-  # CREDIT: T. Yamada and Sean Mackesey
-
-  def fetch_nested(*keys)
+  def fetch_nested(*keys, &block)
+    warn "Hash#fetch_nested is deprecated. Use Hash#dig instead.", uplevel: 1
     begin
-      keys.reduce(self){|accum, k| accum.fetch(k)}
-	rescue (RUBY_VERSION<'1.9' ? IndexError : KeyError)
+      keys.reduce(self) { |accum, k| accum.fetch(k) }
+    rescue KeyError
       block_given? ? yield(*keys) : nil
     end
   end

data/lib/core/facets/hash/graph.rb

@@ -1,4 +1,4 @@
-require 'facets/enumerable/mash'
+require 'facets/enumerable/graph'
 
 class Hash
 

data/lib/core/facets/hash/rekey.rb

@@ -40,13 +40,13 @@ class Hash
 
     if block
       hash = dup.clear
-      if block.arity.abs == 1
+      if block.arity == 2
         each_pair do |k, v|
-          hash[block[k]] = v     #hash[block[k] || k] = v
+          hash[block[k,v]] = v
         end
       else
         each_pair do |k, v|
-          hash[block[k,v]] = v   #hash[block[k,v] || k] = v
+          hash[block[k]] = v
         end
       end
     else

data/lib/core/facets/hash/revalue.rb

@@ -21,13 +21,13 @@ class Hash
 
     if block
       hash = dup.clear  # to keep default_proc
-      if block.arity.abs == 1
+      if block.arity == 2
         each_pair do |k, v|
-          hash[k] = block[v]     #hash[k] = block[v] || v
+          hash[k] = block[k,v]
         end
       else
         each_pair do |k, v|
-          hash[k] = block[k,v]   #hash[k] = block[k,v] || v
+          hash[k] = block[v]
         end
       end
     else

data/lib/core/facets/hash/{to_proc.rb → setter.rb}

@@ -1,7 +1,7 @@
 class Hash
 
-  # Constructs a Proc object from a hash such that the parameter
-  # of the Proc is assigned the hash keys as attributes.
+  # Constructs a Proc that assigns the hash's key-value pairs as
+  # attributes on a given object.
   #
   #   c = Class.new do
   #     attr_accessor :a
@@ -9,20 +9,20 @@ class Hash
   #
   #   h = {:a => 1}
   #   o = c.new
-  #   h.to_proc.call(o)
+  #   h.setter.call(o)
   #   o.a  #=> 1
   #
-  # If +response+ is set to +true+, then assignment will only occur
-  # if receiver responds_to? the writer method.
+  # If +safe+ is set to +true+, then assignment will only occur
+  # if the receiver responds_to? the writer method.
   #
   # CREDIT: Trans
 
-  def to_proc(response=false)
-    if response
+  def setter(safe=false)
+    if safe
       lambda do |o|
         self.each do |k,v|
           ke = "#{k}="
-          o.__send__(ke, v) if respond_to?(ke)
+          o.__send__(ke, v) if o.respond_to?(ke)
         end
       end
     else
@@ -36,4 +36,3 @@ class Hash
   end
 
 end
-

data/lib/core/facets/hash/slice.rb

@@ -1,25 +1,5 @@
 class Hash
 
-  # Returns a new hash with only the given keys.
-  #
-  #   h = {:a=>1, :b=>2, :c=>3}
-  #   h.slice(:a, :c)  #=> {:a=>1, :c=>3}
-  #   h.slice(:a, :d)  #=> {:a=>1}
-  #
-  def slice(*keep_keys)
-    if block_given?
-      each do |k, v|
-        keep_keys << k if yield(k, v)
-      end
-    end
-
-    hash = {}
-    keep_keys.each do |key|
-      hash[key] = fetch(key) if key?(key)
-    end
-    hash
-  end
-
   # Replaces hash with a new hash having only the given keys.
   # This return the hash of keys removed.
   #
@@ -29,12 +9,6 @@ class Hash
   #
   # Returns a Hash of the removed pairs.
   def slice!(*keep_keys)
-    if block_given?
-      each do |k, v|
-        keep_keys << k if yield(k, v)
-      end
-    end
-
     rejected = keys - keep_keys
     removed = {}
     rejected.each{ |k| removed[k] = delete(k) }

data/lib/core/facets/hash/update_keys.rb

@@ -1,21 +1,14 @@
 class Hash
 
-  # Iterate over hash updating just the keys.
+  # @deprecated Use Hash#transform_keys! (Ruby 2.5+) or Hash#rekey! instead.
   #
-  #   h = {:a=>1, :b=>2}
-  #   h.update_keys{ |k| "#{k}!" }
-  #   h  #=> { "a!"=>1, "b!"=>2 }
-  #
-  # @author Trans
-  # @author Evgeniy Dolzhenko (bug fix)
-
-  def update_keys #:yield:
+  def update_keys(&block)
+    warn "Hash#update_keys is deprecated. Use Hash#transform_keys! or Hash#rekey! instead.", uplevel: 1
     if block_given?
-      keys.each { |old_key| store(yield(old_key), delete(old_key)) }
+      transform_keys!(&block)
     else
       to_enum(:update_keys)
     end
   end
 
 end
-

data/lib/core/facets/hash/update_values.rb

@@ -1,20 +1,14 @@
 class Hash
 
-  # Iterate over hash updating just the values.
+  # @deprecated Use Hash#transform_values! (Ruby 2.4+) or Hash#revalue! instead.
   #
-  #   h = {:a=>1, :b=>2}
-  #   h.update_values{ |v| v + 1 }
-  #   h  #=> { :a=>2, :b=>3 }
-  #
-  # CREDIT: Trans
-
-  def update_values #:yield:
+  def update_values(&block)
+    warn "Hash#update_values is deprecated. Use Hash#transform_values! or Hash#revalue! instead.", uplevel: 1
     if block_given?
-      each{ |k,v| store(k, yield(v)) }
+      transform_values!(&block)
     else
       to_enum(:update_values)
     end
   end
 
 end
-

data/lib/core/facets/indexable.rb

@@ -128,7 +128,7 @@ module Indexable
   #   %w{W o r l d}.from(3)  #=> %w{l d}
   #
   def from(i)
-    return self if i >= size
+    return [] if i >= size
     slice(i, size - i) #slice(-n..-1)
   end
 
@@ -199,19 +199,21 @@ module Indexable
     splice(-1)
   end
 
-  # A shorting of "ends at", returns the
-  # last index of the indexable object.
-  # Returns nil if there are no elements.
+  # A shortening of "ends at". Returns the
+  # last index of the indexable object,
+  # or nil if there are no elements.
   #
   #   [1,2,3,4,5].ends  #=> 4
   #
-  # This nearly equivalent to +size - 1+.
+  # This is nearly equivalent to +size - 1+.
   #
   def ends
     return nil if size == 0
     size - 1
   end
 
+  alias_method :last_index, :ends
+
   # Returns the positive ordinal index given
   # a cardinal position, 1 to n or -n to -1.
   #

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

@@ -3,12 +3,7 @@ module Kernel
   alias_method :pp_callstack, :caller
   alias_method :pp_call_stack, :caller
 
-  # Parse a caller string and break it into its components,
-  # returning an array composed of:
-  #
-  # * file (String)
-  # * lineno (Integer)
-  # * method (Symbol)
+  # Returns the call stack as an array of [file, lineno, method] entries.
   #
   # For example, from irb
   #
@@ -16,27 +11,14 @@ module Kernel
   #
   # _produces_ ...
   #
-  #     [["(irb)", 2, :irb_binding],
-  #       ["/usr/lib/ruby/1.8/irb/workspace.rb", 52, :irb_binding],
-  #       ["/usr/lib/ruby/1.8/irb/workspace.rb", 52, nil]]
-  #
-  # Note: If the user decides to redefine caller() to output data
-  # in a different format, _prior_ to requiring this, then the
-  # results will be indeterminate.
+  #     [["(irb)", 2, :irb_binding], ...]
   #
   # CREDIT: Trans
 
   def callstack(level = 1)
-    call_str_array = pp_callstack(level)
-    stack = []
-    call_str_array.each{ |call_str|
-      file, lineno, method = call_str.split(':')
-      if method =~ /in `(.*)'/ then
-        method = $1.intern()
-      end
-      stack << [file, lineno.to_i, method]
-    }
-    stack
+    caller_locations(level).map do |loc|
+      [loc.path, loc.lineno, loc.label&.to_sym]
+    end
   end
 
   alias_method :call_stack, :callstack
@@ -53,4 +35,3 @@ class Binding
 
   alias_method :call_stack, :callstack
 end
-

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

@@ -3,13 +3,13 @@ module Kernel
   # During this trying time when no one can get their
   # techie catchwords to stick to the refrigerator no
   # matter how hard they slap it with the enchanted
-  # magnetic spatula, it’s good to know that the
+  # magnetic spatula, it's good to know that the
   # contrived phrases really do fly, graceful and
   # unclasped and bearing north toward chilled shrimp.
-  # I know what my Hallowe’en pumpkin is going to say.
+  # I know what my Hallowe'en pumpkin is going to say.
   #
-  # NOTE: This method is not a common core extension and is not
-  # loaded automatically when using `require 'facets'`.
+  # @deprecated Use singleton_class or meta_class instead.
+  #   Kept in tribute to WhyTheLuckyStiff who coined the term.
   #
   # CREDIT: WhyTheLuckyStiff
   #
@@ -17,8 +17,8 @@ module Kernel
   #   require 'facets/kernel/eigenclass'
   #
   def eigenclass
-    (class << self; self; end)
+    warn "Kernel#eigenclass is deprecated. Use singleton_class or meta_class instead.", uplevel: 1
+    singleton_class
   end
 
 end
-

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

@@ -26,7 +26,8 @@ module Kernel
 end
 
 class NilClass
-
+  FUNCTOR = Functor.new{ nil }
+  
   # Compliments Kernel#ergo.
   #
   #   "a".ergo{ |o| o.upcase } #=> "A"
@@ -35,8 +36,7 @@ class NilClass
   # CREDIT: Daniel DeLorme
 
   def ergo
-    @_ergo ||= Functor.new{ nil }
-    @_ergo unless block_given?
+    FUNCTOR unless block_given?
   end
 
 end

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

@@ -1,12 +1,9 @@
 module Kernel
 
-  # TODO: Must reduce the number of singleton method methods.
-
-  # Don't say it!
-  #
+  # @deprecated Use singleton_class or meta_class instead.
   def extension
-    class << self; self; end
+    warn "Kernel#extension is deprecated. Use singleton_class or meta_class instead.", uplevel: 1
+    singleton_class
   end
 
 end
-