y_support 2.0.11 → 2.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bc98d20ebfbbb5861b8ec817347e5d73a71e4518
-  data.tar.gz: 1226960b1bc6b9e15a0c1626816266378fa489de
+  metadata.gz: d466ad84213f9677a44efdb9d426ae1a24c11688
+  data.tar.gz: 398a4cbaf4e656dcabd8d87055c5069bcef90275
 SHA512:
-  metadata.gz: 070a617610e329aa6a5ca5ac868ab3f875864485626e4db658da11bade01e37fb64f56a9323d41dc2a98acbac23e440bf3abb15a2d25fd4a0803d9c639713cda
-  data.tar.gz: 68f0b3f5b32caa61bc0fe44391d1946ca25dc6e394dbdc23fdcfe3e63d5b7d8489f9906a691d3b71107b4993a35192f65f452ee33a1a7628d34d4414718b65c7
+  metadata.gz: ace20c52c5676019cdf9b1633911a134903db65a3bca738e478172ea3d826e4485ab957b4f541fd21e2e0ab924b3ae9336ce5c6922be5ac7252edad5ed893bdf
+  data.tar.gz: cf26fc0b943d41e39af89f4dbb8025e258733fea47497a6f5be8b030125ccd0efbeb24212dd852833949111fb312f0acb1ea11e7f1e8f19570d9c7a361e6ca0b

data/lib/y_support/all.rb

@@ -8,6 +8,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/kde'
 require 'y_support/x'

data/lib/y_support/try.rb

@@ -0,0 +1,132 @@
+# -*- coding: 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
+end

data/lib/y_support/version.rb

@@ -1,3 +1,3 @@
 module YSupport
-  VERSION = "2.0.11"
+  VERSION = "2.0.13"
 end

data/test/try_test.rb

@@ -0,0 +1,103 @@
+#! /usr/bin/ruby
+
+require 'minitest/spec'
+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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: y_support
 version: !ruby/object:Gem::Version
-  version: 2.0.11
+  version: 2.0.13
 platform: ruby
 authors:
 - boris
@@ -53,7 +53,6 @@ files:
 - lib/y_support.rb
 - lib/y_support/abstract_algebra.rb
 - lib/y_support/all.rb
-- lib/y_support/conscience.rb
 - lib/y_support/core_ext.rb
 - lib/y_support/core_ext/array.rb
 - lib/y_support/core_ext/array/misc.rb
@@ -81,6 +80,7 @@ files:
 - lib/y_support/stdlib_ext.rb
 - lib/y_support/stdlib_ext/matrix.rb
 - lib/y_support/stdlib_ext/matrix/misc.rb
+- lib/y_support/try.rb
 - lib/y_support/typing.rb
 - lib/y_support/typing/array.rb
 - lib/y_support/typing/array/typing.rb
@@ -96,7 +96,6 @@ files:
 - lib/y_support/version.rb
 - lib/y_support/x.rb
 - test/abstract_algebra_test.rb
-- test/conscience_test.rb
 - test/inert_recorder_test.rb
 - test/kde_test.rb
 - test/local_object_test.rb
@@ -105,6 +104,7 @@ files:
 - test/name_magic_test.rb
 - test/null_object_test.rb
 - test/respond_to_test.rb
+- test/try_test.rb
 - test/typing_test.rb
 - test/unicode_test.rb
 - test/x_test.rb
@@ -135,7 +135,6 @@ summary: LocalObject, RespondTo, InertRecorder, NullObject, NameMagic, core exte
   typing etc.
 test_files:
 - test/abstract_algebra_test.rb
-- test/conscience_test.rb
 - test/inert_recorder_test.rb
 - test/kde_test.rb
 - test/local_object_test.rb
@@ -144,6 +143,7 @@ test_files:
 - test/name_magic_test.rb
 - test/null_object_test.rb
 - test/respond_to_test.rb
+- test/try_test.rb
 - test/typing_test.rb
 - test/unicode_test.rb
 - test/x_test.rb

data/lib/y_support/conscience.rb

@@ -1,132 +0,0 @@
-# -*- coding: utf-8 -*-
-require 'y_support'
-require 'active_support/core_ext/array/extract_options'
-
-# FIXME: Now, here, in order for the token game to work properly with
-# guarding system, several things have to be done. Firstly,
-# Place#set_marking( marking, blame ) will have to be implemented,
-# and in Place#add, blame argument will have to be added
-# Now with that blame, the transition will have to explain what it is
-# trying to do. So actually it should be a block
-#
-# It's gonna be a mixin, Conscience, or something like that, and it will
-# imbue the receiving class with the ability to try something.
-#
-# Transition.try "to fire!" do
-#   if assignment_action? then
-#     note has: "assignment action"
-#     note "Δt", is: Δt
-#     note "domain marking" is: domain_marking
-#     act = note "Action" do Array action( Δt ) end
-#     codomain.each_with_index do |place, i|
-#       try "set the marking of place #{place} to the #{i}-th element of the action vector (#{act[i]})" do
-#         place.marking = act[i]
-#       end
-#     end
-#   else
-#     etc. etc. etc.
-# end
-#
-# Should produce error messages like this:
-# When trying to fire! the transition #{self}, having assignment action, with Δt being #{Δt}, action has
-# been computed to #{Array action(Δt)}, when trying to set the marking of plac #{place} to the #{i}-th
-# element of the action vector (#{act[i]}), GuardError was encountered, with the message: ..."
-#
-# Yes, this is a managed code miniframework that I need here.
-#
-module Conscience
-  class Try
-    PUSH_ORDERED = -> ary, e {
-      named = ary.extract_options!
-      ary << e << named
-    }
-    PUSH_NAMED = -> ary, k, v {
-      named = ary.extract_options!
-      ary << named.update( k => v )
-    }
-    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 :_object_, :_text_, :_block_, :_facts_
-
-    def initialize( object: nil, text: nil, &block )
-      @_object_, @_text_, @_block_ = object, text, block
-      @_facts_ = Hash.new do |ꜧ, key| ꜧ[key] = [ {} ] end
-    end
-
-    def note *subjects, **statements, &block
-      return *Array( subjects ).each do |s|
-        PUSH_ORDERED.( _facts_[s], s )
-      end if statements.empty?
-      subjects << _object_ if subjects.empty?
-      Array( subjects ).each do |subj|
-        statements.each do |verb, object|
-          PUSH_NAMED.( _facts_[subj], verb, object )
-        end
-      end
-      return statements.first[1]
-    end
-
-    def call *args
-      begin
-        instance_exec *args, &_block_
-      rescue StandardError => err
-        txt1 = "When trying #{_text_}"
-        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 method_missing sym, *args
-      _object_.send sym, *args
-    end
-
-    private
-
-    def _describe_ obj=_object_
-      facts = _facts_[obj].dup
-      statements = facts.extract_options!
-      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 == _object_ }.map { |subj, _|
-        thing, statements = _describe_( subj )
-        thing + DECORATE.( statements.map { |v, o|
-                             TRANSITIVE[v] % o
-                           }.join( ', ' ),
-                           prefix: ' ' )
-      }.join( ', ' )
-    end
-  end
-
-  # Try method taxes two textual arguments and one block. The first (optional)
-  # textual argument describes what is the receiver of #try. The second argument
-  # describes in plain speech what activity is #try attempting. The block that
-  # follows then contains the code, which performs that activity. In the block,
-  # #note method is available, that builds up the context for the error message,
-  # if any.
-  # 
-  def try object=self, to_do_something, &block
-    Try.new( object: object, text: to_do_something, &block ).call
-  end
-end

data/test/conscience_test.rb

@@ -1,75 +0,0 @@
-#! /usr/bin/ruby
-
-require 'minitest/spec'
-require 'minitest/autorun'
-# require 'y_support/conscience'     # tested component itself
-require './../lib/y_support/conscience'
-
-include Conscience
-
-describe Try do
-  before do
-    @try = Try.new object: "Dummy", text: "to fire" do
-      note is: "dummy"
-      note has: "no care in the world"
-      n = note "the number", is: 42
-      raise TypeError, 'foo'
-    end
-  end
-
-  it "should have basic functionality" do
-    assert_equal "to fire", @try._text_
-    assert_equal "Dummy", @try._object_
-    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!", Try::DECORATE.( :hello, prefix: ' ', postfix: '!' )
-    assert_equal( ['Dummy', {is: 'dummy', has: 'no care in the world'}],
-                  @try.send( :_describe_, "Dummy" ) )
-  end
-
-  describe 'case 1' do
-    it "should work" do
-      begin
-        @try.call
-      rescue TypeError => err
-        expected_msg = "When trying to fire Dummy (dummy, has no care in " +
-          "the world), the 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
-      o.try "to call a missing method" do hello! end
-    end
-  end
-end