y_support 2.1.18 → 2.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 120a7bb4137ae4605604f405ed60fe3cc3f927b4
-  data.tar.gz: e2ba99d2c42fc89f0750262f42d6d8b7572a6c47
+  metadata.gz: 4ab593edcd28581e245478b60043c42f9440086c
+  data.tar.gz: 4fb00fe45dcb47047877141c63c8c4c5d24d5375
 SHA512:
-  metadata.gz: 8eabfab794856a0b786ba8861d97a1909618279a55861ea96f6bd40d18f6267d511945429fa63a52d078f5675e78f3ea00032ec1e22d439935a2322a84a38f60
-  data.tar.gz: 9434baf3adbd88fc9c0161bc193cbc14db37cebc2518c2a934149a4e9a7bb1c455c050f79024952e795092e6f7efe9736db39d83c82f86cd4138e8efa427d780
+  metadata.gz: 8a20065557690cf1b52ce7525f54342597ad97e071e13b2236ddc5584b5084ed7551d7c86a0b8ab9a9989bdcd266abc2e6cff929aa315d3cd2cab177230fc7dc
+  data.tar.gz: 81d28a6721cb01c0d181d6b17524cfa22674b86fdcdc6fed1658350713fbc5c5d672c604531eec70f08ef82322e28a6df4587487dfaa3ad5579ead28ce675dda

data/lib/y_support/all.rb

@@ -1,6 +1,7 @@
 #encoding: utf-8
 
 require 'y_support'
+require 'y_support/flex_coerce'
 require 'y_support/name_magic'
 require 'y_support/typing'
 require 'y_support/unicode'
@@ -8,38 +9,7 @@ require 'y_support/respond_to'
 require 'y_support/null_object'
 require 'y_support/inert_recorder'
 require 'y_support/local_object'
-require 'y_support/try'
-require 'y_support/abstract_algebra'
+require 'y_support/literate'
 require 'y_support/kde'
 require 'y_support/x'
 require 'y_support/misc'
-
-
-# # Test me!
-# class BlankSlate
-#   class << self
-#     # Hide the method named +name+ in the BlankSlate class. Don't
-#     # hide +instance_eval+ or any method beginning with "__".
-#     def hide( name )
-#       if instance_methods.include? name and
-#           name !~ /^(__|instance_eval)/
-#         @hidden_methods ||= {}
-#         @hidden_methods[name] = instance_method name
-#         undef_method name
-#       end
-#     end
-
-#     def find_hidden_method name
-#       @hidden_methods ||= {}
-#       @hidden_methods[name] || superclass.find_hidden_method( name )
-#     end
-
-#     # Redefine a previously hidden method
-#     def reveal name
-#       unbound_method = find_hidden_method name
-#       fail "Don't know how to reveal method '#{name}'" unless unbound_method
-#       define_method( name, unbound_method )
-#     end
-#   end
-# end # class BlankSlate
-

data/lib/y_support/core_ext/array.rb

@@ -1,2 +1,2 @@
-require 'y_support' unless defined? YSupport
-require File.dirname( __FILE__ ) + '/array/misc'
+require_relative '../../y_support'
+require_relative 'array/misc'

data/lib/y_support/core_ext/class.rb

@@ -1,2 +1,2 @@
-require 'y_support' unless defined? YSupport
-require File.dirname( __FILE__ ) + '/class/misc'
+require_relative '../../y_support'
+require_relative 'class/misc'

data/lib/y_support/core_ext/enumerable.rb

@@ -1,2 +1,2 @@
-require 'y_support' unless defined? YSupport
-require File.dirname( __FILE__ ) + '/enumerable/misc'
+require_relative '../../y_support'
+require_relative 'enumerable/misc'

data/lib/y_support/core_ext/hash/misc.rb

@@ -49,16 +49,26 @@ class Hash
     end
   end
 
-  # The difference from #with_keys is that modify_keys expects block that takes
-  # 2 arguments (key: value pair) and returns the new key.
+  # Like #with_keys, but modifies the receiver.
   # 
-  def modify_keys
+  def with_keys!
+    keys.each_with_object self do |key, hsh|
+      hsh[ yield key ] = delete key
+    end
+  end
+
+  # The difference from #with_keys is that modify_keys expects
+  # block that takes 2 arguments (key: value pair) and returns the
+  # new key.
+  # 
+  def change_keys
     each_with_object self.class.new do |pair, hsh|
       hsh[ yield pair ] = self[ pair[0] ]
     end
   end
 
-  # Applies a block as a mapping on all values, returning a new hash.
+  # Applies a block as a mapping on all values, returning a new
+  # hash.
   # 
   def with_values
     each_with_object self.class.new do |(k, v), hsh| hsh[ k ] = yield v end
@@ -70,8 +80,9 @@ class Hash
     each_with_object self do |(k, v), hsh| hsh[ k ] = yield v end
   end
 
-  # The difference from #do_with_values is that modify_values expects block
-  # that takes 2 arguments (key: value pair) and returns the new value.
+  # The difference from #with_values is that modify_values expects
+  # block that takes 2 arguments [ key, value ] and returns the
+  # new value.
   # 
   def modify_values
     each_with_object self.class.new do |pair, hsh|
@@ -96,15 +107,17 @@ class Hash
     end
   end
 
-  # Checking mainly against the collision with ActiveSupport's Hash#slice.
+  # Checking mainly against the collision with ActiveSupport's
+  # Hash#slice.
   if Hash.instance_methods.include? :slice then
     warn "Collision: Method #slice already defined on Hash! (%s)" %
       Hash.instance_method( :slice ).source_location
   end
 
-  # A bit like Array#slice, but only takes 1 argument, which is either a Range,
-  # or an Array, and returns the selection of the hash for the keys that match
-  # the range or are present in the array.
+  # A bit like Array#slice, but only takes 1 argument, which is
+  # either a Range, or an Array, and returns the selection of the
+  # hash for the keys that match the range or are present in the
+  # array.
   # 
   def slice matcher
     self.class[ case matcher

data/lib/y_support/core_ext/hash.rb

@@ -1,2 +1,2 @@
-require 'y_support' unless defined? YSupport
-require File.dirname( __FILE__ ) + '/hash/misc'
+require_relative '../../y_support'
+require_relative 'hash/misc'

data/lib/y_support/core_ext/module/misc.rb

@@ -1,4 +1,13 @@
 class Module
+  # Hopefully not too ridiculous attempt to call a spade a spade. In the
+  # 1964 landmark paper "The mechanical evaluation of expressions", Peter
+  # Landin has defined an abstract language which is a basic for
+  # expression-oriented high-level languages popular today, such as Ruby.
+  # While Ruby's instance variables can be called "attributes", attribute
+  # readers seem to be called "selectors" in Landin's paper.
+  # 
+  alias selector attr_reader
+
   # Creates a module that inherits from the receiver and is parametrized
   # with the given set of parameters. The parameters have form { symbol:
   # value } and they cause singleton method(s) named "symbol" be defined

data/lib/y_support/core_ext/module.rb

@@ -1,2 +1,2 @@
-require 'y_support' unless defined? YSupport
-require File.dirname( __FILE__ ) + '/module/misc'
+require_relative '../../y_support'
+require_relative 'module/misc'

data/lib/y_support/core_ext/numeric.rb

@@ -1,2 +1,2 @@
-require 'y_support' unless defined? YSupport
-require File.dirname( __FILE__ ) + '/numeric/misc'
+require_relative '../../y_support'
+require_relative 'numeric/misc'

data/lib/y_support/core_ext/object/inspection.rb

@@ -1,7 +1,13 @@
 class Object
   # Constructs the string "#{self.class}:#{self}". Useful for inspection.
   # 
-  def insp
-    "#{self}:#{self.class}"
+  def y_inspect( option=nil )
+    case option
+    when :full then "#<#{y_inspect}>"
+    when :short then
+      "#{self.class.name.to_s.split( "::" ).last}:#{self}"
+    else
+      "#{self.class}:#{self}"
+    end
   end
 end

data/lib/y_support/core_ext/object.rb

@@ -1,3 +1,3 @@
-require 'y_support' unless defined? YSupport
-require File.dirname( __FILE__ ) + '/object/misc'
-require File.dirname( __FILE__ ) + '/object/inspection'
+require_relative '../../y_support'
+require_relative 'object/misc'
+require_relative 'object/inspection'

data/lib/y_support/core_ext/string/misc.rb

@@ -56,26 +56,23 @@ class String
     gsub ' ', '_'
   end
 
-  # Converts a string into a standard symbol. While Symbol class objects can
-  # be created from any string, it is good practice to keep symbols free of
-  # whitespaces and weird characters, so that the are typed easily, usable as
-  # variable names etc. This method thus removes punctuation, removes
-  # superfluous spaces, and underscores the remaining ones, before returning
-  # the string.
+  # Converts a string into a string suitable as a symbol. Although symbols can
+  # be created from any strings, sometimes it is good to have symbols without
+  # accented characters, punctuation and whitespaces. This method returns a
+  # string of these characteristics.
   # 
   def standardize
-    ς = self.dup
+    ς = self.tr( "ÀÁÂÃÄÅàáâãäåĀāĂ㥹ÇçĆćĈĉĊċČčÐðĎďĐđÈÉÊËèéêëĒēĔĕĖėĘęĚěĜĝĞğĠġĢģĤĥĦħÌÍÎÏìíîïĨĩĪīĬĭĮįİıĴĵĶķĸĹĺĻļĽľĿŀŁłÑñŃńŅņŇňʼnŊŋÒÓÔÕÖØòóôõöøŌōŎŏŐőŔŕŖŗŘřŚśŜŝŞşŠšſŢţŤťŦŧÙÚÛÜùúûüŨũŪūŬŭŮůŰűŲųŴŵÝýÿŶŷŸŹźŻżŽž",
+               "AAAAAAaaaaaaAaAaAaCcCcCcCcCcDdDdDdEEEEeeeeEeEeEeEeEeGgGgGgGgHhHhIIIIiiiiIiIiIiIiIiJjKkkLlLlLlLlLlNnNnNnNnnNnOOOOOOooooooOoOoOoRrRrRrSsSsSsSssTtTtTtUUUUuuuuUuUuUuUuUuUuWwYyyYyYZzZzZz"
+             )
     ",.;".each_char { |c| ς.gsub! c, " " }
-    ς.stripn
-      .squeeze(" ")
-      .underscore_spaces
+    ς.stripn.squeeze(" ").underscore_spaces
   end
 
   # Applies #standardize to the receiver and converts the result to a symbol.
   # 
   def to_standardized_sym
-    standardize
-      .to_sym
+    standardize.to_sym
   end
 
   # Capitalizes a string and appends an exclamation mark. Also allows optional

data/lib/y_support/core_ext/string.rb

@@ -1,2 +1,2 @@
-require 'y_support' unless defined? YSupport
-require File.dirname( __FILE__ ) + '/string/misc'
+require_relative '../../y_support'
+require_relative 'string/misc'

data/lib/y_support/core_ext/symbol.rb

@@ -1,2 +1,2 @@
-require 'y_support' unless defined? YSupport
-require File.dirname( __FILE__ ) + '/symbol/misc'
+require_relative '../../y_support'
+require_relative 'symbol/misc'

data/lib/y_support/core_ext.rb

@@ -1,3 +1,3 @@
 Dir["#{File.dirname( __FILE__ )}/core_ext/*.rb"].sort.each do |path|
-  require "y_support/core_ext/#{File.basename( path, '.rb' )}"
+  require_relative "y_support/core_ext/#{File.basename( path, '.rb' )}"
 end

data/lib/y_support/flex_coerce/class_methods.rb

@@ -0,0 +1,49 @@
+# coding: utf-8
+
+# This module defines class methods, with which the host class of FlexProxy
+# is to be extended.
+# 
+module FlexCoerce::ClassMethods
+  # Class method .coercion_table provides access to the table of coercion
+  # behavior specific to each host class. The table itself is a hash with
+  # method names as keys. Each value is an array of pairs [ type, block ],
+  # where type specifies the operand type, and block specifies the behavior
+  # when the method in question is invoked with the given operand type.
+  # 
+  def coercion_table
+    @coercion_table ||= Hash.new { |hash, missing_key|
+      case missing_key
+      when Symbol then hash[ missing_key ] = []
+      else
+        hash[ missing_key.to_sym ]
+      end
+    }
+  end
+
+  # Class method .define_coercion allows the classes that use FlexCoerce to
+  # define custom coercion for certain symbols. The method expects: (1)
+  # object type (or a list of object types), (2) +:method+ parameter
+  # specifying the method(s) for which coercion is being defined, and (3) a
+  # block that defines the operation. The block should take 2 ordered
+  # arguments, representing first and second operand. The first operand is
+  # the object that invoked #coerce method, the second operand is an
+  # instance of the receiver class. Example:
+  #
+  # define_coercion Integer, method: :* do |operand1, operand2|
+  #   operand2 * operand1 # swap the operands
+  # end
+  # 
+  def define_coercion *types,
+                      method: fail( ArgumentError, "When defining coercion, " +
+                                   "method must be given!" ),
+                      &block
+    unless block.arity == 2
+      fail ArgumentError, "The supplied block, which defines operation" +
+                          "#{method}, must take exactly 2 arguments!"
+    end
+    # For each type, add one line to the coercion_table entry.
+    types.each do |type|
+      coercion_table[ method ] << [ type, block ]
+    end
+  end
+end

data/lib/y_support/flex_coerce/flex_proxy.rb

@@ -0,0 +1,121 @@
+# coding: utf-8
+
+# In FlexCoerce, #coerce method of the host class is made to return a pair
+# [ proxy, receiver ], where proxy is an object of FlexProxy class. As name
+# suggests, proxy represents and wraps argument that has been supplied to
+# #coerce method. This gives the user the opportunity to teach the proxy to
+# correctly respond to various operators (#+, #-, #*, #/,...) and other
+# methods. Instances of FlexProxy are essentially a single-use objects –
+# they respond to a single message, after which their life should end.
+# 
+class FlexCoerce::FlexProxy
+  class << self
+    alias of new # allows statements such as FlexProxy.of( first_operand )
+  end
+    
+  attr_reader :operand
+
+  # Method #host_class is delegated to self.class. It refers to the
+  # host class to which a parametrized subclass of FlexProxy belongs.
+  # 
+  def host_class
+    self.class.host_class
+  end
+    
+  # The constructor of FlexProxy requires only one parameter: The first operand
+  # which has been supplied to #coerce method.
+  # 
+  def initialize first_operand
+    @operand = first_operand
+  end
+
+  # Proxy is essentially a single-use object. In its life, it receives a single
+  # message and returning the result. Unless the user specifically orders
+  # FlexProxy to respond to a method, it should raise TypeError.
+  # 
+  def method_missing ß, arg
+    table_entry = host_class.coercion_table[ ß ]
+    response = table_entry.find { |type, closure| type === operand }
+    fail TypeError, "#{operand.class} not compatible with " +
+                    "#{arg.class} and ##{ß} method!" unless response
+    response[ 1 ].call( operand, arg )
+  end
+
+  # Basic form of Proxy#+ method simply raises TypeError. The user is expected
+  # to override this method as necessary.
+  # 
+  def + arg
+    table_entry = host_class.coercion_table[ :+ ]
+    response = table_entry.find { |type, closure| type === operand } or
+      fail TypeError, "#{arg.class} cannot be added to a #{operand.class}!"
+    response[ 1 ].call( operand, arg )
+  end
+
+  # Basic form of Proxy#- method simply raises TypeError. The user is expected
+  # to override this method as necessary.
+  # 
+  def - arg
+    table_entry = host_class.coercion_table[ :- ]
+    response = table_entry.find { |type, closure| type === operand } or
+      fail TypeError, "#{arg.class} cannot be subtracted " +
+                      "from a #{operand.class}!"
+    response[ 1 ].call( operand, arg )
+  end
+
+  # Basic form of Proxy#* method simply raises TypeError. The user is expected
+  # to override this method as necessary.
+  # 
+  def * arg
+    table_entry = host_class.coercion_table[ :* ]
+    response = table_entry.find { |type, closure| type === operand } or
+      fail TypeError, "#{operand.class} cannot be multiplied " +
+                      "by a #{arg.class}!"
+    response[ 1 ].call( operand, arg )
+  end
+
+  # Basic form of Proxy#/ method simply raises TypeError. The user is expected
+  # to override this method as necessary.
+  # 
+  def / arg
+    table_entry = host_class.coercion_table[ :/ ]
+    response = table_entry.find { |type, closure| type === operand } or
+      fail TypeError, "#{arg.class} cannot be divided by a #{operand.class}!"
+    response[ 1 ].call( operand, arg )
+  end
+
+  # Basic form of Proxy#** method simply raises TypeError. The user is expected
+  # to override this method as necessary.
+  # 
+  def ** arg
+    table_entry = host_class.coercion_table[ :** ]
+    response = table_entry.find { |type, closure| type === operand } or
+      fail TypeError, "#{arg.class} cannot be raised to a #{operand.class}!"
+    response[ 1 ].call( operand, arg )
+  end
+
+  # For less common operators, methods raising TypeError are defined below.
+  # Again, the user is expected to override them whenever necessary.
+  # 
+  [ :%,
+    :div,
+    :divmod,
+    :fdiv,
+    :&,
+    :|,
+    :^,
+    :>,
+    :>=,
+    :<,
+    :<=,
+    :<=>,
+    :=== # Operator === is mostly too liberal to call coerce.
+  ].each do |binary_operator|
+    define_method binary_operator do |arg|
+      table_entry = host_class.coercion_table[ binary_operator ]
+      response = table_entry.find { |type, closure| type === operand } or
+        fail TypeError, "#{arg.class} is not compatible with #{operand.class} " +
+                        "and binary operator ##{binary_operator}"
+      response[ 1 ].call( operand, arg )
+    end
+  end
+end # class FlexCoerce::FlexProxy

data/lib/y_support/flex_coerce/module_methods.rb

@@ -0,0 +1,37 @@
+# coding: utf-8
+
+# This module contains methods with which FlexProxy and modules which include
+# it are to be extended.
+# 
+module FlexCoerce::ModuleMethods
+  # This method customizes the host class in which FlexCoerce is included
+  # by setting up a parametrized subclass of FlexCoerce::FlexProxy and
+  # extending the host class with FlexCoerce::ClassMethods.
+  # 
+  def customize_class host_class
+    host_class.instance_exec do
+      # Set up a parametrized subclass of FlexCoerce::FlexProxy
+      param_class!( { FlexProxy: FlexCoerce::FlexProxy },
+                    with: { host_class: host_class } )
+    end
+    host_class.extend FlexCoerce::ClassMethods
+  end
+
+  # This method customizes a module in which FlexCoerce is included by extending
+  # it with FlexCoerce::ModuleMethods.
+  # 
+  def customize_module host_module
+    host_module.extend FlexCoerce::ModuleMethods
+  end
+
+  # Hook method which is invoked whenever a module is included in another module
+  # (or class, which is also a module).
+  # 
+  def included receiver
+    if receiver.is_a? Class then # we have reached the host class
+      customize_class( receiver )
+    else # receiver is a Module
+      customize_module( receiver )
+    end
+  end
+end

data/lib/y_support/flex_coerce.rb

@@ -0,0 +1,24 @@
+# coding: utf-8
+
+require_relative 'core_ext/object'
+
+module FlexCoerce
+  require_relative 'flex_coerce/flex_proxy'
+  require_relative 'flex_coerce/class_methods'
+  require_relative 'flex_coerce/module_methods'
+
+  extend FlexCoerce::ModuleMethods
+
+  # Method #FlexProxy is delegated to the host class, it returns the
+  # parametrized subclass of FlexCoerce::FlexProxy specific to the host class.
+  # 
+  def FlexProxy
+    self.class.FlexProxy
+  end
+
+  # FlexCoerce provides coerce method that returns a proxy object and self.
+  # 
+  def coerce first_operand
+    return FlexProxy().of( first_operand ), self
+  end
+end

data/lib/y_support/kde.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-require 'y_support'
+require_relative '../y_support'
 
 module YSupport::KDE
   class << self