Class: SleepingKingStudios::Tools::ObjectTools

Parent Namespace

SleepingKingStudios::Tools

Inherited Classes

SleepingKingStudios::Tools::Base > Object

Defined In

lib/sleeping_king_studios/tools/object_tools.rb

Table Of Contents

• Overview
• Class Methods
  • instance
• Constructor
• Instance Methods
  • apply
  • deep_dup
  • deep_freeze
  • dig
  • eigenclass
  • fetch
  • immutable?
  • initialize
  • mutable?
  • object?
  • toolbelt
  • try

Overview

Low-level tools for working with objects.

Back To Top

Class Methods

.instance => SleepingKingStudios::Tools::Base (deprecated)

Inherited From

SleepingKingStudios::Tools::Base

Deprecated. v1.3.0 Use Toolbelt.instance instead.

Returns

• (SleepingKingStudios::Tools::Base) — a memoized instance of the tools class.

Back To Top

Constructor

#initialize(toolbelt: nil) => Base

Inherited From

SleepingKingStudios::Tools::Base

Parameters

• toolbelt (SleepingKingStudios::Tools::Toolbelt) — the toolbelt this tools instance belongs to.

Returns

• (Base) — a new instance of Base

Back To Top

Instance Methods

#apply(receiver, proc, *args, **kwargs, &block) => Object

Calls a Proc or lambda on the given receiver with the given parameters.

Unlike calling #instance_exec with the block, ObjectTools#apply allows you to specify a block parameter.

Examples

my_object = double('object', :to_s => 'A mock object')
my_proc   = ->() { puts %{#{self.to_s} says "Greetings, programs!"} }

ObjectTools.apply my_object, my_proc
#=> Writes 'A mock object says "Greetings, programs!"' to STDOUT.

Parameters

• receiver (Object) — The receiver. the proc will be called in the context of this object.
• proc (Proc) — the proc or lambda to call.
• args (Array) — optional. Additional arguments to pass in to the proc or lambda.
• kwargs (Hash) — optional. Additional keywords to pass in to the proc or lambda.
• block (Proc) — optional. If present, will be passed in to proc or lambda.

Returns

• (Object) — the result of calling the proc or lambda with the given receiver and any additional arguments or block.

#deep_dup(obj) =>

Creates a deep copy of the object.

If the object is an Array, returns a new Array with deep copies of each array item. If the object is a Hash, returns a new Hash with deep copies of each hash key and value. Otherwise, returns Object#dup.

Examples

data = {
  :songs => [
    {
      :name   => 'Welcome to the Jungle',
      :artist => "Guns N' Roses",
      :album  => 'Appetite for Destruction'
    },
    {
      :name   => 'Hells Bells',
      :artist => 'AC/DC',
      :album  => 'Back in Black'
    },
    {
      :name   => "Knockin' on Heaven's Door",
      :artist => 'Bob Dylan',
      :album  => 'Pat Garrett & Billy The Kid'
    }
  ]
}

copy = ObjectTools.deep_dup data

copy[:songs] << { :name => 'Sympathy for the Devil', :artist => 'The Rolling Stones', :album => 'Beggars Banquet' }
data[:songs].count
#=> 3

copy[:songs][1][:name] = 'Shoot to Thrill'
data[:songs][1]
#=> { :name => 'Hells Bells', :artist => 'AC/DC', :album => 'Back in Black' }

Parameters

• obj (Object) — the object to copy.

Returns

• () — the copy of the object.

See Also

• ArrayTools#deep_copy
• HashTools#deep_copy

#deep_freeze(obj) => Object

Performs a deep freeze of the object.

If the object is an Array, freezes the array and performs a deep freeze on each array item. If the object is a hash, freezes the hash and performs a deep freeze on each hash key and value. Otherwise, calls Object#freeze.

Examples

data = {
  :songs => [
    {
      :name   => 'Welcome to the Jungle',
      :artist => "Guns N' Roses",
      :album  => 'Appetite for Destruction'
    },
    {
      :name   => 'Hells Bells',
      :artist => 'AC/DC',
      :album  => 'Back in Black'
    },
    {
      :name   => "Knockin' on Heaven's Door",
      :artist => 'Bob Dylan',
      :album  => 'Pat Garrett & Billy The Kid'
    }
  ]
}
ObjectTools.deep_freeze(data)

data.frozen?
#=> true
data[:songs].frozen?
#=> true
data[:songs][0].frozen?
#=> true
data[:songs][0].name.frozen?
#=> true

Parameters

• obj (Object) — The object to freeze.

Returns

• (Object) — the frozen object.

#dig(obj, *method_names, indifferent_keys: false) => Object, nil

Accesses deeply nested properties on an object.

This method finds the first named property on the given object, and then each subsequent property on the result of the previous call.

• If the object responds to the property name as a public method, it calls the method directly.
• If the object does not respond to the property name, or if the property name is not itself a valid method name, checks if the object responds to #[]; if so, calls #[] with the property name.
• Otherwise, immediately returns nil.

Using #[] access allows digging through Array (using integer indices) and Hash data structures as well as object methods.

Examples

ObjectTools.dig(my_object, :first_method, :second_method, :third_method)
#=> my_object.first_method.second_method.third_method

Parameters

• obj (Object) — the object to dig.
• method_names (Array) — the names of the methods to call.
• indifferent_keys (true, false) — if true, matches both String and Symbol keys when accessing a Hash value using #[]. Defaults to false.

Returns

• (Object, nil) — the result of the last method call, or nil if the last object does not respond to the last method.

#eigenclass(obj) => Class (deprecated)

Also known as: metaclass

Deprecated. v1.3.0 Use Object#singleton_class instead.

Returns the object’s eigenclass.

Parameters

• obj (Object) — the object for which an eigenclass is required.

Returns

• (Class) — the object's singleton class.

#fetch(obj, key, default = nil, indifferent_key: false) => Object
#fetch(obj, key, indifferent_key: false, &default) => Object

Overloads

#fetch(obj, key, default = nil, indifferent_key: false) => Object

Retrieves the value at the specified method, key, or index.

If the value does not exist, returns the default value, or raises am exception if there is no default value. If the object defines a native #fetch method, delegates to the native implementation.

Parameters

• obj (Object) — the baseobject.
• key (Object) — the key to retrieve.
• indifferent_key (true, false) — if true and the key is a String or a Symbol, tries to match both the String and Symbol equivalent. Defaults to false.
• default (Object) — the default value.

Returns

• (Object) — the value at the specified key or index.

Raises

• (IndexError, KeyError, NameError) — if the object does not have a value for the requested key or index and there is no default value.

#fetch(obj, key, indifferent_key: false, &default) => Object

Retrieves the value at the specified method, key, or index.

If the value does not exist, returns the default value, or raises am exception if there is no default value. If the object defines a native #fetch method, delegates to the native implementation.

Parameters

• obj (Object) — the baseobject.
• key (Object) — the key to retrieve.
• indifferent_key (true, false) — if true and the key is a String or a Symbol, tries to match both the String and Symbol equivalent. Defaults to false.

Yields

• generates the default value if there is no value at the key.

Yield Parameters

• key (Object) — the requested key.

Yield Returns

• (Object) — the default value.

Returns

• (Object) — the value at the specified key or index.

Raises

• (IndexError, KeyError, NameError) — if the object does not have a value for the requested key or index and there is no default value.

#immutable?(obj) => Boolean

Checks if the object is immutable.

• nil, false, and true are always immutable, as are instances of Numeric and Symbol.
• Strings are immutable if frozen, such as strings defined in a file with a frozen_string_literal pragma.
• Arrays are immutable if the array is frozen and each array item is immutable.
• Hashes are immutable if the hash is frozen and each hash key and hash value are immutable.
• Otherwise, objects are immutable if they are frozen.

Examples

ObjectTools.immutable?(nil)
#=> true

ObjectTools.immutable?(false)
#=> true

ObjectTools.immutable?(0)
#=> true

ObjectTools.immutable?(:hello)
#=> true

ObjectTools.immutable?('Greetings, programs!')
#=> true

ObjectTools.immutable?(+'Greetings, programs!')
#=> false

ObjectTools.immutable?([1, 2, 3])
#=> false

ObjectTools.immutable?([1, 2, 3].freeze)
#=> false

Parameters

• obj (Object) — the object to test.

Returns

• (Boolean) — true if the object is immutable, otherwise false.

See Also

• #mutable?
• ArrayTools#immutable?
• HashTools#immutable?

#mutable?(obj) => Boolean

Checks if the object is mutable.

Parameters

• obj (Object) — the object to test.

Returns

• (Boolean) — true if the object is mutable, otherwise false.

See Also

• #immutable?

#object?(obj) => Boolean

Returns true if the object is an Object.

This should return false only for objects that have an alternate inheritance chain from BasicObject, such as a Proxy.

Examples

ObjectTools.object?(nil)
#=> true

ObjectTools.object?([])
#=> true

ObjectTools.object?({})
#=> true

ObjectTools.object?(1)
#=> true

ObjectTools.object?(BasicObject.new)
#=> false

Parameters

• obj (Object) — the object to test.

Returns

• (Boolean) — true if the object is an Object, otherwise false.

#toolbelt => SleepingKingStudios::Tools::Toolbelt

Also known as: tools

Inherited From

SleepingKingStudios::Tools::Base

Returns

• (SleepingKingStudios::Tools::Toolbelt) — the toolbelt this tools instance belongs to, or the global toolbelt singleton.

#try(obj, method_name, *args) => Object, nil (deprecated)

Deprecated. v1.3.0 Use the safe access operator &. instead.

As #send, but returns nil if the object does not respond to the method.

This method relies on #respond_to?, so methods defined with method_missing will not be called.

Examples

ObjectTools.try(%w(ichi ni san), :count)
#=> 3

ObjectTools.try(nil, :count)
#=> nil

Parameters

• obj (Object) — the receiver of the message.
• method_name (String, Symbol) — the name of the method to call.
• args (Array) — the arguments to the message.

Returns

• (Object, nil) — the return value of the called method, or nil if the object does not respond to the method.

Back To Top

---

Back to Documentation | Reference | SleepingKingStudios | SleepingKingStudios::Tools