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/nullify_blank.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 "not really coercible" into Integer

Direct Known Subclasses

Boolean, Collection, EmbeddedValue, Hash

Defined Under Namespace

Modules: Accessor, Coercible, LazyDefault, NullifyBlank, 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.



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

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. 



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

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. 



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

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. 



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

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. 



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

def primitive
  @primitive
end

#type ⇒ Axiom::Types::Type (readonly)

Return type of this attribute

Returns:

  • (Axiom::Types::Type) 


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

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:



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

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. 



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

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. 



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

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

.coerce(value = Undefined) ⇒ Object

Deprecated.

See Also:



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

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. 



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

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) 


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

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:



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

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. 



232
233
234
235
 
# File 'lib/virtus/attribute.rb', line 232

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. 



238
239
240
241
 
# File 'lib/virtus/attribute.rb', line 238

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:



227
228
229
 
# File 'lib/virtus/attribute.rb', line 227

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:



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

def lazy?
  kind_of?(LazyDefault)
end

#nullify_blank? ⇒ Boolean

Return if the attribute is in the nullify blank coercion mode

Examples:


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

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

Returns:



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

def nullify_blank?
  kind_of?(NullifyBlank)
end

#rename(name) ⇒ Attribute

Return a new attribute with the new name

Parameters:

  • name (Symbol)

Returns:



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

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:



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

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:



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

def strict?
  kind_of?(Strict)
end

#value_coerced?(value) ⇒ Boolean

Return if the given value was coerced

Parameters:

  • value (Object)

Returns:



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

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