dsl_compose 2.15.3 → 2.15.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fd1fd8c1e9fa1f20c3a46fa9d27bd9aca1cf5f4529e8faa2e86ba5b972ef211
-  data.tar.gz: ca41bb7b1ef3f699b0d96baf77dee95fb27a7fcf0d26b7dcc37838b3a575dbff
+  metadata.gz: e0750c158e424591df6b08e2ac3786b689116b5850152b6f6fe51fc39092895a
+  data.tar.gz: 7e818d88dd0dde898b80faa4eb24f18eaa6ca8bd64a4c83fc974621ccee71e3e
 SHA512:
-  metadata.gz: 53328f870487ad66a45bf7d179a5085d39049a0eb02eefacaa7e38a386bdd2fa043cd9fb7a887888ed53156d6b6cdf9fe828e19c53fd0c768f8e81d3b666ec8d
-  data.tar.gz: d904bb0b9c0188755031e678099fa8644f5712433eea0471b0f581ea1247d6f29725766f638383d412bfb0fa7a187d1bcb5bba51ec61fd725ab171446cc87e7b
+  metadata.gz: a374a44e85a232cc6681c98034a1196cc7ccc077689a3f9bb75354aa54e0e02be8758a527de68944af95c81f04157b07df4bcaccab20877cfee48f2164eddad2
+  data.tar.gz: 73fd1c43e1677b42c2389a4919e0ced10feda5e35ca564d1d025376fbb357282f5d8bf7411980d3d9d744c46b6d50cbc2fa370314ad0c4de58093eec569fc53d

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.15.5](https://github.com/craigulliott/dsl_compose/compare/v2.15.4...v2.15.5) (2023-10-06)
+
+
+### Bug Fixes
+
+* added a first_use_only option to the parser so that only the most recent execution of a DSL will be used ([717293d](https://github.com/craigulliott/dsl_compose/commit/717293d906a183d8a13ffa1c4ae47e901de428a0))
+* specs and fixes for `first_use_only` option on parser ([a7dc087](https://github.com/craigulliott/dsl_compose/commit/a7dc0878ffef9a104c25d4f43d5796f939cb7567))
+
+## [2.15.4](https://github.com/craigulliott/dsl_compose/compare/v2.15.3...v2.15.4) (2023-10-04)
+
+
+### Bug Fixes
+
+* passing context along with where DSL's were defined, and then including this context in error messages ([5238a3d](https://github.com/craigulliott/dsl_compose/commit/5238a3daa8c1a32e77783d56c7c429b6335995bd))
+
 ## [2.15.3](https://github.com/craigulliott/dsl_compose/compare/v2.15.2...v2.15.3) (2023-10-03)
 
 

data/lib/dsl_compose/composer.rb

@@ -48,9 +48,11 @@ module DSLCompose
 
           # add a singleton method with the name of this new DSL onto our class, this is how our new DSL will be accessed
           define_singleton_method name do |*args, &block|
+            called_from = caller(1..1).first
+
             # when it is called, we process this new dynamic DSL with the interpreter
             # `self` here is the class in which the dsl is being used, not the class in which the DSL was defined
-            interpreter.execute_dsl self, dsl, *args, &block
+            interpreter.execute_dsl self, dsl, called_from, *args, &block
           end
 
         end

data/lib/dsl_compose/dsl/arguments/argument.rb

@@ -127,7 +127,7 @@ module DSLCompose
             Interpreter.new(self).instance_eval(&block)
           end
         rescue => e
-          raise e, "Error defining argument #{name}: #{e.message}", e.backtrace
+          raise e, "Error while defining argument #{name}\n#{e.message}", e.backtrace
         end
 
         # Set the description for this Argument to the provided value.

data/lib/dsl_compose/dsl/dsl_method.rb

@@ -60,7 +60,7 @@ module DSLCompose
           Interpreter.new(self).instance_eval(&block)
         end
       rescue => e
-        raise e, "Error defining method #{name}: #{e.message}", e.backtrace
+        raise e, "Error while defining method #{name}\n#{e.message}", e.backtrace
       end
 
       # Set the description for this DSLMethod to the provided value.

data/lib/dsl_compose/dsl.rb

@@ -83,8 +83,6 @@ module DSLCompose
       else
         raise NoBlockProvidedError, "No block was provided for this DSL"
       end
-    rescue => e
-      raise e, "Error defining DSL #{@name} on #{@klass}: #{e.message}", e.backtrace
     end
 
     # Set the description for this DSL to the provided value.

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

@@ -4,25 +4,27 @@ module DSLCompose
   class Interpreter
     class Execution
       class Arguments
-        class MissingRequiredArgumentsError < StandardError
+        class MissingRequiredArgumentsError < InterpreterError
         end
 
-        class TooManyArgumentsError < StandardError
+        class TooManyArgumentsError < InterpreterError
         end
 
-        class OptionalArgumentsShouldBeHashError < StandardError
+        class OptionalArgumentsShouldBeHashError < InterpreterError
         end
 
-        class InvalidArgumentTypeError < StandardError
+        class InvalidArgumentTypeError < InterpreterError
         end
 
-        class ArrayNotValidError < StandardError
+        class ArrayNotValidError < InterpreterError
         end
 
         attr_reader :arguments
+        attr_reader :called_from
 
-        def initialize arguments, *args
+        def initialize arguments, called_from, *args
           @arguments = {}
+          @called_from = called_from
 
           required_argument_count = arguments.required_arguments.count
           required_non_kwarg_argument_count = arguments.required_arguments.count { |a| !a.kwarg }
@@ -40,7 +42,7 @@ module DSLCompose
           required_kwargs = arguments.required_arguments.filter { |a| a.kwarg }
 
           if required_kwargs.any? && !all_kwargs.is_a?(Hash)
-            raise MissingRequiredArgumentsError, "This has required keyword arguments, but no keyword arguments were provided"
+            raise MissingRequiredArgumentsError.new("This has required keyword arguments, but no keyword arguments were provided", called_from)
           end
 
           required_kwargs.each do |required_kwarg|
@@ -51,7 +53,7 @@ module DSLCompose
               # left with only the optional args
               all_kwargs.delete required_kwarg.name
             else
-              raise MissingRequiredArgumentsError, "The required kwarg `#{required_kwarg.name}` was not provided"
+              raise MissingRequiredArgumentsError.new("The required kwarg `#{required_kwarg.name}` was not provided", called_from)
             end
           end
 
@@ -61,12 +63,12 @@ module DSLCompose
 
           # assert that a value is provided for every required argument
           unless required_argument_count == required_args.count
-            raise MissingRequiredArgumentsError, "This requires #{required_non_kwarg_argument_count} arguments, but only #{required_args.count} were provided"
+            raise MissingRequiredArgumentsError.new("This requires #{required_non_kwarg_argument_count} arguments, but only #{required_args.count} were provided", called_from)
           end
 
           # assert that too many arguments have not been provided
           if args.count > required_argument_count + (has_optional_arguments ? 1 : 0)
-            raise TooManyArgumentsError, "Too many arguments provided"
+            raise TooManyArgumentsError.new("Too many arguments provided", called_from)
           end
 
           # Assume all optonal arguments are their defaults (except booleans, which default to false).
@@ -88,7 +90,7 @@ module DSLCompose
           # asset that, if provided, then the optional argument (always the last one) is a Hash
           if has_optional_arguments && !optional_arg.nil?
             unless optional_arg.is_a? Hash
-              raise OptionalArgumentsShouldBeHashError, "If provided, then the optional arguments must be last, and be represented as a Hash"
+              raise OptionalArgumentsShouldBeHashError.new("If provided, then the optional arguments must be last, and be represented as a Hash", called_from)
             end
 
             # assert the each provided optional argument is valid
@@ -110,7 +112,7 @@ module DSLCompose
               end
 
               if optional_arg_value.is_a?(Array) && !optional_argument.array
-                raise ArrayNotValidError, "An array was provided to an argument which does not accept an array of values"
+                raise ArrayNotValidError.new("An array was provided to an argument which does not accept an array of values", called_from)
               end
 
               # to simplify the code, we always process the reset of the validations as an array, even
@@ -121,38 +123,38 @@ module DSLCompose
                 case optional_argument.type
                 when :integer
                   unless value.is_a? Integer
-                    raise InvalidArgumentTypeError, "`#{value}` is not an Integer"
+                    raise InvalidArgumentTypeError.new("`#{value}` is not an Integer", called_from)
                   end
                   optional_argument.validate_integer! value
 
                 when :float
                   # float allows either floats or integers
                   unless value.is_a?(Float) || value.is_a?(Integer)
-                    raise InvalidArgumentTypeError, "`#{value}` is not an Float or Integer"
+                    raise InvalidArgumentTypeError.new("`#{value}` is not an Float or Integer", called_from)
                   end
                   optional_argument.validate_float! value
 
                 when :symbol
                   unless value.is_a? Symbol
-                    raise InvalidArgumentTypeError, "`#{value}` is not a Symbol"
+                    raise InvalidArgumentTypeError.new("`#{value}` is not a Symbol", called_from)
                   end
                   optional_argument.validate_symbol! value
 
                 when :string
                   unless value.is_a? String
-                    raise InvalidArgumentTypeError, "`#{value}` is not a String"
+                    raise InvalidArgumentTypeError.new("`#{value}` is not a String", called_from)
                   end
                   optional_argument.validate_string! value
 
                 when :boolean
                   unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
-                    raise InvalidArgumentTypeError, "`#{value}` is not a boolean"
+                    raise InvalidArgumentTypeError.new("`#{value}` is not a boolean", called_from)
                   end
                   optional_argument.validate_boolean! value
 
                 when :class
                   unless value.is_a?(ClassCoerce)
-                    raise InvalidArgumentTypeError, "`#{value}` is not a class coerce (String)"
+                    raise InvalidArgumentTypeError.new("`#{value}` is not a class coerce (String)", called_from)
                   end
                   optional_argument.validate_class! value
 
@@ -160,7 +162,7 @@ module DSLCompose
                   optional_argument.validate_object! value
 
                 else
-                  raise InvalidArgumentTypeError, "The argument value `#{value}` is not a supported type"
+                  raise InvalidArgumentTypeError.new("The argument value `#{value}` is not a supported type", called_from)
                 end
               end
 
@@ -174,7 +176,7 @@ module DSLCompose
                 optional_arg_value
               end
             rescue => e
-              raise e, "Error processing optional argument #{optional_argument_name}: #{e.message}", e.backtrace
+              raise e, "Error processing optional argument #{optional_argument_name}\n#{e.message}", e.backtrace
             end
 
           end
@@ -200,7 +202,7 @@ module DSLCompose
             end
 
             if required_arg_value.is_a?(Array) && !required_argument.array
-              raise ArrayNotValidError, "An array was provided to an argument which does not accept an array of values"
+              raise ArrayNotValidError.new("An array was provided to an argument which does not accept an array of values", called_from)
             end
 
             # to simplify the code, we always process the reset of the validations as an array, even
@@ -211,38 +213,38 @@ module DSLCompose
               case required_argument.type
               when :integer
                 unless value.is_a? Integer
-                  raise InvalidArgumentTypeError, "`#{value}` is not an Integer"
+                  raise InvalidArgumentTypeError.new("`#{value}` is not an Integer", called_from)
                 end
                 required_argument.validate_integer! value
 
               when :float
                 # float allows either floats or integers
                 unless value.is_a?(Float) || value.is_a?(Integer)
-                  raise InvalidArgumentTypeError, "`#{value}` is not an Float or Integer"
+                  raise InvalidArgumentTypeError.new("`#{value}` is not an Float or Integer", called_from)
                 end
                 required_argument.validate_float! value
 
               when :symbol
                 unless value.is_a? Symbol
-                  raise InvalidArgumentTypeError, "`#{value}` is not a Symbol"
+                  raise InvalidArgumentTypeError.new("`#{value}` is not a Symbol", called_from)
                 end
                 required_argument.validate_symbol! value
 
               when :string
                 unless value.is_a? String
-                  raise InvalidArgumentTypeError, "`#{value}` is not a String"
+                  raise InvalidArgumentTypeError.new("`#{value}` is not a String", called_from)
                 end
                 required_argument.validate_string! value
 
               when :boolean
                 unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
-                  raise InvalidArgumentTypeError, "`#{value}` is not a boolean"
+                  raise InvalidArgumentTypeError.new("`#{value}` is not a boolean", called_from)
                 end
                 required_argument.validate_boolean! value
 
               when :class
                 unless value.is_a?(ClassCoerce)
-                  raise InvalidArgumentTypeError, "`#{value}` is not a class coerce (String)"
+                  raise InvalidArgumentTypeError.new("`#{value}` is not a class coerce (String)", called_from)
                 end
                 required_argument.validate_class! value
 
@@ -250,7 +252,7 @@ module DSLCompose
                 required_argument.validate_object! value
 
               else
-                raise InvalidArgumentTypeError, "The argument `#{value}` is not a supported type"
+                raise InvalidArgumentTypeError.new("The argument `#{value}` is not a supported type", called_from)
               end
             end
 
@@ -264,7 +266,7 @@ module DSLCompose
               required_arg_value
             end
           rescue => e
-            raise e, "Error processing required argument #{argument_name}: #{e.message}", e.backtrace
+            raise e, "Error processing required argument #{argument_name}\n#{e.message}", e.backtrace
           end
         end
 

data/lib/dsl_compose/interpreter/execution/method_calls/method_call.rb

@@ -5,15 +5,17 @@ module DSLCompose
     class Execution
       class MethodCalls
         class MethodCall
-          class InvalidDescriptionError < StandardError
+          class InvalidDescriptionError < InterpreterError
           end
 
           attr_reader :dsl_method
+          attr_reader :called_from
           attr_reader :arguments
 
-          def initialize dsl_method, *args, &block
+          def initialize dsl_method, called_from, *args, &block
             @dsl_method = dsl_method
-            @arguments = Arguments.new(dsl_method.arguments, *args)
+            @called_from = called_from
+            @arguments = Arguments.new(dsl_method.arguments, called_from, *args)
           end
 
           def method_name
@@ -30,7 +32,7 @@ module DSLCompose
           # generate documentation
           def add_parser_usage_note note
             unless note.is_a?(String) && note.strip.length > 0
-              raise InvalidDescriptionError, "The parser usage description `#{note}` is invalid, it must be of type string and have length greater than 0"
+              raise InvalidDescriptionError.new("The parser usage description `#{note}` is invalid, it must be of type string and have length greater than 0", @called_from)
             end
 
             @parser_usage_notes ||= []

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

@@ -14,16 +14,18 @@ module DSLCompose
           @method_calls.filter { |mc| mc.method_name == method_name }.any?
         end
 
-        def add_method_call(dsl_method, ...)
+        def add_method_call(dsl_method, called_from, ...)
           # make sure we always have a variable which can be used in the exception message
+          # set to nil first, so that if we get an exception while setting them
+          # it wont break the error message generation
           dsl_method_name = nil
           dsl_method_name = dsl_method.name
 
-          method_call = MethodCall.new(dsl_method, ...)
+          method_call = MethodCall.new(dsl_method, called_from, ...)
           @method_calls << method_call
           method_call
         rescue => e
-          raise e, "Error while executing method #{dsl_method_name}: #{e.message}", e.backtrace
+          raise e, "Error while executing method #{dsl_method_name}\n#{e.message}", e.backtrace
         end
 
         def method_calls_by_name method_name

data/lib/dsl_compose/interpreter/execution.rb

@@ -3,26 +3,28 @@
 module DSLCompose
   class Interpreter
     class Execution
-      class MethodIsUniqueError < StandardError
+      class MethodIsUniqueError < InterpreterError
       end
 
-      class RequiredMethodNotCalledError < StandardError
+      class RequiredMethodNotCalledError < InterpreterError
       end
 
-      class InvalidDescriptionError < StandardError
+      class InvalidDescriptionError < InterpreterError
       end
 
       attr_reader :dsl
+      attr_reader :called_from
       attr_reader :klass
       attr_reader :method_calls
       attr_reader :arguments
 
       # execute/process a dynamically defined DSL
-      def initialize klass, dsl, *args, &block
+      def initialize klass, dsl, called_from, *args, &block
         @klass = klass
         @dsl = dsl
+        @called_from = called_from
         @method_calls = MethodCalls.new
-        @arguments = Arguments.new(dsl.arguments, *args)
+        @arguments = Arguments.new(dsl.arguments, called_from, *args)
 
         # dynamically process the DSL by calling the provided block
         # all methods executions will be caught and processed by the method_missing method below
@@ -34,7 +36,7 @@ module DSLCompose
         dsl.required_dsl_methods.each do |dsl_method|
           unless @method_calls.method_called? dsl_method.name
             dsl_method_name = dsl_method&.name
-            raise RequiredMethodNotCalledError, "The method #{dsl_method_name} is required, but was not called within this DSL"
+            raise RequiredMethodNotCalledError.new("The method #{dsl_method_name} is required, but was not called within this DSL", called_from)
           end
         end
       end
@@ -43,7 +45,7 @@ module DSLCompose
       # generate documentation
       def add_parser_usage_note note
         unless note.is_a?(String) && note.strip.length > 0
-          raise InvalidDescriptionError, "The parser usage description `#{note}` is invalid, it must be of type string and have length greater than 0"
+          raise InvalidDescriptionError.new("The parser usage description `#{note}` is invalid, it must be of type string and have length greater than 0", called_from)
         end
 
         @parser_usage_notes ||= []
@@ -60,15 +62,17 @@ module DSLCompose
 
       # catch and process any method calls within the DSL block
       def method_missing(method_name, ...)
+        called_from = caller(1..1).first
+
         # if the method does not exist, then this will raise a MethodDoesNotExistError
         dsl_method = @dsl.dsl_method method_name
 
         # if the method is unique, then it can only be called once per DSL
         if dsl_method.unique? && @method_calls.method_called?(method_name)
-          raise MethodIsUniqueError, "This method `#{method_name}` is unique and can only be called once within this DSL"
+          raise MethodIsUniqueError.new("This method `#{method_name}` is unique and can only be called once within this DSL", called_from)
         end
 
-        @method_calls.add_method_call(dsl_method, ...)
+        @method_calls.add_method_call(dsl_method, called_from, ...)
       end
 
       def respond_to_missing?(method_name, *args)

data/lib/dsl_compose/interpreter/interpreter_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class Interpreter
+    class InterpreterError < StandardError
+      attr_reader :original_context
+
+      def initialize(message, original_context)
+        super(message)
+        @original_context = original_context
+      end
+
+      def to_s
+        "#{super}\ndsl source: #{@original_context}"
+      end
+    end
+  end
+end

data/lib/dsl_compose/interpreter.rb

@@ -4,10 +4,7 @@ module DSLCompose
   # The class is reponsible for parsing and executing a dynamic DSL (dynamic DSLs are
   # created using the DSLCompose::DSL class).
   class Interpreter
-    class DSLExecutionNotFoundError < StandardError
-    end
-
-    class InvalidDescriptionError < StandardError
+    class InvalidDescriptionError < InterpreterError
     end
 
     # A dynamic DSL can be used multiple times on the same class, each time the DSL is used
@@ -23,7 +20,7 @@ module DSLCompose
     # generate documentation
     def add_parser_usage_note child_class, note
       unless note.is_a?(String) && note.strip.length > 0
-        raise InvalidDescriptionError, "The parser usage description `#{note}` is invalid, it must be of type string and have length greater than 0"
+        raise InvalidDescriptionError.new("The parser usage description `#{note}` is invalid, it must be of type string and have length greater than 0", called_from)
       end
       @parser_usage_notes ||= {}
       @parser_usage_notes[child_class] ||= []
@@ -40,20 +37,23 @@ module DSLCompose
     # Execute/process a dynamically defined DSL on a class.
     # `klass` is the class in which the DSL is being used, not
     # the class in which the DSL was defined.
-    def execute_dsl(klass, dsl, ...)
+    def execute_dsl(klass, dsl, called_from, ...)
       # make sure we have these variables for the exception message below
+      # set to nil first, so that if we get an exception while setting them
+      # it wont break the error message generation
       class_name = nil
-      class_name = klass.name
       dsl_name = nil
+      class_name = klass.name
       dsl_name = dsl.name
 
-      execution = Execution.new(klass, dsl, ...)
+      execution = Execution.new(klass, dsl, called_from, ...)
       @executions << execution
       execution
     rescue => e
-      raise e, "Error processing dsl #{dsl_name} for class #{class_name}: #{e.message}", e.backtrace
+      raise e, "Error while defining DSL #{dsl_name} for class #{class_name}:\n#{e.message}", e.backtrace
     end
 
+    #
     # Returns an array of all executions for a given class.
     def class_executions klass
       @executions.filter { |e| e.klass == klass }
@@ -66,8 +66,15 @@ 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, 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)) }
+    def class_dsl_executions klass, dsl_name, on_current_class, on_ancestor_class, first_use_only
+      filtered_executions = @executions.filter { |e| e.dsl.name == dsl_name && ((on_current_class && e.klass == klass) || (on_ancestor_class && klass < e.klass)) }
+      # Because the classes were evaluated in order, we can just return the
+      # last execution
+      if first_use_only && filtered_executions.length > 0
+        [filtered_executions.last]
+      else
+        filtered_executions
+      end
     end
 
     # returns the most recent, closest single execution of a dsl with the
@@ -83,7 +90,7 @@ module DSLCompose
       # note that this method does not need to do any special sorting, the required
       # order for getting the most recent execution is already guaranteed because
       # parent classes in ruby always have to be evaluated before their descendants
-      class_dsl_executions(klass, dsl_name, true, true).last
+      class_dsl_executions(klass, dsl_name, true, true, false).last
     end
 
     # removes all executions from the interpreter, and any parser_usage_notes

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

@@ -28,6 +28,8 @@ module DSLCompose
             @dsl_execution = dsl_execution
             @method_names = method_names
 
+            dsl_name = dsl_execution.dsl.name
+
             # assert that a block was provided
             unless block
               raise NoBlockProvided
@@ -100,6 +102,14 @@ module DSLCompose
 
                 # yeild the block in the context of this class
                 instance_exec(**args, &block)
+              rescue => e
+                # if this is an InterpreterError, then it already has the called_from metadata
+                # just continue raising the original error
+                if e.is_a? Interpreter::InterpreterError
+                  raise
+                end
+                # otherwise, decorate the error with where the DSL was defined
+                raise e, "#{e.message}\nparsing class: #{child_class.name}\ndsl name: #{dsl_name}\ndsl method name: #{method_name}\ndsl source: #{method_call.called_from}", e.backtrace
               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, on_current_class, on_ancestor_class, &block
+        def initialize base_class, child_class, dsl_names, on_current_class, on_ancestor_class, first_use_only, &block
           @base_class = base_class
           @child_class = child_class
           @dsl_names = dsl_names
@@ -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, on_current_class, on_ancestor_class).each do |dsl_execution|
+            base_class.dsls.class_dsl_executions(child_class, dsl_name, on_current_class, on_ancestor_class, first_use_only).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
@@ -108,6 +108,14 @@ module DSLCompose
               @dsl_execution = dsl_execution
               # yield the block in the context of this class
               instance_exec(**args, &block)
+            rescue => e
+              # if this is an InterpreterError, then it already has the called_from metadata
+              # just continue raising the original error
+              if e.is_a? Interpreter::InterpreterError
+                raise
+              end
+              # otherwise, decorate the error with where the DSL was defined
+              raise e, "#{e.message}\nparsing class: #{child_class.name}\ndsl name: #{dsl_name}\ndsl source: #{dsl_execution.called_from}", e.backtrace
             end
           end
         end

data/lib/dsl_compose/parser/for_children_of_parser.rb

@@ -90,36 +90,42 @@ module DSLCompose
       # end
       #
       # 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.
+      # which was used directly on the current class. If `on_current_class` is false,
+      # then the block will not be yielded to for any DSL which was used directly on it.
       # 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
+      #
+      # If `first_use_only` is true, then this block will only yeild once for each subject class
+      # which directly uses or inherits use of the provided DSL. The DSL execution which occurs
+      # first in the class will be selected, and if the class does not use the DSL then each of
+      # the classes ancestors will be tested until an execution is found (only the current class
+      # will be tested if skip_inherited_dsls has been set to true).
+      def for_dsl dsl_names, on_current_class: true, on_ancestor_class: false, first_use_only: 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, on_current_class, on_ancestor_class, &block)
+        ForDSLParser.new(@base_class, child_class, dsl_names, on_current_class, on_ancestor_class, first_use_only, &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
+      def for_inherited_dsl dsl_names, first_use_only: false, &block
+        for_dsl dsl_names, on_current_class: false, on_ancestor_class: true, first_use_only: first_use_only, &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
+      def for_dsl_or_inherited_dsl dsl_names, first_use_only: false, &block
+        for_dsl dsl_names, on_current_class: true, on_ancestor_class: true, first_use_only: first_use_only, &block
       end
 
       # takes a description of what this parser does and stores it against the DSL definition

data/lib/dsl_compose/reader.rb

@@ -89,7 +89,7 @@ module DSLCompose
     # Returns an array of ExecutionReaders to represent each time the DSL was used
     # on the provided class.
     def executions
-      @dsl_defining_class.dsls.class_dsl_executions(@klass, @dsl_name, true, false).map do |execution|
+      @dsl_defining_class.dsls.class_dsl_executions(@klass, @dsl_name, true, false, false).map do |execution|
         ExecutionReader.new execution
       end
     end
@@ -100,7 +100,7 @@ module DSLCompose
     # earliest ancestor first and if the DSL was used more than once on a class then
     # the order they were used.
     def ancestor_executions
-      @dsl_defining_class.dsls.class_dsl_executions(@klass, @dsl_name, false, true).map do |execution|
+      @dsl_defining_class.dsls.class_dsl_executions(@klass, @dsl_name, false, true, false).map do |execution|
         ExecutionReader.new execution
       end
     end
@@ -110,7 +110,7 @@ module DSLCompose
     # be returned in the order they were executed, which is the earliest ancestor first
     # and if the DSL was used more than once on a class then the order they were used.
     def all_executions
-      @dsl_defining_class.dsls.class_dsl_executions(@klass, @dsl_name, true, true).map do |execution|
+      @dsl_defining_class.dsls.class_dsl_executions(@klass, @dsl_name, true, true, false).map do |execution|
         ExecutionReader.new execution
       end
     end

data/lib/dsl_compose/version.rb

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

data/lib/dsl_compose.rb

@@ -34,6 +34,7 @@ require "dsl_compose/reader/execution_reader/arguments_reader"
 
 require "dsl_compose/reader_base"
 
+require "dsl_compose/interpreter/interpreter_error"
 require "dsl_compose/interpreter/execution/method_calls/method_call"
 require "dsl_compose/interpreter/execution/method_calls"
 require "dsl_compose/interpreter/execution/arguments"

data/sig/dsl_compose/interpreter/execution/arguments.rbs

@@ -4,23 +4,24 @@ module DSLCompose
     class Execution
       class Arguments
         attr_reader arguments: Hash[untyped, untyped]
-        def initialize: (untyped arguments, *untyped args) -> void
+        attr_reader called_from: String
+
+        def initialize: (untyped arguments, String called_from, *untyped args) -> void
         def to_h: -> Hash[untyped, untyped]
 
-        class MissingRequiredArgumentsError < StandardError
-          def initialize: (untyped required_count, untyped provided_count) -> void
+        class MissingRequiredArgumentsError < InterpreterError
         end
 
-        class TooManyArgumentsError < StandardError
+        class TooManyArgumentsError < InterpreterError
         end
 
-        class OptionalArgumentsShouldBeHashError < StandardError
+        class OptionalArgumentsShouldBeHashError < InterpreterError
         end
 
-        class InvalidArgumentTypeError < StandardError
+        class InvalidArgumentTypeError < InterpreterError
         end
 
-        class ArrayNotValidError < StandardError
+        class ArrayNotValidError < InterpreterError
         end
       end
     end

data/sig/dsl_compose/interpreter/execution/method_calls/method_call.rbs

@@ -4,21 +4,22 @@ module DSLCompose
     class Execution
       class MethodCalls
         class MethodCall
-          class InvalidDescriptionError < StandardError
-          end
-
           @method_call: MethodCall
           @parser_usage_notes: Array[String]
 
           attr_reader dsl_method: DSL::DSLMethod
+          attr_reader called_from: String
           attr_reader arguments: Arguments
 
-          def initialize: (DSL::DSLMethod dsl_method, *untyped args) -> void
+          def initialize: (DSL::DSLMethod dsl_method, String called_from, *untyped args) -> void
           def method_name: -> Symbol
           def add_parser_usage_note: (String note) -> void
           def parser_usage_notes: () -> Array[String]
 
           def to_h: -> Hash[untyped, untyped]
+
+          class InvalidDescriptionError < InterpreterError
+          end
         end
       end
     end

data/sig/dsl_compose/interpreter/execution/method_calls.rbs

@@ -9,7 +9,7 @@ module DSLCompose
         def method_calls: () -> Array[MethodCall]
         def method_called?: (Symbol method_name) -> bool
         def method_calls_by_name: (Symbol method_name) -> Array[MethodCall]
-        def add_method_call: (DSL::DSLMethod dsl_method, *untyped args) -> MethodCall
+        def add_method_call: (DSL::DSLMethod dsl_method, String called_from, *untyped args) -> MethodCall
       end
     end
   end

data/sig/dsl_compose/interpreter/execution.rbs

@@ -5,11 +5,12 @@ module DSLCompose
       @parser_usage_notes: Array[String]
 
       attr_reader dsl: DSL
+      attr_reader called_from: String
       attr_reader klass: Object
       attr_reader method_calls: MethodCalls
       attr_reader arguments: Arguments
 
-      def initialize: (Object klass, DSL dsl, *untyped args) -> void
+      def initialize: (Object klass, DSL dsl, String called_from, *untyped args) -> void
       def instance_eval: () -> void
       def add_parser_usage_note: (String note) -> void
       def parser_usage_notes: () -> Array[String]
@@ -18,11 +19,15 @@ module DSLCompose
       def method_missing: (Symbol method_name, *untyped args) -> untyped
       def respond_to_missing?: (Symbol method_name, *untyped args) -> untyped
 
-      class MethodIsUniqueError < StandardError
+      class MethodIsUniqueError < InterpreterError
       end
 
-      class RequiredMethodNotCalledError < StandardError
+      class RequiredMethodNotCalledError < InterpreterError
       end
+
+      class InvalidDescriptionError < InterpreterError
+      end
+
     end
   end
 end

data/sig/dsl_compose/interpreter/interpreter_error.rbs

@@ -0,0 +1,11 @@
+
+# Classes
+module DSLCompose
+  class Interpreter
+    class InterpreterError < StandardError
+      attr_reader original_context: String
+      def initialize: (String message, String original_context) -> void
+      def to_s: -> String
+    end
+  end
+end

data/sig/dsl_compose/interpreter.rbs

@@ -12,10 +12,7 @@ module DSLCompose
     def add_parser_usage_note: (singleton(Object) klass, String note) -> void
     def parser_usage_notes: (singleton(Object) klass) -> Array[String]
 
-    class InvalidDescriptionError < StandardError
-    end
-
-    class DSLExecutionNotFoundError < StandardError
+    class InvalidDescriptionError < InterpreterError
     end
   end
 end

data/sig/dsl_compose/parser/for_children_of_parser/for_dsl_parser.rbs

@@ -8,7 +8,7 @@ module DSLCompose
         @dsl_names: Array[Symbol]
         @dsl_execution: Interpreter::Execution
 
-        def initialize: (singleton(Object) base_class, singleton(Object) child_class, Array[Symbol] dsl_names, bool on_current_class, bool on_ancestor_class) -> void
+        def initialize: (singleton(Object) base_class, singleton(Object) child_class, Array[Symbol] dsl_names, bool on_current_class, bool on_ancestor_class, bool first_use_only) -> void
 
         # overriding this method because steep doesn't
         # correctly infer that a block is being passed to this method

data/sig/dsl_compose/parser/for_children_of_parser.rbs

@@ -14,10 +14,12 @@ module DSLCompose
       ) -> void
 
       private
-      def for_dsl: (Array[Symbol] dsl_names, ?on_current_class: bool, ?on_ancestor_class: bool) -> untyped
+      def for_dsl: (Array[Symbol] dsl_names, ?on_current_class: bool, ?on_ancestor_class: bool, ?first_use_only: bool) -> untyped
+      def for_inherited_dsl: (Array[Symbol] dsl_names, ?first_use_only: bool) -> untyped
+      def for_dsl_or_inherited_dsl: (Array[Symbol] dsl_names, ?first_use_only: bool) -> untyped
 
       class AllBlockParametersMustBeKeywordParametersError < StandardError
-        end
+      end
 
       class ClassDoesNotUseDSLComposeError < StandardError
       end
@@ -26,7 +28,7 @@ module DSLCompose
       end
 
       class NoChildClassError < StandardError
-        end
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dsl_compose
 version: !ruby/object:Gem::Version
-  version: 2.15.3
+  version: 2.15.5
 platform: ruby
 authors:
 - Craig Ulliott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-10-03 00:00:00.000000000 Z
+date: 2023-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: class_spec_helper
@@ -67,6 +67,7 @@ files:
 - lib/dsl_compose/interpreter/execution/arguments.rb
 - lib/dsl_compose/interpreter/execution/method_calls.rb
 - lib/dsl_compose/interpreter/execution/method_calls/method_call.rb
+- lib/dsl_compose/interpreter/interpreter_error.rb
 - lib/dsl_compose/parser.rb
 - lib/dsl_compose/parser/block_arguments.rb
 - lib/dsl_compose/parser/for_children_of_parser.rb
@@ -109,6 +110,7 @@ files:
 - sig/dsl_compose/interpreter/execution/arguments.rbs
 - sig/dsl_compose/interpreter/execution/method_calls.rbs
 - sig/dsl_compose/interpreter/execution/method_calls/method_call.rbs
+- sig/dsl_compose/interpreter/interpreter_error.rbs
 - sig/dsl_compose/parser.rbs
 - sig/dsl_compose/parser/block_arguments.rbs
 - sig/dsl_compose/parser/for_children_of_parser.rbs