Literal Ruby Gem

You can compose pipelines for property blocks using >> or <<.

• Literal::Coercion { |v| }: Normalizes input. Runs only at input boundaries (initializer, writers, draft assignment). It runs instance_exec'd against the object under construction.
• Literal::Seal { |v| }: Fixes the final representation (e.g., freezing). Runs on every constructing store but not on marshal_load. Must be idempotent and type-preserving.

Composition Rules:

• coercion >> seal creates a Seal that carries the coercion.
• seal >> coercion will raise an error (coercion cannot run after sealing).

Built-in Coercions/Seals

• Immutable: Seals by performing a shallow dup and freeze.
• DeepImmutable: Seals by performing a Ractor.make_shareable copy.
• NilIfEmpty: Coerces empty strings, arrays, or hashes ("", [], {}) to nil.

Example of composing a generic type with a seal:

# An array of strings that is also immutable
_Array(String) >> Immutable

Literal::Draft(P) provides a mutable builder that mirrors a Properties class. In a draft, every property is optional (defaulting to Literal::Undefined) and types are relaxed to _DraftState(T).

Finalizing a Draft

Use .finalize to convert a draft into a real instance. You can provide overrides and a block for final touches.

# Using a draft to build an instance
instance = P.build(a: "val") do |draft| 
  # last touches
end

# Or via explicit finalize
draft = P.draft
draft.a = "something"
instance = draft.finalize(b: "override")
```n
### Key Behaviors
- **`P.from_props(hash)`**: The inverse of `to_h`. It creates an instance from final values. It skips `initialize`/`after_initialize` and uses defaults for missing props. It does **not** run coercions.
- **`P.from(other)`**: Rehydrates an instance from another object (e.g., a slice) by calling `from_props(other.to_h.slice(*own_props))`.
- **Draft Types**: Draft classes are types that match any draft of a subtype.

When dealing with untrusted input (like API arguments or JSON) where you want to collect all errors (type errors, unknown keys, and custom checks) without immediately raising an exception, use Literal::Draft.

Usage Patterns:

1. Validating known-good values: If you already have values that pass type checks but want to verify custom invariants, use Literal::Draft(Shape).new(...). This will raise if types are wrong but hold check failures in abeyance.
2. Validating untrusted Hashes: If you have a raw Hash (with string or symbol keys), use Literal::Draft(Shape).check(hash). This is the "soft path" that collects everything: type errors, unknown keys, and custom check failures.

Results:

Both methods return a Literal::Result(Shape, Literal::Checks::Errors). You can then check result.sound? to see if the input was valid.

Note: A draft never mutates the input and never constructs an invalid object; it only builds the object once all checks pass.

# Validating a raw hash without raising
result = Literal::Draft(Span).check({"min" => 1, "max" => 0})

if result.sound?
  span = result.value
else
  puts result.errors
end

You can define structured objects by extending Literal::Properties. This generates an initialize method with a kind-aware signature, to_h, and per-property methods. The storage pipeline follows: coerce → seal → check → assign.

Property Syntax

• prop :name, Type : Required keyword argument.
• prop :name, Type, :positional : Positional argument.
• prop? :name, Type : Optional property (typed as _Union(Type, Literal::Undefined)).
• prop :name, Type, default: :val : Default value (frozen object or Proc executed via instance_exec).
• prop :name, Type, &block : Block used for coercion and pre-checking.

Options

• reader:, writer:, predicate:: Accept :public, :protected, or :private (defaults to :public).
• predicate: Generates a name? method (returns false if the property is Undefined).
• description:: String used for JSON Schema generation.

Inheritance

Redefined properties in subclasses must maintain the same kind, have $\ge$ visibility, and can only narrow the type (LSP). No new properties can be added after a subclass has inherited from a parent.

Slicing

Use .slice to create an anonymous class containing a subset of properties, and .from(instance) to project an existing instance into that slice.

class P < Literal::Object
  prop :a, String
  prop :b, _Integer(0..), reader: :public
  prop :c, Integer, :positional
  prop :d, Symbol, default: :x
  prop? :e, String
  prop :f, _Array(String), &Literal::Array(String)
end

# Slicing example
PName = P.slice(:a)
new_slice = PName.from(p_instance)

class P < Literal::Object
  prop :a, String                  # required keyword
  prop :b, _Integer(0..), reader: :public
  prop :c, Integer, :positional    # kinds: :positional :* :keyword(default) :** :&
  prop :d, Symbol, default: :x     # default: frozen object or Proc (instance_exec'd)
  prop? :e, String                 # optional → _Union(T, Literal::Undefined)
  prop :f, _Array(String), &Literal::Array(String)  # block = coercion, pre-check
end

# Slices
PName = P.slice(:a)   # anonymous class "P.slice(:a)"
PName.from(p)         # copies matching prop values

A Literal::Array is a typed array that enforces its element type on every mutation. Unlike a standard Ruby Array, the validity of its elements is guaranteed for the lifetime of the object.

Key characteristics:

• Type Enforcement: The element type is fixed at construction. It cannot be changed in place. Methods like narrow and widen return new instances rather than modifying the existing one.
• Distinct from Ruby Array: It is not a subtype of Array. While you can pass plain arrays to Literal::Array via new or coerce, they are type-checked upon entry. To get a plain array back, use to_a or to_ary, which return detached copies.
• Safe Lookups: Methods that return an element (like []) return Literal::Undefined instead of nil when an index is out of bounds or an element is not found. nil is only returned if the element type explicitly permits it.
• Immutability vs Mutation: While the type is fixed, the array itself can be mutated (e.g., via <<, push, pop) as long as the new elements match the established type.

Literal::Property is a core abstraction used by the Literal gem to describe individual data fields (properties) within a class. It encapsulates metadata about a field, including its name, type, kind (e.g., positional, keyword, splat), visibility, and whether it is optional or required.

Properties are used to generate type-safe Ruby code, including:

• Readers: Accessor methods.
• Writers: Mutator methods with type checking and coercion.
• Predicates: Boolean methods (e.g., name?) that handle Literal::Undefined correctly.
• Initializers: Logic to handle parameter assignment, defaults, coercion, and sealing during object instantiation.

Key concepts:

• Kinds: Properties can be :positional, :keyword, :* (splat), :** (double splat), or :& (block).
• Optionality: A property is optional? if it has a default value, a nil type, or is undefinable? (part of a Union type containing Literal::Undefined).
• Coercion & Sealing: Properties can define a coercion proc to transform values or a seal proc to validate them during assignment.