crimp 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 933033b434c42dd1f1bddcae7dab3a28ca3cd59ea6f3c1c9099f7b7b94f16eb4
-  data.tar.gz: a48ac5e269d70ac652422d4959372acd2937df77ae3a970887642b67ee5ad4af
+  metadata.gz: c137825335bbd1636911bede1f6acba9dc001070c68cce11aa26d7bb1e79f120
+  data.tar.gz: 610febce9965c5c7f2efe2aea310613f7e854b9de8de3ae1263acf525f12f78a
 SHA512:
-  metadata.gz: b270bad70530524c0110fa9e6e80e29f95751802d7732cb5c683aa3e610d4674485ed4196384f8b6312629dc2cd64d2a60de0cce301a2dd8520f38be9735f966
-  data.tar.gz: 269d0964c13056187ded2be18fc748bbbe9fc9e85b8b5e67d165aa27e9a07c7ff9d8681ccfddd6bd70bbc172514e6976e881d14b9df3da2783a7e04d6d2d0e99
+  metadata.gz: 87a85aedb707739ea28220183e96dbbfb51ed84443314a5cb2459c36f9ea0dd2d1d4e1ddd6a61e6ec43730414d73a021961e3861f1aca4c9e13fb7d8025ed6d3
+  data.tar.gz: 64edcb40a960ad815a0b4c2006d89e091f27b4a1102ad622be001dcae0b324942493d6737bd7b7205945253710c94e1e977dc6699e9ef354cbd44046c15ae969

data/.ruby-version

@@ -1 +1 @@
-jruby-1.7.23
+2.5.1

data/.travis.yml

@@ -1,9 +1,11 @@
 language: ruby
 rvm:
   - "jruby"
+  - "2.3"
+  - "2.5"
 notifications:
   email:
     recipients:
-      - kenoir@gmail.com
+      - D&ENewsFrameworksTeam@bbc.co.uk
     on_failure: change
     on_success: never

data/LICENSE.txt

@@ -1,22 +1,21 @@
-Copyright (c) 2014 Robert Kenny
+The MIT License
 
-MIT License
+Copyright (c) 2014-2018 BBC News https://www.bbc.co.uk/news
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -3,45 +3,187 @@
 [![Build Status](https://travis-ci.org/BBC-News/crimp.png?branch=master)](https://travis-ci.org/BBC-News/crimp)
 [![Gem Version](https://badge.fury.io/rb/crimp.png)](http://badge.fury.io/rb/crimp)
 
-Creating an md5 hash of a number, string, array, or hash in Ruby
-
-![mighty-boosh-four-way-crimp-o](https://f.cloud.github.com/assets/180050/2148112/b44fd6fa-93de-11e3-9f9a-ad941f069b5c.gif)
-
-Shamelessly copied from [this Stack Overflow
-answer](http://stackoverflow.com/a/6462589/3243663).
+Creates an MD5 hash from simple data structures made of numbers, strings, booleans, nil, arrays or hashes.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'crimp'
+```ruby
+gem 'crimp'
+
+```
 
 And then execute:
 
-    $ bundle
+```shell
+$ bundle
+
+```
 
 Or install it yourself as:
 
-    $ gem install crimp
+```shell
+$ gem install crimp
+```
 
 ## Usage
 
-```rb
+```ruby
 require 'crimp'
 
-Crimp.stringify({:a => {:b => 'b', :c => 'c'}, :d => 'd'})
+Crimp.signature({ a: { b: 1 } })
+=> "ac13c15d07e5fa3992fc6b15113db900"
+```
+
+## Multiplatform design
+
+At the BBC we use Crimp to build keys for database and cache entries.
+
+If you want to build a similar library with your language of choice you should be able to follow the simple specifications defined in `spec/crimp_spec.rb`. Using these simple rules you will produce a string ready to be MD5 signed.
+
+Once you get your string, is very important to be sure that you can produce the same key in any language. MD5 is your friend:
+
+### Ruby
+
+```ruby
+irb(main):001:0> require 'digest'
+=> true
+irb(main):002:0> Digest::MD5.hexdigest('abc')
+=> "900150983cd24fb0d6963f7d28e17f72"
+```
+
+### Lua
+
+```lua
+Lua 5.3.5  Copyright (C) 1994-2018 Lua.org, PUC-Rio
+> md5 = require 'md5'
+> md5.sumhexa('abc')
+900150983cd24fb0d6963f7d28e17f72
+```
 
-# => [\"aSymbol=>[\\\"bSymbol=>b\\\", \\\"cSymbol=>c\\\"]Array\",\"dSymbol=>d\"]Array"
+### Elixir
 
-Crimp.signature({:a => {:b => 'b', :c => 'c'}, :d => 'd'})
+``` elixir
+Erlang/OTP 21 [erts-10.0.4] [source] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:1] [hipe] [dtrace]
+Interactive Elixir (1.7.2) - press Ctrl+C to exit (type h() ENTER for help)
+iex(1)> :crypto.hash(:md5 , "abc") |> Base.encode16() |> String.downcase
+"900150983cd24fb0d6963f7d28e17f72"
+```
 
-# => "68d07febc4f47f56fa6ef5de063a77b1"
+### Node.js
 
+``` javascript
+> var crypto = require('crypto');
+undefined
+> crypto.createHash('md5').update('abc').digest('hex');
+'900150983cd24fb0d6963f7d28e17f72'
 ```
 
+## Fine prints
+
+### Symbols
+
+To make Crimp signatures reproducible in any platform we decided to ignore Ruby symbols and treat them as strings, so:
+
+``` ruby
+Crimp.signature(:a) == Crimp.Signature('a')
+```
+
+### Sets
+
+Also Sets get transformed to Arrays:
+
+``` ruby
+Crimp.signature(Set.new(['a', 'b'])) == Crimp.signature(['a', 'b'])
+```
+
+### Sorting of collections
+
+Crimp signatures are generated against sorted collections.
+
+```ruby
+Crimp.signature([1, 2]) == Crimp.signature([2, 1])
+Crimp.signature({'b' => 2, 'a' => 1}) == Crimp.signature({'a' => 1, 'b' => 2})
+```
+
+Crimp also sorts nested collections.
+
+```ruby
+Crimp.signature([1, [3, 2], 4]) == Crimp.signature([4, [2, 3], 1])
+Crimp.signature({'b' => {'d' => 2,'c' => 1}, 'a' => [3, 1, 2]}) == Crimp.signature({'a' => [1, 2, 3], 'b' => { 'c' => 1, 'd' => 2 }})
+```
+
+### Custom objects
+
+Crimp will complain if you try to get a signature from an instance of some custom object:
+
+``` ruby
+Crimp.signature(Object.new)
+=> TypeError: Expected a (String|Number|Boolean|Nil|Hash|Array), Got Object
+```
+It is your responsibility to pass a compatible representation of your object to Crimp.
+
+## Implementation details
+
+Under the hood Crimp annotates the passed data structure to a nested array of primitives (strings, numbers, booleans, nils, etc.) and a single byte to indicate the type of the primitive:
+
+|  Type   | Byte |
+|   :-:   |  :-: |
+| String  |  `S` |
+| Number  |  `N` |
+| Boolean |  `B` |
+| nil     |  `_` |
+| Array   |  `A` |
+| Hash    |  `H` |
+
+You can verify it using the `#annotate` method:
+
+``` ruby
+Crimp.annotate({ a: 1 })
+=> [[[[[1, "N"], ["a", "S"]], "A"]], "H"]
+```
+Notice how Crimp marks the collection as Hash (`H`) and then transforms the tuple of key/values to an Array (`A`).
+
+Here's an example with nested hashes:
+
+```ruby
+Crimp.annotate({ a: { b: 'c' } })
+=> [[[[["a", "S"], [[[[["b", "S"], ["c", "S"]], "A"]], "H"]], "A"]], "H"]
+```
+
+Before signing Crimp transforms the collection of nested array to a string.
+
+```ruby
+Crimp.notation({ a: { b: 'c' } })
+=> "aSbScSAHAH"
+```
+
+Please note the Arrays and Hash keys are sorted before signing.
+
+``` ruby
+Crimp.notation([3, 1, 2])
+=> "1N2N3NA"
+```
+
+key/value tuples get sorted as well.
+
+``` ruby
+Crimp.notation({ a: 1 })
+=> "1NaSAH"
+```
+
+## Changelog
+
+| Version | Changes                                                                    |
+|---------|----------------------------------------------------------------------------|
+|`v0.x`   | Original version of Crimp.                                                 |
+|`v0.2.0` | Crimp compatibility with Ruby >= 2.4, use this for legacy projects.        |
+|`v1.0.0` | Includes **breaking changes** and returns different signatures from `v0.2` |
+
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/crimp/fork )
+1. Fork it ( http://github.com/BBC-News/crimp/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`)

data/Rakefile

@@ -1,6 +1,10 @@
 $LOAD_PATH.unshift File.join(File.dirname(__FILE__), 'lib')
 
+require 'rspec/core/rake_task'
 require 'bundler/gem_tasks'
-require 'rake/rspec'
 
-task default: :spec
+RSpec::Core::RakeTask.new :specs do |task|
+  task.pattern = Dir['spec/**/*_spec.rb']
+end
+
+task default: [:specs]

data/crimp.gemspec

@@ -1,35 +1,24 @@
 # coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'crimp/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "crimp"
-  spec.version       = Crimp::VERSION
-  spec.authors       = ["BBC News"]
-  spec.email         = ["D&ENewsFrameworksTeam@bbc.co.uk"]
-  spec.summary       = %q{Creating an md5 hash of a number, string, array, or hash in Ruby}
-  spec.description   = <<-EOS.gsub /^\s+/, ""
-                         Shamelessly lifted from http://stackoverflow.com/questions/6461812/creating-an-md5-hash-of-a-number-string-array-or-hash-in-ruby
-
-                         All credit should go to http://stackoverflow.com/users/394282/luke
-                       EOS
-  spec.homepage      = ""
-  spec.license       = "MIT"
+  spec.name          = 'crimp'
+  spec.version       = '1.0.0'
+  spec.authors       = ['BBC News']
+  spec.email         = ['D&ENewsFrameworksTeam@bbc.co.uk']
+  spec.summary       = 'Creates an MD5 hash from simple data structures.'
+  spec.description   = 'Platform agnostic MD5 hash from simple data structures made of numbers, strings, booleans, nil, arrays or hashes.'
+  spec.homepage      = 'https://www.bbc.co.uk/news'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "bundler", "~> 1.5"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec"
-  spec.add_development_dependency "rake-rspec"
-  spec.add_development_dependency "rspec-nc"
-  spec.add_development_dependency "guard"
-  spec.add_development_dependency "guard-rspec"
-  spec.add_development_dependency "pry"
-  spec.add_development_dependency "pry-remote"
-  spec.add_development_dependency "pry-nav"
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_dependency 'deepsort'
 end

data/lib/crimp.rb

@@ -1,74 +1,52 @@
-require 'crimp/version'
-require 'digest'
+# frozen_string_literal: true
 
-class Numeric
-  # see http://patshaughnessy.net/2014/1/9/how-big-is-a-bignum
-  def bignum?
-    self >= 4611686018427387904
-  end
-end
+require 'digest/md5'
+require 'set'
+require 'deepsort'
 
-module Crimp
-  def self.signature(obj)
-    Digest::MD5.hexdigest stringify(obj)
-  end
-
-  def self.stringify(obj)
-    convert(obj).tap { |o| return o.class == String ? o : to_string(o) }
-  end
-
-  private
-
-  def self.convert(obj)
-    case obj
-    when Array
-      parse_array obj
-    when Hash
-      parse_hash obj
-    when String
-      obj
-    else
-      to_string obj
+class Crimp
+  class << self
+    def signature(obj)
+      Digest::MD5.hexdigest(notation(obj))
     end
-  end
 
-  def self.hash_to_array(hash)
-    [].tap do |a|
-      hash.each { |k, v| a << pair_to_string(k, v) }
+    def notation(obj)
+      annotate(obj).flatten.join
     end
-  end
 
-  def self.pair_to_string(k, v)
-    "#{stringify k}=>#{stringify v}"
-  end
-
-  def self.parse_array(array)
-    array.map { |e| stringify(e) }.sort
-  end
+    def annotate(obj)
+      obj = coerce(obj)
+
+      case obj
+      when String
+        [obj, 'S']
+      when Numeric
+        [obj, 'N']
+      when TrueClass, FalseClass
+        [obj, 'B']
+      when NilClass
+        [nil, '_']
+      when Array
+        [sort(obj), 'A']
+      when Hash
+        [sort(obj), 'H']
+      else
+        raise TypeError, "Expected a (String|Number|Boolean|Nil|Hash|Array), Got #{obj.class}."
+      end
+    end
 
-  def self.parse_hash(hash)
-    stringify hash_to_array(hash)
-  end
+    private
 
-  def self.to_string(obj)
-    "#{obj}#{legacy_class(obj)}"
-  end
+    def sort(coll)
+      coll.deep_sort_by { |obj| obj.to_s }.map { |obj| annotate(obj) }
+    end
 
-  # This is for legacy/compatibilty reason:
-  #
-  # Ruby 2.1
-  # 2.class => Fixnum
-  # Ruby >= 2.4
-  # 2.class => Integer
-  #
-  # Say you have a huge number of stored keys and you migrate your app from 2.1 to >= 2.4
-  # this would cause a change of the signature for a subset of the keys which would be hard
-  # to debug especially for nested data structures.
-  #
-  def self.legacy_class(obj)
-    return obj.class unless obj.is_a?(Numeric)
-    return 'Float'   if obj.is_a?(Float)
-    return 'Bignum'  if obj.bignum?
-    'Fixnum'
+    def coerce(obj)
+      case obj
+      when Symbol then obj.to_s
+      when Set    then obj.to_a
+      else obj
+      end
+    end
   end
 end

data/spec/acceptance_data.yml

@@ -0,0 +1,66 @@
+---
+-
+  desc: verify String handling
+  json: abc
+  string: abcS
+  signature: c4449120506d97975c67be69719a78e2
+-
+  desc: verify integers handling
+  json: 1
+  string: 1N
+  signature: 594170053719896a11eb08ee513813d5
+-
+  desc: verify floats handling
+  json: 1.2
+  string: 1.2N
+  signature: f1ab6592886cd4b1b66ed55e73d9ab81
+-
+  desc: verify Array handling
+  json: [1, "a", 3]
+  string: 1N3NaSA
+  signature: cd1c43797d488d0f6c0d71537c64d30b
+-
+  desc: verify Array sorting
+  json: [3, null, 1, "1"]
+  string: _1N1S3NA
+  signature: 518e7bb17674f6acbb296845862a152d
+-
+  desc: verify Array sorting with capital letters
+  json: ["a", "A", "b", "B"]
+  string: ASBSaSbSA
+  signature: f6692ab4bc94b35e61ec15c2d1891734
+-
+  desc: verify nested Arrays
+  json: ["a", 1, ["b", "2"]]
+  string: 1N2SbSAaSA
+  signature: 3aaa58da4841eaeb41d3726d2c6fd875
+-
+  desc: verify nested Arrays
+  json: [["b", "2"], "a", 1]
+  string: 1N2SbSAaSA
+  signature: 3aaa58da4841eaeb41d3726d2c6fd875
+-
+  desc: verify hash like data structures
+  json: {"a": 1}
+  string: 1NaSAH
+  signature: 8cb44d69badda0f34b0bab6bb3e7fdbf
+-
+  desc: verify nested hash
+  json: {"a": {"c": null, "2": 2 }}
+  string: aS2S2NA_cSAHAH
+  signature: bff3538075e4007c7679a7ba0d0a5f30
+-
+  desc: verify null values
+  json: null
+  string: _
+  signature: b14a7b8059d9c055954c92674ce60032
+-
+  desc: verify true boolean values
+  json: true
+  string: trueB
+  signature: 6413cfeb7a89f7e0a8872f82b919c0d9
+-
+  desc: verify false boolean values
+  json: false
+  string: falseB
+  signature: fa39253035cfe44c8638b8f5d7a3402e

data/spec/acceptance_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+require 'yaml'
+require 'json'
+
+# other libraries could fetch the test data from Github.
+file  = File.join(__dir__, 'acceptance_data.yml')
+tests = YAML::load_file(file)
+
+describe 'Multiplatform compatibility acceptance tests' do
+  tests.each do |test|
+    input     = JSON.parse(test['json'].to_json, quirks_mode: true)
+    signature = test['signature']
+    string    = test['string']
+
+    specify "#{test['desc']} string"  do
+      expect(Crimp.notation(input)).to eq(string)
+    end
+
+    specify "#{test['desc']} signature"  do
+      expect(Crimp.signature(input)).to eq(signature)
+    end
+  end
+end

data/spec/crimp_spec.rb

@@ -1,99 +1,299 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
-describe Crimp do
-  let(:hash) { { a: { b: 'b', c: 'c' }, d: 'd' } }
-  let(:hash_with_numbers) { { a: { b: 1, c: 3.14 }, d: 'd' } }
-  let(:hash_unordered) { { d: 'd', a: { c: 'c', b: 'b' } } }
-  let(:array) { [1, 2, 3, [4, [5, 6]]] }
-  let(:array_unordered) { [3, 2, 1, [[5, 6], 4]] }
-
-  describe '.signature' do
-    context 'given a Hash' do
-      it 'returns MD5 hash of stringified Hash' do
-        expect(subject.signature(hash)).to eq('68d07febc4f47f56fa6ef5de063a77b1')
-      end
-
-      it 'does not modify original hash' do
-        original_hash = { d: 'd', a: { c: 'c', b: 'b' } }
-        expected_hash = { d: 'd', a: { c: 'c', b: 'b' } }
-
-        subject.signature(original_hash)
-
-        expect(original_hash).to eq(expected_hash)
-      end
-    end
-
-    context 'Given an hash with numbers' do
-      it 'returns MD5 hash of stringified hash' do
-        expect(subject.signature(hash_with_numbers)).to eq 'b1fec09904b6ff36c92e3bd48234def7'
-      end
-    end
-
-    context 'given an Array' do
-      it 'returns MD5 hash of stringified Array' do
-        expect(subject.signature(array)).to eq('4dc4e1161c9315db0bc43c0201b3ec05')
-      end
-
-      it 'does not modify original array' do
-        original_array = [5, 4, 2, 6, [5, 7, 2]]
-        expected_array = [5, 4, 2, 6, [5, 7, 2]]
-
-        subject.signature(original_array)
-
-        expect(original_array).to eq(expected_array)
-      end
-    end
-
-    context 'Given an integer' do
-      it 'returns MD5 hash of an Integer' do
-        expect(subject.signature(123)).to eq '519d3381631851be66711f6d7dfbb4f8'
-      end
-    end
-
-    context 'Given an Bignum' do
-      it 'returns MD5 hash of a Bignum' do
-        expect(subject.signature(9999999999999999999)).to eq 'f00e75abca720e18fd4213e2a6de96c6'
-      end
-    end
-
-    context 'Given an float' do
-      it 'returns MD5 hash of a Float' do
-        expect(subject.signature(3.14)).to eq 'b07d506e3701fddd083ae9095df43218'
-      end
-    end
-  end
-
-  describe '.stringify' do
-    context 'given a Hash' do
-      it 'returns equal strings for differently ordered hashes' do
-        expect(subject.stringify(hash)).to eq(subject.stringify(hash_unordered))
-      end
-
-      it 'does not modify original hash' do
-        original_hash = { d: 'd', a: { c: 'c', b: 'b' } }
-        expected_hash = { d: 'd', a: { c: 'c', b: 'b' } }
-
-        subject.signature(original_hash)
-
-        expect(original_hash).to eq(expected_hash)
-      end
-    end
-
-    context 'given an Array' do
-      specify { expect(subject.stringify(array)).to be_a String }
-
-      it 'returns equal strings for differently ordered arrays' do
-        expect(subject.stringify(array)).to eq(subject.stringify(array_unordered))
-      end
-
-      it 'does not modify original array' do
-        original_array = [5, 4, 2, 6, [5, 7, 2]]
-        expected_array = [5, 4, 2, 6, [5, 7, 2]]
-
-        subject.signature(original_array)
-
-        expect(original_array).to eq(expected_array)
-      end
-    end
+describe '.signature' do
+  it 'will return an md5 hash' do
+    expect(Crimp.signature('a')).to eq 'd132c0567a5964930f9ee5f14e779e32'
+  end
+end
+
+describe '.notation' do
+  it 'returns a string representation of the passed data' do
+    expect(Crimp.notation([123, 'abc'])).to eq('123NabcSA')
+  end
+end
+
+describe '.annotate' do
+  it 'returns an array of tuples representing the value and the type' do
+    expect(Crimp.annotate([123, 'abc'])).to eq([[[123, 'N'], ['abc', 'S']], 'A'])
+  end
+
+  it "returns a tuple [val, 'N'] for numeric primitives" do
+    expect(Crimp.annotate(123)).to eq([123, 'N'])
+  end
+
+  it "returns a tuple [val, 'S'] for string primitives" do
+    expect(Crimp.annotate('abc')).to eq(['abc', 'S'])
+  end
+
+  it "returns a tuple [[], 'A'] for empty arrays" do
+    expect(Crimp.annotate([])).to eq([[], 'A'])
+  end
+end
+
+describe 'Strings' do
+  it 'handles strings' do
+    expect(Crimp.annotate('a')).to eq(['a', 'S'])
+  end
+
+  it 'handles capitalised strings with no modifications' do
+    expect(Crimp.annotate('A')).to eq(['A', 'S'])
+  end
+
+  it 'handles utf-8 strings' do
+    expect(Crimp.annotate('å')).to eq(['å', 'S'])
+  end
+
+  it 'treats symbols like strings' do
+    expect(Crimp.annotate(:a)).to eq(['a', 'S'])
+  end
+
+  it 'treats empty strings like strings' do
+    expect(Crimp.annotate('')).to eq(['', 'S'])
+  end
+end
+
+describe 'Numbers' do
+  it 'handles integers' do
+    expect(Crimp.annotate(1)).to eq([1, 'N'])
+  end
+
+  it 'handles floats' do
+    expect(Crimp.annotate(3.14)).to eq([3.14, 'N'])
+  end
+
+  it 'handles bignums' do
+    bignum = 10_000_000_000_000_000_000
+
+    expect(Crimp.annotate(bignum)).to eq([bignum, 'N'])
+  end
+end
+
+describe 'Nils' do
+  it 'handles nils' do
+    expect(Crimp.annotate(nil)).to eq([nil, '_'])
+  end
+end
+
+describe 'Booleans' do
+  it 'handles falsey values' do
+    expect(Crimp.annotate(false)).to eq([false, 'B'])
+  end
+
+  it 'handles truthy values' do
+    expect(Crimp.annotate(true)).to eq([true, 'B'])
+  end
+end
+
+describe 'Arrays' do
+  it 'handles arrays as collection of primitives' do
+    expect(Crimp.annotate([1, 2])).to eq([[[1, 'N'], [2, 'N']], 'A'])
+  end
+
+  it 'sorts arrays' do
+    expect(Crimp.annotate([2, 1])).to eq([[[1, 'N'], [2, 'N']], 'A'])
+  end
+
+  it 'returns the same signature for two arrays containing the same (unordered) values' do
+    arr1 = [1, 2, 3]
+    arr2 = [2, 1, 3]
+
+    expect(Crimp.signature(arr1)).to eq(Crimp.signature(arr2))
+  end
+
+  it 'does not return the same signature for two arrays containing different values' do
+    arr1 = [1, 2, 3]
+    arr2 = ['1', '2', '3']
+
+    expect(Crimp.signature(arr1)).to_not eq(Crimp.signature(arr2))
+  end
+
+  it 'sorts an array with mixed strings and symbols' do
+    expect(Crimp.notation(["b", :a, "c"])).to eq 'aSbScSA'
+  end
+end
+
+describe 'Nested Arrays' do
+  it 'sorts arrays with a single nested array' do
+    expect(Crimp.notation([3, [4, 2], 1])).to eq('1N3N2N4NAA')
+  end
+
+  it 'sorts arrays with a multiple nested arrays' do
+    expect(Crimp.notation([3, [4, 2], 1, [6, 5]])).to eq('1N3N2N4NA5N6NAA')
+  end
+end
+
+describe 'Hashes' do
+  it 'handles hashes as collection of primitives' do
+    expected = [
+      [
+        [
+          [
+            ['a', 'S'],
+            ['b', 'S']
+          ],
+          'A'
+        ]
+      ],
+      'H'
+    ]
+
+    expect(Crimp.annotate({a: 'b'})).to eq(expected)
+  end
+
+  it 'sorts hashes by key and then sorts the resulting pair of tuples' do
+    expected = [
+      [
+        [
+          [
+            [1, 'N'],
+            ['e', 'S']
+          ],
+          'A'
+        ],
+        [
+          [
+            ['a', 'S'],
+            ['b', 'S']
+          ],
+          'A'
+        ],
+        [
+          [
+            ['c', 'S'],
+            ['f', 'S']
+          ],
+          'A'
+        ]
+      ],
+      'H'
+    ]
+
+    expect(Crimp.annotate({ a: 'b', f: 'c', 'e' => 1 })).to eq(expected)
+  end
+
+  it 'returns the same signature for two hashes containing the same (unordered) values' do
+    hsh1 = { a: 2, b: 1 }
+    hsh2 = { b: 1, a: 2 }
+
+    expect(Crimp.signature(hsh1)).to eq(Crimp.signature(hsh2))
+  end
+
+  it 'does not return the same signature for two hashes containing the different values' do
+    hsh1 = { a: 1, b: 2 }
+    hsh2 = { a: 2, b: 1 }
+
+    expect(Crimp.signature(hsh1)).to_not eq(Crimp.signature(hsh2))
+  end
+
+  it 'sorts an hash with mixed key types' do
+    expect(Crimp.notation({:b => "c", "d" => "a"})).to eq 'aSdSAbScSAH'
+  end
+end
+
+describe 'Sets' do
+  it 'handles sets as arrays' do
+    expect(Crimp.annotate(Set.new([1, 2]))).to eq([[[1, 'N'], [2, 'N']], 'A'])
+  end
+
+  it 'produces the same signature for Array Sets and Arrays' do
+    expect(Crimp.signature(Set.new([1, 2]))).to eq(Crimp.signature([2, 1]))
+  end
+
+  it 'handles Hash sets as arrays' do
+    expect(Crimp.annotate(Set.new({ 1 => 2 }))).to eq([[[[[1, "N"], [2, "N"]], "A"]], "A"])
+  end
+
+  it 'does NOT produce the same signature for Hash Sets and Hashes' do
+    expect(Crimp.signature(Set.new({ 1 => 2 }))).to_not eq(Crimp.signature({ 1 => 2 }))
+  end
+
+  it 'sorts sets as arrays' do
+    expect(Crimp.annotate(Set.new([2, 1]))).to eq([[[1, 'N'], [2, 'N']], 'A'])
+  end
+end
+
+describe 'nested data structures' do
+  it 'handles a hash with nested arrays and hashes' do
+    obj = { a: [1, 2], b: { c: 'd' } }
+
+    expected = [
+      [
+        [
+          [
+            [
+              [
+                [1, 'N'],
+                [2, 'N']
+              ],
+              'A'
+            ],
+            ['a', 'S']
+          ],
+          'A'
+        ],
+        [
+          [
+            ['b', 'S'],
+            [
+              [
+                [
+                  [
+                    ['c', 'S'],
+                    ['d', 'S']
+                  ],
+                  'A']
+              ],
+              'H']
+          ],
+          'A']
+      ],
+      'H'
+    ]
+
+    expect(Crimp.annotate(obj)).to eq(expected)
+  end
+
+  it 'handles an array of hashes' do
+    obj = [{ a: 1 }, { b: 2 }]
+    expected= [
+      [
+        [
+          [
+            [
+              [
+                [1, 'N'],
+                ['a', 'S']
+              ],
+              'A'
+            ]
+          ],
+          'H'
+        ],
+        [
+          [
+            [
+              [
+                [2, 'N'],
+                ['b', 'S']
+              ],
+              'A'
+            ]
+          ],
+          'H'
+        ]
+      ],
+      'A'
+    ]
+
+    expect(Crimp.annotate(obj)).to eq(expected)
+  end
+end
+
+describe 'Objects' do
+  it 'raise an error if not in the list of allowed primitives' do
+    expect { Crimp.signature(Object.new) }
+      .to raise_error(TypeError, 'Expected a (String|Number|Boolean|Nil|Hash|Array), Got Object.')
   end
 end

data/spec/spec_helper.rb

@@ -1,4 +1,3 @@
 $LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
 
-require 'pry'
 require 'crimp'

metadata

@@ -1,59 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: crimp
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - BBC News
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-13 00:00:00.000000000 Z
+date: 2018-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.5'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -67,49 +25,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec-nc
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: guard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: guard-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: pry
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -123,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: pry-remote
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -137,22 +53,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: pry-nav
+  name: deepsort
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: |
-  Shamelessly lifted from http://stackoverflow.com/questions/6461812/creating-an-md5-hash-of-a-number-string-array-or-hash-in-ruby
-  All credit should go to http://stackoverflow.com/users/394282/luke
+description: Platform agnostic MD5 hash from simple data structures made of numbers,
+  strings, booleans, nil, arrays or hashes.
 email:
 - D&ENewsFrameworksTeam@bbc.co.uk
 executables: []
@@ -163,17 +78,16 @@ files:
 - ".ruby-version"
 - ".travis.yml"
 - Gemfile
-- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - crimp.gemspec
 - lib/crimp.rb
-- lib/crimp/version.rb
-- spec/consistency_spec.rb
+- spec/acceptance_data.yml
+- spec/acceptance_spec.rb
 - spec/crimp_spec.rb
 - spec/spec_helper.rb
-homepage: ''
+homepage: https://www.bbc.co.uk/news
 licenses:
 - MIT
 metadata: {}
@@ -196,8 +110,9 @@ rubyforge_project:
 rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
-summary: Creating an md5 hash of a number, string, array, or hash in Ruby
+summary: Creates an MD5 hash from simple data structures.
 test_files:
-- spec/consistency_spec.rb
+- spec/acceptance_data.yml
+- spec/acceptance_spec.rb
 - spec/crimp_spec.rb
 - spec/spec_helper.rb

data/Guardfile

@@ -1,6 +0,0 @@
-guard 'rspec' do
-  watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/.+\.rb$})
-  watch(%r{^spec/support/(.+)\.rb$})                  { 'spec' }
-  watch('spec/spec_helper.rb')                        { 'spec' }
-end

data/lib/crimp/version.rb

@@ -1,3 +0,0 @@
-module Crimp
-  VERSION = '0.2.0'.freeze
-end

data/spec/consistency_spec.rb

@@ -1,44 +0,0 @@
-require 'spec_helper'
-
-describe Crimp do
-  describe '.signature' do
-    context 'check MD5 consistent across versions' do
-      context 'given a Hash' do
-        let(:hash) do
-          {
-            a: 123,
-            b: 1.23,
-            c: 'string',
-            d: :sym
-          }
-        end
-        let(:md5) { '1dd744d51279187cc08cabe240f98be2' }
-
-        specify { expect(subject.signature(hash)).to eq md5 }
-      end
-
-      context 'given legacy Hash' do
-        let(:hash) do
-          { a: { b: 'b', c: 'c' }, d: 'd' }
-        end
-        let(:md5) { '68d07febc4f47f56fa6ef5de063a77b1' }
-
-        specify { expect(subject.signature(hash)).to eq md5 }
-      end
-
-      context 'given an Array' do
-        let(:array) { [123, 1.23, 'string', :sym] }
-        let(:md5) { 'cd29980f258eef3faceca4f4da02ec65' }
-
-        specify { expect(subject.signature(array)).to eq md5 }
-      end
-
-      context 'given legacy Array' do
-        let(:array) { [1, 2, 3, [4, [5, 6]]] }
-        let(:md5) { '4dc4e1161c9315db0bc43c0201b3ec05' }
-
-        specify { expect(subject.signature(array)).to eq md5 }
-      end
-    end
-  end
-end