We place a small wrapper around all of the arguments provided to
Read::drive(), and return a wrapped error, both of which are opaque to
external libraries.
This type obscures the underlying classifications, providing a stable
enum, Category, for classification.
This doesn't particularly change the various module level errors, though
will will have to implement From<Self> for yary::Error.
I'll also need to make private and public versions of the initializer
functions for fallible public methods that can be used internally, e.g
lib/reader.
This commit surfaces a public API for streaming YAML events from a read
source. It provides callers an Events{} type that can be generated from
any reader::Read implementation -- so for the moment, OwnedReader(s) and
BorrowReader(s) -- via the module functions from_reader() and
from_reader_with(). This type implements IntoIterator, and thus can be
integrated with any iterator based flows, and benefits from the entire,
extensive ecosystem around them.
That said, I expect this to be a relatively unused part of this library
in the long term, being the lowest level public API exposed by this
library.
These define the configuration that library users are allowed to set
when iterating over Events.
It currently only has one meaningful option, O_LAZY which reflects the
behavior exposed by lib/scanner. This will likely change in the future,
if more customization is desired when working with Event streams.
- set default rust version
instead of a folder override, as we always expect to use the provided
version globally per run.
- explicitly declare extra rustup components
rather than implicitly rely on the current defaults
These macros make op the test harness used by module tests. They allow
us to declare a set of tokens! which will be matched against the expected
events! that the tokens should produce.
The others simplify the process of declaring some of the more nested
event structures quickly
- flow_sequence_entry_mapping_key
- flow_sequence_entry_mapping_value
- flow_sequence_entry_mapping_end
These are special cased due to how some of the implied values can pop
up, and because we need far fewer rules then in the transition from
block_{sequence,mapping}->flow_mapping.
- block_sequence_entry
- block_mapping_key
- block_mapping_value
- flow_sequence_entry
- flow_mapping_key
- flow_mapping_value
These were mostly straightforward, only tricky bit is handling all the
cases in which YAML allows a (scalar) node to be "implied".
- document_start
- document_end
- explicit_document_content
Note that we guarantee at least one (DocumentStart, DocumentEnd) event
pair in the event stream, regardless of whether these tokens exist or
not.
We also guarantee that each DocumentStart _will_ have a DocumentEnd
eventually, again regardless of whether such exists in the token stream.
This isn't explicitly required by the YAML spec, but makes usage of the
Parser more pleasant to callers, as all "indentation" events --
documents, sequences, mappings -- have a guaranteed start and end event,
without the caller needing to infer this behavior from the stream
itself.
If the caller is interested, each DocumentStart and DocumentEnd event
records whether it was implicit (missing from the byte stream), or not.
The most notable of the types included in this commit is EventData. Its
parent, Event, is a small wrapper with some additional stream information
encoded -- the approximate start and end bytes covered.
EventData has 10 variants:
1. StreamStart
2. StreamEnd
3. DocumentStart
4. DocumentEnd
5. Alias
6. Scalar
7. MappingStart
8. MappingEnd
9. SequenceStart
10. SequenceEnd
Combined, they allow us to express a stream of YAML in an iterative
event model, that should hopefully be easy (at least compared to YAML
proper) to consume.
Expressed in pseudo backus-naur, this is the expected form of any
given event stream:
=== Event Stream ===
stream := StreamStart document+ StreamEnd
document := DocumentStart content? DocumentEnd
content := Scalar | collection
collection := sequence | mapping
sequence := SequenceStart node* SequenceEnd
mapping := MappingStart (node node)* MappingEnd
node := Alias | content
=== Syntax ===
? => 0 or 1 of prefix
* => 0 or more of prefix
+ => 1 or more of prefix
() => production grouping
| => production logical OR
=== End ===
This module will house the first, lowest level public API of this
library, eventually exposing a structure that allows callers to consume
high level YAML 'Events', likely with an Iterator interface.
Paul Stemmet