Flyology JSON API reference

Description

Emits ordinary compact JSON through one caller-owned destination transaction.

Abort_Document

procedure Abort_Document (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

End unpublished staging without publication. Ready enters clean Aborted without a destination call. Active or Interrupted aborts its owned transaction once. Failed and Aborted are idempotent and retain their diagnostic; Uninitialized and Completed are nonmutating clean no-ops. An earlier primary remains primary if destination abort also fails.

Parameters

Self: Writer in any lifecycle state; the state rules above control cleanup.
Diagnostic: Cleared or retained result prescribed by the current state.

Applied_Profile

function Applied_Profile (Self : Writer) return Profiles.Writer_Profile

Read the exact profile frozen before destination begin.

Parameters

Self: Writer with an applied profile.

Return value

Copy of the complete applied writer profile.

Begin_Array

procedure Begin_Array (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Emit an array opener and push one container frame.

Parameters

Self: Active writer at a position that accepts a JSON value.
Diagnostic: Cleared on success or set to grammar, depth, or destination failure.

Begin_Document

procedure Begin_Document (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Start one unpublished whole-document destination transaction.

Parameters

Self: Ready writer whose profile is already frozen.
Diagnostic: Cleared on success or set to begin or lifecycle failure.

Begin_Name

procedure Begin_Name (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Start one object member name and emit its opening quotation mark.

Parameters

Self: Active writer whose current object expects a member name.
Diagnostic: Cleared on success or set to grammar or destination failure.

Begin_Number

procedure Begin_Number (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Start one exact JSON number lexeme without emitting a number-lexeme octet.

Parameters

Self: Active writer at a position that accepts a JSON value.
Diagnostic: Cleared on success or set to a grammar failure.

Begin_Object

procedure Begin_Object (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Emit an object opener and push one container frame.

Parameters

Self: Active writer at a position that accepts a JSON value.
Diagnostic: Cleared on success or set to grammar, depth, or destination failure.

Begin_String

procedure Begin_String (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Start one JSON string value and emit its opening quotation mark.

Parameters

Self: Active writer at a position that accepts a JSON value.
Diagnostic: Cleared on success or set to grammar or destination failure.

Destination_Abort

procedure Destination_Abort (Target : in out Destination_Type; Status : out Destinations.Abort_Status)

Abort is synchronous, nonraising, finite, and nonreentrant. It ends the active unpublished transaction and never publishes, even when Status is Abort_Failed. The writer protects abort and exactly-once bookkeeping from task abort.

Parameters

Target: Destination whose unpublished transaction must end.
Status: Cleanup result; the transaction ends for either value.

Destination_Begin

procedure Destination_Begin (Target : in out Destination_Type; Status : out Destinations.Begin_Status)

Begin is synchronous, nonraising, finite, and nonreentrant. A successful return starts exactly one unpublished transaction. A failed return starts none. The writer protects this ownership boundary from task abort.

Parameters

Target: Caller-owned destination that starts staging.
Status: Whether a transaction was started and is now owned by the writer.

Destination_Commit

procedure Destination_Commit (Target : in out Destination_Type; Status : out Destinations.Commit_Status)

Commit is synchronous, nonraising, finite, and nonreentrant. Success is the only publication point. Failure publishes nothing and leaves the transaction abortable. The writer protects publication and its ownership transition from task abort.

Parameters

Target: Destination whose complete staged document may be published.
Status: Whether the whole document was published.

Destination_Type

type Destination_Type is limited private;

Caller-owned staging destination type. The destination object outlives the writer bound to it.

Destination_Write

procedure Destination_Write
  (Target  : in out Destination_Type;
   Data    : Ada.Streams.Stream_Element_Array;
   Written : out Ada.Streams.Stream_Element_Count;
   Status  : out Destinations.Write_Status)

Write is synchronous, finite, nonreentrant, retains no reference to Data, and does not access a writer alias. On normal return, Write_Succeeded accepts all Data; Write_Exhausted accepts the exact longest prefix; Write_Failed accepts none. Written is a count rather than an Ada index.

On abnormal completion, Write may have staged an in-order prefix of Data from zero through Data'Length. That prefix remains unpublished, Data is not retained, and one coherent transaction remains abortable.

Parameters

Target: Destination whose active transaction receives the span.
Data: Arbitrary-bound octet span retained only for this call.
Written: Count of accepted components beginning at Data'First.
Status: Complete acceptance, exact-prefix exhaustion, or no-prefix failure.

End_Array

procedure End_Array (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Emit an array closer after its last complete value.

Parameters

Self: Active writer whose current container is a closable array.
Diagnostic: Cleared on success or set to grammar or destination failure.

End_Name

procedure End_Name (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Finish the member name and emit the name/value separator.

Parameters

Self: Active writer with a complete UTF-8 member-name token.
Diagnostic: Cleared on success or set to grammar, UTF-8, or destination failure.

End_Number

procedure End_Number (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Finish the number only when all staged lexeme octets form strict JSON syntax.

Parameters

Self: Active writer with an open number token.
Diagnostic: Cleared on success or set to grammar or number failure.

End_Object

procedure End_Object (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Emit an object closer after every member has a complete value.

Parameters

Self: Active writer whose current container is a closable object.
Diagnostic: Cleared on success or set to grammar or destination failure.

End_String

procedure End_String (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Finish a complete decoded UTF-8 string and emit its closing quotation mark.

Parameters

Self: Active writer with an open string token.
Diagnostic: Cleared on success or set to grammar, UTF-8, or destination failure.

Finish_Document

procedure Finish_Document (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Validate the balanced document and request the only destination commit. Commit failure publishes nothing and leaves cleanup to the writer transaction.

Parameters

Self: Active writer after one complete balanced root value.
Diagnostic: Cleared after publication or set to grammar or commit failure.

Has_Applied_Profile

function Has_Applied_Profile (Self : Writer) return Boolean

Test whether initialization or reset froze a validated profile.

Parameters

Self: Writer to inspect.

Return value

True when Applied_Profile is eligible.

Initialize

procedure Initialize
  (Self : in out Writer; Profile : Profiles.Writer_Profile; Diagnostic : out Errors.Diagnostic)

Validate and freeze one explicit output profile without beginning the destination. Maximum depth counts simultaneously open containers. A root container is depth one; a scalar root needs depth zero.

Parameters

Self: Uninitialized writer to prepare.
Profile: Complete explicit writer profile to validate and freeze.
Diagnostic: Cleared on success or set to the nonraising rejection reason.

Put_Boolean

procedure Put_Boolean (Self : in out Writer; Value : Boolean; Diagnostic : out Errors.Diagnostic)

Emit one true or false value.

Parameters

Self: Active writer at a position that accepts a JSON value.
Value: Boolean value whose JSON literal is emitted.
Diagnostic: Cleared on success or set to grammar or destination failure.

Put_Name_Fragment

procedure Put_Name_Fragment
  (Self : in out Writer; Value : Ada.Streams.Stream_Element_Array; Diagnostic : out Errors.Diagnostic)

Validate and escape one decoded UTF-8 member-name fragment. Fragments can split inside a UTF-8 sequence, and Value can have arbitrary bounds.

Parameters

Self: Active writer with an open member-name token.
Value: Next decoded UTF-8 octets; the writer retains no array reference.
Diagnostic: Cleared on success or set to UTF-8, offset, or destination failure.

Put_Null

procedure Put_Null (Self : in out Writer; Diagnostic : out Errors.Diagnostic)

Emit one null value.

Parameters

Self: Active writer at a position that accepts a JSON value.
Diagnostic: Cleared on success or set to grammar or destination failure.

Put_Number_Fragment

procedure Put_Number_Fragment
  (Self : in out Writer; Value : Ada.Streams.Stream_Element_Array; Diagnostic : out Errors.Diagnostic)

Validate and stage one exact number-lexeme fragment without normalization.

Parameters

Self: Active writer with an open number token.
Value: Next exact lexeme octets with arbitrary array bounds.
Diagnostic: Cleared on success or set to number, offset, or destination failure.

Put_String_Fragment

procedure Put_String_Fragment
  (Self : in out Writer; Value : Ada.Streams.Stream_Element_Array; Diagnostic : out Errors.Diagnostic)

Validate and escape one decoded UTF-8 string fragment. Fragments can split inside a UTF-8 sequence, and Value can have arbitrary bounds.

Parameters

Self: Active writer with an open string token.
Value: Next decoded UTF-8 octets; the writer retains no array reference.
Diagnostic: Cleared on success or set to UTF-8, offset, or destination failure.

Reset

procedure Reset
  (Self : in out Writer; Profile : Profiles.Writer_Profile; Diagnostic : out Errors.Diagnostic)

Prepare a completed, failed, or aborted writer for a new operation. The destination target and depth capacity remain fixed.

Parameters

Self: Terminal writer to reset.
Profile: Complete explicit writer profile to validate and freeze.
Diagnostic: Cleared on success or set to profile or lifecycle failure.

State

function State (Self : Writer) return Writer_State

Report the writer lifecycle state.

Parameters

Self: Writer to inspect.

Return value

Current state without changing destination or writer data.

Terminal_Diagnostic

function Terminal_Diagnostic (Self : Writer) return Errors.Diagnostic

Read the retained terminal diagnostic.

Parameters

Self: Interrupted, failed, or aborted writer.

Return value

Final diagnostic; an earlier primary remains primary if abort cleanup also fails.

Writer

type Writer
  (Target        : not null access Destination_Type;
   Maximum_Depth : Natural)
is
  limited private;

Allocation-free writer state bound to one caller-owned destination.

Record fields

Target: Nonnull destination object that outlives the writer.
Maximum_Depth: Maximum simultaneously open object and array containers.

Writer_State

type Writer_State is (Uninitialized, Ready, Active, Interrupted, Completed, Failed, Aborted);

Lifecycle state of one transactional writer operation.

Enumeration literals

Uninitialized: No writer profile has been validated or applied.
Ready: A profile is frozen and no destination transaction is active.
Active: One unpublished destination transaction is active.
Interrupted: An abnormal transfer escaped a writer call; abort is required.
Completed: The destination published one complete document.
Failed: The operation ended with a retained primary diagnostic.
Aborted: The unpublished transaction ended without publication.