slim_string 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7809507e7ec9cd436f92b3a3f90150994eec48c70925fe1a971e97a53867d32b
-  data.tar.gz: d74f135e5475123d3d4c60b0e35dbd641fe109cdcb7f5ee2cbaaabcb6b76b178
+  metadata.gz: '043184def22a05113e776e328a7472c6e1a1c352013a0b619c7b2ce6649a5f41'
+  data.tar.gz: 562fbd66e5a1b8564072d3766b478daacaa1cd1718a2b58ab91145d37a2848e9
 SHA512:
-  metadata.gz: 38b24b2d3841629ec0f1c3d24bd7a18a05f7b00b44d69501ea1fbb1b6c410b2d6f615c966132e31224ba39c953696ed71ca7781dc889f3cc4429be6923ad6501
-  data.tar.gz: 44b0d9508421a804730a59a32e31bf6b2631b51d3f34ccda833a6966f1299f395d3e267ba7a1e780e3a5f60127a9630b0b38268959f9b8f3442c113eda91f0ef
+  metadata.gz: abf6a3ed2ca31405010ec087aa6260badd4f3f1bf4f5bca55a872c575c88bf01985eeff346b2ad785387a00b62688386fb9e2f878a41959e20863b9ded149186
+  data.tar.gz: 92237ddcf40baf8df313cb61fd003cced17a58ef59b14c18ee130a7c180681308037082da7a1ba7f60b0ab889cf7f79f61d386a52efd1fb97b76ee8b36dbb9aa

data/ChangeLog

@@ -1,3 +1,8 @@
+-----
+(Version: v.1.0.2)
+2021-07-04  Masa Sakano
+  * Improved document.
+
 -----
 (Version: v.1.0.1)
 2021-07-04  Masa Sakano

data/README.en.rdoc

@@ -5,56 +5,115 @@
 
 Module {SlimString} contains a single method of the same (but
 snake-case) name +SlimString#slim_string+, which offers functionality
-to "slim down" character String, such as truncating extra spaces with many
-options you can select.
-It fully takes into account *UTF-8 characters* like CJK Zenkaku spaces.
+to "slim down" character String, such as truncating extra spaces, with many
+options you can specify.
+It fully takes into account *UTF8 characters* like CJK Zenkaku spaces
+(U+3000).
 
-The full package of this class is found in
+The full package of this module is found in
 {SlimString Ruby Gems page}[http://rubygems.org/gems/slim_string]
 (with document created from source annotation with yard) and
 in {Github}[https://github.com/masasakano/slim_string]
 
 == Description
 
-=== How to use it?
+The main (and only) method +slim_string+ accepts a String (either as the receiver or first
+argument) and returns a slimmed-down String.
 
-1. Simply call it in a full path (it is extended and so you can call it in this way.
+In default, the returned String is processed as:
 
-  SlimString.slim_string("\nabc\n\n", strip: false) # => "\nabc"
-2. Include in your class/module (or top level), and you can use it without the module name.
+1. all the "weird" spaces like TAB characters are converted into ASCII white spaces (U+0020),
+2. all the consecutive white spaces but new-line characters are truncated into a single white space,
+3. all the consecutive white spaces and new-line characters at the beginning and tail are stripped.
 
-  include SlimString
-  slim_string("\nabc\n\n", strip: false) # => "\nabc"
-3. Include it in +String+ class like and you can use it as an instance method.
+You can specify more *aggressive* or *tamer* processing, specifying
+suitable options (see below).
 
-  class String
-    include SlimString
-  end
+=== How to use it?
 
-  "\nabc\n\n".slim_string(trim: false) # => "\nabc"
+First,
+  require 'slim_string'
 
-=== Options
+Then,
+
+1. Simply call it in a full path (it is extended and so you can call it in this way.
+     SlimString.slim_string("\nabc\n\n", strip: false)
+       # => "\nabc"
+2. "include" it in your class/module (or top level), and you can use it without the module name.
+     include SlimString
+     slim_string("\nabc\n\n", strip: false)
+       # => "\nabc"
+3. "include" it in +String+ class like and you can use it as an instance method.
+     class String
+       include SlimString
+     end
+   
+     "\nabc\n\n".slim_string(strip: false)
+       # => "\nabc"
+
+=== Class constant
+
++DEF_SLIM_OPTIONS+:: Hash containing the default option values. The processing order in +slim_string+ follows that of the keys of this constant.
+
+=== Options (keyword options)
 
 All options (aka, arguments) are Boolean.
 The given string is processed in this order regardless how you do or
 do not specify them.
 
-+delete_newlines+:: (Def: false) Delete all new lines (\f\n\r\v) (maybe useful for Japanese text, unless more than 1 alphabet word are split across 2 lines).
+Here, the terms *space* and *blank* follows the Ruby Regexp convention,
+i.e., *spaces* are non-visible characters including newlines,
+whereas *blanks* are *spaces* minus new-line characters (\\f\\n\\r\\v; ASCII Formfeed (FF), Linefeed (LF), Carriage Return (CR), Vertical Tab (VT)).
+
++delete_newlines+:: (Def: false) Delete all new lines (\\f\\n\\r\\v) (maybe useful for Japanese text, unless more than 1 alphabet word are split across 2 lines).
 +convert_spaces+:: (Def: false) Convert any sort of spaces (including new lines) into an ASCII space.
 +convert_blanks+:: (Def: true) Convert all blanks (=spaces except kind of new lines) into an ASCII space.
 +truncate_spaces+:: (Def: false) Truncate any consecutive spaces into one.
 +truncate_blanks+:: (Def: true) Truncate any consecutive blanks into (the last) one.
 +truncate_triple_newlines+:: (Def: false) Truncate 3 or more consecutive newlines into 2.
-+delete_blanks+:: (Def: false) Simply delete all blanks excluding new lines (n.b., "a top" and "atop" are regarded identical.
++delete_blanks+:: (Def: false) Simply delete all blanks excluding new lines (n.b., "a top" and "atop" are regarded identical).
 +strip+:: (Def: true) Ruby strip; strip spaces including new lines at the head and tail.
 +trim_blanks+:: (Def: false) strip blanks (but new lines) at the tail.
 +trim+:: (Def: true) Trim the tail to strip any spaces including new lines at the tail.
 
+== Examples
+
+Suppose you include +SlimString+ (see "How to use it?" above for
+detail).
+
+In default (see the beginning of Description):
+
+    s  = "\nab  cd\n ef \t gh \n\n"
+    slim_string(s)
+      # => "ab cd\n ef gh"
+
+To preserve consecutive white spaces, but otherwise as in the default, do:
+
+    slim_string(s, truncate_blanks: false)
+      # => "ab  cd\n ef   gh"
+
+To convert all the newlines into white spaces, but otherwise as in the default, do:
+
+    slim_string(s, convert_spaces: true)
+      # => "ab cd ef gh"
+
+To cancel all the default options and specify your own (n.b., here, Hash#map
+is available in Ruby 2.1 (released in 2013) and above), do as follows, for example. In this
+case, it is identical to Ruby's +String#strip+
+
+    s = " \tA  B \n"
+    to_cancel = DEF_SLIM_OPTIONS.map{|k,v| [k, false]}.to_h
+    slim_string(s, **(to_cancel.merge({strip: true})))
+      # => "A  B"  (== s.strip)
+ 
+where +DEF_SLIM_OPTIONS+ is a class constant +SlimString::DEF_SLIM_OPTIONS+ 
+
+The test suite under +test/+ directory contains many more examples.
+
 == Install
 
-This script requires {Ruby}[http://www.ruby-lang.org] Version 2.0
-or above.  Also, all this library depends on {SubObject (sub_object)}[https://rubygems.org/gems/sub_object], which you can
-find in RubyGems.
+This library requires {Ruby}[http://www.ruby-lang.org] Version 2.0
+or above.
 
 == Developer's note
 
@@ -79,3 +138,5 @@ Author::  Masa Sakano < info a_t wisebabel dot com >
 Versions:: The versions of this package follow Semantic Versioning (2.0.0) http://semver.org/
 License:: MIT
 
+----------
+

data/lib/slim_string.rb

@@ -65,11 +65,8 @@ module SlimString
   #    String class and use it as an instance method, the first
   #    argument is mandatory.
   def slim_string(str=nil, **opts)
-    begin
-      ret = (str || self).dup
-    rescue NoMethodError
-      raise ArgumentError, 'first argument is mandatory and must be String-like.'
-    end
+    ret = (str || self).dup
+    raise ArgumentError, 'first argument is mandatory and must be String-like.' if !ret.respond_to? :gsub!
 
     DEF_SLIM_OPTIONS.merge(opts).each_pair do |ek, tf|
       next if !tf

data/slim_string.gemspec

@@ -5,7 +5,7 @@ require 'date'
 
 Gem::Specification.new do |s|
   s.name = 'slim_string'.sub(/.*/){|c| (c == File.basename(Dir.pwd)) ? c : raise("ERROR: s.name=(#{c}) in gemspec seems wrong!")}
-  s.version = "1.0.1".sub(/.*/){|c| fs = Dir.glob('changelog{,.*}', File::FNM_CASEFOLD); raise('More than one ChangeLog exist!') if fs.size > 1; warn("WARNING: Version(s.version=#{c}) already exists in #{fs[0]} - ok?") if fs.size == 1 && !IO.readlines(fs[0]).grep(/^\(Version: #{Regexp.quote c}\)$/).empty? ; c }  # n.b., In macOS, changelog and ChangeLog are identical in default.
+  s.version = "1.0.2".sub(/.*/){|c| fs = Dir.glob('changelog{,.*}', File::FNM_CASEFOLD); raise('More than one ChangeLog exist!') if fs.size > 1; warn("WARNING: Version(s.version=#{c}) already exists in #{fs[0]} - ok?") if fs.size == 1 && !IO.readlines(fs[0]).grep(/^\(Version: #{Regexp.quote c}\)$/).empty? ; c }  # n.b., In macOS, changelog and ChangeLog are identical in default.
   # s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   # s.bindir = 'bin'
   # %w(slim_string).each do |f|

data/test/test_slim_string.rb

@@ -69,10 +69,31 @@ class TestSlimStringClass < MiniTest::Test
     ex = "   a\nb\f\vc\r\n "+z*3+"d \r\n\r\n"
     assert_equal ex, slim_string(s,                        convert_blanks: false, truncate_blanks: false, strip: false, trim_blanks: true, trim: false)
 
+    assert_equal s,  slim_string(s, **(DEF_SLIM_OPTIONS.map{|k,v| [k, false]}).to_h)
+    assert_equal s.strip, slim_string(s, **(DEF_SLIM_OPTIONS.map{|k,v| [k, false]}).to_h.merge({strip: true}))
+
     assert_raises(ArgumentError){ slim_string(s, dummy: true) }
 
     assert_equal "a\nb\f\vc\r\n d", s.slim_string()
     assert_equal "a\nb\f\vc\r\n d", SlimString.slim_string(s)
+    assert_raises(ArgumentError){   SlimString.slim_string() }
+  end
+
+  def test_slim_string_in_doc
+    s = " \tA  B \n"
+    assert_equal s.strip, slim_string(s, **(DEF_SLIM_OPTIONS.map{|k,v| [k, false]}).to_h.merge({strip: true}))
+    assert_equal "A  B",  slim_string(s, **(DEF_SLIM_OPTIONS.map{|k,v| [k, false]}).to_h.merge({strip: true}))
+
+    to_cancel = DEF_SLIM_OPTIONS.map{|k,v| [k, false]}.to_h
+    assert_equal s.strip, slim_string(s, **(to_cancel.merge({strip: true})))
+
+    s  = "\nab  cd\n ef \t gh \n\n"
+    ex =   "ab cd\n ef gh"
+    assert_equal ex, slim_string(s)
+    ex =   "ab cd ef gh"
+    assert_equal ex, slim_string(s, convert_spaces: true)
+    ex =   "ab  cd\n ef   gh"
+    assert_equal ex, slim_string(s, truncate_blanks: false)
   end
 end # class TestUnitSlimString < MiniTest::Test
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slim_string
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Masa Sakano