dsl_compose 2.6.1 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ab97e49cd1581273bc3555e75d7610cab0764024f5c87445cf7da2f48af97d4
-  data.tar.gz: bc8e659445fad939868276749ae23c8e5cd3a44d7afb45989d4cd5dac4b487a2
+  metadata.gz: 9eca7fac101d871e9ce111652e859f93eee66b0c8997fd2d2334231f256b6ebd
+  data.tar.gz: 3e858226842b60303d39af62eebc95208ac72b4839f816da45e8d678a078cfbc
 SHA512:
-  metadata.gz: 3e7e18eec99d3b458d1a03e5a9feff3aad70696318d706bf17064646ceeb152d45f4b0b954aef83cb5edcf501502d76821a44c2da58f88d60a91cba31ae18c70
-  data.tar.gz: 8412d42847af88966b8e523ccda0c37f2724d71c319b244cb1a1f206694899b0cad65e5aaf48d9252e597dd9c1afc8ae50f3bc13e6d4b0459669340f7d242dbb
+  metadata.gz: c779883cc3eb12be2dbb13ed79cda45dff848501be4d23b283dfd1d4de6a59f3ab5301def52b7947e1d03f22671080bae84e290cf05ff7d92432892d97917365
+  data.tar.gz: 9e14efabd12ee806787bceffa742007ae6f8d631e87f02856357418458c4d707e8702ca2eabbb8a332f1a60aadcfe73cf641fd5eef811c13ad2dfc231e76269f

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dsl_compose
 version: !ruby/object:Gem::Version
-  version: 2.6.1
+  version: 2.7.0
 platform: ruby
 authors:
 - Craig Ulliott