Class: Object

Inherits:
BasicObject
Includes:
ActiveSupport::Dependencies::RequireDependency, ActiveSupport::Tryable
Defined in:
lib/active_support/core_ext/object/duplicable.rb,
lib/active_support/core_ext/object/try.rb,
lib/active_support/core_ext/object/json.rb,
lib/active_support/core_ext/object/with.rb,
lib/active_support/core_ext/object/blank.rb,
lib/active_support/core_ext/object/deep_dup.rb,
lib/active_support/core_ext/object/to_query.rb,
lib/active_support/core_ext/object/acts_like.rb,
lib/active_support/core_ext/object/inclusion.rb,
lib/active_support/core_ext/object/with_options.rb,
lib/active_support/core_ext/string/output_safety.rb,
lib/active_support/core_ext/object/instance_variables.rb

Overview

– Most objects are cloneable, but not all. For example you can’t dup methods:

method(:puts).dup # => TypeError: allocator undefined for Method

Classes may signal their instances are not duplicable removing dup/clone or raising exceptions from them. So, to dup an arbitrary object you normally use an optimistic approach and are ready to catch an exception, say:

arbitrary_object.dup rescue object

Rails dups objects in a few critical spots where they are not that arbitrary. That rescue is very expensive (like 40 times slower than a predicate), and it is often triggered.

That’s why we hardcode the following cases and check duplicable? instead of using that rescue idiom. ++

Instance Method Summary collapse

Methods included from ActiveSupport::Tryable

#try, #try!

Methods included from ActiveSupport::Dependencies::RequireDependency

#require_dependency

Instance Method Details

#acts_like?(duck) ⇒ Boolean

Provides a way to check whether some class acts like some other class based on the existence of an appropriately-named marker method.

A class that provides the same interface as SomeClass may define a marker method named acts_like_some_class? to signal its compatibility to callers of acts_like?(:some_class).

For example, Active Support extends Date to define an acts_like_date? method, and extends Time to define acts_like_time?. As a result, developers can call x.acts_like?(:time) and x.acts_like?(:date) to test duck-type compatibility, and classes that are able to act like Time can also define an acts_like_time? method to interoperate.

Note that the marker method is only expected to exist. It isn’t called, so its body or return value are irrelevant.

Example: A class that provides the same interface as String

This class may define:

class Stringish
  def acts_like_string?
  end
end

Then client code can query for duck-type-safeness this way:

Stringish.new.acts_like?(:string) # => true

Returns:

  • (Boolean) 


33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/active_support/core_ext/object/acts_like.rb', line 33

def acts_like?(duck)
  case duck
  when :time
    respond_to? :acts_like_time?
  when :date
    respond_to? :acts_like_date?
  when :string
    respond_to? :acts_like_string?
  else
    respond_to? :"acts_like_#{duck}?"
  end
end

#as_json(options = nil) ⇒ Object

:nodoc:



59
60
61
62
63
64
65
 
# File 'lib/active_support/core_ext/object/json.rb', line 59

def as_json(options = nil) # :nodoc:
  if respond_to?(:to_hash)
    to_hash.as_json(options)
  else
    instance_values.as_json(options)
  end
end

#blank? ⇒ true, false

An object is blank if it’s false, empty, or a whitespace string. For example, nil, ”, ‘ ’, [], {}, and false are all blank.

This simplifies

!address || address.empty?

to

address.blank?

Returns:

  • (true, false) 


18
19
20
 
# File 'lib/active_support/core_ext/object/blank.rb', line 18

def blank?
  respond_to?(:empty?) ? !!empty? : false
end

#deep_dup ⇒ Object

Returns a deep copy of object if it’s duplicable. If it’s not duplicable, returns self.

object = Object.new
dup    = object.deep_dup
dup.instance_variable_set(:@a, 1)

object.instance_variable_defined?(:@a) # => false
dup.instance_variable_defined?(:@a)    # => true



15
16
17
 
# File 'lib/active_support/core_ext/object/deep_dup.rb', line 15

def deep_dup
  duplicable? ? dup : self
end

#duplicable? ⇒ Boolean

Can you safely dup this object?

False for method objects; true otherwise.

Returns:

  • (Boolean) 


26
27
28
 
# File 'lib/active_support/core_ext/object/duplicable.rb', line 26

def duplicable?
  true
end

#html_safe? ⇒ Boolean

Returns:

  • (Boolean) 


7
8
9
 
# File 'lib/active_support/core_ext/string/output_safety.rb', line 7

def html_safe?
  false
end

#in?(another_object) ⇒ Boolean

Returns true if this object is included in the argument.

When argument is a Range, #cover? is used to properly handle inclusion check within open ranges. Otherwise, argument must be any object which responds to #include?. Usage:

characters = ["Konata", "Kagami", "Tsukasa"]
"Konata".in?(characters) # => true

For non Range arguments, this will throw an ArgumentError if the argument doesn’t respond to #include?.

Returns:

  • (Boolean) 


15
16
17
18
19
20
21
22
23
24
 
# File 'lib/active_support/core_ext/object/inclusion.rb', line 15

def in?(another_object)
  case another_object
  when Range
    another_object.cover?(self)
  else
    another_object.include?(self)
  end
rescue NoMethodError
  raise ArgumentError.new("The parameter passed to #in? must respond to #include?")
end

#instance_values ⇒ Object

Returns a hash with string keys that maps instance variable names without “@” to their corresponding values.

class C
  def initialize(x, y)
    @x, @y = x, y
  end
end

C.new(0, 1).instance_values # => {"x" => 0, "y" => 1}



14
15
16
17
18
 
# File 'lib/active_support/core_ext/object/instance_variables.rb', line 14

def instance_values
  instance_variables.to_h do |ivar|
    [ivar[1..-1].freeze, instance_variable_get(ivar)]
  end
end

#instance_variable_names ⇒ Object

Returns an array of instance variable names as strings including “@”.

class C
  def initialize(x, y)
    @x, @y = x, y
  end
end

C.new(0, 1).instance_variable_names # => ["@y", "@x"]



29
30
31
 
# File 'lib/active_support/core_ext/object/instance_variables.rb', line 29

def instance_variable_names
  instance_variables.map(&:name)
end

#presence ⇒ Object

Returns the receiver if it’s present otherwise returns nil. object.presence is equivalent to

object.present? ? object : nil

For example, something like

state   = params[:state]   if params[:state].present?
country = params[:country] if params[:country].present?
region  = state || country || 'US'

becomes

region = params[:state].presence || params[:country].presence || 'US'

Returns:



45
46
47
 
# File 'lib/active_support/core_ext/object/blank.rb', line 45

def presence
  self if present?
end

#presence_in(another_object) ⇒ Object

Returns the receiver if it’s included in the argument otherwise returns nil. Argument must be any object which responds to #include?. Usage:

params[:bucket_type].presence_in %w( project calendar )

This will throw an ArgumentError if the argument doesn’t respond to #include?.

Returns:



34
35
36
 
# File 'lib/active_support/core_ext/object/inclusion.rb', line 34

def presence_in(another_object)
  in?(another_object) ? self : nil
end

#present? ⇒ true, false

An object is present if it’s not blank.

Returns:

  • (true, false) 


25
26
27
 
# File 'lib/active_support/core_ext/object/blank.rb', line 25

def present?
  !blank?
end

#to_param ⇒ Object

Alias of to_s.



7
8
9
 
# File 'lib/active_support/core_ext/object/to_query.rb', line 7

def to_param
  to_s
end

#to_query(key) ⇒ Object

Converts an object into a string suitable for use as a URL query string, using the given key as the param name.



13
14
15
 
# File 'lib/active_support/core_ext/object/to_query.rb', line 13

def to_query(key)
  "#{CGI.escape(key.to_param)}=#{CGI.escape(to_param.to_s)}"
end

#with(**attributes) ⇒ Object

Set and restore public attributes around a block.

client.timeout # => 5
client.with(timeout: 1) do |c|
  c.timeout # => 1
end
client.timeout # => 5

The receiver is yielded to the provided block.

This method is a shorthand for the common begin/ensure pattern:

old_value = object.attribute
begin
  object.attribute = new_value
  # do things
ensure
  object.attribute = old_value
end

It can be used on any object as long as both the reader and writer methods are public.



26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/active_support/core_ext/object/with.rb', line 26

def with(**attributes)
  old_values = {}
  begin
    attributes.each do |key, value|
      old_values[key] = public_send(key)
      public_send("#{key}=", value)
    end
    yield self
  ensure
    old_values.each do |key, old_value|
      public_send("#{key}=", old_value)
    end
  end
end

#with_options(options, &block) ⇒ Object

An elegant way to factor duplication out of options passed to a series of method calls. Each method called in the block, with the block variable as the receiver, will have its options merged with the default options Hash or Hash-like object provided. Each method called on the block variable must take an options hash as its final argument.

Without with_options, this code contains duplication:

class Account < ActiveRecord::Base
  has_many :customers, dependent: :destroy
  has_many :products,  dependent: :destroy
  has_many :invoices,  dependent: :destroy
  has_many :expenses,  dependent: :destroy
end

Using with_options, we can remove the duplication:

class Account < ActiveRecord::Base
  with_options dependent: :destroy do |assoc|
    assoc.has_many :customers
    assoc.has_many :products
    assoc.has_many :invoices
    assoc.has_many :expenses
  end
end

It can also be used with an explicit receiver:

I18n.with_options locale: user.locale, scope: 'newsletter' do |i18n|
  subject i18n.t :subject
  body    i18n.t :body, user_name: user.name
end

When you don’t pass an explicit receiver, it executes the whole block in merging options context:

class Account < ActiveRecord::Base
  with_options dependent: :destroy do
    has_many :customers
    has_many :products
    has_many :invoices
    has_many :expenses
  end
end

with_options can also be nested since the call is forwarded to its receiver.

NOTE: Each nesting level will merge inherited defaults in addition to their own.

class Post < ActiveRecord::Base
  with_options if: :persisted?, length: { minimum: 50 } do
    validates :content, if: -> { content.present? }
  end
end

The code is equivalent to:

validates :content, length: { minimum: 50 }, if: -> { content.present? }

Hence the inherited default for if key is ignored.

NOTE: You cannot call class methods implicitly inside of with_options. You can access these methods using the class name instead:

class Phone < ActiveRecord::Base
  enum :phone_number_type, { home: 0, office: 1, mobile: 2 }

  with_options presence: true do
    validates :phone_number_type, inclusion: { in: Phone.phone_number_types.keys }
  end
end

When the block argument is omitted, the decorated Object instance is returned:

module MyStyledHelpers
  def styled
    with_options style: "color: red;"
  end
end

styled.link_to "I'm red", "/"
# => <a href="/" style="color: red;">I'm red</a>

styled.button_tag "I'm red too!"
# => <button style="color: red;">I'm red too!</button>



92
93
94
95
96
97
98
99
100
 
# File 'lib/active_support/core_ext/object/with_options.rb', line 92

def with_options(options, &block)
  option_merger = ActiveSupport::OptionMerger.new(self, options)

  if block
    block.arity.zero? ? option_merger.instance_eval(&block) : block.call(option_merger)
  else
    option_merger
  end
end