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 TypeLookup

determine_type, extended

Methods included from Options

accept_options, accepted_options

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

#coercer ⇒ Object (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_value ⇒ Object (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

#options ⇒ Object (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

#primitive ⇒ Object (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

#type ⇒ Axiom::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

#finalize ⇒ 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. 



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