Class: FinchAPI::Type::BaseModel Abstract

Inherits:
Object
  • Object
show all
Extended by:
Converter
Defined in:
lib/finch-api/type/base_model.rb

Overview

This class is abstract.

Examples:

# `operation_support_matrix` is a `FinchAPI::Models::OperationSupportMatrix`
operation_support_matrix => {
  create: create,
  delete: delete,
  read: read
}

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Converter

coerce, dump, type_info

Constructor Details

#initialize(data = {}) ⇒ BaseModel

Create a new instance of a model.

Parameters:



335
336
337
338
339
340
341
342
 
# File 'lib/finch-api/type/base_model.rb', line 335

def initialize(data = {})
  case FinchAPI::Util.coerce_hash(data)
  in Hash => coerced
    @data = coerced
  else
    raise ArgumentError.new("Expected a #{Hash} or #{FinchAPI::BaseModel}, got #{data.inspect}")
  end
end

Class Method Details

.==(other) ⇒ Boolean

Parameters:

  • other (Object)

Returns:

  • (Boolean) 


168
 
# File 'lib/finch-api/type/base_model.rb', line 168

def ==(other) = other.is_a?(Class) && other <= FinchAPI::BaseModel && other.fields == fields

.coerce(value, state:) ⇒ FinchAPI::BaseModel, 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.

Parameters:

  • value (FinchAPI::BaseModel, Hash{Object=>Object}, Object)
  • state (Hash{Symbol=>Object}) —

    .

    @option state [Boolean, :strong] :strictness

    @option state [HashSymbol=>Object] :exactness

    @option state [Integer] :branched

Returns:



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/finch-api/type/base_model.rb', line 190

def coerce(value, state:)
  exactness = state.fetch(:exactness)

  if value.is_a?(self.class)
    exactness[:yes] += 1
    return value
  end

  unless (val = FinchAPI::Util.coerce_hash(value)).is_a?(Hash)
    exactness[:no] += 1
    return value
  end
  exactness[:yes] += 1

  keys = val.keys.to_set
  instance = new
  data = instance.to_h

  fields.each do |name, field|
    mode, required, target = field.fetch_values(:mode, :required, :type)
    api_name, nilable, const = field.fetch_values(:api_name, :nilable, :const)

    unless val.key?(api_name)
      if const != FinchAPI::Util::OMIT
        exactness[:yes] += 1
      elsif required && mode != :dump
        exactness[nilable ? :maybe : :no] += 1
      else
        exactness[:yes] += 1
      end
      next
    end

    item = val.fetch(api_name)
    keys.delete(api_name)

    converted =
      if item.nil? && (nilable || !required)
        exactness[nilable ? :yes : :maybe] += 1
        nil
      else
        coerced = FinchAPI::Type::Converter.coerce(target, item, state: state)
        case target
        in FinchAPI::Type::Converter | Symbol
          coerced
        else
          item
        end
      end
    data.store(name, converted)
  end

  keys.each { data.store(_1, val.fetch(_1)) }
  instance
end

.dump(value) ⇒ Hash{Object=>Object}, 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.

Parameters:

Returns:

  • (Hash{Object=>Object}, Object) 


251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/finch-api/type/base_model.rb', line 251

def dump(value)
  unless (coerced = FinchAPI::Util.coerce_hash(value)).is_a?(Hash)
    return super
  end

  acc = {}

  coerced.each do |key, val|
    name = key.is_a?(String) ? key.to_sym : key
    case (field = known_fields[name])
    in nil
      acc.store(name, super(val))
    else
      mode, api_name, type_fn = field.fetch_values(:mode, :api_name, :type_fn)
      case mode
      in :coerce
        next
      else
        target = type_fn.call
        acc.store(api_name, FinchAPI::Type::Converter.dump(target, val))
      end
    end
  end

  known_fields.each_value do |field|
    mode, api_name, const = field.fetch_values(:mode, :api_name, :const)
    next if mode == :coerce || acc.key?(api_name) || const == FinchAPI::Util::OMIT
    acc.store(api_name, const)
  end

  acc
end

.fields ⇒ Hash{Symbol=>Hash{Symbol=>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.

Returns:

  • (Hash{Symbol=>Hash{Symbol=>Object}}) 


31
32
33
34
35
 
# File 'lib/finch-api/type/base_model.rb', line 31

def fields
  known_fields.transform_values do |field|
    {**field.except(:type_fn), type: field.fetch(:type_fn).call}
  end
end

.known_fields ⇒ Hash{Symbol=>Hash{Symbol=>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.

Assumes superclass fields are totally defined before fields are accessed /

defined on subclasses.

Returns:

  • (Hash{Symbol=>Hash{Symbol=>Object}}) 


24
25
26
 
# File 'lib/finch-api/type/base_model.rb', line 24

def known_fields
  @known_fields ||= (self < FinchAPI::BaseModel ? superclass.known_fields.dup : {})
end

.optional(name_sym, type_info, spec = {}) ⇒ 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.

Parameters:

  • name_sym (Symbol)
  • type_info (Hash{Symbol=>Object}, Proc, FinchAPI::Type::Converter, Class)
  • spec (Hash{Symbol=>Object}) (defaults to: {}) —

    .

    @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const

    @option spec [Proc] :enum

    @option spec [Proc] :union

    @option spec [Boolean] :“nil?”



136
137
138
 
# File 'lib/finch-api/type/base_model.rb', line 136

def optional(name_sym, type_info, spec = {})
  add_field(name_sym, required: false, type_info: type_info, spec: spec)
end

.required(name_sym, type_info, spec = {}) ⇒ 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.

Parameters:

  • name_sym (Symbol)
  • type_info (Hash{Symbol=>Object}, Proc, FinchAPI::Type::Converter, Class)
  • spec (Hash{Symbol=>Object}) (defaults to: {}) —

    .

    @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const

    @option spec [Proc] :enum

    @option spec [Proc] :union

    @option spec [Boolean] :“nil?”



117
118
119
 
# File 'lib/finch-api/type/base_model.rb', line 117

def required(name_sym, type_info, spec = {})
  add_field(name_sym, required: true, type_info: type_info, spec: spec)
end

Instance Method Details

#==(other) ⇒ Boolean

Parameters:

  • other (Object)

Returns:

  • (Boolean) 


174
 
# File 'lib/finch-api/type/base_model.rb', line 174

def ==(other) = self.class == other.class && @data == other.to_h

#[](key) ⇒ Object?

Returns the raw value associated with the given key, if found. Otherwise, nil is

returned.

It is valid to lookup keys that are not in the API spec, for example to access
undocumented features. This method does not parse response data into
higher-level types. Lookup by anything other than a Symbol is an ArgumentError.

Parameters:

  • key (Symbol)

Returns:

  • (Object, nil) 


295
296
297
298
299
300
301
 
# File 'lib/finch-api/type/base_model.rb', line 295

def [](key)
  unless key.instance_of?(Symbol)
    raise ArgumentError.new("Expected symbol key for lookup, got #{key.inspect}")
  end

  @data[key]
end

#deconstruct_keys(keys) ⇒ Hash{Symbol=>Object}

Parameters:

  • keys (Array<Symbol>, nil)

Returns:

  • (Hash{Symbol=>Object}) 


320
321
322
323
324
325
326
327
328
329
330
 
# File 'lib/finch-api/type/base_model.rb', line 320

def deconstruct_keys(keys)
  (keys || self.class.known_fields.keys)
    .filter_map do |k|
      unless self.class.known_fields.key?(k)
        next
      end

      [k, public_send(k)]
    end
    .to_h
end

#inspect ⇒ String

Returns:

  • (String) 


345
346
347
348
349
350
351
352
 
# File 'lib/finch-api/type/base_model.rb', line 345

def inspect
  rows = self.class.known_fields.keys.map do
    "#{_1}=#{@data.key?(_1) ? public_send(_1) : ''}"
  rescue FinchAPI::ConversionError
    "#{_1}=#{@data.fetch(_1)}"
  end
  "#<#{self.class.name}:0x#{object_id.to_s(16)} #{rows.join(' ')}>"
end

#to_h ⇒ Hash{Symbol=>Object} Also known as: to_hash

Returns a Hash of the data underlying this object. O(1)

Keys are Symbols and values are the raw values from the response. The return
value indicates which values were ever set on the object. i.e. there will be a
key in this hash if they ever were, even if the set value was nil.

This method is not recursive. The returned value is shared by the object, so it
should not be mutated.

Returns:

  • (Hash{Symbol=>Object}) 


313
 
# File 'lib/finch-api/type/base_model.rb', line 313

def to_h = @data