dsl_compose 1.13.0 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45e24e8af1b43cc20cdfe1b9089c54812b774f9d377f4d74842b202d4b6bd1c2
-  data.tar.gz: 55ee3564fadfa1ff647a340a612ef1b840e616054008616565db52838ba2b2eb
+  metadata.gz: 8fe38926f435f6f7978468bb08e0b91ebbd6962d5863032a7cb49095856c3c50
+  data.tar.gz: c4523746ddbef25e5c64e8b47ea624393d6efa25f0c6b795a0d69ea7910d2683
 SHA512:
-  metadata.gz: 307a73bcdd19bda7531e329710d1c559f31f6635d2a7cd495e9cf9644e02db140e53e286ecb9aded78a64b2d11ae617f1178093cb857226346b55bce50fa5ae7
-  data.tar.gz: 837abd419951f900d30a234d0665ff12d2e6cb9ad43750fc2dc58b2d07a5b08a3c9de2faf9c4a0149da65ff4f3aa6381af5b5a67bb1d7c969c6d64429d5cbac8
+  metadata.gz: ef54cc72949be0609a9bd1feacad07b202c90b183f6be89c6494c19a95944639ccc0cba3986375a16234803aa96f4e90721abc2308fa75e20ace407504bfedce
+  data.tar.gz: 4143b1a1d0d84597da9fa29ef745a9ca0002fc4bc6107a9206b700453f511cdc1e7a0bc6eea16af69e169cc3c220ff43bbbdd5b8603df58704bcc9d51fa5d58b

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.14.0](https://github.com/craigulliott/dsl_compose/compare/v1.13.1...v1.14.0) (2023-07-19)
+
+
+### Features
+
+* Parsers can push notes back to the DSLs to explain how each DSL is being used. These notes can be used in generated documentation. ([#39](https://github.com/craigulliott/dsl_compose/issues/39)) ([053fa50](https://github.com/craigulliott/dsl_compose/commit/053fa50bcbc2180b2f788b5a3bba11576804f206))
+
+## [1.13.1](https://github.com/craigulliott/dsl_compose/compare/v1.13.0...v1.13.1) (2023-07-19)
+
+
+### Bug Fixes
+
+* unused optional arguments no longer raise an error within the parser ([#37](https://github.com/craigulliott/dsl_compose/issues/37)) ([99cd04b](https://github.com/craigulliott/dsl_compose/commit/99cd04b83387c7940e364dc86d527fdb51152405))
+
 ## [1.13.0](https://github.com/craigulliott/dsl_compose/compare/v1.12.0...v1.13.0) (2023-07-17)
 
 

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

@@ -120,7 +120,7 @@ module DSLCompose
             raise DescriptionAlreadyExistsError, "The description has already been set"
           end
 
-          @description = description
+          @description = FixHeredocIndentation.fix_heredoc_indentation description
         end
 
         # Returns `true` if this DSL has a description, else false.

data/lib/dsl_compose/dsl/dsl_method.rb

@@ -76,7 +76,7 @@ module DSLCompose
           raise DescriptionAlreadyExistsError, "The description has already been set"
         end
 
-        @description = description
+        @description = FixHeredocIndentation.fix_heredoc_indentation description
       end
 
       # Returns `true` if this DSL has a description, else false.

data/lib/dsl_compose/dsl.rb

@@ -82,7 +82,7 @@ module DSLCompose
         raise DescriptionAlreadyExistsError, "The DSL description has already been set"
       end
 
-      @description = description
+      @description = FixHeredocIndentation.fix_heredoc_indentation description
     end
 
     # Returns `true` if this DSL has a description, else false.

data/lib/dsl_compose/fix_heredoc_indentation.rb

@@ -0,0 +1,23 @@
+module DSLCompose
+  # A small helper to fix indentation and clean up whitespace in
+  # strings which were created with rubys heredoc syntax.
+  module FixHeredocIndentation
+    # This method is used to fix the indentation of heredoc strings.
+    # It will remove the leading whitespace from each line of the string
+    # and remove the leading newline from the string.
+    def self.fix_heredoc_indentation string
+      # replace all tabs with spaces
+      string = string.gsub(/\t/, "  ")
+      # remove empty lines from the start of the string
+      string = string.gsub(/\A( *\n)+/, "")
+      # remove empty lines from the end of the string
+      string = string.gsub(/( *\n)+\Z/, "")
+      # removes the number of leading spaces on the first line, from
+      # all the other lines
+      string = string.gsub(/^#{string[/\A */]}/, "")
+      # collapse lines which are next to each other onto the same line
+      # because they are really the same paragraph
+      string.gsub(/([^ \n])\n([^ \n])/, '\1 \2')
+    end
+  end
+end

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

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

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

@@ -22,6 +22,19 @@ module DSLCompose
               arguments: @arguments.to_h
             }
           end
+
+          # the parser can provide usage notes for how this dsl is being used, these are used to
+          # generate documentation
+          def add_parser_usage_note note
+            @parser_usage_notes ||= []
+            @parser_usage_notes << DSLCompose::FixHeredocIndentation.fix_heredoc_indentation(note)
+          end
+
+          # return the list of notes which describe how the parsers are using this DSL
+          def parser_usage_notes
+            @parser_usage_notes ||= []
+            @parser_usage_notes
+          end
         end
       end
     end

data/lib/dsl_compose/interpreter/execution.rb

@@ -36,6 +36,19 @@ module DSLCompose
         end
       end
 
+      # the parser can provide usage notes for how this dsl is being used, these are used to
+      # generate documentation
+      def add_parser_usage_note note
+        @parser_usage_notes ||= []
+        @parser_usage_notes << DSLCompose::FixHeredocIndentation.fix_heredoc_indentation(note)
+      end
+
+      # return the list of notes which describe how the parsers are using this DSL
+      def parser_usage_notes
+        @parser_usage_notes ||= []
+        @parser_usage_notes
+      end
+
       private
 
       # catch and process any method calls within the DSL block

data/lib/dsl_compose/interpreter.rb

@@ -13,6 +13,21 @@ module DSLCompose
       @executions = []
     end
 
+    # the parser can provide usage notes for how this dsl is being used, these are used to
+    # generate documentation
+    def add_parser_usage_note child_class, note
+      @parser_usage_notes ||= {}
+      @parser_usage_notes[child_class] ||= []
+      @parser_usage_notes[child_class] << DSLCompose::FixHeredocIndentation.fix_heredoc_indentation(note)
+    end
+
+    # return the list of notes which describe how the parsers are using this DSL
+    def parser_usage_notes child_class
+      @parser_usage_notes ||= {}
+      @parser_usage_notes[child_class] ||= []
+      @parser_usage_notes[child_class]
+    end
+
     # 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.

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

@@ -83,11 +83,22 @@ module DSLCompose
                   end
                 end
 
+                # set the method_call in an instance variable so that method calls to `description`
+                # from within the block will have access to it
+                @method_call = method_call
+
                 # yeild the block in the context of this class
                 instance_exec(**args, &block)
               end
             end
           end
+
+          # takes a description of what this parser does and stores it against the DSL definition
+          # of the current @child_class, this is used to generate documentation for what the parser
+          # has done with the DSL
+          def description description
+            @method_call.add_parser_usage_note description
+          end
         end
       end
     end

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

@@ -108,6 +108,13 @@ module DSLCompose
         def for_method method_names, &block
           ForMethodParser.new(@base_class, @child_class, @dsl_execution, method_names, &block)
         end
+
+        # takes a description of what this parser does and stores it against the DSL definition
+        # of the current @child_class, this is used to generate documentation for what the parser
+        # has done with the DSL
+        def description description
+          @dsl_execution.add_parser_usage_note description
+        end
       end
     end
   end

data/lib/dsl_compose/parser/for_children_of_parser.rb

@@ -121,6 +121,13 @@ module DSLCompose
       def for_dsl_or_inherited_dsl dsl_names, &block
         for_dsl dsl_names, on_current_class: true, on_ancestor_class: true, &block
       end
+
+      # takes a description of what this parser does and stores it against the DSL definition
+      # of the current @child_class, this is used to generate documentation for what the parser
+      # has done with the DSL
+      def description description
+        @base_class.dsls.add_parser_usage_note @child_class, description
+      end
     end
   end
 end

data/lib/dsl_compose/version.rb

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

data/lib/dsl_compose.rb

@@ -45,6 +45,8 @@ require "dsl_compose/composer"
 
 require "dsl_compose/class_coerce"
 
+require "dsl_compose/fix_heredoc_indentation"
+
 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.13.0
+  version: 1.14.0
 platform: ruby
 authors:
 - Craig Ulliott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-17 00:00:00.000000000 Z
+date: 2023-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: class_spec_helper
@@ -62,6 +62,7 @@ files:
 - lib/dsl_compose/dsl/dsl_method/interpreter.rb
 - lib/dsl_compose/dsl/interpreter.rb
 - lib/dsl_compose/dsls.rb
+- lib/dsl_compose/fix_heredoc_indentation.rb
 - lib/dsl_compose/interpreter.rb
 - lib/dsl_compose/interpreter/execution.rb
 - lib/dsl_compose/interpreter/execution/arguments.rb