Fork me on GitHub
NimYAML Home Testing Ground Docs: Overview Serialization Modules

Module yaml/stream

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

data

Types

YamlStream = ref object of RootObj
  nextImpl*: proc (s: YamlStream; e: var Event): bool {...}{.gcSafe.}
  lastTokenContextImpl*: proc (s: YamlStream; lineContent: var string): bool {...}{.
      raises: [].}
  peeked: bool
  cached: Event

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.

YamlStreamError = object of ValueError
  
Exception that may be raised by a YamlStream when the underlying backend raises an exception. The error that has occurred is available from parent.
BufferYamlStream = ref object of YamlStream
  pos: int
  buf: seq[Event]

Procs

proc basicInit(s: YamlStream; lastTokenContextImpl: proc (s: YamlStream;
    lineContent: var string): bool {...}{.raises: [].} = noLastContext) {...}{.raises: [],
    tags: [].}
initialize basic values of the YamlStream. Call this in your constructor if you subclass YamlStream.
proc initYamlStream(backend: iterator (): Event {...}{.gcSafe.}): YamlStream {...}{.
    raises: [], tags: [].}
Creates a new YamlStream that uses the given iterator as backend.
proc newBufferYamlStream(): BufferYamlStream not nil {...}{.raises: [], tags: [].}
proc put(bys: BufferYamlStream; e: Event) {...}{.raises: [], tags: [].}
proc next(s: YamlStream): Event {...}{.raises: [YamlStreamError], gcSafe,
                                  tags: [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.
proc peek(s: YamlStream): Event {...}{.raises: [YamlStreamError], tags: [RootEffect].}
Get the next item of the stream without advancing the stream. Requires finished(s) == true. Handles exceptions of the backend like next().
proc peek=(s: YamlStream; value: Event) {...}{.raises: [], tags: [].}
Set the next item of the stream. Will replace a previously peeked item, if one exists.
proc getLastTokenContext(s: YamlStream; 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.

Iterators

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