dsl_compose 2.6.1 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ab97e49cd1581273bc3555e75d7610cab0764024f5c87445cf7da2f48af97d4
-  data.tar.gz: bc8e659445fad939868276749ae23c8e5cd3a44d7afb45989d4cd5dac4b487a2
+  metadata.gz: c6fea0a926ea88fad5e75633a95629a75105580958b512baae3362c47aa2384c
+  data.tar.gz: '03486a86365c848b0815d768eb7de00478bebeb8b87d9412a4b06db67857ebcd'
 SHA512:
-  metadata.gz: 3e7e18eec99d3b458d1a03e5a9feff3aad70696318d706bf17064646ceeb152d45f4b0b954aef83cb5edcf501502d76821a44c2da58f88d60a91cba31ae18c70
-  data.tar.gz: 8412d42847af88966b8e523ccda0c37f2724d71c319b244cb1a1f206694899b0cad65e5aaf48d9252e597dd9c1afc8ae50f3bc13e6d4b0459669340f7d242dbb
+  metadata.gz: 550d159aca95511d2409fb085ba865f9230ac67fb29ddece4e2f7bbfcf054033e8ce598d6f2ff00d088c27a266c14fdaf1f4405808a6a99fe7ed6888bfeef6a8
+  data.tar.gz: 69c5444f0064dbe31a3da9be2a0712fc419758d3ca661ecf70a22429e80d4581e451a1840a28a7fc2d44902b183d20dc9069036d0f062ad78465de6c58a86a4c

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.8.0](https://github.com/craigulliott/dsl_compose/compare/v2.7.0...v2.8.0) (2023-08-31)
+
+
+### Features
+
+* adding a rerun_all singleton method to re-execute all parsers in the system (useful from within specs) ([d0c4ee3](https://github.com/craigulliott/dsl_compose/commit/d0c4ee3cc41da45e774a17ab9d57990dbbf59603))
+
+## [2.7.0](https://github.com/craigulliott/dsl_compose/compare/v2.6.1...v2.7.0) (2023-08-29)
+
+
+### Features
+
+* adding `namespace` and `title` methods to DSL generation. These help with documentation generation ([1bdf16d](https://github.com/craigulliott/dsl_compose/commit/1bdf16de6c1dc872809cc66d6599c36b3a1f1e99))
+
 ## [2.6.1](https://github.com/craigulliott/dsl_compose/compare/v2.6.0...v2.6.1) (2023-08-29)
 
 

data/README.md

@@ -130,6 +130,31 @@ end
 
 ```
 
+The methods `title` and `namespace` are also available at the top level of your DSL definition. These methods can provide useful metadata when generating documentation, but are typically only useful in much larger systems involving many different DSLs.
+
+```ruby
+class Foo
+  include DSLCompose::Composer
+
+  # DSLs have some top level methods which allow you to set some useful
+  # metadata for use when generating documentation.
+  define_dsl :your_dsl do
+    # You can give your DSLs a friendly title.
+    title "My Friendly DSL Title"
+
+    # You can also logically group a set of DSLs together by setting the same
+    # namespace on each of them.
+    namespace :my_namespace
+
+    # You can also describe this DSL.
+    # Unlike `title` and `namespace`, you can set descriptions on all of your
+    # DSL methods and arguments too (as seen in the various examples above)
+    description "A description of your DSL"
+
+  end
+end
+```
+
 ### Shared Configuration
 
 If you are composing many DSLs across one or many classes and these DSLs share common configuration, then you can share configuration between them.
@@ -247,7 +272,7 @@ class 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
+    add_documentation <<~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
 
@@ -281,7 +306,7 @@ class MyParser < DSLCompose::Parser
     # which were called within this use of your DSL. There is more documentation about
     # Reader classes below.
     for_dsl [:dsl1, :dsl2] do |dsl_name:, a_dsl_argument:, reader:|
-      description <<~DESCRIPTION
+      add_documentation <<~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.
 
@@ -308,7 +333,7 @@ class 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
+        add_documentation <<~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.
 

data/lib/dsl_compose/dsl/interpreter.rb

@@ -28,6 +28,17 @@ module DSLCompose
         @dsl.set_description description
       end
 
+      # sets the namespace of the DSL, this is used
+      # to group DSLs together in documentation
+      def namespace namespace
+        @dsl.set_namespace namespace
+      end
+
+      # sets the title of the DSL
+      def title title
+        @dsl.set_title title
+      end
+
       # adds a new method to the DSL
       #
       # methods flagged as `required` will cause your DSLs to raise an error

data/lib/dsl_compose/dsl.rb

@@ -21,6 +21,18 @@ module DSLCompose
     class DescriptionAlreadyExistsError < StandardError
     end
 
+    class InvalidNamespaceError < StandardError
+    end
+
+    class NamespaceAlreadyExistsError < StandardError
+    end
+
+    class InvalidTitleError < StandardError
+    end
+
+    class TitleAlreadyExistsError < StandardError
+    end
+
     class NoBlockProvidedError < StandardError
     end
 
@@ -31,6 +43,12 @@ module DSLCompose
     # An otional description of this DSL, if provided then it must be a string.
     # The description accepts markdown and is used when generating documentation.
     attr_reader :description
+    # An otional namespace for this DSL, if provided then it must be a Symbol. This
+    # is currently used to group DSLs for the sake of documentation.
+    attr_reader :namespace
+    # An otional namespace for this DSL, if provided then it must be a String. This
+    # is currently used when generating documentation.
+    attr_reader :title
     # an object which represents the argument configuration
     attr_reader :arguments
 
@@ -85,11 +103,55 @@ module DSLCompose
       @description = description.strip
     end
 
+    # Set the namespace for this DSL to the provided value.
+    #
+    # `namespace` must be a Symbol.
+    # The `namespace` can only be set once per DSL
+    # this is currently used for grouping together DSLS for the sake of documentation
+    def set_namespace namespace
+      unless namespace.is_a?(Symbol)
+        raise InvalidNamespaceError, "The DSL namespace `#{namespace}` is invalid, it must be of type Symbol"
+      end
+
+      if has_namespace?
+        raise NamespaceAlreadyExistsError, "The DSL namespace has already been set"
+      end
+
+      @namespace = namespace
+    end
+
+    # Set the title for this DSL to the provided value.
+    #
+    # `title` must be a String with a length greater than 0.
+    # The `title` can only be set once per DSL
+    # this is currently used for documentation
+    def set_title title
+      unless title.is_a?(String) && title.strip.length > 0
+        raise InvalidTitleError, "The DSL title `#{title}` is invalid, it must be of type string and have length greater than 0"
+      end
+
+      if has_title?
+        raise TitleAlreadyExistsError, "The DSL title has already been set"
+      end
+
+      @title = title.strip
+    end
+
     # Returns `true` if this DSL has a description, else false.
     def has_description?
       @description.nil? == false
     end
 
+    # Returns `true` if this DSL has a namespace, else false.
+    def has_namespace?
+      @namespace.nil? == false
+    end
+
+    # Returns `true` if this DSL has a title, else false.
+    def has_title?
+      @title.nil? == false
+    end
+
     # Takes a method name, unique flag, required flag, and a block and creates
     # a new DSLMethod object.
     #

data/lib/dsl_compose/parser.rb

@@ -32,12 +32,17 @@ module DSLCompose
     # children of their own)
     def self.for_children_of base_class, final_children_only: false, rerun: false, &block
       unless rerun
-        @runs ||= []
-        @runs << {
+        run = {
           base_class: base_class,
           final_children_only: final_children_only,
           block: block
         }
+
+        @@all_runs ||= []
+        @@all_runs << run
+
+        @runs ||= []
+        @runs << run
       end
 
       # we parse the provided block in the context of the ForChildrenOfParser class
@@ -56,7 +61,7 @@ module DSLCompose
     # this method is used to rerun the parser, this is most useful from within a test suite
     # when you are testing the parser itself
     def self.rerun
-      # rerun each parset tests
+      # rerun each parser for this specific class
       @runs&.each do |run|
         base_class = run[:base_class]
         block = run[:block]
@@ -64,5 +69,17 @@ module DSLCompose
         for_children_of base_class, rerun: true, final_children_only: final_children_only, &block
       end
     end
+
+    # this method is used to rerun all of the parsers, this is most useful from within a test suite
+    # when you are testing the parser itself
+    def self.rerun_all
+      # rerun each parser for all classes (call this method directly on the parser object `DSLCompose::Parser.rerun_all`)
+      @all_runs&.each do |run|
+        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
+      end
+    end
   end
 end

data/lib/dsl_compose/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dsl_compose
 version: !ruby/object:Gem::Version
-  version: 2.6.1
+  version: 2.8.0
 platform: ruby
 authors:
 - Craig Ulliott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-08-29 00:00:00.000000000 Z
+date: 2023-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: class_spec_helper