mongoid-autoinc 4.0.0 → 5.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 96d00a61057fb2bc8e9fb2132a53f0621c0d3e90
-  data.tar.gz: 7ab2a16af4c5e473cf4c37ffc44982af4cd7dd3e
+  metadata.gz: a79423bfe165eec63f29853f0223dc6d2e5eabcc
+  data.tar.gz: 4eaa807480ffff04081b09e38da549963325b356
 SHA512:
-  metadata.gz: 99e700cf5996f0e5002e2f7dd40281a35041511170500052a44537f4b03c24deef3a38fb4b2d53c6f75341e607d91d000247717a36361001edcdc02921685250
-  data.tar.gz: 70e77ba82f5dd884b7dd6f23dd9622bacb43586a85ba3e25a5bccf95882240a20ce7a8971542fb34e4f60a895fe6c87cb575d7c729a783dcee64031d9430ae9e
+  metadata.gz: c9a43d20f68350a8ca2ab2c08c3df91a7653eace2eef842b2ea264c366516fd2b9e3aaca7753143b7ad24599c4b0833a1b708ae5b11ac4e98e4b4ca55e7ff76b
+  data.tar.gz: 371a8ae6062372b2bb63f8e3d519bbf938c83cca91813b5b2600ec71e2f9c98c14103a48f6d65e1d6f9582a2c5eaafa2d8b9a16490c9b1e2b7e1696ca8e4615c

data/README.md

@@ -2,8 +2,15 @@
 
 A mongoid plugin to add auto incrementing fields to your documents.
 
-[![Build Status](https://travis-ci.org/suweller/mongoid-autoinc.png?branch=master)](https://travis-ci.org/suweller/mongoid-autoinc)
-[![Code Climate](https://codeclimate.com/github/suweller/mongoid-autoinc.png)](https://codeclimate.com/github/suweller/mongoid-autoinc)
+[![Inline docs](
+http://inch-ci.org/github/suweller/mongoid-autoinc.svg?branch=master&style=flat
+)](http://inch-ci.org/github/suweller/mongoid-autoinc)
+[![Code Climate](
+http://img.shields.io/codeclimate/github/suweller/mongoid-autoinc.svg?style=flat
+)](https://codeclimate.com/github/suweller/mongoid-autoinc)
+[![Build Status](
+http://img.shields.io/travis/suweller/mongoid-autoinc.svg?style=flat
+)](https://travis-ci.org/suweller/mongoid-autoinc)
 
 # Versions
 
@@ -11,8 +18,9 @@ Use 0.1.3 for mongoid 2.0
 
 Use 0.3.0 for mongoid 3.0
 
-Use the `mongoid-4` branch for mongoid 4.0.
-We'll ship a new gem version when the mongoid 4.x gem is released.
+Use 4.x.x for mongoid 4
+
+Use 5.x.x for mongoid 5
 
 ## Installation
 
@@ -36,16 +44,16 @@ class User
   include Mongoid::Document
   include Mongoid::Autoinc
   field :name
-  field :number, :type => Integer
+  field :number, type: Integer
 
   increments :number
 end
 
-user = User.create(:name => 'Dr. Percival "Perry" Ulysses Cox')
+user = User.create(name: 'Dr. Percival "Perry" Ulysses Cox')
 user.id # BSON::ObjectId('4d1d150d30f2246bc6000001')
 user.number # 1
 
-another_user = User.create(:name => 'Bob Kelso')
+another_user = User.create(name: 'Bob Kelso')
 another_user.number # 2
 ```
 
@@ -59,9 +67,9 @@ class PatientFile
   include Mongoid::Autoinc
 
   field :name
-  field :number, :type => Integer
+  field :number, type: Integer
 
-  increments :number, :scope => :patient_id
+  increments :number, scope: :patient_id
 
   belongs_to :patient
 
@@ -71,13 +79,13 @@ end
 Scope can also be a Proc:
 
 ``` ruby
-increments :number, :scope => lambda { patient.name }
+increments :number, scope: -> { patient.name }
 ```
 
 ### Custom Increment Trigger
 
 You can trigger the assignment of an increment field manually by passing:
-`:auto => false` to the increment field.
+`auto: false` to the increment field.
 This allows for more flexible assignment of your increment number:
 
 ``` ruby
@@ -88,11 +96,11 @@ class Intern
   field :name
   field :number
 
-  increments :number, :auto => false
+  increments :number, auto: false
 
   after_save :assign_number_to_jd
 
-  protected
+protected
 
   def assign_number_to_jd
     assign!(:number) if number.blank? && name == 'J.D.'
@@ -166,7 +174,7 @@ second_ticket.number # 10
 The step option can also be a Proc:
 
 ``` ruby
-increments :number, step: lambda { 1 + rand(10) }
+increments :number, step: -> { 1 + rand(10) }
 ```
 
 ### Development

data/lib/autoinc.rb

@@ -1,19 +1,41 @@
 require 'autoinc/incrementor'
 
+# namespace all +Mongoid::Autoinc+ functionality to +Mongoid+ to reduce
+# possible clashes with other gems.
 module Mongoid
-
+  # Include module to allow defining of autoincrementing fields.
+  #
+  # @example
+  #   class Invoice
+  #     include Mongoid::Document
+  #     include Mongoid::Autoinc
+  #
+  #     field :number, type: Integer
+  #     increments :number
+  #   end
   module Autoinc
     extend ActiveSupport::Concern
 
     AlreadyAssignedError = Class.new(StandardError)
     AutoIncrementsError = Class.new(StandardError)
 
-    included do
-      before_create :update_auto_increments
-    end
+    included { before_create(:update_auto_increments) }
 
+    # +Mongoid::Autoinc+ class methods to allow for autoincrementing fields.
     module ClassMethods
-
+      # Returns all incrementing fields of the document
+      #
+      # @example
+      #   class Invoice
+      #     include Mongoid::Document
+      #     include Mongoid::Autoinc
+      #
+      #     field :number, type: Integer
+      #     increments :number
+      #   end
+      #   Invoice.incrementing_fields # => {number: {auto: true}}
+      #
+      # @return [ Hash ] +Hash+ with fields and their autoincrement options
       def incrementing_fields
         if superclass.respond_to?(:incrementing_fields)
           @incrementing_fields ||= superclass.incrementing_fields.dup
@@ -22,58 +44,113 @@ module Mongoid
         end
       end
 
-      def increments(field, options={})
-        incrementing_fields[field] = options.reverse_merge!(:auto => true)
+      # Set an autoincrementing field for a +Mongoid::Document+
+      #
+      # @param [ Symbol ] field The name of the field to apply autoincrement to
+      # @param [ Hash ] options The options to pass to that field
+      #
+      # @example
+      #   class Invoice
+      #     include Mongoid::Document
+      #     include Mongoid::Autoinc
+      #
+      #     field :number, type: Integer
+      #     increments :number
+      #   end
+      #
+      # @example
+      #   class User
+      #     include Mongoid::Document
+      #     include Mongoid::Autoinc
+      #
+      #     field :number, type: Integer
+      #     increments :number, auto: false
+      #   end
+      def increments(field, options = {})
+        incrementing_fields[field] = options.reverse_merge!(auto: true)
         attr_protected(field) if respond_to?(:attr_protected)
       end
-
     end
 
+    # Manually assign the next number to the passed autoinc field.
+    #
+    # @raise [ Mongoid::Autoinc::AutoIncrementsError ] When `auto: true` is set
+    # in the increments call for `field`
+    # @raise [ AlreadyAssignedError ] When called more then once.
+    #
+    # @return [ Fixnum ] The assigned number
     def assign!(field)
       options = self.class.incrementing_fields[field]
-      raise AutoIncrementsError if options[:auto]
-      raise AlreadyAssignedError if send(field).present?
+      fail AutoIncrementsError if options[:auto]
+      fail AlreadyAssignedError if send(field).present?
       increment!(field, options)
     end
 
+    # Sets autoincrement values for all autoincrement fields.
+    #
+    # @return [ true ]
     def update_auto_increments
       self.class.incrementing_fields.each do |field, options|
         increment!(field, options) if options[:auto]
-      end
+      end && true
     end
 
+    # Set autoincrement value for the passed autoincrement field,
+    # using the passed options
+    #
+    # @param [ Symbol ] field Field to set the autoincrement value for.
+    # @param [ Hash ] options Options to pass through to the serializer.
+    #
+    # @return [ true ] The value of `write_attribute`
     def increment!(field, options)
       options = options.dup
       model_name = (options.delete(:model_name) || self.class.model_name).to_s
       options[:scope] = evaluate_scope(options[:scope]) if options[:scope]
       options[:step] = evaluate_step(options[:step]) if options[:step]
       write_attribute(
-          field.to_sym, Mongoid::Autoinc::Incrementor.new(model_name, field, options).inc
+          field.to_sym,
+          Mongoid::Autoinc::Incrementor.new(model_name, field, options).inc
       )
     end
 
+    # Asserts the validity of the passed scope
+    #
+    # @param [ Object ] scope The +Symbol+ or +Proc+ to evaluate
+    #
+    # @raise [ ArgumentError ] When +scope+ is not a +Symbol+ or +Proc+
+    #
+    # @return [ Object ] The scope of the autoincrement call
     def evaluate_scope(scope)
-      case scope
-      when Symbol then send(scope)
-      when Proc then instance_exec &scope
-      else raise 'scope is not a Symbol or a Proc'
-      end
+      return send(scope) if scope.is_a? Symbol
+      return instance_exec(&scope) if scope.is_a? Proc
+      fail ArgumentError, 'scope is not a Symbol or a Proc'
     end
 
+    # Returns the number to add to the current increment
+    #
+    # @param [ Object ] step The +Integer+ to be returned
+    # or +Proc+ to be evaluated
+    #
+    # @raise [ ArgumentError ] When +step+ is not an +Integer+ or +Proc+
+    #
+    # @return [ Integer ] The number to add to the current increment
     def evaluate_step(step)
-      case step
-      when Integer then step
-      when Proc then evaluate_step_proc(step)
-      else raise 'step is not an Integer or a Proc'
-      end
+      return step if step.is_a? Integer
+      return evaluate_step_proc(step) if step.is_a? Proc
+      fail ArgumentError, 'step is not an Integer or a Proc'
     end
 
+    # Executes a proc and returns its +Integer+ value
+    #
+    # @param [ Proc ] step_proc The +Proc+ to call
+    #
+    # @raise [ ArgumentError ] When +step_proc+ does not evaluate to +Integer+
+    #
+    # @return [ Integer ] The number to add to the current increment
     def evaluate_step_proc(step_proc)
-      result = instance_exec &step_proc
+      result = instance_exec(&step_proc)
       return result if result.is_a? Integer
-      raise 'step Proc does not evaluate to an Integer'
+      fail 'step Proc does not evaluate to an Integer'
     end
-
   end
-
 end

data/lib/autoinc/incrementor.rb

@@ -1,48 +1,79 @@
 module Mongoid
-
   module Autoinc
-
+    # Object which wraps the mongodb operations needed to allow for
+    # autoincrementing fields in +Mongoid::Document+ models.
     class Incrementor
-      attr_accessor :model_name, :field_name, :scope_key, :collection, :seed, :step
-
-      def initialize(model_name, field_name, options={})
-        self.model_name = model_name.to_s
-        self.field_name = field_name.to_s
-        self.scope_key = options[:scope]
-        self.step = options[:step] || 1
-        self.seed = options[:seed]
-        self.collection = ::Mongoid.default_session['auto_increment_counters']
-        create if seed && !exists?
+      # The name of the autoincrementing model.
+      attr_reader(:model_name)
+
+      # The name of the field of the autoincrementing model.
+      attr_reader(:field_name)
+
+      # The constraint, allowing for more then one series on the same
+      # +model_name+ +field_name+ combination.
+      attr_reader(:scope_key)
+
+      # The mongo connection to the autoincrement counters collection.
+      attr_reader(:collection)
+
+      # The autoincrement offset.
+      attr_reader(:seed)
+
+      # How the next autoincrement number should be calculated.
+      attr_reader(:step)
+
+      # Creates a new incrementor object for the passed +field_name+
+      #
+      # @param [ String ] model_name Part of the name of the increment +key+
+      # @param [ String ] field_name The name of the +field+ to increment
+      # @param [ Hash ] options Options to pass to the incrementer
+      #
+      def initialize(model_name, field_name, options = {})
+        @model_name = model_name.to_s
+        @field_name = field_name.to_s
+        @scope_key = options.fetch(:scope, nil)
+        @step = options.fetch(:step, 1)
+        @seed = options.fetch(:seed, nil)
+        @collection = ::Mongoid.default_client['auto_increment_counters']
+        create if @seed && !exists?
       end
 
+      # Returns the increment key
+      #
+      # @return [ String ] The key to increment
       def key
-        "".tap do |str|
-          str << "#{model_name.underscore}_#{field_name}"
-          str << "_#{scope_key}" unless scope_key.blank?
-        end
+        return "#{model_name.underscore}_#{field_name}" if scope_key.blank?
+        "#{model_name.underscore}_#{field_name}_#{scope_key}"
       end
 
+      # Increments the +value+ of the +key+ and returns it using an atomic op
+      #
+      # @return [ Integer ] The next value of the incrementor
       def inc
-        collection.find(
-          '_id' => key
-        ).modify(
-          {'$inc' => { 'c' => step }},
-          :new => true, :upsert => true
-        )['c']
+        find.find_one_and_update({'$inc' => {c: step}}, upsert: true, return_document: :after).fetch('c')
       end
 
       private
 
-      def exists?
-        collection.find('_id' => key).count > 0
+      # Find the incrementor document, using the +key+ id.
+      #
+      # @return [ Hash ] The persisted version of this incrementor.
+      def find
+        collection.find(_id: key)
       end
 
+      # Persists the incrementor using +key+ as id and +seed+ as value of +c+.
+      #
       def create
-        collection.insert({'_id' => key, 'c' => seed})
+        collection.insert_one(_id: key, c: seed)
       end
 
+      # Checks if the incrementor is persisted
+      #
+      # @return [ true, false ] If the incrementor is already persisted.
+      def exists?
+        find.count > 0
+      end
     end
-
   end
-
 end

data/lib/autoinc/version.rb

@@ -1,5 +1,5 @@
 module Mongoid
   module Autoinc
-    VERSION = "4.0.0"
+    VERSION = '5.0.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongoid-autoinc
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 5.0.1
 platform: ruby
 authors:
 - Robert Beekman
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-11 00:00:00.000000000 Z
+date: 2015-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mongoid
@@ -18,14 +18,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: 5.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: 5.0.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -115,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: Add auto incrementing fields to mongoid documents