rambling-trie 0.5.0 → 0.5.1

data/README.markdown

@@ -28,33 +28,55 @@ gem 'rambling-trie'
 
 ## How to use the Rambling Trie
 
+To create the trie, initialize it like this:
+
+``` ruby
+trie = Rambling::Trie.create
+```
+
 - - -
-### Deprecation warnings
+
+#### Deprecation warnings
 
 * 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:
+You can also provide a block and the created instance will be yielded for you to perform any operation on it:
 
 ``` ruby
-trie = Rambling::Trie.create
+Rambling::Trie.create do |trie|
+  trie << 'word'
+end
 ```
 
-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:
+Additionally, you can 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'
 ```
 
-You can also provide a block and the created instance will be yielded for you to perform any operation on it:
+By default, a plain text file with the following format will be expected:
 
-``` ruby
-Rambling::Trie.create do |trie|
-  trie << 'word'
-end
+``` text
+some
+words
+to
+populate
+the
+trie
 ```
 
+If you want to use a custom file format, you will need to provide a custom file reader that defines the `each_word` method that yields each word contained in the file. Look at the `Rambling::Trie::PlainTextReader` class for an example.
+
+- - -
+
+#### Deprecation warnings
+
+* 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 add new words to the trie, use `add` or `<<`:
 
 ``` ruby

data/lib/rambling/trie.rb

@@ -1,6 +1,7 @@
 %w{
-  invalid_operation children_hash_deferer compressor
-  branches enumerable inspector node root version
+  branches children_hash_deferer compressor enumerable
+  plain_text_reader inspector invalid_operation node
+  root version
 }.map { |file| File.join 'rambling', 'trie', file }.each &method(:require)
 
 # General namespace for all Rambling gems.
@@ -9,20 +10,15 @@ 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.
+      # @param [String, nil] filepath the file to load the words from.
       # @return [Root] the trie just created.
       # @yield [Root] the trie just created.
-      def create(filename = nil)
+      def create(filepath = nil, reader = PlainTextReader.new)
         Root.new do |root|
-          words_from(filename) { |word| root << word } if filename
+          reader.each_word(filepath) { |word| root << word } if filepath
           yield root if block_given?
         end
       end
-
-      private
-      def words_from(filename)
-        File.open(filename) { |file| file.each_line { |line| yield line.chomp } }
-      end
     end
   end
 end

data/lib/rambling/trie/branches.rb

@@ -10,19 +10,19 @@ module Rambling
       def add(word)
         raise InvalidOperation, 'Cannot add branch to compressed trie' if compressed?
         if word.empty?
-          @terminal = true
+          self.terminal = true
           return
         end
 
         first_letter = word.slice(0).to_sym
 
-        if @children.has_key? first_letter
+        if children.has_key? first_letter
           word.slice! 0
-          child = @children[first_letter]
+          child = children[first_letter]
           child << word
           child
         else
-          @children[first_letter] = Node.new word, self
+          children[first_letter] = Node.new word, self
         end
       end
 
@@ -41,7 +41,7 @@ module Rambling
         current_key, current_key_string = current_key first_letter
 
         unless current_key.nil?
-          return @children[current_key].branch_when_compressed?(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
@@ -50,7 +50,7 @@ module Rambling
 
             return true if chars.empty?
             first_letter << char
-            return @children[current_key].branch_when_compressed?(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
           end
         end
 
@@ -68,7 +68,7 @@ module Rambling
         while not chars.empty?
           first_letter << chars.slice!(0)
           key = first_letter.to_sym
-          return @children[key].word_when_compressed?(chars) if @children.has_key? key
+          return children[key].word_when_compressed?(chars) if children.has_key? key
         end
 
         false
@@ -79,7 +79,7 @@ module Rambling
       def current_key(letter)
         current_key_string = current_key = nil
 
-        @children.keys.each do |key|
+        children.keys.each do |key|
           key_string = key.to_s
           if key_string.start_with? letter
             current_key = key
@@ -95,7 +95,7 @@ module Rambling
         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
+          return children[first_letter_sym].send(method, chars) if children.has_key? first_letter_sym
         end
 
         false

data/lib/rambling/trie/children_hash_deferer.rb

@@ -6,7 +6,7 @@ module Rambling
       # @param [Symbol] key the key to look for in the children's hash.
       # @return [Node, nil] the child node with that key or nil.
       def [](key)
-        @children[key]
+        children[key]
       end
 
       # Proxies to @children[key] = value.
@@ -14,21 +14,21 @@ module Rambling
       # @param [Node] value the node to add to the children's hash.
       # @return [Node, nil] the child node with that key or nil.
       def []=(key, value)
-        @children[key] = value
+        children[key] = value
       end
 
       # Proxies to @children.delete(key)
       # @param [Symbol] key the key to delete in the children's hash.
       # @return [Node, nil] the child node corresponding to the key just deleted or nil.
       def delete(key)
-        @children.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)
+        children.has_key?(key)
       end
     end
   end

data/lib/rambling/trie/compressor.rb

@@ -5,18 +5,18 @@ module Rambling
       # Flag for compressed tries.
       # @return [Boolean] `true` for compressed tries, `false` otherwise.
       def compressed?
-        @parent.nil? ? false : @parent.compressed?
+        parent and parent.compressed?
       end
 
       # 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 @letter
-          merge_with! @children.values.first
+        if children.size == 1 and not terminal? and letter
+          merge_with! children.values.first
           compress_tree!
         end
 
-        @children.values.each &:compress_tree!
+        children.values.each &:compress_tree!
 
         self
       end
@@ -24,25 +24,25 @@ 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
+        rehash_on_parent! letter, new_letter
         redefine_self! new_letter, child
 
-        @children.values.each { |node| node.parent = self }
+        children.values.each { |node| node.parent = self }
       end
 
       def rehash_on_parent!(old_letter, new_letter)
-        return if @parent.nil?
+        return if parent.nil?
 
-        @parent.delete old_letter
-        @parent[new_letter] = self
+        parent.delete old_letter
+        parent[new_letter] = self
       end
 
       def redefine_self!(new_letter, merged_node)
-        @letter = new_letter
-        @children = merged_node.children
-        @terminal = merged_node.terminal?
+        self.letter = new_letter
+        self.children = merged_node.children
+        self.terminal = merged_node.terminal?
       end
     end
   end

data/lib/rambling/trie/inspector.rb

@@ -2,6 +2,7 @@ module Rambling
   module Trie
     # Provides pretty printing behavior for the Trie data structure.
     module Inspector
+      # @return [String] a string representation of the current node.
       def inspect
         "#<#{self.class.name} letter: #{letter.inspect or 'nil'}, children: #{children.keys}>"
       end

data/lib/rambling/trie/invalid_operation.rb

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

data/lib/rambling/trie/node.rb

@@ -24,12 +24,13 @@ module Rambling
       # @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, {}]
+        self.parent = parent
+        self.children = {}
 
         unless word.nil? or word.empty?
           letter = word.slice! 0
-          @letter = letter.to_sym unless letter.nil?
-          @terminal = word.empty?
+          self.letter = letter.to_sym if letter
+          self.terminal = word.empty?
           self << word
         end
       end
@@ -37,20 +38,24 @@ module Rambling
       # Flag for terminal nodes.
       # @return [Boolean] `true` for terminal nodes, `false` otherwise.
       def terminal?
-        @terminal
+        !!terminal
       end
 
       # String representation of the current node, if it is a terminal node.
       # @return [String] the string representation of the current node.
       # @raise [InvalidOperation] if node is not terminal or is root.
       def as_word
-        raise InvalidOperation, 'Cannot represent branch as a word' unless @letter.nil? or terminal?
-        get_letter_string
+        raise InvalidOperation, 'Cannot represent branch as a word' unless letter.nil? or terminal?
+        letter_string
       end
 
       protected
-      def get_letter_string
-        (@parent.nil? ? '' : @parent.get_letter_string) << @letter.to_s
+
+      attr_writer :letter, :children
+      attr_accessor :terminal
+
+      def letter_string
+        (parent ? parent.letter_string : '') << letter.to_s
       end
     end
   end

data/lib/rambling/trie/plain_text_reader.rb

@@ -0,0 +1,23 @@
+module Rambling
+  module Trie
+    # File reader for .txt files
+    class PlainTextReader
+      # Yields each word read from a .txt file
+      # @param [String] filepath the full path of the file to load the words from.
+      # @yield [String] Each line read from the file.
+      def each_word(filepath)
+        each_line(filepath) { |line| yield line.chomp }
+      end
+
+      private
+
+      def each_line(filepath)
+        open(filepath) { |file| file.each_line { |line| yield line } }
+      end
+
+      def open(filepath)
+        File.open(filepath) { |file| yield file }
+      end
+    end
+  end
+end

data/lib/rambling/trie/root.rb

@@ -6,35 +6,35 @@ module Rambling
       # @yield [Root] the trie just created.
       def initialize
         super
-        @compressed = false
+        self.compressed = false
         yield self if block_given?
       end
 
       # Compresses the existing tree using redundant node elimination. Flags the trie as compressed.
       # @return [Root] self
       def compress!
-        @compressed = (compressed? or not compress_tree!.nil?)
+        self.compressed = (compressed? or !!compress_tree!)
         self
       end
 
       # Flag for compressed tries. Overrides {Compressor#compressed?}.
       # @return [Boolean] `true` for compressed tries, `false` otherwise.
       def compressed?
-        @compressed
+        !!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 branch?(word = '')
-        fulfills_condition? word, :branch?
+        is? :branch, word
       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 word?(word = '')
-        fulfills_condition? word, :word?
+        is? :word, word
       end
 
       alias_method :include?, :word?
@@ -53,8 +53,9 @@ module Rambling
 
       private
 
-      def fulfills_condition?(word, method)
-        method = method.to_s.slice 0...(method.length - 1)
+      attr_accessor :compressed
+
+      def is?(method, word)
         method = compressed? ? "#{method}_when_compressed?" : "#{method}_when_uncompressed?"
         send method, word.chars.to_a
       end

data/lib/rambling/trie/version.rb

@@ -1,6 +1,6 @@
 module Rambling
   module Trie
     # Current version of the rambling-trie.
-    VERSION = '0.5.0'
+    VERSION = '0.5.1'
   end
 end

data/spec/integration/rambling/trie_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+
+describe Rambling::Trie do
+  describe 'when a filepath is provided' do
+    let(:filepath) { File.join(::SPEC_ROOT, 'assets', 'test_words.txt') }
+    let(:words) { File.readlines(filepath).map &:chomp }
+    subject { Rambling::Trie.create filepath }
+
+    it 'contains all the words from the file' do
+      words.each { |word| expect(subject).to include(word) }
+    end
+
+    describe 'and the trie is compressed' do
+      it 'still contains all the words from the file' do
+        subject.compress!
+        words.each { |word| expect(subject).to include(word) }
+      end
+    end
+  end
+end

data/spec/lib/rambling/trie/plain_text_reader_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+
+module Rambling
+  module Trie
+    describe PlainTextReader do
+      describe '#each_word' do
+        let(:filepath) { File.join(::SPEC_ROOT, 'assets', 'test_words.txt') }
+        let(:words) { File.readlines(filepath).map &:chomp }
+
+        it 'yields every word yielded by the file' do
+          yielded_words = []
+          subject.each_word(filepath) { |word| yielded_words << word }
+          expect(yielded_words).to eq(words)
+        end
+      end
+    end
+  end
+end

data/spec/lib/rambling/trie_spec.rb

@@ -19,14 +19,20 @@ module Rambling
         end
       end
 
-      context 'with a filename' do
-        let(:filename) { File.join(::SPEC_ROOT, 'assets', 'test_words.txt') }
-        let(:words) { File.readlines(filename).map &:chomp }
+      context 'with a filepath' do
+        let(:filepath) { 'test_words.txt' }
+        let(:reader) { double(Trie::PlainTextReader) }
+        let(:words) { %w(a couple of test words over here) }
+
+        before do
+          yielder = reader.stub(:each_word)
+          words.each { |word| yielder = yielder.and_yield(word) }
+        end
 
         it 'loads every word' do
           words.each { |word| root.should_receive(:<<).with(word) }
 
-          Trie.create filename
+          Trie.create filepath, reader
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rambling-trie
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-18 00:00:00.000000000 Z
+date: 2012-12-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -118,6 +118,7 @@ files:
 - lib/rambling/trie/inspector.rb
 - lib/rambling/trie/invalid_operation.rb
 - lib/rambling/trie/node.rb
+- lib/rambling/trie/plain_text_reader.rb
 - lib/rambling/trie/root.rb
 - lib/rambling/trie/tasks/gem.rb
 - lib/rambling/trie/tasks/performance.rb
@@ -125,11 +126,13 @@ files:
 - rambling-trie.gemspec
 - reports/performance
 - spec/assets/test_words.txt
+- spec/integration/rambling/trie_spec.rb
 - spec/lib/rambling/trie/branches_spec.rb
 - spec/lib/rambling/trie/children_hash_deferer_spec.rb
 - spec/lib/rambling/trie/enumerable_spec.rb
 - spec/lib/rambling/trie/inspector_spec.rb
 - spec/lib/rambling/trie/node_spec.rb
+- spec/lib/rambling/trie/plain_text_reader_spec.rb
 - spec/lib/rambling/trie/root_spec.rb
 - spec/lib/rambling/trie_spec.rb
 - spec/spec_helper.rb
@@ -147,7 +150,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2034163289446234430
+      hash: -2285345975138821646
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -156,7 +159,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2034163289446234430
+      hash: -2285345975138821646
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -165,11 +168,13 @@ specification_version: 3
 summary: A custom implementation of the trie data structure.
 test_files:
 - spec/assets/test_words.txt
+- spec/integration/rambling/trie_spec.rb
 - spec/lib/rambling/trie/branches_spec.rb
 - spec/lib/rambling/trie/children_hash_deferer_spec.rb
 - spec/lib/rambling/trie/enumerable_spec.rb
 - spec/lib/rambling/trie/inspector_spec.rb
 - spec/lib/rambling/trie/node_spec.rb
+- spec/lib/rambling/trie/plain_text_reader_spec.rb
 - spec/lib/rambling/trie/root_spec.rb
 - spec/lib/rambling/trie_spec.rb
 - spec/spec_helper.rb