dsl_compose 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cac98dcec2657248ebdbbe75fc478b37789cdc94564bcdf22490e72fe6b25755
-  data.tar.gz: 5a83edd48385063abbbc49de3f227142a808ee2df2b666ab1e9a8c3a6e1a2bc0
+  metadata.gz: c6093d554121170f4ea168c0a5d0e6480befc3ae02f24396b2006534ac7252b2
+  data.tar.gz: 759d6dcf22ff3f049f29f0e4e5fffac72fd535cd1b4b0927934b94cba379ece0
 SHA512:
-  metadata.gz: 7a4a9f7fa6a64e5de3299dc7e8e4163db7d1979133082b2c4910af4e79317d0893516fb18848a1182d0e3740a2916a738f2beb20aa956427e9f7b860db2fd9bb
-  data.tar.gz: 7ce788aa46123b8cbbaa8a11a1512433916c72ed5dc584efd74a48c11659f60814a649a54413a41b34afdcc30d14e872e3eeef81f5aff81a736ae9aadcf4fb6a
+  metadata.gz: 2406e9b5a49d8764a4dc66b00489f58686cb2135980345cac72dbf451c5b97693cfae625153980dd2c124bf84a80b96c8aa59c924c275b36ae825a366194b194
+  data.tar.gz: 83bf9a8302f434adb63906e1abf07ffb3d56a3bcc9336465b0647710e42ff3b076be3d255df19aad6ff7a6f4a35fcbcec37aee4a3bf1f9d5b05ff767d07a377e

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.1.0](https://github.com/craigulliott/dsl_compose/compare/v1.0.0...v1.1.0) (2023-06-20)
+
+
+### Features
+
+* a first complete working version ([#3](https://github.com/craigulliott/dsl_compose/issues/3)) ([d64a666](https://github.com/craigulliott/dsl_compose/commit/d64a6663e5cedcf67af1c8cbad1736c2a7e81282))
+* basic first version which includes internal DSL for composing dynamic DSLs ([37a3753](https://github.com/craigulliott/dsl_compose/commit/37a3753c68455bec579d879f4989f272480e2b06))
+
+
+### Bug Fixes
+
+* incorrect constant name used in version.rb ([a8cdd0b](https://github.com/craigulliott/dsl_compose/commit/a8cdd0b45fddf12fc1db8c0048c00e36cf183673))
+
 ## 1.0.0 (2023-06-09)
 
 

data/README.md

@@ -1,7 +1,21 @@
-# DslCompose
+# DSLCompose
 
 Ruby gem to add dynamic DSLs to classes
 
+[![Gem Version](https://badge.fury.io/rb/dsl_compose.svg)](https://badge.fury.io/rb/dsl_compose)
+[![Specs](https://github.com/craigulliott/dsl_compose/actions/workflows/specs.yml/badge.svg)](https://github.com/craigulliott/dsl_compose/actions/workflows/specs.yml)
+[![Types](https://github.com/craigulliott/dsl_compose/actions/workflows/types.yml/badge.svg)](https://github.com/craigulliott/dsl_compose/actions/workflows/types.yml)
+[![Coding Style](https://github.com/craigulliott/dsl_compose/actions/workflows/linter.yml/badge.svg)](https://github.com/craigulliott/dsl_compose/actions/workflows/linter.yml)
+
+## Key Features
+
+* Contains a simple internal DSL which is used to declare dynamic DSLs on your classes
+* Takes special care not to pollute the namespace of classes where it is used
+* Use of your declared DSLs is validated at run time
+* Automatically generate documentation and instructions for your DSLs
+* Complete test covereage
+* Very lightweight and no external dependencies
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -16,13 +30,296 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 DSLs are added to classes by including the DSLCompose module, and then calling the add_dsl singleton method within the class or a child class.
 
+### Defining your DSL
+
+```ruby
+class Foo
+  include DSLCompose::Composer
+
+  # Define and name the DSL. Your DSL will available on this
+  # class and any children of this class.
+  define_dsl :my_dsl do
+
+    # A description of your DSL.
+    description <<-DESCRIPTION
+      Add a description of your DSL here, this description will be
+      used when generating the documentation for your DSL.
+
+      You can use **Markdown** in this description.
+    DESCRIPTION
+
+    # Define a method which will be available within your DSL. These
+    # methods will be exposed inside your DSL and can be called multiple times.
+    add_method :an_optional_method do
+      # You should provide descriptions for your methods. These descriptions will
+      # be used when generating your documentation. Both of these descriptions
+      # accept markdown
+      description "A description of my awesome method"
+
+      # add your method argument definition here
+    end
+
+    # Define a required within your DSL. If a class uses your DSL but
+    # does not execute this method then an error will be raised.
+    add_method :a_required_method, required: true do
+      # add your description and method argument definition here (see below)
+    end
+
+    # Define a method which can only be called once within your DSL. These
+    # methods will raise an error of they are called multiple times.
+    #
+    # There "unique" methods can be optionally marked as required.
+    add_unique_method :an_optional_method do
+      # add your description and method argument definition here (see below)
+    end
+
+    # Define a method in your DSL which takes arguments
+    add_method :my_method do
+      # A description of my DSL method
+      description "A description of my DSL method"
+
+      # You can add required arguments to your methods. The order in which you
+      # define these arguments determines the order of the arguments in your final DSL.
+      #
+      # Arguments are validated, and their expected type must be defined. Supported
+      # argument types are :integer, :boolean, :float, :string or :symbol
+      requires :my_first_argument, :symbol do
+        # You should provide descriptions for your arguments. These descriptions will
+        # be used when generating your documentation. This description supports markdown
+        description "A description of the first argument for this method"
+      end
+
+      # You can also add optional arguments to your DSL methods. All optional
+      # arguments must be added after required ones. An error will be raised if
+      # you define a required argument after an optional one.
+      optional :an_optional_argument, :integer do
+        description "A description of an optional argument"
+
+        # You can add validation to your arguments. A full list is provided later in this document
+        validate_greater_than 0
+      end
+    end
+
+  end
+end
+
+```
+
+### Using your DSL
+
+Child classes can then use your new DSL
+
+```ruby
+class Bar << Foo
+
+  my_dsl do
+    my_method my_first_argument, my_second_argument, optional_arg: optional_arg_value
+  end
+
+end
+```
+
+## Examples
+
+### Defining a DSL which can be used to configure a client library
+
+Define the DSL
+
+```ruby
+class MyClientLibrary
+  include DSLCompose::Composer
+
+  define_dsl :configure do
+    description "Configure the settings for MyClientLibrary"
+
+    add_unique_method :api_key, required: true do
+      description <<-DESCRIPTION
+        Your API key.
+
+        API keys can be generated from your developer
+        portal at https://developer.example.com/keys
+      DESCRIPTION
+
+      requires :key, :string do
+        description "The api key"
+        validate_format /\A[a-z]{4}-[a-z0-9]{16}\Z/
+      end
+    end
+
+    add_method :log_provider, required: true do
+      description "Activate and configure a log provider for MyClientLibrary"
+
+      requires :provider, :symbol do
+        description "The log provider"
+        validate_in [:stdout, :rails]
+      end
+
+      optional :verbosity, :integer do
+        description "The log provider"
+        validate_greater_than_or_equal_to 0
+        validate_less_than_or_equal_to 3
+      end
+    end
+
+  end
+end
+```
+
+Using the DSL
+
+```ruby
+MyClientLibrary.configure do
+  api_key "afdl-f1ifb2tslhzqwdis"
+  log_provider :stdout, verbosity: 1
+  log_provider :rails, verbosity: 3
+end
+```
+
+## Argument validations
+
+The following validations can be added to the arguments of your DSL methods. Validations can be added to both required and optional arguments, and you can add multiple validations to each argument.
+
+### Numeric Attributes (:integer and :float)
+
+```ruby
+  define_dsl :my_dsl do
+    add_method :my_method do
+
+      requires :my_first_argument, :integer do
+        # The argument must be greater than a provided number.
+        validate_greater_than 0
+
+        # The argument must be greater than or equal to a provided number.
+        validate_greater_than_or_equal_to 0
+
+        # The argument must be less than a provided number.
+        validate_less_than 10
+
+        # The argument must be less than or equal to a provided number.
+        validate_less_than_or_equal_to 10
+
+        # The argument must be exactly equal to a provided number.
+        validate_equal_to 5
+
+        # The argument must not be one of the provided values.
+        validate_not_in [1, 2]
+
+        # The argument must be one of the provided values.
+        validate_in [3, 4]
+      end
+
+    end
+  end
+```
+
+### String attributes (:string)
+
+```ruby
+  define_dsl :my_dsl do
+    add_method :my_method do
+
+      requires :my_first_argument, :string do
+
+        # The text value must be at least a provided length.
+        validate_length minimum: 0
+
+        # The text value must be at most a provided length.
+        validate_length maximum: 10
+
+        # you can combine the minimum and maximum validations
+        validate_length minimum: 0, maximum: 10
+
+        # The length of the text must be exactly the provided value.
+        validate_length is: 10
+
+        # The argument must not be one of the provided values.
+        validate_not_in ["foo", "bar"]
+
+        # The argument must be one of the provided values.
+        validate_in ["cat", "dog"]
+
+        # The argument must match the provided regex.
+        validate_format /\A[A-Z][a-z]+\Z/
+
+      end
+
+    end
+  end
+```
+
+### Symbol attributes (:symbol)
+
+```ruby
+  define_dsl :my_dsl do
+    add_method :my_method do
+
+      requires :my_first_argument, :symbol do
+
+        # The text value must be at least a provided length.
+        validate_length minimum: 0
+
+        # The text value must be at most a provided length.
+        validate_length maximum: 10
+
+        # you can combine the minimum and maximum validations
+        validate_length minimum: 0, maximum: 10
+
+        # The length of the text must be exactly the provided value.
+        validate_length is: 10
+
+        # The argument must not be one of the provided values.
+        validate_not_in [:foo, :bar]
+
+        # The argument must be one of the provided values.
+        validate_in [:cat, :dog]
+
+        # The argument must match the provided regex.
+        validate_format /\A[A-Z][a-z]+\Z/
+
+      end
+
+    end
+  end
+```
+
+### Boolean attributes (:boolean)
+
+```ruby
+  define_dsl :my_dsl do
+    add_method :my_method do
+
+      requires :my_first_argument, :boolean do
+
+        # The argument must be equal to a provided value
+        # for boolean attributes, this provided value can be either false or true.
+
+        # The provided attribute must be `false`.
+        validate_equal_to false
+
+      end
+
+    end
+  end
+```
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 We use [Conventional Commit Messages](https://gist.github.com/qoomon/5dfcdf8eec66a051ecd85625518cfd13).
 
-Publishing is automated via github actions and [googles release please](https://github.com/google-github-actions/release-please-action)
+Code should be linted and formatted according to [Ruby Standard](https://github.com/standardrb/standard).
+
+Publishing is automated via github actions and Googles [Release Please](https://github.com/google-github-actions/release-please-action) github action
+
+We prefer using squash-merges when merging pull requests because it helps keep a linear git history and allows more fine grained control of commit messages which get sent to release-please and ultimately show up in the changelog.
+
+Type checking is enabled for this project. You can find the corresponding `rbs` files in the sig folder.
+
+Install types for the packages used in development (such as `rspec`) by running
+
+    $ rbs collection install
 
 ## Contributing
 
@@ -34,4 +331,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the DslCompose project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/craigulliott/dsl_compose/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the DSLCompose project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/craigulliott/dsl_compose/blob/master/CODE_OF_CONDUCT.md).

data/lib/dsl_compose/composer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  module Composer
+    class ComposerAlreadyInstalledError < StandardError
+      def message
+        "This module has already been included or the define_dsl singleton method already exists for this class."
+      end
+    end
+
+    class MethodAlreadyExistsWithThisDSLNameError < StandardError
+      def message
+        "The define_dsl singleton method already exists for this class."
+      end
+    end
+
+    class GetDSLExecutionResultsMethodAlreadyExistsError < StandardError
+      def message
+        "The dsl_interpreter singleton method already exists for this class."
+      end
+    end
+
+    def self.included klass
+      if (klass.private_methods + klass.methods).include? :define_dsl
+        raise ComposerAlreadyInstalledError
+      end
+
+      # create an interpreter for this class which will be shared by all child classes and all
+      # the dynamicly defined DSLs in this class
+      interpreter = DSLCompose::Interpreter.new
+
+      # return a specific DSL which is defined for this class
+      if klass.respond_to? :dsl_interpreter
+        raise GetDSLExecutionResultsMethodAlreadyExistsError
+      end
+
+      klass.define_singleton_method :dsl_interpreter do
+        interpreter
+      end
+
+      # return a specific DSL which is defined for this class
+      klass.define_singleton_method :define_dsl do |name, &block|
+        # Find or create a DSL with this name for the provided class. We allow an existing
+        # DSL to be accessed so that it can be be extended (have new methods added to it).
+        # `self` here is the class in which `define_dsl` is being called
+        if DSLCompose::DSLs.class_dsl_exists? self, name
+          # get the existing DSL
+          dsl = DSLCompose::DSLs.class_dsl self, name
+
+        else
+          dsl = DSLCompose::DSLs.create_dsl self, name
+
+          # ensure that creating this DSL will not override any existing methods on this class
+          if respond_to? name
+            raise MethodAlreadyExistsWithThisDSLNameError
+          end
+
+          # add a singleton method with the name of this new DSL onto our class, this is how our new DSL will be accessed
+          define_singleton_method name do |&block|
+            # when it is called, we process this new dynamic DSL with the interpreter
+            # `self` here is the class in which the dsl is being used, not the class in which the DSL was defined
+            interpreter.execute_dsl self, dsl, &block
+          end
+
+        end
+
+        # evaluate the configuration block which uses our internal DSL to define this dynamic DSL
+        if block
+          dsl.evaluate_configuration_block(&block)
+        end
+      end
+    end
+  end
+end

data/lib/dsl_compose/dsl/dsl_method/argument/equal_to_validation.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class DSL
+    class DSLMethod
+      class Argument
+        class EqualToValidation
+          class ValidationFailedError < StandardError
+            def message
+              "The argument is invalid"
+            end
+          end
+
+          def initialize value
+            @value = value
+          end
+
+          def validate! value
+            raise ValidationFailedError unless value == @value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dsl_compose/dsl/dsl_method/argument/format_validation.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class DSL
+    class DSLMethod
+      class Argument
+        class FormatValidation
+          class ValidationFailedError < StandardError
+            def message
+              "The argument is invalid"
+            end
+          end
+
+          def initialize regex
+            @regex = regex
+          end
+
+          def validate! value
+            raise ValidationFailedError if @regex.match(value).nil?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dsl_compose/dsl/dsl_method/argument/greater_than_or_equal_to_validation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class DSL
+    class DSLMethod
+      class Argument
+        class GreaterThanOrEqualToValidation
+          class InvalidValueError < StandardError
+            def message
+              "The value provided to validate_greater_than must be a number"
+            end
+          end
+
+          class ValidationFailedError < StandardError
+            def message
+              "The argument is invalid"
+            end
+          end
+
+          def initialize value
+            unless value.is_a?(Numeric)
+              raise InvalidValueError
+            end
+
+            @value = value
+          end
+
+          def validate! value
+            raise ValidationFailedError unless value >= @value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dsl_compose/dsl/dsl_method/argument/greater_than_validation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class DSL
+    class DSLMethod
+      class Argument
+        class GreaterThanValidation
+          class InvalidValueError < StandardError
+            def message
+              "The value provided to validate_greater_than must be a number"
+            end
+          end
+
+          class ValidationFailedError < StandardError
+            def message
+              "The argument is invalid"
+            end
+          end
+
+          def initialize value
+            unless value.is_a?(Numeric)
+              raise InvalidValueError
+            end
+
+            @value = value
+          end
+
+          def validate! value
+            raise ValidationFailedError unless value > @value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dsl_compose/dsl/dsl_method/argument/in_validation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class DSL
+    class DSLMethod
+      class Argument
+        class InValidation
+          class InvalidValueError < StandardError
+            def message
+              "The value provided to validate_greater_than must be a number"
+            end
+          end
+
+          class ValidationFailedError < StandardError
+            def message
+              "The argument is invalid"
+            end
+          end
+
+          def initialize values
+            unless values.is_a?(Array)
+              raise InvalidValueError
+            end
+
+            @values = values
+          end
+
+          def validate! value
+            raise ValidationFailedError unless @values.include? value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dsl_compose/dsl/dsl_method/argument/interpreter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class DSL
+    class DSLMethod
+      class Argument
+        # This class is reponsible for parsing and executing argument definitions
+        # within our internal DSL. These argument definitions determine what arguments
+        # will be available on the methods within our new dynamic DSL.
+        #
+        # This class is instantaited by the DSLCompose::DSL::DSLMethod::Argument class and the
+        # method argument definition part of our internal DSL is evaluated by passing a block
+        # to `instance_eval` on this class.
+        #
+        # An example of our internal DSL which includes a method definition with complex arguments:
+        #  define_dsl :my_dsl do
+        #    add_method :my_method, required: true do
+        #      description "Description of my method"
+        #      optional :my_optional_argument, :string do
+        #        description "A description of this argument"
+        #        validate_greater_than 10
+        #      end
+        #      optional :my_optional_arg, String
+        #    end
+        #  end
+        class Interpreter
+          def initialize argument
+            @argument = argument
+          end
+
+          private
+
+          # sets the description of the Argument
+          def description description
+            @argument.set_description description
+          end
+
+          # adds a greater_than validator to the argument
+          def validate_greater_than value
+            @argument.validate_greater_than value
+          end
+
+          # adds a greater_than_or_equal_to validator to the argument
+          def validate_greater_than_or_equal_to value
+            @argument.validate_greater_than_or_equal_to value
+          end
+
+          # adds a less_than validator to the argument
+          def validate_less_than value
+            @argument.validate_less_than value
+          end
+
+          # adds a less_than_or_equal_to validator to the argument
+          def validate_less_than_or_equal_to value
+            @argument.validate_less_than_or_equal_to value
+          end
+
+          # adds a equal_to validator to the argument
+          def validate_equal_to value
+            @argument.validate_equal_to value
+          end
+
+          # adds a length validator to the argument
+          def validate_length minimum: nil, maximum: nil, is: nil
+            @argument.validate_length minimum: minimum, maximum: maximum, is: is
+          end
+
+          # adds a not_in validator to the argument
+          def validate_not_in values
+            @argument.validate_not_in values
+          end
+
+          # adds a in validator to the argument
+          def validate_in values
+            @argument.validate_in values
+          end
+
+          # adds a format validator to the argument
+          def validate_format regexp
+            @argument.validate_format regexp
+          end
+        end
+      end
+    end
+  end
+end