dsl_compose 1.11.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6a23cf9faddf37ebe1fdec13fe554e8e7601e01f5c53495d8d3d37f28a63faf
-  data.tar.gz: 7254f3f5c46716e462189c72d2bd02b0131cdca1fb39387a8b86fd79cb2e9c6c
+  metadata.gz: 45e24e8af1b43cc20cdfe1b9089c54812b774f9d377f4d74842b202d4b6bd1c2
+  data.tar.gz: 55ee3564fadfa1ff647a340a612ef1b840e616054008616565db52838ba2b2eb
 SHA512:
-  metadata.gz: c71462286d85bdc0b4f2d3879b08bf04a142b4f10bb9554c230fa263d80e69d08fe73bd3cc198d516d8950df1a8b39863823cf0993b3a80af2110b80de69f2a6
-  data.tar.gz: 5b03471c8e676610297c16312b517bd62692fa5d85e5a610aed709684058032764668550622c84089d4cc6b7240d76c2d6a9d21487a4abf074eecaf93b6c19bd
+  metadata.gz: 307a73bcdd19bda7531e329710d1c559f31f6635d2a7cd495e9cf9644e02db140e53e286ecb9aded78a64b2d11ae617f1178093cb857226346b55bce50fa5ae7
+  data.tar.gz: 837abd419951f900d30a234d0665ff12d2e6cb9ad43750fc2dc58b2d07a5b08a3c9de2faf9c4a0149da65ff4f3aa6381af5b5a67bb1d7c969c6d64429d5cbac8

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.13.0](https://github.com/craigulliott/dsl_compose/compare/v1.12.0...v1.13.0) (2023-07-17)
+
+
+### Features
+
+* added for_final_children_of, for_inherited_dsl and for_dsl_or_inherited_dsl methods to the parser ([#35](https://github.com/craigulliott/dsl_compose/issues/35)) ([b01a629](https://github.com/craigulliott/dsl_compose/commit/b01a629e1b18540cbbd90ba53090b41b8fb41dfd))
+
+## [1.12.0](https://github.com/craigulliott/dsl_compose/compare/v1.11.0...v1.12.0) (2023-07-13)
+
+
+### Features
+
+* parsers are now aware of class inheritance, and all classes now assume the DSL configurations of all their ancestors ([#33](https://github.com/craigulliott/dsl_compose/issues/33)) ([6a6cfb1](https://github.com/craigulliott/dsl_compose/commit/6a6cfb1fd9bb44c2ea949888c7b7be14ddc0cef8))
+
 ## [1.11.0](https://github.com/craigulliott/dsl_compose/compare/v1.10.0...v1.11.0) (2023-07-12)
 
 

data/README.md

@@ -241,19 +241,30 @@ A parser class can be used to process complicated DSLs. In the example below, a
 # create your own parser by creating a new class which extends DSLCompose::Parser
 MyParser < DSLCompose::Parser
   # `for_children_of` will process SomeBaseClass and yield the provided
-  # block once for every class which extends SomeBaseClass and uses at
-  # least one of the DSLs that have been defined on it.
+  # block once for every class which extends SomeBaseClass.
+  #
+  # If you only want to process classes at the end of the class hierarchy (classes
+  # which extend the provided base class, but do not have their own children) then
+  # use `for_final_children_of` instead of `for_children_of`
   for_children_of SomeBaseClass do |child_class:|
-    # `for_dsl` accepts a DSL name or an array of DSL names and will yield
-    # it's provided block once for each time a DSL of that name has been
-    # used on the child_class.
+    # `for_dsl` accepts a DSL name or an array of DSL names and will yield it's
+    # provided block once for each time a DSL of that name has been used
+    # directly on the child_class.
     #
-    # An error will be raised if any of the provided DSL names does not exist
+    # If you want to yield the provided block for classes which didn't directly use
+    # one of the provided DSLs, but the DSL was used on one of their ancestors, then
+    # use `for_inherited_dsl :dsl_name` instead of `for_dsl  :dsl_name`. If you want
+    # the block to yield whether the DSL was used directly on the provided class or
+    # anywhere in it's ancestor chain, then use `for_dsl_or_inherited_dsl :dsl_name`.
+    #
+    # An error will be raised if any of the provided DSL names does not exist.
     #
     # You can optionally provide keyword arguments which correspond to any
     # arguments that were defined for the DSL, if multiple dsl names are provided
     # then the requested dsl argument must be present on all DSLs otherwise an
-    # error will be raised.
+    # error will be raised. The parser is aware of class inheritance, and will
+    # consider a DSL to have been executed on the actual class it was used, and
+    # any classes which are descendants of that class
     for_dsl [:dsl1, :dsl2] do |dsl_name:, a_dsl_argument:|
       # `for_method` accepts a method name or an array of method names and will
       # yield it's provided block once for each time a method with this name is

data/lib/dsl_compose/interpreter.rb

@@ -40,9 +40,10 @@ module DSLCompose
       @executions.filter { |e| e.dsl.name == dsl_name }
     end
 
-    # Returns an array of all executions for a given name and class.
-    def class_dsl_executions klass, dsl_name
-      @executions.filter { |e| e.klass == klass && e.dsl.name == dsl_name }
+    # Returns an array of all executions for a given name and class. This includes
+    # any ancestors of the provided class
+    def class_dsl_executions klass, dsl_name, on_current_class, on_ancestor_class
+      @executions.filter { |e| e.dsl.name == dsl_name && ((on_current_class && e.klass == klass) || (on_ancestor_class && klass < e.klass)) }
     end
 
     # removes all executions from the interpreter, this is primarily used from

data/lib/dsl_compose/parser/for_children_of_parser/descendents.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class Parser
+    class ForChildrenOfParser
+      class Descendents
+        def initialize base_class, final_children_only
+          @base_class = base_class
+          @final_children_only = final_children_only
+        end
+
+        def classes
+          # all objects which extend the provided base class
+          extending_classes = ObjectSpace.each_object(Class).select { |klass| klass < @base_class }
+
+          # sort the results, classes are ordered first by the depth of their namespace, and second
+          # by their name
+          extending_classes.sort_by! do |child_class|
+            "#{child_class.name.split("::").count}_#{child_class.name}"
+          end
+
+          # if this is not a final child, but we are processing final children only, then skip it
+          if @final_children_only
+            # reject any classes which have descendents
+            extending_classes.reject! do |child_class|
+              has_descendents child_class
+            end
+          end
+
+          extending_classes
+        end
+
+        private
+
+        def has_descendents base_class
+          ObjectSpace.each_object(Class).count { |klass| klass < base_class } > 0
+        end
+      end
+    end
+  end
+end

data/lib/dsl_compose/parser/for_children_of_parser/for_dsl_parser.rb

@@ -20,7 +20,7 @@ module DSLCompose
         # of the provided name is used by the child class.
         #
         # base_class and child_class are set from the ForChildrenOfParser
-        def initialize base_class, child_class, dsl_names, &block
+        def initialize base_class, child_class, dsl_names, on_current_class, on_ancestor_class, &block
           @base_class = base_class
           @child_class = child_class
           @dsl_names = dsl_names
@@ -31,7 +31,7 @@ module DSLCompose
           end
 
           # if any arguments were provided, then assert that they are valid
-          if block.parameters.any?
+          if block&.parameters&.any?
             # all parameters must be keyword arguments
             if block.parameters.filter { |p| p.first != :keyreq }.any?
               raise AllBlockParametersMustBeKeywordParametersError, "All block parameters must be keyword parameters, i.e. `for_dsl :dsl_name do |dsl_name:|`"
@@ -62,7 +62,7 @@ module DSLCompose
           dsl_names.each do |dsl_name|
             # a dsl can be execued multiple times on a class, so we find all of the executions
             # here and then yield the block once for each execution
-            base_class.dsls.class_dsl_executions(child_class, dsl_name).each do |dsl_execution|
+            base_class.dsls.class_dsl_executions(child_class, dsl_name, on_current_class, on_ancestor_class).each do |dsl_execution|
               # we only provide the requested arguments to the block, this allows
               # us to use keyword arguments to force a naming convention on these arguments
               # and to validate their use

data/lib/dsl_compose/parser/for_children_of_parser.rb

@@ -15,9 +15,27 @@ module DSLCompose
       class NoChildClassError < StandardError
       end
 
-      # This class will yield to the provided block for each class which extends the base_class, provided
-      # that the child also uses at least one of the DSLs which have been defined on the base_class
-      def initialize base_class, &block
+      # This class will yield to the provided block for each descendant
+      # class of the provided base_class
+      #
+      # For example:
+      #
+      # class BaseClass
+      #   include DSLCompose::Composer
+      #   define_dsl :my_foo_dsl
+      # end
+      #
+      # class ChildClass < BaseClass
+      #   my_foo_dsl
+      # end
+      #
+      # class GrandchildClass < ChildClass
+      # end
+      #
+      # parser.for_children_of BaseClass do |child_class:|
+      #    # this will yield for ChildClass and GrandchildClass
+      # and
+      def initialize base_class, final_children_only, &block
         # assert the provided class has the DSLCompose::Composer module installed
         unless base_class.respond_to? :dsls
           raise ClassDoesNotUseDSLComposeError, base_class
@@ -31,23 +49,25 @@ module DSLCompose
         end
 
         # if any arguments were provided, then assert that they are valid
-        if block.parameters.any?
+        if block&.parameters&.any?
           # all parameters must be keyword arguments
           if block.parameters.filter { |p| p.first != :keyreq }.any?
             raise AllBlockParametersMustBeKeywordParametersError, "All block parameters must be keyword parameters, i.e. `for_children_of FooClass do |base_class:|`"
           end
         end
 
-        # yield the provided block for each child class of the provided base_class
-        # which uses a defined DSL
-        base_class.dsls.executions_by_class.each do |child_class, dsl|
+        # yeild the block for all descendents of the provided base_class
+        Descendents.new(base_class, final_children_only).classes.each do |child_class|
+          # determine which arguments to send to the block
           args = {}
           if BlockArguments.accepts_argument?(:child_class, &block)
             args[:child_class] = child_class
           end
+
           # set the child_class in an instance variable so that method calls to
           # `for_dsl` from within the block will have access to it
           @child_class = child_class
+
           # yield the block in the context of this class
           instance_exec(**args, &block)
         end
@@ -57,7 +77,7 @@ module DSLCompose
 
       # Given a dsl name, or array of dsl names, this method will yield to the
       # provided block once for each time a dsl with one of the provided names
-      # was used on the correspondng child_class
+      # was used on the correspondng child_class or any of its ancestors.
       #
       # The value of child_class and base_class are set from the yield of this
       # classes initializer, meaning that the use of this method should look
@@ -68,14 +88,38 @@ module DSLCompose
       #     ...
       #   end
       # end
-      def for_dsl dsl_names, &block
+      #
+      # If `on_current_class` is true, then the block will be yielded to for each DSL
+      # which was used directly on the current class. If `oncurrent_class` is false,
+      # then the block will not be yielded to for any DSL which was used directly on.
+      # If `on_ancestor_class` is true, then the block will be yielded to for each DSL
+      # which was used on any class in the current classes ancestry. If `on_ancestor_class`
+      # is false, then the block will not be yielded to for any DSL which was used on
+      # any class in the current classes ancestry.
+      def for_dsl dsl_names, on_current_class: true, on_ancestor_class: false, &block
         child_class = @child_class
 
         unless child_class
           raise NoChildClassError, "No child_class was found, please call this method from within a `for_children_of` block"
         end
 
-        ForDSLParser.new(@base_class, child_class, dsl_names, &block)
+        ForDSLParser.new(@base_class, child_class, dsl_names, on_current_class, on_ancestor_class, &block)
+      end
+
+      # this is a wrapper for the `for_dsl` method, but it provides a value of true
+      # for the `on_ancestor_class` argument and a value of false for the `on_current_class`
+      # argument. This will cause the parser to only yeild for dsls which were used on
+      # a class which is in the current classes ancestry, but not on the current class
+      def for_inherited_dsl dsl_names, &block
+        for_dsl dsl_names, on_current_class: false, on_ancestor_class: true, &block
+      end
+
+      # this is a wrapper for the `for_dsl` method, but it provides a value of true
+      # for the `on_ancestor_class` argument and a value of true for the `on_current_class`
+      # argument. This will cause the parser to yeild for dsls which were used on either
+      # the current class or any class in its ancestry
+      def for_dsl_or_inherited_dsl dsl_names, &block
+        for_dsl dsl_names, on_current_class: true, on_ancestor_class: true, &block
       end
     end
   end

data/lib/dsl_compose/parser.rb

@@ -24,30 +24,44 @@ module DSLCompose
       raise NotInitializable
     end
 
-    # the first step in defining a parser is to set the base_class, this method
+    # The first step in defining a parser is to set the base_class, this method
     # will yield to the provided block for each child class of the provided base_class
-    # provided that the child_class uses at least one of the base_classes defined DSLs
-    def self.for_children_of base_class, rerun = false, &block
+    # provided that the child_class uses at least one of the base_classes defined DSLs.
+    # If `final_children_only` is true, then this will cause the parser to only return
+    # classes which are at the end of their class hierachy (meaning they dont have any
+    # children of their own)
+    def self.for_children_of base_class, final_children_only: false, rerun: false, &block
       unless rerun
         @runs ||= []
         @runs << {
           base_class: base_class,
+          final_children_only: final_children_only,
           block: block
         }
       end
 
       # we parse the provided block in the context of the ForChildrenOfParser class
       # to help make this code more readable, and to limit polluting the current namespace
-      ForChildrenOfParser.new(base_class, &block)
+      ForChildrenOfParser.new(base_class, final_children_only, &block)
+    end
+
+    # this is a wrapper for the `for_children_of` method, but it provides a value
+    # of true for the `final_children_only` argument. This will cause the parser to only
+    # return classes which are at the end of the class hierachy (meaning they dont have
+    # any children of their own)
+    def self.for_final_children_of base_class, &block
+      for_children_of base_class, final_children_only: true, &block
     end
 
     # this method is used to rerun the parser, this is most useful from within a test suite
     # when you are testing the parser itself
     def self.rerun
+      # rerun each parset tests
       @runs&.each do |run|
         base_class = run[:base_class]
         block = run[:block]
-        for_children_of base_class, true, &block
+        final_children_only = run[:final_children_only]
+        for_children_of base_class, rerun: true, final_children_only: final_children_only, &block
       end
     end
   end

data/lib/dsl_compose/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DSLCompose
-  VERSION = "1.11.0"
+  VERSION = "1.13.0"
 end

data/lib/dsl_compose.rb

@@ -36,6 +36,7 @@ require "dsl_compose/interpreter"
 
 require "dsl_compose/parser/for_children_of_parser/for_dsl_parser/for_method_parser"
 require "dsl_compose/parser/for_children_of_parser/for_dsl_parser"
+require "dsl_compose/parser/for_children_of_parser/descendents"
 require "dsl_compose/parser/for_children_of_parser"
 require "dsl_compose/parser/block_arguments"
 require "dsl_compose/parser"
@@ -49,6 +50,4 @@ require "dsl_compose/shared_configuration"
 require "dsl_compose/dsls"
 
 module DSLCompose
-  class Error < StandardError
-  end
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: dsl_compose
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.13.0
 platform: ruby
 authors:
 - Craig Ulliott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-12 00:00:00.000000000 Z
-dependencies: []
+date: 2023-07-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: class_spec_helper
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Ruby gem to add dynamic DSLs to classes. DSLs are added to classes by
   including the DSLCompose module, and then calling the add_dsl singleton method within
   the class or a child class.
@@ -56,6 +70,7 @@ files:
 - lib/dsl_compose/parser.rb
 - lib/dsl_compose/parser/block_arguments.rb
 - lib/dsl_compose/parser/for_children_of_parser.rb
+- lib/dsl_compose/parser/for_children_of_parser/descendents.rb
 - lib/dsl_compose/parser/for_children_of_parser/for_dsl_parser.rb
 - lib/dsl_compose/parser/for_children_of_parser/for_dsl_parser/for_method_parser.rb
 - lib/dsl_compose/shared_configuration.rb