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
Types
WarningCallback = proc (line, column: int; lineContent: string; message: string)
-
Callback for parser warnings. Currently, this callback may be called on two occasions while parsing a YAML document stream:
- If the version number in the %YAML directive does not match 1.2.
- If there is an unknown directive encountered.
YamlParser = ref object tagLib: TagLibrary callback: WarningCallback anchors: Table[string, AnchorId]
- 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). Source
YamlLoadingError = object of Exception line*: int ## line number (1-based) where the error was encountered column*: int ## column number (1-based) where the error was encountered 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. Source
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.
Source
Procs
proc newYamlParser(tagLib: TagLibrary = initExtendedTagLibrary(); callback: WarningCallback = nil): YamlParser {.
raises: [], tags: [].}- Creates a YAML parser. if callback is not nil, it will be called whenever the parser yields a warning. Source
proc parse(p: YamlParser; s: Stream): YamlStream {.
raises: [YamlParserError], tags: [ReadIOEffect, RootEffect].}- Parse the given stream as YAML character stream. Source
proc parse(p: YamlParser; str: string): YamlStream {.
raises: [YamlParserError], tags: [RootEffect].}- Parse the given string as YAML character stream. Source
proc anchorName(p: YamlParser; anchor: AnchorId): string {.
raises: [], tags: [].}- Retrieve the textual representation of the given anchor as it occurred in the input (without the leading &). Returns the empty string for unknown anchors. Source
proc display(p: YamlParser; event: YamlStreamEvent): string {.
raises: [KeyError], 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.
Source