lazy_string 0.4.0 → 0.7.0

data/LICENSE.txt

@@ -1,20 +1,19 @@
-Copyright (c) 2022 Aaron Beckerman
+Copyright (c) 2024 Aaron Beckerman
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included
-in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.txt

@@ -1,43 +1,28 @@
 LazyString
 
 LazyString is a Ruby class for computing strings only when necessary. This is
-useful when computing the string is expensive but the string is unlikely to be
-used: an error message passed as an argument, for example.
+useful when computing the string is expensive but the string might never be
+used.
 
-Thanks to duck typing and Ruby's standard conversion protocols, you can pass
-an instance of LazyString to many methods that ask for a string.
+Thanks to Ruby's duck typing and conversion protocols, you can often use an
+instance of LazyString where you previously used an instance of String.
 
 
 Usage
 
-LazyString is packaged as a RubyGem. Once you've installed it and required the
-file, you can create a lazy string by passing a block to LazyString.new:
+LazyString is packaged as a gem. Once you've installed it and loaded the file,
+you can create a lazy string by sending new to LazyString with a block. The
+block should return an object that converts to a string:
 
   ls = LazyString.new { "answer = #{expensive_computation}" }
 
-The block (and therefore expensive_computation) will not be called immediately.
-But later, if #to_str or #to_s is sent to the lazy string, the block will be
-called with no arguments in order to create the real string.
+The block (and therefore expensive_computation) will not be run immediately.
+But later, if to_str or to_s is sent to the lazy string, the saved proc
+representing your block will be called with no arguments and the returned
+object converted to create the real string.
 
-  # String interpolation calls #to_s automatically.
+  # String interpolation sends to_s.
   s = "Lazy string computes this: #{ls}"
 
-Once the string is computed, it will be saved, so any future invocations of
-#to_str or #to_s will not perform the computation again.
-
-
-Compatibility
-
-This works on version 1.8.7 and later of Matz's Ruby Interpreter. (At the time
-of this writing, 2.2.3 is the current version.)
-
-
-Author
-
-This software was written by Aaron Beckerman.
-
-
-License
-
-This software is distributed under the MIT License (also known as the Expat
-License). See the LICENSE.txt file for details.
+Once the string is computed, it will be saved, so sending to_str or to_s again
+will not cause the computation to be performed again.

data/lazy_string.gemspec

@@ -1,19 +1,14 @@
-# -*- encoding: utf-8 -*-
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "lazy_string"
-
-Gem::Specification.new do |gem|
-  gem.name = 'lazy_string'
-  gem.version = LazyString::VERSION
-  gem.authors = ['Aaron Beckerman']
-  gem.description = %q{This library provides LazyString, a class for computing strings only when necessary. This is useful when computing the string is expensive but the string is unlikely to be used: an error message passed as an argument, for example.}
-  gem.summary = %q{A Ruby library for lazily computing strings.}
-  gem.license = 'MIT'
-  gem.required_ruby_version = '>= 1.8.7'
-
-  gem.files = %w{LICENSE.txt README.txt lazy_string.gemspec lib/lazy_string.rb test/lazy_string_test.rb}
-  gem.executables = %w{}
-  gem.test_files = %w{test/lazy_string_test.rb}
-  gem.require_paths = %w{lib}
+Gem::Specification.new do |s|
+  s.name = "lazy_string"
+  s.version = "0.7.0"
+  s.authors = ["Aaron Beckerman"]
+  s.summary = "A class for computing strings only when necessary."
+  s.description = "This library provides LazyString, a class for computing" \
+    " strings only when necessary. This is useful when computing the string" \
+    " is expensive but the string might never be used."
+  s.licenses = ["MIT"]
+  s.files = ["LICENSE.txt", "README.txt", "lazy_string.gemspec",
+    "lib/lazy_string.rb", "test/lazy_string_test.rb"]
+  s.test_files = ["test/lazy_string_test.rb"]
+  s.required_ruby_version = ">= 1.8.7"
 end

data/lib/lazy_string.rb

@@ -1,46 +1,46 @@
 ##
-# LazyString is a class for computing strings only when necessary. This is
-# useful when computing the string is expensive but the string is unlikely to
-# be used: an error message passed as an argument, for example.
-#
+# A class for computing strings only when necessary.
+
 class LazyString
-  ##
-  # The version string.
-  #
-  VERSION = '0.4.0'
 
   ##
-  # Creates a new lazy string. The block argument will be saved for later use
-  # by #to_str. If no block argument is given, it will default to a block that
-  # returns an empty string.
-  #
-  def initialize(&block)
-    @block = block || lambda { '' }
+  # Creates a new lazy string. It saves the block as a proc for later use by
+  # #to_str. If no block is given, it saves a proc that returns an empty
+  # string.
+
+  def initialize &prc
+    @prc = prc || ::Proc.new { "" }
+    nil
   end
 
   ##
-  # A synonym for #to_str.
-  #
+  # Computes the string if necessary and returns it. It delegates to #to_str.
+
   def to_s
     to_str
   end
 
   ##
-  # Returns the computed string. It will compute the string by calling (with no
-  # arguments) the block passed to ::new. If the block's return value responds
-  # to the \to_str message, \to_str will be sent to it to create the string.
-  # Otherwise, \to_s will be sent to it. The computed string will be saved,
-  # so subsequent invocations of this method will not cause the block to be
-  # called again.
-  #
+  # Computes the string if necessary and returns it. It computes the string by
+  # calling, with no arguments, the saved proc representing the block passed to
+  # ::new. If an object is returned, this method converts it to a string and
+  # returns the result. It converts the object to a string by sending \to_str
+  # to the object if it responds to that message and \to_s otherwise. It saves
+  # the computed string, so subsequent invocations of this method will not
+  # recompute the string. If an exception is raised, this method immediately
+  # raises that exception and does not save any result.
+
   def to_str
-    @str ||= begin
-      result = @block.call
-      if result.respond_to?(:to_str)
+    if defined? @str
+      @str
+    else
+      result = @prc.call
+      @str = if result.respond_to? :to_str
         result.to_str
       else
         result.to_s
       end
     end
   end
+
 end

data/test/lazy_string_test.rb

@@ -1,55 +1,162 @@
-require 'lazy_string'
+# Sections that create local variables are in class definitions so that later
+# sections cannot accidentally reference those local variables.
 
-Class == LazyString.class or fail
+require "lazy_string"
 
-String == LazyString::VERSION.class or fail
+# LazyString should be a class.
+fail "" unless Class.equal? LazyString.class
 
-lambda do
-  obj = Object.new
-  LazyString.new { obj.freeze }
-  !obj.frozen? or fail
-end.call
+# LazyString.new should return an instance of LazyString.
+fail "" unless LazyString.equal? LazyString.new.class
 
-LazyString.new.respond_to?(:to_str) or fail
+# LazyString.new should raise an exception if any non-block arguments are sent.
+begin
+  LazyString.new nil
+rescue ArgumentError
+else
+  fail ""
+end
+begin
+  LazyString.new(nil) {}
+rescue ArgumentError
+else
+  fail ""
+end
 
-LazyString.new.respond_to?(:to_s) or fail
+# The block should not be called when creating a lazy string.
+class ::Object
+  calls = 0
+  LazyString.new { calls += 1 }
+  fail "" unless 0 == calls
+end
 
-'' == LazyString.new.to_str or fail
+# An instance of LazyString should say it responds to to_str and to_s.
+fail "" unless LazyString.new.respond_to? :to_str
+fail "" unless LazyString.new.respond_to? :to_s
 
-lambda do
-  obj = Object.new
-  def obj.to_str; 'to_str' end
-  def obj.to_s; 'to_s' end
-  'to_str' == LazyString.new { obj }.to_str or fail
-end.call
+# LazyString#to_s should delegate to #to_str.
+class ::Object
+  ls = LazyString.new
+  ls.instance_variable_set :@_test_to_str, test_to_str = Object.new
+  def ls.to_str
+    @_test_to_str
+  end
+  fail "" unless test_to_str.equal? ls.to_s
+end
 
-lambda do
-  obj = Object.new
-  def obj.to_s; 'to_s' end
-  !obj.respond_to?(:to_str) or fail
-  'to_s' == LazyString.new { obj }.to_str or fail
-end.call
+# LazyString#to_str should return an empty string if the lazy string was made
+# without a block.
+fail "" unless "" == LazyString.new.to_str
 
-'42' == LazyString.new { 2 * 21 }.to_s or fail
+# LazyString#to_str should convert the object returned by the saved proc to a
+# string and return the result. If the object responds to to_str, the
+# conversion should be done by sending that message.
+class ::Object
+  block_result = Object.new
+  block_result.instance_variable_set :@_test_to_str, test_to_str = Object.new
+  def block_result.to_str
+    @_test_to_str
+  end
+  def block_result.to_s
+    "to_s"
+  end
+  fail "" unless test_to_str.equal? LazyString.new { block_result }.to_str
+end
 
-lambda do
-  arr = []
-  ls = LazyString.new { arr << nil; 'foo' }
-  ls.to_str
-  'foo' == ls.to_str or fail
-  1 == arr.length or fail
-end.call
+# LazyString#to_str should convert the object returned by the saved proc to a
+# string and return the result. If the object does not respond to to_str, the
+# conversion should be done by sending to_s.
+class ::Object
+  block_result = Object.new
+  block_result.instance_variable_set :@_test_to_s, test_to_s = Object.new
+  def block_result.to_s
+    @_test_to_s
+  end
+  fail "" unless test_to_s.equal? LazyString.new { block_result }.to_str
+end
 
-lambda do
-  ex = StandardError.new
-  ls = LazyString.new { raise(ex) }
+# After LazyString#to_str calls the saved proc as part of a successful string
+# conversion, it should not call it again in subsequent invocations but return
+# the same object.
+class ::Object
+  calls = 0
+  ls = LazyString.new do
+    calls += 1
+    "string"
+  end
+  fail "" unless ls.to_str.equal? ls.to_str
+  fail "" unless 1 == calls
+end
+
+# LazyString#to_str should convert the object returned by the saved proc to a
+# string and save the result. If that was successful, it should not convert the
+# object again in subsequent invocations but return the same object.
+class ::Object
+  block_result = Object.new
+  block_result.instance_variable_set :@_test_calls, 0
+  def block_result.to_s
+    @_test_calls += 1
+    "string"
+  end
+  ls = LazyString.new { block_result }
+  fail "" unless ls.to_str.equal? ls.to_str
+  fail "" unless 1 == block_result.instance_variable_get(:@_test_calls)
+end
+
+# LazyString#to_str should not save any result if converting to a string raised
+# an exception.
+class ::Object
+  block_result = Object.new
+  def block_result.to_s
+    raise RuntimeError
+  end
+  calls = 0
+  ls = LazyString.new do
+    calls += 1
+    block_result
+  end
+  ls.to_str rescue nil
+  ls.to_str rescue nil
+  fail "" unless 2 == calls
+end
+
+# LazyString#to_str and #to_s should propagate exceptions.
+class ::Object
+  e = StandardError.new
+  ls = LazyString.new { ::Kernel.raise e }
   begin
     ls.to_str
   rescue
-    ex.equal?($!) or fail
+    fail "" unless e.equal? $!
+  else
+    fail ""
+  end
+  begin
+    ls.to_s
+  rescue
+    fail "" unless e.equal? $!
   else
-    fail
+    fail ""
   end
-end.call
+end
+
+# LazyString#to_str should raise an exception if any non-block arguments are
+# sent.
+begin
+  LazyString.new.to_str nil
+rescue ArgumentError
+else
+  fail ""
+end
+
+# LazyString#to_s should raise an exception if any non-block arguments are
+# sent.
+begin
+  LazyString.new.to_s nil
+rescue ArgumentError
+else
+  fail ""
+end
 
-puts 'Test finished.'
+# If this message doesn't get written, there was a problem.
+puts "Test finished: #{__FILE__}"

metadata

@@ -1,50 +1,73 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: lazy_string
-version: !ruby/object:Gem::Version
-  version: 0.4.0
+version: !ruby/object:Gem::Version 
+  hash: 3
+  prerelease: 
+  segments: 
+  - 0
+  - 7
+  - 0
+  version: 0.7.0
 platform: ruby
-authors:
+authors: 
 - Aaron Beckerman
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-11-13 00:00:00.000000000 Z
+
+date: 2024-03-11 00:00:00 -07:00
+default_executable: 
 dependencies: []
-description: 'This library provides LazyString, a class for computing strings only
-  when necessary. This is useful when computing the string is expensive but the string
-  is unlikely to be used: an error message passed as an argument, for example.'
-email:
+
+description: This library provides LazyString, a class for computing strings only when necessary. This is useful when computing the string is expensive but the string might never be used.
+email: 
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - LICENSE.txt
 - README.txt
 - lazy_string.gemspec
 - lib/lazy_string.rb
 - test/lazy_string_test.rb
-homepage:
-licenses:
+has_rdoc: true
+homepage: 
+licenses: 
 - MIT
-metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
-  requirements:
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
   - - ">="
-    - !ruby/object:Gem::Version
+    - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
       version: 1.8.7
-required_rubygems_version: !ruby/object:Gem::Requirement
-  requirements:
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
   - - ">="
-    - !ruby/object:Gem::Version
-      version: '0'
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
-specification_version: 4
-summary: A Ruby library for lazily computing strings.
-test_files:
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: A class for computing strings only when necessary.
+test_files: 
 - test/lazy_string_test.rb

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA256:
-  metadata.gz: b95d72633b9419e5306c154c7adda01b3ea723d39d4bf3ee58b41111371bc128
-  data.tar.gz: 2fde23cece3bb04dec3570ab777fd8cf6528024dc1ead33ac2d6dae9d8fde974
-SHA512:
-  metadata.gz: 5ea1f4d2c963a844fe677fdf59bf866b8ce33a323997357f243301640f79fb73dc15f45e7ff456db8274120de018a96d7aa36a5d782186299855ba9123e60699
-  data.tar.gz: 375eb324a2af06e24b661eabce5e674420eb476f33a8165b457123dacb86fbf67148a391d8f24f4839e480b517f8d4be11899e8944283c570fc71e3e8da0de6d