plain_text 0.1

data/lib/plain_text/split.rb

@@ -0,0 +1,103 @@
+# -*- coding: utf-8 -*-
+
+module PlainText
+  #
+  # Contains a method that splits a String in a reversible way
+  #
+  # String#split is a powerful method.
+  # One caveat is there is no way to guarantee the possibility to reverse
+  # the process when a *random* Regexp (as opposed to String or when the user
+  # knows what exactly the Regexp is or has a perfect control about it) is given,
+  # because the resultant Array contains *all* the group-ed String as elements.
+  #
+  # This module provides a method to enable it.  Requiring this file
+  # makes the method included in the String class.
+  #
+  # @example Reversible (the method is assumed to be included in String)
+  #   my_str.split_with_delimiter(/MyRegexp/).join == my_str  # => true
+  #
+  # @author Masa Sakano (Wise Babel Ltd)
+  #
+  module Split
+
+    # The class-method version of the instance method of the same name.
+    #
+    # One more parameter (input String) is required to specify.
+    #
+    # @param instr [String] String that is examined.
+    # @param re_in [Regexp, String] If String, it is interpreted literally as in String#split.
+    # @return [Array]
+    # @see PlainText::Split#split_with_delimiter
+    def self.split_with_delimiter(instr, re_in)
+      re_in = Regexp.new(Regexp.quote(re_in)) if re_in.class.method_defined? :to_str
+      re_grp = add_grouping(re_in)  # Ensure grouping.
+
+      arspl = instr.split re_grp, -1
+      return arspl if arspl.size <= 1  # n.b., Size is 0 for an empty string (only?).
+
+      n_grouping = re_grp.match(instr).size  # The number of grouping - should be at least 2, including $&.
+      return adjust_last_element(arspl) if n_grouping <= 2
+
+      # Takes only the split main contents and delimeter
+      arret = []
+      arspl.each_with_index do |ec, ei|
+        arret << ec if (1..2).include?( (ei + 1) % n_grouping )
+      end
+      adjust_last_element(arret) # => Array
+    end
+
+    ####################################################
+    # Class methods (Private)
+    ####################################################
+
+    # This method encloses the given Regexp with '()'
+    #
+    # @param rule_re [Regexp]
+    # @return [Regexp]
+    def self.add_grouping(rule_re)
+      Regexp.new '('+rule_re.source+')', rule_re.options
+    end
+    private_class_method :add_grouping
+
+    # Utility
+    def self.adjust_last_element(ary)
+      ary.pop if ary[-1].empty?  # ary.size > 0 is guaranteed
+      ary
+    end
+    private_class_method :adjust_last_element
+
+    ####################################################
+    # Instance methods
+    ####################################################
+
+    # Split with the delimiter even when Regexp (or String) is given
+    #
+    # Note the last empty component, if exists, is deleted in the returned Array.
+    # If the input string is empty, the returned Array is also empty,
+    # as in String#split.
+    #
+    # @example Standard split (without grouping) : +s="XQabXXcXQ"+
+    #   s.split(/X+Q?/)         #=> ["", "ab", "c"],                   
+    #   s.split(/X+Q?/, -1)     #=> ["", "ab", "c", ""],               
+    #
+    # @example Standard split (with grouping) : +s="XQabXXcXQ"+
+    #   s.split(/X+(Q?)/, -1)   #=> ["", "Q", "ab", "", "c", "Q", ""], 
+    #   s.split(/(X+(Q?))/, -1) #=> ["", "XQ", "Q", "ab", "XX", "", "c", "XQ", "Q", ""], 
+    #
+    # @example This method (when included in String (as Default)) : +s="XQabXXcXQ"+
+    #   s.split_with_delimiter(/X+(Q?)/)
+    #                           #=> ["", "XQ", "ab", "XX", "c", "XQ"]
+    #
+    # @param re_in [Regexp, String] If String, it is interpreted literally as in String#split.
+    # @return [Array]
+    def split_with_delimiter(*rest)
+      PlainText::Split.public_send(__method__, self, *rest)
+    end
+  end # module Split
+end # module PlainText
+
+class String
+  # Enabling String#split_with_delimiter
+  include PlainText::Split
+end
+

data/lib/plain_text/util.rb

@@ -0,0 +1,104 @@
+# -*- coding: utf-8 -*-
+
+module PlainText
+
+  # Contains some utility methods for use in this module and classes.
+  #
+  # @author Masa Sakano (Wise Babel Ltd)
+  #
+  module Util
+
+    # All methods in this Module are module functions.
+    module_function 
+
+    # Returns a pair of Arrays of even and odd number-indices of the original Array
+    #
+    # @example
+    #    even_odd_arrays([33,44,55], size_even: true)
+    #    # => [[33, 55], [44, ""]]
+    #
+    # @param ary [Array]
+    # @param size_even: [Boolean] if true (Def: false), the sizes of the returned arrays are guaranteed to be identical.
+    # @param filler: [Object] if size_even: is true and if matching is performed, this filler is added at the end of the last element.
+    def even_odd_arrays(ary, size_even: false, filler: "")
+      ar_even = select.with_index { |_, i| i.even? } rescue select.each_with_index { |_, i| i.even? } # Rescue for Ruby 2.1 or earlier
+      ar_odd  = select.with_index { |_, i| i.odd? }  rescue select.each_with_index { |_, i| i.odd? }  # Rescue for Ruby 2.1 or earlier
+      if size_even && (ar_even.size != ar_odd.size)
+        ar_odd.push filler
+        raise "Should not happern." if (ar_even.size != ar_odd.size)
+      end
+      [ar_even, ar_odd]
+    end
+
+    # Returns a non-negative Array index for self
+    #
+    # If positive or zero, it returns i.
+    # If the negative index is out of range, it returns nil.
+    #
+    # @param i [Integer]
+    # @param ary [Array] Reference Array.
+    # @return [Integer, NilClass] nil if out of range to the negative.  Note in most cases in Ruby default, it raises IndexError.  See the code of {#positive_array_index_checked}
+    # @raise [TypeError] if non-integer is specified.
+    # @raise [ArgumentError] if ary is not an Array, or more specifically, it does not have size method or ary.size does not return Integer or similar.
+    def positive_array_index(i, ary)
+      i2 = i.to_int rescue (raise TypeError, sprintf("no implicit conversion of #{i.class} into Integer"))
+      return i2 if i2 >= 0
+      ret = ary.size + i2 rescue (raise ArgumentError, "argument is not an array.")
+      (ret < 0) ? nil : ret
+    end
+  
+  
+    # Returns a non-negative Array index for self, performing a check.
+    #
+    # Exception is raised if it is out of range.
+    #
+    # Wrapper for {#positive_array_index}
+    #
+    # @param index_in [Integer] Index to check and convert from. Potentially negative integer.
+    # @param ary [Array] Reference Array.
+    # @param accept_too_big: [Boolean, NilClass] if true (Default), a positive index larger than the last array index is returned as it is. If nil, the last index + 1 is accepted but raises an Exception for anything larger.  If false, any index larger than the last index raises an Exception.
+    # @param varname: [NilClass, String] Name of the variable (or nil) to be used for error messages.
+    # @return [Integer] Non-negative index; i.e., if index=-1 is specified for an Array with a size of 3, the returned value is 2 (the last index of it).
+    # @raise [IndexError] if the index is out of the range to negative.
+    def positive_array_index_checked(index_in, ary, accept_too_big: true, varname: nil)
+      # def self.positive_valid_index_for_array(index_in, ary, varname: nil)
+      errmsgs = {}
+      %w(of for).each do |i|
+        errmsgs[i] = (varname ? "." : sprintf(" %s %s.", i, varname)) 
+      end
+  
+      index = positive_array_index(index_in, ary)  # guaranteed to be Integer or nil
+      raise IndexError, sprintf("index (%s) too small for array; minimum: -%d", index_in, ary.size) if !index  # Ruby default Error message (except the variable "index" as opposed to "index_in is used in the true Ruby default).
+      if index_in >= 0
+        last_index = ary.size - 1
+        errnote1 = nil
+        if    (index >  last_index + 1) && !accept_too_big
+          errnote1 = ' (or +1)'
+        elsif (index == last_index + 1) && (false == accept_too_big)
+          errnote1 = " "
+        end
+        raise IndexError, sprintf("Specified index (%s) is larger than the last index (%d)%s%s", index_in, last_index, errnote1, errmsgs['of']) if errnote1
+      end
+      index
+    end
+
+    # Raise TypeError
+    #
+    # Call as +raise_typeerror(var_name)+ from instance methods,
+    # providing this Module is included in the Class/Module.
+    #
+    # @param var [Object]
+    # @param to_class [String, Class] class name converted into.
+    # @option verbose: [Boolean] ($DEBUG)
+    # @raise [TypeError]
+    def raise_typeerror(var, to_class, verbose: $DEBUG)
+      msg1 = (verbose ? sprintf("(<= %s)", var.inspect) : "")
+      to_class_str = (to_class.name rescue to_class.to_str)
+      raise TypeError, sprintf("no implicit conversion of %s%s into %s", var.class, msg1, to_class_str)
+    end
+
+  end # module Util
+
+  include Util
+end # module PlainText
+