dialekt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 292d8eb12e8d5c07a6d08fcfc9b52f35bee2bba6f654f5651a6cdad705ad95a6
+  data.tar.gz: ba4af05bf33624ee2c466900224f79e8afebe5cddb9f0e5511796211be042ef6
+SHA512:
+  metadata.gz: 527a36bf572db17d099d155833870ecaa605dba432144328fbd43fc9347163e40a77b88615df437c5cb3da468f7d968c0c0dcf6c7fcb46d1472818ca460edaeb
+  data.tar.gz: cda9eae770da3b8497c2a4e7d569c18c1e857b8beb1d963c5094750a24b8ead69e6d2feb29d4925791480127dc2e250b8e3e7f326d7f3f2c8b4dabb14ccaef0d

data/README.md

@@ -0,0 +1,88 @@
+# What is it?
+
+With Dialekt you can easily define properties for DSL objects that support nice accessor methods, type checking and transformation.
+
+Dialekt is based on [Docile], which is a great tool to create DSLs in Ruby. However, you will soon find yourself creating lots of repetetive code to implement your DSL accessors. Dialekt aims to simplify this task.
+
+[Docile]: https://github.com/ms-ati/docile
+
+## Example
+
+Let's assume you want to create a build tool called Backscratcher (sort of a [small rake][Backscratcher] to scratch an itch :-) that uses a DSL for configuration. Your tool supports tasks and dependencies between tasks, and tasks can be grouped into namespaces. You start by creating a model and using Dialekt to define the properties.
+
+[Backscratcher]: https://en.wikipedia.org/wiki/Backscratcher
+
+```ruby
+    require "dialekt"
+    require "forwardable"
+
+    module Backscratcher
+      extend Forwardable
+
+      class Task
+        attr_reader :name
+
+        # Create a set property containing strings
+        dsl_set :dependencies, value_type: String
+
+        def initialize(name:)
+          @name = name
+        end
+      end
+
+      class FileTask < Task
+      end
+
+      class Namespace
+        attr_reader :name
+
+        # Create a tasks hash with string keys
+        dsl_map :tasks, key_type: String, value_type: Task do
+          # Create an accessor for task entries
+          entry :task, value_factory: ->(key:) { Task.new(name: key) }
+          # Create an accessor for file task entries
+          entry :file, value_type: FileTask, value_factory: ->(key:) { FileTask.new(name: key) }
+        end
+
+        # Create a namespace hash with string keys
+        dsl_map :namespaces, key_type: String, value_type: Namespace do
+          # Create an accessor for namespace entries
+          entry :namespace, value_factory: ->(key:) { Namespace.new(name: key) }
+        end
+
+        def initialize(name:)
+          @name = name
+          @namespaces = {}
+          @tasks = {}
+        end
+      end
+
+      # Make some methods available in the root namespace for convenience
+      def_delegators :root, :namespace, :task, :file
+
+      def root
+        @root ||= Namespace.new(name: "")
+      end
+    end
+
+    include Backscratcher
+```
+
+You now have a DSL for your build tool giving you methods to create namespaces, tasks and dependencies. Dialekt will handle the definition of accessores, type checking, creating new collection entries and applying DSL configurations:
+
+```ruby
+    task "build" do
+      dependency "db:create"
+      dependency "db:load"
+    end
+
+    file "test.txt"
+
+    namespace "db" do
+      task "create"
+
+      task "load" do
+        dependencies ["db:create"]
+      end
+    end
+```

data/dialekt.gemspec

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+LIB_DIR = File.join(__dir__, "lib")
+$LOAD_PATH.unshift(LIB_DIR) unless $LOAD_PATH.include?(LIB_DIR)
+
+require "dialekt/version"
+require "json"
+require "pathname"
+
+Gem::Specification.new do |spec|
+  raise "RubyGems 2.0 or newer is required." unless spec.respond_to?(:metadata)
+
+  spec.name = "dialekt"
+  spec.version = Dialekt::VERSION
+  spec.summary = "DSL utilities"
+
+  spec.required_ruby_version = ">= 2.6"
+
+  spec.authors = ["Jochen Seeber"]
+  spec.email = ["jochen@seeber.me"]
+  spec.homepage = "https://github.com/jochenseeber/dialekt"
+
+  spec.metadata["issue_tracker"] = "https://github.com/jochenseeber/dialekt/issues"
+  spec.metadata["documentation"] = "http://jochenseeber.github.com/dialekt"
+  spec.metadata["source_code"] = "https://github.com/jochenseeber/dialekt"
+  spec.metadata["wiki"] = "https://github.com/jochenseeber/dialekt/wiki"
+
+  spec.files = Dir[
+    "*.gemspec",
+    "*.md",
+    "*.txt",
+    "lib/**/*.rb",
+  ]
+
+  spec.require_paths = [
+    "lib",
+  ]
+
+  spec.bindir = "cmd"
+  spec.executables = spec.files.filter { |f| File.dirname(f) == "cmd" && File.file?(f) }.map { |f| File.basename(f) }
+
+  spec.add_dependency "docile", "~> 1.3.5"
+  spec.add_dependency "dry-inflector", "~> 0.2"
+  spec.add_dependency "zeitwerk", "~> 2.3"
+
+  spec.add_development_dependency "bundler", "~> 2.1"
+  spec.add_development_dependency "calificador", "~> 0.2.0"
+  spec.add_development_dependency "debase", "~> 0.2"
+  spec.add_development_dependency "minitest", "~> 5.14"
+  spec.add_development_dependency "qed", "~> 2.9"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.6"
+  spec.add_development_dependency "rubocop-minitest", "~> 0.10"
+  spec.add_development_dependency "rubocop-rake", "~> 0.5"
+  spec.add_development_dependency "ruby-debug-ide", "~> 0.7"
+  spec.add_development_dependency "simplecov", "~> 0.18"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

data/lib/dialekt.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+# Main module
+module Dialekt
+  class Empty
+    include Singleton
+
+    def to_s
+      "<empty>"
+    end
+
+    alias_method :inspect, :to_s
+  end
+
+  EMPTY = Empty.instance
+end
+
+require "dialekt/dsl"
+require "dialekt/util/core_extensions"

data/lib/dialekt/basic_type_checker.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "pp"
+require "stringio"
+
+module Dialekt
+  # Type checker
+  class BasicTypeChecker
+    def valid?(type:, value:)
+      raise NotImplementedError
+    end
+
+    def union_type(types:)
+      raise NotImplementedError
+    end
+
+    def check!(type:, value:)
+      raise TypeError, "Object must be of type(s) #{type}" unless valid?(type: type, value: value)
+
+      true
+    end
+
+    def format(type:)
+      PP.singleline_pp(type, StringIO.new).string
+    end
+  end
+end

data/lib/dialekt/dsl.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Dialekt
+  # DSL extensions
+  module Dsl
+    # DSL mixins for Class
+    module ClassMixins
+      def dsl_scalar(name, **options, &block)
+        property = Model::ScalarProperty.new(name: name, **options)
+        Docile.dsl_eval(property, &block) if block
+        property.setup(owner: self)
+        property
+      end
+
+      def dsl_map(name, **options, &block)
+        property = Model::MapProperty.new(name: name, **options)
+        Docile.dsl_eval(property, &block) if block
+        property.setup(owner: self)
+        property
+      end
+
+      def dsl_set(name, **options, &block)
+        property = Model::SetProperty.new(name: name, **options)
+        Docile.dsl_eval(property, &block) if block
+        property.setup(owner: self)
+        property
+      end
+    end
+
+    Class.include(ClassMixins)
+  end
+end

data/lib/dialekt/model/basic_property.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Dialekt
+  module Model
+    # BaseAccessor base class
+    class BasicProperty
+      # Property configuration
+      class Shape
+        attr_reader :name, :type, :factory, :transformer
+
+        def initialize(name:, type:, factory: nil, transformer: nil)
+          @name = name.to_sym
+          @type = type
+          @factory = factory&.call_adapter
+          @transformer = transformer&.call_adapter
+        end
+      end
+
+      attr_reader :name
+      attr_writer :type
+
+      def initialize(name:, type: nil, factory: nil, transformer: nil)
+        raise ArgumentError, "Name must not be nil" if name.nil?
+
+        @name = name
+        @type = type
+
+        @variable = :"@#{name}"
+        @factory = factory&.call_adapter
+        @transformer = transformer&.call_adapter
+      end
+
+      def setup(owner:); end
+
+      def access_value(shape:, target:, value: EMPTY)
+        if value.equal?(EMPTY)
+          get_value(shape: shape, target: target)
+        else
+          set_value(shape: shape, target: target, value: value)
+        end
+      end
+
+      def get_value(shape:, target:)
+        if target.instance_variable_defined?(@variable)
+          target.instance_variable_get(@variable)
+        else
+          value = shape.factory&.call(object: target)
+          target.instance_variable_set(@variable, value)
+        end
+      end
+
+      def set_value(shape:, target:, value:)
+        if shape.transformer
+          begin
+            value = shape.transformer.call(object: target, value: value)
+          rescue StandardError
+            raise TypeError, "Cannot transform value '#{value}' for property #{@name}"
+          end
+        end
+
+        type_checker = target.class.dialekt_type_checker
+
+        begin
+          type_checker.check!(type: shape.type, value: value)
+        rescue StandardError
+          raise TypeError, <<~MSG
+            Value '#{value}' (#{value.class}) for property #{@name} must conform to #{type_checker.format(type: shape.type)}
+          MSG
+        end
+
+        target.instance_variable_set(@variable, value)
+      end
+
+      def type(type = EMPTY)
+        type == EMPTY ? @type : (@type = type)
+      end
+
+      def factory(factory = EMPTY, &block)
+        if factory == EMPTY
+          if block
+            self.factory = block
+          else
+            @factory
+          end
+        else
+          raise ArgumentError, "Please provide either a factory proc or a block, not both" if block
+
+          self.factory = factory
+        end
+      end
+
+      def factory=(factory)
+        @factory = factory&.call_adapter
+      end
+
+      def transformer(transformer = EMPTY, &block)
+        if transformer == EMPTY
+          if block
+            self.transformer = block
+          else
+            @transformer
+          end
+        else
+          raise ArgumentError, "Please provide either a transformer proc or a block, not both" if block
+
+          self.transformer = transformer
+        end
+      end
+
+      def transformer=(transformer)
+        @transformer = transformer&.call_adapter
+      end
+    end
+  end
+end

data/lib/dialekt/model/map_property.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "docile"
+require "stringio"
+
+module Dialekt
+  module Model
+    # Base class for DSL map accessors
+    class MapProperty < BasicProperty
+      # Entry configuration
+      class Entry
+        attr_reader :name, :key_type, :key_transformer, :value_type, :value_factory, :value_transformer
+
+        def initialize(name:, key_type:, value_type:, key_transformer: nil, value_factory: nil, value_transformer: nil)
+          @name = name.to_sym
+          @key_type = key_type
+          @key_transformer = key_transformer&.call_adapter
+          @value_type = value_type
+          @value_factory = value_factory&.call_adapter
+          @value_transformer = value_transformer&.call_adapter
+        end
+
+        def to_s
+          result = StringIO.new
+          result << @name << " (" << self.class.base_name << ") {"
+          result << "key_type: " << @key_type.to_s
+          result << ", key_transformer: " << @key_transformer.source_info if @key_transformer
+          result << ", value_type: " << @value_type.to_s
+          result << ", value_factory: " << @value_factory.source_info if @value_factory
+          result << ", value_transformer: " << @value_transformer.source_info if @value_transformer
+          result << "}"
+
+          result.string
+        end
+      end
+
+      def initialize(
+        name:,
+        key_type: nil,
+        value_type: nil,
+        type: Hash,
+        factory: -> { {} },
+        transformer: ->(value:) { value&.to_h }
+      )
+        super(
+          name: name,
+          type: type,
+          factory: factory,
+          transformer: transformer
+        )
+
+        @key_type = key_type
+        @key_transformer = nil
+
+        @value_type = value_type
+        @value_transformer = nil
+        @value_factory = nil
+
+        @entries = {}
+      end
+
+      def entries
+        @entries.dup.freeze
+      end
+
+      def entries=(entries)
+        case entries
+        when Hash
+          @entries = {}
+
+          entries.each do |name, entry|
+            if name != entry.name
+              raise ArgumentError, "Entry key '#{name}' does not match entry name for '#{entry.name}'"
+            end
+
+            define_entry(entry)
+          end
+        when Enumerable
+          @entries = {}
+          entries.each { |entry| define_entry(entry) }
+        else
+          raise ArgumentError, "Entries must be an Enumerable or a Hash"
+        end
+      end
+
+      def entry(name, key_type: nil, key_transformer: nil, value_type: nil, value_transformer: nil, value_factory: nil)
+        entry = Entry.new(
+          name: name.to_sym,
+          key_type: key_type || @key_type,
+          key_transformer: key_transformer || @key_transformer,
+          value_type: value_type || @value_type,
+          value_factory: value_factory || @value_factory,
+          value_transformer: value_transformer || @value_transformer
+        )
+
+        define_entry(entry)
+      end
+
+      def setup(owner:)
+        super
+
+        property = self
+
+        if @entries.empty?
+          raise StandardError, "Please specify a key type or entries for property '#{@name}'" if @key_type.nil?
+          raise StandardError, "Please specify a value type or entries for property '#{@name}'" if @value_type.nil?
+
+          define_entry(Entry.new(name: owner.dialekt_inflector.singularize(@name), key_type: @key_type, value_type: @value_type))
+        end
+
+        type_checker = owner.class.dialekt_type_checker
+
+        @key_type ||= type_checker.union_type(types: @entries.values.map(&:key_type))
+        @value_type ||= type_checker.union_type(types: @entries.values.map(&:value_type))
+
+        owner.define_method(@name) do |value = EMPTY, &block|
+          value = property.access_value(shape: property.map_shape, target: self, value: value, &block)
+          value.dup.freeze
+        end
+
+        owner.define_method(:"#{@name}=") do |value|
+          property.set_value(shape: property.map_shape, target: self, value: value)
+        end
+
+        @entries.each_value do |entry|
+          owner.define_method(entry.name) do |key, value = EMPTY, &block|
+            property.access_entry(entry: entry, target: self, key: key, value: value, &block)
+          end
+        end
+      end
+
+      def map_shape
+        @map_shape ||= BasicProperty::Shape.new(
+          name: @name,
+          type: @type,
+          factory: @factory,
+          transformer: @transformer
+        )
+      end
+
+      def access_entry(entry:, target:, key:, value: EMPTY, &block)
+        value = if value == EMPTY
+          get_entry(entry: entry, target: target, key: key)
+        else
+          set_entry(entry: entry, target: target, key: key, value: value)
+        end
+
+        Docile.dsl_eval(value, &block) if !value.nil? && block
+        value
+      end
+
+      def get_entry(entry:, target:, key:)
+        map = get_value(shape: map_shape, target: target)
+
+        if entry.key_transformer
+          begin
+            key = entry.key_transformer.call(object: target, key: key)
+          rescue StandardError
+            raise ArgumentError, "Cannot transform key '#{key}' for property '#{@name}' (#{entry.name})"
+          end
+        end
+
+        if entry.value_factory
+          map.fetch(key) do
+            value = begin
+              entry.value_factory.call(object: target, key: key)
+            rescue StandardError
+              raise StandardError, "Cannot create entry for '#{key}' for property '#{@name}' (#{entry.name})"
+            end
+
+            map[key] = value
+          end
+        else
+          map.fetch(key) do
+            raise KeyError, "No value for key '#{key}' for property '#{@name}' (#{entry.name})"
+          end
+        end
+      end
+
+      def set_entry(entry:, target:, key:, value:)
+        map = get_value(shape: map_shape, target: target)
+        type_checker = target.class.dialekt_type_checker
+
+        if entry.key_transformer
+          begin
+            key = entry.key_transformer.call(object: target, key: key)
+          rescue StandardError
+            raise ArgumentError, "Cannot transform key '#{key}' for property '#{@name}' (#{entry.name})"
+          end
+        end
+
+        unless type_checker.valid?(type: entry.key_type, value: key)
+          raise TypeError, "Illegal key type '#{key.class}' for property '#{@name}' (#{entry.name})"
+        end
+
+        if entry.value_transformer
+          begin
+            value = entry.value_transformer.call(object: target, key: key, value: value)
+          rescue StandardError
+            raise ArgumentError, "Cannot transform value '#{value}' for property '#{@name}' (#{entry.name})"
+          end
+        end
+
+        unless type_checker.valid?(type: entry.value_type, value: value)
+          raise TypeError, "Illegal value type '#{value.class}' for property '#{@name}' (#{entry.name})"
+        end
+
+        map.store(key, value)
+      end
+
+      def key_type(type = EMPTY)
+        type == EMPTY ? @key_type : (@key_type = type)
+      end
+
+      def key_transformer(transformer = EMPTY)
+        transformer == EMPTY ? @key_transformer : (@key_transformer = transformer&.call_adapter)
+      end
+
+      def value_type(type = EMPTY)
+        type == EMPTY ? @value_type : (@value_type = type)
+      end
+
+      def value_transformer(transformer = EMPTY)
+        transformer == EMPTY ? @value_transformer : (@value_transformer = transformer&.call_adapter)
+      end
+
+      def value_factory(factory = EMPTY)
+        factory == EMPTY ? @value_factory : (@value_factory = factory&.call_adapter)
+      end
+
+      def to_s
+        result = StringIO.new
+
+        result << @name << " (" << self.class.base_name << ") {"
+        result << "type: " << @type
+        result << ", key_type: " << @key_type
+        result << ", value_type: " << @value_type
+        result << ", factory: " << @factory.source_info if @factory
+        result << ", transformer: " << @transformer.source_info if @transformer
+        result << ", entries: [" << @entries.values.map(&:name).join(", ") << "]"
+        result << "}"
+
+        result.string
+      end
+
+      protected
+
+      def define_entry(entry)
+        raise ArgumentError, "Entry '#{entry.name}' already exists for property '#{@name}'" if @entries.key?(entry.name)
+
+        @entries[entry.name] = entry
+      end
+    end
+  end
+end