dsl_factory 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9110073c0a21c89089537a09c4f21394b30fffa76aeaec2291c9918d58051479
+  data.tar.gz: 06d23515ae9d3a03da213d7e6642ffe19cb7deba898e05526af11131070e644b
+SHA512:
+  metadata.gz: 37b94876fd1631ab2247da8688cf5d8ded60282bcd204bec006a3017d7e843015b926aceb4a9237a0c85dc9fdfaa4641a3256709e23950dae1f4fc5103f926f3
+  data.tar.gz: 2844d3bd1abd55906099d5a309276a8dfd180e10a7bfe6b48422c1a931f26cb79cdf8ac1b593e355e4851cfe809f6288463f183da8f029cf072b8aad0f7c1c16

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2022-03-01
+
+- Initial release

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+source "https://rubygems.org"
+gemspec
+gem "rake", "~> 13.0"
+gem "minitest", "~> 5.0"
+gem "pry"

data/Gemfile.lock

@@ -0,0 +1,38 @@
+PATH
+  remote: .
+  specs:
+    dsl_factory (0.1.0)
+      activesupport (>= 5.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (7.0.2.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.9)
+    i18n (1.10.0)
+      concurrent-ruby (~> 1.0)
+    method_source (1.0.0)
+    minitest (5.15.0)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    rake (13.0.6)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  dsl_factory!
+  minitest (~> 5.0)
+  pry
+  rake (~> 13.0)
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Tom Rothe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,264 @@
+# DSL Factory
+
+A small DSL to generate DSLs.  
+Define DSLs quickly and avoid the [boilerplate to write getters and setters](https://gist.github.com/motine/28da503ba0075e9d64d3f3b1faab9014). Oh, and it does validation too.
+
+## Example
+
+```ruby
+# add this to your Gemfile: gem 'dsl_factory'
+
+# define the DSL
+LakeDsl = DslFactory.define_dsl do
+  string :lake_name
+  numeric :max_depth
+  array :fishes, String
+end
+
+# use it in any class
+class LakeSuperior
+  extend LakeDsl
+
+  lake_name 'Lake Superior'
+  max_depth 406
+  fish 'trout'
+  fish 'northern pike'
+end
+
+# and you can access the values
+LakeSuperior.lake_name # => "Lake Superior"
+LakeSuperior.fishes # => ["trout", "northern pike"]
+```
+
+This gem came about during my time at [Netskin GmbH](https://www.netskin.com). Check it out, we do great (Rails) work there.
+
+# Usage
+
+## Definition
+
+**Basic Types**
+
+```ruby
+# the following data types are available
+# if a value is given which does not fit the type a `DslFactory::ValidationError` is raised
+LakeDsl = DslFactory.define_dsl do
+  string :lake_name
+  symbol :group
+  numeric :max_depth
+  boolean :protected_habitat
+  callable :current_temperature_handler
+  any :continent # does not validate the given contents later
+end
+
+# now we can use the definition
+class LakeSuperior
+  extend LakeDsl
+
+  lake_name 'Lake Superior'
+  group :great_lakes
+  max_depth 406
+  protected_habitat true
+  current_temperature_handler ->() { self.temperature = FetchService.receive_temperature } # the proc is only saved, DslFactory will not call it
+  continent Continent::NorthAmerica
+end
+```
+
+**Arrays**
+
+```ruby
+BookDsl = DslFactory.define_dsl do
+  array :authors            # we must use the plural!
+  array :publishers, String # validates that the item is of the given (Ruby) class
+  # see below for nested DSLs
+end
+
+class SuperBook
+  extend BookDsl
+  authors ['Manfred', 'Dieter'] # we can use the plural form to set the whole array
+  author 'Heinz'                # or the singular form to add an item
+
+  publisher 'abc'
+end
+
+SuperBook.authors # => ['Manfred', 'Dieter', 'Heinz']
+SuperBook.publishers # => ['abc']
+```
+
+**Hashes**
+
+```ruby
+GeographyDsl = DslFactory.define_dsl do
+  hash :capital_for_countries         # we must use the plural!
+  hash :country_sizes, String, Numeric # validate key and value (key must be of String class, value of Symbol) 
+  # see below for nested DSLs
+end
+
+class World
+  extend GeographyDsl
+  capital_for_country 'Berlin', 'Germany' # here we use the signular
+  capital_for_country 'Copenhagen', 'Denmark'
+
+  country_size 'Germany', 357_022
+end
+
+SmartyPants.capital_for_countries # => { 'Berlin' => 'Germany', 'Copenhagen' => 'Denmark'}
+SmartyPants.country_sizes # => { 'Germany' => 357022 }
+```
+
+**Nested DSLs**
+```ruby
+PersonDsl = DslFactory.define_dsl do
+  array :parents do
+    string :name
+    numeric :age
+  end
+
+  hash :citizenships, String do # validate key as String
+    symbol :status
+    any :expiry
+  end
+end
+
+class Sabine
+  extend PersonDsl
+  # note that nested DSLs can only be used via the singular form
+
+  parent do
+    name 'Karla'
+    age 88
+  end
+
+  citizenship 'Germany' do
+    status :revoked
+    expiry Time.new(2000)
+  end
+end
+
+Sabine.parents.first.name # => 'Karla'
+Sabine.citizenships['Germany'].status # => :revoked
+```
+
+**Callbacks**
+
+Sometimes we might want to do something when the DSL method is called.
+This can be achived via callbacks.
+
+```ruby
+ButtonDsl = DslFactory.define_dsl do
+  # all types outlined above support callbacks
+  any :trigger, callback: ->(value) { puts "#{value} was triggered" }
+  any :snicker, callback: ->(value) { arg1, arg2 = value; puts "snicker: #{arg1} & #{arg2}" } # we can pass arguments via the value
+  any :clicker, callback: ->(value) { self.do_the_click }
+
+  # for arrays the callback always receives an array (even if it was used in singular form)
+  # for hashes the callback receives two arguments: key, value
+end
+
+class Sabine
+  extend ButtonDsl
+  # if we want to call a method of the class, we need to define it before the first usage of the DSL method
+  def self.do_the_click
+    puts 'Click!'
+  end
+
+  trigger 'abc'            # -> abc was triggered
+  snicker ['haha', 'hihi'] # -> snicker: haha & hihi
+  clicker nil              # make sure to alway pass a value, -> Click!
+end
+```
+
+## Use of the definition
+
+Usually we **extend a class** like so:
+
+```ruby
+class LakeSuperior
+  extend LakeDsl
+  lake_name 'Lake Superior'
+end
+
+LakeSuperior.lake_name # => 'Lake Superior'
+```
+
+However we can also the **DSL in a variable**:
+
+```ruby
+@config = Module.new.extend(LakeDsl)
+@config.lake_name 'Müritz'
+@config.lake_name # => 'Müritz'
+
+# or with the configuration pattern
+@config = Module.new.extend(LakeDsl).tap do |c|
+  c.lake_name 'Summter See'
+end
+@config.lake_name # => 'Summter See'
+
+# or even without any prefix
+@config = Module.new.extend(LakeDsl)
+@config.instance_exec do
+  lake_name 'Mühlenbecker See'
+end
+@config.lake_name # => 'Mühlenbecker See'
+
+```
+
+# Development
+
+```bash
+docker run --rm -ti -v (pwd):/app -w /app ruby:2.7 bash
+bundle install
+rake test # run the tests
+pry # require_relative 'lib/dsl_factory.rb'
+
+# to release a new version, update the version number in `version.rb`, then run
+bundle exec rake release
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+# Alternatives
+
+_Download counts are from 01.03.2022._
+
+- [dslh](https://github.com/kumogata/dslh) (178.000 downloads)
+  Allows to define a Hash as a DSL.
+- [dsl_maker](https://rubygems.org/gems/dsl_maker) (80.700 downloads)
+    allows defining DSLs with structs.
+- [genki-dsl_accessor](https://rubygems.org/gems/genki-dsl_accessor) (5.600 downloads)
+    allows defining hybrid accessors for class.
+- [configuration_dsl](https://rubygems.org/gems/configuration_dsl) (4.100 downloads)
+    nice way to define configuration DSLs. quite outdated.
+- [blockenspiel](https://github.com/dazuma/blockenspiel) (2.869.000 downloads)
+    allows to nicely define configuration blocks. does not facilitate assigning variables.
+- [dsl_accessors](https://rubygems.org/gems/dsl_accessors) (3.700 downloads)
+    provides helpers to facilitate variable setting via DSL. exactly what we need, but unfortunately quite outdated.
+- [open_dsl](https://rubygems.org/gems/open_dsl) (17.000 downloads)
+    dynamically defines OpenStructs to collect data for DSLs. really nice idea and quite close to what we need. unfortunately a little outdated.
+- [alki-dsl](https://rubygems.org/gems/alki-dsl) (12.900 downloads)
+    allows to define DSL methods nicely. does not assist in variable getting/setting.
+
+**Honerable Mentions**
+
+- [cleanroom](https://rubygems.org/gems/cleanroom) (5.560.000 downloads)
+    allows to safely define DSLs. does not really facilitate the data assignments.
+- [dsl_block](https://rubygems.org/gems/dsl_block) 4.900 downloads)
+    allows you to use classes to define blocks with commands. does not really facilitate setting/getting variables.
+- [declarative](https://rubygems.org/gems/declarative) (110.990.000 downloads)
+    define declarative schemas.
+- [dslkit](https://rubygems.org/gems/dslkit) (54.500 downloads)
+    allows defining DSL to be read from files (maybe). documentation hard to find. outdated.
+- [dsltasks](https://rubygems.org/gems/dsltasks) (4.100 downloads)
+    allows to define hierarchical DSLs. does not facilitate variable assignments.
+- [opendsl](https://rubygems.org/gems/opendsl) (8.800 downloads)
+    allows to simply define DSLs. does not help assigning variables. outdated.
+
+**Not Applicable**
+
+- [dsl](https://rubygems.org/gems/dsl) defines delegators. i am not sure when this is useful.
+- [dsl_eval](https://rubygems.org/gems/dsl_eval) only defines an alias for instance_eval.
+- [instant_dsl](https://rubygems.org/gems/instant_dsl) could not find repo/docs. quite outdated.
+- [dsl_companion](https://rubygems.org/gems/dsl_companion) no documentation.
+- [def_dsl](https://rubygems.org/gems/def_dsl) no documentation.
+- [dslr](https://rubygems.org/gems/dslr) no documentation.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/dsl_factory.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "lib/dsl_factory/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "dsl_factory"
+  spec.version       = DslFactory::VERSION
+  spec.authors       = ["Tom Rothe"]
+  spec.email         = ["info@tomrothe.de"]
+
+  spec.summary       = "A small DSL to generate DSLs"
+  spec.description   = "Define DSLs quickly and avoid the boilerplate write getters and setters. Oh, and it does validation too."
+  spec.homepage      = "https://github.com/motine/dsl_factory"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = 'https://github.com/motine/dsl_factory/blob/master/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", ">= 5.0"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/dsl_factory/generator.rb

@@ -0,0 +1,120 @@
+class DslFactory::Generator
+  attr_reader :definition
+
+  def initialize
+    @definition = Module.new do
+      def get_dsl_value(name)
+        @dsl_values ||= {}
+        @dsl_values[name]
+      end
+
+      def set_dsl_value(name, value, &block)
+        @dsl_values ||= {}
+        @dsl_values[name] = value
+      end
+    end
+  end
+
+  # for more information & examples, please see README.md
+  #
+  # if a `callback` is given it will be called when the extended class uses this attribute (after setting the value).
+  # the callback block will be called with the value as first parameter (if you need multiple parameter pass a list).
+  # for examples, please see `README.md``.
+  #
+  # if a validation is given the block will be called with the value as first parameter.
+  # if the block returns false a `DslFactory::ValidationError` will be raised.
+  def any(name, callback: nil, validation: nil)
+    @definition.define_method(name) do |value = :not_given, &block|
+      return get_dsl_value(name) if value == :not_given
+      raise DslFactory::ValidationError, "#{name} is not valid" if validation && !validation.call(value)
+      set_dsl_value(name, value)
+      self.instance_exec(value, &callback) if callback
+    end
+  end
+
+  # for more information & examples, please see README.md
+  def string(name, **kwargs)
+    any(name, validation: ->(value) { value.is_a?(String) }, **kwargs)
+  end
+
+  # for more information & examples, please see README.md
+  def symbol(name, **kwargs)
+    any(name, validation: ->(value) { value.is_a?(Symbol) }, **kwargs)
+  end
+
+  # for more information & examples, please see README.md
+  def numeric(name, **kwargs)
+    any(name, validation: ->(value) { value.is_a?(Numeric) }, **kwargs)
+  end
+
+  # for more information & examples, please see README.md
+  def boolean(name, **kwargs)
+    any(name, validation: ->(value) { value.is_a?(TrueClass) || value.is_a?(FalseClass) }, **kwargs)
+  end
+
+  # for more information & examples, please see README.md
+  def callable(name, **kwargs)
+    any(name, validation: ->(value) { value.respond_to?(:call) }, **kwargs)
+  end
+
+  # for more information & examples, please see README.md
+  def array(plural_name, item_class=nil, callback: nil, &definition_block)
+    singular_name = build_singular_name!(plural_name)
+    raise DslFactory::DefinitionError, "#{plural_name} item_class can not given at the same time as a block" if item_class && definition_block
+
+    any(plural_name, callback: callback, validation: ->(value) { value.is_a?(Array) && (item_class.nil? || value.all? { |item| item.is_a?(item_class) }) })
+
+    @definition.define_method(singular_name) do |value = :not_given, &block|
+      old_value = get_dsl_value(plural_name)
+      return old_value if value == :not_given && !block
+
+      if block # we deal with a sub-DSL
+        value_object = Class.new
+        value_object.extend(DslFactory.define_dsl(&definition_block))
+        value_object.instance_eval(&block)
+        value = value_object
+      end
+      raise DslFactory::ValidationError, "#{singular_name} is not valid" if item_class && !value.is_a?(item_class)
+      new_value = old_value || []
+      new_value << value
+      set_dsl_value(plural_name, new_value)
+      self.instance_exec([value], &callback) if callback # wrap the item in a list
+    end
+  end
+
+  # for more information & examples, please see README.md
+  def hash(plural_name, key_class=nil, value_class=nil, callback: nil, &definition_block)
+    singular_name = build_singular_name!(plural_name)
+    raise DslFactory::DefinitionError, "#{plural_name} value_class can not given at the same time as a block" if value_class && definition_block
+
+    @definition.define_method(plural_name) do |value = nil|
+      raise DslFactory::DefinitionError, "hashes do not support setting values with the plural form, please use #{singular_name} to define items" if value
+      get_dsl_value(plural_name)
+    end
+
+    @definition.define_method(singular_name) do |key, value = nil, &block|
+      raise DslFactory::ValidationError, "value can not be given at the same time as a block for a hash" if value && block
+
+      if block # we deal with a sub-DSL
+        value_object = Class.new
+        value_object.extend(DslFactory.define_dsl(&definition_block))
+        value_object.instance_eval(&block)
+        value = value_object
+      end
+      raise DslFactory::ValidationError, "#{singular_name}'s key is not a #{key_class}" if key_class && !key.is_a?(key_class)
+      raise DslFactory::ValidationError, "#{singular_name}'s value is not a #{value_class}" if value_class && !value.is_a?(value_class)
+      new_value = get_dsl_value(plural_name) || {}
+      new_value[key] = value
+      set_dsl_value(plural_name, new_value)
+      self.instance_exec(key, value, &callback) if callback
+    end
+  end
+
+  protected
+
+  def build_singular_name!(plural_name)
+    singular_name = ActiveSupport::Inflector.singularize(plural_name).to_sym
+    raise DslFactory::DefinitionError, "can not singularize #{plural_name}, please make sure to provide the plural form and that ActiveSupport::Inflector can singularize" if singular_name == plural_name
+    singular_name
+  end
+end

data/lib/dsl_factory/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DslFactory
+  VERSION = "0.1.0"
+end

data/lib/dsl_factory.rb

@@ -0,0 +1,17 @@
+require_relative "dsl_factory/version"
+require_relative "dsl_factory/generator"
+
+require 'active_support/inflector'
+
+module DslFactory
+  class DefinitionError < StandardError; end
+  class ValidationError < StandardError; end
+
+  def define_dsl(&block)
+    generator = DslFactory::Generator.new
+    generator.instance_eval(&block)
+    return generator.definition
+  end
+
+  module_function :define_dsl
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: dsl_factory
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tom Rothe
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-03-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Define DSLs quickly and avoid the boilerplate write getters and setters.
+  Oh, and it does validation too.
+email:
+- info@tomrothe.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- dsl_factory.gemspec
+- lib/dsl_factory.rb
+- lib/dsl_factory/generator.rb
+- lib/dsl_factory/version.rb
+homepage: https://github.com/motine/dsl_factory
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/motine/dsl_factory
+  source_code_uri: https://github.com/motine/dsl_factory
+  changelog_uri: https://github.com/motine/dsl_factory/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: A small DSL to generate DSLs
+test_files: []