dsl_compose 1.13.1 → 1.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ca102e9e28dc1732f0a6c14282bdfc6b0cbc3edddc8b76864921c8d5a295ec0
-  data.tar.gz: 349941451a9954f29938fb91b0324662b306d215ce725e68faa00d25937b883d
+  metadata.gz: ddb7398a7cd392f48c54e7ee60404342857d7d010247926ca006d84ad5caa1ac
+  data.tar.gz: d4515e288a0eea8be71a869434c1f28a20f2cec3943a33c9c6615028b223b970
 SHA512:
-  metadata.gz: '002348ac24e6f8bf513478702c6c08368fb1ee8c788ad8a893d7a848e41103ee6208e5e24f260e0be79eb069700047d408b0c51e51ea3b861bccf55fe2312882'
-  data.tar.gz: 14431a1691709376eb73196c5c7280a7d0ec451d4eb58a3e8ffa3bc43bb6cf26f4433b8f4d6fb488db57d9be06bbcf4f974e5175719d44766a1247271ea76e34
+  metadata.gz: 8512aec08f472d946b2c9a84b6e824bbc1d46db610f3bb908766e05a324833e3c07feeb05638153633d23bccbe1f0e66e8132721e7056e903beaed1a42ef866c
+  data.tar.gz: a2897b08ed6b226a06c8fbf2e07277b68fc1476b7467db663c06acacaa3a1e92db64b3aaac782fb2ada0657605dfecccb47bce6517339d60a49016a48ccd9726

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.14.1](https://github.com/craigulliott/dsl_compose/compare/v1.14.0...v1.14.1) (2023-07-19)
+
+
+### Bug Fixes
+
+* Clearing the parser_usage_notes when also clearing the DSLs. ([#41](https://github.com/craigulliott/dsl_compose/issues/41)) ([bbdb445](https://github.com/craigulliott/dsl_compose/commit/bbdb445ed9fa4b495f8aa5bf0b889707680858d0))
+
+## [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)
 
 

data/README.md

@@ -247,6 +247,16 @@ MyParser < DSLCompose::Parser
   # which extend the provided base class, but do not have their own children) then
   # use `for_final_children_of` instead of `for_children_of`
   for_children_of SomeBaseClass do |child_class:|
+    description <<-DESCRIPTION
+      You can optionally provide a description of anything specific that your parser
+      does in this block, this description will be used when generating documentation
+
+      This description accepts markdown.
+
+      Do not add a description here if the parser does not have any business logic here
+      other than making calls to `for_dsl`, `for_dsl_or_inherited_dsl` or `for_inherited_dsl`
+    DESCRIPTION
+
     # `for_dsl` accepts a DSL name or an array of DSL names and will yield it's
     # provided block once for each time a DSL of that name has been used
     # directly on the child_class.
@@ -266,6 +276,16 @@ MyParser < DSLCompose::Parser
     # consider a DSL to have been executed on the actual class it was used, and
     # any classes which are descendants of that class
     for_dsl [:dsl1, :dsl2] do |dsl_name:, a_dsl_argument:|
+      description <<-DESCRIPTION
+        You can optionally provide a description of anything specific that your parser
+        does in this block, this description will be used when generating documentation.
+
+        This description accepts markdown.
+
+        Do not add a description here if the parser does not have any business logic here
+        other than making calls to `for_method`
+      DESCRIPTION
+
       # `for_method` accepts a method name or an array of method names and will
       # yield it's provided block once for each time a method with this name is
       # executed within the DSL.
@@ -277,6 +297,13 @@ MyParser < DSLCompose::Parser
       # are provided then the requested dsl argument must be present on all DSLs
       # otherwise an error will be raised.
       for_method :some_method_name do |method_name:, a_method_argument:|
+        description <<-DESCRIPTION
+          You can optionally provide a description of anything specific that your parser
+          does in this block, this description will be used when generating documentation.
+
+          This description accepts markdown.
+        DESCRIPTION
+
         # your business logic goes here
         ...
       end

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/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.
@@ -46,11 +61,13 @@ module DSLCompose
       @executions.filter { |e| e.dsl.name == dsl_name && ((on_current_class && e.klass == klass) || (on_ancestor_class && klass < e.klass)) }
     end
 
-    # removes all executions from the interpreter, this is primarily used from
-    # within a test suite when dynamically creating classes for tests and then
-    # wanting to clear the interpreter before the next test.
+    # removes all executions from the interpreter, and any parser_usage_notes
+    # this is primarily used from within a test suite when dynamically creating
+    # classes for tests and then wanting to clear the interpreter before the
+    # next test.
     def clear
       @executions = []
+      @parser_usage_notes ||= {}
     end
 
     def to_h dsl_name

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.1"
+  VERSION = "1.14.1"
 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dsl_compose
 version: !ruby/object:Gem::Version
-  version: 1.13.1
+  version: 1.14.1
 platform: ruby
 authors:
 - Craig Ulliott
@@ -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