corefines 1.0.0

data/lib/corefines/object.rb

@@ -0,0 +1,389 @@
+require 'corefines/support/alias_submodules'
+require 'set'
+
+module Corefines
+  module Object
+    ##
+    # @!method blank?
+    #   An object is blank if it's +false+, empty, or a whitespace string.
+    #   For example, <tt>'', '   ', "\t\n\r", "\u00a0", nil, [], {}</tt> are
+    #   all blank.
+    #
+    #   This simplifies
+    #
+    #     address.nil? || address.empty?
+    #
+    #   to
+    #
+    #     address.blank?
+    #
+    #   @return [Boolean]
+    #
+    # @!method presence
+    #   Returns object if it's not {#blank?}, otherwise returns +nil+.
+    #   +obj.presence+ is equivalent to <tt>obj.blank? ? nil : obj</tt>.
+    #
+    #   This is handy for any representation of objects where blank is the same
+    #   as not present at all. For example, this simplifies a common check for
+    #   HTTP POST/query parameters:
+    #
+    #     state = params[:state] if params[:state].present?
+    #     country = params[:country] if params[:country].present?
+    #     region = state || country || 'CZ'
+    #
+    #   becomes...
+    #
+    #     region = params[:state].presence || params[:country].presence || 'CZ'
+    #
+    #   @return [Object, nil] object if it's not {#blank?}, otherwise +nil+.
+    #
+    module Blank
+
+      BLANK_RE = /\A[[:space:]]*\z/
+
+      refine ::Object do
+        def blank?
+          respond_to?(:empty?) ? !!empty? : !self
+        end
+
+        def presence
+          self unless blank?
+        end
+      end
+
+      refine ::NilClass do
+        def blank?
+          true
+        end
+      end
+
+      refine ::FalseClass do
+        def blank?
+          true
+        end
+      end
+
+      refine ::TrueClass do
+        def blank?
+          false
+        end
+      end
+
+      refine ::Array do
+        alias_method :blank?, :empty?
+      end
+
+      refine ::Hash do
+        alias_method :blank?, :empty?
+      end
+
+      refine ::Numeric do
+        def blank?
+          false
+        end
+      end
+
+      refine ::String do
+        def blank?
+          BLANK_RE === self
+        end
+      end
+    end
+
+    ##
+    # @!method deep_dup
+    #   Returns a deep copy of itself.
+    #
+    #   If +self+ is an instance of +Array+, +Set+ or +Hash+, then it
+    #   recursively copies its elements as well. If a nested object responds to
+    #   +deep_dup+ (note: +respond_to?+ doesn't see refined methods), then it
+    #   use it.
+    #
+    #   @return [Object] a copy of +self+, or +self+ if it's not duplicable.
+    #
+    module DeepDup
+      refine ::Object do
+        # NOTE: Refinement is not active inside itself, so we can't simply call
+        # deep_dup on a nested object like ActiveSupport does. Thus we must use
+        # this ugly approach instead...
+        def deep_dup(obj = self)
+          return obj.deep_dup if obj != self && obj.respond_to?(:deep_dup)
+
+          case obj
+          when ::NilClass, ::FalseClass, ::TrueClass, ::Symbol, ::Numeric, ::Method
+            obj  # not duplicable
+          when ::Array
+            obj.map { |o| deep_dup(o) }
+          when ::Set
+            ::Set[obj.map { |o| deep_dup(o) }]
+          when ::Hash
+            obj.each_with_object({}) { |(k, v), h| h[deep_dup(k)] = deep_dup(v) }
+          else
+            begin
+              obj.dup
+            rescue TypeError, NoMethodError
+              obj
+            end
+          end
+        end
+      end
+    end
+
+    ##
+    # @!method else
+    #   Returns +self+ if +self+ evaluates to +true+, otherwise returns the
+    #   evaluation of the block.
+    #
+    #   @yield [self] gives +self+ to the block.
+    #   @return [Object] +self+ if +self+ evaluates to +true+, otherwise
+    #     returns the evaluation of the block.
+    #
+    module Else
+      refine ::Object do
+        def else
+          self ? self : yield(self)
+        end
+      end
+    end
+
+    ##
+    # @!method in?(other)
+    #   @example Array
+    #     characters = ["Konata", "Kagami", "Tsukasa"]
+    #     "Konata".in?(characters) # => true
+    #
+    #   @example String
+    #     "f".in?("flynn") # => true
+    #     "x".in?("flynn") # => false
+    #
+    #   @param other [#include?]
+    #   @return [Boolean] +true+ if this object is included in the _other_
+    #     object, +false+ otherwise.
+    #   @raise ArgumentError if the _other_ doesn't respond to +#include?+.
+    #
+    module In
+      refine ::Object do
+        def in?(other)
+          other.include? self
+        rescue NoMethodError
+          fail ArgumentError, "The parameter passed to #in? must respond to #include?"
+        end
+      end
+    end
+
+    ##
+    # @!method instance_values
+    #   @example
+    #     class C
+    #       def initialize(x, y)
+    #         @x, @y = x, y
+    #       end
+    #     end
+    #
+    #     C.new(0, 1).instance_values
+    #     => {x: 0, y: 1}
+    #
+    #   @return [Hash] a hash with symbol keys that maps instance variable
+    #     names without "@" to their corresponding values.
+    #
+    module InstanceValues
+      refine ::Object do
+        def instance_values
+          ary = instance_variables.map do |name|
+            [ name[1..-1].to_sym, instance_variable_get(name) ]
+          end
+          ::Hash[ary]
+        end
+      end
+    end
+
+    ##
+    # @!method then
+    #   Returns +self+ if +self+ evaluate to +false+, otherwise returns
+    #   evaluation of the block.
+    #
+    #   This simplifies something like:
+    #
+    #     if m = "Flynn <flynn@encom.com>".match(/<([^>]+)>/)
+    #       m[1]
+    #     end
+    #
+    #   to:
+    #
+    #     "Flynn <flynn@encom.com>".match(/<([^>]+)>/).then { |m| m[1] }
+    #
+    #
+    #   Since +then+ passes +self+ to the block, it can be also used for
+    #   chaining, so something like:
+    #
+    #     html = parse_html(input)
+    #     html = find_nodes(html, "//section")
+    #     html = remove_nodes(html, "//p")
+    #
+    #   can be rewritten to:
+    #
+    #     parse_html(input)
+    #       .then { |h| find_nodes(h, "//section") }
+    #       .then { |h| remove_nodes(h, "//p") }
+    #
+    #   @yield [self] gives +self+ to the block.
+    #   @return [Object] evaluation of the block, or +self+ if no block given
+    #     or +self+ evaluates to false.
+    #
+    module Then
+      refine ::Object do
+        def then
+          if block_given? && self
+            yield self
+          else
+            self
+          end
+        end
+      end
+    end
+
+    ##
+    # @!method then_if(*conditions)
+    #   Returns +self+ if +self+ or any of the _conditions_ evaluates to
+    #   +false+, otherwise returns the evaluation of the block.
+    #
+    #   @example
+    #     "foo".then_if(:empty?) { "N/A" } # => "foo"
+    #        "".then_if(:empty?) { "N/A" } # => "N/A"
+    #
+    #   Each condition may be of the type:
+    #   * +Symbol+ - name of the method to be invoked using +public_send+.
+    #   * +Array+  - name of the method followed by arguments to be invoked
+    #     using +public_send+.
+    #   * +Proc+   - proc to be called with +self+ as the argument.
+    #   * Any other object to be evaluated as +true+, or +false+.
+    #
+    #   @param *conditions conditions to evaluate.
+    #   @yield [self] gives +self+ to the block.
+    #   @return [Object] evaluation of the block, or +self+ if any condition
+    #     evaluates to +false+, or no condition given and +self+ evaluates to
+    #     +false+.
+    #
+    module ThenIf
+      refine ::Object do
+        def then_if(*conditions)
+          return self if conditions.empty? && !self
+          return self unless conditions.all? do |arg|
+            case arg
+            when ::Symbol then public_send(arg)
+            when ::Array then public_send(*arg)
+            when ::Proc then arg.call(self)
+            else arg
+            end
+          end
+          yield self
+        end
+      end
+    end
+
+    ##
+    # @!method try(method, *args, &block)
+    #   Invokes the public method identified by the symbol _method_, passing it
+    #   any arguments and/or the block specified, just like the regular Ruby
+    #   +public_send+ does.
+    #
+    #   *Unlike* that method however, a +NoMethodError+ exception will *not* be
+    #   be raised and +nil+ will be returned instead, if the receiving object
+    #   doesn't respond to the _method_.
+    #
+    #   This method is defined to be able to write:
+    #
+    #     @person.try(:name)
+    #
+    #   instead of:
+    #
+    #     @person.name if @person
+    #
+    #   +try+ calls can be chained:
+    #
+    #     @person.try(:spouse).try(:name)
+    #
+    #   instead of:
+    #
+    #     @person.spouse.name if @person && @person.spouse
+    #
+    #   +try+ will also return +nil+ if the receiver does not respond to the
+    #   method:
+    #
+    #     @person.try(:unknown_method) # => nil
+    #
+    #   instead of:
+    #
+    #     @person.unknown_method if @person.respond_to?(:unknown_method) # => nil
+    #
+    #   +try+ returns +nil+ when called on +nil+ regardless of whether it
+    #   responds to the method:
+    #
+    #     nil.try(:to_i) # => nil, rather than 0
+    #
+    #   Arguments and blocks are forwarded to the method if invoked:
+    #
+    #     @posts.try(:each_slice, 2) do |a, b|
+    #       ...
+    #     end
+    #
+    #   The number of arguments in the signature must match. If the object
+    #   responds to the method, the call is attempted and +ArgumentError+ is
+    #   still raised in case of argument mismatch.
+    #
+    #   Please also note that +try+ is defined on +Object+. Therefore, it won't
+    #   work with instances of classes that do not have +Object+ among their
+    #   ancestors, like direct subclasses of +BasicObject+. For example, using
+    #   +try+ with +SimpleDelegator+ will delegate +try+ to the target instead
+    #   of calling it on the delegator itself.
+    #
+    #   @param method [Symbol] name of the method to invoke.
+    #   @param args arguments to pass to the _method_.
+    #   @return [Object, nil] result of calling the _method_, or +nil+ if
+    #     doesn't respond to it.
+    #
+    # @!method try!(method, *args, &block)
+    #   Same as {#try}, but raises a +NoMethodError+ exception if the receiver
+    #   is not +nil+ and does not implement the tried method.
+    #
+    #   @example
+    #     "a".try!(:upcase) # => "A"
+    #     nil.try!(:upcase) # => nil
+    #     123.try!(:upcase) # => NoMethodError: undefined method `upcase' for 123:Fixnum
+    #
+    #   @param method (see #try)
+    #   @param args (see #try)
+    #   @return (see #try)
+    #
+    module Try
+      refine ::Object do
+        def try(method = nil, *args, &block)
+          try!(method, *args, &block) if respond_to? method
+        end
+
+        def try!(method = nil, *args, &block)
+          public_send method, *args, &block
+        end
+      end
+
+      refine ::NilClass do
+        def try(*args)
+          nil
+        end
+
+        def try!(*args)
+          nil
+        end
+      end
+    end
+
+    include Support::AliasSubmodules
+
+    class << self
+      alias_method :blank?, :blank
+      alias_method :in?, :in
+      alias_method :presence, :blank
+      alias_method :try!, :try
+    end
+  end
+end

data/lib/corefines/string.rb

@@ -0,0 +1,211 @@
+require 'corefines/support/alias_submodules'
+
+module Corefines
+  module String
+
+    ESCAPE_SEQUENCE = /\033\[([0-9]+);([0-9]+);([0-9]+)m(.+?)\033\[0m|([^\033]+)/m
+    private_constant :ESCAPE_SEQUENCE
+
+    ##
+    # @!method color
+    #   @example
+    #     "Roses are red".color(:red) # => "\e[0;31;49mRoses are red\e[0m"
+    #     "Roses are red".color(text: :red, mode: :bold) # => "\e[1;31;49mRoses are red\e[0m"
+    #     "Violets are blue".color(background: 'blue') # => "\e[0;39;44mViolets are blue\e[0m"
+    #     "Sugar is sweet".color(text: 7) # => "\e[0;37;49mSugar is sweet\e[0m"
+    #
+    #   @overload color(text_color)
+    #     @param text_color [#to_sym, Fixnum] text (foreground) color (see
+    #            {COLOR_CODES}).
+    #
+    #   @overload color(opts)
+    #     @option opts [#to_sym, Fixnum] :mode text attributes (see
+    #             {MODE_CODES}).
+    #     @option opts [#to_sym, Fixnum] :text,:fg text (foreground) color (see
+    #             {COLOR_CODES}).
+    #     @option opts [#to_sym, Fixnum] :background,:bg background color (see
+    #             {COLOR_CODES}).
+    #
+    #   @return [String] a copy of this string colored for command line output
+    #           using ANSI escape codes.
+    #   @see Decolor#decolor
+    #
+    module Color
+
+      COLOR_CODES = {
+        black:   0, light_black:   60,
+        red:     1, light_red:     61,
+        green:   2, light_green:   62,
+        yellow:  3, light_yellow:  63,
+        blue:    4, light_blue:    64,
+        magenta: 5, light_magenta: 65,
+        cyan:    6, light_cyan:    66,
+        white:   7, light_white:   67,
+        default: 9
+      }
+
+      MODE_CODES = {
+        default:   0,  # Turn off all attributes.
+        bold:      1,  # Set bold mode.
+        underline: 4,  # Set underline mode.
+        blink:     5,  # Set blink mode.
+        swap:      7,  # Exchange foreground and background colors.
+        hide:      8   # Hide text (foreground color would be the same as background).
+      }
+
+      refine ::String do
+        def color(opts)
+          opts = {text: opts} unless opts.is_a? ::Hash
+          opts[:fg] ||= opts[:text] || opts[:color]
+          opts[:bg] ||= opts[:background]
+
+          scan(ESCAPE_SEQUENCE).reduce('') do |str, match|
+            mode     = Color.mode_code(opts[:mode])    || match[0] || 0
+            fg_color = Color.color_code(opts[:fg], 30) || match[1] || 39
+            bg_color = Color.color_code(opts[:bg], 40) || match[2] || 49
+            text     = match[3] || match[4]
+
+            str << "\033[#{mode};#{fg_color};#{bg_color}m#{text}\033[0m"
+          end
+        end
+      end
+
+      private
+
+      def self.color_code(color, offset)
+        return color + offset if color.is_a? ::Fixnum
+        COLOR_CODES[color.to_sym] + offset if color && COLOR_CODES[color.to_sym]
+      end
+
+      def self.mode_code(mode)
+        return mode if mode.is_a? ::Fixnum
+        MODE_CODES[mode.to_sym] if mode
+      end
+    end
+
+    ##
+    # @!method concat!(obj, separator = nil)
+    #   Appends (concatenates) the given object to _str_. If the _separator_ is
+    #   set and this _str_ is not empty, then it appends the _separator_ before
+    #   the _obj_.
+    #
+    #   @example
+    #     "".concat!("Greetings", ", ") # => "Greetings"
+    #     "Greetings".concat!("programs!", ", ") #=> "Greetings, programs!"
+    #
+    #   @param obj [String, Integer] the string, or codepoint to append.
+    #   @param separator [String, nil] the separator to append when this _str_ is
+    #          not empty.
+    #   @return [String] self
+    #
+    module Concat
+      refine ::String do
+        def concat!(obj, separator = nil)
+          if separator && !self.empty?
+            self << separator << obj
+          else
+            self << obj
+          end
+        end
+      end
+    end
+
+    ##
+    # @!method decolor
+    #   @return [String] a copy of this string without ANSI escape codes
+    #     (e.g. colors).
+    #   @see Color#color
+    #
+    module Decolor
+      refine ::String do
+        def decolor
+          scan(ESCAPE_SEQUENCE).reduce('') do |str, match|
+            str << (match[3] || match[4])
+          end
+        end
+      end
+    end
+
+    ##
+    # @!method remove(*patterns)
+    #   Returns a copy of this string with *all* occurrences of the _patterns_
+    #   removed.
+    #
+    #   The pattern is typically a +Regexp+; if given as a +String+, any
+    #   regular expression metacharacters it contains will be interpreted
+    #   literally, e.g. +'\\d'+ will match a backlash followed by 'd', instead
+    #   of a digit.
+    #
+    #   @example
+    #     str = "This is a good day to die"
+    #     str.remove(" to die") # => "This is a good day"
+    #     str.remove(/\s*to.*$/) # => "This is a good day"
+    #     str.remove("to die", /\s*$/) # => "This is a good day"
+    #
+    #   @param *patterns [Regexp, String] patterns to remove from the string.
+    #   @return [String] a new string.
+    #
+    # @!method remove!(*patterns)
+    #   Removes all the occurrences of the _patterns_ in place.
+    #
+    #   @see #remove
+    #   @param *patterns (see #remove)
+    #   @return [String] self
+    #
+    module Remove
+      refine ::String do
+        def remove(*patterns)
+          dup.remove!(*patterns)
+        end
+
+        def remove!(*patterns)
+          patterns.each { |pattern| gsub!(pattern, '') }
+          self
+        end
+      end
+    end
+
+    ##
+    # @!method unindent
+    #   Remove excessive indentation. Useful for multi-line strings embeded in
+    #   already indented code.
+    #
+    #   @example
+    #     <<-EOF.unindent
+    #       Greetings,
+    #         programs!
+    #     EOF
+    #     => "Greetings\n  programs"
+    #
+    #   Technically, it looks for the least indented line in the whole
+    #   string (blank lines are ignored) and removes that amount of leading
+    #   whitespace.
+    #
+    #   @return [String] a new unindented string.
+    #
+    #
+    # @!method strip_heredoc
+    #   Alias for {#unindent}.
+    #
+    #   @return [String] a new unindented string.
+    #
+    module Unindent
+      refine ::String do
+        def unindent
+          leading_space = scan(/^[ \t]*(?=\S)/).min
+          indent = leading_space ? leading_space.size : 0
+          gsub /^[ \t]{#{indent}}/, ''
+        end
+
+        alias_method :strip_heredoc, :unindent
+      end
+    end
+
+    include Support::AliasSubmodules
+
+    class << self
+      alias_method :concat!, :concat
+      alias_method :remove!, :remove
+    end
+  end
+end

data/lib/corefines/support/alias_submodules.rb

@@ -0,0 +1,103 @@
+module Corefines
+  module Support
+    ##
+    # @private
+    # When this module is included, then it:
+    #
+    # 1. Defines an "alias" for each submodule, i.e. singleton method that
+    #    returns the submodule and it's named after the submodule, but the name
+    #    is converted to underscore_separated or an operator. For example,
+    #    instead of <tt>using Corefines::String::ToHtml</tt> one can write
+    #    <tt>using Corefines::String::to_html</tt>.
+    #
+    # 2. Includes all the submodules into the module. This allows to use all
+    #    refinements inside the submodules just by _using_ their parent module.
+    #
+    # 3. Defines method {[]}.
+    #
+    # @!method self.[](*names)
+    #   @example
+    #     Corefines::Object[:blank?, :then]
+    #
+    #   @param names [Array<Symbol>] names of submodules aliases to include
+    #     into the returned module.
+    #   @return [Module] a new module that includes the named submodules.
+    #
+    module AliasSubmodules
+
+      OPERATORS_MAP = {
+        :op_plus   => :+,
+        :op_minus  => :-,
+        :op_pow    => :**,
+        :op_mul    => :*,
+        :op_div    => :/,
+        :op_mod    => :%,
+        :op_tilde  => :~,
+        :op_cmp    => :<=>,
+        :op_lshift => :<<,
+        :op_rshift => :>>,
+        :op_lt     => :<,
+        :op_gt     => :>,
+        :op_case   => :===,
+        :op_equal  => :==,
+        :op_apply  => :=~,
+        :op_lt_eq  => :<=,
+        :op_gt_eq  => :>=,
+        :op_or     => :|,
+        :op_and    => :&,
+        :op_xor    => :^,
+        :op_store  => :[]=,
+        :op_fetch  => :[]
+      }
+
+      private
+
+      def self.included(target)
+        target.constants.each do |const|
+          submodule = target.const_get(const)
+          next unless submodule.instance_of? ::Module
+
+          # Defines method-named "alias" for the submodule. (1)
+          target.define_singleton_method(method_name(const)) { submodule }
+
+          # Includes the submodule of the target into target. (2)
+          target.send(:include, submodule)
+        end
+
+        target.extend ClassMethods
+      end
+
+      def self.method_name(module_name)
+        name = underscore(module_name)
+        OPERATORS_MAP[name.to_sym] || name
+      end
+
+      def self.underscore(camel_cased_word)
+        return camel_cased_word unless camel_cased_word =~ /[A-Z]/
+
+        camel_cased_word.to_s.dup.tap do |s|
+          s.gsub! /([A-Z\d]+)([A-Z][a-z])/, '\1_\2'
+          s.gsub! /([a-z\d])([A-Z])/, '\1_\2'
+          s.downcase!
+        end
+      end
+
+
+      module ClassMethods
+
+        def [](*names)
+          ::Module.new.tap do |mod|
+            names.each do |mth|
+              unless respond_to? mth
+                fail ArgumentError, "no such refinements submodule with alias '#{mth}'"
+              end
+              mod.send(:include, public_send(mth))
+            end
+          end
+        end
+      end
+
+      private_constant :ClassMethods, :OPERATORS_MAP
+    end
+  end
+end