corefines 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a692c4abce603d86050acd275daec0cdd2c303e6
+  data.tar.gz: 7d8a10a41f2eff14a549d7f192ed1485ecf2348e
+SHA512:
+  metadata.gz: 8507ca0ade2ee56e6e430a552fc5edfd32a28dbe9e434b61f8b884143a9cf25c604b3ce71b5f76dbec7663a77cda404cde7689569cbca89e7c0f568dfb046a7d
+  data.tar.gz: e3136911b789c35cdc559c0280fcd31bae9a64f6465b7a8eaa3428e1a368da021e65c69c406a2c3e2bf7320897739f6571d6d586054e43945e00f01826a8ac62

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright 2015 Jakub Jirutka <jakub@jirutka.cz>.
+
+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.adoc

@@ -0,0 +1,198 @@
+= Corefines
+Jakub Jirutka <https://github.com/jirutka[@jirutka]>
+:page-layout: base
+:idprefix:
+ifdef::env-github[:idprefix: user-content-]
+:idseparator: -
+:source-language: ruby
+:language: {source-language}
+// custom
+:gem-name: corefines
+:gh-name: jirutka/{gem-name}
+:gh-branch: master
+:badge-style: flat
+:doc-base-url: http://www.rubydoc.info/github/jirutka/corefines/Corefines
+
+ifdef::env-github[]
+image:https://img.shields.io/travis/{gh-name}/{gh-branch}.svg?style={badge-style}[Build Status, link="https://travis-ci.org/{gh-name}"]
+image:https://img.shields.io/codeclimate/coverage/github/{gh-name}.svg?style={badge-style}[Test Coverage, link="https://codeclimate.com/github/{gh-name}"]
+image:https://img.shields.io/codeclimate/github/{gh-name}.svg?style={badge-style}[Code Climate, link="https://codeclimate.com/github/{gh-name}"]
+image:https://img.shields.io/gem/v/{gem-name}.svg?style={badge-style}[Gem Version, link="https://rubygems.org/gems/{gem-name}"]
+image:https://img.shields.io/badge/yard-docs-blue.svg?style={badge-style}[Yard Docs, link="http://www.rubydoc.info/github/{gh-name}/frames"]
+endif::env-github[]
+
+Corefines is a collection of general purpose _refinements_ for extending the core capabilities of Ruby’s built-in classes.
+It also provides a <<compatibility-mode>> for older Ruby versions and alternative Ruby implementations that don’t support refinements (yet).
+
+
+== Why refinements?
+
+Extending core classes with so called monkey-paching pollutes the _global_ scope, so it affects all files on the `$LOAD_PATH`, i.e. whole application including used gems.
+It’s not usually so big deal when you’re doing it in your application, but it’s very dangerous when used in a gem (library).
+This can result in strange and hard to debug behaviour if another gem overrides a core class with the same method as your gem, but different implementation, and both gems are used together.
+
+Refinements basically allows you to put monkey patches in an isolated namespace, so that your changes to core classes don’t affect other code.
+
+TODO
+
+
+== Installation
+
+Add this line to your application’s Gemfile:
+
+[source]
+gem 'corefines', '~> 1.0'
+
+or to your gemspec:
+
+[source]
+s.add_runtime_dependency 'corefines', '~> 1.0'
+
+and then execute:
+
+[source, sh]
+$ bundle install
+
+
+== Using
+
+First, you must require `corefines` prior using:
+
+[source]
+require 'corefines'
+
+This will _not_ activate any extensions (just register them), even when running in compatibility mode.
+Extensions (refinements) are activated selectively with the method http://ruby-doc.org/core-2.2.0/Module.html#method-i-using[`using`].
+
+Refinements are organized into modules by class which they refine, and further into submodules for individual methods.
+When an extension refines multiple classes, then it’s included in a module named after their nearest common ancestor (superclass).
+
+[source, plain]
+Corefines::<CLASS>::<METHOD>
+
+A single extension can be imported into the current scope classically, e.g.:
+
+[source]
+using Corefines::Object::ThenIf
+
+or preferably using its “alias”:
+
+[source]
+using Corefines::Object::then_if
+
+If you want to include all extensions for the class, then you can just import the parent module, e.g.:
+
+[source]
+using Corefines::Object
+
+But more often you want to include multiple extensions for the class, but not all of them, e.g.:
+
+[source]
+using Corefines::Object::then_if
+using Corefines::Object::in?
+
+this can be abbreviated to:
+
+[source]
+using Corefines::Object[:then_if, :in?]
+
+If you feel that _Corefines_ is too long, then you can also use abbreviation _CF_ instead:
+
+[source]
+using CF::Object::then_if
+
+Refinements can be activated (with `using`) at top-level (per file), inside a class, module or a method.
+
+
+== Compatibility mode
+
+Refinements are still a young feature, so there’s a possibility that your gem or application will have to work on a Ruby platform that doesn’t fully support refinements yet.
+
+The main Ruby implementation, https://en.wikipedia.org/wiki/Ruby_MRI[MRI] (aka CRuby), supports refinements since version 2.1.0 (https://www.ruby-lang.org/en/news/2013/12/25/ruby-2-1-0-is-released/[released in 25 Dec 2013]).
+footnote:[Actually, refinements has been introduced to MRI in 2.0.0, as an experimental feature. However, its design and implementation has been changed then, so refinements in 2.0.x and 2.1+ behaves quite differently.]
+Version 2.0.0 (https://www.ruby-lang.org/en/news/2013/02/24/ruby-2-0-0-p0-is-released/[released in 24 Feb 2013]) is still supported though.
+http://www.jruby.org/[JRuby] doesn’t support refinements yet, it’s planned in the upcoming version 9.0.0.0 (https://github.com/jruby/jruby/issues/1062[#1062]).
+http://rubini.us/[Rubinius] also doesn’t support refinements yet.
+
+This gem is a collection of pure refinements, and yet, it works even on older Rubies that don’t support refinements.
+Wait… how?
+Well, when you use the gem with an older Ruby, it’s actually cheating.
+Instead of locally scoped changes, it falls back to global monkey-patching.
+
+The Corefines gem adds `refine` and `using` methods to the core classes, so you can define and use refinements just like in newer Rubies.
+But internally it works very differently.
+The `refine` method adds a given block to a collection of pending “refinements” inside its module.
+When `using` is called _first time_ for the module, it _evaluates_ module’s “refinements” in context of the target classes (i.e. do a monkey-patch).
+
+Not ideal indeed, but probably the best of what we can achieve.
+
+
+== List of refinements
+
+* {doc-base-url}/Array[Array]
+** {doc-base-url}/Array/Second[#second]
+** {doc-base-url}/Array/Third[#third]
+* {doc-base-url}/Enumerable[Enumerable]
+** {doc-base-url}/Enumerable/IndexBy[#index_by]
+** {doc-base-url}/Enumerable/MapSend[#map_send]
+* {doc-base-url}/Hash[Hash]
+** {doc-base-url}/Hash/OpPlus[#+]
+** {doc-base-url}/Hash/Compact[#compact]
+** {doc-base-url}/Hash/Compact[#compact!]
+** {doc-base-url}/Hash/Rekey[#rekey]
+** {doc-base-url}/Hash/Rekey[#rekey!]
+** {doc-base-url}/Hash/SymbolizeKeys[#symbolize_keys]
+** {doc-base-url}/Hash/SymbolizeKeys[#symbolize_keys!]
+* {doc-base-url}/Module[Module]
+** {doc-base-url}/Module/AliasClassMethod[#alias_class_method]
+** {doc-base-url}/Module/AliasMethodChain[#alias_method_chain]
+* {doc-base-url}/Object[Object]
+** {doc-base-url}/Object/Blank[#blank?]
+** {doc-base-url}/Object/DeepDup[#deep_dup]
+** {doc-base-url}/Object/Else[#else]
+** {doc-base-url}/Object/In[#in?]
+** {doc-base-url}/Object/InstanceValues[#instance_values]
+** {doc-base-url}/Object/Blank[#presence]
+** {doc-base-url}/Object/Then[#then]
+** {doc-base-url}/Object/ThenIf[#then_if]
+** {doc-base-url}/Object/Try[#try]
+** {doc-base-url}/Object/Try[#try!]
+* {doc-base-url}/String[String]
+** {doc-base-url}/String/Color[#color]
+** {doc-base-url}/String/Concat[#concat]
+** {doc-base-url}/String/Decolor[#decolor]
+** {doc-base-url}/String/Remove[#remove]
+** {doc-base-url}/String/Unindent[#unindent] (alias `#strip_heredoc`)
+* {doc-base-url}/Symbol[Symbol]
+** {doc-base-url}/Symbol/Call[#call]
+
+
+== Acknowledgement
+
+Most of the extension methods are based on, or highly inspired from:
+
+* https://github.com/rails/rails/tree/master/activesupport[Active Support (Ruby extensions)]
+* https://github.com/rubyworks/facets[Ruby Facets]
+* https://github.com/gregwebs/methodchain[methodchain]
+* https://github.com/fazibear/colorize[colorize]
+
+Very useful articles about refinements and how to “trick” them:
+
+* https://www.new-bamboo.co.uk/blog/2014/02/05/refinements-under-the-knife/[
+Refinements under the knife] by https://github.com/leemachin[@leemachin]
+* http://qiita.com/joker1007/items/68d066a12bc763bd2cb4[Refinement関係の小技とできない事をまとめてみた] by https://github.com/joker1007[@joker1007]
+
+
+== Contributing
+
+. Fork it.
+. Create your feature branch (`git checkout -b my-new-feature`).
+. Commit your changes (`git commit -am 'Add some feature'`).
+. Push to the branch (`git push origin my-new-feature`).
+. Create a new Pull Request.
+
+
+== License
+
+This project is licensed under http://opensource.org/licenses/MIT/[MIT License].
+For the full text of the license, see the link:LICENSE[LICENSE] file.

data/Rakefile

@@ -0,0 +1,23 @@
+require 'bundler/gem_tasks'
+
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec)
+
+  task :test => :spec
+  task :default => :spec
+
+rescue LoadError => e
+  warn "#{e.path} is not available"
+end
+
+begin
+  require 'yard'
+
+  # options are defined in .yardopts
+  YARD::Rake::YardocTask.new(:yard)
+
+rescue LoadError => e
+  warn "#{e.path} is not available"
+end

data/lib/corefines/array.rb

@@ -0,0 +1,30 @@
+require 'corefines/support/alias_submodules'
+
+module Corefines
+  module Array
+
+    ##
+    # @!method second
+    #   @return the second element, or +nil+ if doesn't exist.
+    module Second
+      refine ::Array do
+        def second
+          self[1]
+        end
+      end
+    end
+
+    ##
+    # @!method third
+    #   @return the third element, or +nil+ if doesn't exist.
+    module Third
+      refine ::Array do
+        def third
+          self[2]
+        end
+      end
+    end
+
+    include Support::AliasSubmodules
+  end
+end

data/lib/corefines/enumerable.rb

@@ -0,0 +1,64 @@
+require 'corefines/support/alias_submodules'
+require 'corefines/support/classes_including_module'
+
+module Corefines
+  module Enumerable
+
+    ##
+    # @!method index_by
+    #   Convert enumerable into a Hash, iterating over each element where the
+    #   provided block must return the key to be used to map to the value.
+    #
+    #   It's similar to {::Enumerable#group_by}, but when two elements
+    #   corresponds to the same key, then only the last one is preserved in the
+    #   resulting Hash.
+    #
+    #   @example
+    #     people.index_by(&:login)
+    #     => { "flynn" => <Person @login="flynn">, "bradley" => <Person @login="bradley">, ...}
+    #
+    #   @example
+    #     people.index_by.each(&:login)
+    #     => { "flynn" => <Person @login="flynn">, "bradley" => <Person @login="bradley">, ...}
+    #
+    #   @yield [obj] gives each element to the block.
+    #   @yieldreturn the key to be used to map to the value.
+    #   @return [Hash]
+    #
+    module IndexBy
+      Support.classes_including_module(::Enumerable) do |klass|
+
+        refine klass do
+          def index_by
+            ::Hash[map { |elem| [ yield(elem), elem ] }]
+          end
+        end
+      end
+    end
+
+    ##
+    # @!method map_send(method_name, *args, &block)
+    #   Sends a message to each element and collects the result.
+    #
+    #   @example
+    #     [1, 2, 3].map_send(:+, 3) #=> [4, 5, 6]
+    #
+    #   @param method_name [Symbol] name of the method to call.
+    #   @param args arguments to pass to the method.
+    #   @param block [Proc] block to pass to the method.
+    #   @return [Enumerable]
+    #
+    module MapSend
+      Support.classes_including_module(::Enumerable) do |klass|
+
+        refine klass do
+          def map_send(method_name, *args, &block)
+            map { |e| e.__send__(method_name, *args, &block) }
+          end
+        end
+      end
+    end
+
+    include Support::AliasSubmodules
+  end
+end

data/lib/corefines/hash.rb

@@ -0,0 +1,164 @@
+require 'corefines/support/alias_submodules'
+
+module Corefines
+  module Hash
+
+    ##
+    # @!method compact
+    #   @example
+    #     hash = { a: true, b: false, c: nil }
+    #     hash.compact # => { a: true, b: false }
+    #     hash # => { a: true, b: false, c: nil }
+    #     { c: nil }.compact # => {}
+    #
+    #   @return [Hash] a new hash with no key-value pairs which value is +nil+.
+    #
+    # @!method compact!
+    #   Removes all key-value pairs from the hash which value is +nil+.
+    #   Same as {#compact}, but modifies +self+.
+    #
+    #   @return [Hash] self
+    #
+    module Compact
+      refine ::Hash do
+        def compact
+          reject { |_, value| value.nil? }
+        end
+
+        def compact!
+          delete_if { |_, value| value.nil? }
+        end
+      end
+    end
+
+    ##
+    # @!method +(other_hash)
+    #   Alias for +#merge+.
+    #
+    #   @example
+    #     {a: 1, b: 2} + {b: 3, c: 4}
+    #      => {a: 1, b: 3, c: 4}
+    #
+    #   @param other_hash [Hash]
+    #   @return [Hash] a new hash containing the contents of _other_hash_ and
+    #     this hash. The value for entries with duplicate keys will be that of
+    #     _other_hash_.
+    #
+    module OpPlus
+      refine ::Hash do
+        def +(other_hash)
+          merge other_hash
+        end
+      end
+    end
+
+    ##
+    # @!method rekey(key_map = nil, &block)
+    #   Returns a new hash with keys transformed according to the given
+    #   _key_map_ or the _block_.
+    #
+    #   If no _key_map_ or _block_ is given, then all keys are converted
+    #   to +Symbols+, as long as they respond to +to_sym+.
+    #
+    #   @example
+    #     hash = { :a => 1, 'b' => 2 }
+    #     hash.rekey(:a => :x, :c => :y) # => { :x => 1, 'b' => 2 }
+    #     hash.rekey(&:to_s) # => { 'a' => 1, 'b' => 2 }
+    #     hash.rekey { |k| k.to_s.upcase } # => { 'A' => 1, 'B' => 2 }
+    #     hash.rekey # => { :a => 1, :b => 2 }
+    #
+    #   @overload rekey(key_map)
+    #     @param key_map [Hash] a translation map from the old keys to the new
+    #       keys; <tt>{from_key => to_key, ...}</tt>.
+    #
+    #   @overload rekey
+    #     @yield [key, value] gives every key-value pair to the block.
+    #       The return value becomes a new key.
+    #
+    #   @return [Hash] a new hash.
+    #   @raise ArgumentError if both _key_map_ and the _block_ are given.
+    #
+    # @!method rekey!(key_map = nil, &block)
+    #   Transforms keys according to the given _key_map_ or the _block_.
+    #   Same as {#rekey}, but modifies +self+.
+    #
+    #   @overload rekey!(key_map)
+    #     @param key_map [Hash] a translation map from the old keys to the new
+    #       keys; <tt>{from_key => to_key, ...}</tt>.
+    #
+    #   @overload rekey!
+    #     @yield [key, value] gives every key-value pair to the block.
+    #       The return value becomes a new key.
+    #
+    #   @return [Hash] self
+    #   @raise (see #rekey)
+    #
+    module Rekey
+      refine ::Hash do
+        def rekey(key_map = nil, &block)
+          fail ArgumentError, "provide key_map, or block, not both" if key_map && block
+          block = ->(k, _) { k.to_sym rescue k } if !key_map && !block
+
+          # Note: self.dup is used to preserve the default_proc.
+          if block
+            # This is needed for "symbol procs" (e.g. &:to_s).
+            transform_key = block.arity.abs == 1 ? ->(k, _) { block[k] } : block
+
+            each_with_object(dup.clear) do |(key, value), hash|
+              hash[ transform_key[key, value] ] = value
+            end
+          else
+            key_map.each_with_object(dup) do |(from, to), hash|
+              hash[to] = hash.delete(from) if hash.key? from
+            end
+          end
+        end
+
+        def rekey!(key_map = nil, &block)
+          replace rekey(key_map, &block)
+        end
+      end
+    end
+
+    ##
+    # @!method symbolize_keys
+    #   @example
+    #     hash = { 'name' => 'Lindsey', :born => 1986 }
+    #     hash.symbolize_keys # => { :name => 'Lindsey', :born => 1986 }
+    #     hash # => { 'name' => 'Lindsey', :born => 1986 }
+    #
+    #   @return [Hash] a new hash with all keys converted to symbols, as long
+    #     as they respond to +to_sym+.
+    #
+    # @!method symbolize_keys!
+    #   Converts all keys to symbols, as long as they respond to +to_sym+.
+    #   Same as {#symbolize_keys}, but modifies +self+.
+    #
+    #   @return [Hash] self
+    #
+    module SymbolizeKeys
+      refine ::Hash do
+        def symbolize_keys
+          each_with_object(dup.clear) do |(key, value), hash|
+            hash[(key.to_sym rescue key)] = value
+          end
+        end
+
+        def symbolize_keys!
+          keys.each do |key|
+            self[(key.to_sym rescue key)] = delete(key)
+          end
+          self
+        end
+      end
+    end
+
+    include Support::AliasSubmodules
+
+    class << self
+      alias_method :compact!, :compact
+      alias_method :rekey!, :rekey
+      alias_method :symbolize_keys!, :symbolize_keys
+    end
+  end
+end

data/lib/corefines/module.rb

@@ -0,0 +1,95 @@
+require 'corefines/support/alias_submodules'
+
+module Corefines
+  module Module
+    ##
+    # @!method alias_class_method(new_name, old_name)
+    #   Makes _new_name_ a new copy of the class method _old_name_.
+    #
+    #   @param new_name [Symbol] name of the new class method to create.
+    #   @param old_name [Symbol] name of the existing class method to alias.
+    #   @return [self]
+    #
+    module AliasClassMethod
+      refine ::Module do
+        def alias_class_method(new_name, old_name)
+          singleton_class.__send__(:alias_method, new_name, old_name)
+          self
+        end
+      end
+    end
+
+    ##
+    # @!method alias_method_chain(target, feature)
+    #   Encapsulates the common pattern of:
+    #
+    #     alias_method :meth_without_feature, :meth
+    #     alias_method :meth, :meth_with_feature
+    #
+    #   With this, you simply do:
+    #
+    #     alias_method_chain :meth, :feature
+    #
+    #   for example:
+    #
+    #     class ChainExample
+    #       def say
+    #         "hello"
+    #       end
+    #       def say_with_accent
+    #         "helloo!"
+    #       end
+    #       alias_method_chain :say, :accent
+    #     end
+    #
+    #   and both aliases are set up for you:
+    #
+    #     example = ChainExample.new
+    #     example.say #=> "helloo!"
+    #     example.say_without_accent #=> "hello"
+    #
+    #   Query and bang methods (+foo?+, +foo!+) keep the same punctuation:
+    #
+    #     alias_method_chain :say!, :accent
+    #
+    #   is equivalent to:
+    #
+    #     alias_method :say_without_accent!, :say!
+    #     alias_method :say!, :say_with_accent!
+    #
+    #   so you can safely chain +foo+, +foo?+, and +foo!+ with the same
+    #   feature.
+    #
+    #   @param target [Symbol] name of the method to alias.
+    #   @param feature [Symbol] suffix for the aliases.
+    #   @return [self]
+    #
+    module AliasMethodChain
+      refine ::Module do
+        def alias_method_chain(target, feature)
+          # Strip out punctuation on predicates, bang or writer methods since
+          # e.g. target?_without_feature is not a valid method name.
+          aliased_target, punctuation = target.to_s.sub(/([?!=])$/, ''), $1
+
+          with_method = "#{aliased_target}_with_#{feature}#{punctuation}"
+          without_method = "#{aliased_target}_without_#{feature}#{punctuation}"
+
+          alias_method without_method, target
+          alias_method target, with_method
+
+          if public_method_defined? without_method
+            public target
+          elsif protected_method_defined? without_method
+            protected target
+          elsif private_method_defined? without_method
+            private target
+          end
+
+          self
+        end
+      end
+    end
+
+    include Support::AliasSubmodules
+  end
+end