rambling-trie 0.3.2 → 0.3.3

data/README.markdown

@@ -37,25 +37,25 @@ trie = Rambling::Trie.new
 You can also provide a file which contains all the words to be added to the trie, and it will read the file and create the structure for you, like this:
 
 ``` ruby
-trie = Rambling::Trie.new('/path/to/file')
+trie = Rambling::Trie.new '/path/to/file'
 ```
 
 To add new words to the trie, use `add_branch_from`:
 
 ``` ruby
-trie.add_branch_from('word')
+trie.add_branch_from 'word'
 ```
 
 And to find out if a word already exists in the trie, use `is_word?`:
 
 ``` ruby
-trie.is_word?('word')
+trie.is_word? 'word'
 ```
 
-If you wish to find if part of a word exists in the `Rambling::Trie` instance, you should call `has_branch_from?`:
+If you wish to find if part of a word exists in the `Rambling::Trie` instance, you should call `has_branch_for?`:
 
 ``` ruby
-trie.has_branch_from?('partial_word')
+trie.has_branch_for? 'partial_word'
 ```
 
 ### Compression
@@ -80,6 +80,10 @@ You can find out if a `Rambling::Trie` instance is compressed by calling the `co
 trie.compressed?
 ```
 
+## Further Documentation
+
+You can find further API documentation on the autogenerated [RubyDoc.info](http://rubydoc.info/gems/rambling-trie/0.3.3/Rambling)
+
 ## Compatible Ruby and Rails versions
 
 The Rambling Trie has been tested with the following Ruby versions:

data/lib/children_hash_deferer.rb

@@ -1,17 +1,31 @@
 module Rambling
+  # Provides some proxy methods to the children's hash for readability.
   module ChildrenHashDeferer
+    # Proxies to @children[key]
+    # @param [Symbol] key the key to look for in the children's hash.
+    # @return [TrieNode, nil] the child node with that key or nil.
     def [](key)
       @children[key]
     end
 
+    # Proxies to @children[key] = value.
+    # @param [Symbol] key the to add or change the value for.
+    # @param [TrieNode] value the node to add to the children's hash.
+    # @return [TrieNode, nil] the child node with that key or nil.
     def []=(key, value)
       @children[key] = value
     end
 
+    # Proxies to @children.delete(key)
+    # @param [Symbol] key the key to delete in the children's hash.
+    # @return [TrieNode, nil] the child node corresponding to the key just deleted or nil.
     def delete(key)
       @children.delete(key)
     end
 
+    # Proxies to @children.has_key?(key)
+    # @param [Symbol] key the key to look for in the children's hash.
+    # @return [Boolean] `true` for the keys that exist in the children's hash, false otherwise.
     def has_key?(key)
       @children.has_key?(key)
     end

data/lib/invalid_trie_operation.rb

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

data/lib/rambling-trie.rb

@@ -1,7 +1,8 @@
+require File.join(File.dirname(__FILE__), 'rambling.rb')
 require File.join(File.dirname(__FILE__), 'invalid_trie_operation.rb')
 require File.join(File.dirname(__FILE__), 'children_hash_deferer.rb')
 require File.join(File.dirname(__FILE__), 'trie_compressor.rb')
 require File.join(File.dirname(__FILE__), 'trie_branches.rb')
 require File.join(File.dirname(__FILE__), 'trie_node.rb')
 require File.join(File.dirname(__FILE__), 'trie.rb')
-
+require File.join(File.dirname(__FILE__), 'rambling-trie', 'version.rb')

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

@@ -0,0 +1,17 @@
+namespace :gem do
+  task :build do
+    desc 'Build the rambling-trie gem'
+    system 'gem build rambling-trie.gemspec'
+  end
+
+  task release: :build do
+    desc 'Push the latest version of the rambling-trie gem'
+    system "gem push rambling-trie-#{Rambling::Trie::VERSION}.gem"
+  end
+
+  task :version do
+    desc 'Output the current rambling-trie version'
+    puts "rambling-trie #{Rambling::Trie::VERSION}"
+  end
+end
+

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

@@ -0,0 +1,79 @@
+require 'benchmark'
+require 'ruby-prof'
+
+namespace :performance do
+  def report(name, trie, output)
+    words = ['hi', 'help', 'beautiful', 'impressionism', 'anthropological']
+    methods = [:is_word?, :has_branch_for?]
+
+    output.puts "==> #{name}"
+    methods.each do |method|
+      output.puts "`#{method}`:"
+      words.each do |word|
+        output.print "#{word} - #{trie.send(method, word)}".ljust(30)
+        output.puts Benchmark.measure { 200_000.times {trie.send(method, word) }}
+      end
+    end
+  end
+
+  def generate_report(filename = nil)
+    output = filename.nil? ? $stdout : File.open(filename, 'a+')
+
+    trie = Rambling::Trie.new(get_path('assets', 'dictionaries', 'words_with_friends.txt'))
+
+    output.puts "\nReport for rambling-trie version #{Rambling::Trie::VERSION}"
+    report('Uncompressed', trie, output)
+
+    return unless trie.respond_to?(:compress!)
+
+    trie.compress!
+    report('Compressed', trie, output)
+
+    output.close
+  end
+
+  def get_path(*filename)
+    File.join(File.dirname(__FILE__), '..', '..', '..', *filename)
+  end
+
+  task :report do
+    puts 'Generating performance report...'
+    generate_report
+  end
+
+  namespace :report do
+    task :save do
+      puts 'Generating performance report...'
+      generate_report(get_path('reports', 'performance'))
+      puts 'Report has been saved to reports/performance'
+    end
+  end
+
+  task :profile do
+    puts 'Generating 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.compress!}]#lambda {rambling_trie}, lambda {rambling_trie.compress!}]
+
+    methods.each do |method|
+      tries.each do |trie_generator|
+        trie = trie_generator.call
+        result = RubyProf.profile do
+          words.each do |word|
+            200_000.times { trie.send(method, word) }
+          end
+        end
+
+        File.open get_path('reports', "profile-#{trie.compressed? ? 'compressed' : 'uncompressed'}-#{method.to_s.sub(/\?/, '')}-#{Time.now.to_i}"), 'w' do |file|
+          RubyProf::CallTreePrinter.new(result).print(file)
+        end
+      end
+    end
+
+    puts 'Done'
+  end
+
+  task all: [:profile, :report]
+end

data/lib/rambling-trie/version.rb

@@ -0,0 +1,8 @@
+module Rambling
+  class Trie
+    unless defined?(Rambling::Trie::VERSION)
+      # Current version of the rambling-trie.
+      VERSION = '0.3.3'
+    end
+  end
+end

data/lib/rambling.rb

@@ -0,0 +1,3 @@
+# Entry point for the rambling-trie. General Namespace.
+module Rambling
+end

data/lib/trie.rb

@@ -1,5 +1,8 @@
 module Rambling
+  # A representation of the root node in the Trie data structure.
   class Trie < TrieNode
+    # Creates a new Trie.
+    # @param [String, nil] filename the file to load the words from (defaults to nil).
     def initialize(filename = nil)
       super(nil)
 
@@ -8,6 +11,8 @@ module Rambling
       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!
@@ -17,16 +22,26 @@ module Rambling
       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 = '')
-      compressed? ? has_compressed_branch_for?(word) : has_uncompressed_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 = '')
-      compressed? ? is_compressed_word?(word) : is_uncompressed_word?(word)
+      chars = word.chars.to_a
+      compressed? ? is_compressed_word?(chars) : is_uncompressed_word?(chars)
     end
 
     private

data/lib/trie_branches.rb

@@ -1,5 +1,10 @@
 module Rambling
+  # Provides the branching behavior for the Trie data structure.
   module TrieBranches
+    # Adds a branch to the trie based on the word.
+    # @param [String] word the word to add the branch from.
+    # @return [TrieNode] the just added branch's root node.
+    # @raise [InvalidTrieOperation] if the trie is already compressed.
     def add_branch_from(word)
       raise InvalidTrieOperation.new('Cannot add branch to compressed trie') if compressed?
       if word.empty?
@@ -11,7 +16,9 @@ module Rambling
 
       if @children.has_key?(first_letter)
         word.slice!(0)
-        @children[first_letter].add_branch_from(word)
+        child = @children[first_letter]
+        child.add_branch_from(word)
+        child
       else
         @children[first_letter] = TrieNode.new(word, self)
       end
@@ -19,47 +26,65 @@ module Rambling
 
     protected
 
-    def has_uncompressed_branch_for?(word = '')
-      word.empty? or fulfills_uncompressed_condition?(:has_uncompressed_branch_for?, word)
+    def has_uncompressed_branch_for?(chars)
+      chars.empty? or fulfills_uncompressed_condition?(:has_uncompressed_branch_for?, chars)
     end
 
-    def fulfills_uncompressed_condition?(method, word)
-      clone = word.clone
-      first_letter = clone.slice!(0)
-      unless first_letter.nil?
-        first_letter_sym = first_letter.to_sym
-        return @children[first_letter_sym].send(method, clone) if @children.has_key?(first_letter_sym)
+    def has_compressed_branch_for?(chars)
+      return true if chars.empty?
+
+      length = chars.length
+      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?
+          first_letter += chars.slice!(0)
+
+          break unless key.start_with?(first_letter)
+          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 has_compressed_branch_for?(word = '')
-      return true if word.empty?
-
-      keys = @children.keys.map { |x| x.to_s }
-      return true if keys.include?(word)
+    def is_uncompressed_word?(chars)
+      (chars.empty? and terminal?) or fulfills_uncompressed_condition?(:is_uncompressed_word?, chars)
+    end
 
-      partial_key = keys.select { |x| x.start_with?(word) }.first
-      return true unless partial_key.nil?
+    def is_compressed_word?(chars)
+      return true if chars.empty? and terminal?
 
-      key = keys.select { |x| word.start_with?(x) }.first
-      return @children[key.to_sym].has_compressed_branch_for?(word.slice(key.length..word.length)) unless key.nil?
+      length = chars.length
+      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
 
-    def is_uncompressed_word?(word = '')
-      (word.empty? and terminal?) or fulfills_uncompressed_condition?(:is_uncompressed_word?, word)
-    end
+    private
 
-    def is_compressed_word?(word = '')
-      return true if word.empty? and terminal?
-
-      length = word.length
-      for index in (0...length)
-        key = word.slice(0..index).to_sym
-        return @children[key].is_compressed_word?(word.slice((index + 1)...length)) if @children.has_key?(key)
+    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

data/lib/trie_compressor.rb

@@ -1,11 +1,10 @@
 module Rambling
+  # Provides the compressing behavior for the Trie data structure.
   module TrieCompressor
+    # Flag for compressed tries.
+    # @return [Boolean] `true` for compressed tries, `false` otherwise.
     def compressed?
-      if instance_variable_defined?(:@is_compressed)
-        @is_compressed
-      else
-        @parent.nil? ? false : @parent.compressed?
-      end
+      @parent.nil? ? false : @parent.compressed?
     end
 
     protected

data/lib/trie_node.rb

@@ -1,11 +1,25 @@
 module Rambling
+  # A representation of a node in the Trie data structure.
   class TrieNode
     include ChildrenHashDeferer
     include TrieCompressor
     include TrieBranches
 
-    attr_reader :letter, :children, :parent
+    # 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_reader :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
@@ -20,14 +34,15 @@ module Rambling
       end
     end
 
-    def terminal=(terminal)
-      @is_terminal = terminal
-    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 InvalidTrieOperation.new() unless @letter.nil? or terminal?
       get_letter_string
@@ -41,5 +56,9 @@ module Rambling
     def parent=(parent)
       @parent = parent
     end
+
+    def terminal=(terminal)
+      @is_terminal = terminal
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rambling-trie
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-11 00:00:00.000000000 Z
+date: 2012-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &14554820 !ruby/object:Gem::Requirement
+  requirement: &17006080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 2.0.0
   type: :development
   prerelease: false
-  version_requirements: *14554820
+  version_requirements: *17006080
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &14554220 !ruby/object:Gem::Requirement
+  requirement: &17018000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,40 @@ dependencies:
         version: 0.9.2
   type: :development
   prerelease: false
-  version_requirements: *14554220
+  version_requirements: *17018000
+- !ruby/object:Gem::Dependency
+  name: ruby-prof
+  requirement: &17031020 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.10.8
+  type: :development
+  prerelease: false
+  version_requirements: *17031020
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &16618180 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.7.5
+  type: :development
+  prerelease: false
+  version_requirements: *16618180
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: &16616900 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :development
+  prerelease: false
+  version_requirements: *16616900
 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.
@@ -43,7 +76,11 @@ extra_rdoc_files: []
 files:
 - ./lib/children_hash_deferer.rb
 - ./lib/invalid_trie_operation.rb
+- ./lib/rambling-trie/tasks/gem.rb
+- ./lib/rambling-trie/tasks/performance.rb
+- ./lib/rambling-trie/version.rb
 - ./lib/rambling-trie.rb
+- ./lib/rambling.rb
 - ./lib/trie.rb
 - ./lib/trie_branches.rb
 - ./lib/trie_compressor.rb
@@ -75,3 +112,4 @@ signing_key:
 specification_version: 3
 summary: A custom implementation of the trie data structure.
 test_files: []
+has_rdoc: