hashblock 0.0.1 → 0.1.0

data/.gitignore

@@ -2,3 +2,4 @@
 .bundle
 Gemfile.lock
 pkg/*
+README.html

data/README

@@ -0,0 +1,46 @@
+Hashblock (tentative name) is a simple gem that converts free form blocks into hashes.
+
+Here's how to use it
+--------------------
+
+    -> parser = Hashblock::Parser.new
+    => #<Hashblock::Parser ...> 
+    -> to_parse = Proc.new do
+         foo :bar
+         ping :pong
+         nest_this do
+           abra :cadabra
+         end
+       end
+    => #<Proc:...>
+    -> parser.parse(to_parse)
+    => {:foo=>:bar, :ping=>:pong, :nest_this=>{:abra=>:cadabra}}
+
+This may be useful if you're creating an acts\_as\_* type plugin, for example. Say you want your users to invoke your plugin thusly:
+
+    acts_as_whizbang do
+      config do
+        whiz :bang
+      end
+      other_config :foo
+    end
+
+Youll want to handle that like this:
+
+    def acts_as_whizbang(&block)
+      @config = Hashblock::Parser.new.parse(block)
+    end
+
+Now, suppose you want the user to also be able to supply options via a Hash:
+
+    def acts_as_whizbang(hash, &block)
+      if block_given?
+        @config = Hashblock::Parser.new.parse(block)
+      else
+        @config = hash
+      end
+    end
+
+This allows users of your plugin to configure acts\_as\_whizbang via a hash, too:
+
+    acts_as_whizbang :config => { :whiz => :bang }, :other_config => :foo

data/Rakefile

@@ -11,6 +11,10 @@ task :console do
   IRB.start
 end
 
+task :markdown do
+  exec "bluecloth README > README.html"
+end
+
 Rake::TestTask.new do |t|
   t.libs << "test"
   t.test_files = FileList['test/*_test.rb']

data/hashblock.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |s|
   s.email       = ["nathanladd@gmail.com"]
   s.homepage    = "http://github.com/ntl"
   s.summary     = %q{Hashblock converts ruby hashes and blocks to friendly config objects}
-  s.description = %q{Sometimes you'll want to allow the user to configure a plugin or some other object via a ruby block where options are specified through method calls.  Hashblock is a tool which converts either a hash or a block into a plain old ruby object that is simple to access and modify.  Hashblock supports deep nesting and even schema definitions to take the pain out of sanity checking your input.}
+  s.description = %q{Sometimes you'll want to allow the user to configure a plugin or some other object via a ruby block where options are specified through method calls.  Hashblock is a tool which converts either a hash or a block into a plain old ruby object that is simple to access and modify.  Hashblock supports deep nesting and collision handling (since a block can contain multiple invokations of the same method)}
 
   s.rubyforge_project = "hashblock"
 
@@ -19,5 +19,6 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
   
+  s.add_development_dependency "bluecloth"
   s.add_development_dependency "shoulda"
 end

data/lib/hashblock/block_evaluator.rb

@@ -0,0 +1,79 @@
+class Hashblock::BlockEvaluator
+  MERGE_STRATEGIES = [:array, :exception, :first_wins, :last_wins]
+  
+  class DuplicateProperty < StandardError ; end
+  
+  def method_missing(sym, *args, &block)
+    #
+    # Setter method, looks like one of the following:
+    #
+    # some_property value
+    # self.some_property = value
+    if args.size == 1
+      if block_given?
+        raise ArgumentError, "Setters may not have blocks supplied"
+      end
+      __set(sym.to_s.chomp("="), args.first)
+    
+    #
+    # Nested block, convert this to a hash and graft it on to self.  Looks
+    # like this:
+    #
+    # some_property do
+    #   some_nested_property true
+    # end
+    elsif args.empty? and block_given?
+      inner = self.class.new(block, @merge_strategy)
+      __set(sym, inner.to_hash)
+    end
+  end
+
+  def initialize(block, merge_strategy)
+    unless block.is_a?(Proc)
+      raise ArgumentError, "Must supply a Proc, not a `#{block.class}'"
+    end
+    
+    @merge_strategy = merge_strategy
+    @properties = {}
+    
+    self.instance_eval(&block)
+  end
+  
+  def to_hash
+    @properties
+  end
+  
+private
+
+  def __merge_property(property_name, existing_value, new_value)
+    case @merge_strategy
+    when :array then
+      if existing_value.instance_variable_get(:@is_merged_property_array)
+        existing_value.push new_value
+      else
+        [existing_value, new_value].tap do |merged_property_array|
+          merged_property_array.instance_variable_set(:@is_merged_property_array,
+           true)
+        end
+      end
+    when :exception then
+      raise DuplicateProperty, "Supplied multiple values for property "\
+       "`#{property_name}'; consider using a different merge strategy or "\
+       "fixing your input"
+    when :first_wins then existing_value
+    when :last_wins then new_value
+    else raise "Uh oh, @merge_strategy has been clobbered"
+    end
+  end
+  
+  def __set(property_name, value)
+    property_name = property_name.to_sym
+    
+    if @properties[property_name]
+      @properties[property_name] = __merge_property(property_name,
+       @properties[property_name], value)
+    else
+      @properties[property_name] = value
+    end
+  end
+end

data/lib/hashblock/parser.rb

@@ -0,0 +1,80 @@
+class Hashblock::Parser
+  DEFAULTS = {
+   :allow_nil => false,
+   :merge_strategy => :exception
+  }
+  
+  attr_reader *DEFAULTS.keys
+  
+  def allow_nil?
+    self.allow_nil
+  end
+  
+  def initialize(*args)
+    @options = {}
+    
+    if args.last.is_a? Hash
+      args.pop.each do |key, value|
+        @options[key.to_sym] = value
+      end
+    end
+    
+    sanitize_options!
+  end
+  
+  def parse(hash_or_block, merge_strategy = nil)
+    merge_strategy ||= self.merge_strategy
+    
+    if hash_or_block.nil? and allow_nil?
+      return nil
+    end
+    
+    hash = case hash_or_block
+    when Proc then self.class.hashify_block(hash_or_block, merge_strategy)
+    when Hash then hash_or_block
+    else
+      class_list = [Proc, Hash]
+      if allow_nil?
+        class_list.unshift(NilClass)
+      end
+      
+      raise ArgumentError, "Cannot parse a `#{hash_or_block.class}'; not one "\
+       "of #{class_list.map(&:to_s).join(', ')}"
+    end
+    
+    hash
+  end
+  
+  def self.hashify_block(block, merge_strategy = DEFAULTS[:merge_strategy])
+    Hashblock::BlockEvaluator.new(block, merge_strategy).to_hash
+  end
+  
+private
+
+  def sanitize_options!
+    unless @options.is_a?(Hash)
+      raise ArgumentError, "Must supply :defaults as a Hash, not a "\
+       "`#{@defaults.class}'"
+    end
+    
+    DEFAULTS.each do |property_name, value|
+      @options[property_name] = value
+    end
+    
+    invalid_options =  (@options.keys - DEFAULTS.keys).map(&:to_s)
+    unless invalid_options.empty?
+      raise ArgumentError, "Invalid option(s): #{invalid_options.join(', ')}"
+    end
+    
+    @options.each do |option_name, value|
+      instance_variable_set("@#{option_name}", value)
+    end
+    
+    valid_strategies = Hashblock::BlockEvaluator::MERGE_STRATEGIES
+    unless valid_strategies.include? merge_strategy
+      strategy_list = valid_strategies.map(&:to_s).join(", ")
+      raise ArgumentError, "Invalid block to hash merge strategy "\
+       "`#{merge_strategy}'; valid strategies are #{strategy_list}"
+    end
+  end
+end

data/lib/hashblock/version.rb

@@ -1,3 +1,3 @@
 module Hashblock
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/test/parser_test.rb

@@ -0,0 +1,135 @@
+require 'test_helper'
+
+class ParserTest < Test::Unit::TestCase
+  include Hashblock
+  
+  context "Parser.new" do
+    should "not exception when passed zero arguments" do
+      assert_nothing_raised do
+        Parser.new
+      end
+    end
+    should "not exception when passed one hash argument" do
+      assert_nothing_raised do
+        Parser.new {}
+      end
+    end
+  end
+  
+  context "Parser#parse" do
+    setup do
+      @parser = Parser.new
+
+      @as_hash = { :foo => :bar, :ping => { :pong => [:abra, :cadabra]} }
+    end
+    
+    context "when passed a Hash" do
+      setup do
+        @returns = @parser.parse(@as_hash)
+      end
+      
+      should "return a deep copy of original hash" do
+        assert_instance_of Hash, @returns
+        assert_equal @as_hash, @returns
+      end
+    end
+    
+    context "when passed a block" do
+      setup do
+        @as_block = Proc.new do
+          foo :bar
+          ping do
+            self.pong = [:abra, :cadabra]
+          end
+        end
+        @returns = @parser.parse(@as_block)
+      end
+      
+      should "return a deep copy of original hash" do
+        assert_instance_of Hash, @returns
+        assert_equal @as_hash, @returns
+      end
+    end
+    
+    context "when passed a block with collisions" do
+      setup do
+        @as_block = Proc.new do
+          inner do
+            foo :bar
+            foo [:biz]
+            foo :baz
+          end
+          self.foo = :bar
+        end
+      end
+      
+      should "raise when merge strategy is :exception" do
+        assert_raises BlockEvaluator::DuplicateProperty do
+          @parser.parse(@as_block, :exception)
+        end
+      end
+      should "select :bar when merge strategy is :first_wins" do
+        assert_equal({
+          :inner => {
+            :foo => :bar
+          },
+          :foo => :bar
+        }, @parser.parse(@as_block, :first_wins))
+      end
+      should "select :baz when merge strategy is :last_wins" do
+        assert_equal({
+          :inner => {
+            :foo => :baz
+          },
+          :foo => :bar
+        }, @parser.parse(@as_block, :last_wins))
+      end
+      should "create an array when merge strategy is :array" do
+        assert_equal({
+          :inner => {
+            :foo => [:bar, [:biz], :baz]
+          },
+          :foo => :bar
+        }, @parser.parse(@as_block, :array))
+      end
+      
+      context "whose first value is an array" do
+        setup do
+          @as_block = Proc.new do
+            inner do
+              foo [:bar]
+              foo :baz
+            end
+            foo :bar
+          end
+        end
+        should "preserve the array when merging into :array" do
+          assert_equal({
+           :inner => { :foo => [[:bar], :baz] },
+           :foo => :bar
+          }, @parser.parse(@as_block, :array))
+        end
+      end
+    end
+    
+    context "when passed a block with accessors on the single argument" do
+      setup do
+        @as_block = Proc.new do |o|
+          o.inner do |x|
+            x.foo = :bar
+            o.ping = :pong
+          end
+          abra :cadabra
+        end
+      end
+      
+      should "injects the properties correctly" do
+        assert_equal({
+          :inner => { :foo => :bar },
+          :ping => :pong,
+          :abra => :cadabra
+        }, @parser.parse(@as_block))
+      end
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+require 'shoulda'
+require 'pp'
+
+require 'hashblock'

metadata

@@ -2,7 +2,7 @@
 name: hashblock
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors: 
 - Nathan Ladd
@@ -13,7 +13,7 @@ cert_chain: []
 date: 2011-07-26 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: shoulda
+  name: bluecloth
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
@@ -23,7 +23,18 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id001
-description: Sometimes you'll want to allow the user to configure a plugin or some other object via a ruby block where options are specified through method calls.  Hashblock is a tool which converts either a hash or a block into a plain old ruby object that is simple to access and modify.  Hashblock supports deep nesting and even schema definitions to take the pain out of sanity checking your input.
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: Sometimes you'll want to allow the user to configure a plugin or some other object via a ruby block where options are specified through method calls.  Hashblock is a tool which converts either a hash or a block into a plain old ruby object that is simple to access and modify.  Hashblock supports deep nesting and collision handling (since a block can contain multiple invokations of the same method)
 email: 
 - nathanladd@gmail.com
 executables: []
@@ -35,10 +46,15 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - Gemfile
+- README
 - Rakefile
 - hashblock.gemspec
 - lib/hashblock.rb
+- lib/hashblock/block_evaluator.rb
+- lib/hashblock/parser.rb
 - lib/hashblock/version.rb
+- test/parser_test.rb
+- test/test_helper.rb
 homepage: http://github.com/ntl
 licenses: []
 
@@ -66,5 +82,6 @@ rubygems_version: 1.8.6
 signing_key: 
 specification_version: 3
 summary: Hashblock converts ruby hashes and blocks to friendly config objects
-test_files: []
-
+test_files: 
+- test/parser_test.rb
+- test/test_helper.rb