dsl_maker 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4dcf7e27a270d732f50700ad02cc0e2df6410d31
-  data.tar.gz: 67af6f9d5095417301601997d3f4244d6887a329
+  metadata.gz: ff32adb37883c0c6466af73eac18c78e0315cffd
+  data.tar.gz: ebaaa08053e1c7d1a3066c3a3ec18cebf685a10b
 SHA512:
-  metadata.gz: c3c69f7f5890b5266ec5a00a6e2c7d3238f50839ee5f527887024d63b90d146c4959b11f69575753d77ba1f6f3add5f8bbb6957533d8960428c0cdcd0c7c92c5
-  data.tar.gz: 3a78ff0dfce77a4c3e358400864110c068f102698a7aace6741315369f0956f80b55fb92431302ad8d262eb877fe48c955d08960c70dce0a6dac50c2b5d6a8c5
+  metadata.gz: 237aef00aa5afa13e8d5cd39a72ee339e43de1988426305f1af0183b15a242d971de0a3398bae3a5817f1a2cc9f96a8c64fb36888b6617571b5f7c656757c8f6
+  data.tar.gz: 3274e9f900246bac32bc9dbec107e2120544d8241a4109857b79ae4a2d33ec147dd69a832d00392a351a95af015f4f3756110641a6855e3ebe2f98b5c3d05247

data/Changes

@@ -1,5 +1,11 @@
 Revision history for DSL::Maker (ordered by revision number).
 
+0.0.4 Jul 29 2015
+   - Added add_helper() to allow the user to define new helper methods for use
+     within the DSL.
+   - Added missing documentation in README for new features in 0.0.3
+   - Added TODO list in documentation
+
 0.0.3 Jul 28 2015
    - Added entrypoint() that returns the DSL implementing an entrypoint
    - Several refactorings to improve maintainability:

data/README.md

@@ -9,7 +9,6 @@
 [![Code Coverage](https://img.shields.io/codecov/c/github/robkinyon/ruby-dsl-maker.svg)](https://codecov.io/github/robkinyon/ruby-dsl-maker)
 [![Inline docs](http://inch-ci.org/github/robkinyon/ruby-dsl-maker.png)](http://inch-ci.org/github/robkinyon/ruby-dsl-maker)
 
-
 Writing single-level Ruby-like DSLs is really easy. Ruby practically builds them
 for you with a little meta-programming. [Docile](https://github.com/ms-ati/docile)
 makes it ridiculously easy and there are nearly a dozen other modules to do so.
@@ -55,9 +54,6 @@ class PizzaBuilder
     Pizza.new(!!@cheese, !!@pepperoni, !!@bacon, @sauce)
   end
 end
-
-PizzaBuilder.new.cheese.pepperoni.sauce(:extra).build
-#=> #<Pizza:0x00001009dc398 @cheese=true, @pepperoni=true, @bacon=false, @sauce=:extra>
 ```
 
 But, this doesn't actually implement the DSL. That is left for another snippet:
@@ -85,7 +81,14 @@ class PizzaBuilder < DSL::Maker
   end
 end
 
-pizza = PizzaBuilder.parse_dsl(dsl_block)
+pizza = PizzaBuilder.parse_dsl("
+  pizza {
+    cheese yes
+    pepperoni Yes
+    bacon On
+    sauce 'extra'
+  }
+")
 ```
 
 Now, you accept the strings (possibly from `IO.read()`) and magically get the
@@ -132,7 +135,7 @@ john_smith = FamilyTree.parse_dsl("
 ")
 ```
 
-Refactor that a bit and we end up with:
+Pretty easy. We can even refactor that a bit and end up with:
 
 ```ruby
 class FamilyTree < DSL::Maker
@@ -268,7 +271,7 @@ you get back an `Array` with everything in the right order.
 
 ### Class Methods
 
-DSL::Maker provides five class methods - three for constructing your DSL and two
+DSL::Maker provides seven class methods - five for constructing your DSL and two
 for parsing your DSL.
 
 * `add_entrypoint(Symbol, Hash={}, Block)`
@@ -278,6 +281,13 @@ level of your DSL. `add_entrypoint()` will create the right class methods for
 Docile to use when `parse_dsl()` is called. It will also invoke `generate_dsl()`
 with the Hash you give it to create the parsing.
 
+* `entrypoint(Symbol)`
+
+This returns the DSL defined by a previous call to `add_entrypoint()`.
+
+This is primarily useful if you want to take a DSL class and use it within another
+DSL class.
+
 * `generate_dsl(Hash={}, Block)`
 
 This is used in defining your DSL to describe the innards - the guts that actually
@@ -290,14 +300,21 @@ 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_helper(Symbol, Block)`
+
+This is used to create helper methods (similar to `default`, described below) that
+are used within the DSL.
+
+This creates global helpers that are available at every level of your DSLs.
+
 * `parse_dsl(String)` / `execute_dsl(&block)`
 
 You call this on your DSL class when you're ready to invoke your DSL. It will
-return whatever the block provided `add_entrypoint()` returns.
+return whatever the block provided to `add_entrypoint()` returns.
 
 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 of
-invocation.
+these methods will return an array with all the return values in the order they
+were encountered.
 
 ### Coercions
 
@@ -313,18 +330,27 @@ You will be able to add your own coercions in a forthcoming version of DSL::Make
 
 There is one pre-defined helper.
 
-* `default(String, Array, Integer=0)`
+  * `default(String, Array, Integer=0)`
 
 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.
+
 ## Installation
 
 ``` bash
 $ gem install dsl_maker
 ```
 
+## TODO
+
+* Add support for Arrays
+* Add additional coercions (e.g., Number)
+* Allow you to add your own coercions
+
 ## Links
+
 * [Source](https://github.com/robkinyon/ruby-dsl-maker)
 * [Documentation](http://rubydoc.info/gems/ruby-dsl-maker)
 * [Bug Tracker](https://github.com/robkinyon/ruby-dsl-maker/issues)

data/Rakefile

@@ -1,9 +1,10 @@
 require 'rake/clean'
 require 'bundler/gem_tasks'
+require 'rubygems/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__))
+require File.expand_path('on_what', File.dirname(__FILE__))
 
 # Default task for `rake` is to run rspec
 task :default => [:spec]
@@ -14,6 +15,10 @@ RSpec::Core::RakeTask.new
 # Configure `rake clobber` to delete all generated files
 CLOBBER.include('pkg', 'doc', 'coverage', '*.gem')
 
+# Add the gem tasks:
+# :build, :console, :install, :release
+Gem::Tasks.new
+
 if !on_travis? && !on_jruby? && !on_1_8?
   require 'github/markup'
   require 'redcarpet'

data/dsl_maker.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rake', '~> 10'
   s.add_development_dependency 'rspec', '~> 3.0.0', '>= 3.0.0'
   s.add_development_dependency 'simplecov', '~> 0'
+  s.add_development_dependency 'rubygems-tasks', '~> 0'
 
   # To limit needed compatibility with versions of dependencies, only configure
   #   yard doc generation when *not* on Travis, JRuby, or 1.8

data/lib/dsl/maker/version.rb

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

data/lib/dsl/maker.rb

@@ -253,4 +253,16 @@ class DSL::Maker
 
     return @entrypoints[name.to_sym]
   end
+
+  def self.add_helper(name, &block)
+    raise "Block required for add_helper" unless block_given?
+
+    if DSL::Maker::Base.new.respond_to? name.to_sym
+      raise "'#{name.to_s}' is already a helper"
+    end
+
+    DSL::Maker::Base.class_eval do
+      define_method(name.to_sym, &block)
+    end
+  end
 end

data/spec/error_spec.rb

@@ -61,4 +61,29 @@ describe "DSL::Maker validation" do
       dsl_class.entrypoint(:x)
     }.to raise_error("'x' is not an entrypoint")
   end
+
+  it "rejects a helper without a block" do
+    dsl_class = Class.new(DSL::Maker)
+
+    expect {
+      dsl_class.add_helper(:x)
+    }.to raise_error('Block required for add_helper')
+  end
+
+  it "rejects the helper name default" do
+    dsl_class = Class.new(DSL::Maker)
+
+    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) {}
+
+    expect {
+      dsl_class.add_helper(:x) {}
+    }.to raise_error("'x' is already a helper")
+  end
 end

data/spec/helper_spec.rb

@@ -0,0 +1,63 @@
+# This uses a DSL that also provides a set of useful helpers.
+#
+describe "A DSL with helpers" do
+  $Car = Struct.new(:maker, :wheel)
+  $Wheel = Struct.new(:maker, :size)
+
+  it "can add a helper that's useful" do
+    dsl_class = Class.new(DSL::Maker) do
+      add_entrypoint(:car, {
+        :maker => String,
+      }) do
+        $Car.new(maker)
+      end
+
+      add_helper(:transform) do |name|
+        name.upcase
+      end
+    end
+
+    car = dsl_class.parse_dsl("
+      car {
+        maker transform('Honda')
+      }
+    ")
+    expect(car).to be_instance_of($Car)
+    expect(car.maker).to eq('HONDA')
+  end
+
+  # TODO: There is a wart here. We cannot call add_helper() twice in our tests
+  # for the same name even in different specs. The specs should be able to reset
+  # the class, but I'm not sure how.
+  it "adds the helper to every level" do
+    dsl_class = Class.new(DSL::Maker) do
+      add_entrypoint(:car, {
+        :maker => String,
+        :wheel => generate_dsl({
+          :maker => String,
+        }) do
+          $Wheel.new(maker)
+        end
+      }) do
+        $Car.new(maker, wheel)
+      end
+
+      add_helper(:transform2) do |name|
+        name.upcase
+      end
+    end
+
+    car = dsl_class.parse_dsl("
+      car {
+        maker 'Honda'
+        wheel {
+          maker transform2('goodyear')
+        }
+      }
+    ")
+    expect(car).to be_instance_of($Car)
+    expect(car.maker).to eq('Honda')
+    expect(car.wheel).to be_instance_of($Wheel)
+    expect(car.wheel.maker).to eq('GOODYEAR')
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dsl_maker
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Rob Kinyon
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-29 00:00:00.000000000 Z
+date: 2015-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: docile
@@ -78,6 +78,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubygems-tasks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -143,6 +157,7 @@ files:
 - spec/args_spec.rb
 - spec/class_as_subdsl_spec.rb
 - spec/error_spec.rb
+- spec/helper_spec.rb
 - spec/multi_level_spec.rb
 - spec/multiple_invocation_spec.rb
 - spec/single_level_spec.rb