dsl_compose 1.12.0 → 1.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a22a3595bbf6990c27628cf872f751939156cc9cda865d6ae05ca9cd6e6ba544
-  data.tar.gz: 79fcd4ddb46ecc10cc1dd84f50515c4bb85067a0b26482d7a6250112b4d44fc8
+  metadata.gz: 9ca102e9e28dc1732f0a6c14282bdfc6b0cbc3edddc8b76864921c8d5a295ec0
+  data.tar.gz: 349941451a9954f29938fb91b0324662b306d215ce725e68faa00d25937b883d
 SHA512:
-  metadata.gz: 4cc5bf277a33d63d0dba6aa3053bfec1b5154d7f337c7e0e6fd0db2e5f429718e12097b640069904e44d95d02d2d576604d571cc45c96687ab8316064b4de3a7
-  data.tar.gz: 52a29affc55dd62fe4abbc965dc22973c1a01ba7acc170e33e8f7191ddf1ab19e4456f288cf69864282bea49afa8ac445ce1c1316053c07a6b4f2ef0ef1ba10a
+  metadata.gz: '002348ac24e6f8bf513478702c6c08368fb1ee8c788ad8a893d7a848e41103ee6208e5e24f260e0be79eb069700047d408b0c51e51ea3b861bccf55fe2312882'
+  data.tar.gz: 14431a1691709376eb73196c5c7280a7d0ec451d4eb58a3e8ffa3bc43bb6cf26f4433b8f4d6fb488db57d9be06bbcf4f974e5175719d44766a1247271ea76e34

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.13.1](https://github.com/craigulliott/dsl_compose/compare/v1.13.0...v1.13.1) (2023-07-19)
+
+
+### Bug Fixes
+
+* unused optional arguments no longer raise an error within the parser ([#37](https://github.com/craigulliott/dsl_compose/issues/37)) ([99cd04b](https://github.com/craigulliott/dsl_compose/commit/99cd04b83387c7940e364dc86d527fdb51152405))
+
+## [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)
 
 

data/README.md

@@ -241,13 +241,23 @@ 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
+  # 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

data/lib/dsl_compose/interpreter/execution/arguments.rb

@@ -44,6 +44,13 @@ module DSLCompose
             raise TooManyArgumentsError, "Too many arguments provided"
           end
 
+          # assume all optonal arguments are nil. If actual values were provided, then they will be set below
+          if arguments.optional_arguments.any?
+            arguments.optional_arguments.each do |optional_argument|
+              @arguments[optional_argument.name] = nil
+            end
+          end
+
           # asset that, if provided, then the optional argument (always the last one) is a Hash
           if has_optional_arguments && optional_arg.nil? === false
             unless optional_arg.is_a? Hash

data/lib/dsl_compose/interpreter.rb

@@ -42,8 +42,8 @@ module DSLCompose
 
     # 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
-      @executions.filter { |e| e.dsl.name == dsl_name && (e.klass == klass || klass < e.klass) }
+    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

@@ -35,7 +35,7 @@ module DSLCompose
       # parser.for_children_of BaseClass do |child_class:|
       #    # this will yield for ChildClass and GrandchildClass
       # and
-      def initialize base_class, &block
+      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
@@ -49,7 +49,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_children_of FooClass do |base_class:|`"
@@ -57,14 +57,17 @@ module DSLCompose
         end
 
         # yeild the block for all descendents of the provided base_class
-        ObjectSpace.each_object(Class).select { |klass| klass < base_class }.each do |child_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
@@ -85,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.12.0"
+  VERSION = "1.13.1"
 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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dsl_compose
 version: !ruby/object:Gem::Version
-  version: 1.12.0
+  version: 1.13.1
 platform: ruby
 authors:
 - Craig Ulliott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-13 00:00:00.000000000 Z
+date: 2023-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: class_spec_helper
@@ -70,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