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

Module yaml/parser

This is the low-level parser API. A YamlParser enables you to parse any non-nil string or Stream object as YAML character stream.

Imports

stream, lex, internal, escaping, data

Types

YamlParser = object
  issueWarnings: bool
A parser object. Retains its TagLibrary across calls to parse. Can be used to access anchor names while parsing a YAML character stream, but only until the document goes out of scope (i.e. until yamlEndDocument is yielded).
YamlLoadingError = object of ValueError
  mark*: Mark                ## position at which the error has occurred.
  lineContent*: string ## \
                       ## content of the line where the error was encountered. Includes a
                       ## second line with a marker ``^`` at the position where the error
                       ## was encountered.
  
Base class for all exceptions that may be raised during the process of loading a YAML character stream.
YamlParserError = object of YamlLoadingError
  

A parser error is raised if the character stream that is parsed is not a valid YAML character stream. This stream cannot and will not be parsed wholly nor partially and all events that have been emitted by the YamlStream the parser provides should be discarded.

A character stream is invalid YAML if and only if at least one of the following conditions apply:

  • There are invalid characters in an element whose contents is restricted to a limited set of characters. For example, there are characters in a tag URI which are not valid URI characters.
  • An element has invalid indentation. This can happen for example if a block list element indicated by "- " is less indented than the element in the previous line, but there is no block sequence list open at the same indentation level.
  • The YAML structure is invalid. For example, an explicit block map indicated by "? " and ": " may not suddenly have a block sequence item ("- ") at the same indentation level. Another possible violation is closing a flow style object with the wrong closing character (}, ]) or not closing it at all.
  • A custom tag shorthand is used that has not previously been declared with a %TAG directive.
  • Multiple tags or anchors are defined for the same node.
  • An alias is used which does not map to any anchor that has previously been declared in the same document.
  • An alias has a tag or anchor associated with it.

Some elements in this list are vague. For a detailed description of a valid YAML character stream, see the YAML specification.

Procs

proc init(p: var YamlParser; issueWarnings: bool = false) {...}{.raises: [], tags: [].}
Initializes a YAML parser.
proc initYamlParser(issueWarnings: bool = false): YamlParser {...}{.raises: [],
    tags: [].}
Creates an initializes YAML parser and returns it
proc parse(p: YamlParser; s: Stream): YamlStream {...}{.raises: [IOError, OSError],
    tags: [ReadIOEffect].}
proc parse(p: YamlParser; s: string): YamlStream {...}{.raises: [],
    tags: [ReadIOEffect].}
proc display(p: YamlParser; event: Event): string {...}{.raises: [], tags: [].}

Generate a representation of the given event with proper visualization of anchor and tag (if any). The generated representation is conformant to the format used in the yaml test suite.

This proc is an informed version of $ on YamlStreamEvent which can properly display the anchor and tag name as it occurs in the input. However, it shall only be used while using the streaming API because after finishing the parsing of a document, the parser drops all information about anchor and tag names.