safe_clone 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6c47b359f673a690029ee7dc0388eb6bf1875d09
-  data.tar.gz: 34af503afe09f42a3278709c1a5c4f5f801dc06f
+  metadata.gz: 337deb97efeb6f36888f928f0ceb4a6aff7e1807
+  data.tar.gz: 85c5a520fcaaf4936282eb40227c46c38990b1ab
 SHA512:
-  metadata.gz: df8e974b0fa65e8da617f672616d816958c1253922e9c2e1a340b3de232de42156962cb4b249885dcd0b7b421106b51fef2fd3b6e37cf2cd31cbc576412cee2d
-  data.tar.gz: c46c03f29d95f418a2e19bbd609600e7c691e3a3b5cc587a02c2c6d326a8d11d2d0f94f8f63c12c0099b608a0339687d88b8d60277396231c1cab5bb8ed7bc0f
+  metadata.gz: bfdfc38c09b4881333910b339fdface8878c357926c4e586a3f010bf0ac3b19619fd126254ac1aeec194ee297d91a688f8ff8b19452995ce29e3bc43baf09cc4
+  data.tar.gz: 94bc68f5b3f362cce6dc1050f5871ee18c5a33282691f31df09c177ed068e30818ed7a3911e22daa727d2ca21d89d2f1da044a3cd5acc5c28ec7dbd8b76e78d5

data/README.md

@@ -1,10 +1,45 @@
 # SafeClone
 
-This tiny gem implements a version of clone called safe\_clone. Unlike the
-standard clone method, the safe\_clone method does not throw an exception
-when sent to un-clonable value objects like 42 or true. These values simply
-return themselves. This is correct because those types of objects do not _need_
-to be cloned. Instead of having a fit, the code just works!
+This tiny gem implements a version of clone called safe\_clone. In Ruby, if an
+attempt is made to clone an immutable data item like a number, an error occurs.
+The justification for this uncharacteristic strictness is not at all clear, but
+it does mean that the clone operation must be applied with great care.
+
+Unlike the standard clone method, the safe\_clone method does not throw an
+exception when sent to un-clonable value objects like 42 or true. These values
+simply return themselves. This is correct because those types of objects do
+not _need_ to be cloned. Instead of having a fit, the code just works!
+
+On a note about performance, this gem does not just rescue the exceptions
+normally generated by clone, it prevents them from occurring and wasting time
+in the first place.
+
+Finally, this gem does not monkey patch the behavior of the clone method.
+Modifying such a crucial method was considered too risky. Instead, the
+safe_clone method is introduced. This is done to reduce the possibility of
+breaking existing code that often occurs when monkey patching goes too far.
+
+## Family Overview
+
+This gem is a member of a family of four gems that all provide data copying
+services in a safe, easy to use format. The following outlines the available
+gems and how to chose from among them.
+
+Depth / Action | Need to copy all. | Need to copy data only.
+---------------|------------------------------|------------
+Need a shallow copy | require 'safe\_clone' | require 'safe\_dup'
+Need a full copy    | require 'full\_clone' | require 'full\_dup'
+
+<br>**Notes**
+* Since none of these gems override the default clone and dup
+methods, the default behaviors remain available. Further, if multiple,
+differing requirements exists, more than one family member gem may be
+employed in the same project without fear of conflict.
+* If multiple family gems are employed, they will each need to be installed and
+required into the application. See below for details.
+* Meta-data attributes include the frozen status and singleton methods. However
+the tainted status is always copied.
+
 
 ## Installation
 
@@ -20,6 +55,11 @@ Or install it yourself as:
 
     $ gem install safe_clone
 
+The safe_dup gem is at: ( https://rubygems.org/gems/safe_dup )
+<br>The safe_clone gem is at: ( https://rubygems.org/gems/safe_clone )
+<br>The full_dup gem is at: ( https://rubygems.org/gems/full_dup )
+<br>The full_clone gem is at: ( https://rubygems.org/gems/full_clone )
+
 ## Usage
 
     require 'safe_clone'
@@ -36,6 +76,15 @@ instead of
       foo = my_object
     end
 
+It is actually pretty easy to determine where safe\_clone needs to be used. It's
+those places where the clone method is generating unwanted exceptions.
+
+## Demo
+
+A test bed for experimenting with the safe_clone gem is available as a rake task:
+
+    $ rake console
+
 ## Performance
 A reasonable question to raise is "How does safe clone compare with just
 catching the exception and handling it?" The benchmark sets a a realistic
@@ -71,12 +120,7 @@ Benchmark.ips do |x|
 end
 ```
 
-Ruby Version:
-
-    ruby 1.9.3p484 (2013-11-22) [i386-mingw32]
-
-Results:
-
+#### Results: ruby 1.9.3p484 (2013-11-22) [i386-mingw32]
     C:\Sites\safe_clone>ruby bench\bench.rb
     Warming up --------------------------------------
     Clone with standard clone method
@@ -93,12 +137,7 @@ Results:
     Clone with the safe clone method:   534740.1 i/s
     Clone with standard clone method:    12956.6 i/s - 41.27x slower
 
-Ruby Version:
-
-    ruby 2.1.6p336 (2015-04-13 revision 50298) [i386-mingw32]
-
-Results:
-
+#### Results: ruby 2.1.6p336 (2015-04-13 revision 50298) [i386-mingw32]
     C:\Sites\safe_clone>ruby bench\bench.rb
     Warming up --------------------------------------
     Clone with standard clone method
@@ -115,12 +154,7 @@ Results:
     Clone with the safe clone method:   569236.4 i/s
     Clone with standard clone method:    54491.3 i/s - 10.45x slower
 
-Ruby Version:
-
-    ruby 2.2.3p173 (2015-08-18 revision 51636) [i386-cygwin]
-
-Results:
-
+#### Results: ruby 2.2.3p173 (2015-08-18 revision 51636) [i386-cygwin]
     Peter Camilleri@NCC1701G /cygdrive/c/sites/safe_clone
     $ ruby bench/bench.rb
     Warming up --------------------------------------
@@ -143,8 +177,16 @@ Overall: Shorter code  _and_ faster. Winner, winner, chicken dinner!
 
 ## Contributing
 
-1. Fork it
+#### Plan A
+
+1. Fork it ( https://github.com/PeterCamilleri/safe_clone/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+5. Create a new Pull Request
+
+#### Plan B
+
+Go to the GitHub repository and raise an issue calling attention to some
+aspect that could use some TLC or a suggestion or an idea.
+

data/irbt.rb

@@ -0,0 +1,20 @@
+# coding: utf-8
+# An IRB + safe_clone test bed
+
+require 'irb'
+$force_alias_read_line_module = true
+require 'mini_readline'
+
+puts "Starting an IRB console with safe_clone loaded."
+
+if ARGV[0] == 'local'
+  require_relative 'lib/safe_clone'
+  puts "safe_clone loaded locally: #{SafeClone::VERSION}"
+
+  ARGV.shift
+else
+  require 'safe_clone'
+  puts "safe_clone loaded from gem: #{SafeClone::VERSION}"
+end
+
+IRB.start

data/lib/safe_clone/version.rb

@@ -1,3 +1,3 @@
 module SafeClone
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/lib/safe_clone.rb

@@ -1,4 +1,4 @@
-require "safe_clone/version"
+require_relative "safe_clone/version"
 
 class Object
   #By default, reference types use the clone method.

data/{Rakefile → rakefile.rb}

@@ -8,7 +8,12 @@ Rake::TestTask.new do |t|
   t.verbose    = false
 end
 
-desc "What version of full_clone is this?"
+desc "Fire up an IRB session with safe_clone preloaded."
+task :console do
+  system "ruby irbt.rb local"
+end
+
+desc "What version of safe_clone is this?"
 task :vers do |t|
   puts
   puts "safe_clone version = #{SafeClone::VERSION}"

data/safe_clone.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency 'minitest_visible', ">= 0.1.0"
-
+  spec.add_development_dependency 'mini_readline', ">= 0.4.8"
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
   spec.add_development_dependency 'minitest', "~> 5"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: safe_clone
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Peter Camilleri
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-18 00:00:00.000000000 Z
+date: 2016-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest_visible
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: mini_readline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.8
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.8
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -77,10 +91,11 @@ files:
 - Gemfile
 - LICENSE.txt
 - README.md
-- Rakefile
 - bench/bench.rb
+- irbt.rb
 - lib/safe_clone.rb
 - lib/safe_clone/version.rb
+- rakefile.rb
 - safe_clone.gemspec
 - test/safe_clone_tests.rb
 homepage: http://teuthida-technologies.com/