Module yaml.stream

Search:

Group by:

The stream API provides the basic data structure on which all low-level APIs operate. It is not named streams to not confuse it with the modle in the stdlib with that name.

Imports

hashes, ../private/internal, taglib

Types

AnchorId = distinct int

An AnchorId identifies an anchor in the current document. It becomes invalid as soon as the current document scope is invalidated (for example, because the parser yielded a yamlEndDocument event). AnchorId s exists because of efficiency, much like TagId s. The actual anchor name is a presentation detail and cannot be queried by the user. Source

YamlStreamEventKind = enum yamlStartDoc, yamlEndDoc, yamlStartMap, yamlEndMap, yamlStartSeq, yamlEndSeq, yamlScalar, yamlAlias

Kinds of YAML events that may occur in an YamlStream. Event kinds are discussed in YamlStreamEvent. Source

YamlStreamEvent = object case kind*: YamlStreamEventKind of yamlStartMap: mapAnchor*: AnchorId mapTag*: TagId of yamlStartSeq: seqAnchor*: AnchorId seqTag*: TagId of yamlScalar: scalarAnchor*: AnchorId scalarTag*: TagId scalarContent*: string of yamlEndMap, yamlEndSeq, yamlStartDoc, yamlEndDoc: nil of yamlAlias: aliasTarget*: AnchorId

An element from a YamlStream. Events that start an object (yamlStartMap, yamlStartSeq, yamlScalar) have an optional anchor and a tag associated with them. The anchor will be set to yAnchorNone if it doesn't exist.

A non-existing tag in the YAML character stream will be resolved to the non-specific tags ? or ! according to the YAML specification. These are by convention mapped to the TagId s yTagQuestionMark and yTagExclamationMark respectively. Mapping is done by a TagLibrary.

Source

YamlStream = ref object of RootObj nextImpl*: proc (s: YamlStream; e: var YamlStreamEvent): bool lastTokenContextImpl*: proc (s: YamlStream; line, column: var int; lineContent: var string): bool {. raises: [] .} isFinished*: bool peeked: bool cached: YamlStreamEvent

A YamlStream is an iterator-like object that yields a well-formed stream of YamlStreamEvents. Well-formed means that every yamlStartMap is terminated by a yamlEndMap, every yamlStartSeq is terminated by a yamlEndSeq and every yamlStartDoc is terminated by a yamlEndDoc. Moreover, every emitted mapping has an even number of children.

The creator of a YamlStream is responsible for it being well-formed. A user of the stream may assume that it is well-formed and is not required to check for it. The procs in this module will always yield a well-formed YamlStream and expect it to be well-formed if they take it as input parameter.

Source

YamlStreamError = object of Exception

Exception that may be raised by a YamlStream when the underlying backend raises an exception. The error that has occurred is available from parent. Source

BufferYamlStream = ref object of YamlStream pos: int buf: seq[YamlStreamEvent] not nil

Source

Consts

yAnchorNone: AnchorId = -1: yielded when no anchor was defined for a YAML node Source

Procs

proc `==`(left, right: AnchorId): bool {. borrow .}: Source
proc `$`(id: AnchorId): string {. borrow .}: Source
proc hash(id: AnchorId): Hash {. borrow .}: Source
proc basicInit(s: YamlStream; lastTokenContextImpl: proc (s: YamlStream; line, column: var int; lineContent: var string): bool {. raises: [] .} = noLastContext) {. raises: [], tags: [] .}: initialize basic values of the YamlStream. Call this in your constructor if you subclass YamlStream. Source
proc initYamlStream(backend: iterator (): YamlStreamEvent): YamlStream {. raises: [], tags: [] .}: Creates a new YamlStream that uses the given iterator as backend. Source
proc newBufferYamlStream(): BufferYamlStream not nil {. raises: [], tags: [] .}: Source
proc put(bys: BufferYamlStream; e: YamlStreamEvent) {. raises: [], tags: [] .}: Source
proc next(s: YamlStream): YamlStreamEvent {. raises: [YamlStreamError], tags: [WriteIOEffect, RootEffect] .}: Get the next item of the stream. Requires finished(s) == true. If the backend yields an exception, that exception will be encapsulated into a YamlStreamError, which will be raised. Source
proc peek(s: YamlStream): YamlStreamEvent {. raises: [YamlStreamError], tags: [WriteIOEffect, RootEffect] .}: Get the next item of the stream without advancing the stream. Requires finished(s) == true. Handles exceptions of the backend like next(). Source
proc peek=(s: YamlStream; value: YamlStreamEvent) {. raises: [], tags: [] .}: Set the next item of the stream. Will replace a previously peeked item, if one exists. Source
proc finished(s: YamlStream): bool {. raises: [YamlStreamError], tags: [RootEffect] .}: true if no more items are available in the stream. Handles exceptions of the backend like next(). Source
proc getLastTokenContext(s: YamlStream; line, column: var int; lineContent: var string): bool {. raises: [], tags: [RootEffect] .}: true if source context information is available about the last returned token. If true, line, column and lineContent are set to position and line content where the last token has been read from. Source
proc `==`(left: YamlStreamEvent; right: YamlStreamEvent): bool {. raises: [], tags: [] .}: compares all existing fields of the given items Source
proc `$`(event: YamlStreamEvent): string {. raises: [], tags: [] .}: outputs a human-readable string describing the given event Source
proc tag(event: YamlStreamEvent): TagId {. raises: [FieldError], tags: [] .}: returns the tag of the given event Source
proc startDocEvent(): YamlStreamEvent {. inline, raises: [], tags: [] .}: creates a new event that marks the start of a YAML document Source
proc endDocEvent(): YamlStreamEvent {. inline, raises: [], tags: [] .}: creates a new event that marks the end of a YAML document Source
proc startMapEvent(tag: TagId = yTagQuestionMark; anchor: AnchorId = yAnchorNone): YamlStreamEvent {. inline, raises: [], tags: [] .}: creates a new event that marks the start of a YAML mapping Source
proc endMapEvent(): YamlStreamEvent {. inline, raises: [], tags: [] .}: creates a new event that marks the end of a YAML mapping Source
proc startSeqEvent(tag: TagId = yTagQuestionMark; anchor: AnchorId = yAnchorNone): YamlStreamEvent {. inline, raises: [], tags: [] .}: creates a new event that marks the beginning of a YAML sequence Source
proc endSeqEvent(): YamlStreamEvent {. inline, raises: [], tags: [] .}: creates a new event that marks the end of a YAML sequence Source
proc scalarEvent(content: string = ""; tag: TagId = yTagQuestionMark; anchor: AnchorId = yAnchorNone): YamlStreamEvent {. inline, raises: [], tags: [] .}: creates a new event that represents a YAML scalar Source
proc aliasEvent(anchor: AnchorId): YamlStreamEvent {. inline, raises: [], tags: [] .}: creates a new event that represents a YAML alias Source

Iterators

iterator items(s: YamlStream): YamlStreamEvent {. raises: [YamlStreamError], tags: [RootEffect, WriteIOEffect] .}: Iterate over all items of the stream. You may not use peek() on the stream while iterating. Source
iterator mitems(bys: BufferYamlStream): var YamlStreamEvent {. raises: [], tags: [] .}: Iterate over all items of the stream. You may not use peek() on the stream while iterating. Source