dsl_compose 2.11.0 → 2.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0e11587cec1aae93debb5f7aa0290cb506436000dee938b375fe90d04650e9d
-  data.tar.gz: 260343f03b26ac471a7d40f4e981b51d76af15ed4a60074d6531aa71a1f22dc8
+  metadata.gz: c143f5741011efd1d4311e4b2b5beab52fb75600f0c7f492fdb199cc3221c502
+  data.tar.gz: '09a0982fa552f3e36a1005e4b345eaf5294bc3b62c10c41eebb6dbdf42e3a102'
 SHA512:
-  metadata.gz: eec6a16a53886bafaac45e6b7faba38449720adf195867a6ac8f12efce42ccf9f7ec52fbd4f323ac5e9f6121345acd510e41b967e38b1321b4ca680ee0e36148
-  data.tar.gz: fb39f5240eb37fa5f9a3f74f69b5ac85b102e344f02eb6dc8b3df20f2f8f80c01a90f435c7de1650497094ad2d275d6cad56b4a38c183a07e390a61ae456c7c1
+  metadata.gz: 45988d0bbd27cbc1ee285608a795d1cdc95dccf4bce14ccdd76ea0aad26daec4345262c140f73a4059becbe4148aef9548b5b8f127585557ad90b974c9b0807b
+  data.tar.gz: e889b48f585730f5a8a05349e8c90e527885e5393512ecea5568feab6c71e0a82ce9e5b7b417af6d7bcbb4a35f9459a4537b0bbb337e5825bc1e72833cef4edf

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.13.0](https://github.com/craigulliott/dsl_compose/compare/v2.12.0...v2.13.0) (2023-09-04)
+
+
+### Features
+
+* optionally mark required arguments as keyword arguments ([9a1c901](https://github.com/craigulliott/dsl_compose/commit/9a1c90169fb36c550b0577034823579062120647))
+
+## [2.12.0](https://github.com/craigulliott/dsl_compose/compare/v2.11.0...v2.12.0) (2023-09-02)
+
+
+### Features
+
+* adding dsl_name method to execution reader ([54e8a44](https://github.com/craigulliott/dsl_compose/commit/54e8a44b0f7a6fc2fe81a18cd53d3ebe76257348))
+
 ## [2.11.0](https://github.com/craigulliott/dsl_compose/compare/v2.10.0...v2.11.0) (2023-09-02)
 
 

data/README.md

@@ -114,6 +114,16 @@ class Foo
         validate_greater_than 0
       end
 
+      # Required arguments for both DSLs and DSL methods are assumed to be standard ruby
+      # arguments by default, but can be declared as keyword arguments by passing `kwarg: true`.
+      # This is useful because sometimes keyword arguments can make your DSL more readable. This
+      # option does not exist for optional arguments, because optional arguments are always kwargs.
+      requires :required_keyword_argument, :symbol, kwarg: true do
+        # You should provide descriptions for your arguments. These descriptions will
+        # be used when generating your documentation. This description supports markdown
+        description "A description of the first argument for this method"
+      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.

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

@@ -13,6 +13,9 @@ module DSLCompose
         class InvalidTypeError < StandardError
         end
 
+        class ImpossibleKwargError < StandardError
+        end
+
         class InvalidNameError < StandardError
         end
 
@@ -42,6 +45,10 @@ 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 must be provided as a keyword argument, this is only appropriate for
+        # required arguments, as optional arguments are always passed as keywork arguments.
+        # arguments.
+        attr_reader :kwarg
         # 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
@@ -71,9 +78,10 @@ module DSLCompose
         # `name` must be a symbol.
         # `required` is a boolean which determines if this Attribute must be provided when
         # calling its associated DSLMethod.
+        # `kwarg` is a boolean which determines if a required Attribute must be provided as a keyword argument.
         # `type` can be either :integer, :boolean, :float, :string or :symbol
         # `block` contains the instructions to further configure this Attribute
-        def initialize name, required, type, array: false, &block
+        def initialize name, required, kwarg, type, array: false, &block
           if name.is_a? Symbol
 
             if RESERVED_ARGUMENT_NAMES.include? name
@@ -93,6 +101,12 @@ module DSLCompose
 
           @required = required ? true : false
 
+          if @required == false && kwarg == true
+            raise ImpossibleKwargError, "Optional arguments must always be provided as keyword arguments. The argument `#{name}` can not be both required: false and kwarg: true."
+          end
+
+          @kwarg = kwarg ? true : false
+
           @array = array ? true : false
 
           # If a block was provided, then we evaluate it using a seperate

data/lib/dsl_compose/dsl/arguments.rb

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

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

@@ -39,17 +39,19 @@ module DSLCompose
         # `block` contains the argument definition and will be evaluated seperately
         # by the Argument::Interpreter
         def optional name, type, array: false, &block
-          @dsl_method.arguments.add_argument name, false, type, array: array, &block
+          @dsl_method.arguments.add_argument name, false, false, type, array: array, &block
         end
 
         # adds a new required argument to the DSLMethod
         #
         # name must be a symbol
+        # `kwarg` is a boolean which determines if a required Attribute must be provided as a keyword argument.
+        # `array` is a boolean which determines if this argument will accept an array of the given type or a single item
         # `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, array: false, &block
-          @dsl_method.arguments.add_argument name, true, type, array: array, &block
+        def requires name, type, kwarg: false, array: false, &block
+          @dsl_method.arguments.add_argument name, true, kwarg, type, array: array, &block
         end
 
         # executes the shared configuration block with the given name within the

data/lib/dsl_compose/dsl/interpreter.rb

@@ -66,17 +66,19 @@ module DSLCompose
       # `block` contains the argument definition and will be evaluated seperately
       # by the Argument::Interpreter
       def optional name, type, array: false, &block
-        @dsl.arguments.add_argument name, false, type, array: array, &block
+        @dsl.arguments.add_argument name, false, false, type, array: array, &block
       end
 
       # adds a new required argument to the DSLMethod
       #
       # name must be a symbol
+      # `kwarg` is a boolean which determines if a required Attribute must be provided as a keyword argument.
+      # `array` is a boolean which determines if this argument will accept an array of the given type or a single item
       # `type` can be either :integer, :boolean, :float, :string, :symbol, :class or :object
       # `block` contains the argument definition and will be evaluated seperately
       # by the Argument::Interpreter
-      def requires name, type, array: false, &block
-        @dsl.arguments.add_argument name, true, type, array: array, &block
+      def requires name, type, kwarg: false, array: false, &block
+        @dsl.arguments.add_argument name, true, kwarg, type, array: array, &block
       end
 
       # executes the shared configuration block with the given name within the

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

@@ -25,18 +25,38 @@ module DSLCompose
           @arguments = {}
 
           required_argument_count = arguments.required_arguments.count
+          required_non_kwarg_argument_count = arguments.required_arguments.count { |a| !a.kwarg }
           has_optional_arguments = arguments.optional_arguments.any?
 
-          # the first N args, where N = required_argument_count, are the
+          # the first N args, where N = required_non_kwarg_argument_count, are the
           # provided required arguments
-          required_args = args.slice(0, required_argument_count)
-          # the optional arg which comes next is the hash which represents
-          # all the optional arguments
-          optional_arg = args[required_argument_count]
+          required_args = args.slice(0, required_non_kwarg_argument_count)
+
+          # the final argument is the object which contains all the keyword args (these keyword
+          # args could be optional or required)
+          all_kwargs = args[required_non_kwarg_argument_count]
+
+          # process all the required arguments which are kwargs
+          required_kwargs = arguments.required_arguments.filter { |a| a.kwarg }
+          required_kwargs.each do |required_kwarg|
+            if all_kwargs.key? required_kwarg.name
+              # add the keyword argument to the required args
+              required_args << all_kwargs[required_kwarg.name]
+              # delete the required kwarg from the kwargs hash, so that we are
+              # left with only the optional args
+              all_kwargs.delete required_kwarg.name
+            else
+              raise MissingRequiredArgumentsError, "The required kwarg `#{required_kwarg.name}` was not provided"
+            end
+          end
+
+          # at this point, all_kwargs should be a hash which only represents
+          # the optional arguments
+          optional_arg = all_kwargs
 
           # assert that a value is provided for every required argument
           unless required_argument_count == required_args.count
-            raise MissingRequiredArgumentsError, "This requires #{required_argument_count} arguments, but only #{required_args.count} were provided"
+            raise MissingRequiredArgumentsError, "This requires #{required_non_kwarg_argument_count} arguments, but only #{required_args.count} were provided"
           end
 
           # assert that too many arguments have not been provided
@@ -61,7 +81,7 @@ module DSLCompose
           end
 
           # asset that, if provided, then the optional argument (always the last one) is a Hash
-          if has_optional_arguments && optional_arg.nil? === false
+          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"
             end
@@ -165,13 +185,13 @@ module DSLCompose
             # 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 }
+              if required_args[i].is_a?(Array)
+                required_args[i].map { |v| ClassCoerce.new v }
               else
-                ClassCoerce.new args[i]
+                ClassCoerce.new required_args[i]
               end
             else
-              args[i]
+              required_args[i]
             end
 
             if required_arg_value.is_a?(Array) && !required_argument.array

data/lib/dsl_compose/reader/execution_reader.rb

@@ -22,6 +22,11 @@ module DSLCompose
         @execution = execution
       end
 
+      # useful when creating a DSL reader which is usable across multiple DSLs
+      def dsl_name
+        @execution.dsl.name
+      end
+
       # returns an object which represents the arguments available for this DSL and allows
       # accessing their values via methods
       def arguments

data/lib/dsl_compose/version.rb

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

data/sig/dsl_compose/dsl/arguments/argument.rbs

@@ -9,6 +9,7 @@ module DSLCompose
         attr_reader name: Symbol
         attr_reader type: argument_type
         attr_reader required: bool
+        attr_reader kwarg: bool
         attr_reader array: bool
         attr_reader description: String
 
@@ -27,7 +28,7 @@ module DSLCompose
         attr_reader length_validation: LengthValidation
         attr_reader is_a_validation: IsAValidation
 
-        def initialize: (Symbol name, bool required, argument_type `type`, ?array: bool) -> void
+        def initialize: (Symbol name, bool required, bool kwarg, argument_type `type`, ?array: bool) -> void
         def set_description: (String description) -> void
         def has_description?: () -> bool
         def required?: -> bool

data/sig/dsl_compose/dsl/arguments.rbs

@@ -12,7 +12,7 @@ module DSLCompose
       def optional_argument: (Symbol name) -> Argument
       def required_argument: (Symbol name) -> Argument
       def has_argument?: (Symbol name) -> bool
-      def add_argument: (Symbol name, bool required, argument_type `type`, ?array: bool) -> Argument
+      def add_argument: (Symbol name, bool required, bool kwarg, argument_type `type`, ?array: bool) -> Argument
 
       class ArgumentDoesNotExistError < StandardError
         end

data/sig/dsl_compose/dsl/dsl_method/interpreter.rbs

@@ -11,7 +11,7 @@ module DSLCompose
         private
         def description: (String description) -> void
         def optional: (Symbol name, argument_type `type`, ?array: bool) -> void
-        def requires: (Symbol name, argument_type `type`, ?array: bool) -> void
+        def requires: (Symbol name, argument_type `type`, ?kwarg: bool, ?array: bool) -> void
       end
     end
   end

data/sig/dsl_compose/dsl/interpreter.rbs

@@ -14,7 +14,7 @@ module DSLCompose
       def add_method: (Symbol name, ?required: nil) -> void
       def add_unique_method: (Symbol name, ?required: nil) -> void
       def optional: (Symbol name, argument_type `type`, ?array: bool) -> void
-      def requires: (Symbol name, argument_type `type`, ?array: bool) -> void
+      def requires: (Symbol name, argument_type `type`, ?kwarg: bool, ?array: bool) -> void
     end
   end
 end

data/sig/dsl_compose/reader/execution_reader.rbs

@@ -5,6 +5,7 @@ module DSLCompose
       @execution: Interpreter::Execution
 
       def initialize: (Interpreter::Execution execution) -> void
+      def dsl_name: -> Symbol
       def arguments: -> ArgumentsReader
       def method_called?: (Symbol method_name) -> bool
       def method_missing: (Symbol method_name) -> (nil | ArgumentsReader | Array[ArgumentsReader])

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dsl_compose
 version: !ruby/object:Gem::Version
-  version: 2.11.0
+  version: 2.13.0
 platform: ruby
 authors:
 - Craig Ulliott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-09-02 00:00:00.000000000 Z
+date: 2023-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: class_spec_helper