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

Module yaml/data

Search:
Group by:

This module defines the event data structure which serves as internal representation of YAML structures. Every YAML document can be described as stream of events.

Imports

style, escaping

Types

Anchor = distinct string

An Anchor identifies an anchor in the current document. It is not necessarily unique and references to an anchor must be resolved immediately on occurrence.

Anchor provides the operator $ for converting to string, == for comparison, and hash for usage in a hashmap.

Event = object
  startPos*, endPos*: Mark
  case kind*: EventKind
  of yamlStartStream, yamlEndStream:
    nil
  of yamlStartMap:
      mapProperties*: Properties
      mapStyle*: CollectionStyle

  of yamlStartSeq:
      seqProperties*: Properties
      seqStyle*: CollectionStyle

  of yamlScalar:
      scalarProperties*: Properties
      scalarStyle*: ScalarStyle
      scalarContent*: string

  of yamlStartDoc:
      explicitDirectivesEnd*: bool
      version*: string
      handles*: seq[tuple[handle, uriPrefix: string]]

  of yamlEndDoc:
      explicitDocumentEnd*: bool

  of yamlEndMap, yamlEndSeq:
    nil
  of yamlAlias:
      aliasTarget*: Anchor

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 missing tag in the YAML character stream generates 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.

startPos and endPos are only relevant for events from an input stream - they are generally ignored if used with events that generate output.

EventKind = enum
  yamlStartStream, yamlEndStream, yamlStartDoc, yamlEndDoc, yamlStartMap,
  yamlEndMap, yamlStartSeq, yamlEndSeq, yamlScalar, yamlAlias
Kinds of YAML events that may occur in an YamlStream. Event kinds are discussed in YamlStreamEvent. 
Mark = object
  line*: Positive = 1
  column*: Positive = 1

Properties = tuple[anchor: Anchor, tag: Tag]
Tag = distinct string
A Tag contains an URI, like for example "tag:yaml.org,2002:str". 
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.

Consts

nimyamlTagRepositoryPrefix = "tag:nimyaml.org,2016:"
yamlTagRepositoryPrefix = "tag:yaml.org,2002:"
yAnchorNone: Anchor = ""
yielded when no anchor was defined for a YAML node 
yTagBinary = "tag:yaml.org,2002:binary"
yTagBoolean = "tag:yaml.org,2002:bool"
yTagExclamationMark: Tag = "!"
yTagFloat = "tag:yaml.org,2002:float"
yTagInteger = "tag:yaml.org,2002:int"
yTagMapping = "tag:yaml.org,2002:map"
yTagMerge = "tag:yaml.org,2002:merge"
yTagNimField = "tag:nimyaml.org,2016:field"
yTagNull = "tag:yaml.org,2002:null"
yTagOrderedMap = "tag:yaml.org,2002:omap"
yTagPairs = "tag:yaml.org,2002:pairs"
yTagQuestionMark: Tag = "?"
yTagSequence = "tag:yaml.org,2002:seq"
yTagSet = "tag:yaml.org,2002:set"
yTagString = "tag:yaml.org,2002:str"
yTagTimestamp = "tag:yaml.org,2002:timestamp"
yTagValue = "tag:yaml.org,2002:value"
yTagYaml = "tag:yaml.org,2002:yaml"

Procs

proc `$`(event: Event): string {....raises: [], tags: [], forbids: [].}
outputs a human-readable string describing the given event. This string is compatible to the format used in the yaml test suite. 
proc `$`(id: Anchor): string {.borrow, ...raises: [], tags: [], forbids: [].}
proc `$`(tag: Tag): string {.borrow, ...raises: [], tags: [], forbids: [].}
proc `==`(left, right: Anchor): bool {.borrow, ...raises: [], tags: [], forbids: [].}
proc `==`(left, right: Tag): bool {.borrow, ...raises: [], tags: [], forbids: [].}
proc `==`(left: Event; right: Event): bool {....raises: [], tags: [], forbids: [].}
compares all existing fields of the given items 
proc aliasEvent(target: Anchor; startPos: Mark = Mark(); endPos: Mark = Mark()): Event {.
    inline, ...raises: [], tags: [], forbids: [].}
creates a new event that represents a YAML alias 
proc collectionStyle(event: Event): CollectionStyle {....raises: [], tags: [],
    forbids: [].}
returns the style of the given collection start event 
proc defineCoreTag(name: string): Tag {....raises: [], tags: [], forbids: [].}
defines a tag in YAML's core namespace, tag:yaml.org,2002: 
proc defineTag(uri: string): Tag {....raises: [], tags: [], forbids: [].}
defines a tag. Use this to optimize away copies of globally defined Tags. 
proc emptyProperties(event: Event): bool {....raises: [], tags: [], forbids: [].}
returns true if the given event does not need to render any properties if presented into a YAML character stream. 
proc endDocEvent(explicit = false; startPos: Mark = Mark();
                 endPos: Mark = Mark()): Event {.inline, ...raises: [], tags: [],
    forbids: [].}
creates a new event that marks the end of a YAML document 
proc endMapEvent(startPos: Mark = Mark(); endPos: Mark = Mark()): Event {.
    inline, ...raises: [], tags: [], forbids: [].}
creates a new event that marks the end of a YAML mapping 
proc endSeqEvent(startPos: Mark = Mark(); endPos: Mark = Mark()): Event {.
    inline, ...raises: [], tags: [], forbids: [].}
creates a new event that marks the end of a YAML sequence 
proc endStreamEvent(): Event {....raises: [], tags: [], forbids: [].}
proc hash(id: Anchor): Hash {.borrow, ...raises: [], tags: [], forbids: [].}
proc hash(tag: Tag): Hash {.borrow, ...raises: [], tags: [], forbids: [].}
proc hasSpecificTag(event: Event): bool {....raises: [], tags: [], forbids: [].}
proc properties(event: Event): Properties {....raises: [], tags: [], forbids: [].}
returns the tag of the given event 
proc renderAttrs(props: Properties; isPlain: bool = true): string {....raises: [],
    tags: [], forbids: [].}
proc scalarEvent(content: string = ""; tag: Tag = yTagQuestionMark;
                 anchor: Anchor = yAnchorNone; style: ScalarStyle = ssAny;
                 startPos: Mark = Mark(); endPos: Mark = Mark()): Event {.
    inline, ...raises: [], tags: [], forbids: [].}
proc scalarEvent(content: string; props: Properties; style: ScalarStyle = ssAny;
                 startPos: Mark = Mark(); endPos: Mark = Mark()): Event {.
    inline, ...raises: [], tags: [], forbids: [].}
creates a new event that represents a YAML scalar 
proc startDocEvent(explicit = false; version = "";
                   handles: seq[tuple[handle, uriPrefix: string]] = @[];
                   startPos: Mark = Mark(); endPos: Mark = Mark()): Event {.
    inline, ...raises: [], tags: [], forbids: [].}
creates a new event that marks the start of a YAML document 
proc startMapEvent(style: CollectionStyle = csAny; tag: Tag = yTagQuestionMark;
                   anchor: Anchor = yAnchorNone; startPos: Mark = Mark();
                   endPos: Mark = Mark()): Event {.inline, ...raises: [], tags: [],
    forbids: [].}
proc startMapEvent(style: CollectionStyle; props: Properties;
                   startPos: Mark = Mark(); endPos: Mark = Mark()): Event {.
    inline, ...raises: [], tags: [], forbids: [].}
creates a new event that marks the start of a YAML mapping 
proc startSeqEvent(style: CollectionStyle = csAny; tag: Tag = yTagQuestionMark;
                   anchor: Anchor = yAnchorNone; startPos: Mark = Mark();
                   endPos: Mark = Mark()): Event {.inline, ...raises: [], tags: [],
    forbids: [].}
proc startSeqEvent(style: CollectionStyle; props: Properties;
                   startPos: Mark = Mark(); endPos: Mark = Mark()): Event {.
    inline, ...raises: [], tags: [], forbids: [].}
creates a new event that marks the beginning of a YAML sequence 
proc startStreamEvent(): Event {....raises: [], tags: [], forbids: [].}

Exports

collection, CollectionStyle, ScalarStyle, scalar

Made with Nim.