y_support 1.0.0

data/lib/y_support/typing/enumerable/typing.rb

@@ -0,0 +1,75 @@
+#encoding: utf-8
+
+module Enumerable
+  # Fails with TypeError unless all the members of the collection comply with
+  # the supplied block criterion. Optional arguments customize the error
+  # message. First optional argument describes the collection element, the
+  # second one describes the tested duck type. If the criterion block takes
+  # at least one argument, the receiver elemnts are passed to it (#all?
+  # method). If the criterion block takes no arguments (arity 0), it is
+  # gradually executed inside the elements (using #instance_exec method).
+  # If no block is given, all members are required to be truey.
+  # 
+  def aT_all what_is_collection_element=nil, how_comply=nil, &b
+    e = what_is_collection_element || "collection element"
+    if block_given?
+      m = "Each #{e} must %s!" %
+        ( how_comply ? how_comply : "comply with the given duck type" )
+      raise TErr, m unless ( b.arity == 0 ?
+                             all? { |e| e.instance_exec( &b ) } :
+                             all? { |e| b.( e ) } )
+    else
+      m = "No #{e} must be nil or false!"
+      raise TErr, m unless all? { |e| e }
+    end
+    return self
+  end
+
+  # Fails with TypeError unless all collection members are #kind_of? the
+  # class supplied as argument. Second optional argument (collection element
+  # description) customizes the error message.
+  # 
+  def aT_all_kind_of klass, what_is_collection_element=nil
+    e = what_is_collection_element || "collection element"
+    m = "Each #{e} must be kind of #{klass}!"
+    raise TErr, m unless all? { |e| e.kind_of? klass }
+    return self
+  end
+
+  # Fails with TypeError unless all collection members declare compliance with
+  # compliance with the class supplied as argument. Second optional argument
+  # (collection element description) customizes the error message.
+  # 
+  def aT_all_comply klass, what_is_collection_element=nil
+    e = what_is_collection_element || "collection element"
+    m = "Each #{e} must declare compliance to #{klass}!"
+    raise TErr, m unless all? { |e| e.class_complies? klass }
+    return self
+  end
+  
+  # Fails with TypeError unless all the collection members declare compliance
+  # with Numeric. Second optional argument (collection element description)
+  # customizes the error message.
+  # 
+  def aT_all_numeric what_is_collection_element=nil
+    e = what_is_collection_element || "collection element"
+    m = "Each #{e} must declare compliance with Numeric!"
+    raise TErr, m unless all? { |e| e.class_complies? Numeric }
+    return self
+  end
+  
+  # Fails with TypeError unless all the collection members are included int the
+  # collection supplied as argument. Second optional argument (collection
+  # element description) customizes the error message.
+  # 
+  def aT_subset_of other_collection, what_is_receiver_collection=nil,
+                   what_is_other_collection=nil
+    rc = what_is_receiver_collection ?
+      what_is_receiver_collection.to_s.capitalize : "collection"
+    oc = what_is_other_collection ? what_is_other_collection.to_s.capitalize :
+      "the specified collection"
+    m = "The #{rc} must be a subset of #{oc}"
+    raise TErr, m unless all? { |e| other_collection.include? e }
+    return self
+  end
+end

data/lib/y_support/typing/enumerable.rb

@@ -0,0 +1 @@
+require 'y_support/core_ext/enumerable/typing'

data/lib/y_support/typing/hash/typing.rb

@@ -0,0 +1,76 @@
+#encoding: utf-8
+
+class Hash
+  # Merges the synonymous hash keys into a single key - useful for argument
+  # validation. Returns nil if neither main key, nor synonyms are found.
+  # Returns false (no merging) if the main key was found, but no synonym keys.
+  # Returns true (yes merging) if any of the synonym keys is found and
+  # renamed/merged to the main key. Value collisions in synonym keys (detected
+  # by #==) raise ArgumentError.
+  # 
+  def merge_synonym_keys!( key, *synonyms )
+    synonyms.reduce has_key?( key ) ? false : nil do |acc, syn|
+      next acc unless has_key? syn
+      if acc.nil? then
+        self[key] = self[syn]
+        delete syn
+        next true
+      end
+      if self[key] == self[syn] then
+        delete syn
+        next true
+      else
+        raise TErr, "Value collision between #{key} and its synonym #{syn}!"
+      end
+    end
+  end
+  
+  # This method uses #merge_synonym_keys! method first and then returns the
+  # value under the key. The first argument is the main key. Synonyms may be
+  # supplied as a named argument :syn!. (Bang indicates that the synonym keys
+  # will be merged with the main key, modifying the hash.)
+  # 
+  def may_have key, options={}
+    merge_synonym_keys!( key, *options[:syn!] ).nil?
+    return self[key]
+  end
+
+  # This method behaves similarly to #may_have, with the difference that it
+  # does not return the value of the key, only true / false to indicate whether
+  # the key or any synonym has been found.
+  # 
+  def has? key, options={}
+    !merge_synonym_keys!( key, *options[:syn!] ).nil?
+  end
+  
+  # This enforcer method (aka. runtime assertion) raises TypeError when:
+  # 1. Neither the required key nor any of its synonyms are present.
+  # 2. The supplied criterion block, if any, returns false when applied
+  # to the value of the key in question. If the block takes an argument
+  # (or more arguments), the value is passed in. If the block takes no
+  # arguments (arity 0), it is executed inside the singleton class of the
+  # receiver (using #instance_exec method).
+  # 
+  def aT_has key, options={}, &b
+    raise TErr, "Key '#{key}' absent!" unless has? key, options
+    # Now validate self[key] using the supplied block
+    if block_given?
+      m = "Value for #{key} fails its duck type!"
+      raise TErr, m unless ( b.arity == 0 ? self[key].instance_exec( &b ) :
+                               b.( self[key] ) )
+    end
+    return self[key]
+  end
+  alias :must_have :aT_has
+
+  # This method behaves exactly like #aT_has, but with the difference, that
+  # it raises ArgumentError instead of TypeError
+  # 
+  def aE_has key, options={}, &b
+    begin
+      options.empty? ? aT_has( key, &b ) : aT_has( key, options, &b )
+    rescue TypeError => e
+      raise AErr, e.message
+    end
+  end
+end

data/lib/y_support/typing/hash.rb

@@ -0,0 +1 @@
+require 'y_support/core_ext/hash/typing'

data/lib/y_support/typing/module/typing.rb

@@ -0,0 +1,42 @@
+#encoding: utf-8
+
+class Module
+  # === Support for typing by declaration
+
+  # Compliance inquirer (declared compliance + ancestors).
+  # 
+  def complies?( other_module )
+    other_module.aT_kind_of Module, "other module"
+    compliance.include? other_module
+  end
+
+  # Declared complience inquirer.
+  # 
+  def declares_compliance?( other_module )
+    other_module.aT_kind_of Module, "other module"
+    declared_compliance.include? other_module
+  end
+
+  # Compliance (declared compliance + ancestors).
+  # 
+  def compliance
+    ( declared_compliance + ancestors ).uniq
+  end
+
+  # Declared compliance getter.
+  # 
+  def declared_compliance
+    ( ( @declared_compliance || [] ) + ancestors.map { |a|
+        a.instance_variable_get( :@declared_compliance ) || []
+      }.reduce( [], :+ ) ).uniq
+  end
+
+  # Declaration of module / class compliance.
+  # 
+  def declare_compliance! other_module
+    other_module.aT_kind_of Module, "other module"
+    return false if declared_compliance.include? other_module
+    ( @declared_compliance ||= [] ) << other_module
+    return true
+  end
+end

data/lib/y_support/typing/module.rb

@@ -0,0 +1 @@
+require 'y_support/core_ext/module/typing'

data/lib/y_support/typing/object/typing.rb

@@ -0,0 +1,178 @@
+#encoding: utf-8
+
+require 'active_support/core_ext/object/blank'
+
+class Object
+  # === Support for typing by declaration
+
+  # Class compliance inquirer (declared compliance + class ancestors).
+  # 
+  def class_complies?( klass )
+    singleton_class_or_class.complies? klass
+  end
+
+  # Declared class compliance.
+  # 
+  def class_declares_compliance?( klass )
+    singleton_class_or_class.declares_compliance? klass
+  end
+
+  # Class compliance (declared class compliance + ancestors).
+  # 
+  def class_compliance
+    singleton_class_or_class.compliance
+  end
+
+  # Declared class compliance.
+  # 
+  def declared_class_compliance
+    singleton_class_or_class.declared_compliance
+  end
+
+  # Declaration of class compliance.
+  # 
+  def declare_class_compliance!( klass )
+    singleton_class_or_class.declare_compliance! klass
+  end
+
+  # === Duck typing support (aka. runtime assertions)
+
+  # This method takes a block and fails with TypeError, unless the receiver
+  # fullfills the block criterion. Optional arguments customize customize
+  # the error message. First optional argument describes the receiver, the
+  # second one describes the tested duck type. If the criterion block takes
+  # at least one argument, the receiver is passed to it. If the criterion block
+  # takes no arguments (arity 0), it is executed inside the singleton class of
+  # the receiver (using #instance_exec method). If no block is given, it is
+  # checked, whether the object is truey.
+  # 
+  def aT what_is_receiver=nil, how_comply=nil, &b
+    r = what_is_receiver ? what_is_receiver.to_s.capitalize :
+      "#{self.class} instance #{object_id}"
+    if block_given?
+      m = "#{r} fails #{how_comply ? 'to %s' % how_comply : 'its duck type'}!"
+      raise TErr, m unless ( b.arity == 0 ) ? instance_exec( &b ) : b.( self )
+    else
+      raise TErr, m unless self
+    end
+    return self
+  end
+  
+  # This method takes a block and fails with TypeError, unless the receiver
+  # causes the supplied block <em>to return falsey value</em>. Optional arguments
+  # customize customize the error message. First optional argument describes the
+  # receiver, the second one describes the tested duck type. If the criterion
+  # block takes at least one argument (or more arguments), the receiver is passed
+  # to it. If the criterion block takes no arguments (arity 0), it is executed
+  # inside the singleton class of the receiver (using #instance_exec method). If
+  # no block is given, it is checked, whether the object is falsey.
+  # 
+  def aT_not what_is_receiver=nil, how_comply=nil, &b
+    r = what_is_receiver ? what_is_receiver.to_s.capitalize :
+      "#{self.class} instance #{object_id}"
+    if block_given?
+      m = how_comply ? "#{r} must not #{how_comply}!" :
+        "#{r} fails its duck type!"
+      raise TErr, m if ( b.arity == 0 ) ? instance_exec( &b ) : b.( self )
+    else
+      m = "#{r} is not falsey!"
+      raise TErr, m if self
+    end
+    return self
+  end
+
+  # Fails with TypeError unless the receiver is of the prescribed class. Second
+  # optional argument customizes the error message (receiver description).
+  # 
+  def aT_kind_of klass, what_is_receiver=nil
+    r = what_is_receiver ? what_is_receiver.to_s.capitalize :
+      "#{self.class} instance #{object_id}"
+    m = "#{r} is not a kind of #{klass}!"
+    raise TErr, m unless kind_of? klass
+    return self
+  end
+  alias :aT_is_a :aT_kind_of
+
+  # Fails with TypeError unless the receiver declares compliance with the
+  # given class, or is a descendant of that class. Second optional argument
+  # customizes the error message (receiver description).
+  # 
+  def aT_class_complies klass, what_is_receiver=nil
+    r = what_is_receiver ? what_is_receiver.to_s.capitalize :
+      "#{self.class} instance #{object_id}"
+    m = "#{r} does not comply or declare compliance with #{klass}!"
+    raise TErr, m unless class_complies? klass
+    return self
+  end
+  
+  # Fails with TypeError unless the receiver responds to the given
+  # method. Second optional argument customizes the error message (receiver
+  # description).
+  # 
+  def aT_respond_to method_name, what_is_receiver=nil
+    r = what_is_receiver ? what_is_receiver.to_s.capitalize :
+      "#{self.class} instance #{object_id}"
+    m = "#{r} does not respond to method '#{method_name}'!"
+    raise TErr, m unless respond_to? method_name
+    return self
+  end
+  alias :aT_responds_to :aT_respond_to
+  
+  # Fails with TypeError unless the receiver, according to #== method, is
+  # equal to the argument. Two more optional arguments customize the error
+  # message (receiver description and the description of the other object).
+  # 
+  def aT_equal other, what_is_receiver=nil, what_is_other=nil
+    r = what_is_receiver ? what_is_receiver.to_s.capitalize :
+      "#{self.class} instance #{object_id}"
+    o = what_is_other || "the prescribed value (#{other.class})"
+    m = "#{r} is not equal (==) to #{o}!"
+    raise TErr, m unless self == other
+    return self
+  end
+
+  # Fails with TypeError unless the receiver, according to #== method, differs
+  # from to the argument. Two more optional arguments customize the error
+  # message (receiver description and the description of the other object).
+  # 
+  def aT_not_equal other, what_is_receiver=nil, what_is_other=nil
+    r = what_is_receiver ? what_is_receiver.to_s.capitalize :
+      "#{self.class} instance #{object_id}"
+    o = what_is_other || "the prescribed value (#{other.class})"
+    m = "#{r} fails to differ from #{o}!"
+    raise TErr, m if self == other
+    return self
+  end
+
+  # Fails with TypeError unless the ActiveSupport method #blank returns true
+  # for the receiver.
+  # 
+  def aT_blank what_is_receiver=nil
+    r = what_is_receiver ? what_is_receiver.to_s.capitalize :
+      "#{self.class} instance #{object_id}"
+    m = "#{r} fails to be #blank?!"
+    raise TErr, m unless blank?
+    return self
+  end
+
+  # Fails with TypeError unless the ActiveSupport method #present returns true
+  # for the receiver.
+  # 
+  def aT_present what_is_receiver=nil
+    r = what_is_receiver ? what_is_receiver.to_s.capitalize :
+      "#{self.class} instance #{object_id}"
+    m = "#{r} fails to be #present?!"
+    raise TErr, m unless present?
+    return self
+  end
+
+  private
+
+  def singleton_class_or_class
+    begin
+      self.singleton_class
+    rescue TypeError
+      self.class
+    end
+  end
+end

data/lib/y_support/typing/object.rb

@@ -0,0 +1 @@
+require 'y_support/core_ext/object/typing'

data/lib/y_support/typing.rb

@@ -0,0 +1,43 @@
+#encoding: utf-8
+
+require 'y_support'
+
+# Typing library.
+#
+# Apart from Ruby default way of typing objects <em>by class and ancestry</em>,
+# exemplified eg. by built-in #kind_of?, alias #is_a? inquirers, y_support
+# typing library provides support for typing <em>by declaration</em>, and
+# runtime assertions for <em>duck type</em> examination.
+# 
+# 1. Using method <b>declare_compliance</b>, a module (class) can explicitly
+# declare, that it provides an interface compliant with another module (class).
+# Corresponding inquirer methods are <b>declared_compliance</b> (returns a list
+# of modules, to which the receiver declares compliance, or implicitly complies
+# by ancestry), and <b>declares_compliance?( other_module )</b>, which tells,
+# whether the receiver complies with a specific module. An object always
+# implicitly complies with its class and ancestry.
+# 
+# 2. Duck type examination is supported by a collection of runtime assertions.
+# These start with <b>tE_...</b>, meaning "enforce ... by raising TypeError".
+# 
+class Object
+  # Alias for ArgumentError
+  # 
+  AErr = ArgumentError
+  
+  # Alias for TypeError
+  # 
+  TErr = TypeError
+end
+
+directories_to_look_in = [ :typing ]
+
+# The fololowing code looks into the specified directory(ies) and requires
+# all the files in it (them).
+# 
+directories_to_look_in.each do |part|
+  Dir["#{File.dirname( __FILE__ )}/#{part}/*/typing.rb"].sort.each { |path|
+    dir = File.dirname( path ).match( "y_support/#{part}" ).post_match
+    require "y_support/#{part}#{dir}/typing"
+  }
+end

data/lib/y_support/unicode.rb

@@ -0,0 +1,76 @@
+#encoding: utf-8
+
+require 'y_support'
+
+# This library sets forth 4 standard abbreviations of Ruby keywords:
+#
+# * <b>ç</b> – class (c with cedilla, U00E7, compose seq. [c, comma])
+# * <b>ⓒ</b> – singleton class (copyright sign, U00A9, compose seq. [(, c, )])
+# * <b>λ</b> – lambda (Greek character lambda)
+# * <b>Λ</b> – proc (Greek character capital lambda)
+#
+# It is also encouraged that other on-letter Unicode abbreviations are
+# used especially for local variables:
+# 
+# * <b>ɱ</b> – module (m with hook, U2C6E, compose seq. [m, j])
+# * <b>ꜧ</b> – hash (latin small letter heng, UA727, compose seq. [h, j])
+# * <b>ᴀ</b> – array (small capital A, U1D00, compose seq. [a, `])
+# * <b>ß</b> – symbol (German sharp s, U00DF, compose seq. [s, s])
+# * <b>ς</b> – string (Greek final sigma, U03C2, compose seq. [*, w])
+# * <b>w</b> – abbreviation for "with"
+# * <b>wo</b> – abbreviation for "without"
+# 
+# There are, however, no defined methods using these in YSupport. In other
+# words, using these additional abbreviations is completely up to the goodwill
+# of the developer.
+#
+# ==== Note on compose sequences
+# 
+# Each compose sequence has to be preceded by pressing the <compose> key.
+# The compose sequences comply with the standard Kragen's .XCompose file
+# (https://github.com/kragen/xcompose). In some cases, the needed characters
+# are not in Kragen's file and need to be defined manually.
+# 
+class Object
+  alias :ç :class
+  alias :ⓒ :singleton_class
+  alias :© :singleton_class
+
+  # Square root (proxy for Math.sqrt(x)).
+  # 
+  def √( number ); Math.sqrt( number ) end
+
+  # Sum. The argument is expected to be a collection; block can be specified.
+  # Basically same as chaining .reduce( :+ ) to the end; Σ() notation can be
+  # more readable at times.
+  # 
+  def ∑( collection )
+    collection.reduce { |acc, element|
+      acc + ( block_given? ? yield( element ) : element )
+    }
+  end
+  alias :Σ :∑
+
+  # Product. The argument is expected to be a collection; block can be specified.
+  # Basically same as chaining .reduce( :* ) to the end; Π() notation can be
+  # more readable at times.
+  # 
+  def ∏( collection )
+    collection.reduce { |acc, element|
+      acc * ( block_given? ? yield( element ) : element )
+    }
+  end
+  alias :Π :∏
+end
+
+class Module
+  alias :ç_variable_set :class_variable_set
+  alias :ç_variable_get :class_variable_get
+  alias :ç_variable_defined? :class_variable_defined?
+  alias :remove_ç_variable :remove_class_variable
+end
+
+module Kernel
+  alias :λ :lambda
+  alias :Λ :proc
+end

data/lib/y_support/version.rb

@@ -0,0 +1,3 @@
+module YSupport
+  VERSION = "1.0.0"
+end

data/lib/y_support.rb

@@ -0,0 +1,33 @@
+#encoding: utf-8
+
+require "y_support/version"
+
+# What follows is a commented-out list of interesting StdLibs. They may
+# or may no be required in various parts of y_support.
+# 
+# require 'matrix' # in stdlib_ext/matrix/misc.rb
+# require 'mathn'
+# require 'set'
+# require 'csv'
+
+# What follows is a commented-out list of interesting ActiveSupport parts.
+# These may or may not be required in various parts of y_support.
+# 
+# require 'active_support/core_ext/module/delegation'
+# require 'active_support/core_ext/object/blank' # in object/misc.rb, string/misc.rb
+# require 'active_support/core_ext/object/duplicable'
+# require 'active_support/core_ext/string/starts_ends_with'
+# require 'active_support/core_ext/string/strip'
+# require 'active_support/core_ext/string/inflections' # in autoreq; module/misc.rb
+# require 'active_support/core_ext/integer/multiple'
+# require 'active_support/core_ext/integer/inflections'
+# require 'active_support/core_ext/enumerable'
+# require 'active_support/core_ext/array/extract_options' 
+# require 'active_support/core_ext/hash/conversions' # such as #to_xml
+# require 'active_support/core_ext/hash/reverse_merge' # aliased in hash/misc.rb
+# require 'active_support/core_ext/hash/deep_merge'
+# require 'active_support/core_ext/hash/diff'
+# require 'active_support/core_ext/hash/except'
+# require 'active_support/core_ext/hash/keys'
+# require 'active_support/core_ext/hash/slice'
+# require 'active_support/core_ext/hash/indifferent_access'

data/test/inert_recorder_test.rb

@@ -0,0 +1,34 @@
+#! /usr/bin/ruby
+#encoding: utf-8
+
+require 'test/unit'
+require 'shoulda'
+
+class YSupportTest < Test::Unit::TestCase
+  context "Object" do
+    setup do
+      require 'y_support/inert_recorder'
+    end
+
+    should "have #InertRecorder() constructor" do
+      assert_equal InertRecorder, InertRecorder( :bull ).class
+    end
+  end # context Object
+  
+  context "InertRecorder" do
+    setup do
+      require 'y_support/inert_recorder'
+    end
+
+    should "InertRecorder exist and comply" do
+      n = InertRecorder.new
+      assert_equal [true, false], [n.present?, n.blank?]
+      assert_respond_to InertRecorder.new, :arbitrary_message
+      n = InertRecorder.new :x, :y
+      n.arbitrary_message( :a, :b ) { "hello" }
+      assert_equal [:x, :y], n.init_args
+      assert_equal [ :arbitrary_message, [:a, :b] ], n.recorded_messages[0][0..1]
+      assert_equal "hello", n.recorded_messages[0][2].call
+    end
+  end # context InertRecorder
+end # class InertRecorderTest

data/test/local_object_test.rb

@@ -0,0 +1,37 @@
+#! /usr/bin/ruby
+#encoding: utf-8
+
+require 'test/unit'
+require 'shoulda'
+
+class LocalObjectTest < Test::Unit::TestCase
+  context "Object" do
+    setup do
+      require 'y_support/local_object'
+    end
+
+    should "have constructor #LocalObject, alias #L!" do
+      assert_equal LocalObject, LocalObject().class
+      assert_equal LocalObject, L!.class
+    end
+
+    should "have #local_object?, alias #ℓ?" do
+      assert_equal false, Object.new.local_object?
+      assert_equal false, Object.new.ℓ?
+    end
+  end # context Object
+  
+  context "LocalObject" do
+    setup do
+      require 'y_support/local_object'
+    end
+
+    should "exist and comply" do
+      n = LocalObject.new 'whatever'
+      assert ! n.ℓ?
+      assert n.ℓ? 'whatever'
+      assert_equal 'whatever', n.signature
+      assert_equal 'whatever', n.σ
+    end
+  end # context LocalObject
+end # class LocalObjectTest

data/test/misc_test/test_module/fixture_class.rb

@@ -0,0 +1,8 @@
+class MiscTest
+  module TestModule
+    class FixtureClass
+      def hello; "world" end
+    end
+  end
+end
+