gibbler 0.8.10 → 0.10.0.pre.RC1

data/README.md

@@ -0,0 +1,250 @@
+# 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:
+
+    $ 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
+
+```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.
+
+    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.
+
+## 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).
+
+## Credits
+
+Gibbler was created by [Delano Mandelbaum](https://delanotes.com/).
+
+## 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: 8
-:PATCH: 10
+:MINOR: 9
+: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/lib/gibbler/aliases.rb

@@ -1,7 +1,7 @@
 
-require 'gibbler'
+require 'gibbler/mixins'
 
-module Gibbler
+class Gibbler < String
   
   module Object
     alias :digest           :gibbler

data/lib/gibbler/history.rb

@@ -1,7 +1,7 @@
 
 
 
-module Gibbler
+class Gibbler < String
   class NoRevert < Gibbler::Error
     def message; "Revert not implemented for #{@obj}" end
   end
@@ -11,17 +11,17 @@ module Gibbler
   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 @@ module Gibbler
         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 @@ module Gibbler
       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,9 +1,33 @@
+# rubocop:disable all
+require 'gibbler'
 
+class NilClass;            include Gibbler::Nil;       end
+class String;              include Gibbler::String;    end
+class Symbol;              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
+class Module;              include Gibbler::Object;    end
+class Proc;                include Gibbler::Object;    end
+class Regexp;              include Gibbler::String;    end
+class Float;               include Gibbler::String;    end
+class Date;                include Gibbler::String;    end
+class Hash;                include Gibbler::Hash;      end
+class Array;               include Gibbler::Array;     end
+class Time;                include Gibbler::Time;      end
+class DateTime < Date;     include Gibbler::DateTime;  end
+class Range;               include Gibbler::Range;     end
+class File;                include Gibbler::File;      end
+class TempFile;            include Gibbler::File;      end
+class MatchData;           include Gibbler::String;    end
+class OpenStruct;          include Gibbler::Object;    end
 
-class String
-  unless method_defined? :clear
-    def clear
-      replace ""
-    end
-  end
-end
+# URI::Generic must be included towards the
+# end b/c it runs Object#freeze statically.
+module URI; class Generic; include Gibbler::String;    end; end
+
+# Bundler calls freeze on an instance of Gem::Platform
+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