dsl_compose 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '048f2e5d2e94df09db474b6134cacb580dde9a88a751e2e0697d72234be0132e'
-  data.tar.gz: b336eb45f722b2fbafb0f12f43d760ad1de2287eb9beffc27227d020daf5cc43
+  metadata.gz: 9eca7fac101d871e9ce111652e859f93eee66b0c8997fd2d2334231f256b6ebd
+  data.tar.gz: 3e858226842b60303d39af62eebc95208ac72b4839f816da45e8d678a078cfbc
 SHA512:
-  metadata.gz: 412d7f101db06e26ad871a359d7d063a0086b0b2b3e8be2e96cd3b87e69ec1eb7f813c770326779e9b16c166433700b6751ecf9e8b35e568313f8350ed31fd30
-  data.tar.gz: 551f08b45107d633abbcdc008fd13e971c41c317e17ce07e86f0035b2d1ee1ef9ddb6e23b2c1505239279d7f90c1940f22b1d111542ecc51a253b588bb101823
+  metadata.gz: c779883cc3eb12be2dbb13ed79cda45dff848501be4d23b283dfd1d4de6a59f3ab5301def52b7947e1d03f22671080bae84e290cf05ff7d92432892d97917365
+  data.tar.gz: 9e14efabd12ee806787bceffa742007ae6f8d631e87f02856357418458c4d707e8702ca2eabbb8a332f1a60aadcfe73cf641fd5eef811c13ad2dfc231e76269f

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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)
+
+
+### Bug Fixes
+
+* renaming `description` to `add_documentation` for dynamically creating documentation from within parsers ([3e24194](https://github.com/craigulliott/dsl_compose/commit/3e2419492e61d94ea7d3c1f34ef4990fc0f6682a))
+
 ## [2.6.0](https://github.com/craigulliott/dsl_compose/compare/v2.5.2...v2.6.0) (2023-08-23)
 
 

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/interpreter/execution/arguments.rb

@@ -148,7 +148,6 @@ module DSLCompose
               else
                 optional_arg_value
               end
-
             rescue => e
               raise e, "Error processing optional argument #{optional_argument_name}: #{e.message}", e.backtrace
             end
@@ -239,7 +238,6 @@ module DSLCompose
             else
               required_arg_value
             end
-
           rescue => e
             raise e, "Error processing required argument #{argument_name}: #{e.message}", e.backtrace
           end

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

@@ -14,12 +14,12 @@ module DSLCompose
           @method_calls.filter { |mc| mc.method_name == method_name }.any?
         end
 
-        def add_method_call dsl_method, *args, &block
+        def add_method_call(dsl_method, ...)
           # make sure we always have a variable which can be used in the exception message
           dsl_method_name = nil
           dsl_method_name = dsl_method.name
 
-          method_call = MethodCall.new(dsl_method, *args, &block)
+          method_call = MethodCall.new(dsl_method, ...)
           @method_calls << method_call
           method_call
         rescue => e

data/lib/dsl_compose/interpreter/execution.rb

@@ -59,7 +59,7 @@ module DSLCompose
       private
 
       # catch and process any method calls within the DSL block
-      def method_missing method_name, *args, &block
+      def method_missing(method_name, ...)
         # if the method does not exist, then this will raise a MethodDoesNotExistError
         dsl_method = @dsl.dsl_method method_name
 
@@ -68,7 +68,7 @@ module DSLCompose
           raise MethodIsUniqueError, "This method `#{method_name}` is unique and can only be called once within this DSL"
         end
 
-        @method_calls.add_method_call dsl_method, *args, &block
+        @method_calls.add_method_call(dsl_method, ...)
       end
 
       def respond_to_missing?(method_name, *args)

data/lib/dsl_compose/interpreter.rb

@@ -40,14 +40,14 @@ module DSLCompose
     # 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.
-    def execute_dsl klass, dsl, *args, &block
+    def execute_dsl(klass, dsl, ...)
       # make sure we have these variables for the exception message below
       class_name = nil
       class_name = klass.name
       dsl_name = nil
       dsl_name = dsl.name
 
-      execution = Execution.new(klass, dsl, *args, &block)
+      execution = Execution.new(klass, dsl, ...)
       @executions << execution
       execution
     rescue => e

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

@@ -107,8 +107,8 @@ module DSLCompose
           # 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
+          def add_documentation documentation
+            @method_call.add_parser_usage_note documentation
           end
         end
       end

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

@@ -142,8 +142,8 @@ module DSLCompose
         # 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
+        def add_documentation documentation
+          @dsl_execution.add_parser_usage_note documentation
         end
       end
     end

data/lib/dsl_compose/parser/for_children_of_parser.rb

@@ -125,8 +125,8 @@ module DSLCompose
       # 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
+      def add_documentation documentation
+        @base_class.dsls.add_parser_usage_note @child_class, documentation
       end
     end
   end

data/lib/dsl_compose/version.rb

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

metadata

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