NimYAML Home Testing Ground Docs: Overview Serialization Modules NimYAML 2.x Source on GitHub

Module yaml/stream

Search:
Group by:

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

Imports

data

Types

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

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.

Procs

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

Iterators

iterator items(s: YamlStream): Event {....raises: [YamlStreamError],
                                       tags: [RootEffect], forbids: [].}
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: [],
    forbids: [].}
Iterate over all items of the stream. You may not use peek() on the stream while iterating.

Made with Nim.