rambling-trie 0.4.2 → 0.5.0

data/.gitignore

@@ -21,3 +21,9 @@ pkg/
 # Yard
 doc/
 .yardoc/
+
+# CTags
+tags
+
+# General
+tmp/

data/Gemfile

@@ -9,5 +9,7 @@ end
 group :test do
   gem 'rake'
   gem 'guard-rspec'
+  gem 'rb-fsevent'
+  gem 'rb-inotify'
   gem 'simplecov', require: false
 end

data/Guardfile

@@ -1,7 +1,7 @@
 # A sample Guardfile
 # More info at https://github.com/guard/guard#readme
 
-guard 'rspec', version: 2, all_on_start: true, all_after_pass: false do
+guard 'rspec', all_on_start: true, all_after_pass: false do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
   watch('spec/spec_helper.rb')  { "spec" }

data/README.markdown

@@ -1,4 +1,4 @@
-# Rambling Trie [![Build Status](https://secure.travis-ci.org/egonzalez0787/rambling-trie.png)](http://travis-ci.org/egonzalez0787/rambling-trie) [![Dependency Status](https://gemnasium.com/egonzalez0787/rambling-trie.png)](https://gemnasium.com/egonzalez0787/rambling-trie) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/egonzalez0787/rambling-trie)
+# Rambling Trie [![Build Status](https://secure.travis-ci.org/gonzedge/rambling-trie.png)](http://travis-ci.org/gonzedge/rambling-trie) [![Dependency Status](https://gemnasium.com/gonzedge/rambling-trie.png)](https://gemnasium.com/gonzedge/rambling-trie) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/gonzedge/rambling-trie)
 
 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.
 
@@ -29,9 +29,10 @@ gem 'rambling-trie'
 ## How to use the Rambling Trie
 
 - - -
-### Deprecation warning
+### Deprecation warnings
 
-Starting from version 0.4.0, `Rambling::Trie.new` is deprecated. Please use `Rambling::Trie.create` instead.
+* Starting from version 0.4.0, `Rambling::Trie.new` is deprecated. Please use `Rambling::Trie.create` instead.
+* Starting from version 0.5.0, the `has_branch_for?`, `is_word?` and `add_branch_from` methods are deprecated. The methods `branch?`, `word?` and `add` should be used respectively.
 - - -
 
 To create the trie, initialize it like this:
@@ -40,30 +41,38 @@ To create the trie, initialize it like this:
 trie = Rambling::Trie.create
 ```
 
-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:
+You can also provide the path to a file that contains all the words to be added to the trie, and it will read the file and create the complete structure for you, like this:
 
 ``` ruby
 trie = Rambling::Trie.create '/path/to/file'
 ```
 
-To add new words to the trie, use `add_branch_from` or `<<`:
+You can also provide a block and the created instance will be yielded for you to perform any operation on it:
 
 ``` ruby
-trie.add_branch_from 'word'
+Rambling::Trie.create do |trie|
+  trie << 'word'
+end
+```
+
+To add new words to the trie, use `add` or `<<`:
+
+``` ruby
+trie.add 'word'
 trie << 'word'
 ```
 
-And to find out if a word already exists in the trie, use `is_word?` or `include?`:
+And to find out if a word already exists in the trie, use `word?` or `include?`:
 
 ``` ruby
-trie.is_word? 'word'
+trie.word? 'word'
 trie.include? 'word'
 ```
 
-If you wish to find if part of a word exists in the trie instance, you should call `has_branch_for?`:
+If you wish to find if part of a word exists in the trie instance, you should call `branch?`:
 
 ``` ruby
-trie.has_branch_for? 'partial_word'
+trie.branch? 'partial_word'
 ```
 
 ### Compression
@@ -78,7 +87,7 @@ trie.compress!
 
 This will reduce the amount of Trie nodes by eliminating the redundant ones, which are the only-child non-terminal nodes.
 
-Starting from version 0.3.2, the `has_branch_for?` and `is_word?` methods work as expected on a compressed trie.
+Starting from version 0.3.2, the `has_branch_for?` (now `has_branch?`) and `is_word?` (now `word?`) methods work as expected on a compressed trie.
 
 __Note that the `compress!` method acts over the trie instance it belongs to.__
 __Also, adding words after compression is not supported.__
@@ -89,9 +98,22 @@ You can find out if a trie instance is compressed by calling the `compressed?` m
 trie.compressed?
 ```
 
+### Enumeration
+
+Starting from version 0.4.2, you can use any `Enumerable` method over a trie instance, and it will iterate over each word contained in the trie. You can now do things like:
+
+``` ruby
+trie.each do |word|
+  puts word
+end
+
+trie.any? { |word| word.include? 'x' }
+# etc.
+```
+
 ## Further Documentation
 
-You can find further API documentation on the autogenerated [rambling-trie gem RubyDoc.info page](http://rubydoc.info/gems/rambling-trie) or if you want edge documentation, you can go the [GitHub project RubyDoc.info page](http://rubydoc.info/github/egonzalez0787/rambling-trie).
+You can find further API documentation on the autogenerated [rambling-trie gem RubyDoc.info page](http://rubydoc.info/gems/rambling-trie) or if you want edge documentation, you can go the [GitHub project RubyDoc.info page](http://rubydoc.info/github/gonzedge/rambling-trie).
 
 ## Compatible Ruby and Rails versions
 
@@ -105,7 +127,8 @@ And the following Rails versions:
 * 3.1.x
 * 3.2.x
 
-It's possible that Ruby 1.8.7 and Rails 3.0.x are supported, but there is no guarantee.
+It's possible that Rails 3.0.x is supported, but there is no guarantee.
+Ruby 1.8.7 is not supported.
 
 ## Contributing to Rambling Trie
 

data/lib/rambling/trie.rb

@@ -1,13 +1,7 @@
-[
-  'invalid_operation',
-  'children_hash_deferer',
-  'compressor',
-  'branches',
-  'enumerable',
-  'node',
-  'root',
-  'version'
-].map { |file| File.join 'rambling', 'trie', file }.each &method(:require)
+%w{
+  invalid_operation children_hash_deferer compressor
+  branches enumerable inspector node root version
+}.map { |file| File.join 'rambling', 'trie', file }.each &method(:require)
 
 # General namespace for all Rambling gems.
 module Rambling
@@ -15,18 +9,19 @@ module Rambling
   module Trie
     class << self
       # Creates a new Trie. Entry point for the Rambling::Trie API.
-      # @param [String, nil] filename the file to load the words from (defaults to nil).
+      # @param [String, nil] filename the file to load the words from.
+      # @return [Root] the trie just created.
+      # @yield [Root] the trie just created.
       def create(filename = nil)
-        Root.new filename
+        Root.new do |root|
+          words_from(filename) { |word| root << word } if filename
+          yield root if block_given?
+        end
       end
 
-      # Creates a new Trie. Entry point for the Rambling::Trie API.
-      # @param [String, nil] filename the file to load the words from (defaults to nil).
-      # @deprecated Please use {.create} instead.
-      # @see .create
-      def new(filename = nil)
-        warn '[DEPRECATION] `new` is deprecated. Please use `create` instead.'
-        create filename
+      private
+      def words_from(filename)
+        File.open(filename) { |file| file.each_line { |line| yield line.chomp } }
       end
     end
   end

data/lib/rambling/trie/branches.rb

@@ -7,8 +7,8 @@ module Rambling
       # @return [Node] the just added branch's root node.
       # @raise [InvalidOperation] if the trie is already compressed.
       # @note This method clears the contents of the word variable.
-      def add_branch_from(word)
-        raise InvalidOperation.new('Cannot add branch to compressed trie') if compressed?
+      def add(word)
+        raise InvalidOperation, 'Cannot add branch to compressed trie' if compressed?
         if word.empty?
           @terminal = true
           return
@@ -26,56 +26,49 @@ module Rambling
         end
       end
 
-      # Alias for {#add_branch_from}. Defined instead of simple `alias_method` for overriding purposes.
-      # @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.
-      # @see #add_branch_from
-      def <<(word)
-        add_branch_from word
-      end
+      alias_method :<<, :add
 
       protected
 
-      def uncompressed_has_branch_for?(chars)
-        chars.empty? or fulfills_uncompressed_condition?(:uncompressed_has_branch_for?, chars)
+      def branch_when_uncompressed?(chars)
+        chars.empty? or fulfills_uncompressed_condition?(:branch_when_uncompressed?, chars)
       end
 
-      def compressed_has_branch_for?(chars)
+      def branch_when_compressed?(chars)
         return true if chars.empty?
 
         first_letter = chars.slice! 0
         current_key, current_key_string = current_key first_letter
 
         unless current_key.nil?
-          return @children[current_key].compressed_has_branch_for?(chars) if current_key_string.length == first_letter.length
+          return @children[current_key].branch_when_compressed?(chars) if current_key_string.length == first_letter.length
 
           while not chars.empty?
             char = chars.slice! 0
 
             break unless current_key_string[first_letter.length] == char
 
-            first_letter += char
             return true if chars.empty?
-            return @children[current_key].compressed_has_branch_for?(chars) if current_key_string.length == first_letter.length
+            first_letter << char
+            return @children[current_key].branch_when_compressed?(chars) if current_key_string.length == first_letter.length
           end
         end
 
         false
       end
 
-      def uncompressed_is_word?(chars)
-        (chars.empty? and terminal?) or fulfills_uncompressed_condition?(:uncompressed_is_word?, chars)
+      def word_when_uncompressed?(chars)
+        (chars.empty? and terminal?) or fulfills_uncompressed_condition?(:word_when_uncompressed?, chars)
       end
 
-      def compressed_is_word?(chars)
+      def word_when_compressed?(chars)
         return true if chars.empty? and terminal?
 
         first_letter = ''
         while not chars.empty?
-          first_letter += chars.slice! 0
+          first_letter << chars.slice!(0)
           key = first_letter.to_sym
-          return @children[key].compressed_is_word?(chars) if @children.has_key? key
+          return @children[key].word_when_compressed?(chars) if @children.has_key? key
         end
 
         false

data/lib/rambling/trie/compressor.rb

@@ -8,10 +8,10 @@ module Rambling
         @parent.nil? ? false : @parent.compressed?
       end
 
-      # Compressed the current node using redundant node elimination.
+      # Compress the current node using redundant node elimination.
       # @return [Root, Node] the compressed node.
       def compress_tree!
-        if @children.size == 1 and not terminal? and not @letter.nil?
+        if @children.size == 1 and not terminal? and @letter
           merge_with! @children.values.first
           compress_tree!
         end
@@ -24,7 +24,7 @@ module Rambling
       private
 
       def merge_with!(child)
-        new_letter = (@letter.to_s + child.letter.to_s).to_sym
+        new_letter = (@letter.to_s << child.letter.to_s).to_sym
 
         rehash_on_parent! @letter, new_letter
         redefine_self! new_letter, child

data/lib/rambling/trie/inspector.rb

@@ -0,0 +1,10 @@
+module Rambling
+  module Trie
+    # Provides pretty printing behavior for the Trie data structure.
+    module Inspector
+      def inspect
+        "#<#{self.class.name} letter: #{letter.inspect or 'nil'}, children: #{children.keys}>"
+      end
+    end
+  end
+end

data/lib/rambling/trie/node.rb

@@ -6,6 +6,7 @@ module Rambling
       include Compressor
       include Branches
       include Enumerable
+      include Inspector
 
       # Letter or letters corresponding to this node.
       # @return [Symbol, nil] the corresponding letter(s) or nil.
@@ -20,9 +21,9 @@ module Rambling
       attr_accessor :parent
 
       # Creates a new Node.
-      # @param [String] word the word from which to create this Node and his branch.
-      # @param [Node] parent the parent of this node.
-      def initialize(word, parent = nil)
+      # @param [String, nil] word the word from which to create this Node and his branch.
+      # @param [Node, nil] parent the parent of this node.
+      def initialize(word = nil, parent = nil)
         @letter, @parent, @terminal, @children = [nil, parent, false, {}]
 
         unless word.nil? or word.empty?
@@ -43,13 +44,13 @@ module Rambling
       # @return [String] the string representation of the current node.
       # @raise [InvalidOperation] if node is not terminal or is root.
       def as_word
-        raise InvalidOperation.new unless @letter.nil? or terminal?
+        raise InvalidOperation, 'Cannot represent branch as a word' unless @letter.nil? or terminal?
         get_letter_string
       end
 
       protected
       def get_letter_string
-        (@parent.nil? ? '' : @parent.get_letter_string) + @letter.to_s
+        (@parent.nil? ? '' : @parent.get_letter_string) << @letter.to_s
       end
     end
   end

data/lib/rambling/trie/root.rb

@@ -3,19 +3,17 @@ module Rambling
     # 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
+      # @yield [Root] the trie just created.
+      def initialize
+        super
         @compressed = false
-        add_all_nodes if filename
+        yield self if block_given?
       end
 
       # Compresses the existing tree using redundant node elimination. Flags the trie as compressed.
-      # @return [Root] same object
+      # @return [Root] self
       def compress!
-        @compressed = (not compress_tree!.nil?) unless compressed?
+        @compressed = (compressed? or not compress_tree!.nil?)
         self
       end
 
@@ -28,37 +26,37 @@ module Rambling
       # 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 = '')
-        fulfills_condition word, :has_branch_for?
+      def branch?(word = '')
+        fulfills_condition? word, :branch?
       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 = '')
-        fulfills_condition word, :is_word?
+      def word?(word = '')
+        fulfills_condition? word, :word?
       end
 
-      alias_method :include?, :is_word?
+      alias_method :include?, :word?
 
       # Adds a branch to the trie based on the word, without changing the passed 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.
-      # @see Branches#add_branch_from
+      # @see Branches#add
       # @note Avoids clearing the contents of the word variable.
-      def add_branch_from(word)
+      def add(word)
         super word.clone
       end
 
+      alias_method :<<, :add
+
       private
-      def fulfills_condition(word, method)
-        method = compressed? ? "compressed_#{method}" : "uncompressed_#{method}"
-        send(method, word.chars.to_a)
-      end
 
-      def add_all_nodes
-        File.open(@filename).each_line { |line| self << line.chomp }
+      def fulfills_condition?(word, method)
+        method = method.to_s.slice 0...(method.length - 1)
+        method = compressed? ? "#{method}_when_compressed?" : "#{method}_when_uncompressed?"
+        send method, word.chars.to_a
       end
     end
   end

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

@@ -3,7 +3,7 @@ require 'benchmark'
 namespace :performance do
   def report(name, trie, output)
     words = ['hi', 'help', 'beautiful', 'impressionism', 'anthropological']
-    methods = [:is_word?, :has_branch_for?]
+    methods = [:word?, :branch?]
 
     output.puts "==> #{name}"
     methods.each do |method|
@@ -21,7 +21,7 @@ namespace :performance do
     output.puts "\nReport for rambling-trie version #{Rambling::Trie::VERSION}"
 
     trie = nil
-    measure = Benchmark.measure { trie = Rambling::Trie.create get_path('assets', 'dictionaries', 'words_with_friends.txt') }
+    measure = Benchmark.measure { trie = Rambling::Trie.create path('assets', 'dictionaries', 'words_with_friends.txt') }
 
     if ENV['profile_creation']
       output.puts '==> Creation'
@@ -39,8 +39,8 @@ namespace :performance do
     output.close
   end
 
-  def get_path(*filename)
-    File.join File.dirname(__FILE__), '..', '..', '..', *filename
+  def path(*filename)
+    File.join File.dirname(__FILE__), '..', '..', '..', '..', *filename
   end
 
   desc 'Generate performance report'
@@ -53,7 +53,7 @@ namespace :performance do
     desc 'Generate performance report and append result to reports/performance'
     task :save do
       puts 'Generating performance report...'
-      generate_report get_path('reports', 'performance')
+      generate_report path('reports', 'performance')
       puts 'Report has been saved to reports/performance'
     end
   end
@@ -64,9 +64,9 @@ namespace :performance do
 
     puts 'Generating profiling reports...'
 
-    rambling_trie = Rambling::Trie.create get_path('assets', 'dictionaries', 'words_with_friends.txt')
+    rambling_trie = Rambling::Trie.create path('assets', 'dictionaries', 'words_with_friends.txt')
     words = ['hi', 'help', 'beautiful', 'impressionism', 'anthropological']
-    methods = [:has_branch_for?, :is_word?]
+    methods = [:branch?, :word?]
     tries = [lambda {rambling_trie.clone}, lambda {rambling_trie.clone.compress!}]
 
     methods.each do |method|
@@ -78,7 +78,7 @@ namespace :performance do
           end
         end
 
-        File.open get_path('reports', "profile-#{trie.compressed? ? 'compressed' : 'uncompressed'}-#{method.to_s.sub(/\?/, '')}-#{Time.now.to_i}"), 'w' do |file|
+        File.open 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
@@ -93,15 +93,15 @@ namespace :performance do
 
     puts 'Generating cpu profiling reports...'
 
-    rambling_trie = Rambling::Trie.create get_path('assets', 'dictionaries', 'words_with_friends.txt')
+    rambling_trie = Rambling::Trie.create path('assets', 'dictionaries', 'words_with_friends.txt')
     words = ['hi', 'help', 'beautiful', 'impressionism', 'anthropological']
-    methods = [:has_branch_for?, :is_word?]
+    methods = [:branch?, :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
+        result = PerfTools::CpuProfiler.start 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