Class: Dry::Struct

Inherits:

Object

• Object
• Dry::Struct

Extended by:

ClassInterface

Includes:

Core::Constants

Defined in:

lib/dry/struct.rb,
lib/dry/struct/value.rb,
lib/dry/struct/errors.rb,
lib/dry/struct/hashify.rb,
lib/dry/struct/version.rb,
lib/dry/struct/constructor.rb,
lib/dry/struct/class_interface.rb

Overview

Typed Struct with virtus-like DSL for defining schema.

Differences between dry-struct and virtus

Struct look somewhat similar to Virtus but there are few significant differences:

• Structs don't provide attribute writers and are meant to be used as "data objects" exclusively.
• Handling of attribute values is provided by standalone type objects from dry-types.
• Handling of attribute hashes is provided by standalone hash schemas from dry-types, which means there are different types of constructors in Struct (see ClassInterface#constructor_type)
• Struct classes quack like dry-types, which means you can use them in hash schemas, as array members or sum them

Struct class can specify a constructor type, which uses hash schemas to handle attributes in .new method. See ClassInterface#new for constructor types descriptions and examples.

Examples:

require 'dry-struct'

module Types
  include Dry::Types.module
end

class Book < Dry::Struct
  attribute :title, Types::Strict::String
  attribute :subtitle, Types::Strict::String.optional
end

rom_n_roda = Book.new(
  title: 'Web Development with ROM and Roda',
  subtitle: nil
)
rom_n_roda.title #=> 'Web Development with ROM and Roda'
rom_n_roda.subtitle #=> nil

refactoring = Book.new(
  title: 'Refactoring',
  subtitle: 'Improving the Design of Existing Code'
)
refactoring.title #=> 'Refactoring'
refactoring.subtitle #=> 'Improving the Design of Existing Code'

Direct Known Subclasses

Value

Defined Under Namespace

Modules: ClassInterface, Hashify Classes: Constructor, RepeatedAttributeError, Value

Constant Summary

CONSTRUCTOR_TYPE =

Dry::Types['symbol'].enum(:permissive, :schema, :strict, :strict_with_defaults)

Error =

Raised when given input doesn't conform schema and constructor type

Class.new(TypeError)

VERSION =

'0.4.0'.freeze

Instance Method Summary

• #[](name) ⇒ Object

  Retrieves value of previously defined attribute by its' name.

• #__attributes__ ⇒ Object private

  @return[Hash=> Object].

• #constructor_type ⇒ Object

  Sets or retrieves ClassInterface#constructor type as a symbol.

• #equalizer ⇒ Dry::Equalizer
• #initialize(attributes) ⇒ Struct constructor

  A new instance of Struct.

• #input ⇒ Dry::Types::Hash

  Types::Hash subclass with specific behaviour defined for.

• #new(changeset) ⇒ Struct (also: #__new__)

  Create a copy of Struct with overriden attributes.

• #schema ⇒ Hash{Symbol => Dry::Types::Definition, Dry::Struct}
• #to_hash ⇒ Hash{Symbol => Object} (also: #to_h)

  Converts the Struct to a hash with keys representing each attribute (as symbols) and their corresponding values.

Methods included from ClassInterface

argument_error_msg, attribute, attribute?, attribute_names, attributes, call, check_invalid_schema_keys, constrained?, constructor, default?, default_attributes, failure, inherited, optional?, primitive, result, success, try, valid?

Constructor Details

#initialize(attributes) ⇒ Struct

Returns a new instance of Struct.

Parameters:

• attributes (Hash, #each)

# File 'lib/dry/struct.rb', line 182

def initialize(attributes)
  attributes.each { |key, value| instance_variable_set("@#{key}", value) }
end

Instance Method Details

#[](name) ⇒ Object

Retrieves value of previously defined attribute by its' name

Examples:

class Book < Dry::Struct
  attribute :title, Types::Strict::String
  attribute :subtitle, Types::Strict::String.optional
end

rom_n_roda = Book.new(
  title: 'Web Development with ROM and Roda',
  subtitle: nil
)
rom_n_roda[:title] #=> 'Web Development with ROM and Roda'
rom_n_roda[:subtitle] #=> nil

Parameters:

• name (String)

Returns:

• (Object)

# File 'lib/dry/struct.rb', line 203

def [](name)
  public_send(name)
end

#__attributes__ ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

@return[Hash=> Object]

# File 'lib/dry/struct.rb', line 258

def __attributes__
  self.class.attribute_names.each_with_object({}) do |key, h|
    h[key] = instance_variable_get(:"@#{ key }")
  end
end

#constructor_type(type) ⇒ Symbol #constructor_type ⇒ Symbol

Note:

All examples below assume that you have defined Dry::Struct with following attributes and explicitly call only #constructor_type:

class User < Dry::Struct
  attribute :name, Types::Strict::String.default('John Doe')
  attribute :age, Types::Strict::Int
end

Sets or retrieves Dry::Struct::ClassInterface#constructor type as a symbol

Common constructor types include:

• :permissive - the default constructor type, useful for defining Dry::Structs that are instantiated using data from the database (i.e. results of a database query), where you expect all defined attributes to be present and it's OK to ignore other keys (i.e. keys used for joining, that are not relevant from your domain Dry::Structs point of view). Default values are not used otherwise you wouldn't notice missing data.
• :schema - missing keys will result in setting them using default values, unexpected keys will be ignored.
• :strict - useful when you do not expect keys other than the ones you specified as attributes in the input hash
• :strict_with_defaults - same as :strict but you are OK that some values may be nil and you want defaults to be set

To feel the difference between constructor types, look into examples. Each of them provide the same attributes' definitions, different constructor type, and 4 cases of given input:

1. Input omits a key for a value that does not have a default
2. Input omits a key for a value that has a default
3. Input contains nil for a value that specifies a default
4. Input includes a key that was not specified in the schema

Examples:

:permissive constructor

class User < Dry::Struct
  constructor_type :permissive
end

User.new(name: "Jane")
  #=> Dry::Struct::Error: [User.new] :age is missing in Hash input
User.new(age: 31)
  #=> Dry::Struct::Error: [User.new] :name is missing in Hash input
User.new(name: nil, age: 31)
  #=> #<User name="John Doe" age=31>
User.new(name: "Jane", age: 31, unexpected: "attribute")
  #=> #<User name="Jane" age=31>

:schema constructor

class User < Dry::Struct
  constructor_type :schema
end

User.new(name: "Jane")        #=> #<User name="Jane" age=nil>
User.new(age: 31)             #=> #<User name="John Doe" age=31>
User.new(name: nil, age: 31)  #=> #<User name="John Doe" age=31>
User.new(name: "Jane", age: 31, unexpected: "attribute")
  #=> #<User name="Jane" age=31>

:strict constructor

class User < Dry::Struct
  constructor_type :strict
end

User.new(name: "Jane")
  #=> Dry::Struct::Error: [User.new] :age is missing in Hash input
User.new(age: 31)
  #=> Dry::Struct::Error: [User.new] :name is missing in Hash input
User.new(name: nil, age: 31)
  #=> Dry::Struct::Error: [User.new] nil (NilClass) has invalid type for :name
User.new(name: "Jane", age: 31, unexpected: "attribute")
  #=> Dry::Struct::Error: [User.new] unexpected keys [:unexpected] in Hash input

:strict_with_defaults constructor

class User < Dry::Struct
  constructor_type :strict_with_defaults
end

User.new(name: "Jane")
  #=> Dry::Struct::Error: [User.new] :age is missing in Hash input
User.new(age: 31)
  #=> #<User name="John Doe" age=31>
User.new(name: nil, age: 31)
  #=> Dry::Struct::Error: [User.new] nil (NilClass) has invalid type for :name
User.new(name: "Jane", age: 31, unexpected: "attribute")
  #=> Dry::Struct::Error: [User.new] unexpected keys [:unexpected] in Hash input

Overloads:

• #constructor_type(type) ⇒ Symbol

  Sets the constructor type for Dry::Struct

  Parameters:

  • type (Symbol) —

    one of constructor types, see above

  Returns:

  • (Symbol)
• #constructor_type ⇒ Symbol

  Returns the constructor type for Dry::Struct

  Returns:

  • (Symbol) —

    (:strict)

See Also:

• http://dry-rb.org/gems/dry-types/hash-schemas

# File 'lib/dry/struct.rb', line 175

defines :constructor_type, type: CONSTRUCTOR_TYPE

#equalizer ⇒ Dry::Equalizer

Returns:

• (Dry::Equalizer)

# File 'lib/dry/struct.rb', line 179

defines :equalizer

#input ⇒ Dry::Types::Hash

Types::Hash subclass with specific behaviour defined for

Returns:

• (Dry::Types::Hash)

See Also:

• #constructor_type

# File 'lib/dry/struct.rb', line 66

defines :input

#new(changeset) ⇒ Struct Also known as: __new__

Create a copy of Dry::Struct with overriden attributes

Examples:

class Book < Dry::Struct
  attribute :title, Types::Strict::String
  attribute :subtitle, Types::Strict::String.optional
end

rom_n_roda = Book.new(
  title: 'Web Development with ROM and Roda',
  subtitle: '2nd edition'
)
  #=> #<Book title="Web Development with ROM and Roda" subtitle="2nd edition">

rom_n_roda.new(subtitle: '3nd edition')
  #=> #<Book title="Web Development with ROM and Roda" subtitle="3nd edition">

Parameters:

• changeset (Hash{Symbol => Object})

Returns:

• (Struct)

# File 'lib/dry/struct.rb', line 251

def new(changeset)
  self.class[__attributes__.merge(changeset)]
end

#schema ⇒ Hash{Symbol => Dry::Types::Definition, Dry::Struct}

Returns:

• (Hash{Symbol => Dry::Types::Definition, Dry::Struct})

# File 'lib/dry/struct.rb', line 70

defines :schema

#to_hash ⇒ Hash{Symbol => Object} Also known as: to_h

Converts the Dry::Struct to a hash with keys representing each attribute (as symbols) and their corresponding values

Examples:

class Book < Dry::Struct
  attribute :title, Types::Strict::String
  attribute :subtitle, Types::Strict::String.optional
end

rom_n_roda = Book.new(
  title: 'Web Development with ROM and Roda',
  subtitle: nil
)
rom_n_roda.to_hash
  #=> {title: 'Web Development with ROM and Roda', subtitle: nil}

Returns:

• (Hash{Symbol => Object})

# File 'lib/dry/struct.rb', line 224

def to_hash
  self.class.schema.keys.each_with_object({}) do |key, result|
    result[key] = Hashify[self[key]]
  end
end