gibbler 0.3 → 0.4

data/CHANGES.txt

@@ -1,6 +1,23 @@
 GIBBLER, CHANGES
 
 
+#### 0.4 (2009-06-30) #################################
+
+NOTE: Calculated gibbles have changed since 0.3. Most gibbles created with 
+0.3 and earlier will not match those created in 0.4 for the same object
+
+* FIXED: Hash and Array now use the class of the value for hashing
+  rather than Hash or Array (respectively).
+* FIXED: __gibbler methods now return a digest based on their own class. 
+  Previously, all digests were created by String.__gibbler so the class
+  name from the original object got lost. 
+* CHANGE: Gibbler methods are no longer available to all Ruby classes
+  by default. The default list is now: String, Hash, Array, Symbol, 
+  Class, Fixnum, Bignum. 
+* CHANGE: Renamed Gibbler.gibbler_digest_type to Gibbler.digest_type
+* ADDED: Custom objects can now "include Gibbler::Complex"
+
+
 #### 0.3 (2009-06-29) #################################
 
 * CHANGE: Renamed to_gibble -> gibble

data/README.rdoc

@@ -1,30 +1,74 @@
-= Gibbler - v0.2 
+= Gibbler - v0.4
 
 Git-like hashes for Ruby objects.
 
-    
+== Examples
+
     config = {}
-    config.gibble              # => 57589e9811fe00c307ed3ab740cdac516c9975cb
+    config.gibble              # => 4fdcadc66a38feb9c57faf3c5a18d5e76a6d29bf
+    config.gibbled?            # => false
     
     config[:server] = { 
       :users => [:dave, :ali], 
       :ports => [22, 80, 443]
     }
-    config.gibble              # => 87d792aefceb893b2d966828827c61636b0ace3e 
+    config.gibbled?            # => true
+    config.gibble              # => ef23d605f8c4fc80a8e580f9a0e8dab8426454a8 
     
     config[:server][:users] << :yanni
     
-    config.gibble              # => 126ea10af73149ae4e69b0e036aa1d47a7651f07
+    config.gibble              # => 4c558a56bc2abf5f8a845a69e47ceb5e0003683f
+
+
+== 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:
+
+    class FullHouse
+      include Gibbler::Complex
+      attr_accessor :roles
+    end
+    
+    a = FullHouse.new
+    a.gibble                   # => 4192d4cb59975813f117a51dcd4454ac16df6703
+    
+    a.roles = [:jesse, :joey, :danny, :kimmy, :michelle, :dj, :stephanie]
+    a.gibble                   # => 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:
 
+    class Object
+      include Gibbler::String
+    end
 
-== ALPHA NOTICE
+Gibbler::String creates a digest based on the output of the to_s method. This is a reasonable default for more objects however any object that includes the object address in to_s (e.g. "<Object:0x0x4ac9f0...") will produce unreliable gibbles (because the address can change).
+
+
+== ALPHA NOTICE (2009-06-30)
 
 This code is hella fresh. It's ugly and barely tested, but it's fun to play with. I'll happily accept patches. 
 
+NOTE: Gibbles have changed between 0.3 and 0.4. Ones created with 0.3 and earlier will not match ones created with 0.4 for the same object. 
+
+
+== Known Issues
+
+* The gibble method or gibbled? must be called at least once before gibbled? will be able to return a useful value (otherwise there is no previous gibble value to compare to)
+
+
+== More Info
+
+* Codes[http://github.com/delano/gibbler]
+* RDocs[http://delano.github.com/gibbler]
+* Sponsor[http://solutious.com/]
+* Inspiration[http://www.youtube.com/watch?v=fipD4DdV48g]
+
 
 == Credits
 
-* Delano Mandelbaum (delano@solutious.com)
+* Delano (@solutious.com)
 
 
 == License

data/gibbler.gemspec

@@ -1,7 +1,7 @@
 @spec = Gem::Specification.new do |s|
 	s.name = "gibbler"
   s.rubyforge_project = "gibbler"
-	s.version = "0.3"
+	s.version = "0.4"
 	s.summary = "Gibbler: Git-like hashes for Ruby objects"
 	s.description = s.summary
 	s.author = "Delano Mandelbaum"

data/lib/gibbler.rb

@@ -6,7 +6,7 @@ require 'digest/sha1'
 # "Hola, Tanneritos"
 #
 module Gibbler
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
   
   @@gibbler_debug = false
   @@gibbler_digest_type = Digest::SHA1
@@ -16,15 +16,15 @@ module Gibbler
   # 
   #     Object.gibbler_digest_type = Digest::SHA256
   #
-  def self.gibbler_digest_type=(v)
+  def self.digest_type=(v)
     @@gibbler_digest_type = v
   end
   # Returns the current debug status (true or false)
-  def self.gibbler_debug?;      @@gibbler_debug; end
-  # Enable debugging with a true value
-  def self.gibbler_debug=(v);   @@gibbler_debug = v; end
+  def self.debug?;      @@gibbler_debug; end
+  def self.enable_debug;  @@gibbler_debug = true; end
+  def self.disable_debug;  @@gibbler_debug = false; end
   # Returns the current digest class. 
-  def self.gibbler_digest_type; @@gibbler_digest_type; end
+  def self.digest_type; @@gibbler_digest_type; end
 
   # Calculates a digest for the current object instance. 
   # Objects that are a kind of Hash or Array are processed
@@ -37,64 +37,241 @@ module Gibbler
     #  gibbler_debug [klass, a]
     #  a
     #end
-    gibbler_debug [:GIBBLER, self.class, self]
+    gibbler_debug :GIBBLER, self.class, self
     @__gibble__ = self.__gibbler
   end
   
+  # Sends +str+ to Digest::SHA1.hexdigest. If another digest class
+  # has been specified, that class will be used instead. 
+  # See: digest_type
+  def self.digest(str)
+    @@gibbler_digest_type.hexdigest str
+  end
+  
   # Has this object been modified?
+  #
+  # This method compares the return value from gibble with the 
+  # previous value returned by gibble (the value is stored in
+  # <tt>@__gibble__</tt>)
   def gibbled?
+    @__gibble__ ||= self.gibble
     was, now = @__gibble__.clone, self.gibble
-    gibbler_debug [:gibbled?, was, now]
+    gibbler_debug :gibbled?, was, now
     was != now
   end
   
   def gibbler_debug(*args)
-    return unless @@gibbler_debug == true
-    p *args 
+    return unless Gibbler.debug?
+    p args
+  end
+  def self.gibbler_debug(*args)
+    return unless Gibbler.debug?
+    p args
   end
-end
-
-class Hash
-  include Gibbler
   
-  def __gibbler(h=self)
-    klass = h.class
-    d = h.keys.sort { |a,b| a.inspect <=> b.inspect }
-    d.collect! do |name| 
-      '%s:%s:%s' % [klass, name, h[name].__gibbler]
-    end 
-    a = d.join($/).__gibbler 
-    gibbler_debug [klass, a]
-    a  
+  # Gets the list of instance variables from the standard implementation
+  # of the instance_variables method and removes <tt>@__gibble__</tt>. 
+  # Any class the includes Gibbler or Gibbler::* will use this version of
+  # instance_variables. It's important because we don't want the current
+  # gibble value to affect the next gibble. 
+  def instance_variables
+    vars = super
+    vars.reject! { |x| x.to_s == '@__gibble__' }
+    vars
   end
 
-end
-
-class Array
-  extend Gibbler
+  module Complex
+    include Gibbler
+    # Creates a gibble based on: 
+    # * An Array of instance variable names and values in the format: <tt>CLASS:LENGTH:VALUE</tt>
+    #   * The gibble method is called on each element so if it is a Hash or Array etc it 
+    #     will be parsed recursively according to the gibbler method for that class type.
+    # * Gibble the Array of gibbles 
+    # * Return the digest for <tt>class:length:value</tt> where:
+    #   * "class" is equal to the current object class (e.g. FullHouse).
+    #   * "length" is the size of the Array of gibbles (which should equal
+    #     the number of instance variables in the object).
+    #   * "value" is the Array of gibbles joined with a colon (":").
+    #
+    # This method can be used by any class which stores values in instance variables. 
+    #
+    def __gibbler(h=self)
+      klass = h.class
+      d = []
+      instance_variables.each do |n|
+        value = instance_variable_get(n)
+        d << '%s:%s:%s' % [value.class, n, value.__gibbler]
+      end
+      d = d.join(':').__gibbler
+      a = Gibbler.digest "%s:%d:%s" % [klass, d.size, d]
+      gibbler_debug klass, a, [klass, d.size, d]
+      a
+    end
+  end
   
-  def __gibbler(h=self)
-    klass = h.class
-    d, index = [], 0
-    h.each do |value| 
-      d << '%s:%s:%s' % [h.class, index, value.__gibbler]
-      index += 1
+  module String
+    include Gibbler
+    # Creates a gibble based on: <tt>CLASS:LENGTH:VALUE</tt>. 
+    # This method can be used for any class where the <tt>to_s</tt>
+    # method returns an appropriate unique value for this instance. 
+    # It's used by default for Symbol, Class, Fixnum, and Bignum.
+    # e.g.
+    # 
+    #     "str" => String:3:str => 509a839ca1744c72e37759e7684ff0daa3b61427
+    #     :sym  => Symbol:3:sym => f3b7b3ca9529002c6826b1ef609d3583c356c8c8
+    #
+    # To use use method in other classes simply:
+    #
+    #     class MyClass
+    #       include Gibbler::String
+    #     end
+    #
+    def __gibbler(h=self)
+      klass = h.class
+      value = h.nil? ? "\0" : h.to_s
+      a = Gibbler.digest "%s:%d:%s" % [klass, value.size, value]
+      gibbler_debug klass, a, [klass, value.size, value]
+      a
     end
-    a = d.join($/).__gibbler
-    gibbler_debug [klass, a]
-    a
   end
+      
+  module Hash 
+    include Gibbler
+    
+    # Creates a gibble based on: 
+    # * parse each key, value pair into an Array containing keys: <tt>CLASS:KEY:VALUE.__gibbler</tt>
+    #   * The gibble method is called on each element so if it is a Hash or Array etc it 
+    #     will be parsed recursively according to the gibbler method for that class type.
+    # * Gibble the Array of gibbles 
+    # * Return the digest for <tt>class:length:value</tt> where:
+    #   * "class" is equal to the current object class (e.g. Hash).
+    #   * "length" is the size of the Array of gibbles (which should equal
+    #     the number of keys in the original Hash object).
+    #   * "value" is the Array of gibbles joined with a colon (":").
+    #
+    # This method can be used by any class with a <tt>keys</tt> method. 
+    #
+    # e.g. 
+    #
+    #     class OrderedHash
+    #       include Gibbler::Hash
+    #     end
+    #
+    def __gibbler(h=self)
+      klass = h.class
+      d = h.keys.sort { |a,b| a.inspect <=> b.inspect }
+      d.collect! do |name| 
+        value = h[name]
+        '%s:%s:%s' % [value.class, name, value.__gibbler]
+      end 
+      d = d.join(':').__gibbler
+      a = Gibbler.digest '%s:%s:%s' % [klass, d.size, d]
+      gibbler_debug klass, a, [klass, d.size, d]
+      a  
+    end
+  end
+  
+  module Array
+    include Gibbler
+    
+    # Creates a gibble based on:
+    # * parse each element into an Array of gibbles like: <tt>CLASS:INDEX:VALUE.__gibbler</tt>
+    #   * The gibble method is called on each element so if it is a Hash or Array etc it 
+    #     will be parsed recursively according to the gibbler method for that class type. 
+    # * Gibble the Array of gibbles
+    # * Return the digest for <tt>class:length:value</tt> where:
+    #   * "class" is equal to the current object class (e.g. Array).
+    #   * "length" is the size of the Array of gibbles (which should equal
+    #     the number of elements in the original Array object).
+    #   * "value" is the Array of gibbles joined with a colon (":").
+    #
+    # This method can be used by any class with an <tt>each</tt> method.
+    #
+    # e.g.
+    #
+    #     class NamedArray 
+    #       include Gibbler::Array
+    #     end
+    #
+    def __gibbler(h=self)
+      klass = h.class
+      d, index = [], 0
+      h.each do |value| 
+        d << '%s:%s:%s' % [value.class, index, value.__gibbler]
+        index += 1
+      end
+      d = d.join(':').__gibbler
+      a = Gibbler.digest '%s:%s:%s' % [klass, d.size, d]
+      gibbler_debug klass, a, [klass, d.size, d]
+      a
+    end
+  end
+  
+  
+  ##--
+  ## NOTE: this was used when Gibbler supported "include Gibbler". We
+  ## now recommend the "include Gibbler::String" approach. This was an 
+  ## interesting approach so I'm keeping the code here for reference. 
+  ##def self.included(klass)
+  ##  # Find the appropriate Gibbler::* module for the inheriting class
+  ##  gibbler_module = Gibbler.const_get("#{klass}") rescue Gibbler::String
+  ##  
+  ##  # If a Gibbler module is not defined, const_get bubbles up
+  ##  # through the stack to find the constant. This will return 
+  ##  # the global class (likely itself) so we enforce a default.
+  ##  gibbler_module = Gibbler::String if gibbler_module == klass
+  ##  gibbler_debug :constant, klass, gibbler_module
+  ##  
+  ##  klass.module_eval do
+  ##    include gibbler_module
+  ##  end
+  ##  
+  ##end
+  ##++
+  
   
 end
 
-class Object
-  include Gibbler
-  
-  def __gibbler(h=self)
-    klass = h.class
-    value = h.nil? ? "\0" : h.to_s
-    a=@@gibbler_digest_type.hexdigest "%s:%d:%s" % [klass, value.size, value]
-    gibbler_debug [klass, value.size, value, a]
-    a
-  end
+class Hash
+  include Gibbler::Hash
 end
+
+class Array
+  include Gibbler::Array
+end
+
+class String
+  include Gibbler::String
+end
+
+class Symbol
+  include Gibbler::String
+end
+
+class Class
+  include Gibbler::String
+end
+
+class Fixnum
+  include Gibbler::String
+end
+
+class Bignum
+  include Gibbler::String
+end
+
+class TrueClass
+  include Gibbler::String
+end
+
+class FalseClass
+  include Gibbler::String
+end
+
+class Float
+  include Gibbler::String
+end
+
+
+
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: gibbler
 version: !ruby/object:Gem::Version 
-  version: "0.3"
+  version: "0.4"
 platform: ruby
 authors: 
 - Delano Mandelbaum
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-29 00:00:00 -04:00
+date: 2009-06-30 00:00:00 -04:00
 default_executable: 
 dependencies: []