Class: Rigor::Type::HashShape

Inherits:
Object
  • Object
show all
Includes:
AcceptanceRouter, PlainLattice, ValueSemantics
Defined in:
lib/rigor/type/hash_shape.rb

Overview

A hash shape with statically known keys. Inhabitants are Ruby ‘Hash` instances whose known entries inhabit the corresponding value types. RBS records correspond to the exact closed subset; Rigor extends that carrier with optional keys, read-only entry views, and an open/closed extra-key policy.

Keys are restricted to Symbol and String values. Exact closed symbol-keyed shapes erase to the RBS record syntax ‘{ a: Integer, ?b: String }`; all other shapes degrade to `Hash[K, V]` or raw `Hash` when no useful bounds are available.

Equality and hashing are structural over the (key -> Rigor::Type) pair set and policy fields. Hash insertion order is preserved by the underlying storage but does NOT affect equality (matching Ruby’s ‘Hash#==`).

See docs/type-specification/rbs-compatible-types.md (records) and docs/type-specification/rigor-extensions.md (hash shape).

Constant Summary collapse

ALLOWED_KEY_CLASSES = 
[Symbol, String].freeze
EXTRA_KEY_POLICIES = 
%i[open closed].freeze
POLICY_KEYWORDS = 
%i[required_keys optional_keys read_only_keys extra_keys].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from ValueSemantics

included

Methods included from AcceptanceRouter

#accepts

Methods included from PlainLattice

#bot, #dynamic, #top

Constructor Details

#initialize(pairs = nil, **keywords) ⇒ HashShape

Returns a new instance of HashShape.

Parameters:

  • pairs (Hash{Symbol|String => Rigor::Type}) (defaults to: nil) —

    ordered map of keys to declared types. Keys MUST be Symbol or String; values MUST be Rigor::Type instances. The hash is duped and frozen at construction; callers MUST NOT mutate the input afterwards (mutation does not affect the carrier, but the carrier is a value object).

  • required_keys (Array<Symbol|String>, nil) —

    keys that MUST be present. When omitted, every non-optional key is required. When supplied without optional_keys, every remaining known key is treated as optional.

  • optional_keys (Array<Symbol|String>, nil) —

    keys that MAY be absent. Optional absence is not a stored nil.

  • read_only_keys (Array<Symbol|String>) —

    entries that cannot be written through this shape view.

  • extra_keys (Symbol) —

    :closed rejects keys outside pairs; :open permits them.



51
52
53
54
55
56
57
58
 
# File 'lib/rigor/type/hash_shape.rb', line 51

def initialize(pairs = nil, **keywords)
  pairs, policy = split_constructor_args(pairs, keywords)
  validate_pairs!(pairs)

  @pairs = pairs.dup.freeze
  apply_policy!(policy)
  freeze
end

Instance Attribute Details

#extra_keys ⇒ Object (readonly)

Returns the value of attribute extra_keys.



33
34
35
 
# File 'lib/rigor/type/hash_shape.rb', line 33

def extra_keys
  @extra_keys
end

#optional_keys ⇒ Object (readonly)

Returns the value of attribute optional_keys.



33
34
35
 
# File 'lib/rigor/type/hash_shape.rb', line 33

def optional_keys
  @optional_keys
end

#pairs ⇒ Object (readonly)

Returns the value of attribute pairs.



33
34
35
 
# File 'lib/rigor/type/hash_shape.rb', line 33

def pairs
  @pairs
end

#read_only_keys ⇒ Object (readonly)

Returns the value of attribute read_only_keys.



33
34
35
 
# File 'lib/rigor/type/hash_shape.rb', line 33

def read_only_keys
  @read_only_keys
end

#required_keys ⇒ Object (readonly)

Returns the value of attribute required_keys.



33
34
35
 
# File 'lib/rigor/type/hash_shape.rb', line 33

def required_keys
  @required_keys
end

Instance Method Details

#closed? ⇒ Boolean

Returns:

  • (Boolean) 


84
85
86
 
# File 'lib/rigor/type/hash_shape.rb', line 84

def closed?
  extra_keys == :closed
end

#describe(verbosity = :short) ⇒ Object 



60
61
62
63
64
65
66
 
# File 'lib/rigor/type/hash_shape.rb', line 60

def describe(verbosity = :short)
  return "{}" if pairs.empty?

  rendered = pairs.map { |k, v| render_entry(k, v, verbosity) }
  rendered << "..." if open?
  "{ #{rendered.join(', ')} }"
end

#erase_to_rbs ⇒ Object

Erases to the RBS record form ‘{ a: Integer, ?b: String }` for exact closed symbol-keyed shapes. Open shapes and string-keyed closed shapes degrade to a generic Hash bound.



71
72
73
74
75
76
77
78
 
# File 'lib/rigor/type/hash_shape.rb', line 71

def erase_to_rbs
  return "{}" if pairs.empty? && closed?
  return hash_erasure unless closed?
  return hash_erasure if pairs.each_key.any? { |k| !k.is_a?(Symbol) }

  rendered = pairs.map { |k, v| "#{record_key(k)}: #{v.erase_to_rbs}" }
  "{ #{rendered.join(', ')} }"
end

#inspect ⇒ Object 



108
109
110
 
# File 'lib/rigor/type/hash_shape.rb', line 108

def inspect
  "#<Rigor::Type::HashShape #{describe(:short)}>"
end

#open? ⇒ Boolean

Returns:

  • (Boolean) 


80
81
82
 
# File 'lib/rigor/type/hash_shape.rb', line 80

def open?
  extra_keys == :open
end

#optional_key?(key) ⇒ Boolean

Returns:

  • (Boolean) 


92
93
94
 
# File 'lib/rigor/type/hash_shape.rb', line 92

def optional_key?(key)
  optional_keys.include?(key)
end

#read_only_key?(key) ⇒ Boolean

Returns:

  • (Boolean) 


96
97
98
 
# File 'lib/rigor/type/hash_shape.rb', line 96

def read_only_key?(key)
  read_only_keys.include?(key)
end

#required_key?(key) ⇒ Boolean

Returns:

  • (Boolean) 


88
89
90
 
# File 'lib/rigor/type/hash_shape.rb', line 88

def required_key?(key)
  required_keys.include?(key)
end