Description
Trusted, allocation-free incremental parser. Duplicate_Mode is a static selection with no default. This package contains no accounting state, callback, hook, or observational counter.
Abort_Document
procedure Abort_Document (Self : in out Parser)
Parameters
- Self
Applied_Profile
function Applied_Profile (Self : Parser) return Profiles.Parser_Profile
Parameters
- Self
Return value
Boolean_Data
function Boolean_Data (Item : Event) return Boolean
Parameters
- Item
Return value
Byte_Offset
subtype Byte_Offset is Errors.Byte_Offset;
Chunk_Range
type Chunk_Range is record
First_Count : Ada.Streams.Stream_Element_Count;
Octet_Length : Ada.Streams.Stream_Element_Count;
end record;
Record fields
- First_Count
- Octet_Length
Decoded_Fragment_Kind
type Decoded_Fragment_Kind is
(No_Decoded_Fragment, Decoded_Is_Raw_Range, Decoded_Inline_Scalar);
Enumeration literals
- No_Decoded_Fragment
- Decoded_Is_Raw_Range
- Decoded_Inline_Scalar
Decoded_Kind
function Decoded_Kind (Item : Event) return Decoded_Fragment_Kind
Parameters
- Item
Return value
Decoded_Scalar
function Decoded_Scalar (Item : Event) return Inline_Scalar
Parameters
- Item
Return value
Decoded_Source
function Decoded_Source (Item : Event) return Source_Range
Parameters
- Item
Return value
Drain
procedure Drain
(Self : in out Parser;
Input : Ada.Streams.Stream_Element_Array;
End_Of_Input : Boolean;
Events : out Event_Array;
Result : out Drain_Result)
Fill only the first Result.Produced components. Every borrowed range refers to this exact Input. A null Events array returns Output_Full, zero consumed/produced, and leaves Self unchanged, before lifecycle or finality checks. Otherwise Drain shares Step's engine and finality latch. Filling Events takes precedence over a later pending terminal result; the next call reports that result.
Parameters
- Self
- Input
- End_Of_Input
- Events
- Result
Drain_Result
type Drain_Result is record
Stop : Drain_Stop;
Input_Origin : Byte_Offset;
Consumed : Ada.Streams.Stream_Element_Count;
Produced : Ada.Streams.Stream_Element_Count;
Diagnostic : Errors.Diagnostic;
end record;
This result is definite. Diagnostic is eligible only for Drain_Failed or Drain_Rejected; other fields are eligible for every stop. Input_Origin is the operation's absolute next byte before the call, Consumed is a count from Input'First, and Produced is a count from Events'First. A nonnull Output_Full result publishes exactly Events'Length events. Every rejected call consumes and produces zero.
Record fields
- Stop
- Input_Origin
- Consumed
- Produced
- Diagnostic
Drain_Stop
type Drain_Stop is
(Output_Full, Drain_Need_Input, Drain_Document_Complete, Drain_Failed, Drain_Rejected);
Enumeration literals
- Output_Full
- Drain_Need_Input
- Drain_Document_Complete
- Drain_Failed
- Drain_Rejected
Duplicate_Mode
Duplicate_Mode : Profiles.Duplicate_Policy;
Event
type Event is private;
Event is a compact value with no public size, packing, layout, or ABI promise. A copied event retains absolute source coordinates and inline scalar data, but never retains parser input.
Event_Array
type Event_Array is array (Ada.Streams.Stream_Element_Offset range <>) of Event;
Event_Kind
type Event_Kind is
(Document_Begin,
Document_End,
Object_Begin,
Object_End,
Array_Begin,
Array_End,
Name_Begin,
Name_Fragment,
…,
Boolean_Value);
Enumeration literals
- Document_Begin
- Document_End
- Object_Begin
- Object_End
- Array_Begin
- Array_End
- Name_Begin
- Name_Fragment
- Name_End
- String_Begin
- String_Fragment
- String_End
- Number_Begin
- Number_Fragment
- Number_End
- Null_Value
- Boolean_Value
Has_Applied_Profile
function Has_Applied_Profile (Self : Parser) return Boolean
Parameters
- Self
Return value
Has_Raw_Slice
function Has_Raw_Slice (Item : Event) return Boolean
Parameters
- Item
Return value
Initialize
procedure Initialize
(Self : in out Parser; Profile : Profiles.Parser_Profile; Diagnostic : out Errors.Diagnostic)
Maximum_Depth counts simultaneously open object and array containers; a root container is depth one, nested containers add one, and a scalar root needs depth zero. A denied opener is neither consumed nor published and is reported at that opener.
The two name capacities are ignored in Preserve_Unchecked and may be zero. Preserve_Unchecked publishes every member in source order and performs no duplicate storage, comparison, or selection. In Reject_Duplicates, Name_Octet_Capacity bounds the total decoded UTF-8 octets of unique names retained by all simultaneously open objects plus the active candidate. Closing an object releases storage acquired since its opener. A duplicate candidate is reclaimed at detection. Storage denial consumes and publishes the completed scalar's final raw-only provisional source piece or pieces, publishes no decoded scalar, and enters Failure_Pending. An underfull Drain reports Name_Storage_Exhausted in that call while retaining its provisional prefix and prior consumption. If Step returned the raw-only piece or a Drain filled its output, the next admitted call reports the failure with zero consumption and publication. The active name's opening quote is blamed.
Name_Capacity independently bounds retained crit-bit leaves and internal nodes across simultaneously open objects. One unique name consumes one leaf and, unless first in that object, one node. The active candidate consumes neither until Name_End. Capacity zero denies a strict name before its opening quote is consumed or published. An exact-fit unique name succeeds. The next unique name needing an unavailable leaf or node consumes the closing quote, fails at Name_End, publishes no Name_End, and reports Duplicate_Index_Exhausted at its opening quote. Exact duplicates are detected before unique-name index reservation and therefore win over an otherwise simultaneous index denial. Detection occurs at Name_End; no Name_End event is published and the later opening quote is blamed. For decoded candidate length L, retained-node count K, and compared leaf length E, completion performs at most two K-node bit-probe descents, one comparison of the eight-octet length prefix plus max (L, E) content octets, and eight bit tests in the first differing octet. Appending the candidate performs exactly L octet stores. K is at most Name_Capacity; L and E are at most Name_Octet_Capacity. There is no scan over all prior names and no collision-only or quadratic fallback.
Profile must select the package's Duplicate_Mode. Unsupported, mismatched, or incompatible profiles fail before byte zero. Under Require_Object, a recognized array, string, number, Boolean, or null root leader is rejected before that leader is consumed or its token contents are validated. A byte that cannot lead any JSON value remains Unexpected_Token rather than a top-level-kind rejection.
Parameters
- Self
- Profile
- Diagnostic
Inline_Scalar
type Inline_Scalar is record
Length : Positive range 1 .. Scalar_Octets'Length;
Octets : Scalar_Octets;
end record;
Record fields
- Length
- Octets
Kind
function Kind (Item : Event) return Event_Kind
Parameters
- Item
Return value
Parser
type Parser
(Maximum_Depth : Natural;
Name_Octet_Capacity : Natural;
Name_Capacity : Natural)
is limited private;
Record fields
- Maximum_Depth
- Name_Octet_Capacity
- Name_Capacity
Parser_State
type Parser_State is
(Uninitialized, Ready, Active, Failure_Pending, Completed, Failed, Aborted);
Enumeration literals
- Uninitialized
- Ready
- Active
- Failure_Pending
- Completed
- Failed
- Aborted
Reset
procedure Reset
(Self : in out Parser; Profile : Profiles.Parser_Profile; Diagnostic : out Errors.Diagnostic)
Parameters
- Self
- Profile
- Diagnostic
Resolve_Raw_Range
procedure Resolve_Raw_Range
(Item : Event;
Window_Origin : Byte_Offset;
Window_Length : Ada.Streams.Stream_Element_Count;
Slice : out Chunk_Range;
Status : out Slice_Status)
Map Item's absolute raw coordinates into a caller-described input window. This validates coordinate containment only; it does not and cannot authenticate an Ada array's identity or contents. The caller supplies the exact unchanged Input actual from the producing Step/Drain call. The result is a count from that Input's First. A missing or outside range returns zero counts without raising.
Parameters
- Item
- Window_Origin
- Window_Length
- Slice
- Status
Scalar_Octets
subtype Scalar_Octets is
Ada.Streams.Stream_Element_Array
(Ada.Streams.Stream_Element_Offset range 1 .. 4);
RFC 3629 fixes four as the maximum UTF-8 scalar width. This is a constrained subtype of the common octet-array type so callers can pass a decoded prefix directly to collector, writer, or numeric APIs.
Slice_Status
type Slice_Status is (Slice_Resolved, No_Raw_Slice, Range_Outside_Window);
Enumeration literals
- Slice_Resolved
- No_Raw_Slice
- Range_Outside_Window
Source
function Source (Item : Event) return Source_Range
Parameters
- Item
Return value
Source_Range
type Source_Range is record
First : Byte_Offset;
Octet_Length : Byte_Offset;
end record;
Record fields
- First
- Octet_Length
State
function State (Self : Parser) return Parser_State
Parameters
- Self
Return value
Step
procedure Step
(Self : in out Parser;
Input : Ada.Streams.Stream_Element_Array;
End_Of_Input : Boolean;
Result : out Step_Result)
Parameters
- Self
- Input
- End_Of_Input
- Result
Step_Outcome
type Step_Outcome is
(Event_Ready, Need_Input, Document_Complete, Step_Failed, Call_Rejected);
Enumeration literals
- Event_Ready
- Need_Input
- Document_Complete
- Step_Failed
- Call_Rejected
Step_Result
type Step_Result is record
Outcome : Step_Outcome;
Input_Origin : Byte_Offset;
Consumed : Ada.Streams.Stream_Element_Count;
Item : Event;
Diagnostic : Errors.Diagnostic;
end record;
This result is definite: passing a constrained actual cannot raise when Step returns another outcome. Item is eligible only for Event_Ready; Diagnostic only for Step_Failed or Call_Rejected. Input_Origin is the operation's absolute next byte before the call and Consumed is a count from Input'First. Need_Input consumes all supplied input. Every rejected call consumes zero.
Record fields
- Outcome
- Input_Origin
- Consumed
- Item
- Diagnostic
Terminal_Diagnostic
function Terminal_Diagnostic (Self : Parser) return Errors.Diagnostic
Parameters
- Self