Class: PlainText::Part

Inherits:
Array
  • Object
show all
Includes:
Util
Defined in:
lib/plain_text/part.rb,
lib/plain_text/part/boundary.rb,
lib/plain_text/part/paragraph.rb

Overview

TODO:

methods

  • flatten

  • SAFE level for command-line tools?

Class to represent a Chapter-like entity 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, followed by a Boundary-type String-like instance. The first element is always a former and the last element is always a latter.

Essentially, the instance of this class holds the order information between sub-Part-s (< Array) and/or Paragraph-s (< String) and Boundary-s (< String).

An example instance looks like this:

Part (
  (0) Paragraph::Empty,
  (1) Boundary::General,
  (2) Part::ArticleHeader(
        (0) Paragraph::Title,
        (1) Boundary::Empty
      ),
  (3) Boundary::TitleMain,
  (4) Part::ArticleMain(
        (0) Part::ArticleSection(
              (0) Paragraph::Title,
              (1) Boundary::General,
              (2) Paragraph::General,
              (3) Boundary::General,
              (4) Part::ArticleSubSection(...),
              (5) Boundary::General,
              (6) Paragraph::General,
              (7) Boundary::Empty
            ),
        (1) Boundary::General,
        (2) Paragraph::General,
        (3) Boundary::Empty
      ),
  (5) 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!, #select!, #filter!, #keep_if, #flatten!, #uniq! may alter the content in a way it breaks the self-inconsistency of the object. Use it at your own risk, if you wish (or don’t).

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.

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.

  • 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.

  • Update:

    • 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.

Author:

  • Masa Sakano (Wise Babel Ltd)

Defined Under Namespace

Classes: Boundary, Paragraph

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(arin, boundaries = nil, recursive: true, compact: true, compacter: true) ⇒ self

Parameters:

  • arin (Array) —

    of [Paragraph1, Boundary1, Para2, Bd2, …] or just Paragraphs if boundaries is given as the second arguments

  • boundaries (Array) (defaults to: nil) —

    of Boundary

  • recursive: (Hash) (defaults to: true) —

    a customizable set of options

  • compact: (Hash) (defaults to: true) —

    a customizable set of options

  • compacter: (Hash) (defaults to: true) —

    a customizable set of options



92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/plain_text/part.rb', line 92

def initialize(arin, boundaries=nil, recursive: true, compact: true, compacter: true)
  if !boundaries
    super(arin)
  else

    armain = []
    arin.each_with_index do |ea_e, i|
      armain << ea_e
      armain << (boundaries[i] || Boundary.new(''))
    end
    super armain
  end
  normalize!(recursive: recursive, compact: compact, compacter: compacter)
end

Class Method Details

.parse(inprm, rule: PlainText::ParseRule::RuleConsecutiveLbs) ⇒ PlainText::Part

Parses a given string (or PlainText::Part) and returns this class of instance.

Parameters:

  • inprm (String, Array, Part)
  • rule: (Hash) (defaults to: PlainText::ParseRule::RuleConsecutiveLbs) —

    a customizable set of options

Returns:



112
113
114
115
 
# File 'lib/plain_text/part.rb', line 112

def self.parse(inprm, rule: PlainText::ParseRule::RuleConsecutiveLbs)
  arin = rule.apply(inprm)
  self.new(arin)
end

Instance Method Details

#+(other) ⇒ Object

Plus operator

Parameters:

  • other (Object)

Returns:

  • as self



603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
 
# File 'lib/plain_text/part.rb', line 603

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
  ret.normalize!
end

#-(other) ⇒ Object

Minus operator

Parameters:

  • other (Object)

Returns:

  • as self



628
629
630
631
 
# File 'lib/plain_text/part.rb', line 628

def -(other)
  ret = self.class.new super
  ret.normalize!
end

#==(other) ⇒ Object

Equal operator

Unless both are kind of Part instances, false is returned. If you want to make comparison in the Array level, do

p1.to_a == a1.to_a

Parameters:

  • other (Object) 


581
582
583
584
585
586
587
 
# File 'lib/plain_text/part.rb', line 581

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 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
  end
  super
end

#[](arg1, *rest) ⇒ Object Also known as: slice

Returns a partial Part-Array (or Object, if a single Integer is specified)

Because the returned object is this class of instance (when a pair of Integer or Range is specified), only an even number of elements, starting from an even number of index, is allowed.

Parameters:

  • arg1 (Integer, Range)
  • arg2 (Hash) —

    a customizable set of options

Returns:

  • (Object)

Raises:

  • (RangeError) 


650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
 
# File 'lib/plain_text/part.rb', line 650

def [](arg1, *rest)
  arg2 = rest[0]
  return super(arg1) if !arg2 && !arg1.class.method_defined?(:exclude_end?)

  check_bracket_args_type_error(arg1, arg2)  # Args are now either (Int, Int) or (Range)

  if arg2
    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?
    rescue TypeError, IndexError
      # handled by super
    end
    return super
  end

  begin
    rang = normalize_index_range(arg1)
  rescue IndexError #=> err
    return nil
    # raise RangeError, err.message
  end

  raise RangeError if rang.begin < 0 || rang.end < 0

  # 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
  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
end

#[]=(arg1, *rest) ⇒ Object

Replaces some of the Array content.

Parameters:

  • arg1 (Integer, Range)
  • arg2 (Hash) —

    a customizable set of options

Returns:

  • (Object)

Raises:

  • (RangeError) 


693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
 
# File 'lib/plain_text/part.rb', line 693

def []=(arg1, *rest)
  if rest.size == 1
    arg2, val = [nil, rest[-1]]
  else
    arg2, val = rest
  end

  # Simple substitution to a single element
  return super(arg1, val) if !arg2 && !arg1.class.method_defined?(:exclude_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?

  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
  end

  begin
    rang = normalize_index_range(arg1)
  rescue IndexError => err
    raise RangeError, err.message
  end

  raise RangeError if rang.begin < 0 || rang.end < 0

  # The end is smaller than the begin in the positive index.  It is the same as insert (default in Ruby), except it returns the replaced Object (which may not be an Array).
  if rang.end < rang.begin
    insert(arg1, *vals)
    return val
  end

  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

  # The result may not be in an even number anymore.  Correct it.
  Boundary.insert_original_b4_part(size, "") if size.odd?

  # Original method may fill some elements of the array with String or even nil.  
  normalize!
  ret
end

#boundaries ⇒ Array<Boundary>

Returns an array of boundaries (odd-number-index elements), consisting of Boundaries

Returns:

See Also:



129
130
131
 
# File 'lib/plain_text/part.rb', line 129

def boundaries
  select.with_index { |_, i| i.odd? } rescue select.each_with_index { |_, i| i.odd? } # Rescue for Ruby 2.1 or earlier
end

#boundary_extended_at(index) ⇒ Array?

returns all the Boundaries immediately before the index and at it as an Array

See #squash_boundary_at! to squash them.

Parameters:

  • index (Integer)

Returns:

  • (Array, nil) —

    nil if a too large index is specified.



139
140
141
142
143
144
145
 
# File 'lib/plain_text/part.rb', line 139

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]
end

#compact! ⇒ self, NilClass

Array#compact!

If changed, re-#normalize! it.

Returns:

  • (self, NilClass) 


818
819
820
821
 
# File 'lib/plain_text/part.rb', line 818

def compact!
  ret = super
  ret ? ret.normalize!(recursive: false) : ret
end

#concat(*rest) ⇒ self

Array#concat

Parameters:

Returns:

  • (self)

See Also:



829
830
831
 
# File 'lib/plain_text/part.rb', line 829

def concat(*rest)
  insert(size, *(rest.sum([])))
end

#deepcopy ⇒ Part

Returns a dup-ped instance with all the Arrays and Strings dup-ped.

Returns:



150
151
152
 
# File 'lib/plain_text/part.rb', line 150

def deepcopy
  dup.map!{ |i| i.class.method_defined?(:deepcopy) ? i.deepcopy : i.dup }
end

#each_boundary_with_index(**kwd, &bl) ⇒ Object

each method for boundaries only, providing also the index (always an odd number) to the block.

For just looping over the elements of #boundaries, do simply

boundaries.each do |ec|
end

The indices provided in this method are for the main Array, and hence different from #boundaries.each_with_index

Parameters:

  • recursive: (Hash) —

    a customizable set of options

Returns:

  • as self



166
167
168
 
# File 'lib/plain_text/part.rb', line 166

def each_boundary_with_index(**kwd, &bl)
  map_boundary_core(map: false, with_index: true, **kwd, &bl)
end

#each_para_with_index(**kwd, &bl) ⇒ Object

each method for Paras only, providing also the index (always an even number) to the block.

For just looping over the elements of #paras, do simply

paras.each do |ec|
end

The indices provided in this method are for the main Array, and hence different from #paras.each_with_index

Parameters:

  • recursive: (Hash) —

    a customizable set of options

Returns:

  • as self



182
183
184
 
# File 'lib/plain_text/part.rb', line 182

def each_para_with_index(**kwd, &bl)
  map_para_core(map: false, with_index: false, **kwd, &bl)
end

#first_significant_element ⇒ Integer?

The first significant (=non-empty) element.

If the returned value is non-nil and destructively altered, self changes.

Returns:

  • (Integer, nil) —

    if self.empty? nil is returned.



191
192
193
194
 
# File 'lib/plain_text/part.rb', line 191

def first_significant_element
  (i = first_significant_index) || return
  self[i]
end

#first_significant_index ⇒ Integer?

Index of the first significant (=non-empty) element.

If every element is empty, the last index is returned.

Returns:

  • (Integer, nil) —

    if self.empty? nil is returned.



201
202
203
204
205
206
207
 
# File 'lib/plain_text/part.rb', line 201

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
end

#index_para?(i, skip_check: false) ⇒ Boolean

True if the index should be semantically for Paragraph?

Parameters:

  • i (Integer) —

    index for the array of self

  • skip_check: (Hash) (defaults to: false) —

    a customizable set of options

Returns:

  • (Boolean)

See Also:



214
215
216
 
# File 'lib/plain_text/part.rb', line 214

def index_para?(i, skip_check: false)
  skip_check ? i.even? : positive_array_index_checked(i, self).even?
end

#insert(ind, *rest, primitive: false) ⇒ self

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.

Parameters:

  • ind (Index)
  • rest (Array) —

    This must have an even number of arguments, unless ind is larger than the array size and an odd number.

  • primitive: (Hash) (defaults to: false) —

    a customizable set of options

Returns:

  • (self) 


750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
 
# File 'lib/plain_text/part.rb', line 750

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)
    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

  super(ipos, rest)
end

#inspect ⇒ String

Returns:



558
559
560
 
# File 'lib/plain_text/part.rb', line 558

def inspect
  self.class.name + super
end

#last_significant_element ⇒ Integer?

The last significant (=non-empty) element.

If the returned value is non-nil and destructively altered, self changes.

Returns:

  • (Integer, nil) —

    if self.empty? nil is returned.



223
224
225
226
 
# File 'lib/plain_text/part.rb', line 223

def last_significant_element
  (i = last_significant_index) || return
  self[i]
end

#last_significant_index ⇒ Integer?

Index of the last significant (=non-empty) element.

If every element is empty, 0 is returned.

Returns:

  • (Integer, nil) —

    if self.empty? nil is returned.



233
234
235
236
237
238
239
 
# File 'lib/plain_text/part.rb', line 233

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
  end
  return 0
end

#map_boundary(**kwd, &bl) ⇒ Object

map method for boundaries only, returning a copied self.

If recursive is true (Default), any Boundaries in the descendant Parts are also handled.

If a Boundary is set nil or empty, along with the preceding Paragraph, the pair is removed from the returned instance in Default (:compact and :compacter options

Parameters:

  • recursive: (Hash) —

    a customizable set of options

Returns:

  • as self

See Also:



252
253
254
 
# File 'lib/plain_text/part.rb', line 252

def map_boundary(**kwd, &bl)
  map_boundary_core(with_index: false, **kwd, &bl)
end

#map_boundary_with_index(**kwd, &bl) ⇒ Object

map method for boundaries only, providing also the index (always an odd number) to the block, returning a copied self.

Parameters:

  • recursive: (Hash) —

    a customizable set of options

Returns:

  • as self



260
261
262
 
# File 'lib/plain_text/part.rb', line 260

def map_boundary_with_index(**kwd, &bl)
  map_boundary_core(with_index: true, **kwd, &bl)
end

#map_para(**kwd, &bl) ⇒ Object

map method for Paras only, returning a copied self.

If recursive is true (Default), any Paras in the descendant Parts are also handled.

If a Paragraph is set nil or empty, along with the following Boundary, the pair is removed from the returned instance in Default (:compact and :compacter options

Parameters:

  • recursive: (Hash) —

    a customizable set of options

Returns:

  • as self

See Also:



275
276
277
 
# File 'lib/plain_text/part.rb', line 275

def map_para(**kwd, &bl)
  map_para_core(with_index: false, **kwd, &bl)
end

#map_para_with_index(**kwd, &bl) ⇒ Object

map method for paras only, providing also the index (always an even number) to the block, returning a copied self.

Parameters:

  • recursive: (Hash) —

    a customizable set of options

Returns:

  • as self



283
284
285
 
# File 'lib/plain_text/part.rb', line 283

def map_para_with_index(**kwd, &bl)
  map_para_core(with_index: false, **kwd, &bl)
end

#set(index1, index2, *rest) ⇒ self? #set(range) ⇒ self?

merge multiple paragraphs

The boundaries between them are simply joined as String as they are.

Overloads:

  • #set(index1, index2, *rest) ⇒ self?

    With a list of indices. Unless use_para_index is true, this means the main Array index. Namely, if Part is [P0, B0, P1, B1, P2, B2, B3] and if you want to merge P1 and P2, you specify as (2,3,4) or (2,4). If use_para_index is true, specify as (1,2).

    Parameters:

    • index1 (Integer) —

      the first index to merge

    • index2 (Integer) —

      the second index to merge, and so on…

  • #set(range) ⇒ self?

    With a range of the indices to merge. Unless use_para_index is true, this means the main Array index. See the first overload set about it.

    Parameters:

    • range (Range) —

      describe value param

Parameters:

  • use_para_index (Boolean) (defaults to: false) —

    If false (Default), the indices are for the main indices (alternative between Paras and Boundaries, starting from Para). If true, the indices are as obtained with #paras, namely the array containing only Paras.

Returns:

  • (self, nil) —

    nil if nothing is merged (because of wrong indices).



333
334
335
336
337
338
339
340
341
 
# File 'lib/plain_text/part.rb', line 333

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)
  self
end

#merge_para_if {|ary, b1, b2, i| ... } ⇒ self, false

merge Paras if they satisfy the conditions.

A group of two Paras and the Boundaries in between and before and after is passed to the block consecutively.

Yields:

  • (ary, b1, b2, i) —

    Returns true if the two paragraphs should be merged.

Yield Parameters:

  • ary (Array) —

    of [Para1st, BoundaryBetween, Para2nd]

  • b1 (Boundary) —

    Boundary-String before the first Para (nil for the first one)

  • b2 (Boundary) —

    Boundary-String after the second Para

  • i (Integer) —

    Index of the first Para

Yield Returns:

  • (Boolean, Symbol) —

    True if they should be merged. :abort if cancel it.

Returns:

  • (self, false) —

    false if no pairs of Paras are merged, else self.



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/plain_text/part.rb', line 299

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)
    return false                 if do_merge == :abort
    arind2del.push ei, ei+1, ei+2 if do_merge 
  end

  return false if arind2del.empty? 
  arind2del.uniq!

  (arind2ranges arind2del).reverse.each do |er|
    merge_para!(er)
  end
  return self
end

#normalize(recursive: true, ignore_array_boundary: true, compact: true, compacter: true) ⇒ Object

Non-destructive version of #normalize!

Parameters:

  • recursive: (Hash) (defaults to: true) —

    a customizable set of options

  • ignore_array_boundary: (Hash) (defaults to: true) —

    a customizable set of options

  • compact: (Hash) (defaults to: true) —

    a customizable set of options

  • compacter: (Hash) (defaults to: true) —

    a customizable set of options

Returns:

  • as self

See Also:



429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
 
# File 'lib/plain_text/part.rb', line 429

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| 
      # 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?)
    end
  end

  i = -1
  self.class.new(
    arall.map{ |ea|
      i += 1
      normalize_core(ea, i, recursive: recursive)
    } + (arall.size.odd? ? [Boundary.new('')] : [])
  )
end

#normalize!(recursive: true, ignore_array_boundary: true, compact: true, compacter: true) ⇒ self

Normalize the content, making sure it has an even number of elements

The even and odd number elements are, if bare Strings or Array, converted into Paeagraph and Boundary, or Part, respectively. If not, Exception is raised. Note nil is conveted into either an empty Paragraph or Boundary.

Parameters:

  • recursive: (Hash) (defaults to: true) —

    a customizable set of options

  • ignore_array_boundary: (Hash) (defaults to: true) —

    a customizable set of options

  • compact: (Hash) (defaults to: true) —

    a customizable set of options

  • compacter: (Hash) (defaults to: true) —

    a customizable set of options

Returns:

  • (self) 


400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
 
# File 'lib/plain_text/part.rb', line 400

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| 
      # 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?)
    end
  end

  i = -1
  map!{ |ea|
    i += 1
    normalize_core(ea, i, recursive: recursive)
  }
  insert_original_b4_part(size, Boundary.new('')) if size.odd?
  self
end

#paras ⇒ Array<Part, Paragraph>

Returns an array of Paras (even-number-index elements), consisting of Part and/or Paragraph

Returns:

See Also:



456
457
458
459
 
# File 'lib/plain_text/part.rb', line 456

def paras
  select.with_index { |_, i| i.even? } rescue select.each_with_index { |_, i| i.even? } # Rescue for Ruby 2.1 or earlier
  # ret.freeze
end

#push(*rest) ⇒ self Also known as: append

Array#push

Parameters:

Returns:

  • (self)

See Also:



839
840
841
 
# File 'lib/plain_text/part.rb', line 839

def push(*rest)
  concat(rest)
end

#reparse(**kwd) ⇒ PlainText::Part

Non-destructive version of #reparse!

Parameters:

  • rule (Hash) —

    a customizable set of options

  • name (Hash) —

    a customizable set of options

  • range (Hash) —

    a customizable set of options

Returns:



476
477
478
479
480
 
# File 'lib/plain_text/part.rb', line 476

def reparse(**kwd)
  ret = self.dup
  ret.reparse!(**kwd)
  ret
end

#reparse!(rule: PlainText::ParseRule::RuleConsecutiveLbs, name: nil, range: (0..-1)) ⇒ self

Reparses self or a part of it.

Parameters:

  • rule (Hash) (defaults to: PlainText::ParseRule::RuleConsecutiveLbs) —

    a customizable set of options

  • name (Hash) (defaults to: nil) —

    a customizable set of options

  • range (Hash) (defaults to: (0..-1)) —

    a customizable set of options

Options Hash (rule:):

Options Hash (name:):

  • Identifier (String, Symbol, Integer, nil) —

    of rule, if need to specify.

Options Hash (range:):

  • Range (Range, nil) —

    of indices of self to reparse. In Default, the entire self.

Returns:

  • (self) 


467
468
469
470
 
# File 'lib/plain_text/part.rb', line 467

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)
  self
end

#slice!(arg1, *rest, primitive: false) ⇒ Object

Delete elements and return the deleted content or nil if nothing is deleted.

The number of elements to be deleted must be even.

Parameters:

  • arg1 (Integer, Range)
  • arg2 (Hash) —

    a customizable set of options

  • primitive: (Hash) (defaults to: false) —

    a customizable set of options

Returns:

  • as self or NilClass

Raises:

  • (ArgumentError) 


776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
 
# File 'lib/plain_text/part.rb', line 776

def slice!(arg1, *rest, primitive: false)
  return slice_original_b4_part!(arg1, *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?)

  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)
  end

  begin
    rang = normalize_index_range(arg1)
  rescue IndexError => err
    raise RangeError, err.message
  end

  raise RangeError if rang.begin < 0 || rang.end < 0

  return super(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)
end

#squash_boundary_at!(index) ⇒ Boundary?

Emptifies all the Boundaries immediately before the Boundary at the index and squashes it to the one at it.

See #boundary_extended_at to view them.

Parameters:

  • index (Integer)

Returns:

  • (Boundary, nil) —

    nil if a too large index is specified.



489
490
491
492
493
494
495
 
# File 'lib/plain_text/part.rb', line 489

def squash_boundary_at!(index)
  (i_pos = get_valid_ipos_for_boundary(index)) || return
  prt = self[i_pos-1]
  m = :emptify_last_boundary!
  self[i_pos] << prt.public_send(m) if prt.class.method_defined? m
  self[i_pos]
end

#squash_boundaryies! ⇒ self

Wrapper of #squash_boundary_at! to loop over the whole PlainText::Part

Returns:

  • (self) 


501
502
503
504
505
506
 
# File 'lib/plain_text/part.rb', line 501

def squash_boundaryies!
  each_boundary_with_index do |ec, i|
    squash_boundary_at!(i)
  end
  self
end

#subclass_name ⇒ String

Boundary sub-class name only

Make sure your class is a child class of Part Otherwise this method would not be inherited, obviously.

Examples:

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"

Returns:

See Also:



525
526
527
528
 
# File 'lib/plain_text/part.rb', line 525

def subclass_name
  printf "__method__=(%s)\n", __method__
  self.class.name.split(/\A#{Regexp.quote method(__method__).owner.name}::/)[1] || ''
end