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!, interface!, mixes_in_class_methods

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::Props::CustomType) —

    (String) 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.



107
108
109
110
 
# File 'lib/types/props/_props.rb', line 107

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 



132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/types/props/_props.rb', line 132

def const(name, cls_or_args, args={})
  if (cls_or_args.is_a?(Hash) && cls_or_args.key?(:immutable)) || args.key?(:immutable)
    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 



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

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

#included(child) ⇒ Object 



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

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

#inherited(child) ⇒ Object 



159
160
161
162
 
# File 'lib/types/props/_props.rb', line 159

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

#plugin(mod) ⇒ Object

Needs to be documented



126
127
128
 
# File 'lib/types/props/_props.rb', line 126

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 



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

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::Props::CustomType) —

    (String) 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.

  • :array (Class, T::Props::CustomType) —

    If set, specifies the type of individual members of a prop with ‘type` `Array`. This allows for typechecking of arrays, and also for recursive serialization of arrays of sub-Documents.

  • :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.



107
108
109
110
 
# File 'lib/types/props/_props.rb', line 107

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) 


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

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