iron-extensions 1.1.2 → 1.1.3

data/History.txt

@@ -1,3 +1,12 @@
+== 1.1.3 / 2013-09-04
+
+* Flesh out DslProxy#exec to allow specifying one or more yielded values
+* Add #dsl_flag as class method to better support boolean attributes in DSLs
+* Tweak Fixnum#to_human_size to correct some minor issues with output formatting
+* Remove Array#shuffle and Array#shuffle! as they are core methods as of Ruby 1.8.7
+* Deprecate Array#rand and Array#rand! in favor of the core Array#sample method
+* Improve spec coverage and commenting
+
 == 1.1.2 / 2012-03-30
 
 * Rename Enumerable#to_hash to #convert_to_hash to resolve ActiveRecord conflict

data/README.rdoc

@@ -8,14 +8,6 @@ Helpful extensions to core Ruby classes, plus a little sugar for common patterns
 
 == ADDED EXTENSIONS
 
-* Array#rand / Array#rand! - pull n random items from the array
-
-    [1,2,3,4,5].rand(2) # => [2, 5]
-
-* Array#shuffle / Array#shuffle! - randomly reorder the array
-
-    [1,2,3,4,5].shuffle # => [2,4,1,5,3]
-    
 * Array#list_join - join as a list, ignoring blank/nil entries
 
     [1, 2, nil, '', 'count'].list_join # => '1, 2, count'
@@ -32,6 +24,17 @@ Helpful extensions to core Ruby classes, plus a little sugar for common patterns
       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
 
@@ -47,7 +50,7 @@ Helpful extensions to core Ruby classes, plus a little sugar for common patterns
     end
     
 * Fixnum#blank? - always false
-* Fixnum#to_human_size - size to MB/GB/whatever, lifted from Rails
+* Fixnum#to_human_size - size to MB/GB/whatever, adapted from Rails
 
     123456.to_human_size # => "120.5 KB"
 
@@ -68,6 +71,12 @@ 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
+
+    5000.to_display          # => 5,000
+    100.to_display(2)        # => 100.00
+    2105.2348.to_display(2)  # => 2,105.23
+    
 * Numeric#bound - bound a given number to a range
 
     4.bound(5,10) # => 5
@@ -134,3 +143,7 @@ To install, simply run:
 RVM users should drop the 'sudo':
 
     gem install iron-extensions
+    
+Then simply require the library:
+
+    require 'iron/extensions'

data/Version.txt

@@ -1 +1 @@
-1.1.2
+1.1.3

data/lib/iron/extensions/array.rb

@@ -1,24 +1,20 @@
-
 class Array
-  unless [].respond_to?(:shuffle)
-    def shuffle
-      sort_by { Kernel.rand }
-    end
-
-    def shuffle!
-      self.replace shuffle
-    end
-  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")
     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)
   end
+  
 end

data/lib/iron/extensions/class.rb

@@ -1,5 +1,23 @@
 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"
@@ -7,4 +25,22 @@ class Class
     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_proxy.rb

@@ -64,7 +64,7 @@ class DslProxy < BasicObject
   #
   # If the receiver doesn't respond_to? a method, any missing methods
   # will be proxied to the enclosing context.
-  def self.exec(receiver, &block) # :yields: receiver
+  def self.exec(receiver, *to_yield, &block) # :yields: receiver
     # Find the context within which the block was defined
     context = ::Kernel.eval('self', block.binding)
 
@@ -78,7 +78,7 @@ class DslProxy < BasicObject
     end
 
     # Exec the block and return the result
-    proxy._proxy(receiver, &block)
+    proxy._proxy(receiver, *to_yield, &block)
   end
   
   # Simple state setup
@@ -88,7 +88,7 @@ class DslProxy < BasicObject
     @_context = context
   end
   
-  def _proxy(receiver, &block) # :yields: receiver
+  def _proxy(receiver, *to_yield, &block) # :yields: receiver
     # Sanity!
     raise 'Cannot proxy with a DslProxy as receiver!' if receiver.respond_to?(:_to_dsl_proxy)
     
@@ -99,7 +99,6 @@ class DslProxy < BasicObject
         unless var.starts_with?('@_')
           value = @_context.instance_variable_get(var.to_s)
           @_instance_original_values[var] = value
-          #instance_variable_set(var, value)
           instance_eval "#{var} = value"
         end
       end
@@ -108,9 +107,11 @@ class DslProxy < BasicObject
     # Save the dsl target as our receiver for proxying
     _push_receiver(receiver)
 
-    # Run the block with ourselves as the new "self", passing the receiver in case
-    # the code wants to disambiguate for some reason
-    result = instance_exec(@_receivers.last, &block)
+    # 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
@@ -121,7 +122,6 @@ class DslProxy < BasicObject
       @_context.instance_variables.each do |var|
         unless var.starts_with?('@_')
           value = instance_eval("#{var}")
-          #value = instance_variable_get("#{var}")
           if @_instance_original_values[var] != value
             @_context.instance_variable_set(var.to_s, value)
           end

data/lib/iron/extensions/fixnum.rb

@@ -1,13 +1,13 @@
-
 class Fixnum
-  # Lifted from Rails' NumberHelper view helper
+  
+  # Adapted from Rails' NumberHelper view helper
   def to_human_size(precision=1)
     size = Kernel.Float(self)
     case
     when size.to_i == 1 then
       "1 Byte"
     when size < 1024 then
-      "#{size} Bytes"
+      "#{size.to_i} Bytes"
     when size < 1024*1024 then
       "#{(size / 1024).to_display(precision)} KB"
     when size < 1024*1024*1024 then
@@ -15,7 +15,7 @@ class Fixnum
     when size < 1024*1024*1024*1024 then
       "#{(size / (1024*1024*1024)).to_display(precision)} GB"
     else
-      "#{(size / (1024*1024*1024*1024)).to_display(precision)} GB"
+      "#{(size / (1024*1024*1024*1024)).to_display(precision)} TB"
     end
   rescue
     nil
@@ -24,4 +24,5 @@ class Fixnum
   def blank?
     false
   end
+  
 end

data/lib/iron/extensions/math.rb

@@ -1,5 +1,5 @@
-
 module Math
+  
   def self.min(a,b)
     a <= b ? a : b
   end

data/lib/iron/extensions/string.rb

@@ -15,7 +15,7 @@ class String
     self.insert(-1, str.to_s)
   end
 
-  # Date.parse sucks hard (assumes EU formatting, for one, does the wrong thing with 2 digit dates for two... etc.)
+  # Date.parse sucks hard (assumes EU formatting, for one, does the wrong thing with 2 digit years for two... etc.)
   # so we have this here as our personal, bona-fide date parsing helper.
   def to_date
     us_format = /^([0-9]{1,2})[-\/\.]([0-9]{1,2})[-\/\.]([0-9]+)$/        # US standard MM/DD/YYYY, allowing for 2 digit year
@@ -75,7 +75,7 @@ class String
   # To a permalink-style string rep, removing all non-word characters and dasherizing all spaces
   def to_dashcase
     s = self.dup
-    s.gsub!(/\'/,'')    # remove ' from rob's, so we don't get rob_s_blog
+    s.gsub!(/\'/,'')    # remove ' from rob's, so we don't get rob-s-blog
     s.gsub!(/\W+/, ' ') # all non-word chars to spaces
     s.gsub!('_',' ')    # we don't like underscores
     s.strip!            # ooh la la
@@ -85,24 +85,8 @@ class String
   end
   alias_method :to_permalink, :to_dashcase
 
-#  def to_phone
-#    raw, suffix = self.strip.extract(/([0-9\(\)\- \.,]+)(.*)/)
-#    raw.gsub!(/[^0-9\+\,]+/,'')
-#    raw.gsub!(/^\+?1/, '')
-#    raw, pause = raw.extract(/([0-9]+)(.*)/)
-#    count = raw.length
-#    if count == 7 || count == 10
-#      area, first, last = raw.extract(/([0-9]{3})?([0-9]{3})([0-9]{4})/)
-#      area ||= Settings[:site][:phone].default_area_code || '919'
-#      suffix = ' ' + suffix unless suffix.blank?
-#      pattern = Settings[:site][:phone].format || '(area) first-last'
-#      res = pattern.sub('area', area).sub('first', first).sub('last', last) + pause + suffix
-#      return res
-#    else
-#      return self
-#    end
-#  end
-
+  # Truncate a string to no more than len characters, honoring
+  # word boundaries (whitespace and - character)
   def smart_truncate(len = 30, ending = '...')
     len = Math.max(len, 5)
     return self if self.length <= len
@@ -112,7 +96,7 @@ class String
     s.reverse + ending
   end
 
-  # Returns an array that can be compared (eg via <=>) with another string's natural order
+  # Returns an array that can be compared (eg via Array#sort) with another string's natural order
   # to implement natural order sorting ("Bob123" => ['BOB', 123])
   def natural_order(nocase=true)
     i = true

data/spec/extensions/array_spec.rb

@@ -0,0 +1,15 @@
+describe Array do
+  
+  it 'should join lists ignoring blank entries' do
+    ['word', nil, '', 'end'].list_join('-').should == 'word-end'
+  end
+  
+  it 'should handle empty arrays while joining lists' do
+    [].list_join.should == ''
+  end
+  
+  it 'should handle list joins with only blank entries' do
+    [nil, '', nil].list_join.should == ''
+  end
+  
+end

data/spec/extensions/dsl_builder_spec.rb

@@ -1,8 +1,10 @@
 describe DslBuilder do
 
-  it 'should allow creating DSL-style accessors' 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
 
@@ -10,11 +12,18 @@ describe DslBuilder do
     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

@@ -45,7 +45,7 @@ describe DslProxy do
     @foo.should == 'no bar!'
   end
   
-  it 'should proxy missing methods on the receiver to the context' do
+  it 'should proxy missing methods on the receiver to the calling context' do
     class TestContext
       def bar
         'something'
@@ -93,6 +93,11 @@ describe DslProxy do
     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

data/spec/extensions/enumerable_spec.rb

@@ -5,6 +5,10 @@ describe Enumerable do
     [1,2,3].convert_to_hash.should == {1 => nil, 2 => nil, 3 => nil}
   end
   
+  it 'should accept a default value' do
+    [:a, :b].convert_to_hash(false).should == {:a => false, :b => false}
+  end
+  
   it 'should accept a block to set hash values' do
     [:a, :b, :c].convert_to_hash {|k| k.to_s.upcase}.should == {:a => 'A', :b => 'B', :c => 'C'}
   end

data/spec/extensions/numeric_spec.rb

@@ -6,7 +6,7 @@ describe Numeric do
     12345.to_display.should == '12,345'
     123450000066666234234.should be_an_instance_of(Bignum)
     123450000066666234234.to_display.should == '123,450,000,066,666,234,234'
-    0.0004.to_display
+    0.0004.to_display.should == '0.0004'
   end
   
   it 'should display correctly when negative' do

data/spec/spec_helper.rb

@@ -1,9 +1,11 @@
 # Require our library
 require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'iron', 'extensions'))
 
+# Config RSpec options
 RSpec.configure do |config|
-  #config.add_formatter 'documentation'
   config.color = true
+  config.add_formatter 'documentation'
   config.backtrace_clean_patterns = [/rspec/]
 end
 
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iron-extensions
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-02 00:00:00.000000000Z
+date: 2013-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2168582060 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,7 +21,12 @@ dependencies:
         version: '2.6'
   type: :development
   prerelease: false
-  version_requirements: *2168582060
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
 description: Adds common extensions to core Ruby classes
 email:
 - rob@irongaze.com
@@ -46,6 +51,7 @@ files:
 - 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
@@ -81,7 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Extensions to core classes