lotus-utils 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1937436164015390ea262191b1535441167f1e9c
-  data.tar.gz: 65bb8ce1f1d128fdca98e1918f96c08cf9fa4175
+  metadata.gz: 1d04858b6a58f09fa11b7067a9f10b4b936e724b
+  data.tar.gz: 0e7c601a620a91a58516869b34de12013c86d599
 SHA512:
-  metadata.gz: aace7eede8b7e773ea4401d70e5537e89a965d5ed0000ffe9767ad5f78bcd5629080c17755770f3a4358fa61adb63da604df641a685073be6ea2fef9eb44bd88
-  data.tar.gz: 380a90d0b5df6cc0e52bf4bfea010f55e57fc207864268d39d3ba3f6d3f3e86541951fda027edbcef7da968be26779ab88b5e22dfb508b8a8fca86c72638568d
+  metadata.gz: 50dd0f5ae40cec11a6e3b06275988fb1a1535ce42007aaccdf84ba6ec12ff000f9e6ddc67bfb90dab041e5565769cf8c116ffd227f3cdff804cdfeb4ce13101a
+  data.tar.gz: 4136424d1f2efa2082b58adc347ffecedbc4f14200e7cf03609222364a870722e50c2f1e891bddf154bb075fdd0ac1d5072ab67718ca1920430010d52ad29e96

data/CHANGELOG.md

@@ -1,3 +1,38 @@
+## v0.3.0
+### Oct 23, 2014
+
+4f7a8cf 2014-10-22 **Luca Guidi** Use 1/3 less objects when using Lotus::Utils::Kernel.Array
+
+a82437d 2014-10-20 **Luca Guidi** Improved error message for Utils::Class.load!
+
+2a7134d 2014-10-17 **Tom Kadwill** Improved error NameError message by passing in the whole constant name
+
+52c9fe2 2014-10-16 **Luca Guidi** Utils::Hash#to_h return instances of ::Hash in case of nested symbolized data structure
+
+6b9ba7b 2014-09-23 **Luca Guidi** Raise TypeError if nil is passed for PathPrefix#relative_join
+
+28d119f 2014-08-19 **Celso Fernandes** Add BigDecimal coercion to Lotus::Utils::Kernel
+
+a1b7213 2014-08-18 **Luca Guidi** Ensure PathPrefix#relative_join will raise a meaningful error
+
+139c4d5 2014-08-03 **Luca Guidi** Define Boolean, if missing :airplane:
+
+520c021 2014-07-29 **Peter Suschlik** Speedup Lotus::Utils::String#tokenize
+
+2380d62 2014-07-29 **Peter Suschlik** Define Lotus::Utils::Hash#respond_to_missing?
+
+1c300af 2014-07-29 **Peter Suschlik** Define Lotus::Utils::String#responds_to_missing?
+
+46b39e3 2014-07-25 **Luca Guidi** Let Utils::Hash#inspect output to be the same of ::Hash#inspect
+
+5b3e790 2014-07-25 **Luca Guidi** Use composition over inheritance for Lotus::Utils::PathPrefix
+
+6333287 2014-07-09 **Luca Guidi** Specify ::Hash in Lotus::Utils::Kernel.Hash
+
+25e101e 2014-07-09 **Luca Guidi** Use composition over inheritance for Lotus::Utils::Hash
+
+dea7e6b 2014-07-07 **Luca Guidi** Lotus::Utils::String is now a wrapper around a string, instead of inheriting from String.
+
 ## v0.2.0
 ### Jun 23, 2014
 

data/README.md

@@ -9,7 +9,7 @@ Ruby core extentions and class utilities for [Lotus](http://lotusrb.org)
 [![Coverage](http://img.shields.io/coveralls/lotus/utils/master.svg)](https://coveralls.io/r/lotus/utils)
 [![Code Climate](http://img.shields.io/codeclimate/github/lotus/utils.svg)](https://codeclimate.com/github/lotus/utils)
 [![Dependencies](http://img.shields.io/gemnasium/lotus/utils.svg)](https://gemnasium.com/lotus/utils)
-[![Inline Docs](http://inch-pages.github.io/github/lotus/utils.svg)](http://inch-pages.github.io/github/lotus/utils)
+[![Inline Docs](http://inch-ci.org/github/lotus/utils.svg)](http://inch-ci.org/github/lotus/utils)
 
 ## Contact
 
@@ -22,13 +22,15 @@ Ruby core extentions and class utilities for [Lotus](http://lotusrb.org)
 
 ## Rubies
 
-__Lotus::Utils__ supports Ruby (MRI) 2+
+__Lotus::Utils__ supports Ruby (MRI) 2+ and JRuby 1.7 (with 2.0 mode).
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'lotus-utils'
+```ruby
+gem 'lotus-utils'
+```
 
 And then execute:
 

data/lib/lotus/utils/callbacks.rb

@@ -113,7 +113,7 @@ module Lotus
         #
         # @since 0.2.0
         #
-        # @see http://ruby-doc.org/core-2.1.2/Object.html#method-i-freeze
+        # @see http://ruby-doc.org/core/Object.html#method-i-freeze
         #
         # @example
         #   require 'lotus/utils/callbacks'
@@ -225,7 +225,6 @@ module Lotus
           end
         end
 
-        protected
         def hash
           callback.hash
         end

data/lib/lotus/utils/class.rb

@@ -52,7 +52,8 @@ module Lotus
           end
         end
 
-        raise NameError.new(name)
+        full_name = [ (namespace == Object ? nil : namespace), name ].compact.join('::')
+        raise NameError.new("uninitialized constant #{ full_name }")
       end
     end
   end

data/lib/lotus/utils/class_attribute.rb

@@ -8,9 +8,7 @@ module Lotus
     # @see Lotus::Utils::ClassAttribute::ClassMethods
     module ClassAttribute
       def self.included(base)
-        base.class_eval do
-          extend ClassMethods
-        end
+        base.extend ClassMethods
       end
 
       module ClassMethods
@@ -64,7 +62,7 @@ module Lotus
         #   SmallAirplane.engines # => 2
         #   SmallAirplane.wheels  # => 8
         def class_attribute(*attributes)
-          (class << self; self; end).class_eval do
+          singleton_class.class_eval do
             attr_accessor *attributes
           end
 

data/lib/lotus/utils/hash.rb

@@ -2,16 +2,34 @@ module Lotus
   module Utils
     # Hash on steroids
     # @since 0.1.0
-    class Hash < ::Hash
+    class Hash
       # Initialize the hash
       #
-      # @param hash [::Hash, Hash] the value we want to use to initialize this instance
+      # @param hash [#to_h] the value we want to use to initialize this instance
+      # @param blk [Proc] define the default value
       #
-      # @return [Hash] self
+      # @return [Lotus::Utils::Hash] self
       #
       # @since 0.1.0
-      def initialize(hash = {})
-        merge! hash
+      #
+      # @see http://www.ruby-doc.org/core/Hash.html#method-c-5B-5D
+      #
+      # @example Passing a Hash
+      #   require 'lotus/utils/hash'
+      #
+      #   hash = Lotus::Utils::Hash.new('l' => 23)
+      #   hash['l'] # => 23
+      #
+      # @example Passing a block for default
+      #   require 'lotus/utils/hash'
+      #
+      #   hash = Lotus::Utils::Hash.new {|h,k| h[k] = [] }
+      #   hash['foo'].push 'bar'
+      #
+      #   hash.to_h # => { 'foo' => ['bar'] }
+      def initialize(hash = {}, &blk)
+        @hash = hash.to_h
+        @hash.default_proc = blk
       end
 
       # Convert in-place all the keys to Symbol instances, nested hashes are converted too.
@@ -38,6 +56,132 @@ module Lotus
 
         self
       end
+
+      # Returns a new array populated with the keys from this hash
+      #
+      # @return [Array] the keys
+      #
+      # @since 0.3.0
+      #
+      # @see http://www.ruby-doc.org/core/Hash.html#method-i-keys
+      def keys
+        @hash.keys
+      end
+
+      # Deletes the key-value pair and returns the value from hsh whose key is
+      # equal to key.
+      #
+      # @param key [Object] the key to remove
+      #
+      # @return [Object,nil] the value hold by the given key, if present
+      #
+      # @since 0.3.0
+      #
+      # @see http://www.ruby-doc.org/core/Hash.html#method-i-keys
+      def delete(key)
+        @hash.delete(key)
+      end
+
+      # Retrieves the value object corresponding to the key object.
+      #
+      # @param key [Object] the key
+      #
+      # @return [Object,nil] the correspoding value, if present
+      #
+      # @since 0.3.0
+      #
+      # @see http://www.ruby-doc.org/core/Hash.html#method-i-5B-5D
+      def [](key)
+        @hash[key]
+      end
+
+      # Associates the value given by value with the key given by key.
+      #
+      # @param key [Object] the key to assign
+      # @param value [Object] the value to assign
+      #
+      # @since 0.3.0
+      #
+      # @see http://www.ruby-doc.org/core/Hash.html#method-i-5B-5D-3D
+      def []=(key, value)
+        @hash[key] = value
+      end
+
+      # Returns a Ruby Hash as duplicated version of self
+      #
+      # @return [::Hash] the hash
+      #
+      # @since 0.3.0
+      #
+      # @see http://www.ruby-doc.org/core/Hash.html#method-i-to_h
+      def to_h
+        @hash.each_with_object({}) do |(k, v), result|
+          v = v.to_h if v.is_a?(self.class)
+          result[k] = v
+        end
+      end
+
+      alias_method :to_hash, :to_h
+
+      # Converts into a nested array of [ key, value ] arrays.
+      #
+      # @return [::Array] the array
+      #
+      # @since 0.3.0
+      #
+      # @see http://www.ruby-doc.org/core/Hash.html#method-i-to_a
+      def to_a
+        @hash.to_a
+      end
+
+      # Equality
+      #
+      # @return [TrueClass,FalseClass]
+      #
+      # @since 0.3.0
+      def ==(other)
+        @hash == other.to_h
+      end
+
+      alias_method :eql?, :==
+
+      # Returns the hash of the internal @hash
+      #
+      # @return [Fixnum]
+      #
+      # @since 0.3.0
+      def hash
+        @hash.hash
+      end
+
+      # Returns a string describing the internal @hash
+      #
+      # @return [String]
+      #
+      # @since 0.3.0
+      def inspect
+        @hash.inspect
+      end
+
+      # Override Ruby's method_missing in order to provide ::Hash interface
+      #
+      # @api private
+      # @since 0.3.0
+      def method_missing(m, *args, &blk)
+        h = @hash.__send__(m, *args, &blk)
+        h = self.class.new(h) if h.is_a?(::Hash)
+        h
+      rescue NoMethodError
+        raise NoMethodError.new(%(undefined method `#{ m }' for #{ @hash }:#{ self.class }))
+      end
+
+      # Override Ruby's respond_to_missing? in order to support ::Hash interface
+      #
+      # @api private
+      # @since 0.3.0
+      def respond_to_missing?(m, include_private=false)
+        @hash.respond_to?(m, include_private)
+      end
     end
   end
 end

data/lib/lotus/utils/io.rb

@@ -7,9 +7,9 @@ module Lotus
       # Decreases the level of verbosity, during the execution of the given block.
       #
       # Revised version of ActiveSupport's `Kernel.with_warnings` implementation
-      # @see https://github.com/rails/rails/blob/master/activesupport/lib/active_support/core_ext/kernel/reporting.rb#L25
+      # @see https://github.com/rails/rails/blob/v4.1.2/activesupport/lib/active_support/core_ext/kernel/reporting.rb#L25
       #
-      # @param blk [Proc] the block of code that generates warnings.
+      # @yield the block of code that generates warnings.
       #
       # @return [void]
       #
@@ -25,9 +25,9 @@ module Lotus
       #   Lotus::Utils::IO.silence_warnings do
       #     Test::TEST_VALUE = 'redefined'
       #   end
-      def self.silence_warnings(&blk)
+      def self.silence_warnings
         old_verbose, $VERBOSE = $VERBOSE, nil
-        blk.call
+        yield
       ensure
         $VERBOSE = old_verbose
       end

data/lib/lotus/utils/kernel.rb

@@ -2,13 +2,21 @@ require 'set'
 require 'date'
 require 'time'
 require 'pathname'
+require 'bigdecimal'
+
+# Define top level constant Boolean, so it can be easily used by other libraries
+# in coercions DSLs
+#
+# @since 0.3.0
+class Boolean
+end unless defined?(Boolean)
 
 module Lotus
   module Utils
     # Kernel utilities
     # @since 0.1.1
     module Kernel
-      # Coerces the argument to be an array.
+      # Coerces the argument to be an Array.
       #
       # It's similar to Ruby's Kernel.Array, but it applies further
       # transformations:
@@ -23,11 +31,11 @@ module Lotus
       #
       # @since 0.1.1
       #
-      # @see http://www.ruby-doc.org/core-2.1.2/Kernel.html#method-i-Array
+      # @see http://www.ruby-doc.org/core/Kernel.html#method-i-Array
       #
-      # @see http://www.ruby-doc.org/core-2.1.2/Array.html#method-i-flatten
-      # @see http://www.ruby-doc.org/core-2.1.2/Array.html#method-i-compact
-      # @see http://www.ruby-doc.org/core-2.1.2/Array.html#method-i-uniq
+      # @see http://www.ruby-doc.org/core/Array.html#method-i-flatten
+      # @see http://www.ruby-doc.org/core/Array.html#method-i-compact
+      # @see http://www.ruby-doc.org/core/Array.html#method-i-uniq
       #
       # @example Basic Usage
       #   require 'lotus/utils/kernel'
@@ -62,10 +70,14 @@ module Lotus
       #   response = Response.new(200, {}, 'hello')
       #   Lotus::Utils::Kernel.Array(response)         # => [200, {}, "hello"]
       def self.Array(arg)
-        super(arg).flatten.compact.uniq
+        super(arg).dup.tap do |a|
+          a.flatten!
+          a.compact!
+          a.uniq!
+        end
       end
 
-      # Coerces the argument to be a set.
+      # Coerces the argument to be a Set.
       #
       # @param arg [Object] the input
       #
@@ -122,7 +134,7 @@ module Lotus
         raise TypeError.new("can't convert into Set")
       end
 
-      # Coerces the argument to be an hash.
+      # Coerces the argument to be a Hash.
       #
       # @param arg [Object] the input
       #
@@ -132,7 +144,7 @@ module Lotus
       #
       # @since 0.1.1
       #
-      # @see http://www.ruby-doc.org/core-2.1.2/Kernel.html#method-i-Hash
+      # @see http://www.ruby-doc.org/core/Kernel.html#method-i-Hash
       #
       # @example Basic Usage
       #   require 'lotus/utils/kernel'
@@ -190,7 +202,7 @@ module Lotus
         def self.Hash(arg)
           case arg
           when ::Hash                         then arg
-          when ::Array, ::Set                 then Hash[*self.Array(arg)]
+          when ::Array, ::Set                 then ::Hash[*self.Array(arg)]
           when ->(a) { a.respond_to?(:to_h) } then arg.to_h
           else
             super(arg)
@@ -200,7 +212,7 @@ module Lotus
         end
       end
 
-      # Coerces the argument to be an integer.
+      # Coerces the argument to be an Integer.
       #
       # It's similar to Ruby's Kernel.Integer, but it doesn't stop at the first
       # error and raise an exception only when the argument can't be coerced.
@@ -213,7 +225,7 @@ module Lotus
       #
       # @since 0.1.1
       #
-      # @see http://www.ruby-doc.org/core-2.1.2/Kernel.html#method-i-Integer
+      # @see http://www.ruby-doc.org/core/Kernel.html#method-i-Integer
       #
       # @example Basic Usage
       #   require 'bigdecimal'
@@ -305,7 +317,7 @@ module Lotus
       #   Lotus::Utils::Kernel.Integer(input) # => TypeError
       def self.Integer(arg)
         super(arg)
-      rescue ArgumentError, TypeError
+      rescue ArgumentError, TypeError, NoMethodError
         begin
           if arg.respond_to?(:to_i)
             arg.to_i
@@ -319,7 +331,88 @@ module Lotus
         raise TypeError.new "can't convert into Integer"
       end
 
-      # Coerces the argument to be a float.
+      # Coerces the argument to be a BigDecimal.
+      #
+      # @param arg [Object] the argument
+      #
+      # @return [BigDecimal] the result of the coercion
+      #
+      # @raise [TypeError] if the argument can't be coerced
+      #
+      # @since 0.3.0
+      #
+      # @see http://www.ruby-doc.org/stdlib/libdoc/bigdecimal/rdoc/BigDecimal.html
+      #
+      # @example Basic Usage
+      #   require 'lotus/utils/kernel'
+      #
+      #   Lotus::Utils::Kernel.BigDecimal(1)                        # => 1
+      #   Lotus::Utils::Kernel.BigDecimal(1.2)                      # => 1
+      #   Lotus::Utils::Kernel.BigDecimal(011)                      # => 9
+      #   Lotus::Utils::Kernel.BigDecimal(0xf5)                     # => 245
+      #   Lotus::Utils::Kernel.BigDecimal("1")                      # => 1
+      #   Lotus::Utils::Kernel.BigDecimal(Rational(0.3))            # => 0.3
+      #   Lotus::Utils::Kernel.BigDecimal(Complex(0.3))             # => 0.3
+      #   Lotus::Utils::Kernel.BigDecimal(BigDecimal.new(12.00001)) # => 12.00001
+      #   Lotus::Utils::Kernel.BigDecimal(176605528590345446089)
+      #     # => 176605528590345446089
+      #
+      # @example BigDecimal Interface
+      #   require 'lotus/utils/kernel'
+      #
+      #   UltimateAnswer = Struct.new(:question) do
+      #     def to_d
+      #       BigDecimal.new(42)
+      #     end
+      #   end
+      #
+      #   answer = UltimateAnswer.new('The Ultimate Question of Life')
+      #   Lotus::Utils::Kernel.BigDecimal(answer)
+      #     # => #<BigDecimal:7fabfd148588,'0.42E2',9(27)>
+      #
+      # @example Unchecked exceptions
+      #   require 'lotus/utils/kernel'
+      #
+      #   # When nil
+      #   input = nil
+      #   Lotus::Utils::Kernel.BigDecimal(nil) # => TypeError
+      #
+      #   # When true
+      #   input = true
+      #   Lotus::Utils::Kernel.BigDecimal(input) # => TypeError
+      #
+      #   # When false
+      #   input = false
+      #   Lotus::Utils::Kernel.BigDecimal(input) # => TypeError
+      #
+      #   # When Date
+      #   input = Date.today
+      #   Lotus::Utils::Kernel.BigDecimal(input) # => TypeError
+      #
+      #   # When DateTime
+      #   input = DateTime.now
+      #   Lotus::Utils::Kernel.BigDecimal(input) # => TypeError
+      #
+      #   # When Time
+      #   input = Time.now
+      #   Lotus::Utils::Kernel.BigDecimal(input) # => TypeError
+      #
+      #   # Missing #respond_to?
+      #   input = BasicObject.new
+      #   Lotus::Utils::Kernel.BigDecimal(input) # => TypeError
+      def self.BigDecimal(arg)
+        case arg
+        when ->(a) { a.respond_to?(:to_d) } then arg.to_d
+        when Float, Complex, Rational
+          BigDecimal(arg.to_s)
+        else
+          BigDecimal.new(arg)
+        end
+      rescue NoMethodError
+        raise TypeError.new "can't convert into BigDecimal"
+      end
+
+      # Coerces the argument to be a Float.
       #
       # It's similar to Ruby's Kernel.Float, but it doesn't stop at the first
       # error and raise an exception only when the argument can't be coerced.
@@ -332,7 +425,7 @@ module Lotus
       #
       # @since 0.1.1
       #
-      # @see http://www.ruby-doc.org/core-2.1.2/Kernel.html#method-i-Float
+      # @see http://www.ruby-doc.org/core/Kernel.html#method-i-Float
       #
       # @example Basic Usage
       #   require 'bigdecimal'
@@ -443,7 +536,7 @@ module Lotus
         raise TypeError.new "can't convert into Float"
       end
 
-      # Coerces the argument to be a string.
+      # Coerces the argument to be a String.
       #
       # Identical behavior of Ruby's Kernel.Array, still here because we want
       # to keep the interface consistent
@@ -456,7 +549,7 @@ module Lotus
       #
       # @since 0.1.1
       #
-      # @see http://www.ruby-doc.org/core-2.1.2/Kernel.html#method-i-String
+      # @see http://www.ruby-doc.org/core/Kernel.html#method-i-String
       #
       # @example Basic Usage
       #   require 'date'
@@ -529,9 +622,12 @@ module Lotus
       #
       #   # Missing #to_s or #to_str
       #   input = BaseObject.new
-      #   Lotus::Utils::Kernel.Integer(input) # => TypeError
+      #   Lotus::Utils::Kernel.String(input) # => TypeError
       def self.String(arg)
+        arg = arg.to_str if arg.respond_to?(:to_str)
         super(arg)
+      rescue NoMethodError
+        raise TypeError.new "can't convert into String"
       end
 
       # Coerces the argument to be a Date.
@@ -731,7 +827,7 @@ module Lotus
         raise TypeError.new "can't convert into Time"
       end
 
-      # Coerces the argument to be a boolean.
+      # Coerces the argument to be a Boolean.
       #
       # @param arg [Object] the argument
       #

data/lib/lotus/utils/load_paths.rb

@@ -15,7 +15,7 @@ module Lotus
       #
       # @since 0.2.0
       #
-      # @see http://ruby-doc.org/stdlib-2.1.2/libdoc/pathname/rdoc/Pathname.html
+      # @see http://ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html
       # @see Lotus::Utils::Kernel.Pathname
       def initialize(*paths)
         @paths = Array(paths)
@@ -27,8 +27,8 @@ module Lotus
       # @api private
       # @since 0.2.0
       #
-      # @see http://ruby-doc.org/core-2.1.2/Object.html#method-i-clone
-      # @see http://ruby-doc.org/core-2.1.2/Object.html#method-i-dup
+      # @see http://ruby-doc.org/core/Object.html#method-i-clone
+      # @see http://ruby-doc.org/core/Object.html#method-i-dup
       #
       # @example
       #   require 'lotus/utils/load_paths'
@@ -52,16 +52,17 @@ module Lotus
       # It skips duplications and raises an error in case one of the paths
       # doesn't exist.
       #
-      # @param blk [Proc] the block of code to be yielded
+      # @yield [pathname] the block of code that acts on the collection
+      # @yieldparam pathname [Pathname]
       #
       # @return [void]
       #
       # @raise [Errno::ENOENT] if one of the paths doesn't exist
       #
       # @since 0.2.0
-      def each(&blk)
+      def each
         Utils::Kernel.Array(@paths).each do |path|
-          blk.call realpath(path)
+          yield realpath(path)
         end
       end
 
@@ -78,7 +79,7 @@ module Lotus
       #
       # @since 0.2.0
       #
-      # @see http://ruby-doc.org/stdlib-2.1.2/libdoc/pathname/rdoc/Pathname.html
+      # @see http://ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html
       # @see Lotus::Utils::Kernel.Pathname
       # @see Lotus::Utils::LoadPaths#freeze
       #
@@ -119,7 +120,7 @@ module Lotus
       #
       # @since 0.2.0
       #
-      # @see http://ruby-doc.org/core-2.1.2/Object.html#method-i-freeze
+      # @see http://ruby-doc.org/core/Object.html#method-i-freeze
       #
       # @example
       #   require 'lotus/utils/load_paths'

data/lib/lotus/utils/path_prefix.rb

@@ -3,7 +3,7 @@ module Lotus
     # Prefixed string
     #
     # @since 0.1.0
-    class PathPrefix < ::String
+    class PathPrefix
       # Initialize the path prefix
       #
       # @param string [::String] the prefix value
@@ -14,11 +14,11 @@ module Lotus
       # @since 0.1.0
       def initialize(string = nil, separator = '/')
         @separator = separator
-        super(string.to_s)
+        @string    = string.to_s
       end
 
       # Joins self with the given token.
-      # It cleanups the all the `separator` repetitions.
+      # It cleans up all the `separator` repetitions.
       #
       # @param string [::String] the token we want to join
       #
@@ -41,13 +41,16 @@ module Lotus
       end
 
       # Joins self with the given token, without prefixing it with `separator`.
-      # It cleanups the all the `separator` repetitions.
+      # It cleans up all the `separator` repetitions.
       #
       # @param string [::String] the token we want to join
       # @param separator [::String] the separator used between tokens
       #
       # @return [::String] the joined string
       #
+      # @raise [TypeError] if one of the argument can't be treated as a
+      #   string
+      #
       # @since 0.1.0
       #
       # @example
@@ -57,16 +60,47 @@ module Lotus
       #   path_prefix.relative_join 'new'      # => 'posts/new'
       #   path_prefix.relative_join 'new', '_' # => 'posts_new'
       def relative_join(string, separator = @separator)
-        separator = separator || @separator
-        relativize [self, string].join(separator), separator
+        raise TypeError if separator.nil?
+        relativize [@string, string].join(separator), separator
+      end
+
+      # Returns the hash of the internal string
+      #
+      # @return [Fixnum]
+      #
+      # @since 0.3.0
+      def hash
+        @string.hash
       end
 
+      # Returns a string representation
+      #
+      # @return [String]
+      #
+      # @since 0.3.0
+      def to_s
+        @string
+      end
+
+      alias_method :to_str,  :to_s
+
+      # Equality
+      #
+      # @return [TrueClass,FalseClass]
+      #
+      # @since 0.3.0
+      def ==(other)
+        to_s == other
+      end
+
+      alias_method :eql?, :==
+
       private
       attr_reader :separator
 
       def absolutize(string)
         string.tap do |s|
-          s.insert(0, separator) unless absolute?(s)
+          s.prepend(separator) unless absolute?(s)
         end
       end
 

data/lib/lotus/utils/string.rb

@@ -3,16 +3,43 @@ module Lotus
     # String on steroids
     #
     # @since 0.1.0
-    class String < ::String
+    class String
       # Separator between Ruby namespaces
       #
-      # @example
-      #   Lotus::Utils
-      #
       # @since 0.1.0
       # @api private
       NAMESPACE_SEPARATOR = '::'.freeze
 
+      # Separator for #classify
+      #
+      # @since 0.3.0
+      # @api private
+      CLASSIFY_SEPARATOR  = '_'.freeze
+
+      # Regexp for #tokenize
+      #
+      # @since 0.3.0
+      # @api private
+      TOKENIZE_REGEXP     = /\((.*)\)/
+
+      # Separator for #tokenize
+      #
+      # @since 0.3.0
+      # @api private
+      TOKENIZE_SEPARATOR  = '|'.freeze
+
+      # Separator for #underscore
+      #
+      # @since 0.3.0
+      # @api private
+      UNDERSCORE_SEPARATOR = "/".freeze
+
+      # gsub second parameter used in #underscore
+      #
+      # @since 0.3.0
+      # @api private
+      UNDERSCORE_DIVISION_TARGET  = '\1_\2'.freeze
+
       # Initialize the string
       #
       # @param string [::String, Symbol] the value we want to initialize
@@ -21,7 +48,7 @@ module Lotus
       #
       # @since 0.1.0
       def initialize(string)
-        super(string.to_s)
+        @string = string.to_s
       end
 
       # Return a CamelCase version of the string
@@ -36,12 +63,12 @@ module Lotus
       #   string = Lotus::Utils::String.new 'lotus_utils'
       #   string.classify # => 'LotusUtils'
       def classify
-        split('_').map {|token| token.slice(0).upcase + token.slice(1..-1) }.join
+        self.class.new split(CLASSIFY_SEPARATOR).map(&:capitalize).join
       end
 
       # Return a downcased and underscore separated version of the string
       #
-      # Revised version of `ActiveSupport::Inflector.underscore` implementation 
+      # Revised version of `ActiveSupport::Inflector.underscore` implementation
       # @see https://github.com/rails/rails/blob/feaa6e2048fe86bcf07e967d6e47b865e42e055b/activesupport/lib/active_support/inflector/methods.rb#L90
       #
       # @return [String] the transformed string
@@ -54,10 +81,11 @@ module Lotus
       #   string = Lotus::Utils::String.new 'LotusUtils'
       #   string.underscore # => 'lotus_utils'
       def underscore
-        gsub(NAMESPACE_SEPARATOR, '/').
-          gsub(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2').
-          gsub(/([a-z\d])([A-Z])/,'\1_\2').
-          downcase
+        new_string = gsub(NAMESPACE_SEPARATOR, UNDERSCORE_SEPARATOR)
+        new_string.gsub!(/([A-Z\d]+)([A-Z][a-z])/, UNDERSCORE_DIVISION_TARGET)
+        new_string.gsub!(/([a-z\d])([A-Z])/, UNDERSCORE_DIVISION_TARGET)
+        new_string.downcase!
+        self.class.new new_string
       end
 
       # Return the string without the Ruby namespace of the class
@@ -75,7 +103,7 @@ module Lotus
       #   string = Lotus::Utils::String.new 'String'
       #   string.demodulize # => 'String'
       def demodulize
-        split(NAMESPACE_SEPARATOR).last
+        self.class.new split(NAMESPACE_SEPARATOR).last
       end
 
       # Return the top level namespace name
@@ -93,13 +121,13 @@ module Lotus
       #   string = Lotus::Utils::String.new 'String'
       #   string.namespace # => 'String'
       def namespace
-        split(NAMESPACE_SEPARATOR).first
+        self.class.new split(NAMESPACE_SEPARATOR).first
       end
 
       # It iterates thru the tokens and calls the given block.
       # A token is a substring wrapped by `()` and separated by `|`.
       #
-      # @param blk [Proc, #call] the block that is called for each token.
+      # @yield the block that is called for each token.
       #
       # @return [void]
       #
@@ -116,16 +144,92 @@ module Lotus
       #   # =>
       #     'Lotus::Utils'
       #     'Lotus::App'
-      def tokenize(&blk)
-        template = gsub(/\((.*)\)/, "%{token}")
-        tokens   = Array(( $1 || self ).split('|'))
-
-        tokens.each do |token|
-          blk.call(template % {token: token})
+      def tokenize
+        if match = TOKENIZE_REGEXP.match(@string)
+          pre, post = match.pre_match, match.post_match
+          tokens = match[1].split(TOKENIZE_SEPARATOR)
+          tokens.each do |token|
+            yield(self.class.new("#{pre}#{token}#{post}"))
+          end
+        else
+          yield(self.class.new(@string))
         end
 
         nil
       end
+
+      # Returns the hash of the internal string
+      #
+      # @return [Fixnum]
+      #
+      # @since 0.3.0
+      def hash
+        @string.hash
+      end
+
+      # Returns a string representation
+      #
+      # @return [String]
+      #
+      # @since 0.3.0
+      def to_s
+        @string
+      end
+
+      alias_method :to_str,  :to_s
+
+      # Equality
+      #
+      # @return [TrueClass,FalseClass]
+      #
+      # @since 0.3.0
+      def ==(other)
+        to_s == other
+      end
+
+      alias_method :eql?, :==
+
+      # Split the string with the given pattern
+      #
+      # @return [Array<String>]
+      #
+      # @see http://www.ruby-doc.org/core/String.html#method-i-split
+      #
+      # @since 0.3.0
+      def split(pattern, limit = 0)
+        @string.split(pattern, limit)
+      end
+
+      # Replace the given pattern with the given replacement
+      #
+      # @return [String,nil]
+      #
+      # @see http://www.ruby-doc.org/core/String.html#method-i-gsub
+      #
+      # @since 0.3.0
+      def gsub(pattern, replacement, &blk)
+        @string.gsub(pattern, replacement, &blk)
+      end
+
+      # Override Ruby's method_missing in order to provide ::String interface
+      #
+      # @api private
+      # @since 0.3.0
+      def method_missing(m, *args, &blk)
+        s = @string.__send__(m, *args, &blk)
+        s = self.class.new(s) if s.is_a?(::String)
+        s
+      rescue NoMethodError
+        raise NoMethodError.new(%(undefined method `#{ m }' for "#{ @string }":#{ self.class }))
+      end
+
+      # Override Ruby's respond_to_missing? in order to support ::String interface
+      #
+      # @api private
+      # @since 0.3.0
+      def respond_to_missing?(m, include_private=false)
+        @string.respond_to?(m, include_private)
+      end
     end
   end
 end

data/lib/lotus/utils/version.rb

@@ -1,5 +1,5 @@
 module Lotus
   module Utils
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'.freeze
   end
 end

data/lotus-utils.gemspec

@@ -17,7 +17,9 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.0.0'
 
-  spec.add_development_dependency 'bundler', '~> 1.6'
-  spec.add_development_dependency 'rake',    '~> 10'
+  spec.add_development_dependency 'bundler',  '~> 1.6'
+  spec.add_development_dependency 'rake',     '~> 10'
+  spec.add_development_dependency 'minitest', '~> 5.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lotus-utils
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Luca Guidi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-23 00:00:00.000000000 Z
+date: 2014-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.4'
 description: Lotus utilities
 email:
 - me@lucaguidi.com
@@ -72,7 +86,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="