dsl_compose 2.1.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 826d148f5440924eeea1a56699ec7f6a421dcf5fe273012e7e9cf9010ab4cb66
-  data.tar.gz: 0fa06d0fcf99bea843da3b3b5cb66f196be88a923287ba4df64459e6289f7054
+  metadata.gz: 409bc8ce86ea967b4a22f675ea029b609a9bb925d8b35255dd4f0a010049f115
+  data.tar.gz: e8d99aa8be417b6c670978dc5cf4461be8ca65dc4316b27ee840b63d82128738
 SHA512:
-  metadata.gz: c4bcce09e0c5b3028c97ac09dbd16a6481ed8514857e7bcaecbbe7b40aebec22b8d7b4220f299380363dd9b87de9c0585fa456d8c70c031e967d3e6048711b60
-  data.tar.gz: 20eb3288cafb32aafddc8efe78e2e8fba5cf088c1896b5a9e82eb42e21c63c84d6e2536888d5e938f9f4b9bc80d064bfb5e95ca2fdb410316707f0362e0bf6cf
+  metadata.gz: a57708bdfb09d3d35cfa3b3e6a76ffa931bcf71c34c14ece5b8737079f6660fefc9596ab5d079cfbf7fed3f733896212b60f81f23a02504dccbcd89a110e01c1
+  data.tar.gz: d87d67e5e6a1f22d49d0b8bb0642f97755f004684d8c0fa7ca1850ba3ce64e46dc016f3ab5fb21edd068e221734d2bae52c09e92f59135f94b0fabd7ac7d3356

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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)
 
 

data/README.md

@@ -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.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.
     #
@@ -54,6 +75,15 @@ module DSLCompose
       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

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.1"
+  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.1
+  version: 2.2.0
 platform: ruby
 authors:
 - Craig Ulliott
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-26 00:00:00.000000000 Z
+date: 2023-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: class_spec_helper
@@ -77,15 +77,16 @@ 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:
+homepage: 
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/craigulliott/dsl_compose/
   changelog_uri: https://github.com/craigulliott/dsl_compose/blob/main/CHANGELOG.md
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -101,7 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.3.26
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Ruby gem to add dynamic DSLs to classes
 test_files: []