gaddag 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 99e393cc0cfea04c5b5f46c757d30d0081b0985e
+  data.tar.gz: 505ae94f2907cbe881f5684ac06d6e25bac72ed6
+SHA512:
+  metadata.gz: 2871a06741e0ec9d9c5a8dc634d12a5877bc4049c6be0838fd28744383a12d2a659e800b2f01f4b003fd0e92f1d55ea16f3b12df68cfeb5e4454b07ea7da5457
+  data.tar.gz: a126efac0f8a4533485a690399db473ec1b0756c2c6b6185ca53650489f001fa123a33c5724f50afc474eb454ff16dcb36de5b91318e67ee12239a53fe2472cb

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+doc
+.yardoc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--order random

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p353

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Thomas Brus
+
+MIT License
+
+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,38 @@
+# GADDAG data structure in Ruby
+
+A [GADDAG](http://en.wikipedia.org/wiki/GADDAG) is a data structure that
+allows for fast lookup of words by substring. It is a directed acyclic graph, where
+each word can be constructed from the root via any of its reversed prefixes. Its main application
+is move generation in Scrabble. The data structure is explained in more detail in
+[the original research paper](http://www.ericsink.com/downloads/faster-scrabble-gordon.pdf).
+
+## Usage
+
+Initializing the GADDAG is simple:
+
+```ruby
+require 'gaddag'
+gaddag = GADDAG.new
+```
+
+Adding words is done via the `add` method. This will expand the graph with paths for all
+the reversed prefixes of the word. Note that this may take some time when adding
+a large number of words.
+
+```ruby
+IO.foreach('/usr/share/dict/words').map(&:chomp).each do |word|
+  if word.length == 10
+    gaddag.add(word) # => #<Gaddag:0x007fc6c24367b0 ... >
+  end
+end
+```
+
+In order to find all words that contain a given substring, use the `find` method:
+
+```ruby
+gaddag.find('elevi') => # ["televiewer", "television", "televisual"]
+```
+
+## License
+
+See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/gaddag.gemspec

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+Gem::Specification.new do |spec|
+  spec.name          = 'gaddag'
+  spec.version       = '0.1.1'
+  spec.authors       = ['Thomas Brus']
+  spec.email         = ['thomas.brus@me.com']
+  spec.summary       = %q{Implementation of the GADDAG data structure}
+  spec.homepage      = 'https://github.com/thomasbrus/gaddag'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  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.add_dependency 'equalizer', '~> 0.0.9'
+
+  spec.add_development_dependency 'bundler', '~> 1.5.1'
+
+  spec.add_development_dependency 'yard', '~> 0.8.7'
+  spec.add_development_dependency 'inch', '~> 0.4.5'
+
+  spec.add_development_dependency 'rspec', '~> 2.14.1'
+
+  spec.add_development_dependency 'mutant', '~> 0.5.11'
+  spec.add_development_dependency 'mutant-rspec', '~> 0.5.10'
+
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'pry'
+end

data/lib/gaddag.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+require 'equalizer'
+
+require_relative 'gaddag/arc'
+require_relative 'gaddag/node'
+require_relative 'gaddag/path'
+require_relative 'gaddag/word'
+
+# Implementation of the GADDAG data structure
+class GADDAG
+  # The root node
+  attr_reader :root
+
+  # Initializes a GADDAG
+  # @return [GADDAG]
+  def initialize
+    @root = Node.new
+  end
+
+  # Adds a word to the GADDAG
+  # @param word [String] the word to be added
+  # @return [GADDAG] the GADDAG instance
+  def add(word)
+    @root.create_final_path(word.chars.reverse + [Path::DELIMITER])
+
+    Word.new(word.chars).to_delimited_paths.each do |path|
+      @root.create_final_path(path.letters)
+    end
+
+    self
+  end
+
+  # Finds all words that contain the given substring
+  # @param substring [String] the substring to search for
+  # @return [Array<String>] all matching words
+  def find(substring)
+    first_letter, second_letter, *last_letters = *substring.chars
+    return [] unless @root.path?(last_letters.reverse)
+
+    @root.follow_path(last_letters.reverse).final_paths.select do |path|
+      path.start_with?([second_letter, first_letter])
+    end.map do |path|
+      Path.new(last_letters.reverse + path).to_word.to_s
+    end.uniq
+  end
+end

data/lib/gaddag/arc.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+require 'set'
+
+class GADDAG
+
+  # Represents an arc pointing to a destination node with optional final letters
+  class Arc
+    # The destination node
+    attr_reader :destination
+
+    # A set of letters which form a word after being appended to the letter path
+    attr_reader :final_letters
+
+    # Two arcs are equal if they point to the same destination node and contain
+    # the same set of final letters
+    send :include, Equalizer.new(:destination, :final_letters)
+
+    # Initializes a GADDAG arc
+    # @param destination [Node] the destination node
+    # @return [Arc]
+    def initialize(destination)
+      @destination = destination
+      @final_letters = Set.new
+    end
+
+    # Adds a final letter to the arc. A final letter is a letter that,
+    # when appended to the letter path, forms a valid word.
+    # @param letter [String] the letter that is to be marked as final
+    def add_final_letter(letter)
+      @final_letters.add(letter)
+    end
+
+    # Returns all paths starting at this arc that are final
+    # @return [Array<Path>] a list of final paths that start at this arc
+    def final_paths
+      final_letters.map { |fl| Path.new([fl]) } + destination.final_paths
+    end
+  end
+
+end

data/lib/gaddag/node.rb

@@ -0,0 +1,115 @@
+# encoding: utf-8
+
+class GADDAG
+
+  # Represents a node in the GADDAG data structure
+  class Node
+    # A mapping of letters to arcs
+    attr_reader :outgoing_arcs
+
+    # Two nodes are equal if they have the same set of outgoing arcs
+    send :include, Equalizer.new(:outgoing_arcs)
+
+    # Initializes a GADDAG node
+    # @return [Node]
+    def initialize
+      @outgoing_arcs = {}
+    end
+
+    # Creates an outgoing arc for a letter to a destination node
+    # @param letter [String] the letter to be added to the path when this
+    # arc is followed
+    # @param destination [Node] the node to which this arc should point
+    # @return [Arc] the newly created arc or an existing arc if one already
+    #   exists for this letter
+    def create_arc(letter, destination = Node.new)
+      @outgoing_arcs[letter.to_sym] ||= Arc.new(destination)
+    end
+
+    # Checks whether an outgoing arc for the given letter exists
+    # @param letter [String] the letter to check for
+    # @return [Boolean] whether the outgoing arc exists
+    def arc?(letter)
+      @outgoing_arcs.key?(letter.to_sym)
+    end
+
+    # Creates a final outgoing arc for a letter to a destination node. Effectively
+    # this will add a final letter to the outgoing arc, indicating that a valid
+    # word can be formed with it.
+    # @see #create_arc
+    def create_final_arc(letter, final_letter, destination = Node.new)
+      create_arc(letter, destination).tap { |arc| arc.add_final_letter(final_letter) }
+    end
+
+    # Creates a path for a list of letters and optional destination nodes
+    # @param letters [Array<String>] the letters for which the path should be build
+    # @param destinations [Array<Node>] the destination nodes which the path should visit
+    # @return [Node] the lastly created destination ode
+    def create_path(letters, destinations = [])
+      letters.zip(destinations).inject(self) do |node, (letter, destination)|
+        node.create_arc(letter, destination || Node.new).destination
+      end
+    end
+
+    # Checks whether a path exists for the given list of letters
+    # @param letters [Array<String>] the letter path to check for
+    # @return [Boolean] whether the path exists
+    def path?(letters)
+      return true if letters.empty?
+      return false unless arc?(letters.first)
+      follow_arc(letters.first).path?(letters[1..-1])
+    end
+
+    # Creates a path for a list of letters and optional destination nodes,
+    # ommiting the last node, and marking the last letter as final
+    # @see #create_path
+    def create_final_path(letters, destinations = [])
+      *initial_letters, second_last_letter, last_letter = *letters
+      second_last_node = create_path(initial_letters, destinations)
+
+      (destinations[initial_letters.length] || Node.new).tap do |final_destination|
+        second_last_node.create_final_arc(second_last_letter, last_letter, final_destination)
+      end
+    end
+
+    # Checks whether a final path exists for the given list of letters
+    # @param letters [Array<String>] the letter path to check for
+    # @return [Boolean] whether the final path exists
+    def final_path?(letters)
+      *initial_letters, second_last_letter, last_letter = *letters
+
+      path?(initial_letters) && follow_path(initial_letters).final_paths.any? do |path|
+        path == Path.new([second_last_letter, last_letter])
+      end
+    end
+
+    # Follows a single outgoing arc for a given letter
+    # @param letter [String] the letter that should be followed
+    # @raise [KeyError] if no outgoing arc exists for the given letter
+    # @return [Node] the destination node that the arc for this letter leads to
+    def follow_arc(letter)
+      @outgoing_arcs.fetch(letter.to_sym).destination
+    end
+
+    # Recursively follows a list of letters
+    # @param letters [Array<String>] the letters to be followed
+    # @raise [KeyError] if an outgoing arc does not exist for a given letter
+    #   at the corresponding node
+    # @return [Node] the destination node that the path of letters leads to
+    def follow_path(letters)
+      return self if letters.empty?
+      follow_arc(letters[0]).follow_path(letters[1..-1])
+    end
+
+    # Returns all paths from this node that are final. The set of final paths are
+    # all paths for which the last arc includes a final letter. For each final letter
+    # a seperate path is created.
+    # @return [Array<Path>] a list of final paths
+    def final_paths
+      @outgoing_arcs.reduce([]) do |paths, (letter_sym, arc)|
+        paths += arc.final_paths.map { |path| Path.new([letter_sym.to_s] + path) }
+      end
+    end
+  end
+
+end

data/lib/gaddag/path.rb

@@ -0,0 +1,72 @@
+# encoding: utf-8
+
+class GADDAG
+
+  # Represents a (final) path within the GADDAG data structure
+  class Path
+    # The letters that make up this GADDAG path
+    attr_reader :letters
+
+    # Two paths are equal if they contain the same letters in the same order
+    send :include, Equalizer.new(:letters)
+
+    # The path delimiter that seperates the reversed prefix and the suffix
+    DELIMITER = '♢'.freeze
+
+    # Initializes a GADDAG path
+    # @param letters [Array<String>] a list of letters, containing a reversed prefix,
+    # a delimiter, and an optional suffix: REV(PREFIX) ♢ SUFFIX
+    # @return [Path]
+    def initialize(letters)
+      @letters = letters
+    end
+
+    # Returns the reversed prefix of this path
+    # @return [Array<String>] the first portion of this path: the reversed prefix
+    def reversed_prefix_letters
+      return [] if @letters.empty?
+      @letters.join.split(DELIMITER).first.chars
+    end
+
+    # Returns the suffix of this path
+    # @return [Array<String>] the last portion of this path: the suffix
+    def suffix_letters
+      return [] if !include_delimiter? || @letters.last == DELIMITER
+      @letters.join.split(DELIMITER).last.chars
+    end
+
+    # Tells whether the path includes {GADDAG::DELIMITER}
+    # @return [Boolean] whether this path includes the delimiter
+    def include_delimiter?
+      @letters.include?(DELIMITER)
+    end
+
+    # Returns a string presentation of this path
+    # @return the string represtentation, letters are delimited with '>'
+    def to_s
+      @letters.join(' > ')
+    end
+
+    # Coerces into an Array.
+    # @example
+    #   ['K', 'E'] + Path.new(%w(A R B)) # => ['K', 'E', 'A', 'R', 'B']
+    # @return [Array<String>] the letters in this path
+    def to_ary
+      @letters
+    end
+
+    # Tells whether the path starts with the given letters
+    # @param letters [Array<String>] the letters to check for
+    # @return [Boolean] whether the path starts with the letters given
+    def start_with?(letters)
+      @letters.join.start_with?(letters.join)
+    end
+
+    # Constructs a word from the partially reversed letter path
+    # @return [Word] the word that is encoded within this path
+    def to_word
+      Word.new(reversed_prefix_letters.reverse + suffix_letters)
+    end
+  end
+
+end

data/lib/gaddag/word.rb

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+class GADDAG
+
+  # Represents a word in the GADDAG data structure
+  class Word
+    # The letters that make up this word
+    attr_reader :letters
+
+    # Two words are equal if they contain the same letters in the same order
+    send :include, Equalizer.new(:letters)
+
+    # Initializes a GADDAG word
+    # @param letters [Array<String>] an ordered list of letters of which
+    # the word consists
+    # @return [Word]
+    def initialize(letters)
+      @letters = letters
+    end
+
+    # Returns the word as string
+    # @return a string representation of the word
+    def to_s
+      @letters.join
+    end
+
+    # Constructs a list of delimited GADDAG paths from this word
+    # @return [Array<Path>] a list of paths, each containing a reversed prefix,
+    # a delimiter, and a suffix: REV(PREFIX) ♢ SUFFIX
+    def to_delimited_paths
+      1.upto(letters.length - 1).map do |index|
+        reversed_prefix = @letters.slice(0, index).reverse
+        suffix = @letters.slice(index, @letters.count)
+        Path.new(reversed_prefix + [Path::DELIMITER] + suffix)
+      end
+    end
+  end
+
+end

data/spec/shared/unit/gaddag/arc_context.rb

@@ -0,0 +1,6 @@
+# encoding: utf-8
+
+shared_context 'GADDAG::Arc/context' do
+  subject { GADDAG::Arc.new(destination) }
+  let(:destination) { GADDAG::Node.new }
+end