dsl_maker 0.0.1

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rake/clean'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+# This is used by the Yardoc stuff in docile's Rakefile. We're not there yet.
+#require File.expand_path('on_what', File.dirname(__FILE__))
+
+# Default task for `rake` is to run rspec
+task :default => [:spec]
+
+# Use default rspec rake task
+RSpec::Core::RakeTask.new
+
+# Configure `rake clobber` to delete all generated files
+CLOBBER.include('pkg', 'doc', 'coverage')
+
+if !on_travis? && !on_jruby? && !on_1_8?
+  require 'github/markup'
+  require 'redcarpet'
+  require 'yard'
+  require 'yard/rake/yardoc_task'
+
+  YARD::Rake::YardocTask.new do |t|
+    OTHER_PATHS = %w()
+    t.files   = ['lib/**/*.rb', OTHER_PATHS]
+    t.options = %w(--markup-provider=redcarpet --markup=markdown --main=README.md)
+  end
+end

data/dsl_maker.gemspec

@@ -0,0 +1,38 @@
+require File.expand_path('on_what', File.dirname(__FILE__))
+$:.push File.expand_path('../lib', __FILE__)
+require 'dsl/maker/version'
+
+Gem::Specification.new do |s|
+  s.name    = 'dsl_maker'
+  s.version = DSL::Maker::VERSION
+  s.author  = 'Rob Kinyon'
+  s.email   = 'rob.kinyon@gmail.com'
+  s.summary = 'Easy multi-level DSLs'
+  s.description = 'Easy multi-level DSLs, built on top of Docile'
+  s.license = 'GPL2'
+  s.homepage = 'https://github.com/robkinyon/ruby-dsl-maker'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = []
+  s.require_paths = %w(lib)
+
+  s.required_ruby_version = '>= 1.9.3'
+
+  s.add_dependency 'docile', '~> 1.1', '>= 1.1.0'
+
+  # Run rspec tests from rake
+  s.add_development_dependency 'rake', '~> 10'
+  s.add_development_dependency 'rspec', '~> 3.0.0', '>= 3.0.0'
+  s.add_development_dependency 'simplecov', '~> 0'
+
+  # To limit needed compatibility with versions of dependencies, only configure
+  #   yard doc generation when *not* on Travis, JRuby, or 1.8
+  if !on_travis? && !on_jruby? && !on_1_8?
+    # Github flavored markdown in YARD documentation
+    # http://blog.nikosd.com/2011/11/github-flavored-markdown-in-yard.html
+    s.add_development_dependency 'yard', '~> 0.8'
+    s.add_development_dependency 'redcarpet', '~> 3'
+    s.add_development_dependency 'github-markup', '~> 1.3'
+  end
+end

data/lib/dsl/maker.rb

@@ -0,0 +1,207 @@
+require 'dsl/maker/version'
+
+require 'docile'
+
+# The DSL namespace
+module DSL
+  # This is the base class we provide.
+  class Maker
+    # This is a useful class that contains all the Boolean handling we have.
+    class Boolean
+      {
+        :yes => true, :no  => false,
+        :on  => true, :off => false,
+      }.each do |name, result|
+        define_method(name) { result }
+      end
+
+      # 21 character method names are obscene. Make it easier to read.
+      alias :___set :instance_variable_set
+
+      # 21 character method names are obscene. Make it easier to read.
+      alias :___get :instance_variable_get
+
+      # A helper method for handling defaults from args easily.
+      # 
+      # @param method_name [String]  The name of the attribute being defaulted.
+      # @param args        [Array]   The arguments provided to the block.
+      # @param position    [Integer] The index in args to work with, default 0.
+      #
+      # @return nil
+      def default(method_name, args, position=0)
+        method = method_name.to_sym
+        if args.length >= (position + 1) && !self.send(method)
+          self.send(method, args[position])
+        end
+        return
+      end
+    end
+    Yes = On = True = true
+    No = Off = False = false
+    $to_bool = lambda do |value|
+      if value
+        return false if %w(no off false nil).include? value.to_s.downcase
+      end
+      # The bang-bang boolean-izes the value. We want this to be lossy.
+      !!value
+    end
+
+    # TODO: Is this safe if the invoker doesn't use parse_dsl()?
+    @@accumulator = []
+
+    # Parse the DSL provided in the parameter
+    #
+    # @note If the DSL contains multiple entrypoints, then this will return an
+    # Array. This is desirable.
+    #
+    # @param dsl [String] The DSL to be parsed by this class.
+    #
+    # @return    [Object] Whatever is returned by the block defined in this class.
+    def self.parse_dsl(dsl)
+      # add_entrypoint() will use @@accumulator to handle multiple entrypoints.
+      # Reset it here so that we're only handling the values from this run.
+      @@accumulator = []
+      eval dsl, self.get_binding
+      if @@accumulator.length <= 1
+        return @@accumulator[0]
+      end
+      return @@accumulator
+    end
+
+    @@dsl_elements = {
+      String => ->(klass, name, type) {
+        as_attr = '@' + name.to_s
+        klass.class_eval do
+          define_method(name.to_sym) do |*args|
+            ___set(as_attr, args[0].to_s) unless args.empty?
+            ___get(as_attr)
+          end
+        end
+      },
+      Boolean => ->(klass, name, type) {
+        as_attr = '@' + name.to_s
+        klass.class_eval do
+          define_method(name.to_sym) do |*args|
+            ___set(as_attr, $to_bool.call(args[0])) unless args.empty?
+            # Ensure that the default nil returns as false.
+            !!___get(as_attr)
+          end
+        end
+      },
+    }
+
+    # Add a single element of a DSL to a class representing a level in a DSL.
+    #
+    # Each of the types represents a coercion - a guarantee and check of the value
+    # in that name. The standard coercions are:
+    #
+    #   * String  - whatever you give is returned.
+    #   * Boolean - the truthiness of whatever you give is returned.
+    #   * generate_dsl() - this represents a new level of the DSL.
+    #
+    # @param klass [Class]  The class representing this level in the DSL.
+    # @param name  [String] The name of the element we're working on.
+    # @param type  [Class]  The type of this element we're working on.
+    #                       This is the coercion spoken above.
+    #
+    # @return   nil
+    def self.build_dsl_element(klass, name, type)
+      if @@dsl_elements.has_key?(type)
+        @@dsl_elements[type].call(klass, name, type)
+      elsif type.is_a?(Class) && type.ancestors.include?(Boolean)
+        as_attr = '@' + name.to_s
+        klass.class_eval do
+          define_method(name.to_sym) do |*args, &dsl_block|
+            unless (args.empty? && !dsl_block)
+              obj = type.new
+              Docile.dsl_eval(obj, &dsl_block) if dsl_block
+
+              # I don't know why this code doesn't work, but it's why __apply().
+              #___set(as_attr, obj.instance_exec(*args, &defn_block))
+              ___set(as_attr, obj.__apply(*args))
+            end
+            ___get(as_attr)
+          end
+        end
+      else
+        raise "Unrecognized element type '#{type}'"
+      end
+
+      return
+    end
+
+    # Add the meat of a DSL block to some level of this class's DSL.
+    #
+    # In order for Docile to parse a DSL, each level must be represented by a
+    # different class. This method creates anonymous classes that each represents
+    # a different level in the DSL's structure.
+    #
+    # The creation of each DSL element is delegated to build_dsl_element.
+    #
+    # @param args  [Hash]   the elements of the DSL block (passed to generate_dsl)
+    # @param defn_block [Proc]   what is executed once the DSL block is parsed.
+    #
+    # @return      [Class]  The class that implements this level's DSL definition.
+    def self.generate_dsl(args={}, &defn_block)
+      raise 'Block required for generate_dsl' unless block_given?
+
+      # Inherit from the Boolean class to gain access to the useful methods
+      # TODO: Convert DSL::Maker::Boolean into a Role
+      # TODO: Create a DSL::Maker::Base class to inherit from
+      klass = Class.new(Boolean) do
+        # This instance method exists because we cannot seem to inline its work
+        # where we call it. Could it be a problem of incorrect binding?
+        # It has to be defined here because it needs access to &defn_block
+        define_method(:__apply) do |*args|
+          instance_exec(*args, &defn_block)
+        end
+      end
+
+      args.each do |name, type|
+        if klass.new.respond_to? name.to_sym
+          raise "Illegal attribute name '#{name}'"
+        end
+
+        build_dsl_element(klass, name, type)
+      end
+
+      return klass
+    end
+
+    # Add an entrypoint (top-level DSL element) to this class's DSL.
+    #
+    # This delegates to generate_dsl() for the majority of the work.
+    #
+    # @param name  [String] the name of the entrypoint
+    # @param args  [Hash]   the elements of the DSL block (passed to generate_dsl)
+    # @param defn_block [Proc]   what is executed once the DSL block is parsed.
+    # 
+    # @return      nil
+    def self.add_entrypoint(name, args={}, &defn_block)
+      # Without defn_block, there's no way to give back the result of the
+      # DSL parsing. So, raise an error if we don't get one.
+      # TODO: Provide a default block that returns the datastructure as a HoH.
+      raise "Block required for add_entrypoint" unless block_given?
+
+      # Ensure that get_binding() exists in the child class. This is necessary to
+      # provide parse_dsl() so that eval works as expected. We have to do it here
+      # because this is the only place we know for certain will be called.
+      unless self.respond_to? :get_binding
+        define_singleton_method(:get_binding) { binding }
+      end
+
+      # FIXME: This is a wart. Really, we should be pulling out name, then
+      # yielding to generate_dsl() in some fashion.
+      dsl_class = generate_dsl(args) {}
+
+      define_singleton_method(name.to_sym) do |*args, &dsl_block|
+        obj = dsl_class.new
+        Docile.dsl_eval(obj, &dsl_block) if dsl_block
+        rv = obj.instance_exec(*args, &defn_block)
+        @@accumulator.push(rv)
+        return rv
+      end
+      return
+    end
+  end
+end

data/lib/dsl/maker/version.rb

@@ -0,0 +1,6 @@
+module DSL
+  class Maker
+    # The current version of this library
+    VERSION = '0.0.1'
+  end
+end

data/on_what.rb

@@ -0,0 +1,15 @@
+# NOTE: Very simple tests for what system we are on, extracted for sharing
+#   between Rakefile, gemspec, and spec_helper. Not for use in actual library.
+# This is copied from https://github.com/ms-ati/docile/blob/master/on_what.rb
+
+def on_travis?
+  ENV['CI'] == 'true'
+end
+
+def on_jruby?
+  defined?(RUBY_ENGINE) && 'jruby' == RUBY_ENGINE
+end
+
+def on_1_8?
+  RUBY_VERSION.start_with? '1.8'
+end

data/spec/args_spec.rb

@@ -0,0 +1,163 @@
+# This will use a DSL that defines fruit
+
+describe "A DSL with argument handling describing fruit" do
+  Color = Struct.new(:name)
+  Fruit = Struct.new(:name, :color)
+
+  describe "with one argument in add_entrypoint" do
+    dsl_class = Class.new(DSL::Maker) do
+      add_entrypoint(:fruit, {
+        :name => String,
+      }) do |*args|
+        default(:name, args, 0)
+        Fruit.new(name, nil)
+      end
+    end
+
+    it "can handle nil" do
+      fruit = dsl_class.parse_dsl("
+        fruit
+      ")
+      expect(fruit).to be_instance_of(Fruit)
+      expect(fruit.name).to be_nil
+    end
+
+    it "can handle the name in the attribute" do
+      fruit = dsl_class.parse_dsl("
+        fruit { name 'banana' }
+      ")
+      expect(fruit).to be_instance_of(Fruit)
+      expect(fruit.name).to eq('banana')
+    end
+
+    it "can handle the name in the args" do
+      fruit = dsl_class.parse_dsl("
+        fruit 'banana'
+      ")
+      expect(fruit).to be_instance_of(Fruit)
+      expect(fruit.name).to eq('banana')
+    end
+
+    it "can handle setting the name in both" do
+      fruit = dsl_class.parse_dsl("
+        # Minions don't get to name fruit
+        fruit 'buh-nana!' do
+          name 'banana'
+        end
+      ")
+      expect(fruit).to be_instance_of(Fruit)
+      expect(fruit.name).to eq('banana')
+    end
+  end
+
+  describe "with two arguments in add_entrypoint" do
+    dsl_class = Class.new(DSL::Maker) do
+      add_entrypoint(:fruit, {
+        :name => String,
+        :color => String,
+      }) do |*args|
+        default('name', args)
+        default('color', args, 1)
+
+        Fruit.new(name, color)
+      end
+    end
+
+    it "can handle no arguments" do
+      fruit = dsl_class.parse_dsl("
+        fruit
+      ")
+      expect(fruit).to be_instance_of(Fruit)
+      expect(fruit.name).to be_nil
+      expect(fruit.color).to be_nil
+    end
+
+    it "can handle the name in args, color in attributes" do
+      # Must use parentheses if you want to curly-braces
+      fruit = dsl_class.parse_dsl("
+        fruit('banana') {
+          color 'yellow'
+        }
+      ")
+      expect(fruit).to be_instance_of(Fruit)
+      expect(fruit.name).to eq('banana')
+      expect(fruit.color).to eq('yellow')
+
+      # Must use do..end syntax if you want to avoid parentheses
+      fruit = dsl_class.parse_dsl("
+        fruit 'plantain' do
+          color 'green'
+        end
+      ")
+      expect(fruit).to be_instance_of(Fruit)
+      expect(fruit.name).to eq('plantain')
+      expect(fruit.color).to eq('green')
+    end
+
+    it "can handle everything in the args" do
+      fruit = dsl_class.parse_dsl("
+        fruit 'banana', 'yellow'
+      ")
+      expect(fruit).to be_instance_of(Fruit)
+      expect(fruit.name).to eq('banana')
+      expect(fruit.color).to eq('yellow')
+    end
+  end
+
+  describe "with one argument in generate_dsl" do
+    dsl_class = Class.new(DSL::Maker) do
+      add_entrypoint(:fruit, {
+        :name => String,
+        :color => generate_dsl({
+          :name => String,
+        }) { |*args|
+          default('name', args, 0)
+          Color.new(name)
+        }
+      }) do |*args|
+        default('name', args, 0)
+        Fruit.new(name, color)
+      end
+    end
+
+    it "can handle arguments for fruit, but attribute for color" do
+      fruit = dsl_class.parse_dsl("
+        fruit 'banana' do
+          color {
+            name 'yellow'
+          }
+        end
+      ")
+      expect(fruit).to be_instance_of(Fruit)
+      expect(fruit.name).to eq('banana')
+      expect(fruit.color).to be_instance_of(Color)
+      expect(fruit.color.name).to eq('yellow')
+    end
+
+    it "can handle arguments for both fruit and color" do
+      fruit = dsl_class.parse_dsl("
+        fruit 'banana' do
+          color 'yellow'
+        end
+      ")
+      expect(fruit).to be_instance_of(Fruit)
+      expect(fruit.name).to eq('banana')
+      expect(fruit.color).to be_instance_of(Color)
+      expect(fruit.color.name).to eq('yellow')
+    end
+
+    it "can handle arguments for both fruit and color" do
+      fruit = dsl_class.parse_dsl("
+        fruit 'banana' do
+          color 'yellow' do
+            name 'green'
+          end
+        end
+      ")
+      expect(fruit).to be_instance_of(Fruit)
+      expect(fruit.name).to eq('banana')
+      expect(fruit.color).to be_instance_of(Color)
+      expect(fruit.color.name).to eq('green')
+    end
+  end
+end