Module: NestedObjects::Mixin

Defined in:
lib/nested_objects/mixin.rb

Overview

Include this module to add methods for working with nested data structures

Usually included into the Object class.

Examples:

require 'nested_objects/mixin'
Object.include(NestedObjects::Mixin)
data = { 'a' => { 'b' => [1, 2, 3] } }
data.nested_dig(['a', 'b', '0']) #=> 1

Instance Method Summary collapse

Instance Method Details

#nested_bury(path, value) ⇒ Object

Sets a value within a nested data structure

Creates intermediate Hashes along the path if they do not exist. Does NOT create intermediate Arrays (creates a Hash instead).

Examples:

data = { 'a' => { 'b' => [1, 2, 3] } }
NestedObjects.bury(data, ['a', 'b', '0'], 42) #=> { 'a' => { 'b' => [42, 2, 3] } }

will overwrite existing values

data = { 'a' => { 'b' => [1, 2, 3] } }
NestedObjects.bury(data, ['a'], 42) #=> { 'a' => 42 }

will create intermediate Hashes

data = {}
NestedObjects.bury(data, ['a', 'b'], 42) #=> { 'a' => { 'b' => 42 } })

will NOT create intermediate Arrays (creates a Hash instead)

data = {}
NestedObjects.bury(data, ['a', '0'], 42) #=> { 'a' => { '0' => [42, 2, 3] } }

Parameters:

  • data (Hash, Array, Object) —

    The structure to modify

  • path (Array<String>) —

    An array of keys/indices representing the path to the item to set

  • value (Object) —

    The value to set at the specified path

Returns:

  • (Object) —

    The modified data structure

Raises:

  • (BadPathError) —

    if the path is invalid or the item does not exist



23
 
# File 'lib/nested_objects/mixin.rb', line 23

def nested_bury(path, value) = NestedObjects.bury(self, path, value)

#nested_deep_copy ⇒ Object

Creates a deep copy of data using Marshal

Examples:

data = { 'a' => { 'b' => [1, 2, 3] } }
NestedObjects.deep_copy(data) #=> { 'a' => { 'b' => [1, 2, 3] } }

Parameters:

  • data (Object) —

    The object to be deeply copied

Returns:

  • (Object) —

    A new object that is a deep copy of the input obj

Raises:

  • (TypeError) —

    if the object cannot be marshaled (see Marshal documentation)



29
 
# File 'lib/nested_objects/mixin.rb', line 29

def nested_deep_copy = NestedObjects.deep_copy(self)

#nested_delete(path) ⇒ Object

Delete a key or element from nested data identified by path

Examples:

data = { 'a' => { 'b' => [1, 2, 3] } }
NestedObjects.delete(data, ['a', 'b', '0']) #=> 1
data #=> { 'a' => { 'b' => [2, 3] } }

Parameters:

  • data (Hash, Array, Object) —

    The structure to modify

  • path (Array<String>) —

    An array of keys/indices representing the path to the item to delete

Returns:

  • (Object) —

    The value of the element that was deleted

Raises:

  • (BadPathError) —

    if the path is invalid or the item does not exist



26
 
# File 'lib/nested_objects/mixin.rb', line 26

def nested_delete(path) = NestedObjects.delete(self, path)

#nested_dig(path) ⇒ Object

Retrieves the value at the specified path in the given data

Examples:

data = { 'a' => { 'b' => [1, 2, 3] } }
NestedObjects.dig(data, ['a', 'b', '0']) #=> 1

Parameters:

  • data (Hash, Array, Object) —

    The data containing the value to retrieve

  • path (Array<String>) —

    An array of keys/indices representing the path to the desired value

Returns:

  • (Object) —

    the value at the specified path

Raises:

  • (BadPathError) —

    if the path is invalid or does not exist



20
 
# File 'lib/nested_objects/mixin.rb', line 20

def nested_dig(path) = NestedObjects.dig(self, path)

#nested_path?(path) ⇒ Boolean

Check if the path is valid for the given data structure

Examples:

data = { 'a' => { 'b' => [1, 2, 3] } }
NestedObjects.path?(data, ['a', 'b', '0']) #=> true
NestedObjects.path?(data, ['d']) #=> false

Parameters:

  • data (Hash, Array, Object) —

    The structure to check

  • path (Array<String>) —

    An array of keys/indices representing the path to check

Returns:

  • (Boolean) —

    true if the path is valid, false otherwise

Raises:

  • (BadPathError) —

    if path tries to traverse an Array with a non-integer key



17
 
# File 'lib/nested_objects/mixin.rb', line 17

def nested_path?(path) = NestedObjects.path?(self, path)