stretchy 0.3.6 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5822801c4cec4719808f4679f787570f97524b29
-  data.tar.gz: 4684f243aee61ab42f4cc0032163301674afe5df
+  metadata.gz: 6d19628e7bb3b4177002806dee9ae3cd41e67340
+  data.tar.gz: cdb6536ac2450f5f8f01a6efab5071c0bb88e9f8
 SHA512:
-  metadata.gz: 5ab85cf648c091546af556e5a4d86efa91f92889fdc155496be089087f546b8b1b0da6cc72e3868fde31f4b9178b8371211bf96f5deda5f730b2f6fe4af4c2c3
-  data.tar.gz: 21ccd5b5e9178dddd2c9a5fefe1ce056a56458a62b9d3f3a0777b225c6bb3756c2a8788909b5822f419343e8d9d03567fe06cdb39ac1ff7840351b8062c3232e
+  metadata.gz: 1fb125ae7d1763bd44c2fef081d3a1ab2d3ae4e5a9289341e32b98617bd26dd667a387333b38d97ae6942da519d980ac380b28b738c12c80345e174c19b6f1d4
+  data.tar.gz: 1aa29437d28d4dcd4e85840d161f068f09569b2b3f4c008886cdebc1dc005eb50fc9d4aca120c21611b777721bfe971fa3daa4b7da3a116d006a6d54fbcd9960

data/.yardopts

@@ -0,0 +1 @@
+-m markdown lib/**/*.rb - README.md

data/README.md

@@ -33,10 +33,27 @@ Or install it yourself as:
 
 Stretchy is still in early development, so it does not yet support the full feature set of the [Elasticsearch API](http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html). It does support fairly basic queries in an ActiveRecord-ish style.
 
+### Configuration
+
+```ruby
+Stretchy.configure do |c|
+  c.index_name = 'my_index'                       # REQUIRED
+  c.client     = $my_client                       # ignore below, use a custom client
+  c.url        = 'https://user:pw@my.elastic.url' # default is ENV['ELASTICSEARCH_URL']
+  c.adapter    = :patron                          # default is :excon
+
+  c.logger     = Logger.new(STDOUT)               # passed to elasticsearch-api gem
+                                                  # Stretchy will also log, with the params
+                                                  # specified below
+  c.log_level  = :debug                           # default is :silence
+  c.log_color  = :green                           # default is :blue 
+end
+```
+
 ### Base
 
 ```ruby
-query = Stretchy::Query.new(index: 'app_production', type: 'model_name')
+query = Stretchy.query(type: 'model_name')
 ```
 
 From here, you can chain the following query methods:
@@ -44,57 +61,43 @@ From here, you can chain the following query methods:
 ### Match
 
 ```ruby
-query = query.match('welcome to my web site')
-query = query.match('welcome to my web site', field: 'title', operator: 'or')
+query = query.match('welcome to my web site').match(title: 'welcome to my web site')
 ```
 
-Performs a full-text search for the given string. `field` and `operator` are optional, and default to `_all` and `and` respectively.
-
-#### Variants
-
-* `not_match` - filters for documents not matching a full-text search
+Performs a full-text search for the given string. If given a hash, it will use a match query on the specified fields, otherwise it will default to `'_all'`.
 
 
 ### Where
 
 ```ruby
 query = query.where(
-  name: 'Exact Name',
+  name: 'alice',
   email: [
-    'exact@email.com',
-    'another.user.with.same.name@email.com'
-  ]
+    'alice@company.com',
+    'beatrice.christine@other_company.com'
+  ],
+  commit_count: 27..33,
+  is_robot: nil
 )
 ```
 
-Allows passing a hash of matchable options in `field: [values]` format. If any one of the values matches, that field will be considered matched. All fields must match for a document to be returned. See the [Terms filter](http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-terms-filter.html) for more details.
-
-If you pass `field: nil`, Stretchy will construct the relevant `not { exists: field }` filter and apply it as expected.
+Allows passing a hash of matchable options similar to ActiveRecord's `where` method. To be returned, the document must match each of the parameters. If you pass an array of parameters for a field, the document must match at least one of those parameters.
 
 #### Gotcha
 
-Matches _must_ be exact; the values you pass in here are not analyzed by Elasticsearch, while the values stored in the index are (unless you turned analysis off for that field).
-
-#### Variants
-
-* `not_where` - filters for documents *not* matching the criteria
-* `boost_where` - boosts the relevance score for matching documents
-* `boost_not_where` - boosts the relevance score for documents not matching the criteria
+If you pass a string or symbol for a field, it will be converted to a [Match Query](http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query.html) for the specified field. Since Elastic analyzes terms by default, string or symbol terms will be looked for by an analyzed query.
 
 ### Range
 
 ```ruby
-query = query.range(field: 'rating', min: 3, max: 5)
+query = query.range(:rating, min: 3, max: 5)
+             .range(:released, min: Time.now - 60*60*24*100)
+             .range(:quantity, max: 100, exclusive: true)
 ```
 
-Only documents with the specified field, and within the specified range (inclusive) match. You can also pass in dates and times as ranges. Currently, you must pass both a min and a max value.
-
-#### Variants
+Only documents with the specified field, and within the specified range match. You can also pass in dates and times as ranges. While you could pass a normal ruby `Range` object to `.where`, this allows you to specify only a minimum or only a maximum. Range filters are inclusive by default, but you can also pass `:exclusive`, `:exclusive_min`, or `:exclusive_max`.
 
-* `not_range` - filters for only documents where the field is *outside* the given range
-* `boost_range` - boosts the relevance score for matching documents
-
-### Geo
+### Geo Distance
 
 ```ruby
 query = query.geo(field: 'coords', distance: '20mi', lat: 35.0117, lng: 135.7683)
@@ -106,34 +109,63 @@ Filters for documents where the specified `geo_point` field is within the given
 
 The field must be mapped as a `geo_point` field. See [Elasticsearch types](http://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-geo-point-type.html) for more info.
 
-#### Variants
+### Not
+
+```ruby
+query = query.where.not(rating: 0)
+             .match.not('angry')
+             .where.not.geo(field: 'coords', distance: '20mi', lat: 35.0117, lng: 135.7683)
+```
 
-* `not_geo` - filters for documents outside the specified range
-* `boost_geo` - boosts the relevance score for documents based on how far from the given point they are
+Called after `where` or `match` will let you apply inverted filters. Any documents that match those filters will be excluded.
 
-### Limit and Offset
+### Should
 
 ```ruby
-query = query.limit(20).offset(1000)
+query = query.should(name: 'Sarah', awesomeness: 1000).should.not(awesomeness: 0)
 ```
 
-Works the same way as ActiveRecord's limit and offset methods.
+Should filters work similarly to `.where`. Documents that do not match are still returned, but they have a lower relevancy score and will appear after documents that do match in the results. See Elastic's documentation for [BoolQuery](http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-bool-query.html) and [BoolFilter](http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-bool-filter.html) for more info.
 
-### Boost Random
+### Boost
 
 ```ruby
-query = query.boost_random(user.id, 1.4)
+query = query.boost.where(category: 3, weight: 100)
+             .boost.range(:awesomeness, min: 10, weight: 10)
+             .boost.match.not('sucks')
 ```
 
-Provides a random-but-deterministic boost to relevance scores. The first parameter is required, and represents the random seed. The second parameter is optional, and represents the weight for the random factor. See [Random Scoring](http://www.elastic.co/guide/en/elasticsearch/guide/master/random-scoring.html) for more details.
+Boosts use a [Function Score Query](http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-function-score-query.html) with filters to allow you to affect the score for the document. Each condition will be applied as a filter with an optional weight.
 
-### Explain
+
+### Near
+
+```ruby
+query = query.boost.near(field: :published_at, origin: Time.now, scale: '5d')
+             .boost.near(field: :coords, lat: 35.0117, lng: 135.7683, scale: '10mi', decay: 0.33, weight: 1000)
+```
+
+Boosts a document by how close a given field is to a given `:origin` . Accepts dates, times, numbers, and geographical points. Unlike `.where.range` or `.boost.geo`, `.boost.near` is not a binary operation. All documents get a score for that field, which decays the further it is away from the origin point. 
+
+The `:scale` param determines how quickly the value falls off. In the example above, if a document's `:coords` field is 10 miles away from the starting point, its score is about 1/3 that of a document at the origin point.
+
+See the [Function Score Query](http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-function-score-query.html) section on Decay Functions for more info.
+
+### Random
 
 ```ruby
-query = query.explain.results
+query = query.boost.random(user.id, 50)
 ```
 
-Provides Elasticsearch explanation results in `query.response` . See [the explain documentation](http://www.elastic.co/guide/en/elasticsearch/reference/1.x/search-explain.html) for more info.
+Gives each document a randomized boost with a given seed and optional weight. This allows you to show slightly different result sets to different users, but show the same result set to that user every time.
+
+### Limit and Offset
+
+```ruby
+query = query.limit(20).offset(1000)
+```
+
+Works the same way as ActiveRecord's limit and offset methods - analogous to Elasticsearch's `from` and `size` parameters.
 
 ### Response
 
@@ -149,7 +181,7 @@ Executes the query, returns the raw JSON response from Elasticsearch and caches
 query.results
 ```
 
-Executes the query and provides the parsed json for each hit returned by Elasticsearch. 
+Executes the query and provides the parsed json for each hit returned by Elasticsearch, along with `_index`, `_type`, `_id`, and `_score` fields.
 
 ### Ids
 
@@ -157,9 +189,7 @@ Executes the query and provides the parsed json for each hit returned by Elastic
 query.ids
 ```
 
-Provides only the ids for each hit. If your document ids are numeric (as is the case for most ActiveRecord-integrated documents), they will be converted to integers.
-
-This is somewhat intelligent - if you have already called `results` the ids will be fetched from there, otherwise it will run the search and skip the data-fetch phase in Elasticsearch.
+Provides only the ids for each hit. If your document ids are numeric (as is the case for many ActiveRecord integrations), they will be converted to integers.
 
 ### Total
 

data/lib/stretchy/clauses/base.rb

@@ -1,5 +1,17 @@
 module Stretchy
   module Clauses
+    # A Clause is the basic unit of Stretchy's chainable query syntax.
+    # Think of it as a state machine, with transitions between states
+    # being handled by methods that return another Clause. When you
+    # call the `where` method, it stores the params passed as an 
+    # internal representation, to be compiled down to the Elastic query
+    # syntax, and returns a WhereClause. The WhereClause reflects the
+    # current state of the query, and gives you access to methods like
+    # `range` and `geo` to add more specific filters. It inherits
+    # other methods from the Base class, allowing other transitions.
+    #
+    # Attributes are copied when a new Clause is instanciated, so
+    # the underlying storage is maintained throughout the chain.
     class Base
 
       extend Forwardable
@@ -14,6 +26,19 @@ module Stretchy
                 :took, :shards, :total, :max_score] => :query_results
       delegate [:range, :geo] => :where
 
+      #
+      # Generates a chainable query. The only required option for the
+      # first initialization is `:type` , which specifies what type
+      # to query on your index.
+      # 
+      # @overload initialize(base_or_opts, options)
+      #   @param base [Base] another clause to copy attributes from
+      #   @param options [Hash] options to set on the new state
+      # 
+      # @overload initialize(base_or_opts)
+      #   @option base_or_opts [String] :index        The Elastic index to query
+      #   @option base_or_opts [String] :type         The Lucene type to query on
+      #   @option base_or_opts [true, false] :inverse Whether we are in a `not` context
       def initialize(base_or_opts = nil, options = {})
         if base_or_opts && !base_or_opts.is_a?(Hash)
           base                = base_or_opts
@@ -26,6 +51,7 @@ module Stretchy
           @inverse            = options[:inverse] || base.inverse
           @limit              = base.get_limit
           @offset             = base.get_offset
+          @explain            = base.get_explain
         else
           options = Hash(base_or_opts).merge(options)
           @index_name         = options[:index] || Stretchy.index_name
@@ -40,38 +66,128 @@ module Stretchy
         end
       end
 
+      # 
+      # Sets how many results to return, similar to
+      # ActiveRecord's limit method.
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html Elastic Docs - Request Body Search
+      # 
+      # @param num [Integer] How many results to return
+      # 
+      # @return [self]
       def limit(num)
         @limit = num
         self
       end
 
+      # 
+      # Accessor for `@limit`
+      # 
+      # @return [Integer] Value of `@limit`
       def get_limit
         @limit
       end
 
+      # 
+      # Sets the offset to start returning results at.
+      # Corresponds to Elastic's "from" parameter
+      # 
+      # @param num [Integer] Offset for query
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html Elastic Docs - Request Body Search
+      # 
+      # @return [self]
       def offset(num)
         @offset = num
         self
       end
 
+      # 
+      # Accessor for `@offset`
+      # 
+      # @return [Integer] Offset for query
       def get_offset
         @offset
       end
 
+      # 
+      # Tells the search to explain the scoring
+      # mechanism for each document.
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-explain.html Elastic Docs - Request Body Search (explain)
+      # 
+      # @return [self] Allows continuing the query chain
+      def explain
+        @explain = true
+        self
+      end
+
+      def get_explain
+        !!@explain
+      end
+
+      # 
+      # Used for fulltext searching. Works similarly
+      # to {#where} .
+      # 
+      # @param options = {} [Hash] Options to be passed to 
+      #   the MatchClause
+      # 
+      # @return [MatchClause] query state with fulltext matches
+      # 
+      # @see MatchClause#initialize
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query.html Elastic Docs - Match Query
       def match(options = {})
         MatchClause.new(self, options)
       end
       alias :fulltext :match
 
+      # 
+      # Used for filtering results. Works similarly to
+      # ActiveRecord's `where` method.
+      # 
+      # @param options = {} [Hash] Options to be passed to
+      #   the {WhereClause}
+      # 
+      # @return [WhereClause] query state with filters
+      # 
+      # @see  WhereClause#initialize
       def where(options = {})
         WhereClause.new(self, options)
       end
       alias :filter :where
 
+      # 
+      # Used for boosting the relevance score of
+      # search results. Options passed here correspond
+      # to `where`-style filters which boost a document
+      # if matched.
+      # 
+      # @param options = {} [type] [description]
+      # 
+      # @return [BoostClause] query in boost context
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-function-score-query.html Elastic Docs - Function Score Query
       def boost(options = {})
         BoostClause.new(self, options)
       end
 
+      # 
+      # Inverts the current context - the next method
+      # called, such as {#where} or {#match} will generate
+      # a filter specifying the document **does not**
+      # match the specified filter.
+      # 
+      # @overload not(string)
+      #   @param [String] A string that must not be anywhere
+      #                   in the document
+      # 
+      # @overload not(opts_or_string)
+      #   @param [Hash] Options to be passed to an inverted {WhereClause}
+      # 
+      # @return [Base] A {WhereClause}, or a {MatchClause} if only a string 
+      #   is given (ie, doing a full-text search across the whole document)
       def not(opts_or_string = {}, opts = {})
         if opts_or_string.is_a?(Hash)
           WhereClause.new(self, opts_or_string.merge(inverse: true))
@@ -80,6 +196,24 @@ module Stretchy
         end
       end
 
+      # 
+      # Adds filters in the `should` context. Operates just like
+      # {#where}, but these filters only serve to add to the 
+      # relevance score of the returned documents, rather than
+      # being required to match.
+      # 
+      # @overload  should(opts_or_string)
+      #   @param [String] A string to match via full-text search 
+      #     anywhere in the document.
+      # 
+      # @overload should(opts_or_string)
+      #   @param [Hash] Options to generate filters.
+      # 
+      # @return [WhereClause] current query state with should clauses applied
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-bool-query.html Elastic Docs - Bool Query
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-bool-filter.html Elastic Docs - Bool Filter
       def should(opts_or_string = {}, opts = {})
         if opts_or_string.is_a?(Hash)
           WhereClause.new(self, opts_or_string.merge(should: true))
@@ -88,10 +222,22 @@ module Stretchy
         end
       end
 
+      # 
+      # Accessor for `@inverse`
+      # 
+      # @return [true, false] If current context is inverse
       def inverse?
         !!@inverse
       end
 
+      # 
+      # Compiles the internal representation of your filters,
+      # full-text queries, and boosts into the JSON to be 
+      # passed to Elastic. If you want to know exactly what
+      # your query generated, you can call this method.
+      # 
+      # @return [Hash] the query hash to be compiled to json 
+      #   and sent to Elastic
       def to_search
         return @to_search if @to_search
         
@@ -108,6 +254,12 @@ module Stretchy
         @to_search = @to_search.to_search
       end
 
+      # 
+      # The Results object for this query, which handles
+      # sending the search request and providing convienent
+      # accessors for the response.
+      # 
+      # @return [Results::Base] The results returned from Elastic
       def query_results
         @query_results ||= Stretchy::Results::Base.new(self)
       end

data/lib/stretchy/clauses/boost_clause.rb

@@ -2,27 +2,124 @@ require 'stretchy/clauses/base'
 
 module Stretchy
   module Clauses
+      # 
+      # A Boost clause encapsulates the boost query state. It
+      # basically says "the next where / range / match filter
+      # will be used to boost a document's score instead of
+      # selecting documents to return."
+      # 
+      # Calling `.boost` by itself doesn't do anything, but
+      # the next method (`.near`, `.match`, etc) will specify
+      # a boost using the same syntax as other clauses. These
+      # methods take a `:weight` parameter specifying the weight 
+      # to assign that boost.
+      # 
+      # @author [atevans]
+      # 
     class BoostClause < Base
 
       extend Forwardable
 
       delegate [:geo, :range] => :where
 
+      # 
+      # Switch to the boost state, specifying that
+      # the next where / range / etc will be a boost
+      # instead of a regular filter / range / etc.
+      # 
+      # @param base [Base] a clause to copy query state from
+      # @param options = {} [Hash] Options for the boost clause
+      # @option options [true, false] :inverse (nil) If this boost should also be in the inverse state
+      # 
       def initialize(base, options = {})
         super(base)
         @inverse = options.delete(:inverse)
       end
 
+      # 
+      # Changes query state to "match" in the context
+      # of boosting. Options here work the same way as
+      # {MatchClause#initialize}, but the combined query
+      # will be applied as a boost function.
+      # 
+      # @param options = {} [Hash] options for full text matching
+      # 
+      # @return [BoostMatchClause] query with boost match state
       def match(options = {})
         BoostMatchClause.new(self, options)
       end
       alias :fulltext :match
 
+      # 
+      # Changes query state to "where" in the context
+      # of boosting. Works the same way as {WhereClause},
+      # but applies the generated filters as a boost
+      # function. 
+      # 
+      # @param options = {} [Hash] Filters to use in this boost.
+      # 
+      # @return [BoostWhereClause] Query state with boost filters applied
+      # 
       def where(options = {})
         BoostWhereClause.new(self, options)
       end
       alias :filter :where
 
+      # 
+      # Adds a {Boosts::FieldDecayBoost}, which boosts
+      # a search result based on how close it is to a 
+      # specified value. That value can be a date, time,
+      # number, or {Types::GeoPoint}
+      # 
+      # Required:
+      # 
+      # * `:field`
+      # * `:origin` or `:lat` & `:lng` combo
+      # * `:scale`
+      # 
+      # @option options [Numeric] :field What field to check with this boost
+      # @option options [Date, Time, Numeric, Types::GeoPoint] :origin Boost score based on how close the field is to this value. Required unless {Types::GeoPoint} is present (:lat, :lng, etc)
+      # @option options [Numeric] :lat Latitude, for a geo point
+      # @option options [Numeric] :latitude Latitude, for a geo point
+      # @option options [Numeric] :lng Longitude, for a geo point
+      # @option options [Numeric] :lon Longitude, for a geo point
+      # @option options [Numeric] :longitude Longitude, for a geo point
+      # @option options [String] :scale When the field is this distance from origin, the boost will be multiplied by `:decay` . Default is 0.5, so when `:origin` is a geo point and `:scale` is '10mi', then this boost will be twice as much for a point at the origin as for one 10 miles away
+      # @option options [String] :offset Anything within this distance of the origin is boosted as if it were at the origin
+      # @option options [Symbol] :type (:gauss) What type of decay to use. One of `:linear`, `:exp`, or `:gauss` 
+      # @option options [Numeric] :decay (0.5) How much the boost falls off when it is `:scale` distance from `:origin`
+      # @option options [Numeric] :weight (1.2) How strongly to weight this boost compared to others
+      # 
+      # @example Boost near a geo point
+      #   query.boost.near(
+      #     field: :coords,
+      #     distance: '27km',
+      #     scale: '3mi',
+      #     lat: 33.3,
+      #     lng: 28.2
+      #   )
+      # 
+      # @example Boost near a date
+      #   query.boost.near(
+      #     field: :published_at,
+      #     origin: Time.now,
+      #     scale: '3d'
+      #   )
+      # 
+      # @example Boost near a number (with options)
+      #   query.boost.near(
+      #     field: :followers,
+      #     origin: 100,
+      #     scale: 50,
+      #     offset: 2,
+      #     type: :linear,
+      #     decay: 0.75,
+      #     weight: 10
+      #   )
+      # 
+      # @return [Base] Query with field decay filter added
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-function-score-query.html Elastic Docs - Function Score Query
       def near(options = {})
         if options[:lat] || options[:latitude]  ||
            options[:lng] || options[:longitude] || options[:lon]
@@ -34,31 +131,73 @@ module Stretchy
       end
       alias :geo :near
 
+      # 
+      # Adds a {Boosts::RandomBoost} to the query, for slightly
+      # randomizing search results.
+      # 
+      # @param seed [Numeric] The seed for the random value
+      # @param weight [Numeric] The weight for this random value
+      # 
+      # @return [Base] Query with random boost applied
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/guide/master/random-scoring.html Elastic Docs - Random Scoring
       def random(*args)
         @boost_builder.functions << Stretchy::Boosts::RandomBoost.new(*args)
         Base.new(self)
       end
 
+      # 
+      # Defines a global boost for all documents in the query
+      # 
+      # @param num [Numeric] Boost to apply to the whole query
+      # 
+      # @return [self] Boost context with overall boost applied
       def all(num)
         @boost_builder.overall_boost = num
         self
       end
 
+      # 
+      # The maximum boost that any document can have
+      # 
+      # @param num [Numeric] Maximum score a document can have
+      # 
+      # @return [self] Boost context with maximum score applied
       def max(num)
         @boost_builder.max_boost = num
         self
       end
 
+      # 
+      # Set scoring mode for when a document matches multiple
+      # boost functions.
+      # 
+      # @param mode [Symbol] Score mode. Can be one of `multiply sum avg first max min`
+      # 
+      # @return [self] Boost context with score mode applied
       def score_mode(mode)
         @boost_builder.score_mode = mode
         self
       end
 
+      # 
+      # Set boost mode for when a document matches multiple
+      # boost functions.
+      # 
+      # @param mode [Symbol] Boost mode. Can be one of `multiply replace sum avg max min`
+      # 
+      # @return [self] Boost context with boost mode applied
       def boost_mode(mode)
         @boost_builder.boost_mode = mode
         self
       end
 
+      # 
+      # Switches to inverse context - boosts added with {#where} 
+      # and #{match} will be applied to documents which *do not*
+      # match said filters.
+      # 
+      # @return [BoostClause] Boost clause in inverse context
       def not(options = {})
         self.class.new(self, options.merge(inverse: !inverse?))
       end