y_support 2.1.18 → 2.4.4

data/lib/y_support/name_magic/namespace_methods.rb

@@ -1,260 +0,0 @@
-# encoding: utf-8
-
-# Module methods for the modules serving as +NameMagic+ namespaces. A namespace
-# for a certain class featuring +NameMagic+ holds "civil registry" of all its
-# instances, be they named or nameless. For this purpose, the namespace owns
-# +@instances+ hash of pairs <tt>{ instance => name }</tt>, with _nil_ values
-# denoting nameless instances. For named instances, the namespace also holds
-# references to them in constants in the style <tt>Namespace::Name</tt>. This
-# is one of the reasons why instance names in +NameMagic+ must start with
-# a capital letter and generally must be usable as constant names. The list of
-# instances is accessible via +#instances+ method. Individual instances can be
-# queried by +#instance+ method, eg. by their names.
-# 
-# === Life cycle of instances of classes featuring +NameMagic+
-#
-# +NameMagic+ offers 3 hooks for the instances of its user classes. These hooks
-# are closures invoked at the relevant points of the instances' life cycle: 
-#
-# * new instance hook -- when the instance is created
-# * name set hook -- when the instance is offered a name
-# * name get hook -- when the instance's name is queried
-# 
-# These three hooks are stored in instance variables owned by the namespace,
-# accesible by methods +#new_instance_hook, +#name_set_hook+ and
-# +#name_get_hook+. If called with a block, these methods also serve to set
-# their respective hook closures.
-#
-# When an instance is first created, unary +new_instance_hook+ is called.
-# When an instance is offered a name, +name_set_hook+ is called. It is a
-# ternary closure with 3 ordered arguments +name+, +instance+ and +old_name+,
-# receiving respectively the name offered, the instance, and the previous
-# name of the instance (if any). The return value of the closure will be used
-# to actually name the instance. This closure can thus be used to check and
-# modify the names before they are actually used. Finally, when the instances'
-# name is queried, third closure, unary +name_get_hook+ is applied to modify
-# the name output. The purpose of the name get hook is not to really change
-# the name upon reading, but mainly to tweak the preferred form or spelling
-# where multiple forms of are possible for the same name. (For example, the
-# standard form in the +@instances+ hash could be in camel case, such as
-# "AcinonyxJubatus", while preferred querying output would be a binomial name
-# with whitespaces, "Acinonyx jubatus".)
-# 
-# === Avidity of the instances 
-#
-# After the offered name is checked and modified by the name set hook closure,
-# there is one more remaining problem to worry about: Whether the name is
-# already used by another instance in the same namespace. If the name is taken,
-# the ensuing action depends on whether the instance being named is _avid_.
-# Avid instances are so eager to get a name, that they will steal the offered
-# name even if it is already in use, making the conflicting instance nameless
-# in the process. In +NameMagic+, it turns out to be convenient to make the
-# new instances avid by default, unless the name was explicitly supplied to the
-# constructor by +:name+ argument, or avidity suppressed by setting +:name_avid
-# option to _false_.
-#
-# Techincally, avid instances are registered as an array kept by the namespace
-# under the variable +@avid_instances+.
-#
-# === Forgetting instances
-#
-# A namespace can de-register, or forget instances. For this purpose, see
-# methods +#forget+, +#__forget__, +#forget_nameless_instances+,
-# +#forget_all_instances+.
-#
-# === Ersatz constant magic
-# 
-# To imitate built-in constant magic of some Ruby classes, +NamespaceMethods+
-# provides ersatz method +#const_magic+, that searches all the modules in the
-# object space for the pertinent instances newly assigned to constants. Method
-# +#const_magic+ is then called before executing almost every public method of
-# +NameMagic+, thus keeping the "civil registry" up-to-date. While not exactly
-# computationally efficient, it tends to make the user code more readable and
-# pays off in most usecases. For efficiency, we are looking forward to the
-# +#const_assigned+ hook promised by Ruby core team...
-#
-# The namespace method versions that _do_ _not_ perform ersatz constant magic
-# are generally denoted by underlines: Eg. methods +#__instances__+ and
-# +#__forget__+ do not perform constant magic, while +#instances+ and +#forget+
-# do.
-# 
-module NameMagic::NamespaceMethods
-  # Presents the instances registered in this namespace.
-  #
-  def instances *args
-    const_magic
-    __instances__.keys
-  end
-
-  # Deprecated method to get full names of the named instances.
-  # 
-  def instance_names
-    warn "Method #instance_names is deprecated. Use 'instances._names_' or 'instances.names' instead!"
-    instances.names false
-  end
-
-  # Presents namespace-owned +@instances+ hash. The hash consists of pairs
-  # <code>{ instance => instance_name }</code>. Unnamed instances have +nil+
-  # assigned to them as their name. (The method does not trigger
-  # +#const_magic+.)
-  #
-  def __instances__
-    @instances ||= {}
-  end
-
-  # Avid instances registered in this namespace. ("Avid" means that the
-  # instance is able to steal (overwrite) a name from another registered
-  # instance. (The method does not trigger +#const_magic+.)
-  #
-  def __avid_instances__
-    @avid_instances ||= []
-  end
-
-  # Returns the instance identified by the argument, which can be typically
-  # a name (string/symbol). If a registered instance is supplied, it will be
-  # returned unchanged.
-  #
-  def instance id, *args
-    # puts "#instance( #{identifier} )" if DEBUG
-    # In @instances hash, value 'nil' indicates a nameless instance!
-    fail TypeError, "'nil' is not an instance identifier!" if id.nil?
-    ii = instances
-    return id if ii.include? id # return the instance back
-    begin # identifier not a registered instance -- treat it as a name
-      ary = [id, id.to_sym]
-      ihsh = __instances__
-      ii.find { |inst| ary.include? ihsh[ inst ] or ary.include? inst.name }
-    rescue NoMethodError
-    end or fail NameError, "No instance #{id} in #{self}."
-  end
-
-  # Searches all the modules in the the object space for constants referring
-  # to receiver class objects, and names the found instances accordingly.
-  # Internally, it works by invoking private procedure +#search_all_modules.
-  # The return value is the remaining number of nameless instances.
-  #
-  def const_magic
-    puts "#{self}#const_magic invoked!" if ::NameMagic::DEBUG
-    return 0 if nameless_instances.size == 0
-    search_all_modules
-    return nameless_instances.size
-  end
-    
-  # Returns those instances, which are nameless (whose name is set to nil).
-  # 
-  def nameless_instances *args
-    __instances__.select { |key, val| val.nil? }.keys
-  end
-
-  # Clears namespace-owned references to a specified instance. (This is
-  # different from "unnaming" an instance by setting <code>inst.name =
-  # nil</code>, which makes the instance anonymous, but still registered.)
-  # 
-  def forget instance_identifier, *args
-    inst = begin; instance( instance_identifier ); rescue ArgumentError
-             return nil # nothing to forget
-           end
-    ɴ = inst.nil? ? nil : inst.name
-    namespace.send :remove_const, ɴ if ɴ   # clear constant assignment
-    __instances__.delete( inst )           # remove @instances entry
-    __avid_instances__.delete( inst )      # remove if any
-    return inst                            # return the forgotten instance
-  end
-
-  # Clears namespace-owned references to an instance, without performing
-  # #const_magic first. The argument should be a registered instance. Returns
-  # the instance name, or _false_, if there was no such registered instance.
-  # 
-  def __forget__( instance, *args )
-    return false unless __instances__.keys.include? instance
-    namespace.send :remove_const, instance.name if instance.name
-    __avid_instances__.delete( instance )
-    __instances__.delete instance
-  end
-
-  # Clears namespace-owned references to all the anonymous instances.
-  # 
-  def forget_nameless_instances
-    nameless_instances.each { |inst|
-      __instances__.delete( inst )
-      __avid_instances__.delete( inst ) # also from avid instances
-    }
-  end
-
-  # Clears namespace-owned references to all the instances.
-  # 
-  def forget_all_instances
-    __instances__.clear
-    constants( false ).each { |sym|
-      namespace.send :remove_const, sym if const_get( sym ).is_a? self
-    }
-  end
-
-  # Registers a hook to execute upon instantiation. Expects a unary block, whose
-  # argument represents the new instance. It is called right after instantiation,
-  # but before naming the instance. Without a block, it acts as a getter.
-  # 
-  def new_instance_hook &block
-    @new_instance_hook = block if block
-    @new_instance_hook ||= -> instance { instance }
-  end
-
-  # Registers a hook to execute upon instance naming. Expects a ternary block,
-  # with arguments name, instance and old_name, representing respectively the
-  # the requested name, the instance to be named, and the previous name of that
-  # instance (if any). The output of the block should be the name to actually
-  # be used. In other words, the hook can be used (among other things) to check
-  # and/or modify the requested name when christening the instance. It is the
-  # responsibility of this block to output a symbol that can be used as a Ruby
-  # constant name. Without a block, this method acts as a getter.
-  # 
-  def name_set_hook &block
-    @name_set_hook = block if block
-    @name_set_hook ||= -> name, instance, old_name=nil { name }
-  end
-
-  # Registers a hook to execute whenever the instance is asked its name. The
-  # instance names are objects that are kept in a hash referred to by
-  # +@instances+ variable owned by the namespace. Normally, +NameMagic#name+
-  # simply returns the name of the instance, as found in the +@instances+ hash.
-  # When +name_get_hook+ is defined, this name is transformed by it before being
-  # returned. Without a block, this method acts as a getter.
-  # 
-  def name_get_hook &block
-    @name_get_hook = block if block
-    @name_get_hook ||= -> name { name }
-  end
-
-  # Checks whether a name is acceptable as a constant name.
-  # 
-  def validate_name name
-    name.to_s.tap do |ɴ| # check if the name starts with 'A'..'Z'
-      fail NameError, "#{self}-registered name must start with a capital " +
-        " letter 'A'..'Z' ('#{ɴ}' given)!" unless ( ?A..?Z ) === ɴ[0]
-    end
-  end
-
-  private
-
-  # Checks all the constants in some module's namespace, recursively.
-  # 
-  def search_all_modules
-    todo = ( nameless_instances + __avid_instances__ ).map( &:object_id ).uniq
-    ObjectSpace.each_object Module do |ɱ|
-      ɱ.constants( false ).each do |const_ß|
-        begin; instance = ɱ.const_get( const_ß )  # Some constants cause
-        rescue LoadError, StandardError; next end # errors upon loading.
-        next unless todo.include? instance.object_id
-        # puts "NameMagic: Anonymous object under #{const_ß}!" if DEBUG
-        if instance.avid? then # puts "NameMagic: It is avid." if DEBUG
-          instance.make_not_avid!                 # Remove from the avid list.
-          instance.name! const_ß                  # Name it rudely.
-        else # puts "NameMagic: It is not avid." if DEBUG
-          instance.name = const_ß    # Name it cautiously.
-        end
-        todo.delete instance.object_id            # Remove from todo list.
-        break if todo.empty?                      # Abandon the loop if done.
-      end
-    end
-  end
-end # module NameMagic::NamespaceMethods

data/lib/y_support/try.rb

@@ -1,133 +0,0 @@
-# encoding: utf-8
-
-require 'y_support'
-require 'y_support/core_ext/array/misc'
-
-# Provides +Try+ class, and +Object#try+ method that constructs and calls a
-# +Consciously::Try+ instance. This +#try+ method has nothing to do with the
-# error-swallowing +#try+ method frequently seen elsewhere. On the contrary,
-# our +#try+ method _facilitates_ raising and ultimately, correcting errors
-# by providing well-formed error messages.
-#
-# Constructing error messages is labor-intensive. +Consciously::Try+ allows one
-# to construct verbose error messages with +#note+ statements inside the block,
-# that act as comments at the same time.
-#
-#   "FooBar".try "to do something" do
-#     note has: "#{size} letters", is: "a #{self.class} instance"
-#     unless include? "Quux"
-#       note "Quux", is: "not a part of it"
-#       try "to append Quux to it" do
-#         self << "Quux"
-#         fail "EPIC FAIL"
-#       end
-#     end
-#   end
-#
-# Should produce an automatic error message like this: "When trying to do
-# something, FooBar having 6 letters, being a String instance, Quux being
-# not a part of it, RuntimeError occurred: When trying to append Quux to it,
-# RuntimeError occurred: EPIC FAIL"
-#
-module Consciously
-  class Try < BasicObject
-    DECORATE = -> str, prefix: '', postfix: '' {
-      str.to_s.tap { |ς| return ς.empty? ? '' : prefix + ς + postfix }
-    }
-    TRANSITIVE = ::Hash.new do |ꜧ, key| "#{key}ing %s" end
-      .update( is: "being %s",
-               has: "having %s" )
-    STATE = ::Hash.new do |ꜧ, key| "#{key} %s" end
-      .update( is: "%s",
-               has: "has %s" )
-
-    attr_reader :__obj__, :__txt__, :__bl__, :__facts__
-
-    # This 
-    def initialize( object: nil, text: nil, &block )
-      @__obj__, @__txt__, @__bl__ = object, text, block
-      @__facts__ = ::Hash.new do |hsh, key| hsh[key] = [ {} ] end
-    end
-
-    # The syntax of this method, available inside the #try block, is:
-    # 
-    #   note "Concatenation of Foo and Bar", is: "FooBar", has: "6 letters"
-    #
-    def note *subjects, **statements, &block
-      return Array( subjects ).each { |s| __facts__[s].push_ordered s } if
-        statements.empty?
-      subjects << __obj__ if subjects.empty?
-      Array( subjects ).each { |subj|
-        statements.each { |verb, obj| __facts__[subj].push_named verb => obj }
-      }
-      return statements.first[1]
-    end
-
-    # Invokes the Try object's block.
-    # 
-    def __invoke__ *args
-      begin
-        instance_exec *args, &__bl__
-      rescue ::StandardError => err
-        txt1 = "When trying #{__txt__}"
-        thing, statements = __describe__
-        txt2 = DECORATE.( thing, prefix: ' ' )
-        txt3 = DECORATE.( statements.map { |verb, object|
-                            STATE[verb] % object
-                          }.join( ', ' ),
-                          prefix: ' (', postfix: ')' )
-        txt4 = DECORATE.( __circumstances__, prefix: ', ' )
-        txt5 = DECORATE.( "#{err.class} occurred: #{err}", prefix: ', ' )
-        raise err, txt1 + txt2 + txt3 + txt4 + txt5
-      end
-    end
-
-    def try *args, &block
-      __obj__.try *args, &block
-    end
-
-    def method_missing sym, *args
-      __obj__.send sym, *args
-    end
-
-    def __describe__ obj=__obj__
-      facts = __facts__[obj].dup
-      statements = if facts.last.is_a? ::Hash then facts.pop else {} end
-      fs = facts.join ', '
-      if statements.empty? then
-        return fs, statements
-      else
-        return facts.empty? ? obj.to_s : fs, statements
-      end
-    end
-
-    def __circumstances__
-      __facts__.reject { |subj, _| subj == __obj__ }.map { |subj, _|
-        thing, statements = __describe__( subj )
-        thing + DECORATE.( statements.map { |v, o|
-                             TRANSITIVE[v] % o
-                           }.join( ', ' ),
-                           prefix: ' ' )
-      }.join( ', ' )
-    end
-  end
-end
-
-
-class Object
-  # Try method takes two textual arguments and one block. The first (optional)
-  # argument is a natural language description of the method's receiver (with
-  # #to_s of the receiver used by default). The second argument is a natural
-  # language description of the supplied block's _contract_ -- in other words,
-  # what the supplied block tries to do. Finally, the block contains the code
-  # to perform the described risky action. Inside the block, +#note+ method is
-  # available, which builds up the context information for a good error message,
-  # should the risky action raise one.
-  # 
-  def try receiver_NL_description=self, attempt_NL_description, &block
-    Consciously::Try.new( object: receiver_NL_description,
-                         text: attempt_NL_description,
-                         &block ).__invoke__
-  end
-  alias consciously try
-end

data/test/abstract_algebra_test.rb

@@ -1,138 +0,0 @@
-#! /usr/bin/ruby
-#encoding: utf-8
-
-fail NotImplementedError # TODO: This part doesn't work yet
-
-require 'minitest/autorun'
-
-describe "Algebra" do
-  before do
-    require './../lib/y_support/abstract_algebra'
-    # Define the stupidest monoid:
-    @monoid = Class.new { include Algebra::Monoid } # make some class
-    zero = @monoid.new         # call arbitrary instance zero
-    @monoid.class_exec {
-      # Define the stupidest #add method.
-      define_method :add do |other|
-        if self == zero then other
-        elsif other == zero then self
-        else self.class.addition_table[[self, other]] end
-      end
-      # Define the stupidest addition table.
-      instance_variable_set :@addition_table,                      
-      Hash.new { |ꜧ, k|
-        ꜧ[k] = if k[0].object_id <= k[1].object_id
-                 new # just make up an instance
-               else
-                 ꜧ[k[1], k[0]] # swap operands
-               end
-      }
-    }
-    # And refine the @monoid's singleton class.
-    @monoid.singleton_class.class_exec { attr_reader :addition_table }
-    @monoid.define_singleton_method :additive_identity do zero end
-  end
-
-  describe "Algebra" do
-    it "should have working Monoid" do
-      m = @monoid.random                  # choose an instance
-
-      # #== method
-      assert m == m
-
-      # closure
-      # (not tested)
-
-      # associativity
-      n, o = @monoid.random, @monoid.random
-      assert ( m + n ) + o == m + ( n + o )
-
-      # identity element
-      assert m + @monoid.zero == m
-      assert @monoid.zero + m == m
-    end
-
-    it "should have working Group" do
-      g = @group.random
-
-      # (monoid properties not tested)
-
-      # inverse element
-      assert g + (-g) == @group.zero
-      assert (-g) + g == @group.zero
-    end
-
-    it "should define AbelianGroup" do
-      ag = @abelian_group.random
-
-      # (group properties not tested)
-
-      # commutativity
-      bh = @abelian_group.random
-      assert ag + bh == bh + ag
-    end
-
-    it "should define Ring" do
-      r = @ring.random
-
-      # (abelian group properties with respect to addition not tested)
-
-      # (multiplication closure not tested)
-
-      # multiplication associativity
-      s, t = @ring.random, @ring.random
-      assert r * ( s * t ) == ( r * s ) * t
-
-      # multiplication identity
-      mi = @ring.one
-      assert r * mi == r
-      assert mi * r == r
-
-      # distributivity
-      assert r * ( s + t ) == ( r * s ) + ( s * t )
-    end
-
-    it "should define Field" do
-      f = @field.random
-
-      # (ring properties not tested)
-      
-      # multiplicative inverse
-      mi = @ring.multiplicative_identity
-      assert f * f.multiplicative_inverse == mi
-      assert f.multiplicative_inverse * f == mi
-    end
-  end
-
-  describe "numerics" do
-    it "should have patched Integer" do
-      assert Integer.zero.equal? 0
-    end
-
-    it "should have patched Float" do
-      assert Float.zero.equal? 0.0
-    end
-
-    it "should have patched Rational" do
-      assert Rational.zero.equal? Rational( 0, 0 )
-    end
-
-    it "should have patched Complex" do
-      assert Complex.zero.equal? Complex( 0, 0 )
-    end
-  end
-
-  describe "Matrix" do
-    it "should have Matrix.wildcard_zero public instance method" do
-      # FIXME
-    end
-
-    it "should be able to perform #* with nonnumerics in the matrix" do
-      # FIXME
-    end
-
-    it "should numeric matrix multiplication still be working normally" do
-      # FIXME
-    end
-  end # context Matrix
-end

data/test/performance_test_example.rb

@@ -1,23 +0,0 @@
-#! /usr/bin/ruby
-
-require 'minitest/autorun'
-require 'minitest/benchmark'
-
-class TestCoreMethods < Minitest::Benchmark
-  def setup
-    @arrays = ( 1 .. 11_000 ).map { |n| [ 42 ] * n }
-  end
-
-  # Override self.bench_range or default range is [1, 10, 100, 1_000, 10_000]
-  def bench_size
-    assert_performance_linear 0.99 do |n| ( [ 0 ] * n ).reduce :+ end
-    assert_performance_constant 0.99 do |n| 42.times { 42 } end
-    # assert_performance_linear 0.99 do |n| @arrays[ n ].size end
-    assert_performance_constant 0.99 do |n| @arrays[ n ].size end
-    # TODO: For some reason, assert_performance_constant doesn't fail even if
-    # I artificially introduce eg. quadratic algorithm. All the while, the
-    # line assert_performance_linear does fail if uncommented (since the perf.
-    # here is constant).
-    # TODO: In other words, I'm not very experienced in performance testing yet.
-  end
-end

data/test/try_test.rb

@@ -1,102 +0,0 @@
-#! /usr/bin/ruby
-
-require 'minitest/autorun'
-# require 'y_support/try'     # tested component itself
-require './../lib/y_support/try'
-
-describe Consciously do
-  before do
-    @try = Consciously::Try.new object: "Dummy", text: "to fire" do
-      note is: "dummy"
-      note has: "no care in the world"
-      n = note "its number", is: 42
-      raise TypeError, 'foo'
-    end
-  end
-
-  it "should have basic functionality" do
-    assert_equal "to fire", @try.__txt__
-    assert_equal "Dummy", @try.__obj__
-    assert_equal 0, @try.__facts__.size # haven't tried anything yet
-    @try.__facts__["something"]
-    assert_equal 1, @try.__facts__.size
-    @try.note is: 'dummy'
-    @try.note has: 'no care in the world'
-    assert_equal 2, @try.__facts__.size
-    assert_equal ["something", "Dummy"], @try.__facts__.keys
-    assert_equal( [ { is: "dummy", has: "no care in the world" } ],
-                  @try.__facts__["Dummy"] )
-    assert_equal " hello!", Consciously::Try::DECORATE.( :hello, prefix: ' ', postfix: '!' )
-    assert_equal( ['Dummy', {is: 'dummy', has: 'no care in the world'}],
-                  @try.__describe__( "Dummy" ) )
-  end
-
-  describe 'case 1' do
-    it "should work" do
-      begin
-        @try.__invoke__
-      rescue TypeError => err
-        expected_msg = "When trying to fire Dummy (dummy, has no care in " +
-          "the world), its number being 42, TypeError occurred: foo"
-        assert_equal expected_msg, err.message
-      else
-        flunk "Expected TypeError error not raised!"
-      end
-    end
-  end
-
-  describe 'case 2' do
-    it "should work" do
-      begin
-        try "to call constant Nonexistant" do Nonexistant end
-      rescue NameError => err
-        expected_msg = 'When trying to call constant Nonexistant, ' +
-          'NameError occurred: uninitialized constant Nonexistant'
-        assert_equal( expected_msg, err.message )
-      else
-        flunk "Expected NameError error not raised!"
-      end
-    end
-  end
-
-  describe 'case 3' do
-    it "should work" do
-      o = Object.new
-      class << o
-        def to_s; "THIS OBJECT" end
-        def hello!; "hello hello" end
-      end
-      # Object's methods must be callable
-      o.try "to say hello" do hello! end.must_equal "hello hello"
-      begin
-        o.try "to call a weird method" do goodbye! end
-      rescue NoMethodError => err
-        err.message.must_include "When trying to call a weird method, " +
-          "NoMethodError occurred: undefined method"
-        err.message.must_include "goodbye!"
-      end
-    end
-  end
-
-  describe 'case 4' do
-    it "should work" do
-      begin
-        "FooBar".try "to do something" do
-          note has: "#{size} letters", is: "a #{self.class} instance"
-          unless include? "Quux"
-            note "Quux", is: "not a part of it"
-            try "to append Quux to it" do
-              self << "Quux"
-              fail "EPIC FAIL"
-            end
-          end
-        end
-      rescue => err
-        err.message.must_equal 'When trying to do something, FooBar having ' +
-          '6 letters, being a String instance, Quux being not a part of it, ' +
-          'RuntimeError occurred: When trying to append Quux to it, ' +
-          'RuntimeError occurred: EPIC FAIL'
-      end
-    end
-  end
-end