Class: Virtus::Attribute

Inherits:
Object
  • Object
show all
Extended by:
DescendantsTracker, Options, TypeLookup
Defined in:
lib/virtus/attribute.rb,
lib/virtus/attribute/hash.rb,
lib/virtus/attribute/strict.rb,
lib/virtus/attribute/boolean.rb,
lib/virtus/attribute/builder.rb,
lib/virtus/attribute/coercer.rb,
lib/virtus/attribute/accessor.rb,
lib/virtus/attribute/coercible.rb,
lib/virtus/attribute/collection.rb,
lib/virtus/attribute/lazy_default.rb,
lib/virtus/attribute/default_value.rb,
lib/virtus/attribute/embedded_value.rb,
lib/virtus/attribute/default_value/from_symbol.rb,
lib/virtus/attribute/default_value/from_callable.rb,
lib/virtus/attribute/default_value/from_clonable.rb

Overview

Attribute objects handle coercion and provide interface to hook into an attribute set instance that's included into a class or object

Examples:


# non-strict mode
attr = Virtus::Attribute.build(Integer)
attr.coerce('1')
# => 1

# strict mode
attr = Virtus::Attribute.build(Integer, :strict => true)
attr.coerce('not really coercible')
# => Virtus::CoercionError: Failed to coerce "fsafa" into Integer

Direct Known Subclasses

Boolean, Collection, EmbeddedValue, Hash

Defined Under Namespace

Modules: Accessor, Coercible, LazyDefault, Strict Classes: Boolean, Builder, Coercer, Collection, DefaultValue, EmbeddedValue, Hash

Constant Summary

Constants included from TypeLookup

TypeLookup::TYPE_FORMAT

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Options

accept_options, accepted_options

Methods included from TypeLookup

determine_type, extended

Constructor Details

#initialize(type, options) ⇒ Attribute

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.

Returns a new instance of Attribute.


84
85
86
87
88
89
90
# File 'lib/virtus/attribute.rb', line 84

def initialize(type, options)
  @type          = type
  @primitive     = type.primitive
  @options       = options
  @default_value = options.fetch(:default_value)
  @coercer       = options.fetch(:coercer)
end

Instance Attribute Details

#coercerObject (readonly)

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.


50
51
52
# File 'lib/virtus/attribute.rb', line 50

def coercer
  @coercer
end

#default_valueObject (readonly)

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.


50
51
52
# File 'lib/virtus/attribute.rb', line 50

def default_value
  @default_value
end

#optionsObject (readonly)

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.


50
51
52
# File 'lib/virtus/attribute.rb', line 50

def options
  @options
end

#primitiveObject (readonly)

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.


50
51
52
# File 'lib/virtus/attribute.rb', line 50

def primitive
  @primitive
end

#typeAxiom::Types::Type (readonly)

Return type of this attribute

Returns:

  • (Axiom::Types::Type)

47
48
49
# File 'lib/virtus/attribute.rb', line 47

def type
  @type
end

Class Method Details

.build(type, options = {}) ⇒ Attribute

Builds an attribute instance

Parameters:

  • type (Class, Array, Hash, String, Symbol)

    this can be an explicit class or an object from which virtus can infer the type

  • options (#to_hash) (defaults to: {})

    optional extra options hash

Returns:


64
65
66
# File 'lib/virtus/attribute.rb', line 64

def self.build(type, options = {})
  Builder.call(type, options)
end

.build_coercer(type, options = {}) ⇒ 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.


69
70
71
# File 'lib/virtus/attribute.rb', line 69

def self.build_coercer(type, options = {})
  Coercer.new(type, options.fetch(:configured_coercer) { Virtus.coercer })
end

.build_type(definition) ⇒ 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.


74
75
76
# File 'lib/virtus/attribute.rb', line 74

def self.build_type(definition)
  Axiom::Types.infer(definition.primitive)
end

.coerce(value = Undefined) ⇒ Object

Deprecated.

See Also:


35
36
37
38
39
40
# File 'lib/virtus/attribute.rb', line 35

def self.coerce(value = Undefined)
  Virtus.warn "#{self}.coerce is deprecated and will be removed in 1.0.0. Use Virtus.coerce instead: ##{caller.first}"
  return Virtus.coerce if value.equal?(Undefined)
  Virtus.coerce = value
  self
end

.merge_options!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.


79
80
81
# File 'lib/virtus/attribute.rb', line 79

def self.merge_options!(*)
  # noop
end

Instance Method Details

#coerce(input) ⇒ Object

Coerce the input into the expected type

Examples:


attr = Virtus::Attribute.build(String)
attr.coerce(:one) # => 'one'

Parameters:

  • input (Object)

102
103
104
# File 'lib/virtus/attribute.rb', line 102

def coerce(input)
  coercer.call(input)
end

#coercible?Boolean

Return if the attribute is coercible

Examples:


attr = Virtus::Attribute.build(String, :coerce => true)
attr.coercible? # => true

attr = Virtus::Attribute.build(String, :coerce => false)
attr.coercible? # => false

Returns:


141
142
143
# File 'lib/virtus/attribute.rb', line 141

def coercible?
  kind_of?(Coercible)
end

#define_accessor_methods(attribute_set) ⇒ 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.


214
215
216
217
# File 'lib/virtus/attribute.rb', line 214

def define_accessor_methods(attribute_set)
  attribute_set.define_reader_method(self, name,       options[:reader])
  attribute_set.define_writer_method(self, "#{name}=", options[:writer])
end

#finalizeObject

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.


220
221
222
223
# File 'lib/virtus/attribute.rb', line 220

def finalize
  freeze
  self
end

#finalized?Boolean

Return if the attribute was already finalized

Examples:


attr = Virtus::Attribute.build(String, :finalize => true)
attr.finalized? # => true

attr = Virtus::Attribute.build(String, :finalize => false)
attr.finalized? # => false

Returns:


209
210
211
# File 'lib/virtus/attribute.rb', line 209

def finalized?
  frozen?
end

#lazy?Boolean

Return if the attribute has lazy default value evaluation

Examples:


attr = Virtus::Attribute.build(String, :lazy => true)
attr.lazy? # => true

attr = Virtus::Attribute.build(String, :lazy => false)
attr.lazy? # => false

Returns:


158
159
160
# File 'lib/virtus/attribute.rb', line 158

def lazy?
  kind_of?(LazyDefault)
end

#rename(name) ⇒ Attribute

Return a new attribute with the new name

Parameters:

  • name (Symbol)

Returns:


113
114
115
# File 'lib/virtus/attribute.rb', line 113

def rename(name)
  self.class.build(type, options.merge(:name => name))
end

#required?Boolean

Return if the attribute is accepts nil values as valid coercion output

Examples:


attr = Virtus::Attribute.build(String, :required => true)
attr.required? # => true

attr = Virtus::Attribute.build(String, :required => false)
attr.required? # => false

Returns:


192
193
194
# File 'lib/virtus/attribute.rb', line 192

def required?
  options[:required]
end

#strict?Boolean

Return if the attribute is in the strict coercion mode

Examples:


attr = Virtus::Attribute.build(String, :strict => true)
attr.strict? # => true

attr = Virtus::Attribute.build(String, :strict => false)
attr.strict? # => false

Returns:


175
176
177
# File 'lib/virtus/attribute.rb', line 175

def strict?
  kind_of?(Strict)
end

#value_coerced?(value) ⇒ Boolean

Return if the given value was coerced

Parameters:

  • value (Object)

Returns:


124
125
126
# File 'lib/virtus/attribute.rb', line 124

def value_coerced?(value)
  coercer.success?(primitive, value)
end