dsl_compose 1.10.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4269fe819882b592d12b6cce51673a6ef4d87116521ff267c76a7a23aab0382
-  data.tar.gz: 9f13611b9417a7e34f0f81d4ccfda152eb5593168a483a011ccf2949a5624937
+  metadata.gz: c6a23cf9faddf37ebe1fdec13fe554e8e7601e01f5c53495d8d3d37f28a63faf
+  data.tar.gz: 7254f3f5c46716e462189c72d2bd02b0131cdca1fb39387a8b86fd79cb2e9c6c
 SHA512:
-  metadata.gz: 8923178c3d5ce6ab78229eb22a86412f2b4e7c9da41528b0b752965438dde12c6e8bfb1930880433ab4db2490efd36e15243e907f402544e4c2281a0b81f42e4
-  data.tar.gz: e5a0d13825e052290e865365a933b36f6dedcc668f5642283e7f6cbe227617697e83898dec9224179f9f569aa7727a1a6b796201441377431d19ba2235d69fd3
+  metadata.gz: c71462286d85bdc0b4f2d3879b08bf04a142b4f10bb9554c230fa263d80e69d08fe73bd3cc198d516d8950df1a8b39863823cf0993b3a80af2110b80de69f2a6
+  data.tar.gz: 5b03471c8e676610297c16312b517bd62692fa5d85e5a610aed709684058032764668550622c84089d4cc6b7240d76c2d6a9d21487a4abf074eecaf93b6c19bd

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.11.0](https://github.com/craigulliott/dsl_compose/compare/v1.10.0...v1.11.0) (2023-07-12)
+
+
+### Features
+
+* arguments can optionally accept arrays of values, also added a :class and :object type, and an associated "is_a" validator for :object ([#31](https://github.com/craigulliott/dsl_compose/issues/31)) ([acd7034](https://github.com/craigulliott/dsl_compose/commit/acd70345a4d1873e657d0e897f527269ca320453))
+
 ## [1.10.0](https://github.com/craigulliott/dsl_compose/compare/v1.9.1...v1.10.0) (2023-07-11)
 
 

data/README.md

@@ -54,7 +54,9 @@ class Foo
     # `required`)
     #
     # Arguments are validated, and their expected type must be defined. Supported
-    # argument types are :integer, :boolean, :float, :string or :symbol
+    # argument types are :integer, :boolean, :float, :string, :symbol, :class or :object
+    # when :class is used, it should be provided to your final DSL as a string of the
+    # classes name, such as "Users::UserModel" and not the actual class.
     requires :first_dsl_argument, :symbol do
       # You should provide descriptions for your arguments. These descriptions will
       # be used when generating your documentation. This description supports markdown
@@ -111,6 +113,16 @@ class Foo
         # You can add validation to your arguments. A full list is provided later in this document
         validate_greater_than 0
       end
+
+      # All optional and required arguments can optionally accept an array of values. When using
+      # your final DSL, a single item can be provided but will automatically be converted to an
+      # array of items. All items in the array must be of the expected type.
+      optional :another_optional_argument, :object, array: true do
+        description "A description of an optional argument which accepts an array"
+
+        # You can add validation to your arguments. A full list is provided later in this document
+        validate_is_a Date
+      end
     end
 
   end
@@ -414,6 +426,42 @@ The following validations can be added to the arguments of your DSL methods. Val
   end
 ```
 
+### Class attributes (:class)
+
+```ruby
+  define_dsl :my_dsl do
+    add_method :my_method do
+
+      requires :my_first_argument, :class do
+
+        # There are no validations for :class types
+
+      end
+
+    end
+  end
+```
+
+### Object attributes (:object)
+
+```ruby
+  define_dsl :my_dsl do
+    add_method :my_method do
+
+      requires :my_first_argument, :object do
+
+        # The provided attribute must be an instantiated object which
+        # is an instance of the class.
+        #
+        # For example, this would accept a regexp object such as /[a-z]+/
+        validate_is_a Regexp
+
+      end
+
+    end
+  end
+```
+
 
 ## Development
 

data/lib/dsl_compose/class_coerce.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class ClassCoerce
+    class UnexpectedClassNameError < StandardError
+    end
+
+    def initialize class_name
+      unless class_name.is_a? String
+        raise UnexpectedClassNameError, "expected `#{class_name}` to be a String"
+      end
+
+      @class_name = class_name
+    end
+
+    def to_class
+      Object.const_get @class_name
+    end
+  end
+end

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

@@ -100,6 +100,11 @@ module DSLCompose
             @argument.validate_format regexp
           end
 
+          # adds an 'is a' validator to the argument
+          def validate_is_a klass
+            @argument.validate_is_a klass
+          end
+
           # executes the shared configuration block with the given name within the
           # context of this part of the DSL, this is a mechanism to share configuration
           # between DSLs

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class DSL
+    class Arguments
+      class Argument
+        class IsAValidation
+          class ValidationFailedError < StandardError
+          end
+
+          def initialize value
+            @value = value
+          end
+
+          def validate! value
+            raise ValidationFailedError, "The argument is invalid. Expected #{value} to be an instance of #{@value}" unless value.is_a?(@value)
+            true
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -42,6 +42,9 @@ module DSLCompose
         attr_reader :type
         # if required, then this Argument must be provided when calling its associated DSLMethod.
         attr_reader :required
+        # If true, then this argument accepts an array of values. It will also accept a single value,
+        # but that single value will be automatically converted to an array
+        attr_reader :array
         # An otional description of this Attribute, if provided then it must be a string.
         # The description accepts markdown and is used when generating documentation.
         attr_reader :description
@@ -61,6 +64,7 @@ module DSLCompose
         attr_reader :start_with_validation
         attr_reader :not_start_with_validation
         attr_reader :length_validation
+        attr_reader :is_a_validation
 
         # Create a new Attribute object.
         #
@@ -69,7 +73,7 @@ module DSLCompose
         # calling its associated DSLMethod.
         # `type` can be either :integer, :boolean, :float, :string or :symbol
         # `block` contains the instructions to further configure this Attribute
-        def initialize name, required, type, &block
+        def initialize name, required, type, array: false, &block
           if name.is_a? Symbol
 
             if RESERVED_ARGUMENT_NAMES.include? name
@@ -81,14 +85,16 @@ module DSLCompose
             raise InvalidNameError, "The option name `#{name}` is invalid, it must be of type symbol."
           end
 
-          if type == :integer || type == :boolean || type == :float || type == :string || type == :symbol
+          if type == :integer || type == :boolean || type == :float || type == :string || type == :symbol || type == :class || type == :object
             @type = type
           else
-            raise InvalidTypeError, "Argument type `#{type}` must be one of :integer, :boolean, :float, :string or :symbol"
+            raise InvalidTypeError, "Argument type `#{type}` must be one of :integer, :boolean, :float, :string, :symbol, :class or :object"
           end
 
           @required = required ? true : false
 
+          @array = array ? true : false
+
           # If a block was provided, then we evaluate it using a seperate
           # interpreter class. We do this because the interpreter class contains
           # no other methods or variables, if it was evaluated in the context of
@@ -331,6 +337,18 @@ module DSLCompose
           @length_validation = LengthValidation.new(maximum: maximum, minimum: minimum, is: is)
         end
 
+        def validate_is_a klass
+          if @is_a_validation
+            raise ValidationAlreadyExistsError, "The validation `is_a` has already been applied to this method option."
+          end
+
+          unless @type == :object
+            raise ValidationIncompatibleError, "The validation type #{@type} is not compatible with this argument type"
+          end
+
+          @is_a_validation = IsAValidation.new(klass)
+        end
+
         # returns true if every provided integer validation also returns true
         def validate_integer! value
           (greater_than_validation.nil? || greater_than_validation.validate!(value)) &&
@@ -374,6 +392,17 @@ module DSLCompose
         def validate_boolean! value
           (equal_to_validation.nil? || equal_to_validation.validate!(value))
         end
+
+        # returns true if every provided class validation also returns true
+        def validate_class! value
+          # there are no class validations
+          true
+        end
+
+        # returns true if every provided object validation also returns true
+        def validate_object! value
+          (is_a_validation.nil? || is_a_validation.validate!(value))
+        end
       end
     end
   end

data/lib/dsl_compose/dsl/arguments.rb

@@ -81,7 +81,7 @@ module DSLCompose
       # Argument `name` must be unique within the DSLMethod.
       # `required` must be a boolean, and determines if this argument will be required
       # or optional on the method which is exposed in our DSL.
-      def add_argument name, required, type, &block
+      def add_argument name, required, type, array: false, &block
         if @arguments.key? name
           raise ArgumentAlreadyExistsError, "An argument with the name `#{name}` already exists for this DSL method"
         end
@@ -91,7 +91,7 @@ module DSLCompose
           raise ArgumentOrderingError, "Required arguments can not be added after optional ones"
         end
 
-        @arguments[name] = Argument.new(name, required, type, &block)
+        @arguments[name] = Argument.new(name, required, type, array: array, &block)
       end
     end
   end

data/lib/dsl_compose/dsl/dsl_method/interpreter.rb

@@ -38,8 +38,8 @@ module DSLCompose
         # `type` can be either :integer, :boolean, :float, :string or :symbol
         # `block` contains the argument definition and will be evaluated seperately
         # by the Argument::Interpreter
-        def optional name, type, &block
-          @dsl_method.arguments.add_argument name, false, type, &block
+        def optional name, type, array: false, &block
+          @dsl_method.arguments.add_argument name, false, type, array: array, &block
         end
 
         # adds a new required argument to the DSLMethod
@@ -48,8 +48,8 @@ module DSLCompose
         # `type` can be either :integer, :boolean, :float, :string or :symbol
         # `block` contains the argument definition and will be evaluated seperately
         # by the Argument::Interpreter
-        def requires name, type, &block
-          @dsl_method.arguments.add_argument name, true, type, &block
+        def requires name, type, array: false, &block
+          @dsl_method.arguments.add_argument name, true, type, array: array, &block
         end
 
         # executes the shared configuration block with the given name within the

data/lib/dsl_compose/dsl/interpreter.rb

@@ -54,8 +54,8 @@ module DSLCompose
       # `type` can be either :integer, :boolean, :float, :string or :symbol
       # `block` contains the argument definition and will be evaluated seperately
       # by the Argument::Interpreter
-      def optional name, type, &block
-        @dsl.arguments.add_argument name, false, type, &block
+      def optional name, type, array: false, &block
+        @dsl.arguments.add_argument name, false, type, array: array, &block
       end
 
       # adds a new required argument to the DSLMethod
@@ -64,8 +64,8 @@ module DSLCompose
       # `type` can be either :integer, :boolean, :float, :string or :symbol
       # `block` contains the argument definition and will be evaluated seperately
       # by the Argument::Interpreter
-      def requires name, type, &block
-        @dsl.arguments.add_argument name, true, type, &block
+      def requires name, type, array: false, &block
+        @dsl.arguments.add_argument name, true, type, array: array, &block
       end
 
       # executes the shared configuration block with the given name within the

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

@@ -16,6 +16,9 @@ module DSLCompose
         class InvalidArgumentTypeError < StandardError
         end
 
+        class ArrayNotValidError < StandardError
+        end
+
         attr_reader :arguments
 
         def initialize arguments, *args
@@ -49,41 +52,80 @@ module DSLCompose
 
             # assert the each provided optional argument is valid
             optional_arg.keys.each do |optional_argument_name|
-              optional_arg_value = optional_arg[optional_argument_name]
               optional_argument = arguments.optional_argument optional_argument_name
 
-              case optional_argument.type
-              when :integer
-                unless optional_arg_value.is_a? Integer
-                  raise InvalidArgumentTypeError, "#{optional_arg_value} is not an Integer"
-                end
-                optional_argument.validate_integer! optional_arg_value
-
-              when :symbol
-                unless optional_arg_value.is_a? Symbol
-                  raise InvalidArgumentTypeError, "#{optional_arg_value} is not a Symbol"
+              # the value for class types are wrapped in a ClassCoerce class so that they can be
+              # treated specially by the parser (it automatically converts them from a string name
+              # to the corresponding class, logic which doesn't happen here in case the class doesnt
+              # exist yet)
+              optional_arg_value = if optional_argument.type == :class
+                if optional_arg[optional_argument_name].is_a?(Array)
+                  optional_arg[optional_argument_name].map { |v| ClassCoerce.new v }
+                else
+                  ClassCoerce.new optional_arg[optional_argument_name]
                 end
-                optional_argument.validate_symbol! optional_arg_value
+              else
+                optional_arg[optional_argument_name]
+              end
 
-              when :string
-                unless optional_arg_value.is_a? String
-                  raise InvalidArgumentTypeError, "#{optional_arg_value} is not a String"
-                end
-                optional_argument.validate_string! optional_arg_value
+              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"
+              end
 
-              when :boolean
-                unless optional_arg_value.is_a?(TrueClass) || optional_arg_value.is_a?(FalseClass)
-                  raise InvalidArgumentTypeError, "#{optional_arg_value} is not a boolean"
+              # to simplify the code, we always process the reset of the validations as an array, even
+              # if the argument is not of type array
+              values = optional_arg_value.is_a?(Array) ? optional_arg_value : [optional_arg_value]
+
+              values.each do |value|
+                case optional_argument.type
+                when :integer
+                  unless value.is_a? Integer
+                    raise InvalidArgumentTypeError, "`#{value}` is not an Integer"
+                  end
+                  optional_argument.validate_integer! value
+
+                when :symbol
+                  unless value.is_a? Symbol
+                    raise InvalidArgumentTypeError, "`#{value}` is not a Symbol"
+                  end
+                  optional_argument.validate_symbol! value
+
+                when :string
+                  unless value.is_a? String
+                    raise InvalidArgumentTypeError, "`#{value}` is not a String"
+                  end
+                  optional_argument.validate_string! value
+
+                when :boolean
+                  unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+                    raise InvalidArgumentTypeError, "`#{value}` is not a boolean"
+                  end
+                  optional_argument.validate_boolean! value
+
+                when :class
+                  unless value.is_a?(ClassCoerce)
+                    raise InvalidArgumentTypeError, "`#{value}` is not a class coerce (String)"
+                  end
+                  optional_argument.validate_class! value
+
+                when :object
+                  optional_argument.validate_object! value
+
+                else
+                  raise InvalidArgumentTypeError, "The argument value `#{value}` is not a supported type"
                 end
-                optional_argument.validate_boolean! optional_arg_value
+              end
 
+              # The provided value appears valid for this argument, save the value.
+              #
+              # If the argument accepts an array of values, then automatically convert valid singular values
+              # into an array.
+              @arguments[optional_argument_name] = if optional_argument.array && !optional_arg_value.is_a?(Array)
+                [optional_arg_value]
               else
-                raise InvalidArgumentTypeError, "The argument #{optional_arg_value} is not a supported type"
+                optional_arg_value
               end
 
-              # the provided value appears valid for this argument, save the value
-              @arguments[optional_argument_name] = optional_arg_value
-
             rescue => e
               raise e, "Error processing optional argument #{optional_argument_name}: #{e.message}", e.backtrace
             end
@@ -96,39 +138,78 @@ module DSLCompose
             argument_name = nil
             argument_name = required_argument.name
 
-            arg = args[i]
-            case required_argument.type
-            when :integer
-              unless arg.is_a? Integer
-                raise InvalidArgumentTypeError, "#{arg} is not an Integer"
+            # the value for class types are wrapped in a ClassCoerce class so that they can be
+            # treated specially by the parser (it automatically converts them from a string name
+            # to the corresponding class, logic which doesn't happen here in case the class doesnt
+            # exist yet)
+            required_arg_value = if required_argument.type == :class
+              if args[i].is_a?(Array)
+                args[i].map { |v| ClassCoerce.new v }
+              else
+                ClassCoerce.new args[i]
               end
-              required_argument.validate_integer! arg
+            else
+              args[i]
+            end
 
-            when :symbol
-              unless arg.is_a? Symbol
-                raise InvalidArgumentTypeError, "#{arg} is not a Symbol"
-              end
-              required_argument.validate_symbol! arg
+            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"
+            end
 
-            when :string
-              unless arg.is_a? String
-                raise InvalidArgumentTypeError, "#{arg} is not a String"
-              end
-              required_argument.validate_string! arg
+            # to simplify the code, we always process the reset of the validations as an array, even
+            # if the argument is not of type array
+            values = required_arg_value.is_a?(Array) ? required_arg_value : [required_arg_value]
+
+            values.each do |value|
+              case required_argument.type
+              when :integer
+                unless value.is_a? Integer
+                  raise InvalidArgumentTypeError, "`#{value}` is not an Integer"
+                end
+                required_argument.validate_integer! value
+
+              when :symbol
+                unless value.is_a? Symbol
+                  raise InvalidArgumentTypeError, "`#{value}` is not a Symbol"
+                end
+                required_argument.validate_symbol! value
+
+              when :string
+                unless value.is_a? String
+                  raise InvalidArgumentTypeError, "`#{value}` is not a String"
+                end
+                required_argument.validate_string! value
 
-            when :boolean
-              unless arg.is_a?(TrueClass) || arg.is_a?(FalseClass)
-                raise InvalidArgumentTypeError, "#{arg} is not a boolean"
+              when :boolean
+                unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+                  raise InvalidArgumentTypeError, "`#{value}` is not a boolean"
+                end
+                required_argument.validate_boolean! value
+
+              when :class
+                unless value.is_a?(ClassCoerce)
+                  raise InvalidArgumentTypeError, "`#{value}` is not a class coerce (String)"
+                end
+                required_argument.validate_class! value
+
+              when :object
+                required_argument.validate_object! value
+
+              else
+                raise InvalidArgumentTypeError, "The argument `#{value}` is not a supported type"
               end
-              required_argument.validate_boolean! arg
+            end
 
+            # The provided value appears valid for this argument, save the value.
+            #
+            # If the argument accepts an array of values, then automatically convert valid singular values
+            # into an array.
+            @arguments[argument_name] = if required_argument.array && !required_arg_value.is_a?(Array)
+              [required_arg_value]
             else
-              raise InvalidArgumentTypeError, "The argument #{arg} is not a supported type"
+              required_arg_value
             end
 
-            # the provided value appears valid for this argument, save the value
-            @arguments[required_argument.name] = arg
-
           rescue => e
             raise e, "Error processing required argument #{argument_name}: #{e.message}", e.backtrace
           end

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

@@ -77,7 +77,9 @@ module DSLCompose
                 # add any arguments that were provided to the method call
                 method_call.arguments.arguments.each do |name, value|
                   if BlockArguments.accepts_argument?(name, &block)
-                    args[name] = value
+                    # if this value is a ClassCoerce object, then convert it from its original
+                    # string value to a class
+                    args[name] = value.is_a?(ClassCoerce) ? value.to_class : value
                   end
                 end
 

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

@@ -73,7 +73,9 @@ module DSLCompose
               # add any arguments that were provided to the DSL
               dsl_execution.arguments.arguments.each do |name, value|
                 if BlockArguments.accepts_argument?(name, &block)
-                  args[name] = value
+                  # if this value is a ClassCoerce object, then convert it from its original
+                  # string value to a class
+                  args[name] = value.is_a?(ClassCoerce) ? value.to_class : value
                 end
               end
               # set the dsl_execution in an instance variable so that method calls to `for_method`

data/lib/dsl_compose/version.rb

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

data/lib/dsl_compose.rb

@@ -8,6 +8,7 @@ require "dsl_compose/dsl/arguments/argument/format_validation"
 require "dsl_compose/dsl/arguments/argument/greater_than_or_equal_to_validation"
 require "dsl_compose/dsl/arguments/argument/greater_than_validation"
 require "dsl_compose/dsl/arguments/argument/in_validation"
+require "dsl_compose/dsl/arguments/argument/is_a_validation"
 require "dsl_compose/dsl/arguments/argument/length_validation"
 require "dsl_compose/dsl/arguments/argument/less_than_or_equal_to_validation"
 require "dsl_compose/dsl/arguments/argument/less_than_validation"
@@ -41,6 +42,8 @@ require "dsl_compose/parser"
 
 require "dsl_compose/composer"
 
+require "dsl_compose/class_coerce"
+
 require "dsl_compose/shared_configuration"
 
 require "dsl_compose/dsls"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dsl_compose
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.11.0
 platform: ruby
 authors:
 - Craig Ulliott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-11 00:00:00.000000000 Z
+date: 2023-07-12 00:00:00.000000000 Z
 dependencies: []
 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
@@ -24,6 +24,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/dsl_compose.rb
+- lib/dsl_compose/class_coerce.rb
 - lib/dsl_compose/composer.rb
 - lib/dsl_compose/dsl.rb
 - lib/dsl_compose/dsl/arguments.rb
@@ -35,6 +36,7 @@ files:
 - lib/dsl_compose/dsl/arguments/argument/greater_than_validation.rb
 - lib/dsl_compose/dsl/arguments/argument/in_validation.rb
 - lib/dsl_compose/dsl/arguments/argument/interpreter.rb
+- lib/dsl_compose/dsl/arguments/argument/is_a_validation.rb
 - lib/dsl_compose/dsl/arguments/argument/length_validation.rb
 - lib/dsl_compose/dsl/arguments/argument/less_than_or_equal_to_validation.rb
 - lib/dsl_compose/dsl/arguments/argument/less_than_validation.rb