tire 0.3.1 → 0.3.2

data/lib/tire/model/import.rb

@@ -1,6 +1,13 @@
 module Tire
   module Model
 
+    # Provides support for easy importing of large ActiveRecord- and ActiveModel-bound
+    # recordsets into model index.
+    #
+    # Relies on pagination support in your model, namely the `paginate` class method.
+    #
+    # Please refer to the relevant of the README for more information.
+    #
     module Import
 
       module ClassMethods

data/lib/tire/model/indexing.rb

@@ -1,16 +1,47 @@
 module Tire
   module Model
 
+    # Contains logic for definition of index settings and mappings.
+    #
     module Indexing
 
       module ClassMethods
 
+        # Define [_settings_](http://www.elasticsearch.org/guide/reference/api/admin-indices-create-index.html)
+        # for the corresponding index, such as number of shards and replicas, custom analyzers, etc.
+        #
+        # Usage:
+        #
+        #     class Article
+        #       # ...
+        #       settings :number_of_shards => 1 do
+        #         mapping do
+        #           # ...
+        #         end
+        #       end
+        #     end
+        #
         def settings(*args)
           @settings ||= {}
           args.empty?  ? (return @settings) : @settings = args.pop
           yield if block_given?
         end
 
+        # Define the [_mapping_](http://www.elasticsearch.org/guide/reference/mapping/index.html)
+        # for the corresponding index, telling _ElasticSearch_ how to understand your documents:
+        # what type is which property, whether it is analyzed or no, which analyzer to use, etc.
+        #
+        # Usage:
+        #
+        #     class Article
+        #       # ...
+        #       mapping do
+        #         indexes :id,    :type => 'string',  :index    => :not_analyzed
+        #         indexes :title, :type => 'string',  :analyzer => 'snowball',   :boost => 100
+        #         # ...
+        #       end
+        #     end
+        #
         def mapping
           @mapping ||= {}
           if block_given?
@@ -21,6 +52,21 @@ module Tire
           end
         end
 
+        # Define mapping for the property passed as the first argument (`name`)
+        # using definition from the second argument (`options`).
+        #
+        # `:type` is optional and defaults to `'string'`.
+        #
+        # Usage:
+        #
+        # * Index property but do not analyze it: `indexes :id, :index    => :not_analyzed`
+        #
+        # * Use different analyzer for indexing a property: `indexes :title, :analyzer => 'snowball'`
+        #
+        # Please refer to the
+        # [_mapping_ documentation](http://www.elasticsearch.org/guide/reference/mapping/index.html)
+        # for more information.
+        #
         def indexes(name, options = {}, &block)
           options[:type] ||= 'string'
 
@@ -40,16 +86,18 @@ module Tire
           end
         end
 
-        def store_mapping?
-          @store_mapping || false
-        end
-
+        # Creates the corresponding index with desired settings and mappings, when it does not exists yet.
+        #
         def create_elasticsearch_index
           unless index.exists?
             index.create :mappings => mapping_to_hash, :settings => settings
           end
         end
 
+        def store_mapping?
+          @store_mapping || false
+        end
+
         def mapping_to_hash
           { document_type.to_sym => { :properties => mapping } }
         end

data/lib/tire/model/naming.rb

@@ -1,24 +1,44 @@
 module Tire
   module Model
 
+    # Contains logic for getting and setting the index name and document type for this model.
+    #
     module Naming
 
       module ClassMethods
+
+        # Get or set the index name for this model, based on arguments.
+        #
+        # To get the index name:
+        #
+        #     Article.index_name
+        #
+        # To set the index name:
+        #
+        #     Article.index_name 'my-custom-name'
+        #
         def index_name name=nil
           @index_name = name if name
           @index_name || klass.model_name.plural
         end
 
+        # Get the document type for this model, based on the class name.
+        #
         def document_type
           klass.model_name.singular
         end
       end
 
       module InstanceMethods
+
+        # Proxy to class method `index_name`.
+        #
         def index_name
           instance.class.tire.index_name
         end
 
+        # Proxy to instance method `document_type`.
+        #
         def document_type
           instance.class.tire.document_type
         end

data/lib/tire/model/percolate.rb

@@ -1,19 +1,61 @@
 module Tire
   module Model
 
+    # Contains support for the [percolation](http://www.elasticsearch.org/guide/reference/api/percolate.html)
+    # feature of _ElasticSearch_.
+    #
     module Percolate
 
       module ClassMethods
+
+        # Set up the percolation when documents are being added to the index.
+        #
+        # Usage:
+        #
+        #     class Article
+        #       # ...
+        #       percolate!
+        #     end
+        #
+        # First, you have to register a percolator query:
+        #
+        #     Article.index.register_percolator_query('fail')    { |query| query.string 'fail' }
+        #
+        # Then, when you update the index, matching queries are returned in the `matches` property:
+        #
+        #     p Article.create(:title => 'This is a FAIL!').matches
+        #
+        #
+        # You may pass a pattern to filter which percolator queries will be executed.
+        #
+        # See <http://www.elasticsearch.org/guide/reference/api/index_.html> for more information.
+        #
         def percolate!(pattern=true)
           @@_percolator = pattern
           self
         end
 
+        # A callback method for intercepting percolator matches.
+        #
+        # Usage:
+        #
+        #     class Article
+        #       # ...
+        #       on_percolate do
+        #         puts "Article title “#{title}” matches queries: #{matches.inspect}" unless matches.empty?
+        #       end
+        #     end
+        #
+        # Based on the response received in `matches`, you may choose to fire notifications,
+        # increment counters, send out e-mail alerts, etc.
+        #
         def on_percolate(pattern=true,&block)
           percolate!(pattern)
           klass.after_update_elasticsearch_index(block)
         end
 
+        # Returns the status or pattern of percolator for this class.
+        #
         def percolator
           defined?(@@_percolator) ? @@_percolator : nil
         end
@@ -21,14 +63,31 @@ module Tire
 
       module InstanceMethods
 
+        # Run this document against registered percolator queries, without indexing it.
+        #
+        # First, register a percolator query:
+        #
+        #     Article.index.register_percolator_query('fail')    { |query| query.string 'fail' }
+        #
+        # Then, you may query the percolator endpoint with:
+        #
+        #     p Article.new(:title => 'This is a FAIL!').percolate
+        #
+        # Optionally, you may pass a block to filter which percolator queries will be executed.
+        #
+        # See <http://www.elasticsearch.org/guide/reference/api/percolate.html> for more information.
         def percolate(&block)
           index.percolate instance, block
         end
 
+        # Mark this instance for percolation when adding it to the index.
+        #
         def percolate=(pattern)
           @_percolator = pattern
         end
 
+        # Returns the status or pattern of percolator for this instance.
+        #
         def percolator
           @_percolator || instance.class.tire.percolator || nil
         end

data/lib/tire/model/persistence.rb

@@ -1,6 +1,26 @@
 module Tire
   module Model
 
+    # Allows to use _ElasticSearch_ as a primary database (storage).
+    #
+    # Contains all the `Tire::Model::Search` features and provides
+    # an [_ActiveModel_](http://rubygems.org/gems/activemodel)-compatible
+    # interface for persistance.
+    #
+    # Usage:
+    #
+    #     class Article
+    #       include Tire::Model::Persistence
+    #     
+    #       property :title
+    #     end
+    #
+    #     Article.create :id => 1, :title => 'One'
+    #
+    #     article = Article.find
+    #
+    #     article.destroy
+    #
     module Persistence
 
       def self.included(base)

data/lib/tire/model/persistence/attributes.rb

@@ -3,12 +3,13 @@ module Tire
 
     module Persistence
 
+      # Provides infrastructure for declaring the model properties and accessing them.
+      #
       module Attributes
 
         module ClassMethods
 
           def property(name, options = {})
-            # p "#{self}, PERSISTENCE PROPERTY, #{name}"
             attr_accessor name.to_sym
             properties << name.to_s unless properties.include?(name.to_s)
             define_query_method      name.to_sym

data/lib/tire/model/persistence/finders.rb

@@ -3,6 +3,8 @@ module Tire
 
     module Persistence
 
+      # Provides infrastructure for an _ActiveRecord_-like interface for finding records.
+      #
       module Finders
 
         module ClassMethods

data/lib/tire/model/persistence/storage.rb

@@ -3,6 +3,8 @@ module Tire
 
     module Persistence
 
+      # Provides infrastructure for storing records in _ElasticSearch_.
+      #
       module Storage
 
         def self.included(base)

data/lib/tire/version.rb

@@ -1,5 +1,5 @@
 module Tire
-  VERSION   = "0.3.1"
+  VERSION   = "0.3.2"
 
   CHANGELOG =<<-END
     IMPORTANT CHANGES LATELY:

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 3
-  - 1
-  version: 0.3.1
+  - 2
+  version: 0.3.2
 platform: ruby
 authors: 
 - Karel Minarik
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-01 00:00:00 +02:00
+date: 2011-09-04 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -338,7 +338,7 @@ post_install_message: |
       When there's no conflict with existing methods, Tire methods are added
       to the class namespace, as well, so the change is 100% backwards-compatible.
   
-    See the full changelog at <http://github.com/karmi/tire/commits/v0.3.1>.
+    See the full changelog at <http://github.com/karmi/tire/commits/v0.3.2>.
   
   --------------------------------------------------------------------------------