rambling-trie 0.5.2 → 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 403d826dbe4417d5ed4215bb0fd463a4142d51b9
+  data.tar.gz: 363b65990628f645c0d48bdc50803d22c7efbe93
+SHA512:
+  metadata.gz: 428848bed7b6bda02217fcec568001bddc6f6ad880af8ac7ca7714b803cb3175a17c70073102c55b270e648140f9e7ff79d40f5f531eda653e022b99e8cedd5e
+  data.tar.gz: 9b7950cf8dd31fc652f07295b968eb680fe535d4f8258d8357d5dd5646f644102ad27ec57012005c1634492e591863e4753607e88b8ff1a73ce8accef85199c7

data/.travis.yml

@@ -1,4 +1,5 @@
 language: ruby
 rvm:
+  - 2.0.0
   - 1.9.3
   - 1.9.2

data/Gemfile

@@ -1,11 +1,7 @@
-source 'http://rubygems.org'
+source 'https://rubygems.org'
 
 gemspec
 
-group :development do
-  gem 'perftools.rb'
-end
-
 group :test do
   gem 'rake'
   gem 'guard-rspec'

data/LICENSE

@@ -1,4 +1,6 @@
-Copyright (c) 2011-2012 Rambling Labs
+Copyright (c) 2012-2013 Edgar Gonzalez
+
+MIT License
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/README.markdown

@@ -1,4 +1,4 @@
-# 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)
+# 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/github/gonzedge/rambling-trie.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.
 
@@ -71,8 +71,17 @@ If you want to use a custom file format, you will need to provide a custom file
 
 - - -
 
+#### Breaking changes
+
+* Starting from version 0.6.0, the `children` method returns an array of nodes instead of a hash. If you still need access to the underlying hash, use `children_tree` instead.
+
+- - -
+
+- - -
+
 #### Deprecation warnings
 
+* Starting from version 0.6.0, the `branch?` method is deprecated. The `partial_word?` method should be used 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.
 
 - - -
@@ -91,10 +100,11 @@ trie.word? 'word'
 trie.include? 'word'
 ```
 
-If you wish to find if part of a word exists in the trie instance, you should call `branch?`:
+If you wish to find if part of a word exists in the trie instance, you should call `partial_word?`:
 
 ``` ruby
-trie.branch? 'partial_word'
+trie.partial_word? 'partial_word'
+trie.match? 'partial_word'
 ```
 
 ### Compression
@@ -109,8 +119,6 @@ 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?` (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.__
 
@@ -141,13 +149,14 @@ You can find further API documentation on the autogenerated [rambling-trie gem R
 
 The Rambling Trie has been tested with the following Ruby versions:
 
-* 1.9.2
+* 2.0.0
 * 1.9.3
+* 1.9.2
 
 And the following Rails versions:
 
-* 3.1.x
 * 3.2.x
+* 3.1.x
 
 It's possible that Rails 3.0.x is supported, but there is no guarantee.
 Ruby 1.8.7 is not supported.
@@ -159,7 +168,9 @@ Also, be sure to add tests for any feature you may develop or bug you may fix.
 
 ## License and copyright
 
-Copyright (c) 2012 Rambling Labs
+Copyright (c) 2012-2013 Edgar Gonzalez
+
+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:
 

data/lib/rambling/trie.rb

@@ -1,7 +1,8 @@
+require 'forwardable'
 %w{
-  branches children_hash_deferer compressor enumerable
-  plain_text_reader inspector invalid_operation node
-  root version
+  branches compressor enumerable
+  inspector invalid_operation node
+  plain_text_reader root version
 }.map { |file| File.join 'rambling', 'trie', file }.each &method(:require)
 
 # General namespace for all Rambling gems.

data/lib/rambling/trie/branches.rb

@@ -16,13 +16,13 @@ module Rambling
 
         first_letter = word.slice(0).to_sym
 
-        if children.has_key? first_letter
+        if children_tree.has_key? first_letter
           word.slice! 0
-          child = children[first_letter]
+          child = children_tree[first_letter]
           child << word
           child
         else
-          children[first_letter] = Node.new word, self
+          children_tree[first_letter] = Node.new word, self
         end
       end
 
@@ -30,31 +30,12 @@ module Rambling
 
       protected
 
-      def branch_when_uncompressed?(chars)
-        chars.empty? || fulfills_uncompressed_condition?(:branch_when_uncompressed?, chars)
+      def partial_word_when_uncompressed?(chars)
+        chars.empty? || fulfills_uncompressed_condition?(:partial_word_when_uncompressed?, chars)
       end
 
-      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].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
-
-            return true if chars.empty?
-            first_letter << char
-            return children[current_key].branch_when_compressed?(chars) if current_key_string.length == first_letter.length
-          end
-        end
-
-        false
+      def partial_word_when_compressed?(chars)
+        chars.empty? || compressed_trie_has_partial_word?(chars)
       end
 
       def word_when_uncompressed?(chars)
@@ -68,7 +49,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_tree[key].word_when_compressed?(chars) if children_tree.has_key? key
         end
 
         false
@@ -76,10 +57,24 @@ module Rambling
 
       private
 
+      def compressed_trie_has_partial_word?(chars)
+        current_length = 0
+        current_key, current_key_string = current_key chars.slice!(0)
+
+        begin
+          current_length += 1
+
+          if current_key_string.length == current_length || chars.empty?
+            return children_tree[current_key].partial_word_when_compressed?(chars)
+          end
+        end while current_key_string[current_length] == chars.slice!(0)
+        false
+      end
+
       def current_key(letter)
         current_key_string = current_key = nil
 
-        children.keys.each do |key|
+        children_tree.keys.each do |key|
           key_string = key.to_s
           if key_string.start_with? letter
             current_key = key
@@ -95,7 +90,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_tree[first_letter_sym].send(method, chars) if children_tree.has_key? first_letter_sym
         end
 
         false

data/lib/rambling/trie/compressor.rb

@@ -11,23 +11,27 @@ module Rambling
       # Compress the current node using redundant node elimination.
       # @return [Root, Node] the compressed node.
       def compress_tree!
-        if children.size == 1 && !terminal? && letter
-          merge_with! children.values.first
+        if compressable?
+          merge_with! children.first
           compress_tree!
         end
 
-        children.values.each &:compress_tree!
+        children.each &:compress_tree!
 
         self
       end
 
       private
 
+      def compressable?
+        !(root? || terminal?) && children_tree.size == 1
+      end
+
       def merge_with!(child)
         delete_old_key_on_parent!
         redefine_self! child
 
-        children.each { |_, node| node.parent = self }
+        children.each { |node| node.parent = self }
       end
 
       def delete_old_key_on_parent!
@@ -38,7 +42,7 @@ module Rambling
 
       def redefine_self!(merged_node)
         self.letter = letter.to_s << merged_node.letter.to_s
-        self.children = merged_node.children
+        self.children_tree = merged_node.children_tree
         self.terminal = merged_node.terminal?
       end
     end

data/lib/rambling/trie/enumerable.rb

@@ -10,7 +10,7 @@ module Rambling
       def each(&block)
         enumerator = Enumerator.new do |words|
           words << as_word if terminal?
-          children.each { |key, child| child.each { |word| words << word } }
+          children.each { |child| child.each { |word| words << word } }
         end
 
         block.nil? ? enumerator : enumerator.each(&block)

data/lib/rambling/trie/inspector.rb

@@ -4,7 +4,7 @@ module Rambling
     module Inspector
       # @return [String] a string representation of the current node.
       def inspect
-        "#<#{self.class.name} letter: #{letter.inspect || 'nil'}, children: #{children.keys}>"
+        "#<#{self.class.name} letter: #{letter.inspect || 'nil'}, children: #{children_tree.keys}>"
       end
     end
   end

data/lib/rambling/trie/node.rb

@@ -2,7 +2,10 @@ module Rambling
   module Trie
     # A representation of a node in the Trie data structure.
     class Node
-      include ChildrenHashDeferer
+      extend Forwardable
+
+      delegate [:[], :[]=, :delete, :has_key?] => :children_tree
+
       include Compressor
       include Branches
       include Enumerable
@@ -13,8 +16,8 @@ module Rambling
       attr_reader :letter
 
       # Children nodes.
-      # @return [Hash] the children hash, consisting of :letter => node.
-      attr_reader :children
+      # @return [Hash] the children_tree hash, consisting of :letter => node.
+      attr_reader :children_tree
 
       # Parent node.
       # @return [Node, nil] the parent node or nil for the root element.
@@ -25,7 +28,7 @@ module Rambling
       # @param [Node, nil] parent the parent of this node.
       def initialize(word = nil, parent = nil)
         self.parent = parent
-        self.children = {}
+        self.children_tree = {}
 
         unless word.nil? || word.empty?
           self.letter = word.slice! 0
@@ -34,12 +37,6 @@ module Rambling
         end
       end
 
-      # Flag for terminal nodes.
-      # @return [Boolean] `true` for terminal nodes, `false` otherwise.
-      def 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.
@@ -48,6 +45,24 @@ module Rambling
         to_s
       end
 
+      # Children nodes of the current node.
+      # @return [Array] the array of children nodes contained in the current node.
+      def children
+        children_tree.values
+      end
+
+      # If the current node is the root node.
+      # @return [Boolean] `false`
+      def root?
+        false
+      end
+
+      # Flag for terminal nodes.
+      # @return [Boolean] `true` for terminal nodes, `false` otherwise.
+      def terminal?
+        !!terminal
+      end
+
       # String representation of the current node.
       # @return [String] the string representation of the current node.
       def to_s
@@ -56,7 +71,7 @@ module Rambling
 
       protected
 
-      attr_writer :children
+      attr_writer :children_tree
       attr_accessor :terminal
 
       def letter=(letter)

data/lib/rambling/trie/root.rb

@@ -10,6 +10,24 @@ module Rambling
         yield self if block_given?
       end
 
+      # 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
+      # @note Avoids clearing the contents of the word variable.
+      def add(word)
+        super word.clone
+      end
+
+      alias_method :<<, :add
+
+      # @deprecated Use `#partial_word?` instead.
+      def branch?(word = '')
+        warn 'The `#branch?` method will be deprecated, please use `#partial_word?` instead.'
+        partial_word? word
+      end
+
       # Compresses the existing tree using redundant node elimination. Flags the trie as compressed.
       # @return [Root] self
       def compress!
@@ -26,8 +44,16 @@ 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 branch?(word = '')
-        is? :branch, word
+      def partial_word?(word = '')
+        is? :partial_word, word
+      end
+
+      alias_method :match?, :partial_word?
+
+      # If the current node is the root node.
+      # @return [Boolean] `true`
+      def root?
+        true
       end
 
       # Checks if a whole word exists in the trie.
@@ -39,18 +65,6 @@ module Rambling
 
       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
-      # @note Avoids clearing the contents of the word variable.
-      def add(word)
-        super word.clone
-      end
-
-      alias_method :<<, :add
-
       private
 
       attr_accessor :compressed

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

@@ -2,8 +2,8 @@ require 'benchmark'
 
 namespace :performance do
   def report(name, trie, output)
-    words = ['hi', 'help', 'beautiful', 'impressionism', 'anthropological']
-    methods = [:word?, :branch?]
+    words = %w(hi help beautiful impressionism anthropological)
+    methods = [:word?, :partial_word?]
 
     output.puts "==> #{name}"
     methods.each do |method|
@@ -65,8 +65,8 @@ namespace :performance do
     puts 'Generating profiling reports...'
 
     rambling_trie = Rambling::Trie.create path('assets', 'dictionaries', 'words_with_friends.txt')
-    words = ['hi', 'help', 'beautiful', 'impressionism', 'anthropological']
-    methods = [:branch?, :word?]
+    words = %w(hi help beautiful impressionism anthropological)
+    methods = [:word?, :partial_word?]
     tries = [lambda {rambling_trie.clone}, lambda {rambling_trie.clone.compress!}]
 
     methods.each do |method|
@@ -87,31 +87,6 @@ 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.create path('assets', 'dictionaries', 'words_with_friends.txt')
-    words = ['hi', 'help', 'beautiful', 'impressionism', 'anthropological']
-    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 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