extlib 0.9.8 → 0.9.9

data/lib/extlib/string.rb

@@ -2,32 +2,39 @@ require "pathname"
 
 class String
   ##
-  # @return <String> The string with all regexp special characters escaped.
+  # Escape all regexp special characters.
   #
-  # @example
-  #   "*?{}.".escape_regexp #=> "\\*\\?\\{\\}\\."
+  #   "*?{}.".escape_regexp   #=> "\\*\\?\\{\\}\\."
+  #
+  # @return [String] Receiver with all regexp special characters escaped.
+  #
+  # @api public
   def escape_regexp
     Regexp.escape self
   end
-  
+
   ##
-  # @return String The string with all regexp special characters unescaped.
+  # Unescape all regexp special characters.
   #
-  # @example
   #   "\\*\\?\\{\\}\\.".unescape_regexp #=> "*?{}."
+  #
+  # @return [String] Receiver with all regexp special characters unescaped.
+  #
+  # @api public
   def unescape_regexp
     self.gsub(/\\([\.\?\|\(\)\[\]\{\}\^\$\*\+\-])/, '\1')
   end
-  
+
   ##
-  # @return <String> The string converted to snake case.
-  #
-  # @example
-  #   "FooBar".snake_case #=> "foo_bar"
-  # @example
-  #   "HeadlineCNNNews".snake_case #=> "headline_cnn_news"
-  # @example
-  #   "CNN".snake_case #=> "cnn"
+  # Convert to snake case.
+  #
+  #   "FooBar".snake_case           #=> "foo_bar"
+  #   "HeadlineCNNNews".snake_case  #=> "headline_cnn_news"
+  #   "CNN".snake_case              #=> "cnn"
+  #
+  # @return [String] Receiver converted to snake case.
+  #
+  # @api public
   def snake_case
     return self.downcase if self =~ /^[A-Z]+$/
     self.gsub(/([A-Z]+)(?=[A-Z][a-z]?)|\B[A-Z]/, '_\&') =~ /_*(.*)/
@@ -35,57 +42,71 @@ class String
   end
 
   ##
-  # @return <String> The string converted to camel case.
+  # Convert to camel case.
   #
-  # @example
-  #   "foo_bar".camel_case #=> "FooBar"
+  #   "foo_bar".camel_case          #=> "FooBar"
+  #
+  # @return [String] Receiver converted to camel case.
+  #
+  # @api public
   def camel_case
     return self if self !~ /_/ && self =~ /[A-Z]+.*/
     split('_').map{|e| e.capitalize}.join
   end
 
   ##
-  # @return <String> The path string converted to a constant name.
+  # Convert a path string to a constant name.
   #
-  # @example
   #   "merb/core_ext/string".to_const_string #=> "Merb::CoreExt::String"
+  #
+  # @return [String] Receiver converted to a constant name.
+  #
+  # @api public
   def to_const_string
     gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
   end
 
   ##
-  # @return <String>
-  #   The path that is associated with the constantized string, assuming a
-  #   conventional structure.
+  # Convert a constant name to a path, assuming a conventional structure.
   #
-  # @example
   #   "FooBar::Baz".to_const_path # => "foo_bar/baz"
+  #
+  # @return [String] Path to the file containing the constant named by receiver
+  #   (constantized string), assuming a conventional structure.
+  #
+  # @api public
   def to_const_path
     snake_case.gsub(/::/, "/")
   end
 
   ##
-  # @param o<String> The path component to join with the string.
-  #
-  # @return <String> The original path concatenated with o.
+  # Join with _o_ as a file path.
   #
-  # @example
   #   "merb"/"core_ext" #=> "merb/core_ext"
+  #
+  # @param [String] o Path component to join with receiver.
+  #
+  # @return [String] Receiver joined with o as a file path.
+  #
+  # @api public
   def /(o)
     File.join(self, o.to_s)
   end
 
   ##
-  # @param other<String> Base path to calculate against
-  #
-  # @return <String> Relative path from between the two
+  # Calculate a relative path *from* _other_.
   #
-  # @example
   #   "/opt/local/lib".relative_path_from("/opt/local/lib/ruby/site_ruby") # => "../.."
+  #
+  # @param [String] other Base path to calculate *from*.
+  #
+  # @return [String] Relative path from _other_ to receiver.
+  #
+  # @api public
   def relative_path_from(other)
     Pathname.new(self).relative_path_from(Pathname.new(other)).to_s
   end
-  
+
   # Overwrite this method to provide your own translations.
   def self.translate(value)
     translations[value] || value
@@ -95,19 +116,33 @@ class String
     @translations ||= {}
   end
 
-  # Matches any whitespace (including newline) and replaces with a single space
+  ##
+  # Replace sequences of whitespace (including newlines) with either
+  # a single space or remove them entirely (according to param _spaced_)
   #
-  # @example
   #   <<QUERY.compress_lines
   #     SELECT name
   #     FROM users
-  #   QUERY
-  #   => "SELECT name FROM users"
+  #   QUERY => "SELECT name FROM users"
+  #
+  # @param [TrueClass, FalseClass] spaced (default=true)
+  #   Determines whether returned string has whitespace collapsed or removed
+  #
+  # @return [String] Receiver with whitespace (including newlines) replaced
+  #
+  # @api public
   def compress_lines(spaced = true)
     split($/).map { |line| line.strip }.join(spaced ? ' ' : '')
   end
 
-  # Useful for heredocs - removes whitespace margin.
+  ##
+  # Remove whitespace margin.
+  #
+  # @param [Object] indicator ???
+  #
+  # @return [String] receiver with whitespace margin removed
+  #
+  # @api public
   def margin(indicator = nil)
     lines = self.dup.split($/)
 
@@ -120,12 +155,20 @@ class String
     lines.map { |line| line.sub(/^\s{#{min_margin}}/, '') }.join($/)
   end
 
- # Formats String for easy translation. Replaces an arbitrary number of
+  ##
+  # Formats String for easy translation. Replaces an arbitrary number of
   # values using numeric identifier replacement.
   #
-  # @example
-  # "%s %s %s" % %w(one two three) #=> "one two three"
-  # "%3$s %2$s %1$s" % %w(one two three) #=> "three two one"
+  #   "%s %s %s" % %w(one two three)        #=> "one two three"
+  #   "%3$s %2$s %1$s" % %w(one two three)  #=> "three two one"
+  #
+  # @param [#to_s] values
+  #   A list of values to translate and interpolate into receiver
+  #
+  # @return [String]
+  #   Receiver translated with values translated and interpolated positionally
+  #
+  # @api public
   def t(*values)
     self.class::translate(self) % values.collect! { |value| value.frozen? ? value : self.class::translate(value.to_s) }
   end

data/lib/extlib/struct.rb

@@ -1,5 +1,14 @@
 class Struct
-  # Returns a hash containing the names and values for all instance variables in the Struct.
+  ##
+  # Get a hash with names and values of all instance variables.
+  #
+  #   class Foo < Struct.new(:name, :age, :gender); end
+  #   f = Foo.new("Jill", 50, :female)
+  #   f.attributes   #=> {:name => "Jill", :age => 50, :gender => :female}
+  #
+  # @return [Hash] Hash of instance variables in receiver, keyed by ivar name
+  #
+  # @api public
   def attributes
     h = {}
     each_pair { |k,v| h[k] = v }

data/lib/extlib/symbol.rb

@@ -1,17 +1,21 @@
 class Symbol
-  
+
   def try_dup
     self
   end
-  
+
   ##
-  # @param o<String, Symbol> The path component to join with the string.
+  # Join with _o_ as a file path
   #
-  # @return <String> The original path concatenated with o.
+  #   :merb/"core_ext"              #=> "merb/core_ext"
+  #   :merb / :core_ext / :string   #=> "merb/core_ext/string"
   #
-  # @example
-  #   :merb/"core_ext" #=> "merb/core_ext"
+  # @param [#to_s] o The path component(s) to append.
+  #
+  # @return [String] The receiver (as path string), concatenated with _o_.
+  #
+  # @api public
   def /(o)
     File.join(self.to_s, o.to_s)
   end
-end
+end

data/lib/extlib/time.rb

@@ -1,19 +1,41 @@
+require "date"
+
 class Time
-  
-  # @return <String>
-  #   ISO 8601 compatible rendering of the Time object's properties.
-  # 
-  # @example
-  #   Time.now.to_json # => "\"2008-03-28T17:54:20-05:00\""
+
+  ##
+  # Convert to ISO 8601 representation
+  #
+  #   Time.now.to_json        #=> "\"2008-03-28T17:54:20-05:00\""
+  #
+  # @return [String]
+  #   ISO 8601 compatible representation of the Time object.
+  #
+  # @api public
   def to_json(*)
     self.xmlschema.to_json
   end
-  
+
+  ##
+  # Return receiver (for DateTime/Time conversion protocol).
+  #
+  #   Time.now.to_time        #=> Wed Nov 19 20:08:28 -0800 2008
+  #
+  # @return [Time] Receiver
+  #
+  # @api public
   def to_time
     self
   end
-  
+
+  ##
+  # Convert to DateTime (for DateTime/Time conversion protocol).
+  #
+  #   Time.now.to_datetime    #=> #<DateTime: 106046956823/43200,-1/3,2299161>
+  #
+  # @return [DateTime] DateTime object representing the same moment as receiver
+  #
+  # @api public
   def to_datetime
     DateTime.parse self.to_s
   end
-end
+end

data/lib/extlib/version.rb

@@ -1,3 +1,3 @@
 module Extlib
-  VERSION = "0.9.8"
+  VERSION = '0.9.9'
 end

data/lib/extlib/virtual_file.rb

@@ -7,4 +7,4 @@ class VirtualFile < StringIO
     super(string)
     @path = path
   end
-end
+end

data/spec/blank_spec.rb

@@ -0,0 +1,85 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'spec_helper'))
+
+describe Object do
+  it 'should provide blank?' do
+    Object.new.should respond_to(:blank?)
+  end
+
+  it 'should be blank if it is nil' do
+    object = Object.new
+    class << object
+      def nil?; true end
+    end
+    object.should be_blank
+  end
+
+  it 'should be blank if it is empty' do
+    {}.should be_blank
+    [].should be_blank
+  end
+
+  it 'should not be blank if not nil or empty' do
+    Object.new.should_not be_blank
+    [nil].should_not be_blank
+    { nil => 0 }.should_not be_blank
+  end
+end
+
+describe Numeric do
+  it 'should provide blank?' do
+    1.should respond_to(:blank?)
+  end
+
+  it 'should never be blank' do
+    1.should_not be_blank
+  end
+end
+
+describe NilClass do
+  it 'should provide blank?' do
+    nil.should respond_to(:blank?)
+  end
+
+  it 'should always be blank' do
+    nil.should be_blank
+  end
+end
+
+describe TrueClass do
+  it 'should provide blank?' do
+    true.should respond_to(:blank?)
+  end
+
+  it 'should never be blank' do
+    true.should_not be_blank
+  end
+end
+
+describe FalseClass do
+  it 'should provide blank?' do
+    false.should respond_to(:blank?)
+  end
+
+  it 'should always be blank' do
+    false.should be_blank
+  end
+end
+
+describe String do
+  it 'should provide blank?' do
+    'string'.should respond_to(:blank?)
+  end
+
+  it 'should be blank if empty' do
+    ''.should be_blank
+  end
+
+  it 'should be blank if it only contains whitespace' do
+    ' '.should be_blank
+    " \r \n \t ".should be_blank
+  end
+
+  it 'should not be blank if it contains non-whitespace' do
+    ' a '.should_not be_blank
+  end
+end

data/spec/class_spec.rb

@@ -0,0 +1,141 @@
+require File.join(File.dirname(__FILE__), "spec_helper")
+
+class Grandparent
+end
+
+class Parent < Grandparent
+end
+
+class Child < Parent
+end
+
+class Parent
+end
+
+class Grandparent
+  class_inheritable_accessor :last_name, :_attribute
+
+  self._attribute = 1900
+end
+
+describe Class, "#inheritable_accessor" do
+
+  after :each do
+    Grandparent.send(:remove_instance_variable, "@last_name") rescue nil
+    Parent.send(:remove_instance_variable, "@last_name") rescue nil
+    Child.send(:remove_instance_variable, "@last_name") rescue nil
+  end
+
+  it 'inherits from parent unless overriden' do
+    Parent._attribute.should == 1900
+    Child._attribute.should == 1900
+  end
+
+  it 'inherits from grandparent unless overriden' do
+    Child._attribute.should == 1900
+  end
+
+  it "inherits even if the accessor is made after the inheritance" do
+    Grandparent.last_name = "Merb"
+    Parent.last_name.should == "Merb"
+    Child.last_name.should == "Merb"
+  end
+
+  it "supports ||= to change a child" do
+    Parent.last_name ||= "Merb"
+    Grandparent.last_name.should == nil
+    Parent.last_name.should == "Merb"
+    Child.last_name.should == "Merb"
+  end
+
+  it "supports << to change a child when the parent is an Array" do
+    Grandparent.last_name = ["Merb"]
+    Parent.last_name << "Core"
+    Grandparent.last_name.should == ["Merb"]
+    Parent.last_name.should == ["Merb", "Core"]
+  end
+
+  it "supports ! methods on an Array" do
+    Grandparent.last_name = %w(Merb Core)
+    Parent.last_name.reverse!
+    Grandparent.last_name.should == %w(Merb Core)
+    Parent.last_name.should == %w(Core Merb)
+  end
+
+  it "support modifying a parent Hash" do
+    Grandparent.last_name = {"Merb" => "name"}
+    Parent.last_name["Core"] = "name"
+    Parent.last_name.should == {"Merb" => "name", "Core" => "name"}
+    Grandparent.last_name.should == {"Merb" => "name"}
+  end
+
+  it "supports hard-merging a parent Hash" do
+    Grandparent.last_name = {"Merb" => "name"}
+    Parent.last_name.merge!("Core" => "name")
+    Parent.last_name.should == {"Merb" => "name", "Core" => "name"}
+    Grandparent.last_name.should == {"Merb" => "name"}
+  end
+
+  it "supports changes to the parent even if the child has already been read" do
+    Child.last_name
+    Grandparent.last_name = "Merb"
+    Child.last_name.should == "Merb"
+  end
+
+  it "handles nil being set midstream" do
+    Child.last_name
+    Parent.last_name = nil
+    Grandparent.last_name = "Merb"
+    Child.last_name.should == nil
+  end
+
+  it "handles false being used in Parent" do
+    Child.last_name
+    Parent.last_name = false
+    Grandparent.last_name = "Merb"
+    Child.last_name.should == false
+  end
+
+  it "handles the grandparent changing the value (as long as the child isn't read first)" do
+    Grandparent.last_name = "Merb"
+    Grandparent.last_name = "Core"
+    Child.last_name.should == "Core"
+  end
+
+end
+
+#
+# The bug that prompted this estoric spec was found in
+# the wild when using dm-is-versioned with c_i_w.
+#
+
+module Plugin
+  def self.included(base)
+    base.class_eval do
+      class_inheritable_writer :plugin_options
+      class_inheritable_reader :plugin_options
+      self.plugin_options = :foo
+    end
+  end
+end
+
+class Model
+  def self.new
+    model = Class.new
+    model.send(:include, Plugin)
+    model
+  end
+
+  include Plugin
+  self.const_set("Version", Model.new)
+end
+
+describe Class, "#inheritable_accessor" do
+  it "uses object_id for comparison" do
+    Model.methods.should include("plugin_options")
+    Model.plugin_options.should == :foo
+
+    Model::Version.methods.should include("plugin_options")
+    Model::Version.plugin_options.should == :foo
+  end
+end