Flyology JSON API reference

Description

Parses arbitrary input chunks into provisional events with caller-owned storage.

Abort_Document

procedure Abort_Document (Self : in out Parser)

End a ready or active operation without document acceptance. Failure-pending state becomes Failed and retains its primary diagnostic. Other terminal states are unchanged, so repeated cleanup is safe.

Parameters

Self: Parser operation to abort or leave terminal.

Applied_Profile

function Applied_Profile (Self : Parser) return Profiles.Parser_Profile

Read the exact profile frozen before byte zero.

Parameters

Self: Parser with an applied profile.

Return value

Copy of the complete applied parser profile.

Boolean_Data

function Boolean_Data (Item : Event) return Boolean

Read the value of a Boolean literal event.

Parameters

Item: Event whose kind is Boolean_Value.

Return value

True for true and False for false.

Byte_Offset

subtype Byte_Offset is Errors.Byte_Offset;

Zero-based absolute byte coordinate used by source ranges and diagnostics.

Chunk_Range

type Chunk_Range is record
   First_Count  : Ada.Streams.Stream_Element_Count;
   Octet_Length : Ada.Streams.Stream_Element_Count;
end record;

Count-based range relative to the exact input array for one parser call.

Record fields

First_Count: Number of components from Input'First to the first octet.
Octet_Length: Number of input components in the range.

Decoded_Fragment_Kind

type Decoded_Fragment_Kind is (No_Decoded_Fragment, Decoded_Is_Raw_Range, Decoded_Inline_Scalar);

Representation of decoded data carried by a name or string fragment.

Enumeration literals

No_Decoded_Fragment: The event carries no eligible decoded payload.
Decoded_Is_Raw_Range: Decoded octets are the exact raw range in this input call.
Decoded_Inline_Scalar: The event carries one decoded UTF-8 scalar inline.

Decoded_Kind

function Decoded_Kind (Item : Event) return Decoded_Fragment_Kind

Read the decoded payload representation of a name or string fragment.

Parameters

Item: Event to inspect.

Return value

Representation; other event kinds return No_Decoded_Fragment.

Decoded_Scalar

function Decoded_Scalar (Item : Event) return Inline_Scalar

Read one decoded UTF-8 scalar carried inline by the event.

Parameters

Item: Fragment whose decoded kind is Decoded_Inline_Scalar.

Return value

Scalar octets and eligible prefix length.

Decoded_Source

function Decoded_Source (Item : Event) return Source_Range

Read the absolute source range that produced the decoded fragment.

Parameters

Item: Name or string fragment with an eligible decoded payload.

Return value

Complete source range for the decoded raw range or inline scalar.

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: Ready, active, or failure-pending parser.
Input: Current arbitrary-bound input chunk or empty suffix call.
End_Of_Input: True when no later input octet exists for this operation.
Events: Caller storage for a provisional event prefix.
Result: Definite stop reason with count-based consumption and production.

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: Reason parsing stopped in this call.
Input_Origin: Absolute parser byte position before this call.
Consumed: Number of input components consumed beginning at Input'First.
Produced: Number of eligible events beginning at Events'First.
Diagnostic: Failure detail; eligible only for Drain_Failed or Drain_Rejected.

Drain_Stop

type Drain_Stop is (Output_Full, Drain_Need_Input, Drain_Document_Complete, Drain_Failed, Drain_Rejected);

Reason that one batched Drain operation stopped.

Enumeration literals

Output_Full: The event array is full; a null array reports this without effects.
Drain_Need_Input: All supplied input was consumed and another chunk is required.
Drain_Document_Complete: The complete document passed the acceptance gate.
Drain_Failed: Parsing ended with an eligible terminal diagnostic.
Drain_Rejected: The call violated lifecycle or final-input rules.

Duplicate_Mode

Duplicate_Mode : Profiles.Duplicate_Policy;

Compile-time decoded member-name policy. The operation profile must select the same policy before byte zero.

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;

Caller-owned, arbitrary-bound storage filled by one Drain call.

Event_Kind

type Event_Kind is
  (Document_Begin,
   Document_End,
   Object_Begin,
   Object_End,
   Array_Begin,
   Array_End,
   Name_Begin,
   Name_Fragment,
   …,
   Boolean_Value);

Closed grammar vocabulary emitted by Step and Drain.

Enumeration literals

Document_Begin: Starts one provisional document event stream.
Document_End: Ends the balanced root value; acceptance is a separate outcome.
Object_Begin: Starts an object whose member count is not known in advance.
Object_End: Ends the current object.
Array_Begin: Starts an array whose element count is not known in advance.
Array_End: Ends the current array.
Name_Begin: Starts one decoded object member name.
Name_Fragment: Carries decoded UTF-8 or a provisional raw-only source piece.
Name_End: Ends the current member name.
String_Begin: Starts one decoded JSON string value.
String_Fragment: Carries decoded UTF-8 or a provisional raw-only source piece.
String_End: Ends the current string value.
Number_Begin: Starts one exact numeric lexeme.
Number_Fragment: Carries exact source octets from the numeric lexeme.
Number_End: Ends the validated numeric lexeme.
Null_Value: Represents one complete null literal.
Boolean_Value: Represents one complete true or false literal.

Has_Applied_Profile

function Has_Applied_Profile (Self : Parser) return Boolean

Test whether initialization or reset froze a validated profile.

Parameters

Self: Parser to inspect.

Return value

True when Applied_Profile is eligible.

Has_Raw_Slice

function Has_Raw_Slice (Item : Event) return Boolean

Test whether source can be borrowed from the producing input call.

Parameters

Item: Event returned by the parser.

Return value

True only when complete source is inside that call's input window.

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: Uninitialized parser that will own the new operation.
Profile: Complete explicit profile to validate, match, and freeze.
Diagnostic: Cleared on success or set to the nonraising rejection reason.

Inline_Scalar

type Inline_Scalar is record
   Length : Positive range 1 .. Scalar_Octets'Length;
   Octets : Scalar_Octets;
end record;

One complete UTF-8 scalar copied into the event when source cannot be borrowed directly.

Record fields

Length: Eligible octet count in the prefix of Octets.
Octets: Scalar storage; only components 1 through Length are eligible.

Kind

function Kind (Item : Event) return Event_Kind

Read the grammar kind of an event.

Parameters

Item: Event returned by Step or in the produced Drain prefix.

Return value

Grammar kind that controls the event's eligible payload accessors.

Parser

type Parser
  (Maximum_Depth       : Natural;
   Name_Octet_Capacity : Natural;
   Name_Capacity       : Natural)
is
  limited private;

Bounded parser state for one document operation.

Record fields

Maximum_Depth: Maximum simultaneously open object and array containers.
Name_Octet_Capacity: Decoded-name octets retained for strict duplicate detection.
Name_Capacity: Maximum crit-bit leaves and, independently, maximum internal nodes.

Parser_State

type Parser_State is (Uninitialized, Ready, Active, Failure_Pending, Completed, Failed, Aborted);

Lifecycle state of one parser operation.

Enumeration literals

Uninitialized: No profile has been validated or applied.
Ready: A validated profile is frozen and no input has been consumed.
Active: Parsing has begun and events remain provisional.
Failure_Pending: A provisional event preceded a retained failure report.
Completed: One complete document passed the acceptance gate.
Failed: Parsing ended with a retained terminal diagnostic.
Aborted: The caller ended the operation without document acceptance.

Reset

procedure Reset
  (Self : in out Parser; Profile : Profiles.Parser_Profile; Diagnostic : out Errors.Diagnostic)

Start a fresh operation after completion, failure, or abort. Storage capacities remain fixed by the parser discriminants.

Parameters

Self: Terminal parser to prepare for reuse.
Profile: Complete explicit profile to validate, match, and freeze.
Diagnostic: Cleared on success or set to the nonraising rejection reason.

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: Event whose raw source is being resolved.
Window_Origin: Absolute zero-based origin of the producing input array.
Window_Length: Number of components in the producing input array.
Slice: Resolved count-based range, or two zero counts on failure.
Status: Outcome that controls whether Slice identifies source octets.

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);

Outcome of mapping event source into one caller-described input window.

Enumeration literals

Slice_Resolved: Slice identifies the complete raw range in the window.
No_Raw_Slice: The event has no borrowable complete raw range.
Range_Outside_Window: Event coordinates are outside the supplied window.

Source

function Source (Item : Event) return Source_Range

Read the event's complete absolute lexical provenance.

Parameters

Item: Event returned by the parser.

Return value

Absolute source range; it can span more than one input call.

Source_Range

type Source_Range is record
   First        : Byte_Offset;
   Octet_Length : Byte_Offset;
end record;

Absolute lexical provenance in the complete parser input stream.

Record fields

First: Zero-based byte offset of the first source octet.
Octet_Length: Number of source octets in the range.

State

function State (Self : Parser) return Parser_State

Report the parser lifecycle state.

Parameters

Self: Parser to inspect.

Return value

Current state without changing parser data.

Step

procedure Step
  (Self         : in out Parser;
   Input        : Ada.Streams.Stream_Element_Array;
   End_Of_Input : Boolean;
   Result       : out Step_Result)

Advance until one event, a more-input request, acceptance, or a terminal result. The parser retains lexical and structural state but never retains Input.

Parameters

Self: Ready, active, or failure-pending parser.
Input: Current arbitrary-bound input chunk or empty suffix call.
End_Of_Input: True when no later input octet exists for this operation.
Result: Definite outcome with count-based input consumption.

Step_Outcome

type Step_Outcome is (Event_Ready, Need_Input, Document_Complete, Step_Failed, Call_Rejected);

Result category for one caller-driven Step operation.

Enumeration literals

Event_Ready: One provisional event is available in Step_Result.Item.
Need_Input: All supplied input was consumed and another chunk is required.
Document_Complete: The complete document passed the acceptance gate.
Step_Failed: Parsing ended with an eligible terminal diagnostic.
Call_Rejected: The call violated lifecycle or final-input rules.

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: Result category that controls Item and Diagnostic eligibility.
Input_Origin: Absolute parser byte position before this call.
Consumed: Number of components consumed beginning at Input'First.
Item: Provisional event; eligible only for Event_Ready.
Diagnostic: Failure detail; eligible only for Step_Failed or Call_Rejected.

Terminal_Diagnostic

function Terminal_Diagnostic (Self : Parser) return Errors.Diagnostic

Read the retained terminal or pending diagnostic.

Parameters

Self: Failure-pending, failed, or aborted parser.

Return value

Retained failure, or a cleared diagnostic after a clean abort.