dsl_maker 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ff32adb37883c0c6466af73eac18c78e0315cffd
-  data.tar.gz: ebaaa08053e1c7d1a3066c3a3ec18cebf685a10b
+  metadata.gz: cf937996460904dce3266547aab1e117ee498e8d
+  data.tar.gz: 85796fbba9b301299057952af7b5b72bda58d4cc
 SHA512:
-  metadata.gz: 237aef00aa5afa13e8d5cd39a72ee339e43de1988426305f1af0183b15a242d971de0a3398bae3a5817f1a2cc9f96a8c64fb36888b6617571b5f7c656757c8f6
-  data.tar.gz: 3274e9f900246bac32bc9dbec107e2120544d8241a4109857b79ae4a2d33ec147dd69a832d00392a351a95af015f4f3756110641a6855e3ebe2f98b5c3d05247
+  metadata.gz: 96fce7def349ca81bebe71ea969f6f7af69d242409a4ffc8c39c5b9bc2cfbd0e9952a903191f02ebe154ba4740c801c439948713d11c0c4fb47d540e8c36a835
+  data.tar.gz: 8673a94d49a4acb702937b099de6a3c4b20d52b896c4e8a25e16ff59fce3f6c7a1fdbb5abcb536cd24bc7f3a62119134f1b890d6ee4335f254ee59d07532f30c

data/Changes

@@ -1,5 +1,11 @@
 Revision history for DSL::Maker (ordered by revision number).
 
+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
+     creating their DSL.
+   - Eat our own dogfood vis-a-vis helpers and coercions.
+
 0.0.4 Jul 29 2015
    - Added add_helper() to allow the user to define new helper methods for use
      within the DSL.

data/README.md

@@ -300,6 +300,13 @@ This is normally called by `generate_dsl()` to actually construct the DSL elemen
 It is provided for you so that you can create recursive DSL definitions. Look at
 the tests in `spec/multi_level_spec.rb` for an example of this.
 
+* `add_type(Object, Block)`
+
+This is used to create type coercions that are used when defining your DSL. These
+are treated at the same level as the default type coercions described below.
+
+This creates global type coercions that are available to every DSL definition.
+
 * `add_helper(Symbol, Block)`
 
 This is used to create helper methods (similar to `default`, described below) that
@@ -316,15 +323,16 @@ In the case of multiple DSL entrypoints (for example, a normal Chef recipe),
 these methods will return an array with all the return values in the order they
 were encountered.
 
-### Coercions
+### Type Coercions
 
-There are three defined coercions for use within `generate_dsl()`:
+There are four pre-defined type coercions for use within `generate_dsl()`:
 
-  * String - This takes any string.
+  * String - This takes whatever you give it and returns the string within it.
+  * Integer - This takes whatever you give it and returns the integer within it.
   * Boolean - This takes whatever you give it and returns the truthiness of it.
   * `generate_dsl()` - This descends into another level of DSL.
 
-You will be able to add your own coercions in a forthcoming version of DSL::Maker.
+You can add additional type coercions using `add_type()` as described above.
 
 ### Helpers
 
@@ -335,7 +343,7 @@ There is one pre-defined helper.
 This takes a method name and the args provided to the block. It then ensures that
 the method defaults to the value in the args at the optional third argument.
 
-You can add additional helpers using `add_helper()` described above.
+You can add additional helpers using `add_helper()` as described above.
 
 ## Installation
 
@@ -346,8 +354,6 @@ $ gem install dsl_maker
 ## TODO
 
 * Add support for Arrays
-* Add additional coercions (e.g., Number)
-* Allow you to add your own coercions
 
 ## Links
 

data/lib/dsl/maker/version.rb

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

data/lib/dsl/maker.rb

@@ -11,21 +11,6 @@ class DSL::Maker
 
     # 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
 
   # This is a useful module that contains all the Boolean handling we need.
@@ -93,27 +78,52 @@ class DSL::Maker
 
   # FIXME: This may have to be changed when the elements can be altered because
   # it is global to the hierarchy. But, that may be desirable.
-  @@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
-    },
-    DSL::Maker::Boolean => ->(klass, name, type) {
+  @@types = {}
+
+  # This adds a type coercion that's used when creating the DSL.
+  #
+  # Note: These type coercions are global to all DSLs.
+  #
+  # @param type   [Object] the name of the helper
+  # @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.
+  # 
+  # @return nil
+  def self.add_type(type, &block)
+    raise "Block required for add_type" unless block_given?
+    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|
-          ___set(as_attr, Boolean.coerce(args[0])) unless args.empty?
-          # Ensure that the default nil returns as false.
-          !!___get(as_attr)
+          instance_exec(as_attr, *args, &block)
         end
       end
-    },
-  }
+    }
+
+    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)
@@ -122,21 +132,22 @@ class DSL::Maker
   # 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:
+  # in that name. The standard type coercions are:
   #
   #   * String  - whatever you give is returned.
+  #   * Integer - the integer value of 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.
+  #                       This is the type 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)
+    if @@types.has_key?(type)
+      @@types[type].call(klass, name, type)
     elsif $is_dsl.call(type)
       as_attr = '@' + name.to_s
       klass.class_eval do
@@ -221,8 +232,6 @@ class DSL::Maker
       raise "'#{name.to_s}' is already an entrypoint"
     end
 
-    # FIXME: This is a wart. Really, we should be pulling out name, then
-    # yielding to generate_dsl() in some fashion.
     if $is_dsl.call(args)
       dsl_class = args
     else
@@ -254,6 +263,14 @@ class DSL::Maker
     return @entrypoints[name.to_sym]
   end
 
+  # This adds a helper function that's accessible within the DSL.
+  #
+  # Note: These helpers are global to all DSLs.
+  #
+  # @param name   [String] the name of the helper
+  # @param &block [Block]  The function to be executed when the helper is called.
+  # 
+  # @return nil
   def self.add_helper(name, &block)
     raise "Block required for add_helper" unless block_given?
 
@@ -264,5 +281,22 @@ class DSL::Maker
     DSL::Maker::Base.class_eval do
       define_method(name.to_sym, &block)
     end
+
+    return
+  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
+  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
 end

data/spec/class_as_subdsl_spec.rb

@@ -8,7 +8,7 @@ describe "Passing a class into generate_dsl" do
   it "can do it" do
     wheel_dsl = Class.new(DSL::Maker) do
       add_entrypoint(:wheel, {
-        :size => String,
+        :size => Integer,
         :maker => String,
       }) do |*args|
         default(:maker, args, 0)
@@ -37,7 +37,7 @@ describe "Passing a class into generate_dsl" do
     expect(car.maker).to eq('honda')
     expect(car.wheel).to be_instance_of($Wheel)
     expect(car.wheel.maker).to eq('goodyear')
-    expect(car.wheel.size).to eq('26')
+    expect(car.wheel.size).to eq(26)
   end
 
   # This ensures that if we create multiple entrypoints with the same name, they
@@ -45,7 +45,7 @@ describe "Passing a class into generate_dsl" do
   it "will not tramp on the entrypoints with the same name" do
     wheel_dsl = Class.new(DSL::Maker) do
       add_entrypoint(:wheel, {
-        :size => String,
+        :size => Integer,
         :maker => String,
       }) do |*args|
         default(:maker, args, 0)
@@ -78,6 +78,6 @@ describe "Passing a class into generate_dsl" do
     expect(car.maker).to eq('honda')
     expect(car.wheel).to be_instance_of($Wheel)
     expect(car.wheel.maker).to eq('goodyear')
-    expect(car.wheel.size).to eq('26')
+    expect(car.wheel.size).to eq(26)
   end
 end

data/spec/error_spec.rb

@@ -1,14 +1,6 @@
 # This verifies the various error-handling situations.
 
 describe "DSL::Maker validation" do
-  it "requires a block for :add_entrypoint" do
-    expect {
-      Class.new(DSL::Maker) do
-        add_entrypoint(:pizza)
-      end
-    }.to raise_error('Block required for add_entrypoint')
-  end
-
   it "requires a block for :generate_dsl" do
     expect {
       Class.new(DSL::Maker) do
@@ -19,71 +11,103 @@ describe "DSL::Maker validation" do
     }.to raise_error('Block required for generate_dsl')
   end
 
-  it "requires a recognized type for attributes" do
-    expect {
-      Class.new(DSL::Maker) do
-        add_entrypoint(:pizza, {
-          :cheese => true,
-        }) do
-          Pizza.new(cheese, nil, nil, nil)
-        end
-      end
-    }.to raise_error("Unrecognized element type 'true'")
-  end
-
-  it "rejects attributes which block Boolean helper methods" do
-    %w(yes no on off __apply).each do |name|
+  describe "for attributes" do
+    it "requires a recognized type for attributes" do
       expect {
         Class.new(DSL::Maker) do
           add_entrypoint(:pizza, {
-            name => String,
+            :cheese => true,
           }) do
             Pizza.new(cheese, nil, nil, nil)
           end
         end
-      }.to raise_error("Illegal attribute name '#{name}'")
+      }.to raise_error("Unrecognized element type 'true'")
     end
-  end
 
-  it "rejects re-using an entrypoint name in add_entrypoint()" do
-    dsl_class = Class.new(DSL::Maker) do
-      add_entrypoint(:x, {}) { nil }
+    it "rejects attributes which block Boolean helper methods" do
+      %w(yes no on off __apply).each do |name|
+        expect {
+          Class.new(DSL::Maker) do
+            add_entrypoint(:pizza, {
+              name => String,
+            }) do
+              Pizza.new(cheese, nil, nil, nil)
+            end
+          end
+        }.to raise_error("Illegal attribute name '#{name}'")
+      end
     end
-    expect {
-      dsl_class.add_entrypoint(:x, {}) { nil }
-    }.to raise_error("'x' is already an entrypoint")
   end
 
-  it "rejects an entrypoint name that doesn't exist in entrypoint()" do
-    dsl_class = Class.new(DSL::Maker)
+  describe "for entrypoints" do
+    it "requires a block for :add_entrypoint" do
+      expect {
+        Class.new(DSL::Maker) do
+          add_entrypoint(:pizza)
+        end
+      }.to raise_error('Block required for add_entrypoint')
+    end
 
-    expect {
-      dsl_class.entrypoint(:x)
-    }.to raise_error("'x' is not an entrypoint")
-  end
+    it "rejects re-using an entrypoint name in add_entrypoint()" do
+      dsl_class = Class.new(DSL::Maker) do
+        add_entrypoint(:x, {}) { nil }
+      end
+      expect {
+        dsl_class.add_entrypoint(:x, {}) { nil }
+      }.to raise_error("'x' is already an entrypoint")
+    end
 
-  it "rejects a helper without a block" do
-    dsl_class = Class.new(DSL::Maker)
+    it "rejects an entrypoint name that doesn't exist in entrypoint()" do
+      dsl_class = Class.new(DSL::Maker)
 
-    expect {
-      dsl_class.add_helper(:x)
-    }.to raise_error('Block required for add_helper')
+      expect {
+        dsl_class.entrypoint(:x)
+      }.to raise_error("'x' is not an entrypoint")
+    end
   end
 
-  it "rejects the helper name default" do
-    dsl_class = Class.new(DSL::Maker)
+  describe "for helpers" do
+    it "rejects a helper without a block" do
+      dsl_class = Class.new(DSL::Maker)
 
-    expect {
-      dsl_class.add_helper(:default) {}
-    }.to raise_error("'default' is already a helper")
-  end
+      expect {
+        dsl_class.add_helper(:x)
+      }.to raise_error('Block required for add_helper')
+    end
 
-  it "rejects a helper name already in use" do
-    dsl_class = Class.new(DSL::Maker)
-    dsl_class.add_helper(:x) {}
+    it "rejects the helper name default" do
+      dsl_class = Class.new(DSL::Maker)
 
-    expect {
+      expect {
+        dsl_class.add_helper(:default) {}
+      }.to raise_error("'default' is already a helper")
+    end
+
+    it "rejects a helper name already in use" do
+      dsl_class = Class.new(DSL::Maker)
       dsl_class.add_helper(:x) {}
-    }.to raise_error("'x' is already a helper")
+
+      expect {
+        dsl_class.add_helper(:x) {}
+      }.to raise_error("'x' is already a helper")
+    end
+  end
+
+  describe "for type coercions" do
+    it "rejects a type coercion without a block" do
+      dsl_class = Class.new(DSL::Maker)
+
+      expect {
+        dsl_class.add_type(:x)
+      }.to raise_error('Block required for add_type')
+    end
+
+    it "rejects a type coercion type already in use" do
+      dsl_class = Class.new(DSL::Maker)
+
+      expect {
+        dsl_class.add_type(String) {}
+      }.to raise_error("'String' is already a type coercion")
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dsl_maker
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Rob Kinyon