Module: Mongoid::Deprecable Private

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Extended In: `::Mongoid`
Defined in:	lib/mongoid/deprecable.rb

Overview

Adds ability to declare Mongoid-specific deprecations.

Constant Summary

DEPRECATION_WARNING_MUTEX =

The Mutex instance used to guard the deprecation warning flags.

# File 'lib/mongoid/deprecable.rb', line 57
```
Mutex.new
```

Instance Method Summary

#deprecate(target_module, *method_descriptors) Internal use only

Declares method(s) as deprecated.
#deprecation_warning(id, warning, callstack = nil) Internal use only

Emits a warning using the current deprecator.
#deprecator Internal use only

A Mongoid::Deprecation instance to use for reporting deprecations.
#reset_deprecation_warnings! Internal use only

Resets all deprecation warnings.
#deprecation_warning_guard(id, callsite) private Internal use only

Wraps access to the warnings ::Hash in a synchronize block.

Instance Method Details

#deprecate(target_module, *method_descriptors)

Declares method(s) as deprecated.

Examples:

Deprecate a method.

Mongoid.deprecate(Cat, :meow); Cat.new.meow
#=> Mongoid.logger.warn("meow is deprecated and will be removed from Mongoid 8.0")

Deprecate a method and declare the replacement method.

Mongoid.deprecate(Cat, meow: :speak); Cat.new.meow
#=> Mongoid.logger.warn("meow is deprecated and will be removed from Mongoid 8.0 (use speak instead)")

Deprecate a method and give replacement instructions.

Mongoid.deprecate(Cat, meow: 'eat :catnip instead'); Cat.new.meow
#=> Mongoid.logger.warn("meow is deprecated and will be removed from Mongoid 8.0 (eat :catnip instead)")

Parameters:

target_module (Module) —
The parent which contains the method.
*method_descriptors ([ Symbol | Hash<Symbol, [ Symbol | String ]> ]...) —
The methods to deprecate, with optional replacement instructions.

[ GitHub ]

# File 'lib/mongoid/deprecable.rb', line 50


def deprecate(target_module, *method_descriptors)
  deprecator.deprecate_methods(target_module, *method_descriptors)
end

#deprecation_warning(id, warning, callstack = nil)

Emits a warning using the current deprecator. If the given warning (as identified by id) has already been issued previously, this is a no-op.

Parameters:

id (Symbol) —
The unique identifier for this warning.
warning (String) —
The warning message to emit.
callstack (Array<Thread::Backtrace::Location> | nil) (defaults to: nil) —
The backtrace at the call site.

[ GitHub ]

# File 'lib/mongoid/deprecable.rb', line 26


def deprecation_warning(id, warning, callstack = nil)
  site = callstack&.first
  deprecation_warning_guard(id, site ? "#{site.path}:#{site.lineno}" : nil) do
    deprecator.warn(warning, callstack)
  end
end

#deprecation_warning_guard(id, callsite) (private)

Wraps access to the warnings ::Hash in a synchronize block. If the given id+callsite has not been warned already, the method will yield to a block and then flag the id. Otherwise, it returns immediately.

[ GitHub ]

# File 'lib/mongoid/deprecable.rb', line 62


def deprecation_warning_guard(id, callsite)
  DEPRECATION_WARNING_MUTEX.synchronize do
    @deprecation_warnings ||= {}

    key = "#{id}:#{callsite}"
    return if @deprecation_warnings.key?(key)

    yield

    @deprecation_warnings[key] = true
  end
end

#deprecator

A Mongoid::Deprecation instance to use for reporting deprecations

[ GitHub ]

# File 'lib/mongoid/deprecable.rb', line 11


def deprecator
  @deprecator ||= Mongoid::Deprecation.new
end

#reset_deprecation_warnings!

Resets all deprecation warnings. For use in tests.

[ GitHub ]

# File 'lib/mongoid/deprecable.rb', line 16


def reset_deprecation_warnings!
  DEPRECATION_WARNING_MUTEX.synchronize { @deprecation_warnings = {} }
end