cequel 1.0.0.rc1 → 1.0.0.rc2

data/lib/cequel/record/belongs_to_association.rb

@@ -1,31 +1,58 @@
 module Cequel
-
   module Record
-
+    #
+    # Represents a parent association declared by
+    # {Associations::ClassMethods#belongs_to belongs_to}
+    #
+    # @see Associations::ClassMethods#parent_association
+    # @since 1.0.0
+    #
     class BelongsToAssociation
-
       extend Forwardable
 
-      attr_reader :owner_class, :name, :association_class_name
+      # @return [Class] child class that declared `belongs_to`
+      attr_reader :owner_class
+      # @return [Symbol] name of the association
+      attr_reader :name
+      # @return [String] name of parent class
+      attr_reader :association_class_name
 
+      # @!attribute [r] association_key_columns
+      #   @return [Array<Schema::Column>] key columns on the parent class
       def_delegator :association_class, :key_columns, :association_key_columns
 
+      #
+      # @param owner_class [Class] child class that declared `belongs_to`
+      # @param name [Symbol] name of the association
+      # @param options [Options] options for association
+      # @option options [String] :class_name name of parent class
+      #
+      # @api private
+      #
       def initialize(owner_class, name, options = {})
+        options.assert_valid_keys(:class_name)
+
         @owner_class, @name = owner_class, name.to_sym
         @association_class_name =
           options.fetch(:class_name, @name.to_s.classify)
       end
 
+      #
+      # @return [Class] parent class declared by `belongs_to`
+      #
       def association_class
         @association_class ||= association_class_name.constantize
       end
 
+      #
+      # @return [Symbol] instance variable name to use for storing the parent
+      #   instance in a record
+      #
+      # @api private
+      #
       def instance_variable_name
         @instance_variable_name ||= :"@#{name}"
       end
-
     end
-
   end
-
 end

data/lib/cequel/record/bound.rb

@@ -1,15 +1,33 @@
 module Cequel
-
   module Record
-
+    #
+    # An upper or lower bound for a range query.
+    #
+    # @abstract Subclasses must implement the `to_cql` method, and may override
+    #   the `operator` and `bind_value` methods.
+    #
+    # @api private
+    # @since 1.0.0
+    #
     class Bound
-      attr_reader :column, :value
-
+      # @return [Schema::Column] column bound applies to
+      attr_reader :column
+      # @return value for bound
+      attr_reader :value
+
+      #
+      # Create a bound object for the given column. This method returns an
+      # instance of the appropriate `Bound` subclass given the type of the
+      # column and the class of the value.
+      #
+      # @param (see #initialize)
+      # @return [Bound] instance of appropriate bound implementation
+      #
       def self.create(column, gt, inclusive, value)
         implementation =
           if column.partition_key?
             PartitionKeyBound
-          elsif column.type?(Type::Timeuuid) && !value.is_a?(CassandraCQL::UUID)
+          elsif column.type?(:timeuuid) && !value.is_a?(CassandraCQL::UUID)
             TimeuuidBound
           else
             ClusteringColumnBound
@@ -18,27 +36,47 @@ module Cequel
         implementation.new(column, gt, inclusive, value)
       end
 
+      #
+      # @param column [Schema::Column] column bound applies to
+      # @param gt [Boolean] `true` if this is a lower bound
+      # @param inclusive [Boolean] `true` if this is an inclusive bound
+      # @param value value for bound
+      #
       def initialize(column, gt, inclusive, value)
         @column, @gt, @inclusive, @value = column, gt, inclusive, value
       end
 
+      #
+      # @return [Array] pair containing CQL string and bind value
+      #
       def to_cql_with_bind_variables
         [to_cql, bind_value]
       end
 
-
+      #
+      # @return [Boolean] `true` if this is a lower bound
+      #
       def gt?
         !!@gt
       end
 
+      #
+      # @return [Boolean] `true` if this is an upper bound
+      #
       def lt?
         !gt?
       end
 
+      #
+      # @return [Boolean] `true` if this is an inclusive bound
+      #
       def inclusive?
         !!@inclusive
       end
 
+      #
+      # @return [Boolean] `true` if this is an exclusive bound
+      #
       def exclusive?
         !inclusive?
       end
@@ -56,28 +94,49 @@ module Cequel
       def base_operator
         lt? ? '<' : '>'
       end
-
     end
 
+    #
+    # A bound on a partition key.
+    #
+    # @api private
+    # @since 1.0.0
+    #
     class PartitionKeyBound < Bound
+      protected
+
       def to_cql
         "TOKEN(#{column.name}) #{operator} TOKEN(?)"
       end
     end
 
+    #
+    # A bound on a clustering column.
+    #
+    # @api private
+    # @since 1.0.0
+    #
     class ClusteringColumnBound < Bound
+      protected
+
       def to_cql
         "#{column.name} #{operator} ?"
       end
     end
 
-    class TimeuuidBound < Bound
+    #
+    # A bound on a column of type `timeuuid` whose bound value is a `timestamp`
+    #
+    # @api private
+    # @since 1.0.0
+    #
+    class TimeuuidBound < ClusteringColumnBound
+      protected
+
       def to_cql
         "#{column.name} #{operator} #{function}(?)"
       end
 
-      protected
-
       def operator
         base_operator
       end
@@ -95,7 +154,5 @@ module Cequel
         lt? ^ exclusive? ? 'maxTimeuuid' : 'minTimeuuid'
       end
     end
-
   end
-
 end

data/lib/cequel/record/bulk_writes.rb

@@ -1,14 +1,42 @@
 module Cequel
   module Record
+    #
+    # This module implements bulk update and delete functionality for classes
+    # that expose a collection of result rows.
+    #
+    # @abstract Including modules must implement `key_attributes_for_each_row`,
+    #   which should yield successive fully-specified key attributes for each
+    #   result row.
+    #
+    # @since 1.0.0
+    #
     module BulkWrites
+      #
+      # Update all matched records with the given column values, without
+      # executing callbacks.
+      #
+      # @param attributes [Hash] map of column names to values
+      # @return [void]
+      #
       def update_all(attributes)
         each_data_set { |data_set| data_set.update(attributes) }
       end
 
+      #
+      # Delete all matched records without executing callbacks
+      #
+      # @return [void]
+      #
       def delete_all
         each_data_set { |data_set| data_set.delete }
       end
 
+      #
+      # Destroy all matched records, executing destroy callbacks for each
+      # record.
+      #
+      # @return [void]
+      #
       def destroy_all
         each { |record| record.destroy }
       end
@@ -17,7 +45,7 @@ module Cequel
 
       def each_data_set
         key_attributes_for_each_row.each_slice(100) do |batch|
-          connection.batch(:unlogged => true) do
+          connection.batch(unlogged: true) do
             batch.each { |key_attributes| yield table.where(key_attributes) }
           end
         end

data/lib/cequel/record/callbacks.rb

@@ -1,9 +1,26 @@
 module Cequel
-
   module Record
-
+    #
+    # Cequel::Record models provide lifecycle callbacks for `create`, `update`,
+    # `save`, `destroy`, and `validation`.
+    #
+    # @example
+    #   class User
+    #     include Cequel::Record
+    #
+    #     key :login, :text
+    #     column :name, :text
+    #
+    #     after_create :send_welcome_email
+    #     after_update :reindex_posts_for_search
+    #     after_save :reindex_for_search
+    #     after_destroy :send_farewell_email
+    #     before_validation :set_permalink
+    #   end
+    #
+    # @since 0.1.0
+    #
     module Callbacks
-
       extend ActiveSupport::Concern
 
       included do
@@ -11,10 +28,12 @@ module Cequel
         define_model_callbacks :save, :create, :update, :destroy
       end
 
+      # (see Persistence#save)
       def save(options = {})
         connection.batch { run_callbacks(:save) { super }}
       end
 
+      # (see Persistence#save)
       def destroy
         connection.batch { run_callbacks(:destroy) { super }}
       end
@@ -28,9 +47,6 @@ module Cequel
       def update
         run_callbacks(:update) { super }
       end
-
     end
-
   end
-
 end

data/lib/cequel/record/collection.rb

@@ -1,37 +1,117 @@
 require 'delegate'
 
 module Cequel
-
   module Record
-
+    #
+    # The value of a collection column in a {Record}. Collections track
+    # modifications that can be expressed as atomic collection mutations in
+    # CQL, and persist those modifications when their owning record is saved.
+    # Such modifications can be done even if the collection has not loaded
+    # data from CQL, in the case of an unloaded record or where the collection
+    # column was not included in the `SELECT` statement.
+    #
+    # Mutation operations that require reading data before writing it are not
+    # supported (e.g. `Array#map!).
+    #
+    # Each collection implementation wraps a built-in Ruby collection type.
+    #
+    # @abstract Including classes must descend from `Delegator` and implement
+    #   the `::empty` class method.
+    #
+    # @example
+    #   class Blog
+    #     include Cequel::Record
+    #
+    #     key :subdomain
+    #
+    #     list :categories, :text
+    #   end
+    #
+    #   # Get an unloaded Blog instance; no data read
+    #   blog = Blog['cassandra']
+    #
+    #   # Stage modification to collection, still no data read
+    #   blog.categories << 'Big Data'
+    #
+    #   # Issue an UPDATE statement which pushes "Big Data" onto the
+    #   # collection. Still no data read
+    #   blog.save!
+    #
+    #   # Stage another modification to the collection
+    #   blog.categories.unshift('Distributed Database')
+    #
+    #   # Collection is lazily read from the database, and then staged
+    #   # modifications are made to the loaded collection
+    #   puts blog.categories.join(', ') 
+    #
+    #   # Issues an UPDATE statement which prepends "Distributed Data" onto the
+    #   # collection
+    #   blog.save! 
+    #
+    # @since 1.0.0
+    #
     module Collection
-
       extend ActiveSupport::Concern
       extend Forwardable
 
+      #
+      # @!method loaded?
+      #   @return [Boolean] `true` if the collection's contents are loaded into
+      #     memory
+      #
       def_delegators :@model, :loaded?, :updater, :deleter
+      private :updater, :deleter
+
+      #
+      # @!method column_name
+      #   @return [Symbol] the name of the collection column
+      #
       def_delegator :@column, :name, :column_name
+
       def_delegators :__getobj__, :clone, :dup
 
       included do
-        private
         define_method(
           :method_missing,
           BasicObject.instance_method(:method_missing))
+        private :method_missing
       end
 
+      #
+      # @param model [Record] record that contains this collection
+      # @param column [Schema::Column] column this collection's data belongs to
+      # @return [Collection] a new collection
+      #
       def initialize(model, column)
         @model, @column = model, column
       end
 
+      #
+      # @return [String] inspected underlying Ruby collection object
+      #
       def inspect
         __getobj__.inspect
       end
 
+      #
+      # Notify the collection that its underlying data is loaded in memory.
+      #
+      # @return [void]
+      #
+      # @api private
+      #
       def loaded!
-        modifications.each { |modification| modification.() }.clear
+        modifications.each { |modification| modification.call() }.clear
       end
 
+      #
+      # Notify the collection that its staged changes have been written to the
+      # data store.
+      #
+      # @return [void]
+      #
+      # @api private
+      #
       def persisted!
         modifications.clear
       end
@@ -44,10 +124,11 @@ module Cequel
       end
 
       def __setobj__(obj)
-        raise "Attempted to call __setobj__ on read-only delegate!"
+        fail "Attempted to call __setobj__ on read-only delegate!"
       end
 
       private
+
       attr_reader :model, :column
       def_delegator :column, :cast, :cast_collection
       def_delegator 'column.type', :cast, :cast_element
@@ -56,7 +137,7 @@ module Cequel
       def to_modify(&block)
         if loaded?
           model.__send__("#{column_name}_will_change!")
-          block.()
+          block.call()
         else modifications << block
         end
         self
@@ -65,13 +146,20 @@ module Cequel
       def modifications
         @modifications ||= []
       end
-
     end
 
+    #
+    # The value of a list column in a {Record} instance. List collections
+    # encapsulate and behave like the built-in `Array` type.
+    #
+    # @see http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_using/use_collections_c.html#task_ds_lqp_krj_zj CQL documentation for the list type
+    # @since 1.0.0
+    #
     class List < DelegateClass(Array)
-
       include Collection
 
+      # These methods are not available on lists because they require reading
+      # collection data before writing it.
       NON_ATOMIC_MUTATORS = [
         :collect!,
         :delete_if,
@@ -92,14 +180,50 @@ module Cequel
         :sort_by!,
         :uniq!
       ]
-      NON_ATOMIC_MUTATORS.
-        each { |method| undef_method(method) if method_defined? method }
-
+      NON_ATOMIC_MUTATORS
+        .each { |method| undef_method(method) if method_defined? method }
+
+      #
+      # @return [Array] an empty array
+      #
+      # @api private
+      #
       def self.empty; []; end
 
+      #
+      # Set the value at a position or range of positions. This modification
+      # will be staged and persisted as an atomic list update when the record
+      # is saved. If the collection data is loaded in memory, it will also be
+      # modified accordingly.
+      #
+      # @return [void]
+      #
+      # @see DataSet#list_replace
+      # @note Negative positions are not supported, as they are not allowed in
+      #   CQL list operations.
+      #
+      # @overload []=(position, element)
+      #
+      #   @param position [Integer] position at which to set element
+      #   @param element element to insert at position in list
+      #
+      # @overload []=(range, elements)
+      #
+      #   @param range [Range] range of positions at which to replace elements
+      #   @param elements [Array] new elements to replace in this range
+      #
+      # @overload []=(start_position, count, elements)
+      #
+      #   @param start_position [Integer] position at which to begin replacing
+      #     elements
+      #   @param count [Integer] number of elements to replace
+      #   @param elements [Array] new elements to replace in this range
+      #
       def []=(position, *args)
-        if Range === position then first, count = position.first, position.count
-        else first, count = position, args[-2]
+        if position.is_a?(Range)
+          first, count = position.first, position.count
+        else
+          first, count = position, args[-2]
         end
 
         element = args[-1] =
@@ -108,8 +232,9 @@ module Cequel
           end
 
         if first < 0
-          raise ArgumentError,
-            "Bad index #{position}: CQL lists do not support negative indices"
+          fail ArgumentError,
+               "Bad index #{position}: CQL lists do not support negative " \
+               "indices"
         end
 
         if count.nil?
@@ -127,53 +252,105 @@ module Cequel
         to_modify { super }
       end
 
+      #
+      # Remove all elements from the list. This will propagate to the database
+      # as a DELETE of the list column.
+      #
+      # @return [List] self
+      #
       def clear
         deleter.delete_columns(column_name)
         to_modify { super }
       end
 
+      #
+      # Concatenate another collection onto this list.
+      #
+      # @param array [Array] elements to concatenate
+      # @return [List] self
+      #
       def concat(array)
         array = cast_collection(array)
         updater.list_append(column_name, array)
         to_modify { super }
       end
 
+      #
+      # Remove all instances of a given value from the list.
+      #
+      # @param object value to remove
+      # @return [List] self
+      #
       def delete(object)
         object = cast_element(object)
         updater.list_remove(column_name, object)
         to_modify { super }
       end
 
+      #
+      # Remove the element at a given position from the list.
+      #
+      # @param index [Integer] position from which to remove the element
+      # @return [List] self
+      #
       def delete_at(index)
         deleter.list_remove_at(column_name, index)
         to_modify { super }
       end
 
-      def push(object)
-        object = cast_element(object)
-        updater.list_append(column_name, object)
+      #
+      # Push (append) one or more elements to the end of the list.
+      #
+      # @param objects value(s) to add to the end of the list
+      # @return [List] self
+      #
+      def push(*objects)
+        objects.map! { |object| cast_element(object) }
+        updater.list_append(column_name, objects)
         to_modify { super }
       end
       alias_method :<<, :push
-
+      alias_method :append, :push
+
+      #
+      # Replace the entire contents of this list with a new collection
+      #
+      # @param array [Array] new elements for this list
+      # @return [List] self
+      #
       def replace(array)
         array = cast_collection(array)
         updater.set(column_name => array)
         to_modify { super }
       end
 
-      def unshift(*objs)
-        objs.map!(&method(:cast_element))
-        updater.list_prepend(column_name, objs.reverse)
+      #
+      # Prepend one or more values to the beginning of this list
+      #
+      # @param objects value(s) to add to the beginning of the list
+      # @return [List] self
+      #
+      def unshift(*objects)
+        objects.map!(&method(:cast_element))
+        updater.list_prepend(column_name, objects.reverse)
         to_modify { super }
       end
-
+      alias_method :prepend, :unshift
     end
 
+    #
+    # The value of a set column in a {Record} instance. Contains an unordered,
+    # unique set of elements. Encapsulates and behaves like the `Set` type from
+    # the standard library.
+    #
+    # @see http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_using/use_collections_c.html#task_ds_agt_3kj_zj CQL documentation for set columns
+    # @since 1.0.0
+    #
     class Set < DelegateClass(::Set)
-
       include Collection
 
+      # These methods are not implemented because they cannot be expressed as a
+      # single CQL3 write operation.
       NON_ATOMIC_MUTATORS = [
         :add?,
         :collect!,
@@ -185,9 +362,15 @@ module Cequel
         :reject!,
         :select!
       ]
-      NON_ATOMIC_MUTATORS.
-        each { |method| undef_method(method) if method_defined? method }
-
+      NON_ATOMIC_MUTATORS
+        .each { |method| undef_method(method) if method_defined? method }
+
+      #
+      # Add an element to the set
+      #
+      # @param object element to add
+      # @return [Set] self
+      #
       def add(object)
         object = cast_element(object)
         updater.set_add(column_name, object)
@@ -195,30 +378,55 @@ module Cequel
       end
       alias_method :<<, :add
 
+      #
+      # Remove everything from the set. Equivalent to deleting the collection
+      # column from the record's row.
+      #
+      # @return [Set] self
+      #
       def clear
         deleter.delete_columns(column_name)
         to_modify { super }
       end
 
+      #
+      # Remove a single element from the set
+      #
+      # @param object element to remove
+      # @return [Set] self
+      #
       def delete(object)
         object = cast_element(object)
         updater.set_remove(column_name, object)
         to_modify { super }
       end
 
+      #
+      # Replace the entire contents of this set with another set
+      #
+      # @param set [::Set] set containing new elements
+      # @return [Set] self
+      #
       def replace(set)
         set = cast_collection(set)
         updater.set(column_name => set)
         to_modify { super }
       end
-
     end
 
+    #
+    # The value of a `map` column in a {Record} instance. Encapsulates and
+    # behaves like a built-in `Hash`.
+    #
+    # @see http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_using/use_collections_c.html#task_ds_cvq_kcl_zj CQL documentation for map columns
+    # @since 1.0.0
+    #
     class Map < DelegateClass(::Hash)
-
       include Collection
       extend Forwardable
 
+      # These methods involve mutation that cannot be expressed as a CQL
+      # operation, so are not implemented.
       NON_ATOMIC_MUTATORS = [
         :default,
         :default=,
@@ -240,9 +448,16 @@ module Cequel
         :to_options!,
         :transform_keys!
       ]
-      NON_ATOMIC_MUTATORS.
-        each { |method| undef_method(method) if method_defined? method }
-
+      NON_ATOMIC_MUTATORS
+        .each { |method| undef_method(method) if method_defined? method }
+
+      #
+      # Set the value of a given key
+      #
+      # @param key the key
+      # @param value the value
+      # @return [Map] self
+      #
       def []=(key, value)
         key = cast_key(key)
         updater.map_update(column_name, key => value)
@@ -250,17 +465,35 @@ module Cequel
       end
       alias_method :store, :[]=
 
+      #
+      # Remove all elements from this map. Equivalent to deleting the column
+      # value from the row in CQL
+      #
+      # @return [Map] self
+      #
       def clear
         deleter.delete_columns(column_name)
         to_modify { super }
       end
 
+      #
+      # Delete one key from the map
+      #
+      # @param key the key to delete
+      # @return [Map] self
+      #
       def delete(key)
         key = cast_key(key)
         deleter.map_remove(column_name, key)
         to_modify { super }
       end
 
+      #
+      # Update a collection of keys and values given by a hash
+      #
+      # @param hash [Hash] hash containing keys and values to set
+      # @return [Map] self
+      #
       def merge!(hash)
         hash = cast_collection(hash)
         updater.map_update(column_name, hash)
@@ -268,6 +501,12 @@ module Cequel
       end
       alias_method :update, :merge!
 
+      #
+      # Replace the entire contents of this map with a new one
+      #
+      # @param hash [Hash] hash containing new keys and values
+      # @return [Map] self
+      #
       def replace(hash)
         hash = cast_collection(hash)
         updater.set(column_name => hash)
@@ -275,11 +514,9 @@ module Cequel
       end
 
       private
+
       def_delegator 'column.key_type', :cast, :cast_key
       private :cast_key
-
     end
-
   end
-
 end