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

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

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.

Methods included from Converter

coerce, dump, 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 1155

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)

988	# File 'lib/finch-api/base_model.rb', line 988 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:

(FinchAPI::BaseModel, Object)

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

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::Converter.coerce(target, item, state: state)
        case target
        in FinchAPI::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:

value (FinchAPI::BaseModel, Object)

Returns:

(Hash{Object=>Object}, Object)

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

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

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

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



852
853
854

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

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



956
957
958

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

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



937
938
939

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

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)

994	# File 'lib/finch-api/base_model.rb', line 994 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)

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

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 1140

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)

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

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

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

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

.==(other) ⇒ Boolean

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

.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

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

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

.==(other) ⇒ `Boolean`

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

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

#==(other) ⇒ `Boolean`

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

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

#inspect ⇒ `String`

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