couchrest_model/lib/couchrest/model/designs/view.rb

module CouchRest
  module Model
    module Designs

      #
      # A proxy class that allows view queries to be created using
      # chained method calls. After each call a new instance of the method
      # is created based on the original in a similar fashion to ruby's Sequel 
      # library, or Rails 3's Arel.
      #
      # CouchDB views have inherent limitations, so joins and filters as used in 
      # a normal relational database are not possible.
      #
      class View
        include Enumerable

        attr_accessor :owner, :model, :name, :query, :result

        # Initialize a new View object. This method should not be called from
        # outside CouchRest Model.
        def initialize(parent, new_query = {}, name = nil)
          if parent.is_a?(Class) && parent < CouchRest::Model::Base
            raise "Name must be provided for view to be initialized" if name.nil?
            self.model    = parent
            self.owner    = parent
            self.name     = name.to_s
            # Default options:
            self.query    = { }
          elsif parent.is_a?(self.class)
            self.model    = (new_query.delete(:proxy) || parent.model)
            self.owner    = parent.owner
            self.name     = parent.name
            self.query    = parent.query.dup
          else
            raise "View cannot be initialized without a parent Model or View"
          end
          query.update(new_query)
          super()
        end


        # == View Execution Methods
        #
        # Request to the CouchDB database using the current query values.
       
        # Return each row wrapped in a ViewRow object. Unlike the raw
        # CouchDB request, this will provide an empty array if there
        # are no results.
        def rows
          return @rows if @rows
          if execute && result['rows']
            @rows ||= result['rows'].map{|v| ViewRow.new(v, model)}
          else 
            [ ]
          end
        end

        # Fetch all the documents the view can access. If the view has
        # not already been prepared for including documents in the query,
        # it will be added automatically and reset any previously cached
        # results.
        def all
          include_docs!
          docs
        end

        # Provide all the documents from the view. If the view has not been
        # prepared with the +include_docs+ option, each document will be 
        # loaded individually.
        def docs
          @docs ||= rows.map{|r| r.doc}
        end

        # If another request has been made on the view, this will return 
        # the first document in the set. If not, a new query object will be
        # generated with a limit of 1 so that only the first document is 
        # loaded.
        def first
          result ? all.first : limit(1).all.first
        end

        # Same as first but will order the view in descending order. This
        # does not however reverse the search keys or the offset, so if you 
        # are using a +startkey+ and +endkey+ you might end up with 
        # unexpected results.
        #
        # If in doubt, don't use this method!
        #
        def last
          result ? all.last : limit(1).descending.all.last
        end

        # Return the number of documents in the currently defined result set.
        # Use <tt>#count</tt> for the total number of documents regardless
        # of the current limit defined.
        def length
          docs.length
        end

        # Perform a count operation based on the current view. If the view
        # can be reduced, the reduce will be performed and return the first
        # value. This is okay for most simple queries, but may provide
        # unexpected results if your reduce method does not calculate
        # the total number of documents in a result set.
        #
        # Trying to use this method with the group option will raise an error.
        #
        # If no reduce function is defined, a query will be performed 
        # to return the total number of rows, this is the equivalant of:
        #
        #    view.limit(0).total_rows
        #
        def count
          raise "View#count cannot be used with group options" if query[:group]
          if can_reduce?
            row = reduce.rows.first
            row.nil? ? 0 : row.value
          else
            limit(0).total_rows
          end
        end

        # Check to see if the array of documents is empty. This *will* 
        # perform the query and return all documents ready to use, if you don't
        # want to load anything, use +#total_rows+ or +#count+ instead.
        def empty?
          all.empty?
        end

        # Run through each document provided by the +#all+ method.
        # This is also used by the Enumerator mixin to provide all the standard
        # ruby collection directly on the view.
        def each(&block)
          all.each(&block)
        end

        # Wrapper for the results offset. As per the CouchDB API,
        # this may be nil if groups are used.
        def offset
          execute['offset']
        end

        # Wrapper for the total_rows value provided by the query. As per the
        # CouchDB API, this may be nil if groups are used.
        def total_rows
          execute['total_rows']
        end

        # Convenience wrapper to provide all the values from the route
        # set without having to go through +rows+.
        def values
          rows.map{|r| r.value}
        end

        # Accept requests as if the view was an array. Used for backwards compatibity
        # with older queries:
        #
        #    Model.all(:raw => true, :limit => 0)['total_rows']
        #
        # In this example, the raw option will be ignored, and the total rows
        # will still be accessible.
        # 
        def [](value)
          execute[value]
        end

        # No yet implemented. Eventually this will provide a raw hash
        # of the information CouchDB holds about the view.
        def info
          raise "Not yet implemented"
        end


        # == View Filter Methods
        # 
        # View filters return a copy of the view instance with the query 
        # modified appropriatly. Errors will be raised if the methods
        # are combined in an incorrect fashion.
        #

        # Find all entries in the index whose key matches the value provided.
        #
        # Cannot be used when the +#startkey+ or +#endkey+ have been set.
        def key(value)
          raise "View#key cannot be used when startkey or endkey have been set" unless query[:keys].nil? && query[:startkey].nil? && query[:endkey].nil?
          update_query(:key => value)
        end

        # Find all index keys that start with the value provided. May or may 
        # not be used in conjunction with the +endkey+ option.
        #
        # When the +#descending+ option is used (not the default), the start 
        # and end keys should be reversed, as per the CouchDB API.
        #
        # Cannot be used if the key has been set.
        def startkey(value)
          raise "View#startkey cannot be used when key has been set" unless query[:key].nil? && query[:keys].nil?
          update_query(:startkey => value)
        end

        # The result set should start from the position of the provided document. 
        # The value may be provided as an object that responds to the +#id+ call
        # or a string.
        def startkey_doc(value)
          update_query(:startkey_docid => value.is_a?(String) ? value : value.id)
        end

        # The opposite of +#startkey+, finds all index entries whose key is before
        # the value specified.
        #
        # See the +#startkey+ method for more details and the +#inclusive_end+
        # option.
        def endkey(value)
          raise "View#endkey cannot be used when key has been set" unless query[:key].nil? && query[:keys].nil?
          update_query(:endkey => value)
        end

        # The result set should end at the position of the provided document. 
        # The value may be provided as an object that responds to the +#id+ 
        # call or a string.
        def endkey_doc(value)
          update_query(:endkey_docid => value.is_a?(String) ? value : value.id)
        end

        # Keys is a special CouchDB option that will cause the view request to be POSTed
        # including an array of keys. Only documents with the matching keys will be 
        # returned. This is much faster than sending multiple requests for a set 
        # non-consecutive documents.
        #
        # If no values are provided, this method will act as a wrapper around 
        # the rows result set, providing an array of keys.
        def keys(*keys)
          if keys.empty?
            rows.map{|r| r.key}
          else
            raise "View#keys cannot by used when key or startkey/endkey have been set" unless query[:key].nil? && query[:startkey].nil? && query[:endkey].nil?
            update_query(:keys => keys.first)
          end
        end


        # The results should be provided in descending order.
        #
        # Descending is false by default, this method will enable it and cannot
        # be undone.
        def descending
          update_query(:descending => true)
        end

        # Limit the result set to the value supplied.
        def limit(value)
          update_query(:limit => value)
        end

        # Skip the number of entries in the index specified by value. This would be
        # the equivilent of an offset in SQL.
        #
        # The CouchDB documentation states that the skip option should not be used
        # with large data sets as it is inefficient. Use the +startkey_doc+ method
        # instead to skip ranges efficiently.
        def skip(value = 0)
          update_query(:skip => value)
        end

        # Use the reduce function on the view. If none is available this method
        # will fail. 
        def reduce
          raise "Cannot reduce a view without a reduce method" unless can_reduce?
          update_query(:reduce => true, :include_docs => nil)
        end

        # Control whether the reduce function reduces to a set of distinct keys
        # or to a single result row.
        #
        # By default the value is false, and can only be set when the view's 
        # +#reduce+ option has been set.
        def group
          raise "View#reduce must have been set before grouping is permitted" unless query[:reduce]
          update_query(:group => true)
        end

        # Will set the level the grouping should be performed to. As per the 
        # CouchDB API, it only makes sense when the index key is an array.
        # 
        # This will automatically set the group option.
        def group_level(value)
          group.update_query(:group_level => value.to_i)
        end

        def include_docs
          update_query.include_docs!
        end

        ### Special View Filter Methods

        # Specify the database the view should use. If not defined,
        # an attempt will be made to load its value from the model.
        def database(value)
          update_query(:database => value)
        end

        # Set the view's proxy that will be used instead of the model
        # for any future searches. As soon as this enters the
        # new object's initializer it will be removed and replace
        # the model object.
        #
        # See the Proxyable mixin for more details.
        #
        def proxy(value)
          update_query(:proxy => value)
        end

        # Return any cached values to their nil state so that any queries
        # requested later will have a fresh set of data.
        def reset!
          self.result = nil
          @rows = nil
          @docs = nil
        end

        # == Kaminari compatible pagination support
        #
        # Based on the really simple support for scoped pagination in the
        # the Kaminari gem, we provide compatible methods here to perform
        # the same actions you'd expect.
        #

        def page(page)
          limit(owner.default_per_page).skip(owner.default_per_page * ([page.to_i, 1].max - 1))
        end

        def per(num)
          raise "View#page must be called before #per!" if limit_value.nil? || offset_value.nil?
          if (n = num.to_i) <= 0
            self
          else
            limit(num).skip(offset_value / limit_value * n)
          end
        end

        def total_count
          @total_count ||= limit(nil).skip(nil).count
        end

        def offset_value
          query[:skip]
        end

        def limit_value
          query[:limit]
        end

        def num_pages
          (total_count.to_f / limit_value).ceil
        end

        def current_page
          (offset_value / limit_value) + 1
        end

        protected

        def include_docs!
          raise "Cannot include documents in view that has been reduced!" if query[:reduce]
          reset! if result && !include_docs?
          query[:include_docs] = true
          self
        end

        def include_docs?
          !!query[:include_docs]
        end

        def update_query(new_query = {})
          self.class.new(self, new_query)
        end

        def design_doc
          model.design_doc
        end

        def can_reduce?
          !design_doc['views'][name]['reduce'].blank?
        end

        def use_database
          query[:database] || model.database
        end

        def execute
          return self.result if result
          raise "Database must be defined in model or view!" if use_database.nil?

          # Remove the reduce value if its not needed
          query.delete(:reduce) unless can_reduce?

          # Save the design doc for the current database. This should be efficient
          # and check for changes
          model.save_design_doc(use_database)

          self.result = model.design_doc.view_on(use_database, name, query.reject{|k,v| v.nil?})
        end

        # Class Methods
        class << self
          # Simplified view creation. A new view will be added to the 
          # provided model's design document using the name and options.
          #
          # If the view name starts with "by_" and +:by+ is not provided in 
          # the options, the new view's map method will be interpreted and
          # generated automatically. For example:
          #
          #   View.create(Meeting, "by_date_and_name")
          #
          # Will create a view that searches by the date and name properties. 
          # Explicity setting the attributes to use is possible using the 
          # +:by+ option. For example:
          #
          #   View.create(Meeting, "by_date_and_name", :by => [:date, :firstname, :lastname])
          #
          # The view name is the same, but three keys would be used in the
          # subsecuent index.
          #
          # By default, a check is made on each of the view's keys to ensure they
          # do not contain a nil value ('null' in javascript). This is probably what
          # you want in most cases but sometimes in can be useful to create an
          # index where nil is permited. Set the <tt>:allow_nil</tt> option to true to
          # remove this check.
          #
          # Conversely, keys are not checked to see if they are empty or blank. If you'd
          # like to enable this, set the <tt>:allow_blank</tt> option to false. The default
          # is true, empty strings are permited in the indexes.
          #
          def create(model, name, opts = {})

            unless opts[:map]
              if opts[:by].nil? && name.to_s =~ /^by_(.+)/
                opts[:by] = $1.split(/_and_/)
              end

              raise "View cannot be created without recognised name, :map or :by options" if opts[:by].nil?

              opts[:allow_blank] = opts[:allow_blank].nil? ? true : opts[:allow_blank]
              opts[:guards] ||= []
              opts[:guards].push "(doc['#{model.model_type_key}'] == '#{model.to_s}')"

              keys = opts[:by].map{|o| "doc['#{o}']"}
              emit = keys.length == 1 ? keys.first : "[#{keys.join(', ')}]"
              opts[:guards] += keys.map{|k| "(#{k} != null)"} unless opts[:allow_nil]
              opts[:guards] += keys.map{|k| "(#{k} != '')"} unless opts[:allow_blank]
              opts[:map] = <<-EOF
                function(doc) {
                  if (#{opts[:guards].join(' && ')}) {
                    emit(#{emit}, 1);
                  }
                }
              EOF
              opts[:reduce] = <<-EOF
                function(key, values, rereduce) {
                  return sum(values);
                }
              EOF
            end

            model.design_doc['views'] ||= {}
            view = model.design_doc['views'][name.to_s] = { }
            view['map'] = opts[:map]
            view['reduce'] = opts[:reduce] if opts[:reduce]
            view
          end

        end

      end

      # A special wrapper class that provides easy access to the key
      # fields in a result row.
      class ViewRow < Hash
        attr_reader :model
        def initialize(hash, model)
          @model    = model
          replace(hash)
        end
        def id
          self["id"]
        end
        def key
          self["key"]
        end
        def value
          self['value']
        end
        def raw_doc
          self['doc']
        end
        # Send a request for the linked document either using the "id" field's
        # value, or the ["value"]["_id"] used for linked documents.
        def doc
          return model.build_from_database(self['doc']) if self['doc']
          doc_id = (value.is_a?(Hash) && value['_id']) ? value['_id'] : self.id
          doc_id ? model.get(doc_id) : nil
        end
      end

    end
  end
end