Description
Chunk-fed RDF 1.2 Turtle and TriG parser.
Input may be split at any byte boundary, including inside a multi-byte scalar, an escape, or a long string, and produces the same event stream regardless of how it was split.
Events are emitted as soon as a statement completes. A consumer that needs a document to be admitted atomically holds them until Finish reports success; one that is streaming into a store can act immediately.
Code
function Code (Value : Parse_Diagnostic) return Diagnostic_Code
Return the failure category.
Parameters
- Value
Diagnostic to inspect
Return value
The diagnostic code
Create
function Create
(Source_Name : String;
Blank_Node_Prefix : String := "";
Base_IRI : String := "";
Limits : Parse_Limits := (others => <>);
Syntax : Syntax_Kind := TriG_Syntax;
Work_Checkpoint : Work_Checkpoint_Access := null) return Parser
Begin a parse.
Parameters
- Source_Name
Name reported in diagnostics
- Blank_Node_Prefix
Prepended to every blank node label, both those the document writes and those the parser generates, so that labels from two documents parsed by the same consumer cannot collide. Within one document the parser keeps its generated labels clear of the document's own, so reading back what this crate wrote renames nothing and is a fixed point
- Base_IRI
Absolute IRI relative references resolve against, or empty for none
- Limits
Bounds for this parse
- Syntax
Grammar to accept
- Work_Checkpoint
Optional cooperative-yield callback
Return value
A parser ready to be fed
Raised exceptions
- Invalid_Configuration
Base_IRI is neither empty nor an absolute IRI
Diagnostic_Code
type Diagnostic_Code is
(Malformed_Syntax,
Invalid_Encoding,
Invalid_IRI,
Undefined_Prefix,
Byte_Limit,
Quad_Limit,
Nesting_Limit,
Token_Limit,
Prefix_Limit,
Unsupported_Production);
Why a parse failed.
Enumeration literals
- Malformed_Syntax
Input is outside the accepted grammar
- Invalid_Encoding
Input is not canonical UTF-8
- Invalid_IRI
A resolved IRI is not a valid absolute IRI
- Undefined_Prefix
A prefixed name used an unbound prefix
- Byte_Limit
Maximum_Bytes exceeded
- Quad_Limit
Maximum_Quads exceeded
- Nesting_Limit
Maximum_Nesting exceeded
- Token_Limit
Maximum_Token_Bytes exceeded
- Prefix_Limit
Maximum_Prefixes exceeded
- Unsupported_Production
A production this grammar rejects
Event_Sink
type Event_Sink is limited interface;
Receives parse events.
Feed
procedure Feed
(Into : in out Parser;
Bytes : String;
Target : in out Event_Sink'Class)
Supply the next bytes of input, emitting every event they complete.
If a sink callback raises, the exception propagates unchanged and the parser is poisoned: no later Feed emits anything, and Finish reports failure.
Parameters
- Into
Parser to feed
- Bytes
Next chunk, which may split any token
- Target
Sink receiving events
Raised exceptions
- Parser_State_Error
Into has already finished
Finish
function Finish
(Into : in out Parser;
Target : in out Event_Sink'Class) return Parse_Status
Complete the parse, emitting any final events.
Parameters
- Into
Parser to finish
- Target
Sink receiving events
Return value
Whether the document was accepted
Raised exceptions
- Parser_State_Error
Into has already finished
Invalid_Configuration
Invalid_Configuration : exception;
Raised when Create is given a base IRI that is not absolute.
Is_Line_Based
function Is_Line_Based (Value : Syntax_Kind) return Boolean
Report whether a grammar is one of the line-based ones, which admit no directives, no abbreviations, and no relative references.
Parameters
- Value
Grammar to classify
Return value
True for N-Triples and N-Quads
On_Diagnostic
procedure On_Diagnostic
(Target : in out Event_Sink;
Value : Parse_Diagnostic)
Called once, when the parse fails.
Parameters
- Target
The sink
- Value
The diagnostic
On_Graph_Declaration
procedure On_Graph_Declaration
(Target : in out Event_Sink;
Graph : Quads.Graph_Name;
Span : Source_Span)
Called when a graph block or GRAPH declaration names a graph.
Parameters
- Target
The sink
- Graph
The graph being entered
- Span
Region naming the graph
On_Quad
procedure On_Quad
(Target : in out Event_Sink;
Value : Quads.Quad;
Span : Source_Span)
Called once per statement.
Parameters
- Target
The sink
- Value
The statement
- Span
Region that produced it
Parse_Diagnostic
type Parse_Diagnostic is private;
A typed parse failure.
Parse_Limits
type Parse_Limits is record
Maximum_Bytes : Positive := 64 * 1_024 * 1_024;
Maximum_Quads : Natural := 0;
Maximum_Nesting : Positive := 128;
Maximum_Token_Bytes : Positive := 1_048_576;
Maximum_Prefixes : Natural := 4_096;
end record;
Bounds a caller imposes on one parse.
Record fields
- Maximum_Bytes
Total input accepted
- Maximum_Quads
Statements emitted, zero for no limit
- Maximum_Nesting
Depth of collections, property lists, quoted triples, and annotations combined
- Maximum_Token_Bytes
Longest single token
- Maximum_Prefixes
Distinct prefixes bound by directives
Parse_Status
type Parse_Status is (Parse_Succeeded, Parse_Failed);
Outcome of a completed parse.
Enumeration literals
- Parse_Succeeded
Every statement was read and delivered
- Parse_Failed
A diagnostic was delivered and reading stopped
Parser
type Parser (<>) is limited private;
A parse in progress.
Parser_State_Error
Parser_State_Error : exception;
Raised when a parser is used after it has finished or failed.
Production
function Production (Value : Parse_Diagnostic) return Production_Kind
Return the production that failed.
Parameters
- Value
Diagnostic to inspect
Return value
The production kind
Production_Kind
type Production_Kind is
(Document_Production,
Directive_Production,
Graph_Block_Production,
Statement_Production,
Subject_Production,
Predicate_Production,
Object_Production,
IRI_Production,
…,
Annotation_Production);
Which part of the grammar was being read.
Enumeration literals
- Document_Production
The document as a whole
- Directive_Production
A prefix, base or version directive
- Graph_Block_Production
A TriG graph block
- Statement_Production
One statement
- Subject_Production
The subject position
- Predicate_Production
The predicate position
- Object_Production
The object position
- IRI_Production
An IRI, absolute or relative
- Blank_Label_Production
A blank node label
- Literal_Production
A literal and its datatype or tag
- Collection_Production
A parenthesised collection
- Triple_Term_Production
An RDF 1.2 triple term
- Annotation_Production
An RDF 1.2 annotation or reifier
Source_Name
function Source_Name (Value : Parse_Diagnostic) return String
Return the source name supplied at Create.
Parameters
- Value
Diagnostic to inspect
Return value
The source name
Source_Span
type Source_Span is record
Start_Byte : Natural := 0;
End_Byte : Natural := 0;
Start_Line : Positive := 1;
Start_Column : Positive := 1;
End_Line : Positive := 1;
End_Column : Positive := 1;
end record;
A region of the input, given at both ends so that a caller can underline it without rescanning.
Record fields
- Start_Byte
Offset of the first byte, zero when unset
- End_Byte
Offset one past the last byte
- Start_Line
Line the region opens on, counting from one
- Start_Column
Column the region opens on, counting from one
- End_Line
Line the region closes on
- End_Column
Column the region closes on
Span
function Span (Value : Parse_Diagnostic) return Source_Span
Return the region of input responsible.
Parameters
- Value
Diagnostic to inspect
Return value
The source span
Syntax_Kind
type Syntax_Kind is
(Turtle_Syntax, TriG_Syntax, NTriples_Syntax, NQuads_Syntax);
Which document grammar to accept.
The line-based grammars are here rather than in a package of their own because they are a subset of this one down to the token level: they reuse the same scanner, the same event sink, the same diagnostics, and the same chunk-feeding machinery, and differ only in which productions are admitted.
Enumeration literals
- Turtle_Syntax
Reject graph blocks and the GRAPH keyword
- TriG_Syntax
Accept Turtle statements and TriG graph blocks
- NTriples_Syntax
One absolute-IRI statement per line, no graph
- NQuads_Syntax
N-Triples with an optional graph label
Work
function Work (Value : Parser) return Work_Statistics
Report the work this parser has done.
Parameters
- Value
Parser to inspect
Return value
The accumulated statistics
Work_Checkpoint_Access
type Work_Checkpoint_Access is access procedure;
Optional cooperative-yield callback, invoked periodically while scanning. It exists so that a lightweight-task runtime can interleave, and is deliberately typed as a plain access-to-procedure so that this crate depends on no runtime at all.
Work_Checkpoint_Interval
Work_Checkpoint_Interval : constant Positive := 4_096;
Scan units between checkpoint callbacks.
Work_Statistics
type Work_Statistics is record
Bytes_Scanned : Natural := 0;
Tokens_Scanned : Natural := 0;
Statements_Parsed : Natural := 0;
Checkpoint_Calls : Natural := 0;
Maximum_Pending_Bytes : Natural := 0;
Maximum_Pending_Tokens : Natural := 0;
end record;
Deterministic account of scanning work, for tests that need to pin behaviour rather than timing.
Record fields
- Bytes_Scanned
Input bytes examined
- Tokens_Scanned
Tokens produced
- Statements_Parsed
Statements completed
- Checkpoint_Calls
Cooperative callbacks invoked
- Maximum_Pending_Bytes
Largest retained partial token
- Maximum_Pending_Tokens
Largest retained statement, in tokens