plain_text 0.7.1 → 0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45fae90fbac6ba53a5f7c21d6a21b3f858d3db734d770eec82fdbb9838755b11
-  data.tar.gz: 2817d7be2e4e7a3029d00922177c881ae4cdad2c940bb764f8f49cd6c1b08e00
+  metadata.gz: a03c794c7f63a55e51e3f57aeb9345dbb2e60c416525f1649037429539f33697
+  data.tar.gz: b7c80770207ca932edbf9af2fce56586b56271aad5813f2a8c63761a070257f0
 SHA512:
-  metadata.gz: 5443ef391054d08a06f3cef5a67316b0f13ddbf2f60f7689eb51f027aa73804e09418d0e021446cc32f90111047f36a862278a62b92017000055658756fb4759
-  data.tar.gz: 0b158d573ba75b957a0c063aace1bad6c378a23e3e8cd97afe2af6cbd71e79bf26cdd32cce748c0fefd24f61cd6d9053380178889c3c30673219d1bcb13b8809
+  metadata.gz: '080c21444032d57f10d5c62b75be779c915ec110f8902033c5abc46d6b4f668deee9da6f857ea0b75a0a8742be246830af16fc49cbe9045d610434f75d6993d5'
+  data.tar.gz: 75ad795005fcb38417130e4e06948eea36fa68525b50c623efda994d081085b0b70623d6812f81dc5c54d35b86e75647ae63818335edbeae28a576e6134889c6

data/.gitignore

@@ -36,6 +36,7 @@
 *.elc
 *.pyc
 \#*\#
+.#*[a-zA-Z]*
 
 # Elastic Beanstalk Files
 .elasticbeanstalk/*

data/ChangeLog

@@ -1,3 +1,14 @@
+-----
+(Version: 0.8)
+2022-09-14  Masa Sakano
+  * Major upgrade where parent classes changed from Array/String to Object.
+  
+    * Changed the parent classes for Part/Paragraph/Boundary from Array/String to Object.
+    * `PlainText::BuiltinType` introduced to contain common methods.
+    * `PlainText::Part::StringType` introduced for Paragraph/Boundary, to which many methods in the classes were transferred.
+    * Custom Exception is added: `lib/plain_text/error.rb`
+    * Some changes in detailed (minor) specifications.
+
 -----
 (Version: 0.7.1)
 2022-09-09  Masa Sakano

data/Makefile

@@ -20,5 +20,6 @@ test:
 
 ## yard2md_afterclean in Gem plain_text https://rubygems.org/gems/plain_text
 doc:
-	yard doc; [[ -x ".github" && ( "README.en.rdoc" -nt ".github/README.md" ) ]] && ( ruby -r rdoc -e 'puts RDoc::Markup::ToMarkdown.new.convert ARGF.read' < README.en.rdoc | yard2md_afterclean | ruby -e 'puts ARGF.read.sub(/(```)ruby(\nPart )/){$$1+"text"+$$2}' > .github/.README.md && mv .github/.README.md .github/README.md && echo ".github/README.md is updated." ) || exit 0
+	yard doc; [[ -x ".github" && ( "README.en.rdoc" -nt ".github/README.md" ) ]] && ( ruby -r rdoc -e 'puts RDoc::Markup::ToMarkdown.new.convert ARGF.read' < README.en.rdoc | yard2md_afterclean > .github/README.md.$$ && ( mv -f .github/README.md.$$ .github/README.md && echo ".github/README.md and .github/README.html are updated." && pandoc --from=gfm .github/README.md -o .github/README.html ) || ( echo "ERROR: failed to create .github/README.md" >&2 ) ) || exit 0
+## --privat does not show private methods??
 

data/README.en.rdoc

@@ -5,99 +5,99 @@
 
 This module provides utility functions and methods to handle plain
 text.  In the namespace, classes Part/Paragraph/Boundary are defined,
-which represent the logical structure of a document and another class
+which represent the logical structure of a document, and another class
 ParseRule, which describes the rules to parse plain text to produce a Part-type Ruby instance.
-This package also provides a few command-line programs, such as counting the number
-of characters (especially useful for documents in Asian (CJK)
+This package also contains a few command-line programs, such as counting the number
+of characters (which is especially useful for text in Asian (CJK)
 characters) and advanced head/tail commands.
 
 The master of this README file, as well as the document for all the methods, is found in
-{RubyGems/plain_text}[https://rubygems.org/gems/plain_text]
-and in {Github}[https://github.com/masasakano/plain_text]
+{RubyGems/plain_text}[https://rubygems.org/gems/plain_text],
+as well as in {Github}[https://github.com/masasakano/plain_text],
 where all the hyperlinks are active.
 
 == Design concept
 
 === PlainText - Module and root Namespace
 
-The original plain text should be in String in Ruby.
+The original plain text should be String in Ruby.
 
-The module {PlainText} offers some useful methods, such as,
-{PlainText#head} and {PlainText#tail}.  They are meant to be included
-in String.  However, it also contains some useful module functions,
+The module {PlainText} provides some useful methods, such as,
+{PlainText#head} and {PlainText#tail}, which are meant to be included
+in String.  The module also contains some useful module functions,
 such as, {PlainText.clean_text} and {PlainText.count_char}.
 
 === PlainText::Part - Core class to describe the logical structure
 
-In the namespace of this module, it contains {PlainText::Part} class,
-which is the heart to describe the logical structure of a document.
-It is basically a container class and indeed a sub-class of Array. It
-can contain either of other (multiple) {PlainText::Part} or more basic
-components of either of {PlainText::Part::Paragraph} and
-{PlainText::Part::Boundary}, both of which are sub-classes of String.
+The {PlainText::Part} class in the namespace of this module
+is the core class to describe the logical structure of a plain-text document.
+It is basically a container class and behaves like Array (it has been a
+subclass of Array up to Version 0.7). It
+contains one or more components of other {PlainText::Part} and
+{PlainText::Part::Paragraph}, each of which is always followed by
+a single {PlainText::Part::Boundary}.
+Both {PlainText::Part::Paragraph} and {PlainText::Part::Boundary}
+behave like String (they used to be subclasses of String up to Version 0.7).
 
 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
    )
 
-where the names of the subclasses (or constants) here are arbitrary, except for
+where the names of the subclasses are arbitrary, except for
 {PlainText::Part::Paragraph::Empty} and
 {PlainText::Part::Boundary::Empty}, which are pre-defined. Users can
 define their own subclasses to help organize the logical structure at
 their will.
 
-Basically, at every layer, every {PlainText::Part} or
-{PlainText::Part::Paragraph} is sandwiched by
-{PlainText::Part::Boundary}, except for the very first one.
-The former contains something significant on its own, whereas the
-latter (Boundary) contains nothing significant on its own, except they
-may indicate the type of the following (or preceding) entity, such as
-a title or section.
+{PlainText::Part} and {PlainText::Part::Paragraph} are supposed to contain something significant on its own, whereas
+{PlainText::Part::Boundary} contains a kind of separators, such as
+closing parentheses, spaces, newlines, and alike.
 
 In this library (document, classes and modules), the former and latter
 are collectively referred to as Para (or Paras) and Boundary (or
 Boundaries), respectively.  Namely, a Para means either of
 {PlainText::Part} and {PlainText::Part::Paragraph}.
 
-By performing +Part#join+ method, one can retrieve the entire document as a
-String instance any time, just like +Array#join+.
++Part#join+ method returns the entire plain-text document as a
+String instance, just like +Array#join+.
 
 === PlainText::ParseRule - Class to describe the rule of how to parse
 
 {PlainText::ParseRule} is the class to describe how to parse initially
 String, and subsequently {PlainText::Part}, which is basically an Array.
 {PlainText::ParseRule} is a container class and holds a set of ordered
-rules, each of which is either Proc or Regexp as a more simple rule.
-A rule, Proc, is defined by a user and is designed to receive either
+rules, each of which is either Proc or Regexp.
+
+A rule of Proc is defined by a user and is designed to receive either
 String (the first application only) or {PlainText::ParseRule} (Array)
 and to return a fully (or partially) parsed {PlainText::ParseRule}.
 In short, the rule descries how to determine from where to where a
 Paras and Boundaries are located — for example, what and where the
-sections and sub-sections are and so on are.
+sections and sub-sections and so on are.
 
 For example, if a rule is Regexp, it describes how to split a String;
 it is applied to String in the first application, but if it is
@@ -106,7 +106,7 @@ it is applied to each Para separately to split them further.
 
 {PlainText::ParseRule#apply} and {PlainText::Part.parse} are the
 standard methods to apply the rules to an object (either String or
-{PlainText::Part}.
+{PlainText::Part}).
 
 == Command-line tools
 
@@ -195,7 +195,7 @@ still not perfect but does some good automation job.
 
 Module {PlainText::Split} contains an instance method (and class
 method with the same name) {PlainText::Split#split_with_delimiter},
-which is included in String in default.  The method realises a
+which is included in String in default.  The method realizes a
 reversible split of String with a delimiter of an arbitrary Regexp.
 
 In the standard String#split, the following is the result, when
@@ -221,27 +221,33 @@ Work in progress...
 
 == Install
 
-This script requires {Ruby}[http://www.ruby-lang.org] Version 2.0
-or above (possibly 2.2 or above?).
+The easiest way to install this library is simply
+
+  gem install plain_text
+
+The library files should be installed in one of your
+<tt>$LOAD_PATH</tt> and also all the executables (commands) should be
+installed in one of your command-line search paths.
+
+Alternatively, get it from
+{http://rubygems.org/gems/plain_text},
+making sure the library path and command-line search path are set appropriately.
 
-For use of the library, if your Ruby script declares
+Then all you need to do is
 
   require "plain_text"
 
-all the related libraries should be read.
-If you +include PlainText+ from String, it would be handy, though
-not mandatory to use this library.
+in your Ruby script (or irb).
 
-As for the command-line script files, they can be put in any of your command-line search
-paths.  Make sure the RUBYLIB environment
-variable contains the library directory to this gem, which is
+This script requires {Ruby}[http://www.ruby-lang.org] Version 2.0
+or above (possibly 2.2 or above?).
 
-   /THIS/GEM/LIBRARY/PATH/plain_text/lib
+If you +include PlainText+ from String, it would be handy, though
+not mandatory to use this library.
 
-(which should be set automatically, as long as you use the standard Gem environment).
-You may need to modify the first line (Shebang line) of the script to suit your
-environment (it should be unnecessary for Linux and MacOS), or run it
-explicitly with your Ruby command as
+As for the shell-executables, you might need to modify the first line (Shebang line) of the scripts to suit your
+environment (it should be unnecessary for Linux and MacOS), or run them
+explicitly with your Ruby command, such as
 
    % /YOUR/ENV/ruby /YOUR/INSTALLED/countchar
 
@@ -257,7 +263,7 @@ interface for annotation but with easily-browsable {ChangeLog}[https://github.co
 
 === Tests
 
-Ruby codes under the directory <tt>test/</tt> are the test scripts.
+The test suite is located under the directory <tt>test/</tt>.
 You can run them from the top directory as <tt>ruby test/test_****.rb</tt>
 or simply run <tt>make test</tt>.
 

data/lib/plain_text/builtin_type.rb

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+
+module PlainText
+
+  # Contains common methods for builtin-class emulating classes
+  #
+  # The class that includes this module should have a method +instance+
+  # that returns the main instance of the builtin-class instance;
+  # e.g., +instance+ may be equivalent to +to_s+, +to_a+, and alike.
+  #
+  # @author Masa Sakano (Wise Babel Ltd)
+  #
+  module BuiltinType
+    # Subclass name only
+    #
+    # Make sure your class is a child class of {PlainText::Part},
+    # {PlainText::Part::Paragraph}, or {PlainText::Part::Boundary}.
+    # Otherwise this method would not be inherited, obviously.
+    #
+    # @example For a child class of Part
+    #   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         # => "Part::Section::Subsection"
+    #   ss.subclass_name(index_ini: 1) # => "Section::Subsection"
+    #
+    # @example For a child class of Boundary
+    #   class PlainText::Part::Boundary
+    #     class SubBoundary < self
+    #       class SubSubBoundary < self; end  # Grandchild
+    #     end
+    #   end
+    #   ss = PlainText::Part::Boundary::SubBoundary::SubSubBoundary.new ["abc"]
+    #   ss.subclass_name  # => "Part::Boundary::SubBoundary::SubSubBoundary"
+    #   ss.subclass_name(index_ini: 2)    # => "SubBoundary::SubSubBoundary"
+    #
+    # @param index_ini [Integer] Starting index after split, e.g., if 1, +"Part::"+ is removed and if 2, "Part::Boundary::" (for example) is removed.
+    # @return [String]
+    # @see PlainText::Part#subclass_name
+    def subclass_name(index_ini: 0)
+      self.class.name.split(/\A#{Regexp.quote method(__method__).owner.name.split("::")[0..-2].join("::")}::/)[1].split('::')[index_ini..-1].join('::') || ''  # removing "::BuiltinType"
+    end
+
+    # core routine for dup/clone
+    #
+    # @param copied [PlainText::Part] super-ed object
+    # @param metho [Symbol] method name
+    # @param varname [String] instance-variable name, e.g., +"@array"+
+    # @return [Object] e.g., {PlainText::Part}, {PlainText::Part::Paragraph}
+    def dup_or_clone(copied, metho, varname)
+      val = (instance.send(metho)  rescue instance)  # rescue in case of immutable (though instance (e.g., @array) should never be so and in fact it would not raise an Exception in Ruby 3 seemingly).
+      copied.instance_variable_set(varname, val)
+      # NOTE: copied.to_a.replace(val) would not work because it does not change @array.object_id
+      #   A setter like {#to_a=} or {#instance=} would work, though polimorphism would break.
+      copied 
+    end
+    private :dup_or_clone
+
+  end # BuiltinType
+end   # module PlainText
+

data/lib/plain_text/error.rb

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+
+module PlainText
+  class PartNormalizeError < StandardError
+  end
+end

data/lib/plain_text/part/boundary.rb

@@ -1,44 +1,54 @@
 # -*- coding: utf-8 -*-
 
+require_relative "../builtin_type"
+require_relative "string_type"
+
 module PlainText
-  class Part < Array
+  class Part
 
-    # Class to express a Boundary as String
+    # Class to express a Boundary, which behaves like a String
+    #
+    # This used to be a sub-class of String up to Ver.0.7.1
     #
-    class Boundary < String
+    class Boundary
+      include PlainText::BuiltinType
+      include StringType
 
-      # @return [String]
-      def inspect
-        # 'Boundary("\n\n\n")'
-        s = self.class.name
-        sprintf "%s(%s)", (s.split('::')[2..-1].join('::') rescue s), super
+      # Constructor
+      #
+      # @param str [String]
+      def initialize(str)
+        @string = str
       end
 
-      # Boundary sub-class name only
-      #
-      # Make sure your class is a child class of Boundary.
-      # Otherwise this method would not be inherited, obviously.
-      #
-      # @example
-      #   class PlainText::Part::Boundary
-      #     class SubBoundary < self
-      #       class SubBoundary < self; end  # It must be a child class!
-      #     end
-      #   end
-      #   ss = PlainText::Part::SubBoundary::SubSubBoundary.new ["abc"]
-      #   ss.subclass_name  # => "SubBoundary::SubSubBoundary"
+      # @return [Integer, NilClass]
+      def <=>(other)
+        _equal_cmp(other, __method__){ super }
+      end
+
+      # +String#==+ refers to this.
       #
-      # @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] || ''
+      # @see https://ruby-doc.org/core-3.1.2/String.html#method-i-3D-3D
+      def ==(other)
+        _equal_cmp(other, __method__){ super }
+      end
+
+      def boundary?
+        true
+      end
+
+      def paragraph?
+        false
+      end
+
+      def part?
+        false
       end
 
       # Empty Boundary instance
       Empty = self.new ""
       Empty.freeze
-    end # class Boundary < String
-  end # class Part < Array
+    end # class Boundary
+  end # class Part
 end # module PlainText
 

data/lib/plain_text/part/paragraph.rb

@@ -1,35 +1,58 @@
 # -*- coding: utf-8 -*-
 
+require_relative "../builtin_type"
+require_relative "string_type"
+
 module PlainText
-  class Part < Array
+  class Part
 
     # Class to express a Paragraph as String
     #
-    class Paragraph < String
+    class Paragraph
+      include PlainText::BuiltinType
+      include StringType
 
-      # @return [String]
-      def inspect
-        # 'Paragraph("abc\ndef")' or like 'Paragraph::Title("My Title")'
-        s = self.class.name
-        sprintf "%s(%s)", (s.split('::')[2..-1].join('::') rescue s), super
+      # Constructor
+      #
+      # @param str [String]
+      def initialize(str)
+        @string = str
       end
 
-      # Paragraph sub-class name
-      #
-      # Make sure your class is a child class of Paragraph.
-      # Otherwise this method would not be inherited, obviously.
+      ## @return [String]
+      #def to_s
+      #  @string
+      #end
+      #alias_method :to_str, :to_s
+
+      # @return [Integer, NilClass]
+      def <=>(other)
+        _equal_cmp(other, __method__){ super }
+      end
+
+      # +String#==+ refers to this.
       #
-      # @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] || ''
+      # @see https://ruby-doc.org/core-3.1.2/String.html#method-i-3D-3D
+      def ==(other)
+        _equal_cmp(other, __method__){ super }
+      end
+
+      def boundary?
+        false
+      end
+
+      def paragraph?
+        true
+      end
+
+      def part?
+        false
       end
 
       # Empty Paragraph instance
       Empty = self.new ""
       Empty.freeze
-    end # class Paragraph < String
-  end # class Part < Array
+    end # class Paragraph
+  end # class Part
 end # module PlainText
 

data/lib/plain_text/part/string_type.rb

@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*-
+
+require_relative "../builtin_type"
+
+module PlainText
+  class Part
+
+    # Contains common methods for use in the String-type classes.
+    #
+    # @author Masa Sakano (Wise Babel Ltd)
+    #
+    module StringType
+
+      # @return [String]
+      def to_s
+        @string
+      end
+      alias_method :to_str,   :to_s
+      alias_method :instance, :to_s  if ! self.method_defined?(:instance)
+
+      # Basically delegates everything to String
+      def method_missing(method_name, *args, **kwds)
+        ret = to_s.public_send(method_name, *args, **kwds)
+        ret.respond_to?(:to_str) ? self.class.new(ret) : ret
+      end
+
+      # Redefines the behaviour of +respond_to?+ (essential when defining +method_missing+)
+      def respond_to_missing?(method_name, *rest)  # include_all=false
+        to_s.respond_to?(method_name, *rest) || super
+      end
+
+      # +Para("ab\ncd")+ or +Boundary("\n\n\n")+
+      #
+      # @return [String]
+      def inspect
+        s = self.class.name
+        sprintf "%s(%s)", (s.split('::')[2..-1].join('::') rescue s), to_s.inspect
+      end
+
+      # Boundary sub-class name only
+      #
+      # Make sure your class is a child class of Boundary.
+      # Otherwise this method would not be inherited, obviously.
+      #
+      # @example
+      #   class PlainText::Part::Boundary
+      #     class SubBoundary < self
+      #       class SubSubBoundary < self; end  # Grandchild
+      #     end
+      #   end
+      #   ss = PlainText::Part::Boundary::SubBoundary::SubSubBoundary.new ["abc"]
+      #   ss.subclass_name  # => "Boundary::SubBoundary::SubSubBoundary"
+      #
+      # @return [String]
+      # @see PlainText::Part#subclass_name
+#      def subclass_name
+##printf "DEBUG: __method__=(%s)\n", __method__
+#        self.class.name.split(/\A#{Regexp.quote method(__method__).owner.name.split("::")[0..-2].join("::")}::/)[1] || ''  # removing "::StringType"
+#      end
+
+      # Work around because Object#dup does not dup the instance variable @string
+      #
+      # @return [PlainText::Part]
+      def dup
+        dup_or_clone(super, __method__, '@string') # defined in builtin_type.rb
+      end
+
+      # Work around because Object#clone does not clone the instance variable @string
+      #
+      # @return [PlainText::Part]
+      def clone
+        dup_or_clone(super, __method__, '@string') # defined in builtin_type.rb
+      end
+
+      # Core routine for comparison operators
+      #
+      # @example
+      #    _equal_cmp(other, :==){ super }
+      #    _equal_cmp(other, __method__){ super }
+      #
+      # @return [Boolean, Integer, NilClass]
+      def _equal_cmp(other, oper)
+        return yield if !other.respond_to? :to_str
+        to_s.send(oper, other.to_str)  # e.g., @string == other.to_str
+      end
+      private :_equal_cmp
+    end # module StringType
+  end   # class Part
+end     # module PlainText
+