Class: NRSER::Meta::Props::Prop

Inherits:
Object
  • Object
show all
Defined in:
lib/nrser/meta/props/prop.rb

Overview

‘Prop` instances hold the configuration for a property defined on propertied classes.

Props are immutable by design.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(defined_in, name, type: t.any, default: nil, default_from: nil, source: nil, to_data: nil, from_data: nil) ⇒ Prop

Instantiate a new ‘Prop` instance.

You should not need to construct a ‘Prop` directly unless you are doing custom meta-programming - they should be constructed for you via the `.prop` “macro” defined at ClassMethods#prop that is extended in to classes including NRSER::Meta::Props.



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/nrser/meta/props/prop.rb', line 70

def initialize  defined_in,
                name,
                type: t.any,
                default: nil,
                default_from: nil,
                source: nil,
                to_data: nil,
                from_data: nil
  
  # Set these up first so {#to_s} works in case we need to raise errors.
  @defined_in = defined_in
  @name = name
  @type = t.make type
  
  @to_data = to_data
  @from_data = from_data
  
  # Source
  
  @source = source # TODO fix this: t.maybe( t.label ).check source
  
  # Detect if the source
  if source.nil?
    @instance_variable_source = false
  else
    # TODO Check that default and default_from are `nil`, make no sense here
    
    source_str = source.to_s
    @instance_variable_source = source_str[0] == '@'
  end
  
  # Defaults
  
  # Can't provide both default and default_from
  unless default.nil? || default_from.nil?
    raise NRSER::ConflictError.new binding.erb <<-ERB
      Both `default:` and `default_from:` keyword args provided when
      constructing <%= self %>. At least one must be `nil`.
      
      default:
          <%= default.pretty_inspect %>
      
      default_from:
          <%= default_from.pretty_inspect %>
      
    ERB
  end
  
  if default_from.nil?
    # We are going to use `default`
        
    # Validate `default` value
    if default.nil?
      # If it's `nil` we still want to see if it's a valid value for the type
      # so we can report if this prop has a default value or not.
      # 
      # However, we only need to do that if there is no `source`
      # 
      @has_default = if source.nil?
        @type.test default
      else
        # NOTE  This is up for debate... does a derived property have a
        #       default? What does that even mean?
        true # false ?
      end
      
    else
      # Check that the default value is valid for the type, raising TypeError
      # if it isn't.
      @type.check( default ) { |type:, value:|
        binding.erb <<-ERB
          Default value is not valid for <%= self %>:
          
              <%= value.pretty_inspect %>
          
        ERB
      }
      
      # If we passed the check we know the value is valid
      @has_default = true
      
      # Set the default value to `default`, freezing it since it will be
      # set on instances without any attempt at duplication, which seems like
      # it *might be ok* since a lot of prop'd classes are being used
      # immutably.
      @default_value = default.freeze
    end
    
  else
    # `default_from` is not `nil`, so we're going to use that.
    
    # This means we "have" a default since we believe we can use it to make
    # one - the actual values will have to be validates at that point.
    @has_default = true
    
    # And set it.
    # 
    # TODO validate it's something reasonable here?
    # 
    @default_from = default_from
  end
  
end

Instance Attribute Details

#defined_in ⇒ Class (readonly)

The class the prop was defined in.

Returns:

  • (Class) 


30
31
32
 
# File 'lib/nrser/meta/props/prop.rb', line 30

def defined_in
  @defined_in
end

#name ⇒ Symbol (readonly)

The name of the prop, which is used as it’s method name and key where applicable.

Returns:

  • (Symbol) 


38
39
40
 
# File 'lib/nrser/meta/props/prop.rb', line 38

def name
  @name
end

#source ⇒ Symbol | String (readonly)

Optional name of instance variable (including the ‘@` prefix) or getter method (method that takes no arguments) that provides the property’s value.

Props that have a source are considered derived, those that don’t are called primary.

Returns:

  • (Symbol | String) 


57
58
59
 
# File 'lib/nrser/meta/props/prop.rb', line 57

def source
  @source
end

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

The type of the valid values for the property.

Returns:



45
46
47
 
# File 'lib/nrser/meta/props/prop.rb', line 45

def type
  @type
end

Instance Method Details

#default ⇒ Object 



204
205
206
207
208
209
210
211
212
 
# File 'lib/nrser/meta/props/prop.rb', line 204

def default
  if default?
    @default
  else
    raise NameError.new NRSER.squish <<-END
      Prop #{ self } has no default value.
    END
  end
end

#full_name ⇒ String

Full name with class prop was defined in.

Examples:

MyMod::SomeClass.props[:that_prop].full_name
# => 'MyMod::SomeClass#full_name'

Returns:

  • (String) 


183
184
185
 
# File 'lib/nrser/meta/props/prop.rb', line 183

def full_name
  "#{ defined_in.name }##{ name }"
end

#get(instance) ⇒ return_type

TODO:

Document get method.

Returns @todo Document return value.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/nrser/meta/props/prop.rb', line 262

def get instance
  if source?
    if instance_variable_source?
      instance.instance_variable_get source
    else
      case source
      when String, Symbol
        instance.send source
      when Proc
        instance.instance_exec &source
      else
        raise TypeError.squished <<-END
          Expected `Prop#source` to be a String, Symbol or Proc;
          found #{ source.inspect }
        END
      end
    end
  else
    values(instance)[name]
  end
end

#has_default? ⇒ return_type Also known as: default?

Test if this prop is configured to provide default values -

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



196
197
198
 
# File 'lib/nrser/meta/props/prop.rb', line 196

def has_default?
  @has_default
end

#instance_variable_source? ⇒ return_type

TODO:

Document instance_variable_source? method.

Returns @todo Document return value.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



236
237
238
 
# File 'lib/nrser/meta/props/prop.rb', line 236

def instance_variable_source?
  @instance_variable_source
end

#primary? ⇒ return_type

TODO:

Document primary? method.

Returns @todo Document return value.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



249
250
251
 
# File 'lib/nrser/meta/props/prop.rb', line 249

def primary?
  !source?
end

#set(instance, value) ⇒ return_type

TODO:

Document set method.

Returns @todo Document return value.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/nrser/meta/props/prop.rb', line 293

def set instance, value
  type.check( value ) do
    binding.erb <<-END
      Value of type <%= value.class.name %> for prop <%= self.full_name %>
      failed type check.
      
      Must satisfy type:
      
          <%= type %>
      
      Given value:
      
          <%= value.pretty_inspect %>
      
    END
  end
  
  values(instance)[name] = value
end

#set_from_values_hash(instance, **values) ⇒ return_type

TODO:

Document set_from_hash method.

Returns @todo Document return value.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
 
# File 'lib/nrser/meta/props/prop.rb', line 322

def set_from_values_hash instance, **values
  if values.key? name
    set instance, values[name]
  else
    if default?
      # set instance, if !default.nil? && default.respond_to?( :dup )
      #   default.dup
      # else
      #   default
      # end
      set instance, default
    else
      raise TypeError.new binding.erb <<-ERB
        Prop <#= full_name %> has no default value and no value was provided
        in values:
        
            <%= values.pretty_inspect %>
        
      ERB
    end
  end
end

#source? ⇒ return_type

TODO:

Document source? method.

Returns @todo Document return value.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



223
224
225
 
# File 'lib/nrser/meta/props/prop.rb', line 223

def source?
  !@source.nil?
end

#to_data(instance) ⇒ Object

Get the “data” value - a basic scalar or structure of hashes, arrays and scalars, suitable for JSON encoding, etc. - for the property from an instance.

The process depends on the ‘to_data:` keyword provided at property declaration:

  1. nil default

    • If the property value responds to ‘#to_data`, the result of invoking that method will be returned.

      WARNING

      This can cause infinite recursion if an instance has a property value that is also an instance of the same class (as as other more complicated scenarios that boil down to the same problem), but, really, what else would it do in this situation?

      This problem can be avoided by by providing a ‘to_data:` keyword when declaring the property that dictates how to handle it’s value. In fact, that was the motivation for adding ‘to_data:`.

    • Otherwise, the value itself is returned, under the assumption that it is already suitable as data.

  2. Symbol | String

    • The ‘to_data:` string or symbol is sent to the property value (the method with this name is called via Object#send).

  3. Proc

    • The ‘to_data:` proc is called with the property value as the sole argument and the result is returned as the data.

Parameters:

Returns:

  • (Object) —

    Data representation of the property value (hopefully - the value itself is returned if we don’t have any better options, see above).

Raises:

  • (TypeError) —

    If @to_data (provided via the ‘to_data:` keyword at property declaration) is anything other than nil, String, Symbol or Proc.



390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
 
# File 'lib/nrser/meta/props/prop.rb', line 390

def to_data instance
  value = get instance
  
  case @to_data
  when nil
    if value.respond_to? :to_data
      value.to_data
    elsif type.respond_to? :to_data
      type.to_data value
    else
      value
    end
  when Symbol, String
    value.send @to_data
  when Proc
    @to_data.call value
  else
    raise TypeError.squished <<-END
      Expected `@to_data` to be Symbol, String or Proc;
      found #{ @to_data.inspect }
    END
  end
end

#to_s ⇒ String

Returns a short string describing the instance.

Returns:

  • (String) —

    a short string describing the instance.



476
477
478
 
# File 'lib/nrser/meta/props/prop.rb', line 476

def to_s
  "#<#{ self.class.name } #{ full_name }:#{ type }>"
end

#value_from_data(data) ⇒ return_type

TODO:

Document value_from_data method.

Returns @todo Document return value.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
 
# File 'lib/nrser/meta/props/prop.rb', line 423

def value_from_data data
  value = case @from_data
  when nil
    # This {Prop} does not have any custom `from_data` instructions, which
    # means we must rely on the {#type} to covert *data* to a *value*.
    # 
    if type.has_from_data?
      type.from_data data
    else
      data
    end
    
  when Symbol, String
    # The custom `from_data` configuration specifies a string or symbol name,
    # which we interpret as a class method on the defining class and call
    # with the data to produce a value.
    @defined_in.send @to_data, data
  
  when Proc
    # The custom `from_data` configuration provides a procedure, which we
    # call with the data to produce the value.
    @from_data.call data
    
  else
    raise TypeError.new binding.erb <<-ERB
      Expected `@from_data` to be Symbol, String or Proc;
      found <%= @from_data.class %>.
      
      Acceptable types:
      
      -   Symbol or String
          -   Name of class method on the class this property is defined in
              (<%= @defined_in %>) to call with data to convert it to a
              property value.
              
      -   Proc
          -   Procedure to call with data to convert it to a property value.
      
      Found `@from_data`:
      
          <%= @from_data.pretty_inspect %>
      
      (type <%= @from_data.class %>)
      
    ERB
  end
    
end