cassie 1.0.0.beta.33 → 1.0.0.1

data/lib/cassie/statements/README.md

@@ -16,7 +16,9 @@ Cassie.insert(:users_by_username,
               "id = #{some_id}",
               username: some_username)
 ```
+
 or
+
 ```
 Cassie.select_from(:table)
       .where(id: some_id)
@@ -24,6 +26,7 @@ Cassie.select_from(:table)
 ```
 
 Queries defined on the fly like this tend to create debt for an application in the long term. They:
+
   * create gaps in test coverage
   * lack clear documentation
   * resist refactoring
@@ -327,6 +330,7 @@ which is the same as
 
   select count
 ```
+
 ```
 #=> SELECT COUNT(*) FROM posts_by_author;
 ```
@@ -339,9 +343,11 @@ Aliasing is supported with the `as` option.
   select ttl(:popular)
   select writetime(:popular), as: :created_at
 ```
+
 ```
 #=> SELECT id, TTL(popular), WRITETIME(popular) AS created_at FROM posts_by_author;
 ```
+
 Arbitrary strings are supported as well in case the DSL gets in the way.
 
 ```ruby
@@ -350,6 +356,7 @@ Arbitrary strings are supported as well in case the DSL gets in the way.
   select 'cowboy, coder'
 ```
 ```
+
 #=> SELECT cowboy, coder FROM posts_by_author;
 ```
 
@@ -362,6 +369,7 @@ By default, all columns for specified CQL rows will be deleted. Identify a subse
   column :nickname
   where :id, :eq
 ```
+
 ```
 #=> DELETE nickname FROM authors_by_id where id = 123;
 ```
@@ -378,6 +386,7 @@ query.result.class
 ```
 
 The result lazily enumerates domain objects
+
 ```ruby
 query.execute
 #=> true
@@ -386,6 +395,7 @@ query.result.each
 ```
 
 The result has a `first!` method that raises if no result is available
+
 ```ruby
 query.execute
 #=> true
@@ -393,7 +403,8 @@ query.result.first!
 Cassie::Statements::RecordNotFound: CQL row does not exist
 ```
 
-The result delegates to the `Cassandra::Result`.
+The result delegates to the `Cassandra::Result`
+
 ```ruby
 query.result.execution_info
 #=> #<Cassandra::Execution::Info:0x007fb404b51390 @payload=nil, @warnings=nil, @keyspace="cassie_test", @statement=#<Cassandra::Statements::Bound:0x3fda0258dee8 @cql="SELECT * FROM users_by_username LIMIT 500;" @params=[]>, @options=#<Cassandra::Execution::Options:0x007fb404b1b880 @consistency=:local_one, @page_size=10000, @trace=false, @timeout=12, @serial_consistency=nil, @arguments=[], @type_hints=[], @paging_state=nil, @idempotent=false, @payload=nil>, @hosts=[#<Cassandra::Host:0x3fda02541390 @ip=127.0.0.1>], @consistency=:local_one, @retries=0, @trace=nil>
@@ -489,7 +500,7 @@ UsersByUsernameQuery.new.fetch_first!(username: "eprothro").username
 #=> "eprothro"
 ```
 
-Most applications will want to override `build_result` to construct more useful domain objects
+Most applications will want to provide a `build_result` method to construct more useful domain objects
 
 ```ruby
 class UsersByUsernameQuery < Cassie::Query
@@ -509,7 +520,7 @@ UsersByUsernameQuery.new.fetch_first(username: "eprothro")
 #=> #<User:0x007fedec219cd8 @id=123, @username="eprothro">
 ```
 
-`build_results` may be overridden as well to define custom definition of the enumeration of rows returned from Cassandra.
+`build_results` may be provided as well to define custom definition of the enumeration of rows returned from Cassandra.
 
 #### Cursored paging
 
@@ -625,6 +636,7 @@ class RecordsByOwnerQuery < Cassie::Query
   end
 end
 ```
+
 ```ruby
 RecordsByOwnerQuery.new(owner: owner, min_record: 99,990).fetch.map(&:record)
 (2.9ms) SELECT * FROM records_by_owner WHERE owner_id = ? AND bucket = ? AND record >= ? LIMIT 100; [123, 0, 99990]
@@ -638,9 +650,38 @@ By default, this works for ascending and descending orderings when paging in the
 
 Custom policies can be defined by setting `Query.partition_linker` for more complex schemas. See the `SimplePolicy` source for an example.
 
-#### Consistency configuration
 
-The [consistency level](http://datastax.github.io/ruby-driver/api/cassandra/#consistencies-constant) for a query is determined by your `Cassie::configuration` by default, falling to back to the `Cassandra` default if none is given.
+#### Connection options
+
+Options are searched for in the following order:
+
+1. the object instance value
+2. the class instance value
+3. the `Cassie` instance value
+4. the `Cassie::configuruation[:option]` value
+5. the `Cassandra::cluster` value (default cassandra driver value)
+
+Connection options include:
+
+* `keyspace`
+
+See the [Connection Readme](./lib/cassie/configuration/README.md#connection-options) for additional information. Cassie query superclasses include `Cassie::Connection`.
+
+#### Statement options
+
+Like connection options, statement options offer a similar fallback chain for flexibility.
+
+1. the object instance value
+2. the class instance value (e.g. the class inheriting from `Cassie::Query`, `Cassie::Modification`, etc)
+3. the superclass instance value (e.g. `Cassie::Query`, `Cassie::Modification`, etc)
+3. the `Cassie::Statment::default_foo` value (where foo is the option name)
+4. the `Cassandra::cluster` value (default cassandra driver value)
+
+Statement options include:
+
+* `consistency` [symbol](http://datastax.github.io/ruby-driver/api/cassandra/#consistencies-constant)
+* `limit` integer
+* `idempotent` boolean
 
 ```ruby
 Cassie.configuration[:consistency]
@@ -650,15 +691,18 @@ Cassie.cluster.instance_variable_get(:@execution_options).consistency
 #=> :one
 ```
 
-Cassie queries allow for a consistency level to be defined on the object, subclass, base class, and global levels. If none is found, it will default to the `cluster` default when the query is executed.
+See the examples below of setting the `consistency` option at various places.
 
 Object writer:
+
 ```ruby
   query = MyQuery.new
   query.consistency = :all
   query.execute
 ```
+
 Override Object reader:
+
 ```ruby
   select_from :posts_by_author_category
 
@@ -680,6 +724,7 @@ Override Object reader:
 ```
 
 Class writer
+
 ```ruby
   select_from :posts_by_author_category
 
@@ -689,24 +734,28 @@ Class writer
   consistency :quorum
 ```
 
-Cassie query classes
+`Cassie::Query` or `Cassie::Modificaton` superclass writer
+
 ```ruby
 # lib/tasks/interesting_task.rake
 require_relative "interesting_worker"
 
 task :interesting_task do
+  # All modification queries execute with :all consistency
   Cassie::Modification.consistency = :all
 
   InterestingWorker.new.perform
 end
 ```
 
-Cassie global default
+`Cassie` global default
+
 ```ruby
 # lib/tasks/interesting_task.rake
 require_relative "interesting_worker"
 
 task :interesting_task do
+  # All `Cassie` statements execute with :all consistency
   Cassie::Statements.default_consistency = :all
 
   InterestingWorker.new.perform
@@ -719,7 +768,7 @@ Cassie statements are set as [idempotent](http://datastax.github.io/ruby-driver/
 
 Mark queries that are not idempotent, so that the driver won't automatically retry for certain failure scenarios.
 
-Similar to other settings, there is a `Cassie::Statements.default_idempotency`, class level setting, and object level setting.
+Similar to other statement options, there is a `Cassie::Statements.default_idempotency`, class level setting, and object level setting.
 
 ```ruby
 class MyQuery < Cassie::Modification
@@ -732,6 +781,7 @@ class MyQuery < Cassie::Modification
   end
 end
 ```
+
 ```
 MyQuery.idempotent?
 # => true
@@ -750,6 +800,7 @@ class MyQuery < Cassie::Modification
   end
 end
 ```
+
 ```
 MyQuery.idempotent?
 # => false
@@ -881,6 +932,7 @@ Cassie Queries instrument execution time as `cassie.cql.execution` and logs a de
 SelectUserByUsernameQuery.new('some_user').execute
 (5.5ms) SELECT * FROM users_by_username WHERE username = ? LIMIT 1; ["some_user"] [LOCAL_ONE]
 ```
+
 This measures the time to build the CQL query (statement and bindings), transmit the query to the cassandra coordinator, receive the result from the cassandra coordinator, and have the cassandra ruby driver build the ruby representation of the results. It does not include the time it takes for the Cassie Query to build its resource objects.
 
 #### Result Deserialization

data/lib/cassie/statements/core.rb

@@ -4,14 +4,25 @@ require_relative 'logging'
 
 module Cassie::Statements
   module Core
-    extend ActiveSupport::Concern
 
-    included do
-      include Statement
-      include Execution
-      include Logging
+    # @!visibility private
+    # @!parse include Statement
+    # @!parse include Statement::ClassMethods
+    # @!parse include Execution
+    # @!parse include Execution::ClassMethods
+    # @!parse include Logging
+    # @!parse include Logging::ClassMethods
+    def self.included(base)
+      base.instance_eval do
+        include Statement
+        include Execution
+        include Logging
+      end
     end
 
+    # Create a new statement-based object, sending
+    # all options passed as a hash to attribute setters
+    # Similar to ActiveModel::Model initialization
     def initialize(params={})
       params.each do |attr, value|
         self.public_send("#{attr}=", value)

data/lib/cassie/statements/execution/results/core.rb

@@ -2,7 +2,7 @@ module Cassie::Statements::Results
   module Core
 
     def success?
-      # TODO: remove - don't think we need this exception
+      # @todo remove - don't think we need this exception
       # raise "execution not complete, no results to parse" unless result
 
       true

data/lib/cassie/statements/execution/results/modification_result.rb

@@ -2,7 +2,7 @@ module Cassie::Statements::Results
   require_relative 'modification'
 
   class ModificationResult < Result
-    include  Modification
+    include Modification
 
   end
 end

data/lib/cassie/statements/execution/results/query_result.rb

@@ -2,7 +2,7 @@ module Cassie::Statements::Results
   require_relative 'querying'
 
   class QueryResult < Result
-    include  Querying
+    include Querying
 
   end
 end

data/lib/cassie/statements/execution.rb

@@ -1,4 +1,11 @@
 module Cassie::Statements
+  # Execution support for Cassandra Statements
+  #
+  # Requires the following methods be provided:
+  # * +statement+
+  #   * CQL +String+ or +Cassandra::Statements:Statement+ executable by a +Cassandra::Session+
+  # * +session+
+  #   * A +Cassandra::Session+ scoped to an appropriate keyspace
   module Execution
     require_relative 'execution/errors'
     require_relative 'execution/consistency'
@@ -7,22 +14,35 @@ module Cassie::Statements
     require_relative 'execution/partition_linking'
     require_relative 'execution/instrumentation'
 
-    extend ActiveSupport::Concern
-    included do
-      attr_reader :result
+    # @!visibility private
+    # @!parse include Consistency
+    # @!parse include Callbacks
+    # @!parse include PartitionLinking
+    # @!parse include Instrumentation
+    def self.included(base)
+      base.instance_eval do
+        # The result from execution.
+        # Includes all attributes and methods available from
+        # a +Cassandra::Result+
+        # @return [Cassie::Statements::Results::Result] A decorated +Cassandra::Result+ object
+        attr_reader :result
 
-      include Consistency
-      include Callbacks
-      include PartitionLinking
-      include Instrumentation
+        include Consistency
+        include Callbacks
+        include PartitionLinking
+        include Instrumentation
+      end
+      base.extend ClassMethods
     end
 
+    # @!parse extend ClassMethods
     module ClassMethods
       def inherited(subclass)
         subclass.result_class = result_class if defined?(@result_class)
         super
       end
-
+      # The class to use for decorating the +Cassandra::Result+
+      # @!parse attr_accessor :result_class
       def result_class
         return @result_class if defined?(@result_class)
         Cassie::Statements::Results::Result
@@ -33,22 +53,25 @@ module Cassie::Statements
       end
     end
 
-    # Executes the statment, populates result
-    # returns true or false indicating a successful execution or not
+    # Executes the statment and populates result
+    # @return [Boolean] indicating a successful execution or not
     def execute
       @result = result_class.new(session.execute(statement, execution_options), result_opts)
       result.success?
     end
 
-    # Executes the statment, populates result
-    # true or raises if the  was not successful
+    # Same as {#execute}. Raises if not succesfull.
+    # @return [Boolean] true if sucessful
+    # @raise [Cassie::Statements::ExecutionError] if the result was not sucessful, see {Cassie::Statements::Results::Core#success?}
     def execute!
       execute || (raise Cassie::Statements::ExecutionError.new(result))
     end
 
+    # The session exection options configured for statement execution
+    # @return [Hash{Symbol => Object}]
     def execution_options
       {}.tap do |opts|
-        #TODO: rework consistency module to be more
+        # @todo rework consistency module to be more
         #      abstract implementation for all execution options
         opts[:consistency] = consistency if consistency
         opts[:paging_state] = paging_state if respond_to?(:paging_state) && paging_state
@@ -68,6 +91,10 @@ module Cassie::Statements
 
     private
 
+    # Ensures that +clone+ and +dup+ drops the reference to the
+    # result object. The cloned object should be able to mutate
+    # the statement and execute without affecting the original
+    # objecthe resulting object or its results.
     def initialize_copy(other)
       super
       @result = nil

data/lib/cassie/statements/statement/assignments.rb

@@ -22,11 +22,36 @@ module Cassie::Statements::Statement
   module Assignments
     extend ActiveSupport::Concern
 
-    included do
-      include Mapping
+    # @!visibility private
+    # @!parse include Mapping
+    # @!parse extend Mapping::ClassMethods
+    def self.included(base)
+      base.instance_eval do
+        include Mapping
+      end
+      base.extend ClassMethods
     end
 
     module ClassMethods
+      # DSL to set an assigment (+SET+ or +VALUES+ clause) for +UPDATE+ and +INSERT+ statements.
+      #
+      # Defining an assigment also defines an +attr_accessor+ with the same name as
+      # the identifier (or the +:value+ option if a symbol is used). The underlying instance
+      # variable value for this accessor will be used when determining the value for the assigment.
+      #
+      # @param [String, Symbol] identifier The column name to set.
+      # @param [Hash] opts options for the assigment
+      # @option opts [Symbol, Object] :value The value to use for the assigment (constraint). If a [Symbol], a method with that name will be called when the statement is built. Otherwise, the value itself will be used.
+      # @option opts [Symbol, Object] :if Determines if the assigment is applied to the statement or not. If a [Symbol], a method with that name will be called when the statement is built. Otherwise, the value itself will be used.
+      # @option opts [String] :term The argument value to use instead of a positional placeholder (?). If a [Symbol], a method with that name will be called when the statement is built. Otherwise, the value itself will be used.
+      # @return [Enumerable<Array<Object>>] The enumeration of current assigments' parameters
+      # @raise [StandardError] if there is already a getter or setter method defined for the
+      #   assigment value's implied accessor (+identifier+ or symbol +:value+ option).
+      #
+      # @example Assigment with implied accessor
+      #   set :username #<= gets assigment value from `:username` method
+      # @example Assigment with explicit accessor
+      #   set :username, value: :name #<= gets assigment value from `:name` method
       def set(identifier, opts={})
         opts[:value] ||= identifier.to_sym
 
@@ -35,17 +60,22 @@ module Cassie::Statements::Statement
         assignments_args << [identifier, opts.delete(:value), opts]
       end
 
+      # The enumeration of current assignments' parameters that will be
+      # used to build Assignment objects when the statement is built
       def assignments_args
         @assignments_args ||= []
       end
     end
 
+    # The enumeration of current assignments' parameters that will be
+    # used to build Assignment objects when the statement is built
     def assignments_args
       self.class.assignments_args
     end
 
+    protected
+
     def build_update_and_params
-      cql = ""
       arguments = []
       assignment_strings = []
 

data/lib/cassie/statements/statement/conditions.rb

@@ -1,6 +1,8 @@
 module Cassie::Statements::Statement
   module Conditions
-    extend ActiveSupport::Concern
+    def self.included(base)
+      base.extend ClassMethods
+    end
 
     module ClassMethods
       def if_not_exists(opts={})

data/lib/cassie/statements/statement/deleting.rb

@@ -4,22 +4,30 @@ require_relative 'mapping'
 
 module Cassie::Statements::Statement
   module Deleting
-    extend ::ActiveSupport::Concern
 
-    included do
-      include Relations
-      include Conditions
-      include Mapping
+    # @!visibility private
+    # @!parse include Relations
+    # @!parse extend Relations::ClassMethods
+    # @!parse include Conditions
+    # @!parse extend Conditions::ClassMethods
+    # @!parse include Mapping
+    # @!parse extend Mapping::ClassMethods
+    def self.included(base)
+      base.instance_eval do
+        include Relations
+        include Conditions
+        include Mapping
 
-      @result_class = Cassie::Statements::Results::ModificationResult
+        @result_class = Cassie::Statements::Results::ModificationResult
+      end
+      base.extend ClassMethods
     end
 
+    # @!parse extend ClassMethods
     module ClassMethods
-      #TODO: accept block to add specific selectors and aliases
-      #      select_from :table do |t|
-      #        t.id
-      #        t.name as: :username
-      #      end
+      # DSL to set the statement type and table for deleting
+      # @param [String, Symbol] table The table to taret for the delete statement
+      # @return [void]
       def delete_from(table)
         self.table = table
         self.type = :delete
@@ -27,16 +35,16 @@ module Cassie::Statements::Statement
         yield(self) if block_given?
       end
 
-      def delete(table)
-        Cassie.logger.warn "[DEPRECATION] `Cassie::Modification#delete` has been replaced by `delete_from` and will be removed."
-        delete_from(table)
-      end
-
-
-      def column(identifier, opts={})
+      # Add a specific column to tombstone by this statement
+      # @param [String, Symbol] identifier the column to tombstone
+      def column(identifier)
+        # @todo replace with Selection
+        # Module and aliases?
         columns << identifier.to_s
       end
 
+      # The columns to be tombstoned from this statement
+      # @return [Array<String>] column names
       def columns
         @columns ||= []
       end
@@ -64,7 +72,7 @@ module Cassie::Statements::Statement
     end
 
     def build_delete_clause
-      str = if columns.empty?
+      if columns.empty?
         ''
       else
         columns.join(', ')

data/lib/cassie/statements/statement/idempotency.rb

@@ -9,14 +9,19 @@ module Cassie::Statements
   end
 
 
+  # Sepcific functionality and DSL for idempotent statements.
   module Statement::Idempotency
-    extend ActiveSupport::Concern
-
-    included do
-      attr_writer :idempotent
+    # @!visibility private
+    def self.included(base)
+      base.instance_eval do
+        attr_writer :idempotent
+      end
+      base.extend ClassMethods
     end
 
+    # @!parse extend ClassMethods
     module ClassMethods
+      # @!visibility private
       def inherited(subclass)
         subclass.idempotent = idempotent if defined?(@idempotent)
         super
@@ -26,6 +31,9 @@ module Cassie::Statements
         @idempotent = val
       end
 
+      # DSL to set a statement as idempotent
+      # @param [Boolean] val The value to set for idempotency. Returns the current value if no parameter is given.
+      # @return [Boolean] idempotent value
       def idempotent(val=:get)
         if val == :get
           return @idempotent if defined?(@idempotent)
@@ -35,20 +43,31 @@ module Cassie::Statements
         end
       end
 
+      # DSL to set a satement as non-idempotent
+      # @return [Boolean] false
       def non_idempotent
         self.idempotent = false
       end
 
+      # Indicates where the statement has no negative side-effect
+      # if issued multiple times.
+      # @return [Boolean] indicating idempotency. Defaults to {Cassie::Statements.default_idempotency} if no value has been set.
       def idempotent?
         !!idempotent
       end
     end
 
+    # Indicates where the statement has no negative side-effect
+    # if issued multiple times.
+    # @return [Boolean] indicating idempotency. Defaults to {Cassie::Statements.default_idempotency} if no value has been set.
     def idempotent
       return @idempotent if defined?(@idempotent)
       self.class.idempotent
     end
 
+    # Indicates where the statement has no negative side-effect
+    # if issued multiple times.
+    # @return [Boolean] indicating idempotency. Defaults to {Cassie::Statements.default_idempotency} if no value has been set.
     def idempotent?
       !!idempotent
     end

data/lib/cassie/statements/statement/inserting.rb

@@ -3,26 +3,33 @@ require_relative 'conditions'
 
 module Cassie::Statements::Statement
   module Inserting
-    extend ::ActiveSupport::Concern
 
-    included do
-      include Assignments
-      include Conditions
-
-      @result_class = Cassie::Statements::Results::ModificationResult
+    # @!visibility private
+    # @!parse include Assignments
+    # @!parse extend Assignments::ClassMethods
+    # @!parse include Conditions
+    # @!parse extend Conditions::ClassMethods
+    def self.included(base)
+      base.instance_eval do
+        include Assignments
+        include Conditions
+
+        @result_class = Cassie::Statements::Results::ModificationResult
+      end
+      base.extend ClassMethods
     end
 
+    # @!parse extend ClassMethods
     module ClassMethods
+      # DSL to set the statement type and table for insertion
+      # @param [String, Symbol] table The table to taret for the insert statement
+      # @return [void]
       def insert_into(table)
         self.table = table
         self.type = :insert
 
         yield(self) if block_given?
       end
-      def insert(table)
-        Cassie.logger.warn "[DEPRECATION] `Cassie::Modification#insert` has been replaced by `insert_into` and will be removed."
-        insert_into(table)
-      end
     end
 
     protected

data/lib/cassie/statements/statement/limiting.rb

@@ -12,8 +12,11 @@ module Cassie::Statements
   module Statement::Limiting
     extend ActiveSupport::Concern
 
-    included do
-      attr_writer :limit
+    def self.included(base)
+      base.instance_eval do
+        attr_writer :limit
+      end
+      base.extend ClassMethods
     end
 
     module ClassMethods