gibbler 0.9.0 → 0.10.0.pre.RC1

data/{README.rdoc → README.md}

@@ -1,236 +1,250 @@
-= Gibbler - v0.9
+# Gibbler - v0.10.0
 
-Git-like hashes and history for Ruby objects for Ruby 1.8, 1.9 and JRuby. 
+Git-like hashes and history for Ruby objects for Ruby 3.1+.
 
-Check out the screencast[http://www.rubypulse.com/episode-0.3-gibbler.html] created by Alex Peuchert.
+Check out [this post on RubyInside](http://www.rubyinside.com/gibbler-git-like-hashes-and-history-for-ruby-objects-1980.html).
 
-== Some things to keep in mind
+* [Repo](https://github.com/delano/gibbler)
+* [Docs](https://delanotes.com/gibbler)
+* [Sponsor](https://solutious.com/)
+* [Inspiration](https://www.youtube.com/watch?v=fipD4DdV48g)
 
-* Digest calculation may change between minor releases (as it did between 0.6 and 0.7)
-* Gibbler history is not suitable for very large objects since it keeps complete copies of the object in memory. This is a very early implementation of this feature so don't rely on it for production code. 
-* Don't forget to enjoy your life!
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add gibbler
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install gibbler
+
+## Usage
 
+### Example 1 -- Standalone Usage
 
-== Example 1 -- Standalone Usage
-    
+```ruby
     require 'gibbler'
-    
+
     g = Gibbler.new 'id', 1001   # => f4fb3796ababa3788d1bded8fdc589ab1ccb1c3d
     g.base(36)                   # => sm71s7eam4hm5jlsuzlqkbuktwpe5h9
-    
+
     g == 'f4fb3796ababa3788d1bded8fdc589ab1ccb1c3d'   # => true
     g === 'f4fb379'              # => true
-    
-== Example 2 -- Mixins Usage
-    
+```
+
+### Example 2 -- Mixins Usage
+
+```ruby
     require 'gibbler/mixins'
-    
+
     "kimmy".gibbler              # => c8027100ecc54945ab15ddac529230e38b1ba6a1
     :kimmy.gibbler               # => 52be7494a602d85ff5d8a8ab4ffe7f1b171587df
-    
+
     config = {}
     config.gibbler               # => 4fdcadc66a38feb9c57faf3c5a18d5e76a6d29bf
     config.gibbled?              # => false
-    
-    config[:server] = {          
-      :users => [:dave, :ali],   
-      :ports => [22, 80, 443]    
-    }                            
+
+    config[:server] = {
+      :users => [:dave, :ali],
+      :ports => [22, 80, 443]
+    }
     config.gibbled?              # => true
-    config.gibbler               # => ef23d605f8c4fc80a8e580f9a0e8dab8426454a8 
-    
+    config.gibbler               # => ef23d605f8c4fc80a8e580f9a0e8dab8426454a8
+
     config[:server][:users] << :yanni
-    
+
     config.gibbler               # => 4c558a56bc2abf5f8a845a69e47ceb5e0003683f
-    
+
     config.gibbler.short         # => 4c558a56
 
     config.gibbler.base36        # => 8x00l83jov4j80i9vfzpaxr9jag23wf
-    
+
     config.gibbler.base36.short  # => 8x00l83j
-    
-    
-== Example 3 -- Object History 
-    
-Gibbler can also keep track of the history of changes to an object. By default Gibbler supports history for Hash, Array, and String objects. The <tt>gibbler_commit</tt> method creates a clone of the current object and stores in an instance variable using the current hash digest as the key. 
+```
+
+### Example 3 -- Object History
 
+Gibbler can also keep track of the history of changes to an object. By default Gibbler supports history for Hash, Array, and String objects. The `gibbler_commit` method creates a clone of the current object and stores in an instance variable using the current hash digest as the key.
+
+```ruby
     require 'gibbler/mixins'
     require 'gibbler/history'
-    
-    a = { :magic => :original }     
+
+    a = { :magic => :original }
     a.gibbler_commit             # => d7049916ddb25e6cc438b1028fb957e5139f9910
-    
-    a[:magic] = :updated           
+
+    a[:magic] = :updated
     a.gibbler_commit             # => b668098e16d08898532bf3aa33ce2253a3a4150e
-    
-    a[:magic] = :changed 
+
+    a[:magic] = :changed
     a.gibbler_commit             # => 0b11c377fccd44554a601e5d2b135c46dc1c4cb1
-    
+
     a.gibbler_history            # => d7049916, b668098e, 0b11c377
-    
+
     a.gibbler_revert! 'd7049916' # Return to a specific commit
     a.gibbler                    # => d7049916ddb25e6cc438b1028fb957e5139f9910
-    a                            # => { :magic => :original } 
-    
+    a                            # => { :magic => :original }
+
     a.delete :magic
-    
-    a.gibbler_revert!            # Return to the previous commit  
+
+    a.gibbler_revert!            # Return to the previous commit
     a.gibbler                    # => 0b11c377fccd44554a601e5d2b135c46dc1c4cb1
     a                            # => { :magic => :changed }
-        
-    
+
+
     a.gibbler_object 'b668098e'  # => { :magic => :updated }
     a.gibbler_stamp              # => 2009-07-01 18:56:52 -0400
-    
-http://delano.github.com/gibbler/img/whoababy.gif
+```
+
+![](https://delanotes.com/gibbler/img/whoababy.gif)
 
 
-== Example 4 -- Method Aliases
+### Example 4 -- Method Aliases
 
 If you have control over the namespaces of your objects, you can use the method aliases to tighten up your code a bit. The "gibbler" and "gibbled?" methods can be accessed via "digest" and "changed?", respectively. (The reason they're not enabled by default is to avoid conflicts.)
-  
+
+```ruby
     require 'gibbler/aliases'
-    
+
     "kimmy".digest               # => c8027100ecc54945ab15ddac529230e38b1ba6a1
     :kimmy.digest                # => 52be7494a602d85ff5d8a8ab4ffe7f1b171587df
-    
+
     a = [:a, :b, :c]
     a.digest                     # => e554061823b8f06367555d1ee4c25b4ffee61944
     a << :d
     a.changed?                   # => true
 
-
 The history methods also have aliases which remove the "gibbler_" prefix.
-    
+
     require 'gibbler/aliases'
     require 'gibbler/history'
-    
-    a = { :magic => :original }     
-    a.commit                     
-    a.history                    
-    a.revert!                    
+
+    a = { :magic => :original }
+    a.commit
+    a.history
+    a.revert!
     # etc...
-    
-== Example 5 -- Different Digest types
+```
 
-By default Gibbler creates SHA1 hashes. You can change this globally or per instance. 
+### Example 5 -- Different Digest types
 
+By default Gibbler creates SHA1 hashes. You can change this globally or per instance.
+
+```ruby
     require 'gibbler/mixins'
-    
+
     Gibbler.digest_type = Digest::MD5
-    
+
     :kimmy.gibbler               # => 0c61ff17f46223f355759934154d5dcb
-    
+
     :kimmy.gibbler(Digest::SHA1) # => 52be7494a602d85ff5d8a8ab4ffe7f1b171587df
-    
+```
 
-In Jruby, you can grab the digest types from the openssl library. 
+In Jruby, you can grab the digest types from the openssl library.
 
+```ruby
     require 'openssl'
-    
+
     Gibbler.digest_type = OpenSSL::Digest::SHA256
-    
+
     :kimmy.gibbler               # => 1069428e6273cf329436c3dce9b680d4d4e229d7b7...
-    
-    
-== Example 6 -- All your base
+```
 
+### Example 6 -- All your base
+
+```ruby
     require 'gibbler/mixins'
-    
+
     :kimmy.gibbler               # => 52be7494a602d85ff5d8a8ab4ffe7f1b171587df
     :kimmy.gibbler.base(16)      # => 52be7494a602d85ff5d8a8ab4ffe7f1b171587df
     :kimmy.gibbler.base(36)      # => 9nydr6mpv6w4k8ngo3jtx0jz1n97h7j
 
     :kimmy.gibbler.base(10)      # => 472384540402900668368761869477227308873774630879
     :kimmy.gibbler.to_i          # => 472384540402900668368761869477227308873774630879
+```
 
+### Example 7 -- Global secret
 
-== Example 7 -- Global secret
-
-Gibbler can prepend all digest inputs with a global secret. You can set this once per project to ensure your project's digests are unique. 
+Gibbler can prepend all digest inputs with a global secret. You can set this once per project to ensure your project's digests are unique.
 
+```ruby
     require 'gibbler/mixins'
-    
+
     :kimmy.gibbler               # => 52be7494a602d85ff5d8a8ab4ffe7f1b171587df
-    
+
     Gibbler.secret = "sUp0r5ekRu7"
-    
+
     :kimmy.gibbler               # => 6c5f5aff4d809cec7e7da091214a35a2698489f8
-    
+```
 
-== Supported Classes
+### Supported Classes
 
-Gibbler methods are available only to the classes which explicitly include them (see RDocs[http://delano.github.com/gibbler] for details on which classes are supported by default). You can also extend custom objects:
+Gibbler methods are available only to the classes which explicitly include them [see docs'(https://delanotes.com/gibbler) for details on which classes are supported by default). You can also extend custom objects:
 
+```ruby
     class FullHouse
       include Gibbler::Complex
       attr_accessor :roles
     end
-    
+
     a = FullHouse.new
     a.gibbler                    # => 4192d4cb59975813f117a51dcd4454ac16df6703
-    
+
     a.roles = [:jesse, :joey, :danny, :kimmy, :michelle, :dj, :stephanie]
     a.gibbler                    # => 6ea546919dc4caa2bab69799b71d48810a1b48fa
-    
-Gibbler::Complex creates a digest based on the name of the class and the names and values of the instance variables. See the RDocs[http://delano.github.com/gibbler] for other Gibbler::* types. 
+```
+
+`Gibbler::Complex` creates a digest based on the name of the class and the names and values of the instance variables. See the RDocs[http://delano.github.com/gibbler] for other Gibbler::* types.
 
 If you want to support all Ruby objects, add the following to your application:
 
+```ruby
     class Object
       include Gibbler::String
     end
+```
 
-Gibbler::String creates a digest based on the name of the class and the output of the to_s method. This is a reasonable default for most objects however any object that includes the object address in to_s (e.g. "Object:0x0x4ac9f0...") will produce unreliable digests (because the address can change).
-
-As of 0.7 all Proc objects have the same digest: <tt>12075835e94be34438376cd7a54c8db7e746f15d</tt>. 
-
+`Gibbler::String` creates a digest based on the name of the class and the output of the to_s method. This is a reasonable default for most objects however any object that includes the object address in to_s (e.g. "Object:0x0x4ac9f0...") will produce unreliable digests (because the address can change).
 
+As of 0.7 all Proc objects have the same digest: `12075835e94be34438376cd7a54c8db7e746f15d`.
 
-== Known Issues
+### Some things to keep in mind
 
-* gibbler or gibbled? must be called at least once before gibbled? will be able to return a useful value (otherwise there is no previous digest value to compare to)
-* Digests for Bignum objects are different between Ruby and JRuby. Why?
-* Digests for Proc objects are different between Ruby 1.8 and 1.9 because Proc.arity returns different values and 1.8 has no lambda? method.
-
-
-== Installation
-
-Via Rubygems:
-
-    $ gem install gibbler
+* Digest calculation may change between minor releases (as it did between 0.6 and 0.7)
+* Gibbler history is not suitable for very large objects since it keeps complete copies of the object in memory. This is a very early implementation of this feature so don't rely on it for production code.
+* Don't forget to enjoy your life!
 
-or via download:
-* gibbler-latest.tar.gz[http://github.com/delano/gibbler/tarball/latest]
-* gibbler-latest.zip[http://github.com/delano/gibbler/zipball/latest]
+## What People Are Saying
 
+* "nice approach - everything is an object, every object is 'gittish'" -- [@olgen_morten](https://twitter.com/olgen_morten/statuses/2629909133)
+* "gibbler is just awesome" -- [@TomK32](https://twitter.com/TomK32/statuses/2618542872)
+* "wie cool ist Gibbler eigentlich?" -- [@we5](https://twitter.com/we5/statuses/2615274279)
+* "it's nice idea and implementation!" --[HristoHristov](https://www.rubyinside.com/gibbler-git-like-hashes-and-history-for-ruby-objects-1980.html#comment-39092)
 
-== What People Are Saying
+## Development
 
-* "nice approach - everything is an object, every object is 'gittish'" -- @olgen_morten[http://twitter.com/olgen_morten/statuses/2629909133]
-* "gibbler is just awesome" -- @TomK32[http://twitter.com/TomK32/statuses/2618542872]
-* "wie cool ist Gibbler eigentlich?" -- @we5[http://twitter.com/we5/statuses/2615274279]
-* "it's nice idea and implementation!" -- HristoHristov[http://www.rubyinside.com/gibbler-git-like-hashes-and-history-for-ruby-objects-1980.html#comment-39092]
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-== More Info
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-* Codes[http://github.com/delano/gibbler]
-* RDocs[http://delano.github.com/gibbler]
-* Sponsor[http://solutious.com/]
-* Inspiration[http://www.youtube.com/watch?v=fipD4DdV48g]
+### Contributing
 
+Bug reports and pull requests are welcome [GitHub Issues](https://github.com/delano/gibbler/issues). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/delano/gibbler/blob/main/CODE_OF_CONDUCT.md).
 
-== Thanks
+### Thanks
 
-* Kalin Harvey (krrh[http://github.com/krrh]) for the early feedback and artistic direction. 
-* Alex Peuchert (aaalex[http://github.com/aaalex]) for creating the screencast.
+* Kalin Harvey ([krrh](https://github.com/kalin)) for the early feedback and artistic direction.
+* Alex Peuchert ([aaalex](https://github.com/aaalex)) for creating the screencast.
 
+## Code of Conduct
 
-== Credits
+Everyone interacting in the Gibbler project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/delano/gibbler/blob/main/CODE_OF_CONDUCT.md).
 
-* [Delano Mandelbaum](http://delanotes.com/) (@solutious.com)
+## Credits
 
+Gibbler was created by [Delano Mandelbaum](https://delanotes.com/).
 
-== License
+## License
 
-See: LICENSE.txt
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "gibbler"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/gibbler/history.rb

@@ -11,17 +11,17 @@ class Gibbler < String
   class BadDigest < Gibbler::Error
     def message; "Unknown digest: #{@obj}"; end
   end
-    
+
   module History
     extend Attic
-    
+
     attic :__gibbler_history
-    
+
     @@mutex = Mutex.new
-    
+
     def self.mutex; @@mutex; end
-    
-    # Returns an Array of digests in the order they were committed. 
+
+    # Returns an Array of digests in the order they were committed.
     # If +short+ is anything but false, the digests will be converted
     # to the short 8 character digests.
     def gibbler_history(short=false)
@@ -37,104 +37,104 @@ class Gibbler < String
         self.__gibbler_history[:history].collect { |g| g.short }
       end
     end
-    
+
     # Returns the object stored under the given digest +g+.
-    # If +g+ is not a valid digest, returns nil. 
-    def gibbler_object(g=nil) 
+    # If +g+ is not a valid digest, returns nil.
+    def gibbler_object(g=nil)
       g = gibbler_find_long g
       g = self.gibbler_history.last if g.nil?
 
       return unless gibbler_valid? g
       self.__gibbler_history[:objects][ g ]
     end
-    
-    # Returns the timestamp (a Time object) when the digest +g+ was committed. 
-    # If +g+ is not a valid gibble, returns nil. 
+
+    # Returns the timestamp (a Time object) when the digest +g+ was committed.
+    # If +g+ is not a valid gibble, returns nil.
     def gibbler_stamp(g=nil)
       g = gibbler_find_long g
       g = self.gibbler_history.last if g.nil?
       return unless gibbler_valid? g
       self.__gibbler_history[:stamp][ g ]
     end
-    
+
     # Stores a clone of the current object instance using the current
     # digest value. If the object was not changed, this method does
-    # nothing but return the gibble. 
+    # nothing but return the gibble.
     #
     # NOTE: This method is not fully thread safe. It uses a Mutex.synchronize
-    # but there's a race condition where two threads can attempt to commit at 
-    # near the same time. The first will get the lock and create the commit. 
-    # The second will get the lock and create another commit immediately 
-    # after. What we probably want is for the second thread to return the 
+    # but there's a race condition where two threads can attempt to commit at
+    # near the same time. The first will get the lock and create the commit.
+    # The second will get the lock and create another commit immediately
+    # after. What we probably want is for the second thread to return the
     # digest for that first snapshot, but how do we know this was a result
     # of the race conditioon rather than two legitimate calls for a snapshot?
     def gibbler_commit
       now, digest, point = nil,nil,nil
-      
+
       if self.__gibbler_history.nil?
         @@mutex.synchronize {
           self.__gibbler_history ||= { :history => [], :objects => {}, :stamp => {} }
         }
       end
-      
+
       @@mutex.synchronize {
         now, digest, point = ::Time.now, self.gibbler, self.clone
         self.__gibbler_history[:history] << digest
         self.__gibbler_history[:stamp][digest] = now
         self.__gibbler_history[:objects][digest] = point
       }
-      
+
       digest
     end
-    
+
     # Revert this object to a previously known state. If called without arguments
     # it will revert to the most recent commit. If a digest is specified +g+, it
-    # will revert to that point. 
+    # will revert to that point.
     #
-    # Ruby does not support replacing self (<tt>self = previous_self</tt>) so each 
+    # Ruby does not support replacing self (`self = previous_self`) so each
     # object type needs to implement its own __gibbler_revert! method. This default
-    # run some common checks and then defers to self.__gibbler_revert!. 
-    # 
+    # run some common checks and then defers to self.__gibbler_revert!.
+    #
     # Raise the following exceptions:
     # * NoRevert: if this object doesn't have a __gibbler_revert! method
     # * NoHistory: This object has no commits
     # * BadDigest: The given digest is not in the history for this object
     #
-    # If +g+ matches the current digest value this method does nothing. 
+    # If +g+ matches the current digest value this method does nothing.
     #
-    # Returns the new digest (+g+). 
+    # Returns the new digest (+g+).
     def gibbler_revert!(g=nil)
       raise NoRevert unless self.respond_to? :__gibbler_revert!
       raise NoHistory, self.class unless gibbler_history?
       raise BadDigest, g if !g.nil? && !gibbler_valid?(g)
-      
+
       g = self.gibbler_history.last if g.nil?
-      g = gibbler_find_long g 
-      
-      # Do nothing if the given digest matches the current gibble. 
+      g = gibbler_find_long g
+
+      # Do nothing if the given digest matches the current gibble.
       # NOTE: We use __gibbler b/c it doesn't update self.gibbler_cache.
       unless self.__gibbler == g
         @@mutex.synchronize {
-          # Always make sure self.gibbler_digest is a Gibbler::Digest 
+          # Always make sure self.gibbler_digest is a Gibbler::Digest
           self.gibbler_cache = g.is_a?(Gibbler::Digest) ? g : Gibbler::Digest.new(g)
           self.__gibbler_revert!
         }
       end
-      
+
       self.gibbler_cache
     end
-    
+
     # Is the given digest +g+ contained in the history for this object?
     def gibbler_valid?(g)
       return false unless gibbler_history?
       gibbler_history.member? gibbler_find_long(g)
     end
-    
+
     # Does the current object have any history?
     def gibbler_history?
       !gibbler_history.empty?
     end
-    
+
     # Returns the long digest associated to the short digest +g+.
     # If g is longer than 8 characters it returns the value of +g+.
     def gibbler_find_long(g)
@@ -143,7 +143,7 @@ class Gibbler < String
       gibbler_history.select { |d| d.match /\A#{g}/ }.first
     end
   end
-  
+
 end
 
 class Hash
@@ -161,7 +161,7 @@ class Array
     self.push *(self.gibbler_object self.gibbler_cache)
   end
 end
-  
+
 class String
   include Gibbler::History
   def __gibbler_revert!
@@ -169,5 +169,3 @@ class String
     self << (self.gibbler_object self.gibbler_cache)
   end
 end
-      
-

data/lib/gibbler/mixins.rb

@@ -1,10 +1,10 @@
+# rubocop:disable all
 require 'gibbler'
 
 class NilClass;            include Gibbler::Nil;       end
 class String;              include Gibbler::String;    end
 class Symbol;              include Gibbler::String;    end
-class Fixnum;              include Gibbler::String;    end
-class Bignum;              include Gibbler::String;    end
+class Integer;             include Gibbler::String;    end
 class TrueClass;           include Gibbler::String;    end
 class FalseClass;          include Gibbler::String;    end
 class Class;               include Gibbler::Object;    end
@@ -23,7 +23,7 @@ class TempFile;            include Gibbler::File;      end
 class MatchData;           include Gibbler::String;    end
 class OpenStruct;          include Gibbler::Object;    end
 
-# URI::Generic must be included towards the 
+# URI::Generic must be included towards the
 # end b/c it runs Object#freeze statically.
 module URI; class Generic; include Gibbler::String;    end; end
 
@@ -31,4 +31,3 @@ module URI; class Generic; include Gibbler::String;    end; end
 module Gem; class Platform; include Gibbler::Complex;  end; end
 
 module Addressable; class URI; include Gibbler::String; end; end
-

data/lib/gibbler/version.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Gibbler
+
+  module VERSION
+    def self.to_s
+      load_config
+      [@version[:MAJOR], @version[:MINOR], @version[:PATCH]].join('.')
+    end
+    alias_method :inspect, :to_s
+    def self.load_config
+      require 'yaml'
+      @version ||= YAML.load_file(::File.join(GIBBLER_LIB_HOME, '..', 'VERSION.yml'))
+    end
+  end
+
+end