dsl_compose 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 535a5086604fa5366f7a9baf2cc1a1ef823d4f29f16d8fc273b78a680180c3e2
-  data.tar.gz: 12f9bfc80a59ad1cbf61ad03795fd6e29535618c41143dbb7d8afb1228c7f3ae
+  metadata.gz: 409bc8ce86ea967b4a22f675ea029b609a9bb925d8b35255dd4f0a010049f115
+  data.tar.gz: e8d99aa8be417b6c670978dc5cf4461be8ca65dc4316b27ee840b63d82128738
 SHA512:
-  metadata.gz: 768fbc012d89a3542f0c96934bfc9187098c790a4a7d975dff80ae63ba1e50c0eb19e8f8abddacf234410839fd1a5688eb76c30a51ed939485d219c67263c5f7
-  data.tar.gz: 3553a51fc949265b84866761ce8ee5ed2ae4de67d2db17da36b4d646a21a5feb34b91f0085a3fcdfa54c5707457aa3cc0adc9c63d3da5820e042e372d5224603
+  metadata.gz: a57708bdfb09d3d35cfa3b3e6a76ffa931bcf71c34c14ece5b8737079f6660fefc9596ab5d079cfbf7fed3f733896212b60f81f23a02504dccbcd89a110e01c1
+  data.tar.gz: d87d67e5e6a1f22d49d0b8bb0642f97755f004684d8c0fa7ca1850ba3ce64e46dc016f3ab5fb21edd068e221734d2bae52c09e92f59135f94b0fabd7ac7d3356

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.2.0](https://github.com/craigulliott/dsl_compose/compare/v2.1.1...v2.2.0) (2023-07-27)
+
+
+### Features
+
+* Added a ReaderBase which can be extended to create custom reader classes. Also added dsl_used?, dsl_used_on_ancestors? and dsl_used_on_class_or_ancestors? helper methods to the Reader class ([6507e4a](https://github.com/craigulliott/dsl_compose/commit/6507e4a082c9a0d7e63c580a17bcb8eb2bd940ea))
+
+## [2.1.1](https://github.com/craigulliott/dsl_compose/compare/v2.1.0...v2.1.1) (2023-07-26)
+
+
+### Bug Fixes
+
+* fixed bug where Execution classes were being returned from within the Reader but ExecutionReader classes were expected ([#56](https://github.com/craigulliott/dsl_compose/issues/56)) ([546cdaf](https://github.com/craigulliott/dsl_compose/commit/546cdaf323f3fc3be6ad09a47e5f99c3a59a50e2))
+
 ## [2.1.0](https://github.com/craigulliott/dsl_compose/compare/v2.0.1...v2.1.0) (2023-07-24)
 
 

data/README.md

@@ -168,7 +168,7 @@ You can use `import_shared` anywhere within your DSL definition, you can even us
 Child classes can then use your new DSL
 
 ```ruby
-class Bar << Foo
+class Bar < Foo
 
   your_dsl :first_dsl_argument, do
     your_method "first_method_argument", optional_argument: 123
@@ -239,7 +239,7 @@ A parser class can be used to process complicated DSLs. In the example below, a
 
 ```ruby
 # create your own parser by creating a new class which extends DSLCompose::Parser
-MyParser < DSLCompose::Parser
+class MyParser < DSLCompose::Parser
   # `for_children_of` will process SomeBaseClass and yield the provided
   # block once for every class which extends SomeBaseClass.
   #
@@ -312,7 +312,7 @@ 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.
+In addition to parser classes (or as a useful tool within parser classes) you can access the results of DSL execution with a Reader class.
 
 ```ruby
 # Create a new Reader object.
@@ -339,10 +339,6 @@ reader = DSLCompose::Reader.new MyClass, :my_dsl
 # 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
@@ -372,7 +368,9 @@ execution.my_dsl_method.each do |arguments|
 end
 
 # Returns an array of ExecutionReaders to represent each time the DSL was used
-# on ancestors of the provided class.
+# on the provided class.
+executions = reader.executions
+
 # 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
@@ -386,6 +384,106 @@ executions = reader.ancestor_executions
 # and if the DSL was used more than once on a class then the order they were used.
 executions = reader.all_executions
 
+# Returns true if dsl has been executed once or more on the provided class,
+# otherwise returns false.
+was_used = reader.dsl_used?
+
+# Returns true if dsl has been executed once or more on one of the ancestors
+# of the provided class, otherwise returns false.
+was_used = reader.dsl_used_on_ancestors?
+
+# Returns true if dsl has been executed once or more on the provided class or
+# any of its ancestors, otherwise returns false.
+was_used = reader.dsl_used_on_class_or_ancestors?
+
+# `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
+```
+
+A ReaderBase class is also provided. You can extend this class to create your own Reader objects and provide a much cleaner interface to your specific DSLs.
+
+```ruby
+# This is an example DSL for configuring which database and schema should be used
+# by classes which extend a BaseModel (it's from a hypothetical ORM).
+class BaseModel
+  # define a DSL which can be used on descendants of this class
+  # to determine which database should be used
+  define_dsl :database_configuration do
+    requires :server_type, :symbol do
+      validate_in [:postgres, :mysql]
+    end
+    requires :server_name, :symbol
+    optional :database_name, :symbol
+  end
+  # define a DSL to set the schema which should be used
+  define_dsl :schema do
+    requires :schema_name, :symbol
+  end
+end
+
+# A hypothetical model which extends BaseModel and uses this DSL
+class User < BaseModel
+  # Use the primary postgres server and the default database_name (because
+  # we are not using the optional `database_name: :foo` argument).
+  database_configuration :postgres, :primary
+  # Persist this models data in the `users` schema.
+  schema :users
+end
+
+# An example reader which could be created to provide a more concise
+# interface to this DSL.
+# Because this DSL Reader is named DatabaseConfigurationDSLReader it
+# will automatically refer to the dsl named :database_configuration.
+class DatabaseConfigurationDSLReader < DSLCompose::ReaderBase
+  # The three methods below provide a more concise access to the DSLs
+  # arguments. If the DSL was never used on the provided class, or any
+  # of it's ancestors, then an error will be raised. This error will
+  # be raised because we are using `last_execution!` instead of `last_execution`.
+  def server_type
+    last_execution!.arguments.server_type
+  end
+
+  def server_name
+    last_execution!.arguments.server_name
+  end
+
+  def database_name
+    last_execution!.arguments.database_name
+  end
+
+  # Returns true or false, depending on if the optional database_name
+  # attribute was used when executing the DSL. If the DSL was never
+  # used on the provided class, or any of it's ancestors, then an error will
+  # be raised (because of the bang method).
+  def has_database_name?
+    last_execution!.arguments.database_name != nil
+  end
+
+  # This method is provided as an example of how to reference other DSLs within
+  # your reader.
+  def schema_name
+    last_execution_of_schema&.arguments&.schema_name || :public
+  end
+
+  private
+
+  # This method is used by the schema_name method above, and is included as an
+  # example of how to reference other DSLs within your Reader.
+  def last_execution_of_schema
+    # Note that there is no bang method here (no "!" after last_execution), so it
+    # will return nil if the DSL was not used.
+    @schema_reader ||= DSLCompose::Reader.new(@base_class, :schema).last_execution
+  end
+end
+
+# Use our DatabaseConfigurationDSLReader when parsing this class to
+# enjoy a more concise API for accessing our DSL values
+reader = DatabaseConfigurationDSLReader.new(User)
+reader.server_type # :postgres
+reader.has_database_name? # false
+reader.schema_name # :users
+
 ```
 
 

data/lib/dsl_compose/reader/execution_reader.rb

@@ -15,6 +15,8 @@ module DSLCompose
       class MethodDoesNotExist < StandardError
       end
 
+      attr_reader :execution
+
       def initialize execution
         raise InvalidExecution unless execution.is_a? Interpreter::Execution
         @execution = execution

data/lib/dsl_compose/reader.rb

@@ -11,6 +11,9 @@ module DSLCompose
     class DSLNotFound < StandardError
     end
 
+    class NoDSLExecutionFound < 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
@@ -42,6 +45,24 @@ module DSLCompose
       end
     end
 
+    # Returns true if dsl has been executed once or more on the provided class,
+    # otherwise returns false.
+    def dsl_used?
+      executions.any?
+    end
+
+    # Returns true if dsl has been executed once or more on one of the ancestors
+    # of the provided class, otherwise returns false.
+    def dsl_used_on_ancestors?
+      ancestor_executions.any?
+    end
+
+    # Returns true if dsl has been executed once or more on the provided class or
+    # any of its ancestors, otherwise returns false.
+    def dsl_used_on_class_or_ancestors?
+      all_executions.any?
+    end
+
     # Returns an ExecutionReader class which exposes a simple API to access the
     # arguments, methods and method arguments provided when using this DSL.
     #
@@ -51,13 +72,24 @@ module DSLCompose
     # 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
+      ExecutionReader.new(@dsl_defining_class.dsls.get_last_dsl_execution(@klass, @dsl_name))
+    end
+
+    # A wrapper for last_execution which raises an error if no execution exists
+    def last_execution!
+      execution = @dsl_defining_class.dsls.get_last_dsl_execution(@klass, @dsl_name)
+      if execution.nil?
+        raise NoDSLExecutionFound, "No execution of the `#{@dsl_name}` dsl was found on `#{@klass}` or any of its ancestors"
+      end
+      ExecutionReader.new execution
     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
+      @dsl_defining_class.dsls.class_dsl_executions(@klass, @dsl_name, true, false).map do |execution|
+        ExecutionReader.new execution
+      end
     end
 
     # Returns an array of ExecutionReaders to represent each time the DSL was used
@@ -66,7 +98,9 @@ module DSLCompose
     # 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
+      @dsl_defining_class.dsls.class_dsl_executions(@klass, @dsl_name, false, true).map do |execution|
+        ExecutionReader.new execution
+      end
     end
 
     # Returns an array of ExecutionReaders to represent each time the DSL was used
@@ -74,7 +108,9 @@ module DSLCompose
     # 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
+      @dsl_defining_class.dsls.class_dsl_executions(@klass, @dsl_name, true, true).map do |execution|
+        ExecutionReader.new execution
+      end
     end
   end
 end

data/lib/dsl_compose/reader_base.rb

@@ -0,0 +1,64 @@
+module DSLCompose
+  # This class provides a skeleton for creating your own DSL readers.
+  #
+  # All classes which extend from this base class must follow a strict naming convention. The class name
+  # must be the camelcased form of the DSL name, followed by the string "DSLReader". For example, a reader
+  # for a DLS named `:foo_bar` must have the class name `FooBarDSLReader`, as seen below
+  #
+  # class FooBarDSLReader < DSLCompose::ReaderBase
+  #  # ...
+  # end
+  class ReaderBase
+    attr_reader :base_class
+    attr_reader :dsl_name
+    attr_reader :reader
+
+    def initialize base_class
+      @base_class = base_class
+      # get the DSL name from the class name
+      @dsl_name = dsl_name_from_class_name self.class
+      # create the reader
+      @reader = DSLCompose::Reader.new(base_class, @dsl_name)
+    end
+
+    private
+
+    def dsl_name_from_class_name reader_class
+      camelcased = reader_class.name.split("::").last.gsub(/DSLReader\Z/, "")
+      underscored = camelcased.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2')
+      underscored.downcase.to_sym
+    end
+
+    def dsl_used?
+      @reader.dsl_used?
+    end
+
+    def dsl_used_on_ancestors?
+      @reader.dsl_used_on_ancestors?
+    end
+
+    def dsl_used_on_class_or_ancestors?
+      @reader.dsl_used_on_class_or_ancestors?
+    end
+
+    def last_execution
+      @reader.last_execution
+    end
+
+    def last_execution!
+      @reader.last_execution!
+    end
+
+    def executions
+      @reader.executions
+    end
+
+    def ancestor_executions
+      @reader.ancestor_executions
+    end
+
+    def all_executions
+      @reader.all_executions
+    end
+  end
+end

data/lib/dsl_compose/version.rb

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

data/lib/dsl_compose.rb

@@ -32,6 +32,8 @@ require "dsl_compose/reader"
 require "dsl_compose/reader/execution_reader"
 require "dsl_compose/reader/execution_reader/arguments_reader"
 
+require "dsl_compose/reader_base"
+
 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.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Craig Ulliott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-24 00:00:00.000000000 Z
+date: 2023-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: class_spec_helper
@@ -77,6 +77,7 @@ files:
 - lib/dsl_compose/reader.rb
 - lib/dsl_compose/reader/execution_reader.rb
 - lib/dsl_compose/reader/execution_reader/arguments_reader.rb
+- lib/dsl_compose/reader_base.rb
 - lib/dsl_compose/shared_configuration.rb
 - lib/dsl_compose/version.rb
 homepage: