dsl_compose 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca7d4076508adb7aa4c534ffe69f276d4da8c50abcb65dbc898a2a40a241b2be
-  data.tar.gz: f0efae218b8a5ed32212077de0b42d3a345e5578c29ebf0dc4e00356ae0d00cf
+  metadata.gz: 535a5086604fa5366f7a9baf2cc1a1ef823d4f29f16d8fc273b78a680180c3e2
+  data.tar.gz: 12f9bfc80a59ad1cbf61ad03795fd6e29535618c41143dbb7d8afb1228c7f3ae
 SHA512:
-  metadata.gz: 1f1302ffba75b9614fbecf1c3d84159360dcbc67f760e7474fed1e9ba321abeb7200c424ba0b9c6d7a6eb26891649012474037a896387eeec058fc3e58cba651
-  data.tar.gz: b20711b1f065090f9507e32029640d3766f8fd4ceb0a5d1d9372c3ddbdb03eef311982531284d0b213b4a559d614929f3531747b659db88d5eda8ebffd22cc6c
+  metadata.gz: 768fbc012d89a3542f0c96934bfc9187098c790a4a7d975dff80ae63ba1e50c0eb19e8f8abddacf234410839fd1a5688eb76c30a51ed939485d219c67263c5f7
+  data.tar.gz: 3553a51fc949265b84866761ce8ee5ed2ae4de67d2db17da36b4d646a21a5feb34b91f0085a3fcdfa54c5707457aa3cc0adc9c63d3da5820e042e372d5224603

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [2.1.0](https://github.com/craigulliott/dsl_compose/compare/v2.0.1...v2.1.0) (2023-07-24)
+
+
+### Features
+
+* created a Reader class which can be used to access the resulting configuration from executing DSLs ([#53](https://github.com/craigulliott/dsl_compose/issues/53)) ([6e18eb7](https://github.com/craigulliott/dsl_compose/commit/6e18eb736611193b4fad8dac380cdd760095760f))
+
 ## [2.0.1](https://github.com/craigulliott/dsl_compose/compare/v2.0.0...v2.0.1) (2023-07-19)
 
 

data/README.md

@@ -312,6 +312,82 @@ MyParser < DSLCompose::Parser
 end
 ```
 
+In addition to parser classes (or as a useful tool within parser classes) you can access the results of DSL execution via the class (or via a descendent of the class) where the DSL was originally defined.
+
+```ruby
+# Create a new Reader object.
+#
+# Reader objects build and return ExecutionReader classes which expose a
+# simple API to access the arguments, methods and method arguments which
+# were provided when using a DSL.
+#
+# In the example below, MyClass is a class, or descendent of a class which
+# had a DSL defined on it with the name :my_dsl.
+#
+# An error will be raised if a DSL with the provided name was never defined
+# on MyClass or any of its ancestors.
+reader = DSLCompose::Reader.new MyClass, :my_dsl
+
+# `reader.last_execution` will return an ExecutionReader which represents
+# the last time the DSL was used.
+#
+# If the dsl has been executed once or more on the provided class, then
+# the last (most recent) execution will be returned. If the DSL was not
+# executed on the provided class, then we traverse up the classes ancestors
+# and look for the last (most recent) time it was executed on each ancestor.
+#
+# If no execution of the DSL is found, then nil will be returned
+execution = reader.last_execution
+
+# `execution.arguments` returns an ArgumentsReader object which allows access
+# via dot notation to to any argument values provided to the DSL
+execution.arguments.my_dsl_argument # returns the value provided for the argument, or nil
+
+# `execution.method_called?` will return true if the method with the provided
+# name was called, if a method with this name does exist, but was not called
+# then false will be returned. If a method with this name does not exist, then
+# an error will be raised.
+execution.method_called? :my_dsl_method # returns true/false
+
+# You can directly access the argument values for methods by calling the
+# ExecutionReader object with the same method name as the defined method on
+# your DSL.
+#
+# If your method was defined as unique via `add_unique_method` then this will
+# return a single ArgumentsReader which represents the arguments provided to
+# your method.
+#
+# Note that `execution.my_dsl_method` will return nil if the method was
+# not used in this DSL execution, so you should either check this first
+# with `method_called?` or use ruby's safe navigation operator (`.&`). If
+# you want to enforce use of this method, then it should be marked as
+# required when your DSL was originally defined.
+execution.my_dsl_method.my_dsl_method_argument
+
+# If your method was not defined as unique, then this will return an array
+# representing each time the method was used. If the method was never used
+# then an empty array will be returned
+execution.my_dsl_method.each do |arguments|
+  arguments.my_dsl_method_argument # returns the value provided for the argument, or nil
+end
+
+# Returns an array of ExecutionReaders to represent each time the DSL was used
+# on ancestors of the provided class.
+# Returns an array of ExecutionReaders to represent each time the DSL was used
+# on the ancestors of the provided class, but not on the provided class itself.
+# The executions will be returned in the order they were executed, which is the
+# earliest ancestor first and if the DSL was used more than once on a class then
+# the order they were used.
+executions = reader.ancestor_executions
+
+# Returns an array of ExecutionReaders to represent each time the DSL was used
+# on the provided class or ancestors of the provided class. The executions will
+# be returned in the order they were executed, which is the earliest ancestor first
+# and if the DSL was used more than once on a class then the order they were used.
+executions = reader.all_executions
+
+```
+
 
 ## Argument validations
 

data/lib/dsl_compose/dsl/arguments.rb

@@ -22,6 +22,11 @@ module DSLCompose
         @arguments = {}
       end
 
+      # returns true if there are any arguments, otherwise returns false
+      def any?
+        @arguments.values.any?
+      end
+
       # Returns an array of all this DSLMethods Argument objects.
       def arguments
         @arguments.values

data/lib/dsl_compose/dsl.rb

@@ -107,6 +107,21 @@ module DSLCompose
       @dsl_methods.values
     end
 
+    # does this DSL have any methods
+    def has_methods?
+      dsl_methods.any?
+    end
+
+    # does this DSL have any required methods
+    def has_required_methods?
+      required_dsl_methods.any?
+    end
+
+    # does this DSL have any optional methods
+    def has_optional_methods?
+      optional_dsl_methods.any?
+    end
+
     # Returns an array of only the required DSLMethods in this DSL.
     def required_dsl_methods
       dsl_methods.filter(&:required?)

data/lib/dsl_compose/dsls.rb

@@ -32,8 +32,8 @@ module DSLCompose
       @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
+    # if a DSL witg the provided name exists for the provided class, then return true
+    # else return false
     def self.class_dsl_exists? klass, name
       @dsls.key?(klass) && @dsls[klass].key?(name)
     end

data/lib/dsl_compose/fix_heredoc_indentation.rb

@@ -2,9 +2,10 @@ module DSLCompose
   # A small helper to fix indentation and clean up whitespace in
   # strings which were created with rubys heredoc syntax.
   module FixHeredocIndentation
-    # This method is used to fix the indentation of heredoc strings.
-    # It will remove the leading whitespace from each line of the string
-    # and remove the leading newline from the string.
+    # This method is used to trim empty lines from the start and end of
+    # a block of markdown, it will also fix the indentation of heredoc
+    # strings by removing the leading whitespace from the first line, and
+    # that same amount of white space from every other line
     def self.fix_heredoc_indentation string
       # replace all tabs with spaces
       string = string.gsub(/\t/, "  ")
@@ -14,10 +15,7 @@ module DSLCompose
       string = string.gsub(/( *\n)+\Z/, "")
       # removes the number of leading spaces on the first line, from
       # all the other lines
-      string = string.gsub(/^#{string[/\A */]}/, "")
-      # collapse lines which are next to each other onto the same line
-      # because they are really the same paragraph
-      string.gsub(/([^ \n])\n([^ \n])/, '\1 \2')
+      string.gsub(/^#{string[/\A */]}/, "")
     end
   end
 end

data/lib/dsl_compose/interpreter.rb

@@ -4,6 +4,9 @@ module DSLCompose
   # The class is reponsible for parsing and executing a dynamic DSL (dynamic DSLs are
   # created using the DSLCompose::DSL class).
   class Interpreter
+    class DSLExecutionNotFoundError < StandardError
+    end
+
     # A dynamic DSL can be used multiple times on the same class, each time the DSL is used
     # a corresponding execution will be created. The execution contains the resulting configuration
     # from that particular use of the DSL.
@@ -61,6 +64,22 @@ module DSLCompose
       @executions.filter { |e| e.dsl.name == dsl_name && ((on_current_class && e.klass == klass) || (on_ancestor_class && klass < e.klass)) }
     end
 
+    # returns the most recent, closest single execution of a dsl with the
+    # provided name for the provided class
+    #
+    # If the dsl has been executed once or more on the provided class, then
+    # the last (most recent) execution will be returned. If the DSL was not
+    # executed on the provided class, then we traverse up the classes ancestors
+    # until we reach the ancestor where the DSL was originally defined and test
+    # each of them and return the first most recent execution of the DSL.
+    # If no execution of the DSL is found, then nil will be returned
+    def get_last_dsl_execution klass, dsl_name
+      # note that this method does not need to do any special sorting, the required
+      # order for getting the most recent execution is already guaranteed because
+      # parent classes in ruby always have to be evaluated before their descendents
+      class_dsl_executions(klass, dsl_name, true, true).last
+    end
+
     # removes all executions from the interpreter, and any parser_usage_notes
     # this is primarily used from within a test suite when dynamically creating
     # classes for tests and then wanting to clear the interpreter before the

data/lib/dsl_compose/reader/execution_reader/arguments_reader.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class Reader
+    class ExecutionReader
+      # This class is part of a decorator for DSL executions.
+      class ArgumentsReader
+        # When instantiated, this class dynamically provides methods which corespiond to argument
+        # names and returns the argument value.
+        #
+        # `arguments` should be the DSL Arguments object, as this represents the possible arguments
+        # `argument_values` is a key/value object representing the actual values which were provided
+        # when the DSL was executed
+        #
+        # This class is used to represent both DSL arguments, and dsl_method arguments
+        def initialize arguments, argument_values
+          @arguments = arguments
+          @argument_values = argument_values
+        end
+
+        # catch and process any method calls, if arguments exist with the same name
+        # as the method call, then return the appropriate value, otherwise raise an error
+        def method_missing method_name
+          # fetch the argument to ensure it exists (this will raise an error if it does not)
+          argument = @arguments.argument method_name
+          # return the argument value, or nil if the argument was not used
+          @argument_values.arguments[argument.name]
+        end
+
+        def respond_to_missing? method_name
+          @arguments.has_argument? method_name
+        end
+      end
+    end
+  end
+end

data/lib/dsl_compose/reader/execution_reader.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  class Reader
+    # This class is a decorator for DSL executions.
+    #
+    # When a dynamically defined DSL is executed on a class, it creates an execution
+    # object which represents the argument values, and any methods and subsequent
+    # method argument values which were provided. This class provides a clean and simple
+    # API to access those vaues
+    class ExecutionReader
+      class InvalidExecution < StandardError
+      end
+
+      class MethodDoesNotExist < StandardError
+      end
+
+      def initialize execution
+        raise InvalidExecution unless execution.is_a? Interpreter::Execution
+        @execution = execution
+      end
+
+      # returns an object which represents the arguments available for this DSL and allows
+      # accessing their values via methods
+      def arguments
+        ArgumentsReader.new @execution.dsl.arguments, @execution.arguments
+      end
+
+      # was a method with the provided name called during the use of this DSL
+      def method_called? method_name
+        unless @execution.dsl.has_dsl_method? method_name
+          raise MethodDoesNotExist, "The method `#{method_name}` does not exist for DSL `#{@execution.dsl.name}`"
+        end
+        @execution.method_calls.method_called? method_name
+      end
+
+      # Catch and process any method calls, if a DSL method with the same name exists
+      # then return a representation of the arguments which were provided to the execution
+      # of that method within the DSL.
+      #
+      # If the method is marked as unique, then an arguments object will be returned, if the
+      # method is not unique, then an array of arguments objects will be returned (one for each
+      # time the method was used within this DSL execution).
+      def method_missing method_name
+        # Fetch the method from the DSL (this will raise an error if a method with this name
+        # was not defined for this exections DSL).
+        dsl_method = @execution.dsl.dsl_method method_name
+
+        # the Arguments object which represents the possible arguments which can be
+        # used with this method
+        arguments = dsl_method.arguments
+
+        # Fetch the array of method calls, this represents each use of a DSL method within
+        # a single use of the DSL
+        method_calls = @execution.method_calls.method_calls_by_name(method_name)
+
+        # If the use of this DSL method is only allowed once per DSL execution, then return
+        # an ArgumentsReader object which represents the argument values provided when the
+        # method was used.
+        #
+        # If the method was never used, then nil will be returned. We don't have to validate
+        # if the method use is required or not here, because that validation already happened
+        # when the DSL was used.
+        if dsl_method.unique?
+          method_call = method_calls.first
+          unless method_call.nil?
+            ArgumentsReader.new arguments, method_call.arguments
+          end
+
+        # If the method call is not unique, then return an array representing the argument
+        # values provided for each use of the DSL method
+        else
+          method_calls.map do |method_call|
+            ArgumentsReader.new arguments, method_call.arguments
+          end
+        end
+      end
+
+      def respond_to_missing? method_name
+        method_called? method_name
+      end
+    end
+  end
+end

data/lib/dsl_compose/reader.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module DSLCompose
+  # This class is a decorator for DSL executions.
+  #
+  # When a dynamically defined DSL is executed on a class, it creates an execution
+  # object which represents the argument values, and any methods and subsequent
+  # method argument values which were provided. This class provides a clean and simple
+  # API to access those vaues
+  class Reader
+    class DSLNotFound < StandardError
+    end
+
+    # given a class and the DSL name, finds and creates a reference to the DSL
+    # and the ancestor class where the DSL was originally defined
+    def initialize klass, dsl_name
+      # a reference to the class and dsl_name which we want to read values for
+      @klass = klass
+      @dsl_name = dsl_name
+
+      # Move up through this classes ancestors until we find the class which defined
+      # the DSL with the provided name. When we reach the top of the ancestor chain we
+      # exit the loop.
+      while klass
+        # if we find a DSL with this name, then store a reference to the DSL and the
+        # ancestor class where it was defined
+        if DSLs.class_dsl_exists?(klass, dsl_name)
+          @dsl = DSLs.class_dsl(klass, dsl_name)
+          @dsl_defining_class = klass
+          # stop once we find the DSL
+          break
+        end
+
+        # the DSL was not found here, so traverse up the provided classes hierachy
+        # and keep looking for where this DSL was initially defined
+        klass = klass.superclass
+      end
+
+      # if no DSL was found, then raise an error
+      if @dsl.nil? && @dsl_defining_class.nil?
+        raise DSLNotFound, "No DSL named `#{dsl_name}` was found for class `#{klass}`"
+      end
+    end
+
+    # Returns an ExecutionReader class which exposes a simple API to access the
+    # arguments, methods and method arguments provided when using this DSL.
+    #
+    # If the dsl has been executed once or more on the provided class, then
+    # the last (most recent) execution will be returned. If the DSL was not
+    # executed on the provided class, then we traverse up the classes ancestors
+    # and look for the last time it was executed on each ancestor.
+    # If no execution of the DSL is found, then nil will be returned
+    def last_execution
+      @dsl_defining_class.dsls.get_last_dsl_execution @klass, @dsl_name
+    end
+
+    # Returns an array of ExecutionReaders to represent each time the DSL was used
+    # on the provided class.
+    def executions
+      @dsl_defining_class.dsls.class_dsl_executions @klass, @dsl_name, true, false
+    end
+
+    # Returns an array of ExecutionReaders to represent each time the DSL was used
+    # on the ancestors of the provided class, but not on the provided class itself.
+    # The executions will be returned in the order they were executed, which is the
+    # earliest ancestor first and if the DSL was used more than once on a class then
+    # the order they were used.
+    def ancestor_executions
+      @dsl_defining_class.dsls.class_dsl_executions @klass, @dsl_name, false, true
+    end
+
+    # Returns an array of ExecutionReaders to represent each time the DSL was used
+    # on the provided class or ancestors of the provided class. The executions will
+    # be returned in the order they were executed, which is the earliest ancestor first
+    # and if the DSL was used more than once on a class then the order they were used.
+    def all_executions
+      @dsl_defining_class.dsls.class_dsl_executions @klass, @dsl_name, true, true
+    end
+  end
+end

data/lib/dsl_compose/version.rb

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

data/lib/dsl_compose.rb

@@ -28,6 +28,10 @@ require "dsl_compose/dsl/interpreter"
 
 require "dsl_compose/dsl"
 
+require "dsl_compose/reader"
+require "dsl_compose/reader/execution_reader"
+require "dsl_compose/reader/execution_reader/arguments_reader"
+
 require "dsl_compose/interpreter/execution/method_calls/method_call"
 require "dsl_compose/interpreter/execution/method_calls"
 require "dsl_compose/interpreter/execution/arguments"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dsl_compose
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Craig Ulliott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-19 00:00:00.000000000 Z
+date: 2023-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: class_spec_helper
@@ -74,6 +74,9 @@ files:
 - lib/dsl_compose/parser/for_children_of_parser/descendents.rb
 - lib/dsl_compose/parser/for_children_of_parser/for_dsl_parser.rb
 - lib/dsl_compose/parser/for_children_of_parser/for_dsl_parser/for_method_parser.rb
+- lib/dsl_compose/reader.rb
+- lib/dsl_compose/reader/execution_reader.rb
+- lib/dsl_compose/reader/execution_reader/arguments_reader.rb
 - lib/dsl_compose/shared_configuration.rb
 - lib/dsl_compose/version.rb
 homepage: