dsl_maker 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cf937996460904dce3266547aab1e117ee498e8d
-  data.tar.gz: 85796fbba9b301299057952af7b5b72bda58d4cc
+  metadata.gz: a60b85736172ba9bfbd06b14f39a8d0163bd6cf1
+  data.tar.gz: 32d6433a84322447e8104e921c9a47e354a60f11
 SHA512:
-  metadata.gz: 96fce7def349ca81bebe71ea969f6f7af69d242409a4ffc8c39c5b9bc2cfbd0e9952a903191f02ebe154ba4740c801c439948713d11c0c4fb47d540e8c36a835
-  data.tar.gz: 8673a94d49a4acb702937b099de6a3c4b20d52b896c4e8a25e16ff59fce3f6c7a1fdbb5abcb536cd24bc7f3a62119134f1b890d6ee4335f254ee59d07532f30c
+  metadata.gz: e99238cb102708130d8ea95967c5acf0764988b9db5123e395f67a9f3213c8cdff94e7807d835884d6e9efb07af931a708bd69fdc9c3d66ae5e384a8543a62cb
+  data.tar.gz: 233cd1b86c6a0cee61a04ade5f947aa2b78ee35a69d14750bf4fb020f3137d5d8854548110d6483650ee9cb4d570f61be4b1999764fe6a84b0888e45f1bb0d43

data/Changes

@@ -1,5 +1,11 @@
 Revision history for DSL::Maker (ordered by revision number).
 
+0.0.6 Aug ?? 2015
+   - Added add_verification(name?) to allow for runtime verifications
+   - Don't require a dummy block when passing a DSL class to add_entrypoint.
+   - Refactored several items into private methods
+   - Pulled the provided types and helpers out of the class definition
+
 0.0.5 Jul 30 2015
    - Added missing YaRDOC for new features in 0.0.4
    - Added add_coercion() to allow the user to define new coercions for use when

data/README.md

@@ -353,7 +353,16 @@ $ gem install dsl_maker
 
 ## TODO
 
-* Add support for Arrays
+* Add support for Arrays (ArrayOf[Type]?)
+* Add support for generating useful errors (ideally with line numbers ... ?)
+* Add support for auto-generating documentation
+* Add default block that returns a Struct-of-Structs named after entrypoints
+* Add example of binary to execute a DSL
+* Add example of/link to validation and production of data structure
+   * 3-part DSL handling
+* DSL for DSL construction
+* Add "include" helper that loads another file and continues the execution
+   * Should provide useful directory searching
 
 ## Links
 

data/lib/dsl/maker.rb

@@ -42,14 +42,7 @@ class DSL::Maker
   #
   # @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
+    __run_dsl { eval dsl, self.get_binding }
   end
 
   # Execute the DSL provided in the block.
@@ -61,19 +54,9 @@ class DSL::Maker
   #
   # @return    [Object] Whatever is returned by &block
   def self.execute_dsl(&block)
-    @accumulator = []
-    instance_eval(&block)
-    if @accumulator.length <= 1
-      return @accumulator[0]
-    end
-    return @accumulator
-  end
+    raise 'Block required for execute_dsl' unless block_given?
 
-  # Returns the binding as needed by parse_dsl() and execute_dsl()
-  #
-  # @return [Binding] The binding of the invoking class.
-  def self.get_binding
-    binding
+    __run_dsl { instance_eval(&block) }
   end
 
   # FIXME: This may have to be changed when the elements can be altered because
@@ -88,11 +71,11 @@ class DSL::Maker
   # @param &block [Block]  The function to be executed when the coercion is exercised.
   #
   # Your block will receive the following signature: |attr, *args| where 'attr' is
-  # the name of the attribute and *args are the arguments passed into your method.
-  # You are responsible for acting as a mutator. You have ___get() and ___set()
-  # available for your use. These are aliases to instance_variable_get and
-  # instance_variable_set, respectively. Please read the coercions provided for
-  # you in this source file.
+  # the name of the attribute and *args are the arguments passed into your method
+  # within the DSL. You are responsible for acting as a mutator. You have ___get()
+  # and ___set() available for your use. These are aliases to
+  # instance_variable_get and instance_variable_set, respectively. Please read the
+  # coercions provided for you in this source file as examples.
   # 
   # @return nil
   def self.add_type(type, &block)
@@ -100,10 +83,9 @@ class DSL::Maker
     raise "'#{type}' is already a type coercion" if @@types.has_key? type
 
     @@types[type] = ->(klass, name, type) {
-      as_attr = '@' + name.to_s
       klass.class_eval do
         define_method(name.to_sym) do |*args|
-          instance_exec(as_attr, *args, &block)
+          instance_exec('@' + name.to_s, *args, &block)
         end
       end
     }
@@ -111,24 +93,6 @@ class DSL::Maker
     return
   end
 
-  add_type(Integer) do |attr, *args|
-    ___set(attr, args[0].to_i) unless args.empty?
-    ___get(attr)
-  end
-  add_type(String) do |attr, *args|
-    ___set(attr, args[0].to_s) unless args.empty?
-    ___get(attr)
-  end
-  add_type(Boolean) do |attr, *args|
-    ___set(attr, Boolean.coerce(args[0])) unless args.empty?
-    # Ensure that the default nil also returns as false.
-    !!___get(attr)
-  end
-
-  $is_dsl = lambda do |proto|
-    proto.is_a?(Class) && proto.ancestors.include?(DSL::Maker::Base)
-  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
@@ -148,16 +112,13 @@ class DSL::Maker
   def self.build_dsl_element(klass, name, type)
     if @@types.has_key?(type)
       @@types[type].call(klass, name, type)
-    elsif $is_dsl.call(type)
+    elsif __is_dsl(type)
       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)
@@ -223,31 +184,41 @@ class DSL::Maker
   # 
   # @return      [Class]  The class that implements this level's DSL definition.
   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?
+    symname = name.to_sym
 
-    if self.respond_to?(name.to_sym)
+    if self.respond_to?(symname)
       raise "'#{name.to_s}' is already an entrypoint"
     end
 
-    if $is_dsl.call(args)
+    if __is_dsl(args)
       dsl_class = args
     else
+      # 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?
       dsl_class = generate_dsl(args, &defn_block)
     end
 
-    define_singleton_method(name.to_sym) do |*args, &dsl_block|
+    define_singleton_method(symname) do |*args, &dsl_block|
       obj = dsl_class.new
       Docile.dsl_eval(obj, &dsl_block) if dsl_block
-      rv = obj.instance_exec(*args, &defn_block)
+      rv = obj.__apply(*args)
+
+      if @verifications && @verifications.has_key?(symname)
+        @verifications[symname].each do |verify|
+          failure = verify.call(rv)
+          raise failure if failure
+        end
+      end
+
       @accumulator.push(rv)
       return rv
     end
 
     @entrypoints ||= {}
-    return @entrypoints[name.to_sym] = dsl_class
+    return @entrypoints[symname] = dsl_class
   end
 
   # This returns the DSL corresponding to the entrypoint's name.
@@ -256,7 +227,7 @@ class DSL::Maker
   # 
   # @return      [Class]  The class that implements this name's DSL definition.
   def self.entrypoint(name)
-    unless self.respond_to?(name.to_sym)
+    unless __is_entrypoint(name)
       raise "'#{name.to_s}' is not an entrypoint"
     end
 
@@ -285,18 +256,95 @@ class DSL::Maker
     return
   end
 
-  # A helper method for handling defaults from args easily.
+  # This adds a verification that's executed after the DSL is finished parsing.
+  #
+  # The verification will be called with the value(s) returned by the entrypoint's
+  # execution. If the verification returns a true value (of any kind), then that
+  # will be raised as a runtime exception.
   #
-  # @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.
+  # Note: These verifications are specific to the DSL you add them to.
+  # Note: Verifications are called in the order you specify them.
   #
+  # @param name   [String] the name of the entrypoint to add a verification to
+  # @param &block [Block]  The function to be executed when verifications execute
+  # 
   # @return nil
-  add_helper(:default) do |method_name, args, position=0|
-    method = method_name.to_sym
-    if args.length >= (position + 1) && !self.send(method)
-      self.send(method, args[position])
-    end
+  def self.add_verification(name, &block)
+    raise "Block required for add_verification" unless block_given?
+    raise "'#{name.to_s}' is not an entrypoint for a verification" unless __is_entrypoint(name)
+
+    @verifications ||= {}
+    @verifications[name.to_sym] ||= []
+
+    # This craziness converts the block provided into a proc that can be called
+    # in add_entrypoint(). Taken from http://stackoverflow.com/a/2946734/1732954
+    # Note: self is not preserved. This should be okay because the verification
+    # should only care about the value provided.
+    obj = Object.new
+    obj.define_singleton_method(:_, &block)
+    @verifications[name.to_sym].push(obj.method(:_).to_proc)
+
     return
   end
+
+  private
+
+  # Returns the binding as needed by parse_dsl() and execute_dsl()
+  #
+  # @return [Binding] The binding of the invoking class.
+  def self.get_binding
+    binding
+  end
+
+  def self.__run_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 = []
+
+    yield
+
+    if @accumulator.length <= 1
+      return @accumulator[0]
+    end
+    return @accumulator
+  end
+
+  def self.__is_dsl(proto)
+    proto.is_a?(Class) && proto.ancestors.include?(DSL::Maker::Base)
+  end
+
+  def self.__is_entrypoint(name)
+    respond_to?(name.to_sym)
+  end
+end
+
+# These are the default setups.
+
+DSL::Maker.add_type(Integer) do |attr, *args|
+  ___set(attr, args[0].to_i) unless args.empty?
+  ___get(attr)
+end
+DSL::Maker.add_type(String) do |attr, *args|
+  ___set(attr, args[0].to_s) unless args.empty?
+  ___get(attr)
+end
+DSL::Maker.add_type(DSL::Maker::Boolean) do |attr, *args|
+  ___set(attr, DSL::Maker::Boolean.coerce(args[0])) unless args.empty?
+  # Ensure that the default nil also returns as false.
+  !!___get(attr)
+end
+
+# 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
+DSL::Maker.add_helper(:default) do |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

data/lib/dsl/maker/version.rb

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

data/spec/error_spec.rb

@@ -11,6 +11,12 @@ describe "DSL::Maker validation" do
     }.to raise_error('Block required for generate_dsl')
   end
 
+  it "requires a block for execute_dsl" do
+    expect {
+      Class.new(DSL::Maker).execute_dsl
+    }.to raise_error('Block required for execute_dsl')
+  end
+
   describe "for attributes" do
     it "requires a recognized type for attributes" do
       expect {
@@ -66,6 +72,24 @@ describe "DSL::Maker validation" do
     end
   end
 
+  describe "for verifications" do
+    it "requires a block for :add_verification" do
+      expect {
+        Class.new(DSL::Maker) do
+          add_verification(:pizza)
+        end
+      }.to raise_error('Block required for add_verification')
+    end
+
+    it "rejects an verification name that doesn't exist in entrypoint()" do
+      dsl_class = Class.new(DSL::Maker)
+
+      expect {
+        dsl_class.add_verification(:x) {}
+      }.to raise_error("'x' is not an entrypoint for a verification")
+    end
+  end
+
   describe "for helpers" do
     it "rejects a helper without a block" do
       dsl_class = Class.new(DSL::Maker)

data/spec/single_level_spec.rb

@@ -108,12 +108,11 @@ describe 'A single-level DSL for pizza' do
         :bacon => DSL::Maker::Boolean,
         :pepperoni => DSL::Maker::Boolean,
         :sauce => String,
-      }) {}
-
-      # This is a wart - this block should be against toppings_dsl, not here.
-      add_entrypoint(:pizza, toppings_dsl) do
+      }) do
         $Pizza.new(cheese, pepperoni, bacon, sauce)
       end
+
+      add_entrypoint(:pizza, toppings_dsl)
     end
 
     pizza = dsl_class.parse_dsl("
@@ -139,12 +138,11 @@ describe 'A single-level DSL for pizza' do
         :bacon => DSL::Maker::Boolean,
         :pepperoni => DSL::Maker::Boolean,
         :sauce => String,
-      }) {}
-
-      # This is a wart - this block should be against toppings_dsl, not here.
-      add_entrypoint(:pizza, toppings_dsl) do
+      }) do
         $Pizza.new(cheese, pepperoni, bacon, sauce)
       end
+
+      add_entrypoint(:pizza, toppings_dsl)
     end
 
     pizza = dsl_class.execute_dsl do

data/spec/validation_spec.rb

@@ -0,0 +1,29 @@
+# These are tests about the validation process for DSL::Maker
+
+describe "Validations" do
+  it "validates entrypoint-specific items" do
+    dsl_class = Class.new(DSL::Maker) do
+      toppings_dsl = generate_dsl({
+        :cheese => DSL::Maker::Boolean,
+        :bacon => DSL::Maker::Boolean,
+        :pepperoni => DSL::Maker::Boolean,
+        :sauce => String,
+      }) do
+        $Pizza.new(cheese, pepperoni, bacon, sauce)
+      end
+
+      add_entrypoint(:pizza, toppings_dsl)
+      add_verification(:pizza) do |item|
+        return "Pizza must have sauce" unless item.sauce
+      end
+    end
+
+    expect {
+      dsl_class.parse_dsl("pizza {}")
+    }.to raise_error("Pizza must have sauce")
+
+    expect {
+      dsl_class.parse_dsl("pizza { sauce :extra }")
+    }.to_not raise_error
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dsl_maker
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Rob Kinyon
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-30 00:00:00.000000000 Z
+date: 2015-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: docile
@@ -162,6 +162,7 @@ files:
 - spec/multiple_invocation_spec.rb
 - spec/single_level_spec.rb
 - spec/spec_helper.rb
+- spec/validation_spec.rb
 homepage: https://github.com/robkinyon/ruby-dsl-maker
 licenses:
 - GPL2