config_leaf 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.idea

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Bil Bas (Spooner)
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,86 @@
+ConfigLeaf
+==========
+
+ConfigLeaf allows an object to be configured using a terse syntax
+like Object#instance_eval, while not exposing the internals 
+(protected/private methods and ivars) of the object!
+
+If the user doesn't like to use this ConfigLeaf wrapping, then they
+can just use normal #tap syntax by requesting a block parameter.
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+    gem 'config_leaf'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install config_leaf
+
+Usage
+-----
+
+ConfigLeaf can be used directly by the end-user after an object has been created,
+but it more likely used by those wanting to allow block setting of config after
+their object has been instantiated:
+
+    require 'config_leaf'
+    
+    class Cheese
+      attr_accessor :value, :list
+      
+      def initialize(&block)
+        # Set defaults.
+        @value = 0
+        @list = []
+
+        # Allow the user access via ConfigLeaf syntax.
+        ConfigLeaf.wrap object, &block if block_given?
+      end
+
+      def reverse!
+        @list.reverse!
+      end
+      
+      protected
+      def explode!
+        DeathStar.instance.boom!
+      end
+    end
+
+    # User uses the ConfigLeaf block.
+    object = Cheese.new do
+      list [1, 2, 3]      # Calls object.list = [1, 2, 3]
+      list << 4           # Calls object.list << 4
+      value 5             # Calls object.value = 5
+      value list.size     # Calls object.value = object.list.size
+      reverse!            # Calls object.reverse!
+      
+      # These would be possible if using instance_eval, but not here.
+      #explode!           # Not allowed because it is protected (raises an exception).
+      #@value = 5         # Would set @value on the wrapper, not in the wrapped object, so has no effect.
+    end
+
+    # User chooses to not use ConfigLeaf block syntax by requesting a block parameter.
+    object = Cheese.new do |c|
+      c.list = [1, 2, 3]
+      c.list << 4
+      c.value = 5
+      c.value = c.list.size
+      c.reverse!
+    end
+
+Contributing
+------------
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,19 @@
+#!/usr/bin/env rake
+require 'bundler/setup'
+
+require 'bundler/gem_tasks'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rspec/core/rake_task'
+
+CLOBBER.include('doc/**/*')
+
+desc 'Generate Yard docs.'
+task :yard do
+  system 'yard doc lib'
+end
+
+RSpec::Core::RakeTask.new do
+end
+
+task :default => :spec

data/config_leaf.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/config_leaf/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Bil Bas (Spooner)"]
+  gem.email         = ["bil.bagpuss@gmail.com"]
+  gem.description   = <<END
+ConfigLeaf allows an object to be configured using a terse syntax
+like Object#instance_eval, while not exposing the internals
+(protected/private methods and ivars) of the object!
+END
+  gem.summary       = %q{Terse configuration syntax for objects}
+  gem.homepage      = "https://github.com/spooner/config_leaf"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "config_leaf"
+  gem.require_paths = ["lib"]
+  gem.version       = ConfigLeaf::VERSION
+
+  gem.add_development_dependency "rspec", "~> 2.11.0"
+  gem.add_development_dependency "rr", "~> 1.0.4"
+  gem.add_development_dependency "yard", "~> 0.8.3"
+  gem.add_development_dependency "redcarpet", "~> 2.1.1"
+  gem.add_development_dependency "rake"
+end

data/lib/config_leaf/version.rb

@@ -0,0 +1,3 @@
+module ConfigLeaf
+  VERSION = "0.0.1"
+end

data/lib/config_leaf/wrapper.rb

@@ -0,0 +1,47 @@
+module ConfigLeaf
+
+  class Wrapper
+    # @return [Object] Object that the Wrapper object is redirecting to.
+    attr_reader :_owner
+
+    class << self
+      # Synonym for .new.
+      alias_method :wrap, :new
+    end
+
+    # If passed a block, the DSLWrapper will #instance_eval it automatically.
+    #
+    # @param owner [Object] Object to redirect the public methods of.
+    def initialize(owner, &block)
+      @_owner = owner
+
+      metaclass = class << self; self; end
+
+      (@_owner.public_methods - Object.public_instance_methods).each do |target_method|
+        redirection_method = target_method.to_s.chomp('=').to_sym
+
+        metaclass.class_eval do
+          define_method redirection_method do |*args, &inner_block|
+            if @_owner.respond_to? "#{redirection_method}=" and (args.any? or not @_owner.respond_to? redirection_method)
+              # Has a setter and we are passing argument(s) or if we haven't got a corresponding getter.
+              @_owner.send "#{redirection_method}=", *args, &inner_block
+            elsif @_owner.respond_to? redirection_method
+              # We have a getter or general method
+              @_owner.send redirection_method, *args, &inner_block
+            else
+              # Should never reach here, but let's be paranoid.
+              raise NoMethodError, "#{@_owner} does not have a public method, ##{redirection_method}"
+            end
+          end
+        end
+      end
+
+      instance_eval &block if block_given?
+    end
+
+    private
+    def method_missing(meth, *args, &block)
+      raise NoMethodError, "#{_owner} does not have either public method, ##{meth} or ##{meth}="
+    end
+  end
+end

data/lib/config_leaf.rb

@@ -0,0 +1,82 @@
+require 'config_leaf/version'
+require 'config_leaf/wrapper'
+
+module ConfigLeaf
+  class << self
+    # Wraps an object and redirects public methods to it, to allow for a terse, block-based API.
+    #
+    # * Safer alternative to running Object#instance_eval directly, since protected/private methods and instance variables are not exposed.
+    # * Less wordy than a system which operates like Object#tap (`object.tap {|o| o.fish = 5; o.run }`)
+    #
+    # A method call, #meth called on the wrapper will try to call #meth or #meth= on the owner, as appropriate.
+    #
+    # @example Using ConfigLeaf to configure an object externally.
+    #     # To create a DSL block for a given object.
+    #     class Cheese
+    #       attr_accessor :value, :list
+    #
+    #       def initialize
+    #         @value = 0
+    #         @list = []
+    #       end
+    #
+    #       def invert
+    #         @list.reverse!
+    #       end
+    #     end
+    #
+    #     object = Cheese.new
+    #     ConfigLeaf.wrap object do
+    #       list [1, 2, 3]      # Calls object.list = [1, 2, 3]
+    #       list << 4           # Calls object.list << 4
+    #       value 5             # Calls object.value = 5
+    #       value list.size     # Calls object.value = object.list.size
+    #       invert              # Calls object.invert
+    #     end
+    #
+    # @example Allowing the user to configure the object externally.
+    #     # To create a DSL block for a given object.
+    #     class Cheese
+    #       attr_accessor :value, :list
+    #
+    #       def initialize(&block)
+    #         @value = 0
+    #         @list = []
+    #
+    #         ConfigLeaf.wrap object, &block if block_given?
+    #       end
+    #
+    #       def invert
+    #         @list.reverse!
+    #       end
+    #     end
+    #
+    #     # User chooses to use the ConfigLeaf block syntax.
+    #     object = Cheese.new do
+    #       list [1, 2, 3]      # Calls object.list = [1, 2, 3]
+    #       list << 4           # Calls object.list << 4
+    #       value 5             # Calls object.value = 5
+    #       value list.size     # Calls object.value = object.list.size
+    #       invert              # Calls object.invert
+    #     end
+    #
+    #    # User chooses to not use ConfigLeaf block syntax by requesting a block parameter.
+    #    object = Cheese.new do |c|
+    #       c.list = [1, 2, 3]
+    #       c.list << 4
+    #       c.value = 5
+    #       c.value = c.list.size
+    #       c.invert
+    #     end
+    #
+    def wrap(object, &block)
+      raise ArgumentError, "block is required" unless block_given?
+
+      if block.arity == 0 # e.g. { }
+        Wrapper.wrap object, &block
+      else                # e.g. {|me| }
+        block.call object
+      end
+    end
+  end
+end

data/spec/config_leaf/config_leaf_spec.rb

@@ -0,0 +1,45 @@
+require File.expand_path("../../teststrap", __FILE__)
+
+describe ConfigLeaf do
+  describe ".wrap" do
+    it "should fail without a block" do
+      lambda { ConfigLeaf.wrap Object.new }.should raise_error ArgumentError, "block is required"
+    end
+
+    context "without block arguments" do
+      it "should alter the context to that of the wrapper within the block" do
+        passed = nil
+        ConfigLeaf.wrap Object.new do
+          passed = self
+        end
+        passed.should be_kind_of ConfigLeaf::Wrapper
+      end
+    end
+
+    context "with block arguments" do
+      it "should pass object into the block" do
+        object = Object.new
+        passed = nil
+
+        ConfigLeaf.wrap object do |x|
+          passed = x
+        end
+
+        passed.should eq object
+      end
+
+      it "should not alter the context in the block" do
+        object = Object.new
+        block_self = nil
+        original_self = self
+
+        ConfigLeaf.wrap object do |x|
+          block_self = self
+        end
+
+        # Use id or the two rspec contexts will barf.
+        original_self.__id__.should eq block_self.__id__
+      end
+    end
+  end
+end

data/spec/config_leaf/wrapper_spec.rb

@@ -0,0 +1,110 @@
+require File.expand_path("../../teststrap", __FILE__)
+
+class Owner
+  def frog; end
+  def fish; end
+  def fish=(fish); end
+  def knees=(knees); end
+  def add_cheese(a, b); end
+  def add_peas(a, &block); end
+
+  protected
+  def wibble; end
+end
+
+describe ConfigLeaf::Wrapper do
+  let(:owner) { Owner.new }
+  let(:subject) { described_class.wrap owner }
+
+  let :expected_methods do
+    methods = [:frog, :fish, :add_cheese, :_owner, :add_peas, :knees]
+    methods.map! &:to_s if RUBY_VERSION =~ /^1\.8\./
+    methods
+  end
+
+  describe "#public_methods" do
+    it "should be the same as the owner's + #_owner" do
+      subject.public_methods(false).sort.should eq expected_methods.sort
+    end
+  end
+  
+  describe "#_owner" do
+    it "should be set to the owner of the wrapper" do
+      subject._owner.should eq owner
+    end
+  end
+  
+  context "dynamic method redirection" do
+    it "a method that doesn't exist on the wrapped object should fail" do
+      lambda { subject.wobble }.should raise_error NoMethodError, /<Owner:0x\w+> does not have either public method, #wobble or #wobble=/
+    end
+
+    it "a protected method on the wrapped object should not be accessible" do
+      lambda { subject.wibble }.should raise_error NoMethodError, /<Owner:0x\w+> does not have either public method, #wibble or #wibble=/
+    end
+
+    it "redirect to a setter, that has no corresponding getter, even if no arguments are passed" do
+      lambda { subject.knees }.should raise_error ArgumentError
+    end
+
+    it "redirect to a getter, that has no corresponding setter, even if arguments are passed" do
+      lambda { subject.frog 25 }.should raise_error ArgumentError
+    end
+
+    it "redirect a getter (that has no corresponding setter)" do
+      mock(owner, :frog).returns 5
+      subject.frog.should eq 5
+    end
+
+    it "redirect a setter (that has no corresponding getter)" do
+      mock(owner, :knees=).with(1).returns(5)
+      subject.knees(1).should eq 5
+    end
+
+    it "redirect a getter (that has a corresponding setter)" do
+      mock(owner, :fish).returns(5)
+      subject.fish.should eq 5
+    end
+
+    it "redirect a setter (that has a corresponding getter)" do
+      mock(owner, :fish=).with(5).returns(5)
+      subject.fish(5).should eq 5
+    end
+
+    it "redirect a setter (that has a corresponding getter)" do
+      mock(owner).add_cheese(1, 2).returns(99)
+      subject.add_cheese(1, 2).should eq 99
+    end
+
+    it "should redirect a block as well as pass arguments" do
+      mock(owner).add_peas(1).yields(:knees)
+
+      yielded = nil
+      subject.add_peas(1) do |arg|
+        yielded = arg
+      end
+
+      yielded.should eq :knees
+    end
+  end
+
+  describe "" do
+    it "should instance_eval when given a block on the constructor (.new)" do
+      mock(owner).frog(5)
+
+      ConfigLeaf::Wrapper.new owner do
+        frog 5
+      end
+    end
+  end
+
+  describe ".wrap" do
+    it "should be an alias for .new" do
+      described_class.wrap(owner).should be_kind_of described_class
+    end
+
+    it "should be an alias for .new given a block" do
+      described_class.wrap(owner) {}.should be_kind_of described_class
+    end
+  end
+end

data/spec/teststrap.rb

@@ -0,0 +1,8 @@
+require 'rspec/autorun'
+require 'rr'
+
+RSpec.configure do |config|
+  config.mock_framework = :rr
+end
+
+require File.expand_path('../../lib/config_leaf', __FILE__)

metadata

@@ -0,0 +1,153 @@
+--- !ruby/object:Gem::Specification
+name: config_leaf
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Bil Bas (Spooner)
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+- !ruby/object:Gem::Dependency
+  name: rr
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.4
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.3
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.1.1
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! 'ConfigLeaf allows an object to be configured using a terse syntax
+
+  like Object#instance_eval, while not exposing the internals
+
+  (protected/private methods and ivars) of the object!
+
+'
+email:
+- bil.bagpuss@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- config_leaf.gemspec
+- lib/config_leaf.rb
+- lib/config_leaf/version.rb
+- lib/config_leaf/wrapper.rb
+- spec/config_leaf/config_leaf_spec.rb
+- spec/config_leaf/wrapper_spec.rb
+- spec/teststrap.rb
+homepage: https://github.com/spooner/config_leaf
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 196843955
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 196843955
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Terse configuration syntax for objects
+test_files:
+- spec/config_leaf/config_leaf_spec.rb
+- spec/config_leaf/wrapper_spec.rb
+- spec/teststrap.rb
+has_rdoc: