cowtech-extensions 2.1.3 → 2.5.0

data/lib/cowtech-extensions/exceptions.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+#
+# This file is part of the cowtech-extensions gem. Copyright (C) 2011 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Cowtech
+  module Extensions
+    # Exceptions for cowtech-extensions.
+    module Exceptions
+      # This exception is raised from {Object#debug_dump} when `must_raise` is `true`.
+      class Dump < ::RuntimeError
+      end
+    end
+  end
+end

data/lib/cowtech-extensions/hash.rb

@@ -6,25 +6,36 @@
 
 module Cowtech
 	module Extensions
+    # Extensions for Hash objects.
 		module Hash
-			extend ActiveSupport::Concern
+			extend ::ActiveSupport::Concern
 
+      # This is called when the user access a member using dotted notation.
+      #
+      # @param method [String|Symbol] Key to search.
+      # @param args [Array] *Unused.*
+      # @param block [Proc] *Unused.*
+      # @return [Object] The value for the key.
 			def method_missing(method, *args, &block)
-        rv = nil
+       rv = nil
 
-        if self.has_key?(method.to_sym) then
+       if self.has_key?(method.to_sym) then
           rv = self[method.to_sym]
-        elsif self.has_key?(method.to_s) then
+       elsif self.has_key?(method.to_s) then
           rv = self[method.to_s]
-        else
-          rv = super(method, *args, &block)
-        end
+       else
+          rv = ::Hash.method_missing(method, *args, &block)
+       end
 
-        rv
+       rv
 			end
 
+      # This is called when the user access a member using dotted notation.
+      #
+      # @param method [String|Symbol] Key to search.
+      # @return [Boolean] `true` if the key exists, `false` otherwise.
 			def respond_to?(method)
-				(self.has_key?(method.to_sym) || self.has_key?(method.to_s)) ? true : super(method)
+				(self.has_key?(method.to_sym) || self.has_key?(method.to_s)) ? true : ::Hash.respond_to?(method)
 			end
 		end
 	end

data/lib/cowtech-extensions/math.rb

@@ -6,36 +6,43 @@
 
 module Cowtech
 	module Extensions
+    # Utility methods for Math module.
 		module Math
-			extend ActiveSupport::Concern
+			extend ::ActiveSupport::Concern
 
+      # General methods.
 			module ClassMethods
+        # Returns the minimum value in the arguments
+        #
+        # @param args [Array] A collection of object to compare (with the `<` operator).
+        # @return [Object] The minimum value or `nil` (if the collection is empty).
 				def min(*args)
-          args = args.ensure_array.flatten
+          rv = nil
 
+          args = args.ensure_array.flatten
           if args.length > 0 then
             rv = args[0]
             args.each do |a| rv = a if a < rv end
-          else
-            rv = nil
           end
 
           rv
         end
 
+        # Returns the maximum value in the arguments
+        #
+        # @param args [Array] A collection of object to compare (with the `>` operator).
+        # @return [Object] The maximum value or `nil` (if the collection is empty).
         def max(*args)
-          args = args.ensure_array.flatten
+          rv = nil
 
+          args = args.ensure_array.flatten
           if args.length > 0 then
             rv = args[0]
             args.each do |a| rv = a if a > rv end
-          else
-            rv = nil
           end
 
           rv
         end
-
       end
 		end
 	end

data/lib/cowtech-extensions/object.rb

@@ -6,10 +6,14 @@
 
 module Cowtech
 	module Extensions
+    # Extensions for all objects.
 		module Object
-			include ActionView::Helpers::NumberHelper
-			extend ActiveSupport::Concern
+			include ::ActionView::Helpers::NumberHelper
+			extend ::ActiveSupport::Concern
 
+      # Normalizes a number for conversion. Basically this methods removes all separator and ensures that `.` is used for decimal separator.
+      #
+      # @return [String] The normalized number.
       def normalize_number
         rv = self.ensure_string.strip
         rv = rv.split(/[\.,]/)
@@ -17,83 +21,136 @@ module Cowtech
         rv.join("")
       end
 
+      # Checks if the object is a valid number.
+      #
+      # @return [Boolean] `true` is a valid number, `false` otherwise.
       def is_number?
 				self.is_float?
 			end
 
+      # Checks if the object is a valid integer.
+      #
+      # @return [Boolean] `true` is a valid integer, `false` otherwise.
 			def is_integer?
-				self.is_a?(Integer) || /^([+-]?)(\d+)$/.match(self.normalize_number)
+				self.is_a?(::Integer) || /^([+-]?)(\d+)$/.match(self.normalize_number)
 			end
 
+      # Checks if the object is a valid float.
+      #
+      # @return [Boolean] `true` is a valid float, `false` otherwise.
 			def is_float?
-				self.is_a?(Float) || /^([+-]?)(\d+)([.,]\d+)?$/.match(self.normalize_number)
+				self.is_a?(::Float) || /^([+-]?)(\d+)([.,]\d+)?$/.match(self.normalize_number)
 			end
 
+      # Checks if the object is a valid boolean value.
+      #
+      # @return [Boolean] `true` is a valid boolean value, `false` otherwise.
 			def is_boolean?
-				self.is_a?(TrueClass) || self.is_a?(FalseClass) || self.is_a?(NilClass) || (self.ensure_string.strip =~ /^(1|0|true|false|yes|no|t|f|y|n)$/i)
+				self.is_a?(::TrueClass) || self.is_a?(::FalseClass) || self.is_a?(::NilClass) || (self.ensure_string.strip =~ /^(1|0|true|false|yes|no|t|f|y|n)$/i)
 			end
 
+      # Makes sure that the object is an array. For non array objects, return a single element array containing the object.
+      #
+      # @return [Array] If the object is an array, then the object itself, a single element array containing the object otherwise.
 			def ensure_array
-				self.is_a?(Array) ? self : [self]
+				self.is_a?(::Array) ? self : [self]
 			end
 
-			def ensure_string
+      # Makes sure that the object is a string. For `nil`, it returns "".
+      #
+      # @return [String] The string representation of the object.
+      def ensure_string
 				self.present? ? self.to_s : ""
 			end
 
-			def to_float(default_value = 0.0)
-        if self.is_a?(Float)
+      # Converts the object to a float.
+      #
+      # @param default_value [Float] The value to return if the conversion is not possible.
+      # @return [Float] The float representation of the object.
+      def to_float(default_value = 0.0)
+        if self.is_a?(::Float)
           self
-        elsif self.is_a?(Integer)
+        elsif self.is_a?(::Integer)
           self.to_f
         else
-				  self.is_float? ? Kernel.Float(self.normalize_number) : default_value
+				  self.is_float? ? ::Kernel.Float(self.normalize_number) : default_value
         end
 			end
 
+      # Converts the object to a integer.
+      #
+      # @param default_value [Fixnum] The value to return if the conversion is not possible.
+      # @return [Fixnum] The integer representation of the object.
 			def to_integer(default_value = 0)
-        if self.is_a?(Integer)
+        if self.is_a?(::Integer)
           self
-        elsif self.is_a?(Float)
+        elsif self.is_a?(::Float)
           self.to_i
         else
-          self.is_integer? ? Kernel.Integer(self.normalize_number) : default_value
+          self.is_integer? ? ::Kernel.Integer(self.normalize_number) : default_value
         end
       end
 
+      # Converts the object to a boolean.
+      #
+      # @return [Boolean] The boolean representation of the object.
 			def to_boolean
         rv = self
-        rv = rv.to_i if rv.is_a?(Float)
+        rv = rv.to_i if rv.is_a?(::Float)
 				(rv.is_a?(TrueClass) || /^(1|on|true|yes|t|y)$/i.match(rv.ensure_string.strip)) ? true : false
 			end
 
+      # Returns the rounded float representaton of the object.
+      #
+      # @param prec [Fixnum] The precision to keep.
+      # @return [Float] The rounded float representaton of the object.
 			def round_to_precision(prec = 2)
         (self.is_number? && prec >= 0) ? number_with_precision(self, :precision => prec) : nil
 			end
 
+      # Formats a number.
+      # @see Settings#setup_format_number
+      #
+      # @param prec [Fixnum] The precision to show.
+      # @param decimal_separator [String] The string to use as decimal separator.
+      # @param add_string [String] The string to append to the number.
+      # @param k_separator [String] The string to use as thousands separator.
+      # @return [String] The string representation of the object.
 			def format_number(prec = nil, decimal_separator = nil, add_string = nil, k_separator = nil)
-        prec = Cowtech::Extensions.settings.format_number[:prec] if prec.nil?
-        decimal_separator = Cowtech::Extensions.settings.format_number[:decimal_separator] if decimal_separator.nil?
-        add_string = Cowtech::Extensions.settings.format_number[:add_string] if add_string.nil?
-        k_separator = Cowtech::Extensions.settings.format_number[:k_separator] if k_separator.nil?
+        prec = ::Cowtech::Extensions.settings.format_number[:prec] if prec.nil?
+        decimal_separator = ::Cowtech::Extensions.settings.format_number[:decimal_separator] if decimal_separator.nil?
+        add_string = ::Cowtech::Extensions.settings.format_number[:add_string] if add_string.nil?
+        k_separator = ::Cowtech::Extensions.settings.format_number[:k_separator] if k_separator.nil?
 
         (self.is_number? && prec >= 0) ? number_to_currency(self, {:precision => prec, :separator => decimal_separator, :delimiter => k_separator, :format => add_string.blank? ? "%n" : "%n %u", :unit => add_string.blank? ? "" : add_string.strip}) : nil
-			end
-
-      def set_defaults_for_format_number
-
       end
 
-			def format_boolean
-        Cowtech::Extensions.settings.boolean_names[self.to_boolean]
+      # Formats a boolean.
+      # @see Settings#setup_boolean_names
+      #
+      # @param true_name [String] The string representation of `true`. Defaults to `Yes`.
+      # @param false_name [String] The string representation of `false`. Defaults to `No`.
+      # @return [String] The string representation of the object.
+			def format_boolean(true_name = nil, false_name = nil)
+        names = {
+          true => true_name || ::Cowtech::Extensions.settings.boolean_names[true],
+          false => false_name || ::Cowtech::Extensions.settings.boolean_names[false]
+        }
+
+        names[self.to_boolean]
 			end
 
+      # Inspects an object.
+      #
+      # @param format The format to use.
+      # @param must_raise [Boolean] If raise a Dump exception.
+      # @return [String] The object inspected and formatted.
 			def debug_dump(format = :yaml, must_raise = true)
 				rv = ""
 
 				begin
 					if format == :pretty_json then
-						rv = JSON.pretty_generate(self)
+						rv = ::JSON.pretty_generate(self)
 					else
 						rv = self.send("to_#{format}")
 					end
@@ -101,7 +158,7 @@ module Cowtech
 					rv = self.inspect
 				end
 
-				must_raise ? raise(Cowtech::Extensions::Exceptions::Dump.new(rv)) : rv
+				must_raise ? raise(::Cowtech::Extensions::Exceptions::Dump.new(rv)) : rv
 			end
 		end
 	end

data/lib/cowtech-extensions/pathname.rb

@@ -6,9 +6,18 @@
 
 module Cowtech
 	module Extensions
+    # Extensions for the Pathname class.
 		module Pathname
-			extend ActiveSupport::Concern
+			extend ::ActiveSupport::Concern
 
+      # Returns all the components that are included in this path.
+      #
+      # ```ruby
+      # Pathname.new("/usr/bin/ruby").components
+      # # => ["usr", "bin", "ruby"]
+      # ```
+      #
+      # @return [Array] A list of all components that are included in this path.
 			def components
         rv = []
 				self.each_filename { |p| rv << p }

data/lib/cowtech-extensions/settings.rb

@@ -0,0 +1,120 @@
+# encoding: utf-8
+#
+# This file is part of the cowtech-extensions gem. Copyright (C) 2011 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Cowtech
+	module Extensions
+    # Settings for the extensions.
+    class Settings
+      # Settings for numbers formatting.
+      attr_reader :format_number
+
+      # String representations of booleans.
+      attr_reader :boolean_names
+
+      # String representations of days and months.
+      attr_reader :date_names
+
+      # Custom date and time formats.
+      attr_reader :date_formats
+
+      # Returns the singleton instance of the settings.
+      #
+      # @return [Settings] The singleton instance of the settings.
+      def self.instance
+        @instance ||= self.new
+      end
+
+      # Initializes a new settings object.
+      def initialize
+        self.setup_format_number
+        self.setup_boolean_names
+        self.setup_date_formats
+        self.setup_date_names
+      end
+
+      # Setups formatters for a number.
+      # @see Object#format_number
+      #
+      # @param prec [Fixnum] The precision to show.
+      # @param decimal_separator [String] The string to use as decimal separator.
+      # @param add_string [String] The string to append to the number.
+      # @param k_separator [String] The string to use as thousands separator.
+      # @return [Hash] The new formatters.
+      def setup_format_number(prec = 2, decimal_separator = ".", add_string = "", k_separator = ",")
+        @format_number = {
+          :prec => prec,
+          :decimal_separator => decimal_separator,
+          :add_string => add_string,
+          :k_separator => k_separator
+        }
+      end
+
+      # Setups strings representation of booleans.
+      # @see Object#format_boolean
+      #
+      # @param true_name [String] The string representation of `true`. Defaults to `Yes`.
+      # @param false_name [String] The string representation of `false`. Defaults to `No`.
+      # @return [Hash] The new representations.
+      def setup_boolean_names(true_name = nil, false_name = nil)
+        true_name ||= "Yes"
+        false_name ||= "No"
+        @boolean_names = {true => true_name, false => false_name}
+      end
+
+      # Setups custom formats for dates and times.
+      # @see DateTime#lstrftime
+      #
+      # @param formats [Hash] The format to add or replace.
+      # @param replace [Boolean] If to discard current formats.
+      # @return [Hash] The new formats.
+      def setup_date_formats(formats = nil, replace = false)
+        formats = {
+            :ct_date => "%Y-%m-%d",
+            :ct_time => "%H:%M:%S",
+            :ct_date_time => "%F %T",
+            :ct_iso_8601 => "%FT%T%z"
+        } if formats.blank?
+
+        if formats.is_a?(Hash) then
+          if !replace then
+            @date_formats ||= {}
+            @date_formats.merge!(formats)
+          else
+            @date_formats = formats
+          end
+
+          @date_formats.each_pair do |k, v| ::Time::DATE_FORMATS[k] = v end
+        end
+
+        @date_formats
+      end
+
+      # Setups strings representation of days and months.
+      # @see DateTime::ClassMethods#days
+      # @see DateTime::ClassMethods#months
+      # @see DateTime#lstrftime
+      #
+      # @param long_months [Array] The string representation of months.
+      # @param short_months [Array] The abbreviated string representation of months.
+      # @param long_days [Array] The string representation of days.
+      # @param short_days [Array] The abbreviated string representation of days.
+      # @return [Hash] The new representations.
+      def setup_date_names(long_months = nil, short_months = nil, long_days = nil, short_days = nil)
+        long_months = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"] if long_months.blank?
+        short_months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] if short_months.blank?
+        long_days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]  if long_days.blank?
+        short_days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]  if short_days.blank?
+
+        @date_names = {
+          :long_months => long_months,
+          :short_months => short_months,
+          :long_days => long_days,
+          :short_days => short_days
+        }
+      end
+    end
+	end
+end

data/lib/cowtech-extensions/string.rb

@@ -6,21 +6,48 @@
 
 module Cowtech
 	module Extensions
+    # Extensions for the String class.
 		module String
-			extend ActiveSupport::Concern
+			extend ::ActiveSupport::Concern
 
+      # Removes accents from the string, normalizing to the normal letter.
+      #
+      # ```ruby
+      # "èòàù".remove_accents
+      # # => "eoau"
+      # ```
+      #
+      # @return The string with all accents removed.
 			def remove_accents
-				self.mb_chars.normalize(:kd).gsub(/[^\x00-\x7F]/n, "").to_s
+        silence_warnings {
+				  self.mb_chars.normalize(:kd).gsub(/[^\x00-\x7F]/n, "").to_s
+        }
 			end
 
+      # Returns the tagged version of a string.
+      #
+      # The string is downcased and spaces are substituted with `-`.
+      #
+      # ```ruby
+      # "ABC cde".untitleize
+      # # => "abc-cde"
+      # ```
+      #
+      # @return [String] The untitleized version of the string.
 			def untitleize
 				self.downcase.gsub(" ", "-")
 			end
 
-			def replace_ampersands
+      # Returns the string with all `&` replaced with `&`.
+      #
+      # @return [String] The string with all `&` replaced with `&`.
+      def replace_ampersands
 				self.gsub(/&(\S+);/, "&\\1;")
 			end
 
+      # Returns the string itself for use in form helpers.
+      #
+      # @return [String] The string itself.
 			def value
 				self
 			end