metaruby 1.0.0.rc2 → 1.0.0.rc3

data/lib/metaruby/inherited_attribute.rb

@@ -1,8 +1,44 @@
 require 'set'
 require 'utilrb/module/dsl_attribute'
 module MetaRuby
+    # Basic functionality for attributes that are aware of inheritance
+    #
+    # There's basically two main interfaces: {.inherited_single_value_attribute}
+    # and {.inherited_attribute}.
+    #
+    # The former will return the value as set at the lowest level in the
+    # model hierarchy (i.e. on self, then on supermodel if self is unset and so
+    # forth).
+    #
+    # The latter enumerates a collection (e.g. Array, Set or Hash). If a map
+    # is used (such as a Hash), additional functionality gives different choices
+    # as to how the key-value mapping is handled w.r.t. model hierarchy.
+    #
+    # In both cases, a value returned by a submodel is optionally passed through
+    # a promotion method (called #promote_#attributename) which allows to update
+    # the returned value (as e.g. update a possible back-reference of the
+    # enumerated value to its containing model from the original model to the
+    # receiver).
+    #
+    # @example promotion to update back references
+    #   class Port; attr_accessor :component_model end
+    #   class Component
+    #       inherited_attribute(:ports, :port, map: true) { Hash.new }
+    #
+    #       # Update #component_model to make it point to the receiver instead
+    #       # of the original model. Note that metaruby does not memoize the
+    #       # result, so it has to be done in the promote method if it is
+    #       # desired
+    #       def promote_port(port)
+    #           port = port.dup
+    #           port.component_model = self
+    #           port
+    #       end
+    #   end
     module Attributes
-        InheritedAttribute = Struct.new :single_value, :name, :accessor_name, :init
+        # Internal representation of inherited attributes
+        class InheritedAttribute < Struct.new(:single_value, :name, :accessor_name, :init)
+        end
 
         # The set of inherited attributes defined on this object
         # @return [Array<InheritedAttribute>]
@@ -35,6 +71,9 @@ module MetaRuby
 
         # Defines an attribute that holds at most a single value
         #
+        # The value returned by the defined accessor will be the one set at the
+        # lowest level in the model hierarchy (i.e. self, then superclass, ...)
+        #
         # @param [String] name the attribute name
         # @return [InheritedAttribute] the attribute definition
         # @raise [ArgumentError] if no attribute with that name exists
@@ -62,6 +101,8 @@ module MetaRuby
             nil
         end
 
+        # @api private
+        #
         # Helper method for {#inherited_single_value_attribute} in case there
         # are no promotion method(s) defined
         def define_single_value_without_promotion(method_name, ivar)
@@ -99,6 +140,8 @@ module MetaRuby
             EOF
         end
 
+        # @api private
+        #
         # Helper method for {#inherited_single_value_attribute} in case there is
         # a promotion method defined
         def define_single_value_with_promotion(method_name, promotion_method_name, ivar)
@@ -146,14 +189,14 @@ module MetaRuby
         # relevant methods and accessors to allow accessing it in a way that
         # makes sense when embedded in a model hierarchy
         #
-        # More specifically, it defines a <tt>each_#{name}(&iterator)</tt>
-        # instance method and a <tt>each_#{name}(&iterator)</tt>
+        # More specifically, it defines a <tt>each_#name(&iterator)</tt>
+        # instance method and a <tt>each_#name(&iterator)</tt>
         # class method which iterates (in order) on 
-        # - the instance #{name} attribute
-        # - the singleton class #{name} attribute
-        # - the class #{name} attribute
-        # - the superclass #{name} attribute
-        # - the superclass' superclass #{name} attribute
+        # - the instance #name attribute
+        # - the singleton class #name attribute
+        # - the class #name attribute
+        # - the superclass #name attribute
+        # - the superclass' superclass #name attribute
         # ...
         #
         # This method can be used on modules, in which case the module is used as if 
@@ -314,6 +357,8 @@ module MetaRuby
             end
         end
 
+        # @api private
+        #
         # Helper class that defines the iteration method for inherited_attribute
         # when :map is set and there is not promotion method
         def self.map_without_promotion(name, attribute_name, options)
@@ -364,6 +409,8 @@ module MetaRuby
             return code, file, line
         end
 
+        # @api private
+        #
         # Helper class that defines the iteration method for inherited_attribute
         # when :map is not set and there is no promotion method
         def self.nomap_without_promotion(name, attribute_name, options)
@@ -388,6 +435,8 @@ module MetaRuby
             return code, file, line
         end
 
+        # @api private
+        #
         # Helper class that defines the iteration method for inherited_attribute
         # when :map is set and there is a promotion method
         def self.map_with_promotion(name, attribute_name, options)
@@ -453,6 +502,8 @@ module MetaRuby
             return code, file, line
         end
 
+        # @api private
+        #
         # Helper class that defines the iteration method for inherited_attribute
         # when :map is not set and there is a promotion method
         def self.nomap_with_promotion(name, attribute_name, options)

data/lib/metaruby/module.rb

@@ -24,9 +24,18 @@ module MetaRuby
         include Registration
         extend Attributes
 
-        # @return [String] set or get the documentation text for this model
+        # @!method doc
+        #   @overload doc
+        #     @return [String] the documentation text for this model
+        #   @overload doc(new_doc)
+        #     @param [String] new_doc the new documentation
+        #     @return [String] the documentation text for this model
         inherited_single_value_attribute :doc
 
+        # Validate that a string can be used as a constant name
+        #
+        # @param [String] name the name to validate
+        # @raise [ArgumentError] if the name cannot be used as a constant name
         def self.validate_constant_name(name)
             if name !~ /^[A-Z]\w+$/
                 raise ArgumentError, "#{name} is not a valid model name"
@@ -38,6 +47,16 @@ module MetaRuby
         #
         # It is usually used to create specific DSL-like methods that allow to
         # create these models
+        #
+        # @param [Module,Class] namespace
+        # @param [String] name the model name, it must be valid for a Ruby
+        #   constant name
+        # @param [Module] base_model the base model, which should include
+        #   {ModelAsModule} itself
+        # @param [Array] args additional arguments to pass to base_model's
+        #   #setup_submodel
+        # @param [#call] block block passed to base_model's #setup_submodel
+        # @return [Module] the new model
         def self.create_and_register_submodel(namespace, name, base_model, *args, &block)
             ModelAsModule.validate_constant_name(name)
 
@@ -68,6 +87,8 @@ module MetaRuby
         # True if this model is a root model
         attr_predicate :root?, true
 
+        # @!attribute [rw] name
+        #
         # Sets a name on this model
         #
         # Only use this on 'anonymous models', i.e. on models that are not
@@ -83,25 +104,21 @@ module MetaRuby
             @name = name
         end
 
-        # Set the root model. See {root_model}
+        # Set or get the root model
         attr_accessor :supermodel
 
         # Creates a new DataServiceModel that is a submodel of +self+
         #
-        # @param [Hash] options the option hash
-        # @option options [String] :name the submodel name. Use this option
+        # @param [String] name the submodel name. Use this option
         #   only for "anonymous" models, i.e. models that won't be
         #   registered on a Ruby constant
-        # @option options [Class] :type (self.class) the type of the submodel
+        # @param [Class] type (self.class) the type of the submodel
         #
-        def new_submodel(options = Hash.new, &block)
-            options, submodel_options = Kernel.filter_options options,
-                :name => nil, :type => self.class
-
-            model = options[:type].new
+        def new_submodel(name: nil, type: self.class, **submodel_options, &block)
+            model = type.new
             model.extend ModelAsModule
-            if options[:name]
-                model.name = options[:name].dup
+            if name
+                model.name = name.dup
             end
             model.definition_location = call_stack
             setup_submodel(model, submodel_options, &block)

data/lib/metaruby/registration.rb

@@ -3,6 +3,7 @@ require 'facets/module/basename'
 require 'facets/kernel/call_stack'
 require 'utilrb/object/attribute'
 require 'utilrb/module/attr_predicate'
+
 module MetaRuby
     # Handling of registration of model hierarchies
     #
@@ -21,8 +22,10 @@ module MetaRuby
         # @return [Boolean]
         attr_predicate :permanent_model?, true
 
-        # @return [Set] the set of models that are children of this one
-        attribute(:submodels) { Set.new }
+        # @api private
+        #
+        # @return [Array<WeakRef>] the set of models that are children of this one
+        attribute(:submodels) { Array.new }
 
         # Returns the model that is parent of this one
         #
@@ -34,6 +37,11 @@ module MetaRuby
             end
         end
 
+        # Returns whether a model is a submodel of self
+        def has_submodel?(model)
+            each_submodel.any? { |m| m == model }
+        end
+
         # @return [Boolean] true if the definition context (module, class) in
         #   which self is registered is permanent or not w.r.t. the model
         #   registration functionality of metaruby
@@ -75,7 +83,7 @@ module MetaRuby
                 klass.definition_location = call_stack
             end
 
-            submodels << klass
+            submodels << WeakRef.new(klass)
             if m = supermodel
                 m.register_submodel(klass)
             end
@@ -84,11 +92,23 @@ module MetaRuby
         # Enumerates all models that are submodels of this class
         def each_submodel
             return enum_for(:each_submodel) if !block_given?
-            submodels.each do |obj|
-                yield(obj)
+            submodels.delete_if do |obj|
+                begin
+                    yield(obj.__getobj__)
+                    false
+                rescue WeakRef::RefError
+                    true
+                end
             end
         end
 
+        # Clears this model
+        #
+        # It deregisters sef if it is not a {#permanent_model?}, and clears the
+        # submodels
+        #
+        # Model classes and modules should also clear their respective
+        # attributes (if there are any)
         def clear_model
             if !permanent_model?
                 if m = supermodel
@@ -110,9 +130,9 @@ module MetaRuby
             constant("::#{obj.spacename}").send(:remove_const, obj.basename)
         end
 
-        # Clears all registered submodels
+        # Recursively deregisters all non-permanent submodels
         def clear_submodels
-            children = self.submodels.find_all { |m| !m.permanent_model? }
+            children = each_submodel.find_all { |m| !m.permanent_model? }
             if !children.empty?
                 deregister_submodels(children)
             end
@@ -130,25 +150,37 @@ module MetaRuby
             # We can call #clear_submodels while iterating here as it is a
             # constraint that all models in #submodels are permanent (and
             # will therefore not be removed)
-            submodels.each { |m| m.clear_submodels }
+            each_submodel { |m| m.clear_submodels }
             # And this the non-permanent ones
             children.each { |m| m.clear_submodels }
             true
         end
 
+        # @api private
+        #
         # Deregisters a set of submodels on this model and all its
         # supermodels
         #
         # This is usually not called directly. Use #clear_submodels instead
         #
-        # @param [ValueSet] set the set of submodels to remove
+        # @param [Set] set the set of submodels to remove
         def deregister_submodels(set)
-            current_size = submodels.size
-            submodels.subtract(set.to_value_set)
+            has_match = false
+            submodels.delete_if do |m|
+                begin
+                    m = m.__getobj__
+                    if set.include?(m)
+                        has_match = true
+                    end
+                rescue WeakRef::RefError
+                    true
+                end
+            end
+
             if m = supermodel
                 m.deregister_submodels(set)
             end
-            current_size != submodels.size
+            has_match
         end
     end
 end

data/lib/metaruby/test.rb

@@ -34,30 +34,26 @@ end
 module MetaRuby
     # This module is the common setup for all tests
     #
-    # It should be included in the toplevel describe blocks
+    # It is included in all the minitest tests
     #
     # @example
     #   require 'metaruby/test'
     #   describe MetaRuby do
-    #     include MetaRuby::SelfTest
+    #       # Use helpers methods from SelfTest here
     #   end
     #
     module SelfTest
+        # Common setup code for all metaruby tests
         def setup
-            # Setup code for all the tests
         end
 
+        # Common teardown code for all metaruby tests
         def teardown
         end
     end
 end
 
-module Minitest
-    class Spec
-        include MetaRuby::SelfTest
-    end
-    class Test
-        include MetaRuby::SelfTest
-    end
+class Minitest::Test
+    include MetaRuby::SelfTest
 end
 

data/lib/metaruby/version.rb

@@ -1,3 +1,4 @@
 module MetaRuby
-    VERSION = "1.0.0.rc2"
+    # The metaruby library version
+    VERSION = "1.0.0.rc3"
 end

data/lib/yard-metaruby.rb

@@ -1,14 +1,21 @@
 require 'pp'
 module MetaRuby
+    # Yard plugin to handle some of the metaruby DSL methods
+    #
+    # This is used by adding
+    #
+    #   --plugin metaruby
+    #
+    # to the .yardopts file
     module YARD
         include ::YARD
+
+        # Handling of {Attributes#inherited_attribute}
         class InheritedAttributeHandler < YARD::Handlers::Ruby::AttributeHandler
             handles method_call(:inherited_attribute)
             namespace_only
 
-            def self.process(handler, name, attr_name, is_map, key_name = nil, return_type = nil)
-            end
-
+            # Callback handled by YARD
             def process
                 name = statement.parameters[0].jump(:tstring_content, :ident).source
                 if statement.parameters.size == 4

data/manifest.xml

@@ -4,6 +4,7 @@
   <maintainer>Sylvain Joyeux/sylvain.joyeux@m4x.org</maintainer>
   <license>LGPLv3</license>
 
+  <depend package="bundler" />
   <depend package="utilrb" />
   <depend package="kramdown" optional="1" />
 </package>

data/metaruby.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |s|
     s.extra_rdoc_files = ["README.md"]
     s.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
 
-    s.add_runtime_dependency "utilrb", ">= 2.1.0.a"
+    s.add_runtime_dependency "utilrb", ">= 3.0.0.a"
     s.add_runtime_dependency "kramdown"
     s.add_development_dependency "flexmock", ">= 2.0.0"
     s.add_development_dependency "minitest", ">= 5.0", "~> 5.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metaruby
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc2
+  version: 1.0.0.rc3
 platform: ruby
 authors:
 - Sylvain Joyeux
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-26 00:00:00.000000000 Z
+date: 2015-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: utilrb
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.1.0.a
+        version: 3.0.0.a
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.1.0.a
+        version: 3.0.0.a
 - !ruby/object:Gem::Dependency
   name: kramdown
   requirement: !ruby/object:Gem::Requirement
@@ -106,6 +106,7 @@ files:
 - lib/metaruby/dsls/doc.rb
 - lib/metaruby/dsls/find_through_method_missing.rb
 - lib/metaruby/gui.rb
+- lib/metaruby/gui/exception_rendering.rb
 - lib/metaruby/gui/exception_view.rb
 - lib/metaruby/gui/html.rb
 - lib/metaruby/gui/html/button.rb