string-builder 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47bae59709088183dfce8b8b556c1363234b8b0c57e91c50cec51a6def01675f
-  data.tar.gz: 1ffccd0dcbb9cb5dad6480e63618ba24b9c49591503271e13ad8fe4b0f0e1eb6
+  metadata.gz: eea962779b625fe78ef9c54a3806aff2550d6a9e3880387ada1fd7bdcacee075
+  data.tar.gz: c52ff6c81a88f7ac0b4f895dad393371fa66de4986526f9daa7f049206d5a532
 SHA512:
-  metadata.gz: 93b5c440450e88eab450d79c4a67cccaa1038c5d6347e5bc7ec9d9a87879d8e56573794f8849b0487b8222aa1fc08b59b9231a55fe50ab9f1c2a80a556233d09
-  data.tar.gz: 97fe5c373cf15b819a0d1fc880f2a125b4af42b524c2d919417a2471288e45b42ede0cb7dc421fffbebb0ae6bb6574717274be59a5d780ff627c92b2b03c9380
+  metadata.gz: 0d6ed807bab2e597ea88d2c46b71db92710d634b58cecf964c26664f625c4b03976798e9892ee6c345a6342a379143aa09126d53c02942b6806785fc42c79aa8
+  data.tar.gz: 66dd1494d5fa8801c49d1e861f2f26f0635936e437b916b6bacbc7dd703d20932e94f765afb8bbeb13a47db8631d6cdcc980db18c2f548e61e6f945abaa795b4

data/README.md

@@ -4,69 +4,119 @@
 
 # String::Builder
 
-Modified port of the [String::Builder IO initializer](https://crystal-lang.org/api/0.20.3/String/Builder.html#build%28capacity%3AInt%3D64%2C%26block%29%3AString-class-method) for the String class of the Crystal programming language.
+Modified and extended port of the [String::Builder](https://crystal-lang.org/api/0.20.3/String/Builder.html#build%28capacity%3AInt%3D64%2C%26block%29%3AString-class-method) IO-style initializer from the `String` class of the Crystal programming language.
 
-## Limitations of string building in Ruby and Crystal
+## Methods
 
-The [String::Builder](https://crystal-lang.org/api/0.20.3/String/Builder.html) class of the Crystal programming language provides an initializer method for the `String` class called `build` which is essentially an optimized version of Ruby's `StringIO`.
+There are three new methods in this extension of the `String` class:
 
-Ruby's `StringIO` and Crystal's `String::Builder` are great because it essentially turns strings into IO objects, allowing you to pass a block into the constructor (yielding `self`) which leads to nice chaining such as:
+### Instance methods
+
+#### `String#build`
+
+Takes a block yielding a new builder string, and appends the builder string to a duplicate of the original `String` object, `self`.
+
+##### Examples
 
 ```ruby
-# Ruby - StringIO
-test = StringIO.open do |s|
-  s << 'Hello '
-  s << 'World!'
-  s.string
+foobar = 'foo'.build do |s|
+  s << 'bop'
+  s.gsub!('op','ar')
 end
-#=> "Hello World!"
+
+foobar #=> "foobar"
 ```
 
-Note the necessary `StringIO#string` method call. Since we are yielding a `StringIO` object, we must convert it to a `String` at the end. This is a bit cleaner in Crystal:
+```ruby
+foo = 'foo'
+
+foobar = foo.build do |s|
+  s << 'bop'
+  s.gsub!('op','ar')
+end
+
+foobar #=> "foobar"
+```
+
+#### `String#build!`
+
+Takes a block yielding a new builder string, and appends the builder string to the original `String` object, `self`.
+
+**NOTE**: This mutates the original string, as indicated by the bang `!`.
+
+##### Example
 
 ```ruby
-# Crystal - String::Builder
-test = String.build do |s|
-  s << "Hello "
-  s << "World!"
+foobar = 'foo'
+
+foobar.build! do |s|
+  s << 'bop'
+  s.gsub!('op','ar')
 end
-#=> "Hello World!"
+
+foobar #=> "foobar"
 ```
 
----
+### Class methods
 
-However, since neither of these two implementations yield a `String` object, you can't use `String` methods to mutate the object:
+#### `String.build`
+
+Takes an arbitrary object and a block yielding a new string builder, and appends the builder string to a duplicate of the object parameter converted to a string (with `to_s`).
+
+If no block is given, then the object converted to a string (with `to_s`) is returned.
+
+##### Examples
 
 ```ruby
-# Ruby - StringIO
-test = StringIO.open do |s|
-  s << 'Hello '
-  s << 'World!'
-  s.upcase!
-  s.string
+foobar = String.build 'foo' do |s|
+  s << 'bop'
+  s.gsub!('op','ar')
 end
-#=> ... undefined method `upcase!' for #<StringIO:0x00007fe0bc09d810> (NoMethodError)
+
+foobar #=> "foobar"
 ```
 
 ```ruby
-# Crystal - String::Builder
-test = String.build do |s|
-  s << "Hello "
-  s << "World!"
-  s.gsub!("!", "?")
+foobar = String.build 3 do |s|
+  s << 'bop'
+  s.gsub!('op','ar')
 end
-#=> ... undefined method 'gsub!' for String::Builder
+
+foobar #=> "3bar"
 ```
 
-**That's where this gem comes in!**
+```ruby
+foo = 'foo'
+
+foobar = String.build foo do |s|
+  s << 'bop'
+  s.gsub!('op','ar')
+end
 
-## Example
+foobar #=> "foobar"
+foo #=> "foo"
+```
+
+## Detailed example
 
 This example shows how to make a simple logger by constructing log messages with `String::Builder`.
 
-> **NOTE**:
-> - You can pass an optional argument before the block, specifying what the starting string (or any object that has a working `to_s` method) should be.
-> - Since the block `yield`s a `String` object, `String::Builder` allows you to mutate the string itself as seen in this example with the `String#gsub!` method.
+Suppose we want a `Logger` class that allows us to do the following:
+
+```ruby
+logger = Logger.new
+
+logger.error 'String::Builder is good?'
+#=> [03:54:53s] (lib/string-builder.rb) ERROR » String::Builder is good!
+logger.success 'String::Builder is good?'
+#=> [03:54:55s] (lib/string-builder.rb) SUCCESS » String::Builder is good!
+logger.info 'String::Builder is good?'
+#=> [03:54:57s] (lib/string-builder.rb) INFO » String::Builder is good!
+logger.warning 'String::Builder is good?'
+#=> [03:54:59s] (lib/string-builder.rb) WARNING » String::Builder is good!
+```
+
+### Class method - `String.build`
 
 ```ruby
 require 'string/builder'
@@ -75,28 +125,37 @@ class Logger
   using String::Builder
   %i[error success info warning].each do |severity|
     define_method(severity) do |message|
-      String.build Time.now.strftime("[%H:%M:%Ss] ") do |s|
-        s << "(#{__FILE__}) "
-        s << "#{severity.to_s.upcase} » #{message}"
-        s.gsub! '?', '!'
+      time = Time.now.strftime("[%H:%M:%Ss]")
+      String.build time do |s|
+        s << " (#{__FILE__})"
+        s << " #{severity.to_s.upcase} » #{message}"
+        s.gsub!('?','!')
       end
     end
   end
 end
+```
 
-logger = Logger.new
-
-logger.error 'String::Builder is good?'
-#=> [03:54:53s] (lib/string-builder.rb) ERROR » String::Builder is good!
+### Instance method - `String#build`
 
-logger.success 'String::Builder is good?'
-#=> [03:54:55s] (lib/string-builder.rb) SUCCESS » String::Builder is good!
+The class shown above can use the `String#build` instance method to achieve the same functionality.
 
-logger.info 'String::Builder is good?'
-#=> [03:54:57s] (lib/string-builder.rb) INFO » String::Builder is good!
+```ruby
+require 'string/builder'
 
-logger.warning 'String::Builder is good?'
-#=> [03:54:59s] (lib/string-builder.rb) WARNING » String::Builder is good!
+class Logger
+  using String::Builder
+  %i[error success info warning].each do |severity|
+    define_method(severity) do |message|
+      time = Time.now.strftime("[%H:%M:%Ss]")
+      time.build do |s|
+        s << " (#{__FILE__})"
+        s << " #{severity.to_s.upcase} » #{message}"
+        s.gsub!('?','!')
+      end
+    end
+  end
+end
 ```
 
 ## Installation
@@ -117,26 +176,78 @@ Or install it yourself as:
 
 ## Usage
 
-This monkey-patch is in the form of a `refinement`. This means that you will have to call the following `using` directive within the scope that you want the `String.build` class method to be monkey-patched into the `String` class:
+This extension is in the form of a `refinement`. This means that you will have to call the following `using` directive within the scope that you want the `String` class to be extended with `String::Builder` methods:
 
 ```ruby
 require 'string/builder'
 using String::Builder
 ```
 
-Though you should typically avoid doing this in the global scope (unless you really need to), and instead only use the monkey-patch where you need it - inside your specific modules or classes:
+Though you should typically avoid doing this in the global scope (unless you really need to), and instead only use the extension where you need it - inside your specific modules or classes:
 
 ```ruby
 require 'string/builder'
 
 class A
   using String::Builder
-  # CAN use String.build in this class
+  # CAN use String::Builder methods in this class
 end
 
 module B
-  # CANNOT use String.build in this module
+  # CANNOT use String::Builder methods in this module
+end
+
+# CANNOT use String::Builder methods in the global scope
+```
+
+## Limitations of string building in Ruby and Crystal
+
+The [String::Builder](https://crystal-lang.org/api/0.20.3/String/Builder.html) class of the Crystal programming language provides an initializer method for the `String` class called `build` which is essentially an optimized version of Ruby's `StringIO`.
+
+Ruby's `StringIO` and Crystal's `String::Builder` are great because it essentially turns strings into IO objects, allowing you to pass a block into the constructor (yielding `self`) which leads to nice chaining such as:
+
+```ruby
+# Ruby - StringIO
+test = StringIO.open do |s|
+  s << 'Hello '
+  s << 'World!'
+  s.string
 end
+#=> "Hello World!"
+```
+
+Note the necessary `StringIO#string` method call. Since we are yielding a `StringIO` object, we must convert it to a `String` at the end. This is a bit cleaner in Crystal:
+
+```ruby
+# Crystal - String::Builder
+test = String.build do |s|
+  s << "Hello "
+  s << "World!"
+end
+#=> "Hello World!"
+```
 
-# CANNOT use String.build in the global scope
+---
+
+However, since **neither** of these two implementations yield a `String` object, you can't use `String` methods to mutate the object:
+
+```ruby
+# Ruby - StringIO
+test = StringIO.open do |s|
+  s << 'Hello '
+  s << 'World!'
+  s.upcase!
+  s.string
+end
+#=> ... undefined method `upcase!' for #<StringIO:0x00007fe0bc09d810> (NoMethodError)
+```
+
+```ruby
+# Crystal - String::Builder
+test = String.build do |s|
+  s << "Hello "
+  s << "World!"
+  s.gsub!("!", "?")
+end
+#=> ... undefined method 'gsub!' for String::Builder
 ```

data/Rakefile

@@ -1,6 +1,6 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
 task :default => :spec
+
+desc "Runs specs"
+task :spec do
+    sh "rspec -fd spec"
+end

data/lib/string/builder.rb

@@ -1,12 +1,32 @@
 module String::Builder
   refine String.singleton_class do
+
     def build(obj = String.new)
       return obj.to_s unless block_given?
       yield builder = self.new
       obj.dup.to_s << builder
     end
-    def respond_to?(symbol, include_all = false)
-      self.methods(false).dup.<<(:build).include?(symbol)
+
+    def respond_to?(id, private = false)
+      id.to_sym == :build ? true : super
     end
+
+  end
+  refine String do
+
+    def build
+      yield builder = String.new
+      self.dup << builder
+    end
+
+    def build!
+      yield builder = String.new
+      self << builder
+    end
+
+    def respond_to?(id, private = false)
+      %i[build build!].include?(id.to_sym) ? true : super
+    end
+
   end
 end

data/string-builder.gemspec

@@ -3,11 +3,11 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "string-builder"
-  spec.version       = "2.0.2"
+  spec.version       = "2.1.0"
   spec.authors       = ["Edwin Onuonga"]
   spec.email         = ["edwinonuonga@gmail.com"]
 
-  spec.summary       = %q{Modified port of the String::Builder IO initializer for the String class of the Crystal programming language.}
+  spec.summary       = %q{Modified and extended port of the String::Builder IO-style initializer from the String class of the Crystal programming language.}
   spec.homepage      = "https://www.github.com/eonu/string-builder"
   spec.license       = "MIT"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: string-builder
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.1.0
 platform: ruby
 authors:
 - Edwin Onuonga
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-05 00:00:00.000000000 Z
+date: 2018-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -93,6 +93,6 @@ rubyforge_project:
 rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
-summary: Modified port of the String::Builder IO initializer for the String class
-  of the Crystal programming language.
+summary: Modified and extended port of the String::Builder IO-style initializer from
+  the String class of the Crystal programming language.
 test_files: []