dsl_compose 1.13.1 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ca102e9e28dc1732f0a6c14282bdfc6b0cbc3edddc8b76864921c8d5a295ec0
-  data.tar.gz: 349941451a9954f29938fb91b0324662b306d215ce725e68faa00d25937b883d
+  metadata.gz: 8fe38926f435f6f7978468bb08e0b91ebbd6962d5863032a7cb49095856c3c50
+  data.tar.gz: c4523746ddbef25e5c64e8b47ea624393d6efa25f0c6b795a0d69ea7910d2683
 SHA512:
-  metadata.gz: '002348ac24e6f8bf513478702c6c08368fb1ee8c788ad8a893d7a848e41103ee6208e5e24f260e0be79eb069700047d408b0c51e51ea3b861bccf55fe2312882'
-  data.tar.gz: 14431a1691709376eb73196c5c7280a7d0ec451d4eb58a3e8ffa3bc43bb6cf26f4433b8f4d6fb488db57d9be06bbcf4f974e5175719d44766a1247271ea76e34
+  metadata.gz: ef54cc72949be0609a9bd1feacad07b202c90b183f6be89c6494c19a95944639ccc0cba3986375a16234803aa96f4e90721abc2308fa75e20ace407504bfedce
+  data.tar.gz: 4143b1a1d0d84597da9fa29ef745a9ca0002fc4bc6107a9206b700453f511cdc1e7a0bc6eea16af69e169cc3c220ff43bbbdd5b8603df58704bcc9d51fa5d58b

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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)
 
 

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.

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.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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dsl_compose
 version: !ruby/object:Gem::Version
-  version: 1.13.1
+  version: 1.14.0
 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