core.json

JsonProperty : struct {
    key : string
    value : JsonValue
}

JsonParser : struct {
    src : string
    pos : i64 = 0
    allocator : ^Allocator = null
}

parse : func(source : string) -> [JsonValue, JsonStatus]

Parses one complete JSON document from a string.

Parameters:
  source : string - JSON text to parse. The source is borrowed and remains
                    owned by the caller.

Returns:
  [JsonValue, JsonStatus] - parsed value and status. On success returns the
                            value with JsonStatus.Ok. On failure returns an
                            empty JsonValue and the status describing the
                            parse or allocation error.

Notes:
  - Strings, arrays, and objects in the returned tree are allocated with
    the current context allocator.
  - The caller owns a successful result and must call deinit with the same
    allocator.
  - Non-whitespace content after the root value returns
    JsonStatus.TrailingCharacters.

deinit : func(value : ^JsonValue)

Recursively releases allocator-owned storage inside a JsonValue tree using
the context allocator.

Parameters:
  value : ^JsonValue - root value to clean up. May be null.

Returns:
  void

Notes:
  - context.allocator must match the allocator used to construct the tree.
  - This releases nested strings, arrays, objects, property keys, and child
    values, then resets the root to JsonTypeKind.Null.
  - This does not free the JsonValue object pointed to by `value`.
  - A null value or context allocator is treated as a no-op.

deinit : func(value : ^JsonValue, allocator : ^Allocator)

Recursively releases allocator-owned storage inside a JsonValue tree.

Parameters:
  value     : ^JsonValue - root value to clean up. May be null.
  allocator : ^Allocator - allocator that owns the tree's strings and
                           container storage.

Returns:
  void

Notes:
  - The allocator must match the allocator used to construct the tree.
  - This releases nested strings, arrays, objects, property keys, and child
    values, then resets the root to JsonTypeKind.Null.
  - This does not free the JsonValue object pointed to by `value`.
  - A null value or allocator is treated as a no-op.

find : func(value : ^JsonValue, name : string) -> ^JsonProperty

Finds an object property using a dot-separated path such as `a.b.c`.

Parameters:
  value : ^JsonValue - root value to search. Each traversed value must be a
                       JSON object.
  name  : string     - exact, case-sensitive property path.

Returns:
  ^JsonProperty - pointer to the matching property, or null when the input
                  is invalid, a path segment is absent, or traversal reaches
                  a value that is not an object.

Notes:
  - The returned pointer aliases the JsonValue tree; no allocation or copy
    is performed.
  - The pointer becomes invalid after deinit or after the containing
    object's property list reallocates.

save_json : func(value : ^JsonValue, path : string) -> JsonStatus

Serializes a JsonValue tree and writes it to a file.

Parameters:
  value : ^JsonValue - root value to serialize. The value is borrowed.
  path  : string     - destination file path.

Returns:
  JsonStatus - JsonStatus.Ok after the complete document is written and
               flushed. Returns JsonStatus.InvalidValue,
               JsonStatus.InvalidAllocator, JsonStatus.AllocationFailed,
               JsonStatus.SerializationFailed, or JsonStatus.IoError when
               the corresponding operation fails.

Notes:
  - The destination file is created or overwritten.
  - Temporary serialization storage uses the current context allocator.
  - The input tree is not consumed or modified.

new_value : func(kind : JsonTypeKind) -> ^JsonValue

Allocates storage for one JsonValue and sets its active kind.

Parameters:
  kind : JsonTypeKind - kind assigned to the new value.

Returns:
  ^JsonValue - allocated value, or null when allocation fails.

Notes:
  - Storage is allocated with the current context allocator.
  - The selected union payload must be initialized by the caller before it
    is read or passed to deinit.
  - deinit releases nested storage but not this outer allocation. The caller
    must free or delete the returned pointer separately with the same
    allocator.