Class: FinchAPI::BaseModel Abstract

Inherits:

Object

Object
FinchAPI::BaseModel

show all

Extended by:: Converter

Defined in:: lib/finch-api/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
}

Direct Known Subclasses

Class Method Summary collapse

.coerce(value) ⇒ FinchAPI::BaseModel, Object private
.defaults ⇒ Hash{Symbol=>Proc} private
.dump(value) ⇒ Hash{Object=>Object}, Object private
.fields ⇒ Hash{Symbol=>Hash{Symbol=>Object}} private
.known_fields ⇒ Hash{Symbol=>Hash{Symbol=>Object}} private

Assumes superclass fields are totally defined before fields are accessed / defined on subclasses.
.optional(name_sym, type_info, spec = {}) ⇒ Object private
.required(name_sym, type_info, spec = {}) ⇒ Object private
.reverse_map ⇒ Hash{Symbol=>Symbol} private
.try_strict_coerce(value) ⇒ Array(true, Object, nil), Array(false, Boolean, Integer) private

Instance Method Summary collapse

#==(other) ⇒ Boolean
#[](key) ⇒ Object^?

Returns the raw value associated with the given key, if found.
#deconstruct_keys(keys) ⇒ Hash{Symbol=>Object}
#initialize(data = {}) ⇒ BaseModel constructor

Create a new instance of a model.
#inspect ⇒ String
#to_h ⇒ Hash{Symbol=>Object} (also: #to_hash)

Returns a Hash of the data underlying this object.
#to_s ⇒ String

Methods included from Converter

coerce, dump, try_strict_coerce, type_info

Constructor Details

#initialize(data = {}) ⇒ `BaseModel`

Create a new instance of a model.

Parameters:

data (Hash{Symbol=>Object}, FinchAPI::BaseModel) (defaults to: {})

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

def initialize(data = {})
  case FinchAPI::Util.coerce_hash(data)
  in Hash => coerced
    @data = coerced.to_h do |key, value|
      name = key.to_sym
      mapped = self.class.reverse_map.fetch(name, name)
      type = self.class.fields[mapped]&.fetch(:type)
      stored =
        case [type, value]
        in [Module, Hash] if type <= FinchAPI::BaseModel
          type.new(value)
        in [FinchAPI::ArrayOf, Array] | [FinchAPI::HashOf, Hash]
          type.coerce(value)
        else
          value
        end
      [name, stored]
    end
  else
    raise ArgumentError.new("Expected a #{Hash} or #{FinchAPI::BaseModel}, got #{data.inspect}")
  end
end

Class Method Details

.coerce(value) ⇒ `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)

Returns:

(FinchAPI::BaseModel, Object)

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

def coerce(value)
  case FinchAPI::Util.coerce_hash(value)
  in Hash => coerced
    new(coerced)
  else
    value
  end
end

.defaults ⇒ `Hash{Symbol=>Proc}`

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=>Proc})

908	# File 'lib/finch-api/base_model.rb', line 908 def defaults = (@defaults \|\|= {})

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

value (FinchAPI::BaseModel, Object)

Returns:

(Hash{Object=>Object}, Object)

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

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

  values = coerced.filter_map do |key, val|
    name = key.to_sym
    case (field = known_fields[name])
    in nil
      [name, val]
    else
      mode, type_fn, api_name = field.fetch_values(:mode, :type_fn, :key)
      case mode
      in :coerce
        next
      else
        target = type_fn.call
        [api_name, FinchAPI::Converter.dump(target, val)]
      end
    end
  end.to_h

  defaults.each do |key, val|
    next if values.key?(key)

    values[key] = val
  end

  values
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}})

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

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}})



885
886
887

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

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::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?”



999
1000
1001

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

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::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?”



980
981
982

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

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

.reverse_map ⇒ `Hash{Symbol=>Symbol}`

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=>Symbol})



892
893
894

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

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

.try_strict_coerce(value) ⇒ `Array(true, Object, nil)`, `Array(false, Boolean, Integer)`

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 (Object)

Returns:

(Array(true, Object, nil), Array(false, Boolean, Integer))

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

def try_strict_coerce(value)
  case value
  in Hash | FinchAPI::BaseModel
    value = value.to_h
  else
    return [false, false, 0]
  end

  keys = value.keys.to_set
  great_success = true
  tally = 0
  acc = {}

  known_fields.each_value do |field|
    mode, required, type_fn, api_name = field.fetch_values(:mode, :required, :type_fn, :key)
    keys.delete(api_name)

    case [required && mode != :dump, value.key?(api_name)]
    in [_, true]
      target = type_fn.call
      item = value.fetch(api_name)
      case FinchAPI::Converter.try_strict_coerce(target, item)
      in [true, coerced, score]
        tally += score
        acc[api_name] = coerced
      in [false, true, score]
        great_success = false
        tally += score
        acc[api_name] = item
      in [false, false, _]
        great_success &&= item.nil?
      end
    in [true, false]
      great_success = false
    in [false, false]
      nil
    end
  end

  keys.each do |key|
    acc[key] = value.fetch(key)
  end

  great_success ? [true, new(acc), tally] : [false, true, tally]
end

Instance Method Details

#==(other) ⇒ `Boolean`

Parameters:

other (Object)

Returns:

(Boolean)

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

def ==(other)
  case other
  in FinchAPI::BaseModel
    self.class.fields == other.class.fields && @data == other.to_h
  else
    false
  end
end

#[](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)

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

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})

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

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

    [k, method(k).call]
  end
  .to_h
end

#inspect ⇒ `String`

Returns:

(String)

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

def inspect
  "#<#{self.class.name}:0x#{object_id.to_s(16)} #{deconstruct_keys(nil).map do |k, v|
    "#{k}=#{v.inspect}"
  end.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})

1172	# File 'lib/finch-api/base_model.rb', line 1172 def to_h = @data

#to_s ⇒ `String`

Returns:

(String)

1217	# File 'lib/finch-api/base_model.rb', line 1217 def to_s = @data.to_s

Class: FinchAPI::BaseModel Abstract

Overview

Examples:

Direct Known Subclasses

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Converter

Constructor Details

#initialize(data = {}) ⇒ BaseModel

Class Method Details

.coerce(value) ⇒ FinchAPI::BaseModel, Object

.defaults ⇒ Hash{Symbol=>Proc}

.dump(value) ⇒ Hash{Object=>Object}, Object

.fields ⇒ Hash{Symbol=>Hash{Symbol=>Object}}

.known_fields ⇒ Hash{Symbol=>Hash{Symbol=>Object}}

.optional(name_sym, type_info, spec = {}) ⇒ Object

.required(name_sym, type_info, spec = {}) ⇒ Object

.reverse_map ⇒ Hash{Symbol=>Symbol}

.try_strict_coerce(value) ⇒ Array(true, Object, nil), Array(false, Boolean, Integer)

Instance Method Details

#==(other) ⇒ Boolean

#[](key) ⇒ Object?

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

#inspect ⇒ String

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

#to_s ⇒ String

#initialize(data = {}) ⇒ `BaseModel`

.coerce(value) ⇒ `FinchAPI::BaseModel`, `Object`

.defaults ⇒ `Hash{Symbol=>Proc}`

.dump(value) ⇒ `Hash{Object=>Object}`, `Object`

.fields ⇒ `Hash{Symbol=>Hash{Symbol=>Object}}`

.known_fields ⇒ `Hash{Symbol=>Hash{Symbol=>Object}}`

.optional(name_sym, type_info, spec = {}) ⇒ `Object`

.required(name_sym, type_info, spec = {}) ⇒ `Object`

.reverse_map ⇒ `Hash{Symbol=>Symbol}`

.try_strict_coerce(value) ⇒ `Array(true, Object, nil)`, `Array(false, Boolean, Integer)`

#==(other) ⇒ `Boolean`

#[](key) ⇒ `Object`^?

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

#inspect ⇒ `String`

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

#to_s ⇒ `String`