wordhash 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bafbadf27d8434cf3cc4f76759abf5cdcea16c9c
+  data.tar.gz: 7147720cbd69eadcefdfe6cc3cdbedcf1c339bdb
+SHA512:
+  metadata.gz: 1a575fd75b4116782b6318fff4eaab149f618660e29f383bb75ae7ca236a605ad5a77e9dfcc62d683d9abfea8e70bd1cb33f21a43316488824d3125aa3330ff2
+  data.tar.gz: 4dc26aa7779d1c85160f0f0079aa7f2b2aba1a7a882568eab772d90d3253bb359d12b2a759e59eb93373b8f28a2b1874ffb9d176fe09e63ad0f7398b87c83b52

data/LICENCE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2015 Louis Pilfold. All Rights Reserved.
+
+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 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

@@ -0,0 +1,70 @@
+# wordhash
+
+[![Build Status](https://travis-ci.org/lpil/wordhash.svg?branch=master)](https://travis-ci.org/lpil/humanhash.rb)
+[![Code Climate](https://codeclimate.com/github/lpil/wordhash/badges/gpa.svg)](https://codeclimate.com/github/lpil/humanhash.rb)
+
+wordhash provides human-readable representations of digests.  
+A clone of Zachary Voase's
+[humanhash](https://github.com/zacharyvoase/humanhash).
+
+## Example
+
+```ruby
+require 'word_hash'
+
+digest = '7528880a986c40e78c38115e640da2a1'
+# => "7528880a986c40e78c38115e640da2a1"
+
+WordHash.new.humanize digest
+# => "three-georgia-xray-jig"
+WordHash.new.humanize digest, 6
+# => "high-mango-white-oregon-purple-charlie"
+
+WordHash.new.uuid
+# => ["04edcd5325a34dc191d4880676ebae61", "lemon-artist-snake-gee"]
+```
+
+## Caveats
+
+Don't store the humanhash output, as its statistical uniqueness is only around
+1 in 4.3 billion. Its intended use is as a human-readable (and, most
+importantly, memorable) representation of a longer digest, unique enough for
+display in a user interface, where a user may need to remember or verbally
+communicate the identity of a hash, without having to remember a 40-character
+hexadecimal sequence. Nevertheless, you should keep original digests around,
+then pass them through humanize() only as you're displaying them.
+
+## How It Works
+
+The procedure for generating a humanhash involves compressing the input to a
+fixed length (default: 4 bytes), then mapping each of these bytes to a word in
+a pre-defined wordlist (a default wordlist is supplied with the library). This
+algorithm is consistent, so the same input, given the same wordlist, will
+always give the same output. You can also use your own wordlist, and specify a
+different number of words for output.
+
+(The algorithm and this text are completely lifted from Zachary's version)
+
+## Licence
+
+```
+Copyright © 2015 Louis Pilfold. All Rights Reserved.
+
+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 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/lib/word_hash.rb

@@ -0,0 +1,108 @@
+require 'securerandom'
+
+# Transforms hex digests to human-readable strings.
+#
+# The format of these strings will look something like:
+# `victor-bacon-zulu-lima`. The output is obtained by compressing the input
+# digest to a fixed number of bytes, then mapping those bytes to one of 256
+# words. A default wordlist is provided, but you can override this if you
+# prefer.
+#
+# As long as you use the same wordlist, the output will be consistent (i.e.
+# the same digest will always render the same representation).
+class WordHash
+  attr_reader :wordlist
+
+  DEFAULT_WORDLIST = %w(
+    ack alabama alanine alaska alpha angel apart april arizona arkansas artist
+    asparagus aspen august autumn avocado bacon bakerloo batman beer berlin
+    beryllium black blossom blue bluebird bravo bulldog burger butter
+    california carbon cardinal carolina carpet cat ceiling charlie chicken
+    coffee cola cold colorado comet connecticut crazy cup dakota december
+    delaware delta diet don double early earth east echo edward eight eighteen
+    eleven emma enemy equal failed fanta fifteen fillet finch fish five fix
+    floor florida football four fourteen foxtrot freddie friend fruit gee
+    georgia glucose golf green grey hamper happy harry hawaii helium high hot
+    hotel hydrogen idaho illinois india indigo ink iowa island item jersey jig
+    johnny juliet july jupiter kansas kentucky kilo king kitten lactose lake
+    lamp lemon leopard lima lion lithium london louisiana low magazine
+    magnesium maine mango march mars maryland massachusetts may mexico michigan
+    mike minnesota mirror mississippi missouri mobile mockingbird monkey
+    montana moon mountain muppet music nebraska neptune network nevada nine
+    nineteen nitrogen north november nuts october ohio oklahoma one orange
+    oranges oregon oscar oven oxygen papa paris pasta pennsylvania pip pizza
+    pluto potato princess purple quebec queen quiet red river robert robin
+    romeo rugby sad salami saturn september seven seventeen shade sierra single
+    sink six sixteen skylark snake social sodium solar south spaghetti speaker
+    spring stairway steak stream summer sweet table tango ten tennessee tennis
+    texas thirteen three timing triple twelve twenty two uncle undress uniform
+    uranus utah vegan venus vermont victor video violet virginia washington
+    west whiskey white william winner winter wisconsin wolfram wyoming xray
+    yankee yellow zebra zulu
+  )
+
+  def initialize(wordlist = DEFAULT_WORDLIST)
+    fail ArgumentError, 'Wordlist must have exactly 256 items' unless
+      wordlist.length == 256
+
+    @wordlist = wordlist
+  end
+
+
+  # Compress a list of byte values to a fixed target length.
+  #
+  # Attempting to compress a smaller number of bytes to a larger
+  # number is an error
+  def compress(bytes, target)
+    fail ArgumentError, 'Fewer input bytes than requested output' if
+      target > bytes.size
+
+    slices = slice_bytes bytes, target
+
+    # XOR checksum-like compression
+    slices.map do |slice|
+      slice.reduce :^
+    end
+  end
+
+  # Humanize a given hexadecimal digest.
+  #
+  # Change the number of words output by specifying `words`. Change the
+  # word separator with `separator`.
+  def humanize(hexdigest, words = 4, separator = '-')
+    bytes = hexdigest.split('')
+                     .each_slice(2).to_a
+    bytes.pop if bytes.last.size == 1
+
+    bytes = bytes.map { |byte| byte.join('').to_i 16 }
+
+    wordify_bytes(bytes, words, separator)
+  end
+
+  # Generate a UUID with a human-readable representation.
+  #
+  # Returns `[human_repr, full_digest]`.
+  # Accepts the same keyword arguments as `humanize`
+  def uuid(*args)
+    digest = SecureRandom.uuid.delete '-'
+    word_hash = humanize digest, *args
+    [digest, word_hash]
+  end
+
+  private
+
+  def wordify_bytes(bytes, words, separator)
+    compress(bytes, words).map { |byte| wordlist[byte] }
+                          .join separator
+  end
+
+  def slice_bytes(bytes, target)
+    slice_size = bytes.size / target
+    slices = bytes.each_slice(slice_size).to_a
+
+    # Catch any left-over bytes in the last segment.
+    extra = slices.pop(slices.size - target).flatten
+    slices.last.concat extra unless extra.empty?
+    slices
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require_relative '../lib/human_hash'

data/spec/word_hash_spec.rb

@@ -0,0 +1,81 @@
+require_relative 'spec_helper'
+
+describe WordHash do
+  describe '#initialize' do
+    it 'requires a wordlist of length 256' do
+      expect { WordHash.new Array.new(255, 'word') }
+        .to raise_error ArgumentError
+
+      expect { WordHash.new Array.new(257, 'word') }
+        .to raise_error ArgumentError
+
+      expect { WordHash.new Array.new(256, 'word') }
+        .not_to raise_error
+    end
+
+    it 'will initialize with no args to use a default' do
+      expect { WordHash.new }.not_to raise_error
+    end
+  end
+
+  describe '#compress' do
+    it 'requires a byte list longer than the target length' do
+      expect { WordHash.new.compress [1, 2, 3], 4 }
+        .to raise_error ArgumentError
+    end
+
+    it do
+      bytes = [96, 173, 141, 13, 135, 27, 96, 149, 128, 130, 151]
+      expect(WordHash.new.compress bytes, 4).to eq [205, 128, 156, 96]
+    end
+
+    it do
+      bytes = [96, 173, 141, 13, 135, 27, 96, 149, 128, 130, 151]
+      expect(WordHash.new.compress bytes, 2).to eq [202, 123]
+    end
+
+    it do
+      bytes = [96, 173, 141, 13, 135, 27, 96, 149, 128, 130, 151]
+      expect(WordHash.new.compress bytes, 8)
+        .to eq [96, 173, 141, 13, 135, 27, 96, 0]
+    end
+
+    it do
+      bytes = [96, 173, 141, 13, 135, 149, 128, 130, 151]
+      expect(WordHash.new.compress bytes, 3).to eq [64, 31, 149]
+    end
+  end
+
+  describe '#humanize' do
+    it 'humanizes' do
+      digest = '60ad8d0d871b6095808297'
+      expect(WordHash.new.humanize digest)
+        .to eq 'sodium-magnesium-nineteen-hydrogen'
+    end
+
+    it do
+      expect(WordHash.new.humanize '60ad8d0d871b60958082971')
+        .to eq 'sodium-magnesium-nineteen-hydrogen'
+    end
+
+    it do
+      expect(WordHash.new.humanize '295734958734589739587')
+        .to eq 'low-october-princess-pennsylvania'
+    end
+
+    it do
+      expect(WordHash.new.humanize '2398532498572856792989')
+        .to eq 'robin-lemon-south-oregon'
+    end
+
+    it do
+      expect(WordHash.new.humanize '205934859384566493698')
+        .to eq 'lima-pluto-blossom-six'
+    end
+
+    it do
+      expect(WordHash.new.humanize '298234859234895734895389')
+        .to eq 'november-cat-vegan-georgia'
+    end
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: wordhash
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Louis Pilfold
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.28'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.28'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+description: |2-
+
+  wordhash: Human-readable representations of digests.
+
+  A clone of Zachary Voase's humanhash.
+email: louis@lpil.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENCE
+- README.md
+- lib/word_hash.rb
+- spec/spec_helper.rb
+- spec/word_hash_spec.rb
+homepage: http://github.com/lpil/wordhash
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Human-readable representations of digests
+test_files:
+- spec/spec_helper.rb
+- spec/word_hash_spec.rb