rambling-trie 0.3.4 → 0.4.0

data/lib/rambling-trie.rb

@@ -1,12 +1,22 @@
 [
   'rambling',
-  'invalid_trie_operation',
-  'children_hash_deferer',
-  'trie_compressor',
-  'trie_branches',
-  'trie_node',
-  'trie',
+  'rambling-trie/invalid_operation',
+  'rambling-trie/children_hash_deferer',
+  'rambling-trie/compressor',
+  'rambling-trie/branches',
+  'rambling-trie/node',
+  'rambling-trie/root',
   'rambling-trie/version'
 ].each do |file|
   require File.join File.dirname(__FILE__), file
 end
+
+module Rambling
+  module Trie
+    class << self
+      def create(*params)
+        Root.new *params
+      end
+    end
+  end
+end

data/lib/rambling-trie/branches.rb

@@ -0,0 +1,95 @@
+module Rambling
+  module Trie
+    # Provides the branching behavior for the Trie data structure.
+    module Branches
+      # Adds a branch to the trie based on the word.
+      # @param [String] word the word to add the branch from.
+      # @return [Node] the just added branch's root node.
+      # @raise [InvalidOperation] if the trie is already compressed.
+      def add_branch_from(word)
+        raise InvalidOperation.new('Cannot add branch to compressed trie') if compressed?
+        if word.empty?
+          @is_terminal = true
+          return
+        end
+
+        first_letter = word.slice(0).to_sym
+
+        if @children.has_key?(first_letter)
+          word.slice!(0)
+          child = @children[first_letter]
+          child.add_branch_from(word)
+          child
+        else
+          @children[first_letter] = Node.new word, self
+        end
+      end
+
+      protected
+
+      def has_uncompressed_branch_for?(chars)
+        chars.empty? or fulfills_uncompressed_condition?(:has_uncompressed_branch_for?, chars)
+      end
+
+      def has_compressed_branch_for?(chars)
+        return true if chars.empty?
+
+        first_letter = chars.slice!(0)
+        key = nil
+        @children.keys.each do |x|
+          x = x.to_s
+          if x.start_with?(first_letter)
+            key = x
+            break
+          end
+        end
+
+        unless key.nil?
+          sym_key = key.to_sym
+          return @children[sym_key].has_compressed_branch_for?(chars) if key.length == first_letter.length
+
+          while not chars.empty?
+            char = chars.slice!(0)
+
+            break unless key[first_letter.length] == char
+
+            first_letter += char
+            return true if chars.empty?
+            return @children[sym_key].has_compressed_branch_for?(chars) if key.length == first_letter.length
+          end
+        end
+
+        false
+      end
+
+      def is_uncompressed_word?(chars)
+        (chars.empty? and terminal?) or fulfills_uncompressed_condition?(:is_uncompressed_word?, chars)
+      end
+
+      def is_compressed_word?(chars)
+        return true if chars.empty? and terminal?
+
+        first_letter = ''
+        while not chars.empty?
+          first_letter += chars.slice!(0)
+          key = first_letter.to_sym
+          return @children[key].is_compressed_word?(chars) if @children.has_key?(key)
+        end
+
+        false
+      end
+
+      private
+
+      def fulfills_uncompressed_condition?(method, chars)
+        first_letter = chars.slice!(0)
+        unless first_letter.nil?
+          first_letter_sym = first_letter.to_sym
+          return @children[first_letter_sym].send(method, chars) if @children.has_key?(first_letter_sym)
+        end
+
+        false
+      end
+    end
+  end
+end

data/lib/rambling-trie/compressor.rb

@@ -0,0 +1,49 @@
+module Rambling
+  module Trie
+    # Provides the compressing behavior for the Trie data structure.
+    module Compressor
+      # Flag for compressed tries.
+      # @return [Boolean] `true` for compressed tries, `false` otherwise.
+      def compressed?
+        @parent.nil? ? false : @parent.compressed?
+      end
+
+      protected
+
+      def compress_own_tree!
+        if @children.size == 1 and not terminal? and not @letter.nil?
+          merge_with!(@children.values.first)
+          compress_own_tree!
+        end
+
+        @children.values.each { |node| node.compress_own_tree! }
+
+        self
+      end
+
+      private
+
+      def merge_with!(child)
+        new_letter = (@letter.to_s + child.letter.to_s).to_sym
+
+        rehash_on_parent!(@letter, new_letter)
+        redefine_self!(new_letter, child)
+
+        @children.values.each { |node| node.parent = self }
+      end
+
+      def rehash_on_parent!(old_letter, new_letter)
+        return if @parent.nil?
+
+        @parent.delete(old_letter)
+        @parent[new_letter] = self
+      end
+
+      def redefine_self!(new_letter, merged_node)
+        @letter = new_letter
+        @children = merged_node.children
+        @is_terminal = merged_node.terminal?
+      end
+    end
+  end
+end

data/lib/rambling-trie/invalid_operation.rb

@@ -0,0 +1,10 @@
+module Rambling
+  module Trie
+    # Raised when trying to execute an invalid operation for this Trie data structure.
+    class InvalidOperation < Exception
+      def initialize(message = nil)
+        super
+      end
+    end
+  end
+end

data/lib/rambling-trie/node.rb

@@ -0,0 +1,58 @@
+module Rambling
+  module Trie
+    # A representation of a node in the Trie data structure.
+    class Node
+      include ChildrenHashDeferer
+      include Compressor
+      include Branches
+
+      # Letter or letters corresponding to this node.
+      # @return [Symbol, nil] the corresponding letter(s) or nil.
+      attr_reader :letter
+
+      # Children nodes.
+      # @return [Hash] the children hash, consisting of :letter => node.
+      attr_reader :children
+
+      # Parent node.
+      # @return [TrieNode, nil] the parent node or nil for the root element.
+      attr_accessor :parent
+
+      # Creates a new TrieNode.
+      # @param [String] word the word from which to create this TrieNode and his branch.
+      # @param [TrieNode] parent the parent of this node.
+      def initialize(word, parent = nil)
+        @letter = nil
+        @parent = parent
+        @is_terminal = false
+        @children = {}
+
+        unless word.nil? or word.empty?
+          letter = word.slice!(0)
+          @letter = letter.to_sym unless letter.nil?
+          @is_terminal = word.empty?
+          add_branch_from(word)
+        end
+      end
+
+      # Flag for terminal nodes.
+      # @return [Boolean] `true` for terminal nodes, `false` otherwise.
+      def terminal?
+        @is_terminal
+      end
+
+      # String representation of the current node, if it is a terminal node.
+      # @return [String] the string representation of the current node.
+      # @raise [InvalidTrieOperation] if node is not terminal or is root.
+      def as_word
+        raise InvalidOperation.new() unless @letter.nil? or terminal?
+        get_letter_string
+      end
+
+      protected
+      def get_letter_string
+        (@parent.nil? ? '' : @parent.get_letter_string) + @letter.to_s
+      end
+    end
+  end
+end

data/lib/rambling-trie/root.rb

@@ -0,0 +1,58 @@
+module Rambling
+  module Trie
+    # A representation of the root node in the Trie data structure.
+    class Root < Node
+      # Creates a new Trie.
+      # @param [String, nil] filename the file to load the words from (defaults to nil).
+      def initialize(filename = nil)
+        super(nil)
+
+        @filename = filename
+        @is_compressed = false
+        add_all_nodes if filename
+      end
+
+      # Compresses the existing tree using redundant node elimination. Flags the trie as compressed.
+      # @return [Trie] same object
+      def compress!
+        unless compressed?
+          compress_own_tree!
+          @is_compressed = true
+        end
+
+        self
+      end
+
+      # Flag for compressed tries. Overrides {TrieCompressor#compressed?}.
+      # @return [Boolean] `true` for compressed tries, `false` otherwise.
+      def compressed?
+        @is_compressed = @is_compressed.nil? ? false : @is_compressed
+      end
+
+      # Checks if a path for a word or partial word exists in the trie.
+      # @param [String] word the word or partial word to look for in the trie.
+      # @return [Boolean] `true` if the word or partial word is found, `false` otherwise.
+      def has_branch_for?(word = '')
+        chars = word.chars.to_a
+        compressed? ? has_compressed_branch_for?(chars) : has_uncompressed_branch_for?(chars)
+      end
+
+      # Checks if a whole word exists in the trie.
+      # @param [String] word the word to look for in the trie.
+      # @return [Boolean] `true` only if the word is found and the last character corresponds to a terminal node.
+      def is_word?(word = '')
+        chars = word.chars.to_a
+        compressed? ? is_compressed_word?(chars) : is_uncompressed_word?(chars)
+      end
+
+      private
+      def add_all_nodes
+        File.open(@filename) do |file|
+          while word = file.gets
+            add_branch_from(word.chomp)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rambling-trie/tasks/performance.rb

@@ -1,5 +1,4 @@
 require 'benchmark'
-require 'ruby-prof'
 
 namespace :performance do
   def report(name, trie, output)
@@ -53,6 +52,8 @@ namespace :performance do
 
   desc 'Generate application profiling reports'
   task :profile do
+    require 'ruby-prof'
+
     puts 'Generating profiling reports...'
 
     rambling_trie = Rambling::Trie.new(get_path('assets', 'dictionaries', 'words_with_friends.txt'))
@@ -78,6 +79,31 @@ namespace :performance do
     puts 'Done'
   end
 
+  desc 'Generate CPU profiling reports'
+  task :cpu_profile do
+    require 'perftools'
+
+    puts 'Generating cpu profiling reports...'
+
+    rambling_trie = Rambling::Trie.new(get_path('assets', 'dictionaries', 'words_with_friends.txt'))
+    words = ['hi', 'help', 'beautiful', 'impressionism', 'anthropological']
+    methods = [:has_branch_for?, :is_word?]
+    tries = [lambda {rambling_trie.clone}, lambda {rambling_trie.clone.compress!}]
+
+    methods.each do |method|
+      tries.each do |trie_generator|
+        trie = trie_generator.call
+        result = PerfTools::CpuProfiler.start get_path('reports', "cpu_profile-#{trie.compressed? ? 'compressed' : 'uncompressed'}-#{method.to_s.sub(/\?/, '')}-#{Time.now.to_i}") do
+          words.each do |word|
+            200_000.times { trie.send(method, word) }
+          end
+        end
+      end
+    end
+
+    puts 'Done'
+  end
+
   desc 'Generate profiling and performance reports'
   task all: [:profile, :report]
 end

data/lib/rambling-trie/version.rb

@@ -1,6 +1,6 @@
 module Rambling
-  unless defined?(Rambling::Trie::VERSION)
+  module Trie
     # Current version of the rambling-trie.
-    Rambling::Trie.const_set(:VERSION, '0.3.4')
+    VERSION = '0.4.0'
   end
 end

data/rambling-trie.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require 'rambling-trie/version'
+
+Gem::Specification.new do |gem|
+  gem.authors = ['Rambling Labs']
+  gem.email = ['development@ramblinglabs.com']
+  gem.description = 'The Rambling Trie is a custom implementation of the Trie data structure with Ruby, which includes compression abilities and is designed to be very fast to traverse.'
+  gem.summary = 'A custom implementation of the trie data structure.'
+  gem.homepage = 'http://github.com/ramblinglabs/rambling-trie'
+  gem.date = Time.now.strftime('%Y-%m-%d')
+
+  gem.executables = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  gem.files = `git ls-files`.split("\n")
+  gem.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.require_paths = ['lib']
+
+  gem.name = 'rambling-trie'
+  gem.version = Rambling::Trie::VERSION
+  gem.platform = Gem::Platform::RUBY
+
+  gem.add_development_dependency 'rspec', '>=2.0.0'
+  gem.add_development_dependency 'rake', '>=0.9.2'
+  gem.add_development_dependency 'ruby-prof', '>=0.10.8'
+  gem.add_development_dependency 'yard', '>=0.7.5'
+  gem.add_development_dependency 'redcarpet', '>=2.1.0'
+end

data/spec/assets/test_words.txt

@@ -0,0 +1,23 @@
+are
+beautiful
+course
+false
+hello
+hi
+is
+it
+mine
+my
+no
+of
+ours
+today
+true
+truth
+whatever
+where
+who
+yeah
+you
+your
+yours

data/spec/lib/rambling-trie/node_spec.rb

@@ -0,0 +1,202 @@
+require 'spec_helper'
+
+module Rambling
+  module Trie
+    describe Node do
+      describe '.new' do
+        context 'with no letters' do
+          let(:node) { Node.new '' }
+
+          it 'does not have any letter' do
+            node.letter.should be_nil
+          end
+
+          it 'includes no children' do
+            node.should have(0).children
+          end
+
+          it 'is not a terminal node' do
+            node.should_not be_terminal
+          end
+
+          it 'returns empty string as its word' do
+            node.as_word.should be_empty
+          end
+
+          it 'is not compressed' do
+            node.should_not be_compressed
+          end
+        end
+
+        context 'with one letter' do
+          let(:node) { Node.new 'a' }
+
+          it 'makes it the node letter' do
+            node.letter.should == :a
+          end
+
+          it 'includes no children' do
+            node.should have(0).children
+          end
+
+          it 'is a terminal node' do
+            node.should be_terminal
+          end
+        end
+
+        context 'with two letters' do
+          let(:node) { Node.new 'ba' }
+
+          it 'takes the first as the node letter' do
+            node.letter.should == :b
+          end
+
+          it 'includes one child' do
+            node.should have(1).children
+          end
+
+          it 'includes a child with the expected letter' do
+            node.children.values.first.letter.should == :a
+          end
+
+          it 'has the expected letter as a key' do
+            node.has_key?(:a).should be_true
+          end
+
+          it 'returns the child corresponding to the key' do
+            node[:a].should == node.children[:a]
+          end
+
+          it 'does not mark itself as a terminal node' do
+            node.should_not be_terminal
+          end
+
+          it 'marks the first child as a terminal node' do
+            node[:a].should be_terminal
+          end
+        end
+
+        context 'with a large word' do
+          let(:node) { Node.new 'spaghetti' }
+
+          it 'marks the last letter as terminal node' do
+            node[:p][:a][:g][:h][:e][:t][:t][:i].should be_terminal
+          end
+
+          it 'does not mark any other letter as terminal node' do
+            node[:p][:a][:g][:h][:e][:t][:t].should_not be_terminal
+            node[:p][:a][:g][:h][:e][:t].should_not be_terminal
+            node[:p][:a][:g][:h][:e].should_not be_terminal
+            node[:p][:a][:g][:h].should_not be_terminal
+            node[:p][:a][:g].should_not be_terminal
+            node[:p][:a].should_not be_terminal
+            node[:p].should_not be_terminal
+          end
+        end
+      end
+
+      describe '#add_branch_from' do
+        context 'new word for existing branch' do
+          let(:node) { Node.new 'back' }
+
+          before :each do
+            node.add_branch_from 'a'
+          end
+
+          it 'does not increment the child count' do
+            node.should have(1).children
+          end
+
+          it 'marks it as terminal' do
+            node[:a].should be_terminal
+          end
+        end
+
+        context 'old word for existing branch' do
+          let(:node) { Node.new 'back' }
+
+          before :each do
+            node.add_branch_from 'ack'
+          end
+
+          it 'does not increment any child count' do
+            node.should have(1).children
+            node[:a].should have(1).children
+            node[:a][:c].should have(1).children
+            node[:a][:c][:k].should have(0).children
+          end
+        end
+      end
+
+      describe '#as_word' do
+        context 'for an empty node' do
+          let(:node) { Node.new '' }
+
+          it 'returns nil' do
+            node.as_word.should be_empty
+          end
+        end
+
+        context 'for one letter' do
+          let(:node) { Node.new 'a' }
+
+          it 'returns the expected one letter word' do
+            node.as_word.should == 'a'
+          end
+        end
+
+        context 'for a small word' do
+          let(:node) { Node.new 'all' }
+
+          it 'returns the expected small word' do
+            node[:l][:l].as_word.should == 'all'
+          end
+
+          it 'raises an error for a non terminal node' do
+            lambda { node[:l].as_word }.should raise_error(InvalidOperation)
+          end
+        end
+
+        context 'for a long word' do
+          let(:node) { Node.new 'beautiful' }
+
+          it 'returns the expected long word' do
+            node[:e][:a][:u][:t][:i][:f][:u][:l].as_word.should == 'beautiful'
+          end
+        end
+
+        context 'for a node with nil letter' do
+          let(:node) { Node.new nil }
+          it 'returns nil' do
+            node.as_word.should be_empty
+          end
+        end
+      end
+
+      describe '#compressed?' do
+        let(:root) { double('Root') }
+        let(:node) { Node.new '', root }
+
+        context 'parent is compressed' do
+          before :each do
+            root.stub(:compressed?).and_return true
+          end
+
+          it 'returns true' do
+            node.should be_compressed
+          end
+        end
+
+        context 'parent is not compressed' do
+          before :each do
+            root.stub(:compressed?).and_return false
+          end
+
+          it 'returns false' do
+            node.compressed?.should be_false
+          end
+        end
+      end
+    end
+  end
+end