gibbler 0.9.0 → 0.10.0

data/README.md

@@ -0,0 +1,258 @@
+# Gibbler - v0.10.0
+
+Git-like hashes and history for Ruby objects for Ruby 3.1+.
+
+Check out [this post on RubyInside](http://www.rubyinside.com/gibbler-git-like-hashes-and-history-for-ruby-objects-1980.html).
+
+* [Repo](https://github.com/delano/gibbler)
+* [Docs](https://delanotes.com/gibbler)
+* [Sponsor](https://solutious.com/)
+* [Inspiration](https://www.youtube.com/watch?v=fipD4DdV48g)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+  $ bundle add gibbler
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+  $ gem install gibbler
+```
+
+
+## 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
+
+```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.gibbled?              # => true
+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 `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.gibbler_commit             # => d7049916ddb25e6cc438b1028fb957e5139f9910
+
+a[:magic] = :updated
+a.gibbler_commit             # => b668098e16d08898532bf3aa33ce2253a3a4150e
+
+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.delete :magic
+
+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
+```
+
+![](https://delanotes.com/gibbler/img/whoababy.gif)
+
+
+### 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.
+
+
+```ruby
+    require 'gibbler/aliases'
+    require 'gibbler/history'
+
+    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.
+
+```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.
+
+```ruby
+require 'openssl'
+
+Gibbler.digest_type = OpenSSL::Digest::SHA256
+
+:kimmy.gibbler               # => 1069428e6273cf329436c3dce9b680d4d4e229d7b7...
+```
+
+### 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
+
+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
+
+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.
+
+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: `12075835e94be34438376cd7a54c8db7e746f15d`.
+
+### Some things to keep in mind
+
+* 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!
+
+## 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)
+
+## Development
+
+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.
+
+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).
+
+### 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
+
+* 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.
+
+* Andrea Barber
+
+
+## Code of Conduct
+
+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).
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/VERSION.yml

@@ -1,4 +1,4 @@
---- 
+---
 :MAJOR: 0
-:MINOR: 9
+:MINOR: 10
 :PATCH: 0

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/gibbler.gemspec

@@ -1,71 +1,22 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
-# -*- encoding: utf-8 -*-
-
 Gem::Specification.new do |s|
-  s.name = "gibbler"
-  s.version = "0.9.0"
+    s.name        = "gibbler"
+    s.version     = "0.10.0"
+    s.summary     = "Git-like hashes for Ruby objects"
+    s.description = "About Gibbler: Git-like hashes for Ruby objects"
+    s.authors     = ["Delano Mandelbaum"]
+    s.email       = "gems@solutious.com"
+    s.homepage    = "https://github.com/delano/gibbler"
+    s.license     = "MIT"
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Delano Mandelbaum"]
-  s.date = "2012-04-20"
-  s.description = "Gibbler: Git-like hashes for Ruby objects"
-  s.email = "delano@solutious.com"
-  s.extra_rdoc_files = [
-    "LICENSE.txt",
-     "README.rdoc"
-  ]
-  s.files = [
-    "CHANGES.txt",
-     "LICENSE.txt",
-     "README.rdoc",
-     "Rakefile",
-     "VERSION.yml",
-     "gibbler.gemspec",
-     "lib/gibbler.rb",
-     "lib/gibbler/aliases.rb",
-     "lib/gibbler/history.rb",
-     "lib/gibbler/mixins.rb",
-     "try/01_core_ext_try.rb",
-     "try/02_compat_try.rb",
-     "try/05_gibbler_digest_try.rb",
-     "try/10_standalone_try.rb",
-     "try/11_basic_try.rb",
-     "try/12_basic_sha256_try.rb",
-     "try/14_extended_try.rb",
-     "try/15_file_try.rb",
-     "try/16_uri_try.rb",
-     "try/17_complex_object_try.rb",
-     "try/18_proc_try.rb",
-     "try/20_time_try.rb",
-     "try/30_secret_try.rb",
-     "try/50_history_try.rb",
-     "try/51_hash_history_try.rb",
-     "try/52_array_history_try.rb",
-     "try/53_string_history_try.rb",
-     "try/57_arbitrary_history_try.rb",
-     "try/59_history_exceptions_try.rb",
-     "try/80_performance_try.rb",
-     "try/90_alias_try.rb"
-  ]
-  s.homepage = "http://github.com/delano/gibbler"
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubyforge_project = "gibbler"
-  s.rubygems_version = "1.8.22"
-  s.summary = "Gibbler: Git-like hashes for Ruby objects"
+    s.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    s.bindir        = "exe"
+    s.executables   = s.files.grep(%r{^exe/}) { |f| File.basename(f) }
+    s.require_paths = ["lib"]
 
-  if s.respond_to? :specification_version then
-    s.specification_version = 3
+    s.required_ruby_version = Gem::Requirement.new(">= 2.6.8")
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<attic>, [">= 0.4.0"])
-    else
-      s.add_dependency(%q<attic>, [">= 0.4.0"])
-    end
-  else
-    s.add_dependency(%q<attic>, [">= 0.4.0"])
-  end
-end
+    s.add_dependency "rake", "~> 13.0"
 
+    s.add_development_dependency "rubocop", "~> 1.0"
+    s.add_development_dependency "tryouts", "~> 2.2"
+  end

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