y_support 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 39372bbe12e6643f53e78e2b4fd8666477554a67
+  data.tar.gz: 9d1c8f648ab7369104ba1ca178fe6ca4abec4cf7
+SHA512:
+  metadata.gz: 7e3457d0f805683af3c83018bb7174b161868f614a77b90e7ecc022937ec9b4768fbbfc904717b97beb71dbe0f96296cac46fe60f52db06f89c80c9afa5ce755
+  data.tar.gz: 8a57a47dcb40f4c286ffcdf3ad19c0ccd3cd6a58bb32f7d32861701c6907c4734db0eb6e72b6490afcf43e8c2797b0661fda1e7166ed15267736729d45fb06b8

data/.gitignore

@@ -0,0 +1,20 @@
+*~
+.#*
+\#*#
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in y_support.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 boris
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,29 @@
+# YSupport
+
+Common support library for Y* gems.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'y_support'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install y_support
+
+## Usage
+
+Require 'y_support/all', or require 'y_support/something', and use it.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/y_support/all.rb

@@ -0,0 +1,40 @@
+#encoding: utf-8
+
+require 'y_support'
+require 'y_support/name_magic'
+require 'y_support/typing'
+require 'y_support/unicode'
+require 'y_support/respond_to'
+require 'y_support/null_object'
+require 'y_support/inert_recorder'
+require 'y_support/local_object'
+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/misc.rb

@@ -0,0 +1,45 @@
+class Array
+  # Converts an array, whose elements are also arrays, to a hash.  Head
+  # (position 0) of each array is made to point at the rest of the array
+  # (tail), normally starting immediately after the head (position 1). The
+  # starting position of the tail can be controlled by an optional
+  # argument. Tails of 2 and more elements are represented as arrays.
+  # 
+  def to_hash( tail_from = 1 )
+    self.reject { | e | e[0].nil? }.reduce({}) { |a, e|
+      tail = e[tail_from..-1]
+      a.merge( { e[0] => tail.size >= 2 ? tail : tail[0] } )
+    }
+  end
+  
+  # Does things for each consecutive pair (expects a binary block).
+  # 
+  def each_consecutive_pair
+    if block_given?
+      return self if ( n = self.size - 1 ) <= 0
+      n.times.with_index{|i| yield( self[i], self[i+1] ) }
+      return self
+    else
+      return Enumerator.new do |yielder|
+        n.times.with_index{|i| yielder << [ self[i], self[i+1] ] } unless
+          ( n = self.size - 1 ) <= 0
+      end
+    end
+  end
+  
+  # Allows style &[ function, *arguments ]
+  # 
+  def to_proc
+    proc { |receiver| receiver.send *self }
+  end # def to_proc
+  
+  # TEST ME
+  # def pretty_inspect
+  #   each_slice( 4 ) { |slice|
+  #     slice.map { |e|
+  #       str = e.to_s[0..25]
+  #       str + ' ' * ( 30 - str.size )
+  #     }.reduce( :+ ) + "\n"
+  #   }.reduce( :+ )
+  # end
+end

data/lib/y_support/core_ext/array.rb

@@ -0,0 +1 @@
+require 'y_support/core_ext/array/misc'

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

@@ -0,0 +1,32 @@
+#encoding: utf-8
+
+module Enumerable
+  # Checks whether #all? collection elements are #kind_of? module
+  # supplied as an argument
+  # 
+  def all_kind_of?( kind )
+    all? {|e| e.kind_of? kind }
+  end
+  
+  # Checks whether #all? collection elements are #kind_of? Numeric.
+  # 
+  def all_numeric?
+    all? {|e| e.kind_of? Numeric }
+  end
+  
+  # Checks whether the receiver collection is fully included in the
+  # collection supplied as an argument.
+  # 
+  def subset_of?( other_collection )
+    all? {|e| other_collection.include? e }
+  end
+  alias :⊂? :subset_of?
+  
+  # Checks whether the receiver collection contains every element of
+  # the collection supplied as an argument.
+  # 
+  def superset_of?( other_collection )
+    other.all? {|e| self.include? e }
+  end
+  alias :⊃? :superset_of?
+end

data/lib/y_support/core_ext/enumerable.rb

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

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

@@ -0,0 +1,90 @@
+#encoding: utf-8
+
+require 'active_support/core_ext/hash/reverse_merge'
+
+class Hash
+  # reversed merge!: defaults.merge( self! )
+  alias :default! :reverse_merge!
+  
+  # Applies a block as a mapping on all keys, returning a new hash
+  def with_keys
+    keys.each_with_object self.class.new do |hash_key, ꜧ|
+      ꜧ[ yield( hash_key ) ] = self[ hash_key ]
+    end
+  end
+  alias :do_with_keys :with_keys
+  
+  # The difference from do_with_keys is that modify_keys expects block
+  # that takes 2 arguments (key: value pair) and returns the new key.
+  def modify_keys
+    each_with_object self.class.new do |hash_pair, ꜧ|
+      ꜧ[ yield( hash_pair ) ] = self[ hash_pair[0] ]
+    end
+  end
+  
+  # Applies a block as a mapping on all values, returning a new hash
+  def with_values
+    each_with_object self.class.new do |hash_pair, ꜧ|
+      ꜧ[ hash_pair[0] ] = yield( hash_pair[1] )
+    end
+  end
+  alias :do_with_values :with_values
+  
+  # Like #do_with_values, but modifies the receiver.
+  def with_values!
+    each_with_object self do |hash_pair, ꜧ|
+      hash_key, hash_val = hash_pair
+      ꜧ[ hash_key ] = yield( hash_val )
+    end
+  end
+  alias :do_with_values! :with_values!
+  
+  # The difference from #do_with_values is that modify_values expects block
+  # that takes 2 arguments (key: value pair) and returns the new value.
+  def modify_values
+    each_with_object self.class.new do |hash_pair, ꜧ|
+      ꜧ[ hash_pair[0] ] = yield( hash_pair )
+    end
+  end
+  
+  # Like #modify_values, but modifies the receiver
+  def modify_values!
+    each_with_object self do |hash_pair, ꜧ|
+      ꜧ[ hash_pair[0] ] = yield( hash_pair )
+    end
+  end
+  
+  # Like #map that returns a hash.
+  def modify
+    each_with_object self.class.new do |hash_pair, ꜧ|
+      key, val = yield hash_pair
+      ꜧ[key] = val
+    end
+  end
+  
+  # Makes hash keys accessible as methods. If the hash keys collide with
+  # its methods, ArgumentError is raised, unless :overwrite_methods
+  # option == true.
+  # 
+  def dot!( oo = {} )
+    keys.each do |key|
+      msg = "key #{key} of #dot!-ted hash is not convertible to a symbol"
+      raise ArgumentError, msg unless key.respond_to? :to_sym
+      unless oo[:overwrite_methods]
+        if methods.include? key.to_sym
+          raise ArgumentError, "#dot!-ted hash must not have key names " +
+            "colliding with its methods"
+        end
+      end
+      
+      define_singleton_method key.to_sym do
+        self[key]
+      end
+      
+      define_singleton_method "#{key}=".to_sym do |value|
+        self[key] = value
+      end
+    end
+    return self
+  end
+end

data/lib/y_support/core_ext/hash.rb

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

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

@@ -0,0 +1,43 @@
+#encoding: utf-8
+
+class Module
+  # Further automation of soon-to-be-deprecated #autorequire.
+  # 
+  def autoreq( *symbols, descending_path: '..', ascending_path_prefix: 'lib' )
+
+    require 'active_support/core_ext/string/inflections'
+
+    namespace = self.name
+    namespace_path = namespace.underscore
+    namespace_chain = namespace.split "::"
+    ascending_path = ascending_path_prefix + '/' + namespace_path
+    symbols.map( &:to_s ).each { |ς|
+      next if ς.strip.empty?
+      camelized_ß = ς.camelize.to_sym
+      path = './' + [ descending_path, ascending_path, ς ].join( '/' )
+      autoload camelized_ß, path
+    }
+  end
+  
+  # I didn't write this method by myself.
+  # 
+  def attr_accessor_with_default *symbols, &block
+    raise ArgumentError, 'Block with default value required!' unless block
+    symbols.each { |ß|
+      module_eval {
+        define_method "#{ß}=" do |arg|
+          instance_variable_set "@#{ß}", arg
+        end
+        define_method ß do
+          singleton_class.class_eval { attr_reader ß }
+          if instance_variables.include? "@#{ß}".to_sym then
+            instance_variable_get "@#{ß}"
+          else
+            instance_variable_set "@#{ß}", block.call
+          end
+        end
+      }
+    }
+  end
+  alias :attr_accessor_w_default :attr_accessor_with_default
+end

data/lib/y_support/core_ext/module.rb

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

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

@@ -0,0 +1,13 @@
+#encoding: utf-8
+
+class << Integer
+  def zero; 0 end
+end
+
+class << Float
+  def zero; 0.0 end
+end
+
+class << Complex
+  def zero; Complex 0, 0 end
+end

data/lib/y_support/core_ext/numeric.rb

@@ -0,0 +1 @@
+require 'y_support/core_ext/numeric/misc'

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

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+class Object
+  def const_set_if_not_defined( const, value )
+    mod = self.is_a?(Module) ? self : self.singleton_class
+    mod.const_set( const, value ) unless mod.const_defined?( const )
+  end
+
+  def const_redefine_without_warning( const, value )
+    mod = self.is_a?(Module) ? self : self.singleton_class
+    mod.send(:remove_const, const) if mod.const_defined?( const )
+    mod.const_set( const, value )
+  end
+
+  # Create public attributes (ie. with readers) and initialize them with
+  # prescribed values. Takes a hash of { symbol => value } pairs. Existing methods
+  # are not overwritten by the new getters, unless option :overwrite_methods
+  # is set to true.
+  def singleton_set_attr_with_readers( hash, oo = {} )
+    hash.each { |key, val|
+      key = key.aE_respond_to( :to_sym, "key of the attr hash" ).to_sym
+      instance_variable_set( "@#{key}", val )
+      if oo[:overwrite_methods] then ⓒ.module_exec { attr_reader key }
+      elsif methods.include? key
+        raise "Attempt to add \##{key} getter failed: " +
+          "method \##{key} already defined."
+      else ⓒ.module_exec { attr_reader key } end
+    }
+  end
+  alias :ⓒ_set_attr_w_readers :singleton_set_attr_with_readers
+end

data/lib/y_support/core_ext/object.rb

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

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

@@ -0,0 +1,80 @@
+#encoding: utf-8
+
+require 'active_support/core_ext/object/blank'
+
+class String
+  # Integer() style conversion, or false if conversion impossible.
+  # 
+  def to_Integer
+    begin
+      int = Integer stripn
+      return int
+    rescue ArgumentError
+      return false
+    end
+  end
+  
+  # Float() style conversion, or false if conversion impossible.
+  # 
+  def to_Float
+    begin
+      fl = Float stripn
+      return fl
+    rescue ArgumentError
+      return false
+    end
+  end
+  
+  # Like #strip, but also strips newlines.
+  # 
+  def stripn
+    encode( universal_newline: true )
+      .gsub("\n", "")
+      .strip
+  end
+  
+  # Joins a paragraph of possibly indented, newline separated lines into a
+  # single contiguous string.
+  # 
+  def wring_heredoc
+    encode(universal_newline: true)
+      .split("\n")                   # split into lines
+      .map( &:strip )                # strip them
+      .delete_if( &:blank? )         # delete blank lines
+      .join " "                      # and join with whitspace
+  end
+  
+  # If the string is empty, it gets replace with the string given as argument.
+  # 
+  def default! default_string
+    strip.empty? ? clear << default_string.to_s : self
+  end
+  
+  # As it says – replaces spaces with underscores.
+  # 
+  def underscore_spaces
+    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.
+  # 
+  def standardize
+    ς = self.dup
+    ",.;".each_char { |c| ς.gsub! c, " " }
+    ς.stripn
+      .squeeze(" ")
+      .underscore_spaces
+  end
+  
+  # Applies #standardize to the receiver and converts the result to a symbol.
+  # 
+  def to_standardized_sym
+    standardize
+      .to_sym
+  end
+end

data/lib/y_support/core_ext/string.rb

@@ -0,0 +1 @@
+require 'y_support/core_ext/string/misc'

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

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+class Symbol
+  # This method applies String#default! method to the receiver converted to
+  # a string. Of course, symbols are immutable, so in spite of the exclamation
+  # mark in the method name, a new symbol (supplied as argument) is returned,
+  # if the original one is considered "defaulted" (otherwise, original symbol
+  # is returned unchanged).
+  # 
+  def default! default_symbol
+    to_s.default!( default_symbol ).to_sym
+  end
+  
+  # Applies String#to_standardized_sym method to the recevier converted to a
+  # string.
+  # 
+  def to_standardized_sym
+    to_s.to_standardized_sym
+  end
+end

data/lib/y_support/core_ext/symbol.rb

@@ -0,0 +1 @@
+require 'y_support/core_ext/symbol/misc'

data/lib/y_support/core_ext.rb

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

data/lib/y_support/inert_recorder.rb

@@ -0,0 +1,51 @@
+#encoding: utf-8
+
+require 'y_support'
+
+# Inert recorder is similar to a null object in the sense, that in response to
+# almost all messages it returns self. But in addition, it records received
+# messages along with their arguments and blocks (if given). Recoded messages
+# are available via #recorded_messages reader, aliased #ρ (small Greek rho).
+# Inert recorder does not require any arguments for initalization, but if they
+# are supplied, they are silently recoded into @init_args (for arguments) and
+# @init_block (for block, if given) instance variables, exposed via standard
+# readers.
+# 
+class InertRecorder
+  attr_reader :init_args, :init_block, :recorded_messages
+  alias ρ recorded_messages
+
+  # No arguments are required for initialization, but if they are supplied, they
+  # are silently recorded into @init_args (for argument array) and @init_block
+  # (for block, if given) instance variables, exposed via standard readers.
+  # 
+  def initialize *args, &block
+    @init_args = args
+    @init_block = block
+    @recorded_messages = []
+  end
+
+  # Always true.
+  # 
+  def present?; true end
+
+  # Always false.
+  # 
+  def blank?; false end
+
+  # Always true.
+  # 
+  def respond_to? ß, *args, █ true end
+
+  def method_missing ß, *args, &block      # :nodoc:
+    @recorded_messages << [ ß, args, block ]
+    return self
+  end
+end # class InertRecorder
+
+
+class Object
+  # InertRecorder constructor.
+  # 
+  def InertRecorder *args, &block; InertRecorder.new *args, &block end
+end

data/lib/y_support/local_object.rb

@@ -0,0 +1,39 @@
+#encoding: utf-8
+
+require 'y_support'
+
+# Object, whose business is to stay local to methods. Optional signature
+# provides additional level of safety in ensuring object locality. (Signature
+# accessor is :signature, aliased as :σ (small Greek sigma).)
+# 
+class LocalObject
+  attr_reader :signature
+  alias σ signature
+
+  # Optional argument signature provides additional level of safety in
+  # ascertaining that the object indeed is of local origin.
+  # 
+  def initialize signature=__callee__
+    @signature=signature
+  end
+
+  # True if the (optional) signature matches.
+  # 
+  def local_object? signature=__callee__
+    signature == self.signature
+  end
+  alias ℓ? local_object?
+end
+
+
+class Object
+  # LocalObject constructor.
+  # 
+  def LocalObject signature=nil; LocalObject.new signature end
+  alias L! LocalObject
+
+  # False for normal objects, overriden in the LocalObject class.
+  # 
+  def local_object? signature=nil; false end
+  alias ℓ? local_object?
+end

data/lib/y_support/misc.rb

@@ -0,0 +1,28 @@
+#encoding: utf-8
+require 'y_support'
+
+# Typing library.
+#
+# Apart from usual <em>typing by class and ancestry</em>, supported by built-in
+# #kind_of?, alias #is_a? inquirerers, this typing library provides support for
+# provides support for <em>typing by declaration</em> and <em>duck typing</em>.
+# 
+# 1. Using method <b>declare_compliance</b>, a module can explicitly declare that
+# it provides the interface compliant with another module. Corresponding inquirer
+# methods are <b>declared_compliance</b> (returning a list of modules with which
+# the receiver declares compliance or implicitly complies) and
+# <b>declares_compliance?( other_module )</b>, which anwers whether the receiver
+# complies with other_module. An object always implicitly complies with its class
+# and class ancestry.
+# 
+# 2. Duck type enforcement for method parameters is supported by a collection of
+# enforcer methods (aka. run-time assertions). These methods look very much like
+# assertions, but they start with <b>tE_...</b>, meaning "enforce by raising
+# TypeError".
+
+[ :core_ext, :stdlib_ext ].each do |ext|
+  Dir["#{File.dirname( __FILE__ )}/#{ext}/*/misc.rb"].sort.each { |path|
+    dir = File.dirname( path ).match( "y_support/#{ext}" ).post_match
+    require "y_support/#{ext}#{dir}/misc"
+  }
+end