such 2.0.210201 → 2.1.230106

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84767a253e3e1535798068135516617e3c198fc4b3ed756e529c16c27f25a649
-  data.tar.gz: 919ffcc84f13208bb3fc232ad8dc2ac92eb16b40d0cc6f63bb81b2b79c8b7e63
+  metadata.gz: c296ea57df2d19bf9db70eb35f97494e15b8c739d5b0e8cea5a31163c457dc76
+  data.tar.gz: a1c10cf419d67311a9b9e33fdf26a3f587052af4a5a3260a6b3f2db90b255056
 SHA512:
-  metadata.gz: d53f03a3dc85ad766199e40d0f7d08011420ec1c437de865cdda76f2757a8c4bac012379098fd087af1f78ce11918be949b46fe0cff68668806df237a175a5f0
-  data.tar.gz: 96c391adf17465cdf4330a37c83eece66a1d4ae37337067fc8b04cd1f0105fe5f4b45b4863371c60d558552980e5ab744f9cb817c4c26322895b50139567760a
+  metadata.gz: 23fd64fe227f2fb0fd3e3ac26c512a754fbf19b047a90ca21e0e12bc807309642543e614cc33b88a5aee46c6efe2f06fc4ea06d7881cf59d25346c3acd44af1d
+  data.tar.gz: 8907935ccdea95e257bda042ac851fdcacdb0d9b8972e8f43d1d4fd1e071d514f59001d7e5557c0d864b4f17c6813e1d77b3a2047a20b866c032bf14b3766723

data/README.md

@@ -1,6 +1,6 @@
 # Such
 
-* [VERSION 2.0.210201](https://github.com/carlosjhr64/such/releases)
+* [VERSION 2.1.230106](https://github.com/carlosjhr64/such/releases)
 * [github](https://www.github.com/carlosjhr64/such)
 * [rubygems](https://rubygems.org/gems/such)
 
@@ -12,13 +12,10 @@ Can be used to wrap any class with the alternate constructor,
 although targeted only Gtk3 widgets.
 
 ## INSTALL:
-
 ```shell
-$ sudo gem install such
+$ gem install such
 ```
-
 ## SYNOPSIS:
-
 ```ruby
 require 'gtk3'
 require 'such'
@@ -38,13 +35,11 @@ window.show_all
 
 Gtk.main #=> nil
 ```
-
 ## MORE:
 
-Arrays are passed to constructer's super,
+Arrays are passed to constructor's super,
 Hashes are method=>arguments pairs, and Strings are signals.
 Other objects are assumed to be containers:
-
 ```ruby
 Such::Button.new(
   window,
@@ -60,17 +55,13 @@ window.add button
 button.set_size_request 100, 50
 button.signal_connect('clicked'){puts 'OK'}
 ```
-
 To set the packing method to say `:pack_start`, set the `:into` method as follows:
-
 ```ruby
 {into: [:pack_start, expand:false, fill:false, padding:0]}
-# The effect in the contructor will be as if the following was run:
+# The effect in the constructor will be as if the following was run:
 #   container.pack_start(self, expand:false, fill:false, padding:0)
 ```
-
 One can configure Symbol keys to represent metadata about a widget:
-
 ```ruby
    Thing.configure(
      KEY: [ arg1, arg2, arg3 ], # an array for super(arg1, arg2, arg3)
@@ -82,8 +73,7 @@ One can configure Symbol keys to represent metadata about a widget:
      key!: [[arg1, arg2], {meth1:args1, meth2:args2}, 'signal1', 'signal2'] # the splatter bang!
    )
 ```
-
-The examples in this repository are reworks of the examples given in
+Many examples in this repository are reworks of the examples given in
 ZetCode.com[http://zetcode.com/gui/rubygtk/] (back in 2015).
 
 ## Features:
@@ -93,19 +83,26 @@ ZetCode.com[http://zetcode.com/gui/rubygtk/] (back in 2015).
 * Missing signal assumed to be 'clicked'
 * Heuristics on when one wants to iterate a method over the arguments given
 * Packing method defaults (ultimately) to :add
-* Way to change default packing behaviour
+* Way to change default packing behavior
 
 ## But wait!  One more thing:
 
 See [such_parts_demo](examples/such_parts_demo) in the examples directory
-and [tc_part](test/tc_part) for hints on how to use the powerful
+and [tc_part](test/tc_part) for hints on how to use
 [Such::Part module](lib/such/part.rb).
 
+See also [tc_convention](test/tc_convention) in the test directory
+for a suggested convention for naming keys.
+
+## Gnarly!
+
+Yes, I know!
+
 ## LICENSE:
 
 (The MIT License)
 
-Copyright (c) 2021 CarlosJHR64
+Copyright (c) 2023 CarlosJHR64
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/lib/such/convention.rb

@@ -0,0 +1,99 @@
+# Use this to validate your configuration against the given convention.
+# It should be run as part of your tests,
+# not necessarily in your application.
+module Such
+  module Convention
+    module Refinements
+      refine Object do
+        # Atoms
+        def item_symbol?
+          is_a?Symbol and match?(/^\w+[!?]?$/)
+        end
+        def item_boolean?
+          [TrueClass,FalseClass].any?{is_a?_1}
+        end
+        def item_value?
+          [String,Float,Integer].any?{is_a?_1}
+        end
+        # Item
+        def item_tangible?
+          item_value? or item_symbol?
+        end
+        def item?
+          item_tangible? or item_boolean?
+        end
+        # Items
+        def items?
+          item? or item_array? or item_hash?
+        end
+        def item_hash?
+          is_a?Hash and all?{_1.item_symbol? and (_2.nil? or _2.items?)}
+        end
+        def item_array?
+          is_a?Array and all?{_1.nil? or _1.items?}
+        end
+        def item_bang_array?
+          is_a?Array and
+          all?{_1.is_a?Symbol or _1.is_a?String or
+               _1.item_array? or _1.item_hash?}
+        end
+        def item_explicit_array?
+          is_a?Array and
+          all?{_1.is_a?String or _1.item_array? or _1.item_hash?}
+        end
+      end
+    end
+
+    CAPS   = /^[A-Z_]+$/
+    CAPS1  = /^[A-Z_]+!$/
+    CAPS2  = /^[A-Z_]+[?]$/
+    LOWER  = /^[a-z_]+$/
+    LOWER1 = /^[a-z_]+!$/
+    LOWER2 = /^[a-z_]+[?]$/
+    WORD   = /^\w+$/
+    WORD1  = /^\w+!$/
+    WORD2  = /^\w+[?]$/
+
+    using Refinements
+
+    def self.validate_kv(k,v)
+      raise   'unrecognized item symbol'    unless k.item_symbol?
+      case k
+      when LOWER  # abc
+        raise 'unrecognized item hash'      unless v.item_hash? or
+                                           (v.is_a?Symbol and LOWER.match?v)
+      when CAPS   # ABC
+        raise 'unrecognized item array'     unless v.item_array?
+      when WORD   # Abc
+        raise 'unrecognized item tangible'  unless v.item_tangible?
+      when LOWER1 # abc!
+        raise 'unrecognized bang array'     unless v.item_bang_array?
+      when CAPS1  # ABC!
+        raise 'unrecognized explicit array' unless v.item_explicit_array?
+      when WORD1  # Abc!
+        raise 'unrecognized items'          unless v.items?
+      when LOWER2 # abc?
+        raise 'unrecognized boolean'        unless v.item_boolean?
+      when CAPS2  # ABC?
+        raise 'unrecognized boolean|nil'    unless v.nil? or v.item_boolean?
+      when WORD2  # Abc?
+        raise 'unrecognized item value|nil' unless v.nil? or v.item_tangible?
+      else
+        raise 'should not happen'
+      end
+    end
+
+    def self.validate(config)
+      raise 'expected hash' unless config.is_a?Hash
+      errors = {}
+      config.each do |k,v|
+        begin
+          validate_kv(k,v)
+        rescue
+          errors[k] = $!.message
+        end
+      end
+      return errors.empty? ? nil : errors
+    end
+  end
+end

data/lib/such/part.rb

@@ -6,18 +6,27 @@ module Such
       super(*parameters)
       self.class.plugs.each do |plg|
         if md = PLUG_PATTERN.match(plg)
-          plg, sym, cls = "#{plg}=".to_sym, "#{md[:sym]}!".to_sym, Object.const_get("Such::#{md[:cls]}")
+          plg,sym,cls = "#{plg}=".to_sym,
+                        "#{md[:sym]}!".to_sym,
+                        Object.const_get("Such::#{md[:cls]}")
           # self.<plg> = Such::<cls>.new(self, :<sym>!, &block)
           public_send plg, cls.new(self, sym, &block)
         end
       end
     end
 
+    # Each part\Such::Part can invoke `message` on each of its connected part,
+    # and so on...
+    # Any part can override its `message` method to act as a terminal node or
+    # modify its relay behavior.
     def message(*parameters)
       self.class.plugs.each{|plg| public_send(plg).message(*parameters) }
     end
 
-    def method_missing(maybe,*args) # maybe a plug down the plugged things.
+    # Maybe a plug down the plugged things responds?
+    # This is a search through the connections which
+    # returns the first(non-nil) response.
+    def method_missing(maybe,*args)
       super unless args.length==0 and PLUG_PATTERN.match?(maybe)
       self.class.plugs.each do |plug|
         thing = public_send(plug)

data/lib/such/parts.rb

@@ -1,22 +1,43 @@
 module Such
   module Parts
+    ### Such::Parts ###
+    # Signature:
+    #   Such::Parts.make(part\Symbol, thing\Such::Thing, plugs\Array(Symbol)) \
+    #   (Such::Thing+Such::Part)
+    # The name of the Such::Part sub-class will be part.
+    # It will be a sub-class of thing(a sub-class of Such::Thing).
+    # The Array of symbols, plugs, will be accessors to other connected Such::Part's.
+    # Each plug must match:
+    #   /^<Part config key!>_<Name of connected sub-classed super-class>$/
+    # Note that these plugs are `attr_accessor`s,.
+    # Exemplar:
+    #   Component0#initialize(...,&block_given)
+    #     ...
+    #     part_obj.key_Component1 = Component1.new(:key!,&block_given)
+    #     ...
+    # Note that all connected components share the same block_given:
+    #   block_given(part\Such::Part, *w, signal\String)
+    # It gets called when the part receives its assigned activation signal,
+    # like "clicked" for a Button.
     def self.make(part, thing, *plugs)
       unless thing < Such::Thing and [part,*plugs].all?{_1.is_a? Symbol}
-        raise "Expected Such::Parts.make(Symbol part, Class thing < Such::Thing, *Symbol plugs)"
+        raise "Expected Such::Parts.make(Symbol part, " +
+              "Class thing < Such::Thing, *Symbol plugs)"
       end
       plugs.each do |plug|
-        if /^[^\W_]+_(?<klass>[^\W_]+)$/=~plug
+        if /^[^\W_]+_(?<super_class>[^\W_]+)$/=~plug
           next unless $VERBOSE
-          unless Object.const_defined?("Such::#{klass}")
-            $stderr.puts "Warning: Such::#{klass} not defined yet."
+          unless Object.const_defined?("Such::#{super_class}")
+            $stderr.puts "Warning: Such::#{super_class} not defined yet."
           end
         else
           raise "Plugs must have the form key_class: #{plug}"
         end
       end
-      subklass = Such.subclass(part, thing, include: Such::Part, attr_accessor: plugs)
-      subklass.singleton_class.class_eval{ define_method(:plugs){plugs} }
-      return subklass
+      sub_class = Such.subclass(part, thing,
+                               include: Such::Part, attr_accessor: plugs)
+      sub_class.singleton_class.class_eval{ define_method(:plugs){plugs} }
+      return sub_class
     end
   end
 end

data/lib/such/such.rb

@@ -1,8 +1,13 @@
 module Such
-  def self.subclass(name, klass, **kw, &block)
-    subklass = const_set(name, Class.new(klass))
-    kw.each{|method, args| subklass.public_send(method, *args)}
-    subklass.class_eval(&block) if block
-    return subklass
+  def self.subclass(name, super_class, **including, &block)
+    # See documentation for Class#new
+    sub_class = const_set(name, Class.new(super_class))
+    # To be able to say like:
+    #   include Such::Thing
+    #   attr_accessor :attribute2, :attribute2
+    including.each{|these, mods| sub_class.public_send(these, *mods)}
+    # And to explicitly define methods in the subclass:
+    sub_class.class_eval(&block) if block
+    return sub_class
   end
 end

data/lib/such/thing.rb

@@ -5,7 +5,7 @@ module Such
 
     # PARAMETERS' pretense of being a Hash constant :P
     @@PARAMETERS = {}
-    PARAMETERS = lambda{|k| @@PARAMETERS[k]}
+    PARAMETERS = lambda{@@PARAMETERS[_1]}
     def PARAMETERS.to_h = @@PARAMETERS
     def self.configure(conf)
       @@PARAMETERS = conf
@@ -61,7 +61,7 @@ module Such
     end
 
     def self.which_method(container, methods=INTOS)
-      mthd = methods.detect{|m| container.respond_to?(m)}
+      mthd = methods.detect{container.respond_to?_1}
       raise "Don't know how to put into #{container.class}." if mthd.nil?
       return mthd
     end
@@ -69,7 +69,7 @@ module Such
     def self.into(obj, container=nil, mthd=nil, *args)
       if container
         if mthd
-          unless mthd.class==Symbol and container.respond_to?(mthd)
+          unless container.respond_to?(mthd)
             raise "Need container & method. Got #{container.class}##{mthd}(#{obj.class}...)"
           end
         else
@@ -90,7 +90,7 @@ module Such
       rescue ArgumentError, TypeError
         # Assume user meant to iterate. Note that the heuristic is not perfect.
         $stderr.puts "# Iterated Method #{mthd}." if $VERBOSE
-        [*args].each{|arg| m.call(*arg)}
+        [*args].each{m.call(*_1)}
       end
     end
 
@@ -105,9 +105,8 @@ module Such
 
     def self.do_links(obj, signals, block)
       return if signals.first==''
-      none = (signals.length==0)
       if block
-        signals.push(*SIGNALS) if none
+        signals=SIGNALS if signals.empty?
         signals.each do |signal|
           break if signal==''
           begin
@@ -117,11 +116,15 @@ module Such
             warn "Warning: no #{signal} signal for #{obj.class}"
           end
         end
-      elsif not none
+      elsif !signals.empty?
         warn "Warning: No block given for #{signals.join(',')} on #{obj.class}."
       end
     end
 
+    # Given an Object not sub-classed as a Thing:
+    #   obj = NotAThing.new
+    # One can still act on it like a Thing as follows:
+    #   Thing.do_config(obj, *parameters, &block)
     def self.do_config(obj, *parameters, &block)
       container, arguments, methods, signals = Thing.do_parameters(parameters)
       Thing.do_methods(obj, methods, container)
@@ -129,6 +132,7 @@ module Such
       warn "Warning: arguments not used in do_config(#{obj.class}...)." if arguments.length > 0
     end
 
+    # The alternate sub-class constructor:
     def initialize(*parameters, &block)
       container, arguments, methods, signals = Thing.do_parameters(parameters)
       super(*arguments)

data/lib/such/things.rb

@@ -1,19 +1,20 @@
 module Such
   module Things
-    def self.list(superklass)
-      ObjectSpace.each_object(Class).select{|klass| klass < superklass}
+    def self.list(super_class)
+      ObjectSpace.each_object(Class).select{_1 < super_class}
     end
 
-    def self.subclass(klass)
-      Such.subclass(klass.name.sub(/^.*::/,'').to_sym, klass, include: Such::Thing)
+    def self.subclass(sub_class)
+      Such.subclass(sub_class.name.sub(/^.*::/,'').to_sym, sub_class,
+                    include: Such::Thing)
     end
 
-    def self.in(superklass)
-      Things.list(superklass).each do |klass|
+    def self.in(super_class)
+      Things.list(super_class).each do |sub_class|
         begin
-          Things.subclass(klass)
+          Things.subclass(sub_class)
         rescue
-          $stderr.puts "#{$!.class}:\t#{superklass}" if $VERBOSE
+          $stderr.puts "#{$!.class}:\t#{super_class}" if $VERBOSE
         end
       end
     end

data/lib/such.rb

@@ -1,10 +1,11 @@
 module Such
-  VERSION = '2.0.210201'
+  VERSION = '2.1.230106'
+  require 'such/such'
+  autoload :Convention, 'such/convention.rb'
+  autoload :Thing,      'such/thing.rb'
+  autoload :Things,     'such/things.rb'
+  autoload :Part,       'such/part.rb'
+  autoload :Parts,      'such/parts.rb'
 end
-require 'such/such'
-require 'such/thing'
-require 'such/things'
-require 'such/part'
-require 'such/parts'
 # Requires:
 #`ruby`

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: such
 version: !ruby/object:Gem::Version
-  version: 2.0.210201
+  version: 2.1.230106
 platform: ruby
 authors:
-- carlosjhr64
-autorequire:
+- CarlosJHR64
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-01 00:00:00.000000000 Z
+date: 2023-01-06 00:00:00.000000000 Z
 dependencies: []
 description: |
   Wraps widgets with an alternate constructor
@@ -22,6 +22,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/such.rb
+- lib/such/convention.rb
 - lib/such/part.rb
 - lib/such/parts.rb
 - lib/such/such.rb
@@ -31,7 +32,7 @@ homepage: https://github.com/carlosjhr64/such
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -46,9 +47,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements:
-- 'ruby: ruby 3.0.0p0 (2020-12-25 revision 95aff21468) [x86_64-linux]'
-rubygems_version: 3.2.3
-signing_key:
+- 'ruby: ruby 3.2.0 (2022-12-25 revision a528908271) [aarch64-linux]'
+rubygems_version: 3.4.2
+signing_key: 
 specification_version: 4
 summary: Wraps widgets with an alternate constructor which factors out the configuration
   and assembly procedures into metadata. Can be used to wrap any class with the alternate