plain_text 0.7.1 → 0.8

data/lib/plain_text/part.rb

@@ -1,10 +1,12 @@
 # -*- coding: utf-8 -*-
 
-require "plain_text/util"
+require_relative "error"
+require_relative "builtin_type"
+require_relative "util"
 
 module PlainText
 
-  # Class to represent a Chapter-like entity like an Array
+  # Class to represent a Chapter-like entity, which behaves like an Array
   #
   # An instance of this class contains always an even number of elements,
   # either another {Part} instance or {Paragraph}-type String-like instance,
@@ -17,65 +19,80 @@ module PlainText
   # An example instance looks like this:
   #
   #   Part (
-  #     (0) Paragraph::Empty,
-  #     (1) Boundary::General,
+  #     (0) Part::Paragraph::Empty,
+  #     (1) Part::Boundary::General,
   #     (2) Part::ArticleHeader(
-  #           (0) Paragraph::Title,
-  #           (1) Boundary::Empty
+  #           (0) Part::Paragraph::Title,
+  #           (1) Part::Boundary::Empty
   #         ),
-  #     (3) Boundary::TitleMain,
+  #     (3) Part::Boundary::TitleMain,
   #     (4) Part::ArticleMain(
   #           (0) Part::ArticleSection(
-  #                 (0) Paragraph::Title,
-  #                 (1) Boundary::General,
-  #                 (2) Paragraph::General,
-  #                 (3) Boundary::General,
+  #                 (0) Part::Paragraph::Title,
+  #                 (1) Part::Boundary::General,
+  #                 (2) Part::Paragraph::General,
+  #                 (3) Part::Boundary::General,
   #                 (4) Part::ArticleSubSection(...),
-  #                 (5) Boundary::General,
-  #                 (6) Paragraph::General,
-  #                 (7) Boundary::Empty
+  #                 (5) Part::Boundary::General,
+  #                 (6) Part::Paragraph::General,
+  #                 (7) Part::Boundary::Empty
   #               ),
-  #           (1) Boundary::General,
-  #           (2) Paragraph::General,
-  #           (3) Boundary::Empty
+  #           (1) Part::Boundary::General,
+  #           (2) Part::Paragraph::General,
+  #           (3) Part::Boundary::Empty
   #         ),
-  #     (5) Boundary::General
+  #     (5) Part::Boundary::General
   #   )
   #
   # A Section (Part) always has an even number of elements: pairs of a Para ({Part}|{Paragraph}) and {Boundary} in this order.
   #
-  # Note some standard destructive Array operations, most notably +#delete+, +#delete_if+, +#reject!+,
+  # This class behaves like an Array and so Array methods that usually return
+  # an Array returns an instance of this class, such as +pt[0..-2]+.
+  # However, not all Array methods are accepted in the same way.
+  # For example, for the instance +pt+, +pt[0..-2]+ raises an Exception
+  # because it would violate the principle of the instance of this class
+  # having always an even number of elements.  Use +to_a+ to obtain
+  # a standard Array; e.g., +pt.to_a[0..-2]+ returns an Array with
+  # an odd number of elements.
+  #
+  # Some destructive Array operations, most notably +#delete+, +#delete_if+, +#reject!+,
   # +#select!+, +#filter!+, +#keep_if+, +#flatten!+, +#uniq!+ may alter the content in a way
-  # it breaks the self-inconsistency of the object.
+  # it breaks the self-consistency of the object.
   # Use it at your own risk, if you wish (or don't).
+  # Such operations may become prohibited in the future release.
+  # {#<<} and {#delete_at} are currently disabled.
   #
   # An instance of this class is always *non-equal* to that of the standard Array class.
-  # To compare it at the Array level, convert a {Part} class instance into Array with #to_a first and compare them.
+  # To compare it at the Array level, convert a {Part} class instance into Array
+  # with {#to_a} first: +pt.to_a == my_array+
   #
   # For CRUD of elements (contents) of an instance, the following methods are most basic:
   #
   # * Create:
-  #   * Insert/Append: {#insert} to insert. If the specified index is #size}, it means "append". For primitive operations, specify +primitive: true+ to skip various checks performed to guarantee the self-consistency as an instance of this class.
-  #   * {#<<} is disabled.
+  #   * Use +PlainText::Part.new+ (see {PlainText::Part.initialize})
   # * Read:
-  #   * Read: #to_a gives the standard Array, and then you can do whatever manipulation allowed for Array.  For example, if you delete an element in the returned Array, that does not affect the original {Part} instance.  However, it is a shallow copy, and hence if you alter an element of it destructively (such as String#replace), the original instance, too, is affected.
-  #     * The methods {#[]} (or its alias {#slice}) have some restrictions, such as, an odd number of elements cannot be retrieved, so as to conform the returned value is a valid instance of this class.
+  #   * All non-destructive Array operations are permitted and returns an instance of this class if the corresponding Array method returns an Array, providing it does not break the self-consistency.
+  #   * {#to_a} gives or exposes the internal Array object, and then you can do whatever manipulation allowed for Array with it, if you insist.  Note that destructive modification of the object carries a risk of breaking self-consistency of the instance and so is highly discouraged.  You must know what you are doing if you do.
   # * Update:
+  #   * Insert/Append: {#insert} to insert. If the specified index is #size}, it means "append". For primitive operations, specify +primitive: true+ to skip various checks performed to guarantee the self-consistency as an instance of this class.
   #   * Replace: {#[]=} has some restrictions, such as, if multiple elements are replaced, they have to be pairs of Paragraph and Boundary.  To skip all the checks, do {#insert} with +primitive: true+
   # * Delete:
   #   * Delete: {#slice!} to delete. For primitive operations, specify +primitive: true+ to skip various checks performed to guarantee the self-consistency as an instance of this class.
-  #     * +#delete_at+ is disabled. +#delete+, +#delete_if+, +#reject!+, +#select!+, +#filter!+, +#keep_if+ (and +#drop_while+ and +#take_whie+ in recent Ruby) remain enabled, but if you use them, make sure to use them carefully at your own risk, as no self-consistency checks would be performed automatically.
+  #     * +#delete_at+ is disabled. +#delete+, +#delete_if+, +#reject!+, +#select!+, +#filter!+, +#keep_if+ (and +#drop_while+ and +#take_whie+ in recent Ruby) remain enabled, but if you use them, do so at your own risk, as no self-consistency checks would be performed automatically. {#normalize} would return the self-consistent instance, or its destructive version, {#normalize!}.
   #
   # @author Masa Sakano (Wise Babel Ltd)
   #
   # @todo methods
   #   * flatten
-  #   * SAFE level  for command-line tools?
   #
-  class Part < Array
+  class Part
 
+    include PlainText::BuiltinType
     include PlainText::Util
 
+    # Array methods that are disabled for this class.
+    DISABLED_ARRAY_METHODS = %i(<< delete_at)
+
     # Error messages
     ERR_MSGS = {
       even_num: 'even number of elements must be specified.',
@@ -83,25 +100,44 @@ module PlainText
     }
     private_constant :ERR_MSGS
 
-    # @param arin [Array] of [Paragraph1, Boundary1, Para2, Bd2, ...] or just Paragraphs if boundaries is given as the second arguments
+    # Constructor
+    #
+    # New String-type objects are always created, i.e.,
+    # regardless of whether the input is a pure String or {Paragraph} etc,
+    # a new {Paragraph} is always created from {Paragraph#to_s}. Therefore,
+    # even if one of the String given to the argument is destructively
+    # modified, it does not affect the generated {Part} object. This also means
+    # that if the input {Paragraph} has special singloton methods or
+    # instance variables, the information will be lost.
+    #
+    # @param arin [Array] of [Paragraph1, Boundary1, Para2, Bd2, ...] or just of Paragraphs if boundaries is given as the second arguments
     # @param boundaries [Array] of Boundary
     # @option recursive: [Boolean] if true (Default), normalize recursively.
     # @option compact: [Boolean] if true (Default), pairs of nil paragraph and boundary are removed.  Otherwise, nil is converted to an empty string.
     # @option compacter: [Boolean] if true (Default), pairs of nil or empty paragraph and boundary are removed.
     # @return [self]
     def initialize(arin, boundaries=nil, recursive: true, compact: true, compacter: true)
+      raise ArgumentError, "Arguments must be an Array(s) or equivalent: "+arin.inspect+(boundaries ? ", "+boundaries.inspect : "") if (!arin.respond_to?(:compact) && !arin.respond_to?(:paras)) || boundaries && !boundaries.respond_to?(:compact)  # arin must be an Array or Part
       if !boundaries
-        super(arin)
+        @array = arin.clone
+        #super(arin)
       else
+        raise ArgumentError, "Two main Arrays must have the same size." if arin.size != boundaries.size
 
         armain = []
         arin.each_with_index do |ea_e, i|
           armain << ea_e
           armain << (boundaries[i] || Boundary.new(''))
         end
-        super armain
+        @array = armain
+        #super armain
+      end
+
+      begin
+        normalize!(recursive: recursive, compact: compact, compacter: compacter)
+      rescue PlainText::PartNormalizeError => err
+        raise TypeError, err.message
       end
-      normalize!(recursive: recursive, compact: compact, compacter: compacter)
     end
 
     # Parses a given string (or {Part}) and returns this class of instance.
@@ -114,6 +150,33 @@ module PlainText
       self.new(arin)
     end
 
+    # Returns true if it is {PlainText::Part}
+    def self.part?(other)
+      _part_paragraph_boundary?(other, __method__)
+    end
+
+    # Returns true if it is {PlainText::Part::Boundary}
+    def self.boundary?(other)
+      _part_paragraph_boundary?(other, __method__)
+    end
+
+    # Returns true if it is {PlainText::Part::Paragraph}
+    def self.paragraph?(other)
+      _part_paragraph_boundary?(other, __method__)
+    end
+
+    # Returns true if it is built-in String or similar
+    def self.builtin_string?(other)
+      other.respond_to?(:to_str) && !boundary? && !paragraph?
+    end
+
+    # Core routines for {Part.part?} etc.
+    def self._part_paragraph_boundary?(other, metho)
+      %i(boundary? paragraph? part?).all?{|i| other.respond_to? i} && other.send(metho)
+    end
+    private_class_method :_part_paragraph_boundary?
+
+
     ####################################################
     # Instance methods
     ####################################################
@@ -122,12 +185,24 @@ module PlainText
     # Unique instance methods (not existing in Array)
     ##########
 
+    def boundary?
+      false
+    end
+
+    def paragraph?
+      false
+    end
+
+    def part?
+      true
+    end
+
     # Returns an array of boundaries (odd-number-index elements), consisting of Boundaries
     #
     # @return [Array<Boundary>]
     # @see #paras
     def boundaries
-      select.with_index { |_, i| i.odd? } rescue select.each_with_index { |_, i| i.odd? } # Rescue for Ruby 2.1 or earlier
+      @array.select.with_index { |_, i| i.odd? } rescue @array.select.each_with_index { |_, i| i.odd? } # Rescue for Ruby 2.1 or earlier
     end
 
     # returns all the Boundaries immediately before the index and at it as an Array
@@ -139,16 +214,19 @@ module PlainText
     def boundary_extended_at(index)
       (i_pos = get_valid_ipos_for_boundary(index)) || return
       arret = []
-      prt = self[i_pos-1]
-      arret = prt.public_send(__method__, -1) if prt.class.method_defined? __method__
-      arret << self[index]
+      prt = @array[i_pos-1]
+      arret = prt.public_send(__method__, -1) if prt.respond_to? __method__
+      arret << @array[index]
     end
 
     # Returns a dup-ped instance with all the Arrays and Strings dup-ped.
     #
     # @return [Part]
     def deepcopy
-      dup.map!{ |i| i.class.method_defined?(:deepcopy) ? i.deepcopy : i.dup }
+      _return_this_or_other{
+        @array.dup.map!{ |i| i.respond_to?(:deepcopy) ? i.deepcopy : (i.dup rescue i)}
+        # the "rescue" deals with cases where i is immutable (which should never happen and in fact it would not raise an Exception in Ruby 3 seemingly).
+      }
     end
 
     # each method for boundaries only, providing also the index (always an odd number) to the block.
@@ -164,7 +242,7 @@ module PlainText
     # @param (see #map_boundary_with_index)
     # @return as self
     def each_boundary_with_index(**kwd, &bl)
-      map_boundary_core(map: false, with_index: true, **kwd, &bl)
+      map_boundary_core(do_map: false, with_index: true, **kwd, &bl)
     end
 
     # each method for Paras only, providing also the index (always an even number) to the block.
@@ -180,7 +258,7 @@ module PlainText
     # @param (see #map_para_with_index)
     # @return as self
     def each_para_with_index(**kwd, &bl)
-      map_para_core(map: false, with_index: false, **kwd, &bl)
+      map_para_core(do_map: false, with_index: false, **kwd, &bl)
     end
 
     # The first significant (=non-empty) element.
@@ -190,7 +268,7 @@ module PlainText
     # @return [Integer, nil] if self.empty? nil is returned.
     def first_significant_element
       (i = first_significant_index) || return
-      self[i]
+      @array[i]
     end
 
     # Index of the first significant (=non-empty) element.
@@ -199,20 +277,19 @@ module PlainText
     #
     # @return [Integer, nil] if self.empty? nil is returned.
     def first_significant_index
-      return nil if empty?
-      each_index do |i|
-        return i if self[i] && !self[i].empty?  # self for sanity
-      end
-      return size-1
+      return nil if @array.empty?
+      @array.find_index do |val|
+        val && !val.empty?
+      end || (@array.size-1)
     end
 
     # True if the index should be semantically for Paragraph?
     #
     # @param i [Integer] index for the array of self
-    # @option skip_check: [Boolean] if true (Default: false), skip conversion of the negative index to positive.
+    # @option accept_negative: [Boolean] if false (Default: true), skip conversion of the negative index to positive.
     # @see #paras
-    def index_para?(i, skip_check: false)
-      skip_check ? i.even? : positive_array_index_checked(i, self).even?
+    def index_para?(i, accept_negative: true)
+      accept_negative ? positive_array_index_checked(i, @array).even? : i.even?
     end
 
     # The last significant (=non-empty) element.
@@ -222,7 +299,7 @@ module PlainText
     # @return [Integer, nil] if self.empty? nil is returned.
     def last_significant_element
       (i = last_significant_index) || return
-      self[i]
+      @array[i]
     end
 
     # Index of the last significant (=non-empty) element.
@@ -233,7 +310,7 @@ module PlainText
     def last_significant_index
       return nil if empty?
       (0..(size-1)).to_a.reverse.each do |i|
-        return i if self[i] && !self[i].empty?  # self for sanity
+        return i if @array[i] && !@array[i].empty?  # self for sanity
       end
       return 0
     end
@@ -298,12 +375,12 @@ module PlainText
     # @return [self, false] false if no pairs of Paras are merged, else self.
     def merge_para_if()
       arind2del = []  # Indices to delete (both paras and boundaries)
-      each_index do |ei|
-        break if ei >= size - 3  # 2nd last paragraph or later.
-        next if !index_para?(ei, skip_check: true)
-        ar1st = self.to_a[ei..ei+2]
-        ar2nd = ((ei==0) ? nil : self[ei-1])
-        do_merge = yield(ar1st, ar2nd, self[ei+3], ei)
+      @array.each_index do |ei|
+        break if ei >= @array.size - 3  # 2nd last paragraph or later.
+        next if !index_para?(ei, accept_negative: false)
+        ar1st = @array[ei..ei+2]
+        ar2nd = ((ei==0) ? nil : @array[ei-1])
+        do_merge = yield(ar1st, ar2nd, @array[ei+3], ei)
         return false                 if do_merge == :abort
         arind2del.push ei, ei+1, ei+2 if do_merge 
       end
@@ -332,11 +409,9 @@ module PlainText
     # @return [self, nil] nil if nothing is merged (because of wrong indices).
     def merge_para!(*rest, use_para_index: false)
 $myd = true
-#warn "DEBUG:m00: #{rest}\n"
       (ranchk = build_index_range_for_merge_para!(*rest, use_para_index: use_para_index)) || (return self)  # Do nothing.
       # ranchk is guaranteed to have a size of 2 or greater.
-#warn "DEBUG:m0: #{ranchk}\n"
-      self[ranchk] = [self[ranchk].to_a[0..-2].join, self[ranchk.end]]  # 2-elements (Para, Boundary)
+      @array[ranchk] = [Paragraph.new(@array[ranchk][0..-2].join), @array[ranchk.end]]  # Array[Range] replaced with 2-elements (Para, Boundary)
       self
     end
 
@@ -351,13 +426,10 @@ $myd = true
     # @param use_para_index [Boolean] false
     # @return [Range, nil] nil if no range is selected.
     def build_index_range_for_merge_para!(*rest, use_para_index: false)
-#warn "DEBUG:b0: #{rest.inspect} to_a=#{to_a}\n"
       inary = rest.flatten
       return nil if inary.empty?
       # inary = inary[0] if like_range?(inary[0])
-#warn "DEBUG:b1: #{inary.inspect}\n"
-      (ary = to_ary_positive_index(inary, to_a)) || return  # Guaranteed to be an array of positive indices (sorted and uniq-ed).
-#warn "DEBUG:b3: #{ary}\n"
+      (ary = to_ary_positive_index(inary, @array)) || return  # Guaranteed to be an array of positive indices (sorted and uniq-ed).
       return nil if ary.empty?
 
       # Normalize so the array contains both Paragraph and Boundaries in between.
@@ -367,7 +439,7 @@ $myd = true
       #   of elements, ending with Boundary.
       if use_para_index
         ary = ary.map{|i| [i*2, i*2+1]}.flatten
-      elsif index_para?(ary[-1], skip_check: true)
+      elsif index_para?(ary[-1], accept_negative: false)
         # The last index in the given Array or Range was for Paragraph (Likely case).
         ary.push(ary[-1]+1)
       end
@@ -377,7 +449,7 @@ $myd = true
 
 $myd = false
       # Exception if the first index is for Boundary and no Paragraph.
-      raise ArgumentError, "The first index (#{ary[0]}) is not for Paragraph." if !index_para?(ary[0], skip_check: true)
+      raise ArgumentError, "The first index (#{ary[0]}) is not for Paragraph." if !index_para?(ary[0], accept_negative: false)
 
       i_end = [ary[-1], size-1].min
       return if i_end - ary[0] < 3  # No more than 1 para selected.
@@ -399,22 +471,22 @@ $myd = false
     # @return [self]
     def normalize!(recursive: true, ignore_array_boundary: true, compact: true, compacter: true)
       # Trim pairs of consecutive Paragraph and Boundary of nil
-      size_parity = (size.even? ? 0 : 1)
-      if (compact || compacter) && (size > 0+size_parity)
-        ((size-2-size_parity)..0).each do |i| 
+      size_parity = (@array.size.even? ? 0 : 1)
+      if (@array.compact || compacter) && (@array.size > 0+size_parity)
+        ((@array.size-2-size_parity)..0).each do |i| 
           # Loop over every Paragraph
           next if i.odd?
-          slice! i, 2 if compact   &&  !self[i] && !self[i+1]
-          slice! i, 2 if compacter && (!self[i] || self[i].empty?) && (!self[i+1] || self[i+1].empty?)
+          @array.slice! i, 2 if @array.compact &&  !@array[i] && !@array[i+1]
+          @array.slice! i, 2 if compacter      && (!@array[i] || @array[i].empty?) && (!@array[i+1] || @array[i+1].empty?)
         end
       end
 
-      i = -1
-      map!{ |ea|
-        i += 1
-        normalize_core(ea, i, recursive: recursive)
+      @array.map!.with_index{ |ea, ind|
+        ax = normalize_core(ea, ind, recursive: recursive)
+        ax
+        #normalize_core(ea, ind, recursive: recursive)
       }
-      insert_original_b4_part(size, Boundary.new('')) if size.odd?
+      @array.insert(@array.size, Boundary.new('')) if @array.size.odd?
       self
     end
 
@@ -428,14 +500,14 @@ $myd = false
     # @see #normalize!
     def normalize(recursive: true, ignore_array_boundary: true, compact: true, compacter: true)
       # Trims pairs of consecutive Paragraph and Boundary of nil
-      arall = to_a
-      size_parity = (size.even? ? 0 : 1)
-      if (compact || compacter) && (size > 0+size_parity)
-        ((size-2-size_parity)..0).each do |i| 
+      arall = @array
+      size_parity = (@array.size.even? ? 0 : 1)
+      if (@array.compact || compacter) && (@array.size > 0+size_parity)
+        ((@array.size-2-size_parity)..0).each do |i| 
           # Loop over every Paragraph
           next if i.odd?
-          arall.slice! i, 2 if compact   &&  !self[i] && !self[i+1]
-          arall.slice! i, 2 if compacter && (!self[i] || self[i].empty?) && (!self[i+1] || self[i+1].empty?)
+          arall.slice! i, 2 if compact   &&  !@array[i] && !@array[i+1]
+          arall.slice! i, 2 if compacter && (!@array[i] || @array[i].empty?) && (!@array[i+1] || @array[i+1].empty?)
         end
       end
 
@@ -454,7 +526,7 @@ $myd = false
     # @return [Array<Part, Paragraph>]
     # @see #boundaries
     def paras
-      select.with_index { |_, i| i.even? } rescue select.each_with_index { |_, i| i.even? } # Rescue for Ruby 2.1 or earlier
+      @array.select.with_index { |_, i| i.even? } rescue @array.select.each_with_index { |_, i| i.even? } # Rescue for Ruby 2.1 or earlier
       # ret.freeze
     end
 
@@ -465,7 +537,7 @@ $myd = false
     # @option range [Range, nil] Range of indices of self to reparse. In Default, the entire self.
     # @return [self]
     def reparse!(rule: PlainText::ParseRule::RuleConsecutiveLbs, name: nil, range: (0..-1))
-      insert range.begin, self.class.parse((range ? self[range] : self), rule: rule, name: name)
+      insert range.begin, self.class.parse((range ? @array[range] : self), rule: rule, name: name)
       self
     end
 
@@ -474,7 +546,7 @@ $myd = false
     # @param (see #reparse!)
     # @return [PlainText::Part]
     def reparse(**kwd)
-      ret = self.dup
+      ret = @array.dup
       ret.reparse!(**kwd)
       ret
     end
@@ -488,17 +560,17 @@ $myd = false
     # @return [Boundary, nil] nil if a too large index is specified.
     def squash_boundary_at!(index)
       (i_pos = get_valid_ipos_for_boundary(index)) || return
-      prt = self[i_pos-1]
+      prt = @array[i_pos-1]
       m = :emptify_last_boundary!
-      self[i_pos] << prt.public_send(m) if prt.class.method_defined? m
-      self[i_pos]
+      @array[i_pos] << prt.public_send(m) if prt.respond_to? m
+      @array[i_pos]
     end
 
 
     # Wrapper of {#squash_boundary_at!} to loop over the whole {Part}
     #
     # @return [self]
-    def squash_boundaryies!
+    def squash_boundaries!
       each_boundary_with_index do |ec, i|
         squash_boundary_at!(i)
       end
@@ -506,70 +578,37 @@ $myd = false
     end
 
 
-    # Boundary sub-class name only
-    #
-    # Make sure your class is a child class of Part
-    # Otherwise this method would not be inherited, obviously.
-    #
-    # @example
-    #   class PlainText::Part
-    #     class Section < self
-    #       class Subsection < self; end  # It must be a child class!
-    #     end
-    #   end
-    #   ss = PlainText::Part::Section::Subsection.new ["abc"]
-    #   ss.subclass_name  # => "Section::Subsection"
-    #
-    # @return [String]
-    # @see PlainText::Part#subclass_name
-    def subclass_name
-      printf "__method__=(%s)\n", __method__
-      self.class.name.split(/\A#{Regexp.quote method(__method__).owner.name}::/)[1] || ''
-    end
-
     ##########
     # Overwriting instance methods of the parent Object or Array class
     ##########
 
-    # Original equal and plus operators of Array
-    hsmethod = {
-      :equal_original_b4_part => :==,
-      :substitute_original_b4_part => :[]=,
-      :insert_original_b4_part    => :insert,
-      :delete_at_original_b4_part => :delete_at,
-      :slice_original_b4_part     => :slice,
-      :slice_original_b4_part!    => :slice!,
-    }
+    ########## Most basic methods (Object/BasicObject) ##########
 
-    hsmethod.each_pair do |k, ea_orig|
-      if self.method_defined?(k)
-        # To Developer: If you see this message, switch the DEBUG flag on (-d option) and run it.
-        warn sprintf("WARNING: Method %s#%s has been already defined, which should not be.  Contact the code developer. Line %d in %s%s", self.name, k.to_s, __FILE__, __LINE__, ($DEBUG ? "\n"+caller_locations.join("\n").map{|i| "  "+i} : ""))
-      else
-        alias_method k, ea_orig
-      end
+    # @return [String]
+    def inspect
+      self.class.name + @array.inspect
     end
 
-    alias_method :substit, :substitute_original_b4_part
-
-    ########## Most basic methods (Object) ##########
+    # @return [Array]
+    def to_a
+      @array
+    end
+    alias_method :to_ary, :to_a
+    alias_method :instance, :to_a  if ! self.method_defined?(:instance)
 
-    # @return [String]
-    def inspect
-      self.class.name + super
+    # Work around because Object#dup does not dup the instance variable @array
+    #
+    # @return [PlainText::Part]
+    def dup
+      dup_or_clone(super, __method__, '@array') # defined in builtin_type.rb
     end
 
-    # # clone
-    # #
-    # # Redefines Array#clone so the instance variables are also cloned.
-    # #
-    # # @return [self]
-    # def clone
-    #   copied = super
-    #   val = (@sep.clone        rescue @sep)  # rescue in case of immutable.
-    #   copied.instance_eval{ @sep = val }
-    #   copied 
-    # end
+    # Work around because Object#clone does not clone the instance variable @array
+    #
+    # @return [PlainText::Part]
+    def clone
+      dup_or_clone(super, __method__, '@array') # defined in builtin_type.rb
+    end
  
     # Equal operator
     #
@@ -579,44 +618,23 @@ $myd = false
     #
     # @param other [Object]
     def ==(other)
-      return false if !other.class.method_defined?(:to_ary)
+      return false if  !other.respond_to?(:to_ary) || !other.respond_to?(:normalize!)
       %i(paras boundaries).each do |ea_m|  # %i(...) defined in Ruby 2.0 and later
-        return false if !other.class.method_defined?(ea_m) || (self.public_send(ea_m) != other.public_send(ea_m))  # public_send() defined in Ruby 2.0 (1.9?) and later
+        return false if !other.respond_to?(ea_m) || (self.public_send(ea_m) != other.public_send(ea_m))  # public_send() defined in Ruby 2.0 (1.9?) and later
       end
-      super
+      @array == other.to_a  # or you may just return true?
     end
  
 
-    # # Multiplication operator
-    # #
-    # # @param other [Integer, String]
-    # # @return as self
-    # def *(other)
-    #   super
-    # end
-
-
     # Plus operator
     #
     # @param other [Object]
     # @return as self
     def +(other)
-      # ## The following is strict, but a bit redundant.
-      # # is_para = true  # Whether "other" is a Part class instance.
-      # # %i(to_ary paras boundaries).each do |ea_m|  # %i(...) defined in Ruby 2.0 and later
-      # #   is_para &&= other.class.method_defined?(ea_m)
-      # # end
-
-      # begin
-      #   other_even_odd = 
-      #     ([other.paras, other.boundaries] rescue even_odd_arrays(self, size_even: true, filler: ""))
-      # rescue NoMethodError
-      #   raise TypeError, sprintf("no implicit conversion of %s into %s", other.class.name, self.class.name)
-      # end
-
       # # eg., if self is PlainText::Part::Section, the returned object is the same.
       # ret = self.class.new(self.paras+other_even_odd[0], self.boundaries+other_even_odd[1])
-      ret = self.class.new super
+      raise(TypeError, "cannot operate with no #{self.class.name} instance (#{other.class.name})") if (!other.respond_to?(:to_ary) && !other.respond_to?(:normalize!))
+      ret = self.class.new(@array+other.to_ary)
       ret.normalize!
     end
  
@@ -626,17 +644,43 @@ $myd = false
     # @param other [Object]
     # @return as self
     def -(other)
-      ret = self.class.new super
+      raise ArgumentError, "cannot operate with no {self.class.name} instance" if !other.respond_to?(:to_ary) || !other.respond_to?(:normalize!)
+      ret = self.class.new(@array+other.to_ary)
       ret.normalize!
     end
  
-    # Array#<< is now undefined
-    # (because the instances of this class must take always an even number of elements).
-    undef_method(:<<) if method_defined?(:<<)
+    # if the Array method returns an Array, returns this class instance.
+    #
+    # Note that even the value is this-class instance, a new instance is created
+    # in default unless it is +eql?(self)+.
+    #
+    # @param obj [Object] the value to be evaluated.
+    # @return [Object]
+    # @yield [] the returned value is evaluated, if no argument is given
+    # @yieldreturn [Object] Either this-class instance or Object
+    def _return_this_or_other(obj=nil)
+      ret = (block_given? ? yield : obj)
+      (ret.respond_to?(:to_ary) && !ret.eql?(self)) ? self.class.new(ret) : ret
+    end
+    private :_return_this_or_other
  
-    # Array#delete_at is now undefined
-    # (because the instances of this class must have always an even number of elements).
-    undef_method(:delete_at) if method_defined?(:delete_at)
+    # Basically delegates everything to Array
+    #
+    # Array#<< and Array#delete_at are undefined
+    # because the instances of this class must take always an even number of elements.
+    def method_missing(method_name, *args, **kwds)
+      if DISABLED_ARRAY_METHODS.include? method_name
+        raise NoMethodError, "no method "+method_name.to_s
+      end
+      _return_this_or_other{
+        @array.public_send(method_name, *args, **kwds)
+      }
+    end
+
+    # Redefines the behaviour of +respond_to?+ (essential when defining +method_missing+)
+    def respond_to_missing?(method_name, *rest)  # include_all=false
+      !DISABLED_ARRAY_METHODS.include?(method_name) && @array.respond_to?(method_name, *rest) || super
+    end
 
     # Returns a partial Part-Array (or Object, if a single Integer is specified)
     #
@@ -649,7 +693,7 @@ $myd = false
     # @return [Object]
     def [](arg1, *rest)
       arg2 = rest[0]
-      return super(arg1) if !arg2 && !arg1.class.method_defined?(:exclude_end?)
+      return @array[arg1] if !arg2 && !arg1.respond_to?(:exclude_end?)
 
       check_bracket_args_type_error(arg1, arg2)  # Args are now either (Int, Int) or (Range)
 
@@ -657,11 +701,13 @@ $myd = false
         size2ret = size2extract(arg1, arg2, ignore_error: true)  # maybe nil (if the index is too small).
         raise ArgumentError, ERR_MSGS[:even_num]+" "+ERR_MSGS[:use_to_a] if size2ret.odd?
         begin
-          raise ArgumentError, "odd index is not allowed as the starting index for #{self.class.name}.  It must be even. "+ERR_MSGS[:use_to_a] if positive_array_index_checked(arg1, self).odd?
+          raise ArgumentError, "odd index is not allowed as the starting index for #{self.class.name}.  It must be even. "+ERR_MSGS[:use_to_a] if positive_array_index_checked(arg1, @array).odd?
         rescue TypeError, IndexError
           # handled by super
         end
-        return super
+        return _return_this_or_other{
+          @array[arg1, arg2]
+        }
       end
 
       begin
@@ -675,13 +721,17 @@ $myd = false
 
       # The end is smaller than the begin in the positive index.  Empty instance of this class is returned.
       if rang.end < rang.begin
-        return super
+        return _return_this_or_other{
+          @array[arg1, *rest]
+        }
       end
 
       raise RangeError, "odd index is not allowed as the starting Range for #{sefl.class.name}.  It must be even. "+ERR_MSGS[:use_to_a] if rang.begin.odd?
       size2ret = size2extract(rang, skip_renormalize: true)
       raise ArgumentError, ERR_MSGS[:even_num]+" "+ERR_MSGS[:use_to_a] if size2ret.odd?
-      super
+      _return_this_or_other{
+        @array[arg1, *rest]
+      }
     end
  
 
@@ -698,17 +748,23 @@ $myd = false
       end
 
       # Simple substitution to a single element
-      return super(arg1, val) if !arg2 && !arg1.class.method_defined?(:exclude_end?)
+      if !arg2 && !arg1.respond_to?(:exclude_end?)
+        return _return_this_or_other{
+          @array[arg1] = val
+        }
+      end
 
       check_bracket_args_type_error(arg1, arg2)  # Args are now either (Int, Int) or (Range)
 
-      # raise TypeError, "object to replace must be Array type with an even number of elements." if !val.class.method_defined?(:to_ary) || val.size.odd?
+      # raise TypeError, "object to replace must be Array type with an even number of elements." if !val.respond_to?(:to_ary) || val.size.odd?
 
       vals = (val.to_ary rescue [val])
       if arg2
         size2delete = size2extract(arg1, arg2, ignore_error: true)  # maybe nil (if the index is too small).
         raise ArgumentError, "odd-even parity of size of array to replace must be identical to that to slice." if size2delete && ((size2delete % 2) != (vals.size % 2))
-        return super
+        return _return_this_or_other{
+          @array[arg1] = val
+        }
       end
 
       begin
@@ -727,41 +783,53 @@ $myd = false
 
       size2delete = size2extract(rang, skip_renormalize: true)
       raise ArgumentError, "odd-even parity of size of array to replace must be identical to that to slice." if size2delete && ((size2delete % 2) != (vals.size % 2))
-      ret = super
+      @array[arg1] = val
 
       # The result may not be in an even number anymore.  Correct it.
-      Boundary.insert_original_b4_part(size, "") if size.odd?
+      Boundary.insert(@array.size, "") if @array.size.odd?   ############## is it correct???
 
       # Original method may fill some elements of the array with String or even nil.  
       normalize!
-      ret
     end
 
     # Array#insert
     #
     # The most basic method to add/insert elements to self.  Called from {#[]=} and {#push}, for example.
     #
-    # If ind is greater than size, a number of "", as opposed to nil, are inserted.
+    # The maximum permitted position index is the size of self,s
+    # unlike +Array#insert+, which allows an index larger than the size,
+    # in which case +nil+ is inserted in between.
+    #
+    # The number of the inserted elements must be always even.
     #
-    # @param ind [Index]
-    # @param rest [Array] This must have an even number of arguments, unless ind is larger than the array size and an odd number.
-    # @option primitive: [String] if true (Def: false), the original {#insert_original_b4_part} is called.
+    # @param ind [Index] +rest+ is inserted *before* +ind+ if non-negative and *after* if negative.
+    # @param rest [Array] This must have an even number of arguments.
+    # @option primitive: [Boolean] if true (Def: false), no wrapper action is performed.
     # @return [self]
     def insert(ind, *rest, primitive: false)
-      return insert_original_b4_part(ind, *rest) if primitive
-      ipos = positive_array_index_checked(ind, self)
-      if    rest.size.even? && (ipos > size - 1) && ipos.even?  # ipos.even? is equivalent to index_para?(ipos), i.e., "is the index for Paragraph?"
-        raise ArgumentError, sprintf("number of arguments (%d) must be odd for index %s.", rest.size, ind)
-      elsif rest.size.odd?  && (ipos <= size - 1)
+      #return insert_original_b4_part(ind, *rest) if primitive
+      return _return_this_or_other(@array.insert(ind, *rest)) if primitive
+
+      ipos = positive_array_index_checked(ind, @array)  # IndexError may be raised.
+      ipos += 1 if ind < 0
+      # If ipos is negative, it should be inserted AFTER the index according to Array#index,
+      # whereas if ipos is non-negative, inserted BEFORE.
+
+      if ipos > @array.size
+        raise IndexError, sprintf("index (%s) too large for array: maximum: %d.", ipos, @array.size)
+      elsif rest.size.odd?
         raise ArgumentError, sprintf("number of arguments (%d) must be even.", rest.size)
       end
 
-      if ipos >= size
-        rest = Array.new(ipos - size).map{|i| ""} + rest
-        ipos = size
-      end
+      return self if rest.empty?
 
-      super(ipos, rest)
+      begin
+        _return_this_or_other{
+          @array.insert(ipos, *rest) && normalize! && self
+        }
+      rescue PlainText::PartNormalizeError => err
+        raise TypeError, err.message
+      end
     end
 
 
@@ -771,24 +839,24 @@ $myd = false
     #
     # @param arg1 [Integer, Range]
     # @option arg2 [Integer, NilClass]
-    # @option primitive: [Boolean] if true (Def: false), the original {#insert_original_b4_part} is called.
+    # @option primitive: [Boolean] if true (Def: false), no wrapper action is performed.
     # @return as self or NilClass
     def slice!(arg1, *rest, primitive: false)
-      return slice_original_b4_part!(arg1, *rest) if primitive
+      #return slice_original_b4_part!(arg1, *rest) if primitive
+      return _return_this_or_other(@array.slice(ind, *rest)) if primitive
 
       arg2 = rest[0]
 
       # Simple substitution to a single element
-      raise ArgumentError, ERR_MSGS[:even_num] if !arg2 && !arg1.class.method_defined?(:exclude_end?)
+      raise ArgumentError, ERR_MSGS[:even_num] if !arg2 && !arg1.respond_to?(:exclude_end?)
 
       check_bracket_args_type_error(arg1, arg2)  # Args are now either (Int, Int) or (Range)
 
       if arg2
         size2delete = size2extract(arg1, arg2, ignore_error: true)  # maybe nil (if the index is too small).
-        # raise ArgumentError, ERR_MSGS[:even_num] if arg2.to_int.odd?
         raise ArgumentError, ERR_MSGS[:even_num] if size2delete && size2delete.odd?
         raise ArgumentError, "odd index is not allowed as the starting Range for #{self.class.name}.  It must be even." if arg1.odd?  # Because the returned value is this class of instance.
-        return super(arg1, *rest)
+        return _return_this_or_other(@array.slice!(arg1, *rest))
       end
 
       begin
@@ -799,12 +867,13 @@ $myd = false
 
       raise RangeError if rang.begin < 0 || rang.end < 0
 
-      return super(arg1, *rest) if (rang.begin > rang.end)  # nil or [] is returned
+      return _return_this_or_other(@array.slice!(arg1, *rest)) if (rang.begin > rang.end)  # nil or [] is returned
+      
 
       size2delete = size2extract(rang, skip_renormalize: true)
       raise ArgumentError, ERR_MSGS[:even_num] if size2delete && size2delete.odd? 
       raise ArgumentError, "odd index is not allowed as the starting Range for #{self.class.name}.  It must be even." if rang.begin.odd?  # Because the returned value is this class of instance.
-      super(arg1, *rest)
+      _return_this_or_other(@array.slice!(arg1, *rest))
     end
  
  
@@ -816,8 +885,8 @@ $myd = false
     #
     # @return [self, NilClass]
     def compact!
-      ret = super
-      ret ? ret.normalize!(recursive: false) : ret
+      ret = @array.send(__method__)
+      ret ? normalize!(recursive: false) : ret
     end
 
     # Array#concat
@@ -827,7 +896,7 @@ $myd = false
     # @param rest [Array<Array>]
     # @return [self]
     def concat(*rest)
-      insert(size, *(rest.sum([])))
+      insert(@array.size, *(rest.sum([])))
     end
 
     # Array#push
@@ -863,9 +932,9 @@ $myd = false
     # @raise [TypeError] if not conforms.
     def check_bracket_args_type_error(arg1, arg2=nil)
       if arg2
-        raise TypeError, sprintf("no implicit conversion of #{arg2.class} into Integer") if !arg2.class.method_defined?(:to_int)
+        raise TypeError, sprintf("no implicit conversion of #{arg2.class} into Integer") if !arg2.respond_to?(:to_int)
       else
-        raise TypeError if !arg1.class.method_defined?(:exclude_end?)
+        raise TypeError if !arg1.respond_to?(:exclude_end?)
       end
     end
     private :check_bracket_args_type_error
@@ -875,11 +944,11 @@ $myd = false
     #
     # @return [Boundary] all the descendants' last Boundaries merged.
     def emptify_last_boundary!
-      return Boundary::Empty.dup if size == 0
+      return Boundary::Empty.dup if @array.size == 0
       ret = ""
-      ret << prt.public_send(__method__) if prt.class.method_defined? __method__
-      ret << self[-1]
-      self[-1] = Boundary::Empty.dup
+      ret << prt.public_send(__method__) if prt.respond_to? __method__
+      ret << @array[-1]
+      @array[-1] = Boundary::Empty.dup
       ret
     end
     private :emptify_last_boundary!
@@ -890,8 +959,8 @@ $myd = false
     # @param index [Integer]
     # @return [Integer, nil] nil if a too large index is specified.
     def get_valid_ipos_for_boundary(index)
-      i_pos = positive_array_index_checked(index, self)
-      raise ArgumentError, "Index #{index} specified was for Para, which should be for Boundary." if index_para?(i_pos, skip_check: true)
+      i_pos = positive_array_index_checked(index, @array)
+      raise ArgumentError, "Index #{index} specified was for Para, which should be for Boundary." if index_para?(i_pos, accept_negative: false)
       (i_pos > size - 1) ? nil : i_pos
     end
     private :get_valid_ipos_for_boundary
@@ -899,44 +968,44 @@ $myd = false
 
     # Core routine for {#map_boundary} and similar.
     #
-    # @option map opts: [Boolean] if true (Default), map is performed. Else just each.
+    # @option do_map opts: [Boolean] if true (Default), map is performed. Else just each.
     # @option with_index: [Boolean] if true (Default: false), yield with also index
     # @option recursive: [Boolean] if true (Default), map is performed recursively.
     # @return as self if map: is true, else void
-    def map_boundary_core(map: true, with_index: false, recursive: true, **kwd, &bl)
+    def map_boundary_core(do_map: true, with_index: false, recursive: true, **kwd, &bl)
       ind = -1
-      arnew = map{ |ec|
+      arnew = @array.map{ |ec|
         ind += 1
-        if recursive && index_para?(ind, skip_check: true) && ec.class.method_defined?(__method__)
+        if recursive && index_para?(ind, accept_negative: false) && ec.respond_to?(__method__)
           ec.public_send(__method__, recursive: true, **kwd, &bl)
-        elsif !index_para?(ind, skip_check: true)
+        elsif !index_para?(ind, accept_negative: false)
           with_index ? yield(ec, ind) : yield(ec)
         else
           ec
         end
       }
-      self.class.new arnew, recursive: recursive, **kwd if map
+      self.class.new arnew, recursive: recursive, **kwd if do_map
     end
     private :map_boundary_core
 
     # Core routine for {#map_para}
     #
-    # @option map: [Boolean] if true (Default), map is performed. Else just each.
+    # @option do_map: [Boolean] if true (Default), map is performed. Else just each.
     # @option with_index: [Boolean] if true (Default: false), yield with also index
     # @option recursive: [Boolean] if true (Default), map is performed recursively.
     # @return as self
     # @see #initialize for the other options (:compact and :compacter)
-    def map_para_core(map: true, with_index: false, recursive: true, **kwd, &bl)
+    def map_para_core(do_map: true, with_index: false, recursive: true, **kwd, &bl)
       ind = -1
       new_paras = paras.map{ |ec|
         ind += 1
-        if recursive && ec.class.method_defined?(__method__)
+        if recursive && ec.respond_to?(__method__)
           ec.public_send(__method__, recursive: true, **kwd, &bl)
         else
           with_index ? yield(ec, ind) : yield(ec)
         end
       }
-      self.class.new new_paras, boundaries, recursive: recursive, **kwd if map
+      self.class.new new_paras, boundaries, recursive: recursive, **kwd if do_map
     end
     private :map_para_core
 
@@ -948,18 +1017,25 @@ $myd = false
     # @option ignore_array_boundary: [Boolean] if true (Default), even if a Boundary element (odd-numbered index) is an Array, ignore it.
     # @return [Part, Paragraph, Boundary]
     def normalize_core(ea, i, recursive: true, ignore_array_boundary: true)
-      if    ea.class.method_defined?(:to_ary)
-        if index_para?(i, skip_check: true) || ignore_array_boundary
+      if    ea.respond_to?(:to_ary)
+        if index_para?(i, accept_negative: false) || ignore_array_boundary
           (/\APlainText::/ =~ ea.class.name && defined?(ea.normalize)) ? (recursive ? ea.normalize : ea) : self.class.new(ea, recursive: recursive)
         else
-          raise "Index ({#i}) is an Array or its child, but it should be Boundary or String."
+          raise "Element at index ({#i}) is a Part or Array, but it should be Boundary or String."
+        end
+      elsif ea.respond_to?(:to_str)
+        if   i.even? && self.class.boundary?(ea)
+          msg = "not be Boundary"
+        elsif i.odd? && self.class.paragraph?(ea)
+          msg = "be neither Part nor Paragraph"
         end
-      elsif ea.class.method_defined?(:to_str)
+        raise PlainText::PartNormalizeError, sprintf("Element at index=(%d) must %s", i, msg) if msg
+
         if /\APlainText::/ =~ ea.class.name
           # Paragraph or Boundary
-          ea.unicode_normalize
+          ea.unicode_normalize  # Unicode-normalized new object
         else
-          if index_para?(i, skip_check: true)
+          if index_para?(i, accept_negative: false)
             Paragraph.new(ea.unicode_normalize || "")
           else
             Boundary.new( ea.unicode_normalize || "")
@@ -979,7 +1055,7 @@ $myd = false
     # @raise [IndexError] if too negative index is specified.
     def normalize_index_range(rng, **kwd)
       # NOTE to developers: (0..-1).to_a returns [] (!)
-      arpair = [rng.begin, rng.end].to_a.map{ |i| positive_array_index_checked(i, self, **kwd) }
+      arpair = [rng.begin, rng.end].to_a.map{ |i| positive_array_index_checked(i, @array, **kwd) }
       arpair[1] -= 1 if rng.exclude_end?
       (arpair[0]..arpair[1])
     end
@@ -1002,11 +1078,11 @@ $myd = false
     # @return [Integer, NilClass] nil if an Error is raised with ignore_error being true
     def size2extract(arg1, arg2=nil, ignore_error: false, skip_renormalize: false, **kwd)
       begin
-        if arg1.class.method_defined? :exclude_end?
+        if arg1.respond_to? :exclude_end?
           rng = arg1
           rng = normalize_index_range(rng, **kwd) if !skip_renormalize
         else
-          ipos = positive_array_index_checked(arg1, self)
+          ipos = positive_array_index_checked(arg1, @array)
           rng = (ipos..(ipos+arg2.to_int-1))
         end
         return 0 if rng.begin > size-1
@@ -1024,48 +1100,13 @@ $myd = false
 end # module PlainText
 
 
-####################################################
-# Modifies Array
-####################################################
-
-class Array
-
-  # Original equal and plus operators of Array
-  hsmethod = {
-    :equal_original_b4_part? => :== ,
-    # :plus_operator_original_b4_part => :+
-  }
-
-  hsmethod.each_pair do |k, ea_orig|
-    if self.method_defined?(k)
-      # To Developer: If you see this message, switch the DEBUG flag on (-d option) and run it.
-      warn sprintf("WARNING: Method %s#%s has been already defined, which should not be.  Contact the code developer. Line %d in %s%s", self.name, k.to_s, __FILE__, __LINE__, ($DEBUG ? "\n"+caller_locations.join("\n").map{|i| "  "+i} : ""))
-    else
-      alias_method k, ea_orig
-    end
-  end
-
-  # Equal operator modified to deal with {PlainText::Part}
-  #
-  # @param other [Object]
-  def ==(other)
-    return false if !other.class.method_defined?(:to_ary)
-    %i(paras boundaries).each do |ea_m|  # %i(...) defined in Ruby 2.0 and later
-      return equal_original_b4_part?(other) if !other.class.method_defined?(ea_m)
-      return false if !self.class.method_defined?(ea_m) || (self.public_send(ea_m) != other.public_send(ea_m))  # public_send() defined in Ruby 2.0 (1.9?) and later
-    end
-    true
-  end
-
-end
-
 ####################################################
 # require (after the module is defined)
 ####################################################
 
-require 'plain_text/part/paragraph'
-require 'plain_text/part/boundary'
-require "plain_text/parse_rule"
+require_relative 'part/paragraph'
+require_relative 'part/boundary'
+require_relative "parse_rule"
 
 #######
 # idea