dsl_compose 1.0.0 → 1.1.0

data/lib/dsl_compose/dsl/dsl_method.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class DSL
+    class DSLMethod
+      class ArgumentDoesNotExistError < StandardError
+        def message
+          "This argument does not exist for this DSLMethod"
+        end
+      end
+
+      class InvalidNameError < StandardError
+        def message
+          "The method #{method_name} is invalid, it must be of type symbol"
+        end
+      end
+
+      class MethodNameIsReservedError < StandardError
+        def message
+          "This method already would override an existing internal method"
+        end
+      end
+
+      class InvalidDescriptionError < StandardError
+        def message
+          "The DSL method description is invalid, it must be of type string and have length greater than 0"
+        end
+      end
+
+      class DescriptionAlreadyExistsError < StandardError
+        def message
+          "The description has already been set"
+        end
+      end
+
+      class ArgumentOrderingError < StandardError
+        def message
+          "Required arguments can not be added after optional ones"
+        end
+      end
+
+      class ArgumentAlreadyExistsError < StandardError
+        def message
+          "An argument with this name already exists for this DSL method"
+        end
+      end
+
+      class RequestedOptionalArgumentIsRequiredError < StandardError
+        def message
+          "A specific argument which was expected to be optional was requested, but the argument found was flagged as required"
+        end
+      end
+
+      class RequestedRequiredArgumentIsOptionalError < StandardError
+        def message
+          "A specific argument which was expected to be required was requested, but the argument found was flagged as optional"
+        end
+      end
+
+      # The name of this DSLMethod.
+      attr_reader :name
+      # if unique, then this DSLMethod can only be called once within the DSL.
+      attr_reader :unique
+      # if required, then this DSLMethod must be called at least once within the DSL.
+      attr_reader :required
+      # An otional description of this DSLMethod, if provided then it must be a string.
+      # The description accepts markdown and is used when generating documentation.
+      attr_reader :description
+
+      # Create a new DSLMethod object with the provided name and class.
+      #
+      # `name` must be a symbol.
+      # `unique` is a boolean which determines if this DSLMethod can only be called once witihn the DSL.
+      # `required` is a boolean which determines if this DSLMethod must be called at least once within the DSL.
+      # `block` contains the instructions to further configure this DSLMethod
+      def initialize name, unique, required, &block
+        @arguments = {}
+
+        if name.is_a? Symbol
+
+          # don't allow methods to override existing internal methods
+          if Class.respond_to? name
+            raise MethodNameIsReservedError
+          end
+
+          @name = name
+        else
+          raise InvalidNameError
+        end
+
+        @unique = unique ? true : false
+        @required = required ? true : false
+
+        # If a block was provided, then we evaluate it using a seperate
+        # interpreter class. We do this because the interpreter class contains
+        # no other methods or variables, if it was evaluated in the context of
+        # this class then the block would have access to all of the methods defined
+        # in here.
+        if block
+          Interpreter.new(self).instance_eval(&block)
+        end
+      end
+
+      # Set the description for this DSLMethod to the provided value.
+      #
+      # `description` must be a string with a length greater than 0.
+      # The `description` can only be set once per DSLMethod
+      def set_description description
+        unless description.is_a?(String) && description.length > 0
+          raise InvalidDescriptionError
+        end
+
+        if has_description?
+          raise DescriptionAlreadyExistsError
+        end
+
+        @description = description
+      end
+
+      # Returns `true` if this DSL has a description, else false.
+      def has_description?
+        @description.nil? == false
+      end
+
+      # Returns an array of all this DSLMethods Argument objects.
+      def arguments
+        @arguments.values
+      end
+
+      # Returns an array of only the optional Argument objects on this DSLMethod.
+      def optional_arguments
+        arguments.filter(&:optional?)
+      end
+
+      # Returns an array of only the required Argument objects on this DSLMethod.
+      def required_arguments
+        arguments.filter(&:required?)
+      end
+
+      # returns a specific Argument by it's name, if the Argument does not
+      # exist, then an error is raised
+      def argument name
+        if has_argument? name
+          @arguments[name]
+        else
+          raise ArgumentDoesNotExistError
+        end
+      end
+
+      # returns a specific optional Argument by it's name, if the Argument does not
+      # exist, or if it is required, then an error is raised
+      def optional_argument name
+        arg = argument name
+        if arg.optional?
+          @arguments[name]
+        else
+          raise RequestedOptionalArgumentIsRequiredError
+        end
+      end
+
+      # returns a specific required Argument by it's name, if the Argument does not
+      # exist, or if it is optional, then an error is raised
+      def required_argument name
+        arg = argument name
+        if arg.required?
+          @arguments[name]
+        else
+          raise RequestedRequiredArgumentIsOptionalError
+        end
+      end
+
+      # Returns `true` if an Argument with the provided name exists in this
+      # DSLMethod, otherwise it returns `false`.
+      def has_argument? name
+        @arguments.key? name
+      end
+
+      # returns true if this DSLMethod is flagged as unique, otherwise returns false.
+      def unique?
+        @unique == true
+      end
+
+      # returns true if this DSLMethod is flagged as required, otherwise returns false.
+      def required?
+        @required == true
+      end
+
+      # returns true if this DSLMethod is flagged as optional, otherwise returns false.
+      def optional?
+        @required == false
+      end
+
+      # Takes a method name, unique flag, required flag, and a block and creates
+      # a new Argument object.
+      #
+      # Argument `name` must be unique within the DSLMethod.
+      # `required` must be a boolean, and determines if this argument will be required
+      # or optional on the method which is exposed in our DSL.
+      def add_argument name, required, type, &block
+        if @arguments.key? name
+          raise ArgumentAlreadyExistsError
+        end
+
+        # required arguments may not come after optional ones
+        if required && optional_arguments.any?
+          raise ArgumentOrderingError
+        end
+
+        @arguments[name] = Argument.new(name, required, type, &block)
+      end
+    end
+  end
+end

data/lib/dsl_compose/dsl/interpreter.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class DSL
+    # The class is reponsible for parsing and executing our internal DSL which is used to define
+    # a new dynamic DSL. This class is instantaited by the DSLCompose::DSL class and our internal
+    # DSL is evaluated by passing a block to `instance_eval` on this class.
+    #
+    # An example of our internal DSL:
+    #  define_dsl :my_dsl do
+    #    description "This is my DSL"
+    #    add_method :my_method do
+    #      # ...
+    #    end
+    #    add_unique_method :my_uniq_method do
+    #      # ...
+    #    end
+    #  end
+    class Interpreter
+      def initialize dsl
+        @dsl = dsl
+      end
+
+      private
+
+      # sets the description of the DSL
+      def description description
+        @dsl.set_description description
+      end
+
+      # adds a new method to the DSL
+      #
+      # methods flagged as `required` will cause your DSLs to raise an error
+      # if they are not used at least once within your new DSLs
+      # `block` contains the method definition and will be evaluated seperately
+      # by the DSLMethod::Interpreter
+      def add_method name, required: nil, &block
+        @dsl.add_method name, false, required ? true : false, &block
+      end
+
+      # adds a new unique method to the DSL
+      #
+      # methods flagged as `required` will cause your DSLs to raise an error
+      # if they are not used at least once within your new DSLs
+      # `block` contains the method definition and will be evaluated seperately
+      # by the DSLMethod::Interpreter
+      def add_unique_method name, required: nil, &block
+        @dsl.add_method name, true, required ? true : false, &block
+      end
+    end
+  end
+end

data/lib/dsl_compose/dsl.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  # The class is reponsible for creating and representing a dynamic DSL
+  #
+  # These new dynamic DSL's are created using our own internal DSL, which is accessed
+  # by calling `define_dsl` in a class and passing it a block which contains the DSL definition
+  class DSL
+    class MethodDoesNotExistError < StandardError
+      def message
+        "This method does not exist for this DSL"
+      end
+    end
+
+    class MethodAlreadyExistsError < StandardError
+      def message
+        "This method already exists for this DSL"
+      end
+    end
+
+    class InvalidNameError < StandardError
+      def message
+        "This DSL name is invalid, it must be of type symbol"
+      end
+    end
+
+    class InvalidDescriptionError < StandardError
+      def message
+        "This DSL description is invalid, it must be of type string and have length greater than 0"
+      end
+    end
+
+    class DescriptionAlreadyExistsError < StandardError
+      def message
+        "The DSL description has already been set"
+      end
+    end
+
+    class NoBlockProvidedError < StandardError
+      def message
+        "No block was provided for this DSL"
+      end
+    end
+
+    # The name of this DSL.
+    attr_reader :name
+    # klass will be the class where `define_dsl` was called.
+    attr_reader :klass
+    # 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
+
+    # Create a new DSL object with the provided name and class.
+    #
+    # `name` must be a symbol.
+    # `klass` should be the class in which `define_dsl` is being called.
+    def initialize name, klass
+      @dsl_methods = {}
+
+      if name.is_a? Symbol
+        @name = name
+      else
+        raise InvalidNameError
+      end
+
+      @klass = klass
+    end
+
+    # Evaluate the configuration block which defines our new DSL
+    # `block` contains the DSL definition and will be evaluated to create
+    # the rest of the DSL.
+    def evaluate_configuration_block &block
+      if block
+        # We evaluate the internal DSL configuration blocks using a seperate interpreter
+        # class. We do this because the interpreter class contains no other methods or
+        # variables, if it was evaluated in the context of this class then the block
+        # would have access to all of the methods defined in here.
+        Interpreter.new(self).instance_eval(&block)
+      else
+        raise NoBlockProvidedError
+      end
+    end
+
+    # Set the description for this DSL to the provided value.
+    #
+    # `description` must be a string with a length greater than 0.
+    # The `description` can only be set once per DSL
+    def set_description description
+      unless description.is_a?(String) && description.length > 0
+        raise InvalidDescriptionError
+      end
+
+      if has_description?
+        raise DescriptionAlreadyExistsError
+      end
+
+      @description = description
+    end
+
+    # Returns `true` if this DSL has a description, else false.
+    def has_description?
+      @description.nil? == false
+    end
+
+    # Takes a method name, unique flag, required flag, and a block and creates
+    # a new DSLMethod object.
+    #
+    # Method `name` must be unique within the DSL.
+    def add_method name, unique, required, &block
+      if has_dsl_method? name
+        raise MethodAlreadyExistsError
+      end
+
+      @dsl_methods[name] = DSLMethod.new(name, unique, required, &block)
+    end
+
+    # Returns an array of all this DSLs DSLMethods.
+    def dsl_methods
+      @dsl_methods.values
+    end
+
+    # Returns an array of only the required DSLMethods in this DSL.
+    def required_dsl_methods
+      dsl_methods.filter(&:required?)
+    end
+
+    # Returns an array of only the optional DSLMethods in this DSL.
+    def optional_dsl_methods
+      dsl_methods.filter(&:optional?)
+    end
+
+    # returns a specific DSLMethod by it's name, if the DSLMethod does not
+    # exist, then an error is raised
+    def dsl_method name
+      if has_dsl_method? name
+        @dsl_methods[name]
+      else
+        raise MethodDoesNotExistError
+      end
+    end
+
+    # Returns `true` if a DSLMethod  with the provided name exists in this
+    # DSL, otherwise it returns `false`.
+    def has_dsl_method? name
+      @dsl_methods.key? name
+    end
+  end
+end

data/lib/dsl_compose/dsls.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  module DSLs
+    class ClassDSLDefinitionDoesNotExistError < StandardError
+      def message
+        "The requested DSL does not exist on this class"
+      end
+    end
+
+    class DSLAlreadyExistsError < StandardError
+      def message
+        "A DSL with this name already exists"
+      end
+    end
+
+    class NoDSLDefinitionsForClassError < StandardError
+      def message
+        "No DSLs have been defined for this class"
+      end
+    end
+
+    # an object to hold all of the defined DSLs in our application, the DSLs are
+    # organized by the class in which they were defined
+    @dsls = {}
+
+    # create a new DSL definition for a class
+    # `klass` here is the class in which `define_dsl` was called
+    def self.create_dsl klass, name
+      @dsls[klass] ||= {}
+
+      if @dsls[klass].key? name
+        raise DSLAlreadyExistsError
+      end
+
+      @dsls[klass][name] = DSLCompose::DSL.new(name, klass)
+    end
+
+    # return all of the DSL definitions
+    def self.dsls
+      @dsls
+    end
+
+    # return a DSL with a provided name for the provided class, if the DSL doesn't
+    # exist then it will be automatically created
+    def self.class_dsl_exists? klass, name
+      @dsls.key?(klass) && @dsls[klass].key?(name)
+    end
+
+    # return an array of DSL definitions for a provided class, if no DSLs
+    # exist for the provided class, then an error is raised
+    def self.class_dsls klass
+      if @dsls.key? klass
+        @dsls[klass].values
+      else
+        raise NoDSLDefinitionsForClassError
+      end
+    end
+
+    # return a specific DSL definition for a provided class
+    # if it does not exist, then an error is raised
+    def self.class_dsl klass, name
+      if @dsls.key? klass
+        if @dsls[klass].key? name
+          @dsls[klass][name]
+        else
+          raise ClassDSLDefinitionDoesNotExistError
+        end
+      else
+        raise NoDSLDefinitionsForClassError
+      end
+    end
+
+    # removes all DSL deinitions, this method is typically used by the test
+    # suite for resetting state inbetween each test
+    def self.reset
+      @dsls = {}
+    end
+  end
+end

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class Interpreter
+    class Execution
+      class MethodCalls
+        class MethodCall
+          attr_reader :dsl_method
+          attr_reader :arguments
+
+          class MissingRequiredArgumentsError < StandardError
+            def initialize required_count, provided_count
+              super "This method requires #{required_count} arguments, but only #{required_count} were provided"
+            end
+          end
+
+          class TooManyArgumentsError < StandardError
+            def message
+              "Too many arguments provided to this method"
+            end
+          end
+
+          class OptionalArgsShouldBeHashError < StandardError
+            def message
+              "If provided, then the optional arguments must be last, and be represented as a Hash"
+            end
+          end
+
+          class InvalidArgumentTypeError < StandardError
+            def message
+              "The provided argument is the wrong type"
+            end
+          end
+
+          def initialize dsl_method, *args, &block
+            @dsl_method = dsl_method
+            @arguments = {}
+
+            required_argument_count = dsl_method.required_arguments.count
+            has_optional_arguments = dsl_method.optional_arguments.any?
+
+            # the first N args, where N = required_argument_count, are the
+            # provided required arguments
+            required_args = args.slice(0, required_argument_count)
+            # the optional arg which comes next is the hash which represents
+            # all the optional arguments
+            optional_arg = args[required_argument_count]
+
+            # assert that a value is provided for every required argument
+            unless required_argument_count == required_args.count
+              raise MissingRequiredArgumentsError.new required_argument_count, required_args.count
+            end
+
+            # assert that too many arguments have not been provided
+            if args.count > required_argument_count + (has_optional_arguments ? 1 : 0)
+              raise TooManyArgumentsError
+            end
+
+            # asset that, if provided, then the optional argument (always the last one) is a Hash
+            if has_optional_arguments && optional_arg.nil? === false
+              unless optional_arg.is_a? Hash
+                raise OptionalArgsShouldBeHashError
+              end
+
+              # assert the each provided optional argument is valid
+              optional_arg.keys.each do |optional_argument_name|
+                optional_arg_value = optional_arg[optional_argument_name]
+                optional_argument = dsl_method.optional_argument optional_argument_name
+
+                case optional_argument.type
+                when :integer
+                  unless optional_arg_value.is_a? Integer
+                    raise InvalidArgumentTypeError
+                  end
+                  optional_argument.validate_integer! optional_arg_value
+
+                when :symbol
+                  unless optional_arg_value.is_a? Symbol
+                    raise InvalidArgumentTypeError
+                  end
+                  optional_argument.validate_symbol! optional_arg_value
+
+                when :string
+                  unless optional_arg_value.is_a? String
+                    raise InvalidArgumentTypeError
+                  end
+                  optional_argument.validate_string! optional_arg_value
+
+                when :boolean
+                  unless optional_arg_value.is_a?(TrueClass) || optional_arg_value.is_a?(FalseClass)
+                    raise InvalidArgumentTypeError
+                  end
+                  optional_argument.validate_boolean! optional_arg_value
+
+                else
+                  raise InvalidArgumentTypeError
+                end
+
+                # the provided value appears valid for this argument, save the value
+                @arguments[optional_argument_name] = optional_arg_value
+              end
+
+            end
+
+            # validate the value provided to each required argument
+            dsl_method.required_arguments.each_with_index do |required_argument, i|
+              arg = args[i]
+              case required_argument.type
+              when :integer
+                unless arg.is_a? Integer
+                  raise InvalidArgumentTypeError
+                end
+                required_argument.validate_integer! arg
+
+              when :symbol
+                unless arg.is_a? Symbol
+                  raise InvalidArgumentTypeError
+                end
+                required_argument.validate_symbol! arg
+
+              when :string
+                unless arg.is_a? String
+                  raise InvalidArgumentTypeError
+                end
+                required_argument.validate_string! arg
+
+              when :boolean
+                unless arg.is_a?(TrueClass) || arg.is_a?(FalseClass)
+                  raise InvalidArgumentTypeError
+                end
+                required_argument.validate_boolean! arg
+
+              else
+                raise InvalidArgumentTypeError
+              end
+
+              # the provided value appears valid for this argument, save the value
+              @arguments[required_argument.name] = arg
+            end
+          end
+
+          def method_name
+            @dsl_method.name
+          end
+
+          def to_h
+            {
+              arguments: @arguments
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class Interpreter
+    class Execution
+      class MethodCalls
+        attr_reader :method_calls
+
+        def initialize
+          @method_calls = []
+        end
+
+        def method_called? method_name
+          @method_calls.filter { |mc| mc.method_name == method_name }.any?
+        end
+
+        def add_method_call dsl_method, *args, &block
+          method_call = MethodCall.new(dsl_method, *args, &block)
+          @method_calls << method_call
+          method_call
+        end
+      end
+    end
+  end
+end