class

Chem::Metadata

Inherits Iterable / Enumerable / Reference / Object

A Metadata is a hash-like container that holds metadata about an object. It maps a property name (as string) to a primitive value (integer, float, string, or bool) or an array of them. Most of the functionality mirrors that of a Hash, where some specific methods like Hash#dig or default values are excluded.

Values are stored as Any instances, which a thin wrapper for a dynamically-typed primitive value and it offers convenient #as_* cast methods.

Examples

metadata = Chem::Metadata.new

# four data types are supported
metadata["str"] = "Foo"
metadata["int"] = 123
metadata["float"] = 1.234
metadata["bool"] = true
# metadata["x"] = /[a-z]/ # fails to compile

# (base type) arrays are also supported
metadata["array_of_int"] = [1, 2, 3]
metadata["array_of_string"] = %w(1 2 3)
metadata["nested_array"] = [[1, 2], [3]]
# metadata["mixed_array"] = [1, "2", true] # does not compile

Values are stored as Any instances. Use #as_* cast methods get the actual value.

metadata["str"]             # => Chem::Metadata::Any("Foo")
metadata["str"].as_s.upcase # => "FOO"
metadata["str"].as_i?       # => nil
metadata["str"].as_i        # raises TypeCastError
metadata["str"].as_a        # raises TypeCastError

Arrays are returned as Array(Any). Use Array#map(&.as_*) or #as_a(type) to get a typed array.

metadata["array_of_int"].as_a             # => [Chem::Metadata::Any(1), ...]
metadata["array_of_int"].as_a.map(&.as_i) # => [1, 2, 3]
metadata["array_of_int"].as_a(Int32)      # => [1, 2, 3]
metadata["nested_array"].as_2a(Int32)     # => [[1, 2], [3]]

Instance methods

[](key : String) : Any

Returns the value for the given key. Raises KeyError if not found.

Source
[]=(key : String, value : Bool) : Bool

Sets the value of key to the given value.

Source
[]=(key : String, value : Float64) : Float64

Sets the value of key to the given value.

Source
[]=(key : String, value : Int32) : Int32

Sets the value of key to the given value.

Source
[]=(key : String, value : String) : String

Sets the value of key to the given value.

Source
[]=(key : String, value : Array) : Array

Sets the value of key to the given value.

Source
[]?(key : String) : Any | Nil

Returns the value for the given key. Returns nil if not found.

Source
clear

Empties the Metadata and returns it.

Source
delete(key : String) : Any | Nil

Deletes the key-value pair and returns the value. Returns nil if key does not exist.

Source
delete(key : String, & : String -> {String, Bool | Float64 | Int32 | String}) : Any | {String, Bool | Float64 | Int32 | String} forall T

Deletes the key-value pair and returns the value. Yields key and returns the value returned by the given block if key does not exist.

Source
each

Must yield this collection's elements to the block.

Source
each

Must return an Iterator over the elements in this collection.

Source
each_key

Yields each key to the given block.

The enumeration follows the order the keys were inserted.

Source
each_key

Returns an iterator over the keys.

Source
each_value

Yields each value to the given block.

The enumeration follows the order the keys were inserted.

Source
each_value

Returns an iterator over the values.

Source
empty?

Returns true when the metadata contains no key-value pairs, else false.

Source
fetch(key : String, default : {String, Bool | Float64 | Int32 | String}) : Any | {String, Bool | Float64 | Int32 | String} forall T

Returns the value if the given key exists, else default.

Source
fetch(key : String, & : String -> {String, Bool | Float64 | Int32 | String}) : Any | {String, Bool | Float64 | Int32 | String} forall T

Returns the value if the given key exists, else the value returned by the given block invoked with key.

Source
has_key?(key : String) : Bool

Returns true if key exists, else false.

Source
has_value?(value : ValueType) : Bool

Returns true if any key is associated with value, else false.

Source
inspect(io : IO) : Nil

Appends a String representation of this object which includes its class name, its object address and the values of all instance variables.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).inspect # => #<Person:0x10fd31f20 @name="John", @age=32>
Source
key_for(value : ValueType) : String

Returns a key with the given value. Raises KeyError if no key is associated with value.

Source
key_for(value : Bool, & : Bool -> {String, Bool | Float64 | Int32 | String}) : String | {String, Bool | Float64 | Int32 | String} forall T

Returns a key with the given value. Yields value to the given block and returns the returned value if no key is associated with value.

Source
key_for(value : Float64, & : Float64 -> {String, Bool | Float64 | Int32 | String}) : String | {String, Bool | Float64 | Int32 | String} forall T

Returns a key with the given value. Yields value to the given block and returns the returned value if no key is associated with value.

Source
key_for(value : Int32, & : Int32 -> {String, Bool | Float64 | Int32 | String}) : String | {String, Bool | Float64 | Int32 | String} forall T

Returns a key with the given value. Yields value to the given block and returns the returned value if no key is associated with value.

Source
key_for(value : String, & : String -> {String, Bool | Float64 | Int32 | String}) : String | {String, Bool | Float64 | Int32 | String} forall T

Returns a key with the given value. Yields value to the given block and returns the returned value if no key is associated with value.

Source
key_for?(value : ValueType) : String | Nil

Returns a key with the given value, or nil if no key is associated with value.

Source
keys

Returns a new Array with all the keys.

Source
merge!(other : self) : self

Adds the contents of other to this metadata. Existing entries will be replaced with those in otherยจ.

Source
merge!(other : self, & : String, Any, Any -> _) : self

Adds the contents of other to this metadata. If a key exists in both hashes, the given block is called with the key, the value in self and the value in other, and the returned value will be set.

Source
reject!

Deletes the entries for which the given block is truthy.

Source
reject!(keys : Enumerable(String)) : self

Deletes the entries for the given keys.

Source
reject!(*keys : String) : self

Deletes the entries for the given keys.

Source
select!

Deletes every entry except for which the given block is falsey.

Source
select!(keys : Enumerable(String)) : self

Deletes every entry except for the given keys.

Source
select!(*keys : String) : self

Deletes every entry except for the given keys.

Source
size

Returns the number of key-value pairs.

Source
to_a

Returns an array containing key-value pairs as tuples.

Source
to_s(io : IO) : Nil

Appends a short String representation of this object which includes its class name and its object address.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).to_s # => #<Person:0x10a199f20>
Source
update(key : String, & : Any -> ValueType) : Any

Yields the value for the given key and updates it with the value returned by the given block. Raises KeyError if key does not exist.

It returns the value used as input for the given block (i.e., the old value).

Source
values

Returns an array containing the values.

Source
values_at(keys : Enumerable(String)) : Array(Any)

Returns the values for the given keys. Raises KeyError if a key does not exist.

Values are returned in the same order of the keys.

Source
values_at(*keys : String)

Returns the values for the given keys. Raises KeyError if a key does not exist.

Values are returned in the same order of the keys.

Source

Nested types