Module: T::Props::ClassMethods

Extended by:
Helpers, Sig
Defined in:
lib/types/props/_props.rb

Overview

CAUTION: This mixin is used in hundreds of classes; we want to keep its surface area as narrow as possible and avoid polluting (and possibly conflicting with) the classes that use it.

It currently has zero instance methods; let’s try to keep it that way. For ClassMethods (below), try to add things to T::Props::Decorator instead unless you are sure it needs to be exposed here.

Constant Summary

Constants included from Helpers

Helpers::Private

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Sig

sig

Methods included from Helpers

abstract!, final!, interface!, mixes_in_class_methods, sealed!

Class Method Details

.prop(name, type, opts = {}) ⇒ void

This method returns an undefined value.

Define a new property. See README for some concrete

examples.

Defining a property defines a method with the same name as the property, that returns the current value, and a prop= method to set its value. Properties will be inherited by subclasses of a document class.

Parameters:

  • name (Symbol) —

    The name of this property

  • cls (Class, T::Types::Base) —

    The type of this property. If the type is itself a Document subclass, this property will be recursively serialized/deserialized.

  • rules (Hash) —

    Options to control this property’s behavior.



103
104
105
106
 
# File 'lib/types/props/_props.rb', line 103

def prop(name, cls, rules={})
  cls = T::Utils.coerce(cls) if !cls.is_a?(Module)
  decorator.prop_defined(name, cls, rules)
end

Instance Method Details

#const(name, cls_or_args, args = {}) ⇒ Object 



128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/types/props/_props.rb', line 128

def const(name, cls_or_args, args={})
  if (cls_or_args.is_a?(Hash) && cls_or_args.key?(:immutable)) || args.key?(:immutable)
    Kernel.raise ArgumentError.new("Cannot pass 'immutable' argument when using 'const' keyword to define a prop")
  end

  if cls_or_args.is_a?(Hash)
    self.prop(name, cls_or_args.merge(immutable: true))
  else
    self.prop(name, cls_or_args, args.merge(immutable: true))
  end
end

#decorator ⇒ Object 



28
 
# File 'lib/types/props/_props.rb', line 28

def decorator; @decorator ||= decorator_class.new(self); end

#decorator_class ⇒ Object 



26
 
# File 'lib/types/props/_props.rb', line 26

def decorator_class; Decorator; end

#extended(child) ⇒ Object 



150
151
152
153
 
# File 'lib/types/props/_props.rb', line 150

def extended(child)
  decorator.model_inherited(child.singleton_class)
  super
end

#included(child) ⇒ Object 



140
141
142
143
 
# File 'lib/types/props/_props.rb', line 140

def included(child)
  decorator.model_inherited(child)
  super
end

#inherited(child) ⇒ Object 



155
156
157
158
 
# File 'lib/types/props/_props.rb', line 155

def inherited(child)
  decorator.model_inherited(child)
  super
end

#plugin(mod) ⇒ Object

Needs to be documented



122
123
124
 
# File 'lib/types/props/_props.rb', line 122

def plugin(mod)
  decorator.plugin(mod)
end

#plugins ⇒ Object 



24
 
# File 'lib/types/props/_props.rb', line 24

def plugins; @plugins ||= []; end

#prepended(child) ⇒ Object 



145
146
147
148
 
# File 'lib/types/props/_props.rb', line 145

def prepended(child)
  decorator.model_inherited(child)
  super
end

#prop(name, cls, rules = {}) ⇒ void

This method returns an undefined value.

Define a new property. See README for some concrete

examples.

Defining a property defines a method with the same name as the property, that returns the current value, and a prop= method to set its value. Properties will be inherited by subclasses of a document class.

Parameters:

  • name (Symbol) —

    The name of this property

  • cls (Class, T::Types::Base) —

    The type of this property. If the type is itself a Document subclass, this property will be recursively serialized/deserialized.

  • rules (Hash) (defaults to: {}) —

    Options to control this property’s behavior.

Options Hash (rules):

  • :optional (T::Boolean, Symbol) —

    If true, this property is never required to be set before an instance is serialized. If :on_load (default), when this property is missing or nil, a new model cannot be saved, and an existing model can only be saved if the property was already missing when it was loaded. If false, when the property is missing/nil after deserialization, it will be set to the default value (as defined by the default or factory option) or will raise if they are not present. Deprecated: For Models, if :optional is set to the special value :existing, the property can be saved as nil even if it was deserialized with a non-nil value. (Deprecated because there should never be a need for this behavior; the new behavior of non-optional properties should be sufficient.)

  • :enum (Array) —

    An array of legal values; The property is required to take on one of those values.

  • :dont_store (T::Boolean) —

    If true, this property will not be saved on the hash resulting from #serialize

  • :ifunset (Object) —

    A value to be returned if this property is requested but has never been set (is set to nil). It is applied at property-access time, and never saved back onto the object or into the database.

    :ifunset is considered DEPRECATED and should not be used

    in new code, in favor of just setting a default value.
  • :foreign (Model, Symbol, Proc) —

    A model class that this property is a reference to. Passing :foreign will define a ‘:“#name_”` method, that will load and return the corresponding foreign model.

    A symbol can be passed to avoid load-order dependencies; It will be lazily resolved relative to the enclosing module of the defining class.

    A callable (proc or method) can be passed to dynamically specify the foreign model. This will be passed the object instance so that other properties of the object can be used to determine the relevant model class. It should return a string/symbol class name or the foreign model class directly.

  • :default (Object) —

    A default value that will be set by #initialize if none is provided in the initialization hash. This will not affect objects loaded by from_hash.

  • :factory (Proc) —

    A Proc that will be called to generate an initial value for this prop on #initialize, if none is provided.

  • :immutable (T::Boolean) —

    If true, this prop cannot be modified after an instance is created or loaded from a hash.

  • :override (T::Boolean) —

    It is an error to redeclare a prop that has already been declared (including on a superclass), unless :override is set to true.

  • :redaction (Symbol, Array) —

    A redaction directive that may be passed to Chalk::Tools::RedactionUtils.redact_with_directive to sanitize this parameter for display. Will define a ‘:“#name_redacted”` method, which will return the value in sanitized form.



103
104
105
106
 
# File 'lib/types/props/_props.rb', line 103

def prop(name, cls, rules={})
  cls = T::Utils.coerce(cls) if !cls.is_a?(Module)
  decorator.prop_defined(name, cls, rules)
end

#props ⇒ Object 



23
 
# File 'lib/types/props/_props.rb', line 23

def props; decorator.props; end

#reload_decorator! ⇒ Object 



29
 
# File 'lib/types/props/_props.rb', line 29

def reload_decorator!; @decorator = decorator_class.new(self); end

#validate_prop_value(propname, value) ⇒ void

This method returns an undefined value.

Validates the value of the specified prop. This method allows the caller to

validate a value for a prop without having to set the data on the instance.
Throws if invalid.

Parameters:

  • prop (Symbol)
  • val (Object) 


117
118
119
 
# File 'lib/types/props/_props.rb', line 117

def validate_prop_value(prop, val)
  decorator.validate_prop_value(prop, val)
end