dsl_compose 2.14.3 → 2.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddbe8b1e65763bba6eb8893aae605c7a3767c2d14f5aa5e120340cca933c6b1b
-  data.tar.gz: bdec4caaf6784bb0721fbd00593b0112d79f9fbf9c807f97bb89c3c713341053
+  metadata.gz: ae01b58f13f59318a89b06b444bd0dc0a17487e66d03a7701cb605673774f75a
+  data.tar.gz: 2feeab8f8494a6dea3ee59c52903a21c84cde2da623f406aea9530581146d124
 SHA512:
-  metadata.gz: 81c959506de138f0d4598d152d5d9b66756e0018bb0cee870fc749a49cbdcca6132c4252b7cb0c38308c517ead07102fe644ac12301aff743d3054e32efff404
-  data.tar.gz: 4f02a341c854c005c2212b6387b40f5ce805fe1c5aabf277d69ce91b0d85e34cb003c805d6fad3681b33964c5cc8c6952216d2152b57165ade6e793db242ad4e
+  metadata.gz: 6d1b476aef66fcaf034b3e7775a91233b69f30dc46c1dfc6d2891596ed859d0a9219e69c7bfec5ede49179d56a0fa2e59f31398b5b95504eb8ebd72c6f9a4d01
+  data.tar.gz: 565b63fb9b5e24f6d778e74f477b7aea4cd6619bfb39aa5ae62a9651daffd5b54e06ceaa8cef3378c111b508babe89d55d02af768c0692f24e4be9c68ad23845

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [2.15.1](https://github.com/craigulliott/dsl_compose/compare/v2.15.0...v2.15.1) (2023-10-03)
+
+
+### Bug Fixes
+
+* sorting classes by ancestry chain (i.e. ancestors before descendants) in the parser ([4e7dd6f](https://github.com/craigulliott/dsl_compose/commit/4e7dd6fd302c50ee3147f76f59a52089fb6f39ee))
+
+## [2.15.0](https://github.com/craigulliott/dsl_compose/compare/v2.14.3...v2.15.0) (2023-10-03)
+
+
+### Features
+
+* added option to skip certain provided classes within dsl parsers ([c2be111](https://github.com/craigulliott/dsl_compose/commit/c2be111289f4ca0b84b95e641c18bdbd784b5b6f))
+* adding default values for dsl arguments ([b89bd69](https://github.com/craigulliott/dsl_compose/commit/b89bd697eb6598f5f723a28533bd3e67e4ab9207))
+
+
+### Bug Fixes
+
+* passing classes to skip to the parser as class names (strings) instead of the actual classes. This prevents this library holding a reference to those classes and preventing garbage collection of the classes when they are dynamically created/destroyed within a test suite. ([74b332a](https://github.com/craigulliott/dsl_compose/commit/74b332ab99b7cf96bb8468a06634ee217cd5c58b))
+
 ## [2.14.3](https://github.com/craigulliott/dsl_compose/compare/v2.14.2...v2.14.3) (2023-09-27)
 
 

data/README.md

@@ -106,8 +106,9 @@ class Foo
 
       # You can also add optional arguments to your DSL methods. All optional
       # arguments must be added after required ones. An error will be raised if
-      # you define a required argument after an optional one.
-      optional :optional_argument, :integer do
+      # you define a required argument after an optional one. Optional arguments can
+      # have an default value, if a default is not provided then nil will be assumed.
+      optional :optional_argument, :integer, default: 123 do
         description "A description of an optional argument"
 
         # You can add validation to your arguments. A full list is provided later in this document
@@ -281,6 +282,9 @@ class MyParser < DSLCompose::Parser
   # 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`
+  #
+  # Both `for_children_of` and `for_final_children_of` accept an optional parameter
+  # named skip_classes which accepts an array of class names which should be skipped.
   for_children_of SomeBaseClass do |child_class:|
     add_documentation <<~DESCRIPTION
       You can optionally provide a description of anything specific that your parser
@@ -367,7 +371,7 @@ In addition to parser classes (or as a useful tool within parser classes) you ca
 # simple API to access the arguments, methods and method arguments which
 # were provided when using a DSL.
 #
-# In the example below, MyClass is a class, or descendent of a class which
+# In the example below, MyClass is a class, or descendant of a class which
 # had a DSL defined on it with the name :my_dsl.
 #
 # An error will be raised if a DSL with the provided name was never defined

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

@@ -52,6 +52,8 @@ module DSLCompose
         # 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
+        # The default value for optional arguments, if one is not provided then nil will be assumed.
+        attr_reader :default
         # 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
@@ -81,7 +83,7 @@ module DSLCompose
         # `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, kwarg, type, array: false, &block
+        def initialize name, required, kwarg, type, array: false, default: nil, &block
           if name.is_a? Symbol
 
             if RESERVED_ARGUMENT_NAMES.include? name
@@ -109,6 +111,13 @@ module DSLCompose
 
           @array = array ? true : false
 
+          unless default.nil?
+            if @required
+              raise ImpossibleKwargError, "The argument `#{name}` is required, so can not be given a default value."
+            end
+            @default = default
+          end
+
           # 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

data/lib/dsl_compose/dsl/arguments.rb

@@ -85,9 +85,11 @@ module DSLCompose
       #
       # Argument `name` must be unique within the DSLMethod.
       # `required` must be a boolean, and determines if this argument will be required
+      # `array` is a boolean which determines if this argument will accept an array of the given type or a single item
+      # `default` contains the default value, if one is not provided then nil will be assumed (it is only available for optional arguments)
       # `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, kwarg, type, array: false, &block
+      def add_argument name, required, kwarg, type, array: false, default: nil, &block
         if @arguments.key? name
           raise ArgumentAlreadyExistsError, "An argument with the name `#{name}` already exists for this DSL method"
         end
@@ -97,7 +99,7 @@ module DSLCompose
           raise ArgumentOrderingError, "Required arguments can not be added after optional ones"
         end
 
-        @arguments[name] = Argument.new(name, required, kwarg, type, array: array, &block)
+        @arguments[name] = Argument.new(name, required, kwarg, type, array: array, default: default, &block)
       end
     end
   end

data/lib/dsl_compose/dsl/interpreter.rb

@@ -63,10 +63,12 @@ module DSLCompose
       #
       # name must be a symbol
       # `type` can be either :integer, :boolean, :float, :string, :symbol, :class or :object
+      # `array` is a boolean which determines if this argument will accept an array of the given type or a single item
+      # `default` contains the default value, if one is not provided then nil will be assumed
       # `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, false, type, array: array, &block
+      def optional name, type, array: false, default: nil, &block
+        @dsl.arguments.add_argument name, false, false, type, array: array, default: default, &block
       end
 
       # adds a new required argument to the DSLMethod

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

@@ -69,17 +69,17 @@ module DSLCompose
             raise TooManyArgumentsError, "Too many arguments provided"
           end
 
-          # Assume all optonal arguments are nil (except booleans, which default to false).
+          # Assume all optonal arguments are their defaults (except booleans, which default to false).
           # If actual values were provided, then they will be set further below.
           if arguments.optional_arguments.any?
             arguments.optional_arguments.each do |optional_argument|
               # assume it is nil
-              @arguments[optional_argument.name] = nil
+              @arguments[optional_argument.name] = optional_argument.default
               # unless the argument is an array or a boolean, in which case it defaults
               # to an empty array or false
               if optional_argument.array
                 @arguments[optional_argument.name] = [].freeze
-              elsif optional_argument.type == :boolean
+              elsif optional_argument.type == :boolean && optional_argument.default.nil?
                 @arguments[optional_argument.name] = false
               end
             end

data/lib/dsl_compose/interpreter.rb

@@ -82,7 +82,7 @@ module DSLCompose
     def get_last_dsl_execution klass, dsl_name
       # 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 descendents
+      # parent classes in ruby always have to be evaluated before their descendants
       class_dsl_executions(klass, dsl_name, true, true).last
     end
 

data/lib/dsl_compose/parser/for_children_of_parser/{descendents.rb → descendants.rb}

@@ -3,27 +3,44 @@
 module DSLCompose
   class Parser
     class ForChildrenOfParser
-      class Descendents
-        def initialize base_class, final_children_only
+      class Descendants
+        def initialize base_class, final_children_only, skip_classes = []
           @base_class = base_class
           @final_children_only = final_children_only
+          @skip_classes = skip_classes
         end
 
         def classes
           # all objects which extend the provided base class
           extending_classes = subclasses @base_class
 
-          # sort the results, classes are ordered first by the depth of their namespace, and second
-          # by the presence of decendents and finally by their name
+          # sort the results
+          #
+          # classes are ordered first by name
           extending_classes.sort_by! do |child_class|
-            "#{child_class.name.split("::").count}_#{has_descendents(child_class) ? 0 : 1}_#{child_class.name}"
+            "#{child_class.name.split("::").count}_#{has_descendants(child_class) ? 0 : 1}_#{child_class.name}"
+          end
+          # then by ansestory chain (i.e. ancestors before descendants)
+          extending_classes.sort do |a, b|
+            if a < b
+              1
+            elsif a > b
+              -1
+            else
+              0
+            end
+          end
+
+          # reject any classes which we are skipping
+          extending_classes.reject! do |child_class|
+            @skip_classes.include? 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
+            # reject any classes which have descendants
             extending_classes.reject! do |child_class|
-              has_descendents child_class
+              has_descendants child_class
             end
           end
 
@@ -39,7 +56,7 @@ module DSLCompose
           }.flatten
         end
 
-        def has_descendents base_class
+        def has_descendants base_class
           base_class.subclasses.count { |subclass| class_is_still_defined? subclass } > 0
         end
 

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, final_children_only, &block
+      def initialize base_class, final_children_only, skip_classes = [], &block
         # assert the provided class has the DSLCompose::Composer module installed
         unless base_class.respond_to? :dsls
           raise ClassDoesNotUseDSLComposeError, base_class
@@ -56,8 +56,8 @@ module DSLCompose
           end
         end
 
-        # yeild the block for all descendents of the provided base_class
-        Descendents.new(base_class, final_children_only).classes.each do |child_class|
+        # yeild the block for all descendants of the provided base_class
+        Descendants.new(base_class, final_children_only, skip_classes).classes.each do |child_class|
           # determine which arguments to send to the block
           args = {}
           if BlockArguments.accepts_argument?(:child_class, &block)

data/lib/dsl_compose/parser.rb

@@ -30,27 +30,28 @@ module DSLCompose
     # 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
+    def self.for_children_of base_class, final_children_only: false, skip_classes: [], rerun: false, &block
       unless rerun
         @runs ||= []
         @runs << {
           base_class: base_class,
           final_children_only: final_children_only,
+          skip_classes: skip_classes,
           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, final_children_only, &block)
+      ForChildrenOfParser.new(base_class, final_children_only, skip_classes, &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
+    def self.for_final_children_of base_class, skip_classes: [], &block
+      for_children_of base_class, final_children_only: true, skip_classes: skip_classes, &block
     end
 
     # this method is used to rerun the parser, this is most useful from within a test suite
@@ -61,7 +62,8 @@ module DSLCompose
         base_class = run[:base_class]
         block = run[:block]
         final_children_only = run[:final_children_only]
-        for_children_of base_class, rerun: true, final_children_only: final_children_only, &block
+        skip_classes = run[:skip_classes]
+        for_children_of base_class, rerun: true, final_children_only: final_children_only, skip_classes: skip_classes, &block
       end
     end
 

data/lib/dsl_compose/version.rb

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

data/lib/dsl_compose.rb

@@ -42,7 +42,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/descendants"
 require "dsl_compose/parser/for_children_of_parser"
 require "dsl_compose/parser/block_arguments"
 require "dsl_compose/parser"

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

@@ -11,6 +11,7 @@ module DSLCompose
         attr_reader required: bool
         attr_reader kwarg: bool
         attr_reader array: bool
+        attr_reader default: untyped
         attr_reader description: String
 
         attr_reader greater_than_validation: GreaterThanValidation
@@ -28,7 +29,7 @@ module DSLCompose
         attr_reader length_validation: LengthValidation
         attr_reader is_a_validation: IsAValidation
 
-        def initialize: (Symbol name, bool required, bool kwarg, argument_type `type`, ?array: bool) -> void
+        def initialize: (Symbol name, bool required, bool kwarg, argument_type `type`, ?array: bool, ?default: untyped) -> 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, bool kwarg, argument_type `type`, ?array: bool) -> Argument
+      def add_argument: (Symbol name, bool required, bool kwarg, argument_type `type`, ?array: bool, ?default: untyped) -> Argument
 
       class ArgumentDoesNotExistError < StandardError
         end

data/sig/dsl_compose/dsl/interpreter.rbs

@@ -13,7 +13,7 @@ module DSLCompose
       def title: (String title) -> void
       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 optional: (Symbol name, argument_type `type`, ?array: bool, ?default: untyped) -> void
       def requires: (Symbol name, argument_type `type`, ?kwarg: bool, ?array: bool) -> void
     end
   end

data/sig/dsl_compose/parser/for_children_of_parser/{descendents.rbs → descendants.rbs}

@@ -2,15 +2,16 @@
 module DSLCompose
   class Parser
     class ForChildrenOfParser
-      class Descendents
+      class Descendants
         @base_class: singleton(Object)
+        @skip_classes: Array[String]
         @final_children_only: bool
 
-        def initialize: (singleton(Object) base_class, bool final_children_only) -> void
+        def initialize: (singleton(Object) base_class, bool final_children_only, ?Array[String] skip_classes) -> void
         def classes: -> Array[singleton(Object)]
 
         private
-        def has_descendents: (singleton(Object) base_class) -> bool
+        def has_descendants: (singleton(Object) base_class) -> bool
       end
     end
   end

data/sig/dsl_compose/parser/for_children_of_parser.rbs

@@ -5,7 +5,7 @@ module DSLCompose
       @base_class: singleton(Object)
       @child_class: singleton(Object)
 
-      def initialize: (singleton(Object) base_class, bool final_children_only) -> void
+      def initialize: (singleton(Object) base_class, bool final_children_only, ?Array[String] skip_classes) -> void
 
       # overriding this method because steep doesn't
       # correctly infer that a block is being passed to this method

data/sig/dsl_compose/parser.rbs

@@ -4,7 +4,8 @@ module DSLCompose
     self.@runs: untyped
 
     def initialize: -> void
-    def self.for_children_of: (singleton(Object) base_class, ?final_children_only: bool, ?rerun: bool) -> void
+    def self.for_children_of: (singleton(Object) base_class, ?final_children_only: bool, ?skip_classes: Array[String], ?rerun: bool) -> void
+    def self.for_final_children_of: (singleton(Object) base_class, ?skip_classes: Array[String]) -> void
 
     class NotInitializable < StandardError
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dsl_compose
 version: !ruby/object:Gem::Version
-  version: 2.14.3
+  version: 2.15.1
 platform: ruby
 authors:
 - Craig Ulliott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-09-27 00:00:00.000000000 Z
+date: 2023-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: class_spec_helper
@@ -70,7 +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/descendants.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/reader.rb
@@ -112,7 +112,7 @@ files:
 - sig/dsl_compose/parser.rbs
 - sig/dsl_compose/parser/block_arguments.rbs
 - sig/dsl_compose/parser/for_children_of_parser.rbs
-- sig/dsl_compose/parser/for_children_of_parser/descendents.rbs
+- sig/dsl_compose/parser/for_children_of_parser/descendants.rbs
 - sig/dsl_compose/parser/for_children_of_parser/for_dsl_parser.rbs
 - sig/dsl_compose/parser/for_children_of_parser/for_dsl_parser/for_method_parser.rbs
 - sig/dsl_compose/reader.rbs