iron-extensions 1.1.5 → 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 25e58b7dab82ea9ffef58c5d04ad58ba2d9777c9
+  data.tar.gz: 915e17967decb24e1526328b927f1e562357a01b
+SHA512:
+  metadata.gz: 63b0cbb8e2702a7645818e80e26557221b919998152f2dd0a9724672b1fa94f3d8839f64e932b31d1784d162d88e3fa379dcb7648979930339c2d150b035ab6e
+  data.tar.gz: 916089267edf2c7735e357f2a9a0535202f6f50f1e4e0a7a2fcc6f1fc2c3f40cf4d1b5128de8e4d0909228ff3facbbe5fb87b7be19a859f1ac5ad3c4d20db004

data/History.txt

@@ -1,3 +1,10 @@
+== 1.2.0 / 2015-01-27
+
+* BREAKING CHANGE: removed DslProxy/DslBuilder and the dsl_* accessor helpers and moved them into the iron-dsl gem
+* BREAKING CHANGE: removed deprecated Array#rand and Array#rand! - use #shuffle instead
+* Improved blank? to work on strings containing only whitespace
+* Improved documentation & specs a bit
+
 == 1.1.5 / 2014-03-31
 
 * Fix bug in Enumerable#convert_to_hash where default values (eg hashes) weren't being duplicated

data/README.rdoc

@@ -4,7 +4,9 @@ Written by Rob Morris @ Irongaze Consulting LLC (http://irongaze.com)
 
 == DESCRIPTION
 
-Helpful extensions to core Ruby classes, plus a little sugar for common patterns
+Helpful extensions to core Ruby classes, plus a little sugar for common patterns.  For users of
+version 1.1.x and lower, please note that as of version 1.2.0 the DSL-specific extensions
+have been moved to the iron-dsl gem!
 
 == ADDED EXTENSIONS
 
@@ -12,48 +14,23 @@ Helpful extensions to core Ruby classes, plus a little sugar for common patterns
 
     [1, 2, nil, '', 'count'].list_join # => '1, 2, count'
     
-* Class#dsl_accessor - helpful method for defining accessors on DSL builder-style classes
+* Enumerable#convert_to_hash - convert an array or other enumerable to a hash using a block or constant
 
-    class MyBuilder
-      dsl_accessor :name
-    end
-    builder = MyBuilder.new
-    builder.name 'ProjectX'
-    builder.name  # => 'ProjectX'
-    DslProxy.exec(builder) do
-      name 'Project Omega'
-    end
-    builder.name  # => 'Project Omega'
-    
-* Class#dsl_flag - same as above, but designed for boolean values
-
-    class AnotherBuilder
-      dsl_flag :awesome
-    end
-    
-    builder = AnotherBuilder
-    builder.awesome?  # => false on uninitialized value
-    builder.awesome!  # => sets @awesome to true
-    builder.awesome true  # ditto, same style as dsl_accessor above
-
-* Enumerable#to_hash - convert an array or other enumerable to a hash using a block or constant
-
-    [:frog, :pig].to_hash {|n| n.to_s.capitalize} # => {:frog => 'Frog', :pig => 'Pig'}
-    [:frog, :pig].to_hash(nil) # => {:frog => nil, :pig => nil}
+    [:frog, :pig].convert_to_hash {|n| n.to_s.capitalize} # => {:frog => 'Frog', :pig => 'Pig'}
+    [:frog, :pig].convert_to_hash(nil) # => {:frog => nil, :pig => nil}
 
 * Enumerable#delete_unless - equivalent to delete_if but with inverted test
 
     [1,2,3,4,5].delete_unless(&:odd?) # => [1,3,5]
     
-* File.replace - atomic replacement of a file given a block to generate it
+* File.safe_replace - atomic replacement of a file given a block to generate it
 
     # Defers deleting old file until block completes successfully (ie no exceptions), then
     # moves the new file into the old file's location
-    File.replace('./config') do |file|
+    File.safe_replace('./config') do |file|
       file.write("PRODUCTION: true")
     end
     
-* Fixnum#blank? - always false
 * Fixnum#to_human_size - size to MB/GB/whatever, adapted from Rails
 
     123456.to_human_size # => "120.5 KB"
@@ -75,7 +52,7 @@ Helpful extensions to core Ruby classes, plus a little sugar for common patterns
     
 * Nil#blank? - always true
 
-* Numeric#to_display - pretty display of numbers with options for number of decimal places and inclusion of thousands separator
+* Numeric#to_display - pretty display of numbers with options for number of decimal places and inclusion of thousands separator (US-only, sorry!)
 
     5000.to_display          # => 5,000
     100.to_display(2)        # => 100.00
@@ -97,8 +74,8 @@ Helpful extensions to core Ruby classes, plus a little sugar for common patterns
 * Regexp::IP_ADDRESS, Regexp::EMAIL_ADDRESS, Regexp::DOMAIN - commonly useful regexen
 
 * String#blank? - true if empty?
-* String#append / String#prepend - this should be in Ruby core
-* String#to_date - "better" date parser than Date.parse
+* String#append / String#prepend - these should be in Ruby core
+* String#to_date - "better" date parser than Date.parse (US-centric)
 * String#to_dashcase - perfect for permalinks!
 * String#smart_truncate - truncate honoring word boundaries
 * String#integer? - true when string represents an integer
@@ -110,22 +87,6 @@ Helpful extensions to core Ruby classes, plus a little sugar for common patterns
 * Symbol#blank? - always false
 * Symbol#to_dashcase - same as for String
 
-== ADDED CLASSES/MODULES
-
-* DslProxy - a cool and sexy way to make powerful DSLs (domain-specific languages) look easy - see the docs for details
-
-    # DslProxy makes this code possible:
-    @items = ['one', 'two']
-    Console.out do
-      # No explicit receiver for DSL method calls
-      p 'Item List'
-      hr
-      indent do
-        # Even nested, local variables are still available
-        @items.each {|item| p item }
-      end
-    end
-
 == SYNOPSIS
 
 To use:

data/Version.txt

@@ -1 +1 @@
-1.1.5
+1.2.0

data/lib/iron/extensions/array.rb

@@ -1,17 +1,5 @@
 class Array
   
-  # DEPRECATED: as of Ruby 1.9, you should use Array#sample instead
-  def rand(count = 1)
-    warn("[DEPRECATION] Array#rand is deprecated - use Array#sample instead")
-    shuffle[0...count]
-  end
-
-  # DEPRECATED: as of Ruby 1.9, you should use Array#sample instead
-  def rand!(count = 1)
-    warn("[DEPRECATION] Array#rand is deprecated - use Array#sample instead")
-    self.replace rand(count)
-  end
-
   # Join an array's values ignoring blank entries
   def list_join(sep = ', ')
     self.select{|e| !e.blank?}.join(sep)

data/lib/iron/extensions/enumerable.rb

@@ -16,4 +16,8 @@ module Enumerable
     delete_if {|*args| !block.call(*args)}
   end
   
+  def blank?
+    empty?
+  end
+  
 end

data/lib/iron/extensions/fixnum.rb

@@ -21,8 +21,4 @@ class Fixnum
     nil
   end
   
-  def blank?
-    false
-  end
-  
 end

data/lib/iron/extensions/object.rb

@@ -5,4 +5,8 @@ class Object
     enum.include?(self)
   end
   
+  def blank?
+    false
+  end
+  
 end

data/lib/iron/extensions/string.rb

@@ -4,7 +4,7 @@ class String
 
   # Provide helper for nil/"" blankness checker
   def blank?
-    empty?
+    self.strip.empty?
   end
 
   def prepend(str)

data/lib/iron/extensions/symbol.rb

@@ -1,10 +1,5 @@
 class Symbol
 
-  # Provide helper for nil/"" blankness checker
-  def blank?
-    false
-  end
-
   def to_dashcase
     self.to_s.to_dashcase
   end

data/spec/extensions/enumerable_spec.rb

@@ -31,4 +31,11 @@ describe Enumerable do
     h.should == {:c => 12}
   end
 
+  it 'should be appropriately empty' do
+    [].blank?.should be_true
+    {}.blank?.should be_true
+    [1].blank?.should be_false
+    {:a => 2}.blank?.should be_false
+  end
+
 end

data/spec/extensions/object_spec.rb

@@ -7,4 +7,8 @@ describe Object do
     :b.in?([:a, :b, :c]).should == true
   end
 
+  it 'should not be blank' do
+    Object.new.should_not be_blank
+  end
+
 end

data/spec/extensions/string_spec.rb

@@ -78,5 +78,11 @@ describe String do
   it 'should support natural ordering' do
     ['a0', 'a90', 'a10', 'a9'].sort_by {|a| a.natural_order}.should == ['a0', 'a9', 'a10', 'a90']
   end
+  
+  it 'should be appropriately blank' do
+    [nil, '', '  ', "\t", "\n"].each do |test|
+      test.should be_blank
+    end
+  end
 
 end

metadata

@@ -1,30 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: iron-extensions
 version: !ruby/object:Gem::Version
-  version: 1.1.5
-  prerelease: 
+  version: 1.2.0
 platform: ruby
 authors:
 - Rob Morris
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-31 00:00:00.000000000 Z
+date: 2015-01-28 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.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.6'
 description: Adds common extensions to core Ruby classes
@@ -34,10 +31,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".rspec"
+- History.txt
+- LICENSE
+- README.rdoc
+- Version.txt
+- lib/iron/extensions.rb
 - lib/iron/extensions/array.rb
-- lib/iron/extensions/class.rb
-- lib/iron/extensions/dsl_builder.rb
-- lib/iron/extensions/dsl_proxy.rb
 - lib/iron/extensions/enumerable.rb
 - lib/iron/extensions/file.rb
 - lib/iron/extensions/fixnum.rb
@@ -50,10 +50,7 @@ files:
 - lib/iron/extensions/regexp.rb
 - lib/iron/extensions/string.rb
 - lib/iron/extensions/symbol.rb
-- lib/iron/extensions.rb
 - spec/extensions/array_spec.rb
-- spec/extensions/dsl_builder_spec.rb
-- spec/extensions/dsl_proxy_spec.rb
 - spec/extensions/enumerable_spec.rb
 - spec/extensions/kernel_spec.rb
 - spec/extensions/numeric_spec.rb
@@ -61,34 +58,28 @@ files:
 - spec/extensions/string_spec.rb
 - spec/extensions/symbol_spec.rb
 - spec/spec_helper.rb
-- LICENSE
-- History.txt
-- Version.txt
-- README.rdoc
-- .rspec
 homepage: https://github.com/irongaze/iron-extensions
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 2.4.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Extensions to core classes
 test_files: []

data/lib/iron/extensions/class.rb

@@ -1,46 +0,0 @@
-class Class
-  
-  # Provides a DSL-friendly way to set values.  Similar to attr_accessor, but
-  # supports setting values like so:
-  #
-  #   class Widget
-  #     dsl_accessor :size
-  #   end
-  #   @w = Widget.new
-  #   @w.size = 5  # normal setter, same as...
-  #   @w.size 5    # note the lack of explicit = sign
-  #   puts @w.size # still get reader access
-  #
-  # Useful in DslProxy blocks:
-  #
-  #   DslProxy.exec(Widget.new) do
-  #     size 10    # sets size to 10, as expected
-  #     size = 10  # fails, creates local variable 'size' instead of invoking Widget#size
-  #   end
-  #
-  def dsl_accessor(*keys)
-    keys.each do |key|
-      class_eval "def #{key}(val = :__UNDEFINED); @#{key} = val unless val == :__UNDEFINED; @#{key}; end"
-      class_eval "def #{key}=(val); @#{key} = val; end"
-    end
-  end
-  
-  # Like #dsl_accessor, but adds imperative and query versions of the keys as well to set the
-  # flag to true and to query the true-ness of the flag.
-  #
-  #   class Widget
-  #     dsl_flag :heavy
-  #   end
-  #   @w = Widget.new
-  #   @w.heavy?  # => false
-  #   @w.heavy!  # now is true
-  #
-  def dsl_flag(*keys)
-    dsl_accessor(*keys)
-    keys.each do |key|
-      class_eval "def #{key}!; @#{key} = true; end"
-      class_eval "def #{key}?; @#{key} === true; end"
-    end
-  end
-  
-end

data/lib/iron/extensions/dsl_builder.rb

@@ -1,14 +0,0 @@
-# Provides a base class for building DSL (domain specific language) builder
-# classes, ie classes that define a minimal subset of methods and act as aggregators
-# of settings or functionality.  Similar to BasicObject in the standard library, but
-# has methods such as respond_to? and send that are required for any real DSL building
-# effort.
-class DslBuilder < Object
-  
-  # Remove all methods not explicitly desired
-  instance_methods.each do |m|
-    keepers = [:inspect, :send]
-    undef_method m if m =~ /^[a-z]+[0-9]?$/ && !keepers.include?(m)
-  end
-  
-end

data/lib/iron/extensions/dsl_proxy.rb

@@ -1,176 +0,0 @@
-# Specialty helper class for building elegant DSLs (domain-specific languages)
-# The purpose of the class is to allow seamless DSL's by allowing execution
-# of blocks with the instance variables of the calling context preserved, but
-# all method calls proxied to a given receiver.  This sounds pretty abstract,
-# so here's an example:
-# 
-#   class ControlBuilder
-#     def initialize; @controls = []; end
-#     def control_list; @controls; end
-#     def knob; @controls << :knob; end
-#     def button; @controls << :button; end
-#     def switch; @controls << :switch; end
-#     def self.define(&block)
-#       @builder = self.new
-#       DslProxy.exec(@builder, &block)
-#       # Do something here with the builder's list of controls
-#       @builder.control_list
-#     end
-#   end
-#
-#   @knob_count = 5
-#   new_list = ControlBuilder.define do
-#     switch
-#     @knob_count.times { knob }
-#     button
-#   end
-#
-# Notice the lack of explicit builder receiver to the calls to #switch, #knob and #button.
-# Those calls are automatically proxied to the receiver we passed to the DslProxy.
-#
-# In quick and dirty DSLs, like Rails' migrations, you end up with a lot of
-# pointless receiver declarations for each method call, like so:
-#
-#   def change
-#     create_table do |t|
-#       t.integer :counter
-#       t.text :title
-#       t.text :desc
-#       # ... tired of typing "t." yet? ...
-#     end
-#   end
-#
-# This is not a big deal if you're using a simple DSL, but when you have multiple nested
-# builders going on at once, it is ugly, pointless, and can cause bugs when
-# the throwaway arg names you choose (eg 't' above) overlap in scope.
-# 
-# In addition, simply using a yield statment loses the instance variables set in the calling
-# context.  This is a major pain in eg Rails views, where most of the interesting
-# data resides in instance variables.  You can get around this when #yield-ing by
-# explicitly creating a local variable to be picked up by the closure created in the
-# block, but it kind of sucks.
-# 
-# In summary, DslProxy allows you to keep all the local and instance variable context
-# from your block declarations, while proxying all method calls to a given
-# receiver.  If you're not building DSLs, this class is not for you, but if you are,
-# I hope it helps!
-class DslProxy < BasicObject
-  
-  # Pass in a builder-style class, or other receiver you want set as "self" within the
-  # block, and off you go.  The passed block will be executed with all
-  # block-context local and instance variables available, but with all
-  # method calls sent to the receiver you pass in.  The block's result will
-  # be returned.  
-  #
-  # If the receiver doesn't respond_to? a method, any missing methods
-  # will be proxied to the enclosing context.
-  def self.exec(receiver, *to_yield, &block) # :yields: receiver
-    # Find the context within which the block was defined
-    context = ::Kernel.eval('self', block.binding)
-
-    # Create or re-use our proxy object
-    if context.respond_to?(:_to_dsl_proxy)
-      # If we're nested, we don't want/need a new dsl proxy, just re-use the existing one
-      proxy = context._to_dsl_proxy
-    else
-      # Not nested, create a new proxy for our use
-      proxy = DslProxy.new(context)
-    end
-
-    # Exec the block and return the result
-    proxy._proxy(receiver, *to_yield, &block)
-  end
-  
-  # Simple state setup
-  def initialize(context)
-    @_receivers = []
-    @_instance_original_values = {}
-    @_context = context
-  end
-  
-  def _proxy(receiver, *to_yield, &block) # :yields: receiver
-    # Sanity!
-    raise 'Cannot proxy with a DslProxy as receiver!' if receiver.respond_to?(:_to_dsl_proxy)
-    
-    if @_receivers.empty?
-      # On first proxy call, run each context instance variable, 
-      # and set it to ourselves so we can proxy it
-      @_context.instance_variables.each do |var|
-        unless var.starts_with?('@_')
-          value = @_context.instance_variable_get(var.to_s)
-          @_instance_original_values[var] = value
-          instance_eval "#{var} = value"
-        end
-      end
-    end
-
-    # Save the dsl target as our receiver for proxying
-    _push_receiver(receiver)
-
-    # Run the block with ourselves as the new "self", passing the given yieldable(s) or
-    # the receiver in case the code wants to disambiguate for some reason
-    to_yield = [receiver] if to_yield.empty?
-    to_yield = to_yield.first(block.arity)
-    result = instance_exec(*to_yield, &block)
-    
-    # Pop the last receiver off the stack
-    _pop_receiver
-    
-    if @_receivers.empty?
-      # Run each local instance variable and re-set it back to the context if it has changed during execution
-      #instance_variables.each do |var|
-      @_context.instance_variables.each do |var|
-        unless var.starts_with?('@_')
-          value = instance_eval("#{var}")
-          if @_instance_original_values[var] != value
-            @_context.instance_variable_set(var.to_s, value)
-          end
-        end
-      end
-    end
-    
-    return result
-  end
-  
-  # For nesting multiple proxies
-  def _to_dsl_proxy
-    self
-  end
-  
-  # Set the currently active receiver
-  def _push_receiver(receiver)
-    @_receivers.push receiver
-  end
-  
-  # Remove the currently active receiver, restore old receiver if nested
-  def _pop_receiver
-    @_receivers.pop
-  end
-
-  # Proxies all calls to our receiver, or to the block's context
-  # if the receiver doesn't respond_to? it.
-  def method_missing(method, *args, &block)
-    #$stderr.puts "Method missing: #{method}"
-    if @_receivers.last.respond_to?(method)
-      #$stderr.puts "Proxy [#{method}] to receiver"
-      @_receivers.last.__send__(method, *args, &block)
-    else
-      #$stderr.puts "Proxy [#{method}] to context"
-      @_context.__send__(method, *args, &block)
-    end
-  end
-  
-  # Let anyone who's interested know what our proxied objects will accept
-  def respond_to?(method, include_private = false)
-    return true if method == :_to_dsl_proxy
-    @_receivers.last.respond_to?(method, include_private) || @_context.respond_to?(method, include_private)
-  end
-  
-  # Proxies searching for constants to the context, so that eg Kernel::foo can actually
-  # find Kernel - BasicObject does not partake in the global scope!
-  def self.const_missing(name)
-    #$stderr.puts "Constant missing: #{name} - proxy to context"
-    @_context.class.const_get(name)
-  end
-  
-end

data/spec/extensions/dsl_builder_spec.rb

@@ -1,29 +0,0 @@
-describe DslBuilder do
-
-  # TODO: break this out a bit...
-  it 'should allow using DSL-style accessors' do
-    class MyBuilder < DslBuilder
-      dsl_accessor :name
-      dsl_flag :flagged
-    end
-    builder = MyBuilder.new
-
-    # Test standalone
-    builder.name 'ProjectX'
-    builder.name.should == 'ProjectX'
-    
-    builder.flagged?.should be_false
-    builder.flagged = true
-    builder.flagged?.should be_true
-    builder.flagged = false
-    
-    # Test as part of DslProxy usage (common case)
-    DslProxy.exec(builder) do
-      name 'Project Omega'
-      flagged!
-    end
-    builder.name.should == 'Project Omega'
-    builder.flagged?.should be_true
-  end
-  
-end

data/spec/extensions/dsl_proxy_spec.rb

@@ -1,110 +0,0 @@
-describe DslProxy do
-
-  # Sample DSL builder class for use in testing
-  class ControlBuilder
-    def initialize; @controls = []; end
-    def controls; @controls; end
-    def knob; @controls << :knob; end
-    def button; @controls << :button; end
-    def switch; @controls << :switch; end
-
-    def self.define(&block)
-      @builder = self.new
-      DslProxy.exec(@builder, &block)
-      @builder.controls
-    end
-  end
-  
-  it 'should proxy calls to the receiver' do
-    receiver = Object.new
-    DslProxy.exec(receiver) do
-      self.class.name.should == 'Object'
-    end
-  end
-  
-  it 'should proxy respond_to? to the receiver' do
-    receiver = ControlBuilder.new
-    DslProxy.exec(receiver) do
-      respond_to?(:garbaz).should == false
-      respond_to?(:button).should == true
-    end
-  end
-  
-  it 'should proxy local variables from the binding context' do
-    @foo = 'bar'
-    DslProxy.exec(Object.new) do
-      @foo.should == 'bar'
-    end
-  end
-
-  it 'should propagate local variable changes back to the binding context' do
-    @foo = 'bar'
-    DslProxy.exec(Object.new) do
-      @foo = 'no bar!'
-    end
-    @foo.should == 'no bar!'
-  end
-  
-  it 'should proxy missing methods on the receiver to the calling context' do
-    class TestContext
-      def bar
-        'something'
-      end
-      
-      def test
-        DslProxy.exec(Object.new) do
-          bar
-        end
-      end
-    end
-    
-    TestContext.new.test.should == 'something'
-  end
-
-  it 'should return the result of the block' do
-    res = DslProxy.exec(Object.new) do
-      'foo'
-    end
-    res.should == 'foo'
-  end
-
-  it 'should allow access to global constants' do
-    DslProxy.exec(self) do # Use self here, so #be_a is defined.  :-)
-      Object.new.should be_a(Object)
-    end
-  end
-  
-  it 'should proxy correctly even when nested' do
-    def outerfunc
-      5
-    end
-    @instance_var = nil
-    local_var = nil
-    DslProxy.exec(self) do
-      DslProxy.exec(Object.new) do
-        outerfunc.should == 5
-        @instance_var.should be_nil
-        local_var.should be_nil
-        @instance_var = 10
-        local_var = 11
-      end
-    end
-    @instance_var.should == 10
-    local_var.should == 11
-  end
-  
-  it 'should pass additional args to block as argument' do
-    l = lambda {|arg1, arg2| arg1 + arg2}
-    DslProxy.exec(Object.new, 5, 1, &l).should == 6
-  end
-  
-  it 'should put it all together' do
-    @knob_count = 5
-    controls = ControlBuilder.define do
-      switch
-      @knob_count.times { knob }
-    end
-    controls.count.should == 6
-  end
-  
-end