iron-extensions 1.0.0

data/.rspec

@@ -0,0 +1 @@
+--require <%= File.join(File.expand_path(File.dirname(__FILE__)), 'spec', 'spec_helper.rb') %>

data/History.txt

@@ -0,0 +1,6 @@
+== 1.0.0 / 2012-03-02
+
+* Broke out extensions from older irongaze gem
+* Vastly improved README with listing of extensions added
+* Improved spec coverage
+* Integrated several new extensions

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Irongaze Consulting LLC
+
+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.rdoc

@@ -0,0 +1,101 @@
+= GEM: iron-extensions
+
+Written by Rob Morris @ Irongaze Consulting LLC (http://irongaze.com)
+
+== DESCRIPTION:
+
+Helpful extensions to core Ruby classes
+
+== 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'
+    
+* 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}
+    
+* File.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.write("PRODUCTION: true")
+    end
+    
+* Fixnum#blank? - always false
+* Fixnum#to_human_size - size to MB/GB/whatever, lifted from Rails
+
+    123456.to_human_size # => "120.5 KB"
+
+* Kernel#capture_stdout - capture all text sent to STDOUT within the passed block
+
+    # Will result in out == 'Hi mom!\n'
+    out = capture_stdout do 
+      puts 'Hi mom!'
+    end
+
+* Math.max/Math.min - find the max/min value passed
+
+    Math.max(2,10) # => 10
+    
+* Math.scale_to_fit - shrink width and height vals to fit in a box, preserving aspect ratio
+
+    Math.scale_to_fit(100, 100, 50, 80) # => 50, 50
+    
+* Nil#blank? - always true
+
+* Numeric#bound - bound a given number to a range
+
+    4.bound(5,10) # => 4
+
+* Object#in? - sugar to make expressing inclusion clearer
+
+    1.in? [2,3,4] # => false
+    'foo'.in? ['foo', 'bar'] # => true
+
+* Range#bound - ensure a number is in a range
+
+    (1..5).bound(6) # => 5
+
+* 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#to_dashcase - perfect for permalinks!
+* String#smart_truncate - truncate honoring word boundaries
+* String#integer? - true when string represents an integer
+* String#extract - simplifies pulling info out of strings using regexen
+
+    "Irongaze Consulting".extract(/^[a-z]/i) # => "Irongaze"
+    dollars, cents = "$12.95".extract(/([0-9]+)\.([0-9]+)/) # => dollars == '12' and cents == '95'
+
+* Symbol#blank? - always false
+* Symbol#to_dashcase - same as for String
+
+== SYNOPSIS:
+
+To use:
+
+    require 'iron/extensions'
+
+== REQUIREMENTS:
+
+* None
+
+== INSTALL:
+
+To install, simply run:
+
+    sudo gem install iron-extensions

data/lib/iron/extensions.rb

@@ -0,0 +1,5 @@
+# Requires all extensions
+search_path = File.join(File.expand_path(File.dirname(__FILE__)), 'extensions', '*.rb')
+Dir.glob(search_path) do |path|
+  require path
+end

data/lib/iron/extensions/array.rb

@@ -0,0 +1,24 @@
+
+class Array
+  unless [].respond_to?(:shuffle)
+    def shuffle
+      sort_by { Kernel.rand }
+    end
+
+    def shuffle!
+      self.replace shuffle
+    end
+  end
+
+  def rand(count = 1)
+    shuffle[0...count]
+  end
+
+  def rand!(count = 1)
+    self.replace rand(count)
+  end
+
+  def list_join(sep = ', ')
+    self.select{|e| !e.blank?}.join(sep)
+  end
+end

data/lib/iron/extensions/enumerable.rb

@@ -0,0 +1,13 @@
+module Enumerable
+  
+  # Converts an enumerable into a hash, by accepting an initial value
+  # or a block to compute the value for a given key.
+  def to_hash(init_val = nil)
+    hash = {}
+    self.each do |key|
+      hash[key] = block_given? ? yield(key) : init_val
+    end
+    hash
+  end
+  
+end

data/lib/iron/extensions/file.rb

@@ -0,0 +1,24 @@
+require 'fileutils'
+
+class File
+
+  # Atomic replace code - write to temp file, rename to source file path
+  # Usage:
+  #
+  # File.safe_replace('/etc/foo.conf') do |file|
+  #   file.write('bob=1234')
+  # end
+  def self.safe_replace(path, perm=nil) # :yields: file
+    begin
+      tmp_path = path + '.tmp' + Kernel.rand(99999).to_s
+    end while File.exist?(tmp_path)
+
+    file = File.open(tmp_path, 'w', perm)
+    yield file
+    file.close
+
+    FileUtils.mv(tmp_path, path)
+  end
+
+end
+

data/lib/iron/extensions/fixnum.rb

@@ -0,0 +1,27 @@
+
+class Fixnum
+  # Lifted 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"
+    when size < 1024*1024 then
+      "#{(size / 1024).to_display(precision)} KB"
+    when size < 1024*1024*1024 then
+      "#{(size / (1024*1024)).to_display(precision)} MB"
+    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"
+    end
+  rescue
+    nil
+  end
+  
+  def blank?
+    false
+  end
+end

data/lib/iron/extensions/kernel.rb

@@ -0,0 +1,15 @@
+
+require 'stringio'
+ 
+module Kernel
+ 
+  def capture_stdout
+    out = StringIO.new
+    $stdout = out
+    yield
+    return out.string
+  ensure
+    $stdout = STDOUT
+  end
+ 
+end

data/lib/iron/extensions/math.rb

@@ -0,0 +1,27 @@
+
+module Math
+  def self.min(a,b)
+    a <= b ? a : b
+  end
+
+  def self.max(a,b)
+    a >= b ? a : b
+  end
+
+  def self.scale_to_fit(w,h,max_w,max_h)
+    ratio = max_w.to_f / max_h.to_f
+    nw, nh = w, h
+    cur_ratio = nw.to_f / nh.to_f
+
+    if cur_ratio >= ratio
+      nw = max_w
+      nh = max_w / cur_ratio
+    else
+      nh = max_h
+      nw = max_h * cur_ratio
+    end
+
+    return nw.to_i, nh.to_i
+  end
+
+end

data/lib/iron/extensions/nil.rb

@@ -0,0 +1,8 @@
+
+class NilClass
+
+  def blank?
+    true
+  end
+
+end

data/lib/iron/extensions/numeric.rb

@@ -0,0 +1,35 @@
+
+class Numeric
+
+  # Returns self, bounded to min/max values
+  def bound(min, max)
+    min, max = max, min if max < min
+    return min if min > self
+    return max if max < self
+    self
+  end
+
+  def to_display(decimal_count = nil, include_thousands = true)
+    res = ''
+    decimal = self.to_s.extract(/\.([0-9]+)/)
+    unless decimal.nil? || decimal_count.nil?
+      decimal = decimal[0...decimal_count].ljust(decimal_count,'0')
+    end
+    val = self.to_i.abs
+    if include_thousands
+      while val > 999
+        res.prepend(',' + (val % 1000).to_s.rjust(3,'0'))
+        val /= 1000
+      end
+    end
+    res.prepend(val.to_s) if val > 0 || res.empty?
+    res = '-' + res if self < 0
+    res = res + '.' + decimal unless decimal.blank?
+    res
+  end
+  
+  #def to_currency
+  #  Currency::parse(self)
+  #end
+
+end

data/lib/iron/extensions/object.rb

@@ -0,0 +1,8 @@
+class Object
+  
+  def in?(enum)
+    return false unless enum.respond_to?(:include?)
+    enum.include?(self)
+  end
+  
+end

data/lib/iron/extensions/range.rb

@@ -0,0 +1,13 @@
+
+class Range
+  def bound(arg)
+    if arg < min
+      return min
+    elsif arg > max
+      return max
+    else
+      return arg
+    end
+  end
+end
+

data/lib/iron/extensions/regexp.rb

@@ -0,0 +1,8 @@
+
+class Regexp
+
+  IP_ADDRESS = /(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})/.freeze
+  EMAIL_ADDRESS = /^([a-z0-9]+[a-z0-9\.\-\_\+]*)@([a-z0-9\.\-]+\.[a-z]{2,})$/
+  DOMAIN = /^([a-z0-9\.\-]+\.[a-z]{2,})$/
+
+end

data/lib/iron/extensions/string.rb

@@ -0,0 +1,172 @@
+require 'date'
+
+class String
+
+  # Provide helper for nil/"" blankness checker
+  def blank?
+    empty?
+  end
+
+  def prepend(str)
+    self.insert(0, str.to_s)
+  end
+  
+  def append(str)
+    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.)
+  # 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
+    db_format = /^([0-9]{4})[-\/\.]([0-9]{2})[-\/\.]([0-9]{2})$/  # More sane, but less common YYYY-MM-DD
+
+    if self.match(us_format)
+      m, d, y = self.extract(us_format)
+    elsif self.match(db_format)
+      y, m, d = self.extract(db_format)
+    else
+      return nil
+    end
+    
+    y = y.to_i
+    if y < 100
+      # Ok, we'll let you do this 2 digit thing, but only because we like you.
+      # Assume that 10 years in the future is as far as we're interested in.
+      cutoff = Date.today.year - 2000 + 10
+      y += (y < cutoff) ? 2000 : 1900
+    end
+    Date.new(y,m.to_i,d.to_i) rescue nil
+  end
+
+  # Returns the various captured elements from this string with the regex applied.
+  #   Usage:  a,b = 'abc123 is cool'.extract(/([a-z]*)([0-9]*)/)
+  #     => a = 'abc', b = '123'
+  # With no capture in regex, returns full match
+  # If no match, returns nil
+  def extract(regex)
+    data = self.match(regex)
+    return nil unless data
+    if data.size > 2
+      return *(data.to_a[1..-1])
+    elsif data.size == 2
+      return data[1]
+    else
+      return data[0]
+    end
+  end
+
+  # Simple parse-and-replace code, use eg: "My name is :name:".replace_vars(@person), will call #name on @person
+  # and insert into place of :name:.  You can also pass in a hash to
+  # source the variable values, eg: "I like :food:!".replace_vars({:food => 'eggs'})
+  def replace_vars(obj)
+    self.gsub(/:([a-z0-9_]+):/) do |match|
+      verb = Regexp.last_match[1].intern
+      if obj.is_a?(Hash)
+        obj[verb].to_s
+      elsif obj.respond_to?(verb)
+        obj.send(verb).to_s
+      else
+        ":#{verb}:"
+      end
+    end
+  end
+
+  # 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!(/\W+/, ' ') # all non-word chars to spaces
+    s.strip!            # ohh la la
+    s.downcase!         #
+    s.gsub!(/\ +/, '-') # spaces to dashes, preferred separator char everywhere
+    s
+  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
+
+  def smart_truncate(len = 30, ending = '...')
+    len = Math.max(len, 5)
+    return self if self.length <= len
+    s = self[0...(len-2)].reverse
+    bits = s.split(/[\s\-,]/,2)
+    s = bits.length == 2 ? bits[1] : bits[0]
+    s.reverse + ending
+  end
+
+  # Returns an array that can be compared (eg via <=>) with another string's natural order
+  # to implement natural order sorting ("Bob123" => ['BOB', 123])
+  def natural_order(nocase=true)
+    i = true
+    str = self
+    str = str.upcase if nocase
+    str.gsub(/\s+/, '').split(/(\d+)/).map {|x| (i = !i) ? x.to_i : x}
+  end
+
+  # Intelligently pluralize a phrase, looking for an initial number and doing the right thing if it's found.
+  # Also handles ignoring punctuation.
+  #   "Buy 2 widget!".smart_pluralize => "Buy 2 widgets!"
+  # Requires Rails or a pluralize method on string
+  if ''.respond_to?(:pluralize)
+    def smart_pluralize
+      amt, word = self.extract(/[^0-9\-]*(-?[0-9,]+)?.*(?:[^a-z]|^)([a-z]+)[^a-z]*$/i)
+      unless word.blank?
+        word = word.pluralize if amt.blank? || amt.gsub(',','').to_i != 1
+        return self.gsub(/([^a-z]|^)([a-z]+)([^a-z]*)$/i, '\1'+word+'\3')
+      end
+      return self
+    end
+  end
+
+  # Someday will be part of core ruby, with luck...
+  unless ''.respond_to?(:starts_with?)
+    # Does the string start with the specified +prefix+?
+    def starts_with?(prefix)
+      prefix = prefix.to_s
+      self[0, prefix.length] == prefix
+    end
+
+    # Does the string end with the specified +suffix+?
+    def ends_with?(suffix)
+      suffix = suffix.to_s
+      self[-suffix.length, suffix.length] == suffix
+    end
+  end
+
+  # In case we're running in Rails, which defines this already...
+  unless ''.respond_to?(:constantize)
+    def constantize()
+      names = self.split('::')
+      names.shift if names.empty? || names.first.empty?
+
+      constant = Object
+      names.each do |name|
+        constant = constant.const_defined?(name) ? constant.const_get(name) : constant.const_missing(name)
+      end
+      constant
+    end
+  end
+
+  # When true, is a valid integer
+  def integer?
+    self.to_i.to_s == self
+  end
+
+end

data/lib/iron/extensions/symbol.rb

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

data/sample.rdoc

@@ -0,0 +1,3 @@
+This will break:
+
+    'foo'.match(/bar/)

data/spec/extensions/enumerable_spec.rb

@@ -0,0 +1,12 @@
+
+describe Enumerable do
+
+  it 'should convert to a hash' do
+    [1,2,3].to_hash.should == {1 => nil, 2 => nil, 3 => nil}
+  end
+  
+  it 'should accept a block to set hash values' do
+    [:a, :b, :c].to_hash {|k| k.to_s.upcase}.should == {:a => 'A', :b => 'B', :c => 'C'}
+  end
+
+end

data/spec/extensions/object_spec.rb

@@ -0,0 +1,11 @@
+
+describe Object do
+
+  it 'should respond to in?' do
+    1.in?([1,2,3]).should == true
+    5.in?([1,2,3]).should == false
+    "foo".in?(nil).should == false
+    :b.in?([:a, :b, :c]).should == true
+  end
+
+end

data/spec/extensions/string_spec.rb

@@ -0,0 +1,82 @@
+
+describe String do
+
+  describe 'when extracting' do 
+    it 'should respond to extract' do
+      "test".should respond_to(:extract)
+    end
+
+    it 'should return nil if extract fails to match' do
+      'test'.extract(/nossir/).should be_nil
+    end
+
+    it 'should extract a single value if the whole regex matches' do
+      res = 'test'.extract(/est/)
+      res.should be_a(String)
+      res.should == 'est'
+    end
+
+    it 'should extract a single value correctly if a capture is specified' do
+      res = 'test'.extract(/e(s)t/)
+      res.should be_a(String)
+      res.should == 's'
+    end
+
+    it 'should extract multiple values if more than one capture is specified' do
+      res = 'a great big number 10!'.extract(/(great).*(number).*([0-9]{2})/)
+      res.should be_an(Array)
+      res.should == ['great', 'number', '10']
+    end
+
+    it 'should extract nil for missing captures' do 
+      a, b, c = 'a great big numero 10!'.extract(/(great).*(number)?.*([0-9]{2})/)
+      a.should == 'great'
+      b.should be_nil
+      c.should == '10'
+    end
+  end
+  
+  it 'should convert to a date correctly' do
+    {
+      '' => nil,
+      '13/1/2010' => nil,
+      '12/4/73' => Date.new(1973,12,4),
+      '12/4/1973' => Date.new(1973,12,4),
+      '12-31-10' => Date.new(2010,12,31),
+      '2025-01-04' => Date.new(2025,1,4)
+    }.each_pair do |str, date|
+      str.to_date.should == date
+    end
+  end
+
+  it 'should respond to ends_with?' do 
+    'bob'.should respond_to(:ends_with?)
+  end
+
+  it 'should correctly determine if it ends with a passed string' do
+    'bob'.ends_with?('ob').should be_true
+    'bob'.ends_with?('o').should_not be_true
+  end
+
+  it 'should be convertable to dashcase' do
+    "Rob's greatest hits!".to_dashcase.should == 'robs-greatest-hits'
+  end
+
+  it 'should truncate intelligently' do
+    "A great big string o' doom!".smart_truncate(15).should == 'A great big...'
+    "Agreatbigstringodoom!".smart_truncate(15).should == 'Agreatbigstri...'
+  end
+
+  it 'should constantize correctly' do
+    'Object'.constantize.should equal(Object)
+  end
+
+  it 'should constantize modules' do
+    'Enumerable'.constantize.should equal(Enumerable)
+  end
+
+  it 'should support natural ordering' do
+    ['a0', 'a90', 'a10', 'a9'].sort_by {|a| a.natural_order}.should == ['a0', 'a9', 'a10', 'a90']
+  end
+
+end

data/spec/spec_helper.rb

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

data/version.txt

@@ -0,0 +1 @@
+1.0.0

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: iron-extensions
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Rob Morris
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-02 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2152110960 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: *2152110960
+description: Adds common extensions to core Ruby classes
+email:
+- rob@irongaze.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/iron/extensions/array.rb
+- lib/iron/extensions/enumerable.rb
+- lib/iron/extensions/file.rb
+- lib/iron/extensions/fixnum.rb
+- lib/iron/extensions/kernel.rb
+- lib/iron/extensions/math.rb
+- lib/iron/extensions/nil.rb
+- lib/iron/extensions/numeric.rb
+- lib/iron/extensions/object.rb
+- lib/iron/extensions/range.rb
+- lib/iron/extensions/regexp.rb
+- lib/iron/extensions/string.rb
+- lib/iron/extensions/symbol.rb
+- lib/iron/extensions.rb
+- spec/extensions/enumerable_spec.rb
+- spec/extensions/object_spec.rb
+- spec/extensions/string_spec.rb
+- spec/spec_helper.rb
+- LICENSE
+- History.txt
+- version.txt
+- README.rdoc
+- sample.rdoc
+- .rspec
+homepage: http://irongaze.com
+licenses:
+- MIT
+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.10
+signing_key: 
+specification_version: 3
+summary: Extensions to core classes
+test_files: []