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

Module yaml/presenter

Search:
Group by:

This is the presenter API, used for generating YAML character streams.

Imports

data, taglib, stream, internal, hints, parser

Types

ContainerStyle = enum
  cBlock, cFlow, cMixed
How to serialize containers nodes.
  • cBlock writes all container nodes in block style, i.e. indentation-based.
  • cFlow writes all container nodes in flow style, i.e. JSON-like.
  • cMixed writes container nodes that only contain alias nodes and short scalar nodes in flow style, all other container nodes in block style.
DirectivesEndStyle = enum
  deAlways, deIfNecessary, deNever
Whether to write a directives end marker '---'
  • deAlways: Always write it.
  • deIfNecessary: Write it if any directive has been written, or if the root node has an explicit tag
  • deNever: Don't write it. Suppresses output of directives
NewLineStyle = enum
  nlLF, nlCRLF, nlOSDefault, nlNone
What kind of newline sequence is used when presenting.
  • nlLF: Use a single linefeed char as newline.
  • nlCRLF: Use a sequence of carriage return and linefeed as newline.
  • nlOSDefault: Use the target operation system's default newline sequence (CRLF on Windows, LF everywhere else).
  • nlNone: Don't use newlines, write everything in one line. forces ContainerStyle cFlow.
OutputYamlVersion = enum
  ov1_2, ov1_1, ovNone

Specify which YAML version number the presenter shall emit. The presenter will always emit content that is valid YAML 1.1, but by default will write a directive %YAML 1.2. For compatibility with other YAML implementations, it is possible to change this here.

It is also possible to specify that the presenter shall not emit any YAML version. The generated content is then guaranteed to be valid YAML 1.1 and 1.2 (but not 1.0 or any newer YAML version).

PresentationOptions = object
  containers*: ContainerStyle = cMixed ## how mappings and sequences are presented
  indentationStep*: int = 2  ## how many spaces a new level should be indented
  newlines*: NewLineStyle = nlOSDefault ## kind of newline sequence to use
  outputVersion*: OutputYamlVersion = ovNone ## whether to write the %YAML tag
  maxLineLength*: Option[int] = (val: 80, has: true) ## max length of a line, including indentation
  directivesEnd*: DirectivesEndStyle = deIfNecessary ## whether to write '---' after tags
  suppressAttrs*: bool = false ## whether to suppress all attributes on nodes
  quoting*: ScalarQuotingStyle = sqUnset ## how scalars are quoted
  condenseFlow*: bool = true ## whether non-nested flow containers use a single line
  explicitKeys*: bool = false ## whether mapping keys should always use '?'
Options for generating a YAML character stream 
ScalarQuotingStyle = enum
  sqUnset, sqDouble, sqJson
Specifies whether scalars should forcibly be double-quoted.
  • sqUnset: Quote where necessary
  • sqDouble: Force double-quoted style for every scalar
  • sqJson: Force JSON-compatible double-quoted style for every scalar except for scalars of other JSON types (bool, int, double)
YamlPresenterJsonError = object of ValueError
Exception that may be raised by the YAML presenter when it is instructed to output JSON, but is unable to do so. This may occur if:
  • The given YamlStream contains a map which has any non-scalar type as key.
  • Any float scalar bears a NaN or positive/negative infinity value
YamlPresenterOutputError = object of ValueError
Exception that may be raised by the YAML presenter. This occurs if writing character data to the output stream raises any exception. The error that has occurred is available from parent.

Procs

proc present(s: YamlStream; options: PresentationOptions = PresentationOptions()): string {....raises: [
    YamlPresenterJsonError, YamlPresenterOutputError, YamlStreamError],
    tags: [RootEffect, WriteIOEffect], forbids: [].}
Convert s to a YAML character stream and return it as string. 
proc present(s: YamlStream; target: Stream;
             options: PresentationOptions = PresentationOptions()) {....raises: [
    YamlPresenterJsonError, YamlPresenterOutputError, YamlStreamError],
    tags: [RootEffect, WriteIOEffect], forbids: [].}
Convert s to a YAML character stream and write it to target. 
proc transform(input: Stream | string;
               options: PresentationOptions = PresentationOptions();
               resolveToCoreYamlTags: bool = false): string {....raises: [IOError,
    OSError, YamlParserError, YamlPresenterJsonError, YamlPresenterOutputError].}
Parse input as YAML character stream and then dump it using the given presentation options. Returns the resulting string. If resolveToCoreYamlTags is true, non-specific tags will be replaced by specific tags according to the YAML core schema. 
proc transform(input: Stream | string; output: Stream;
               options: PresentationOptions = PresentationOptions();
               resolveToCoreYamlTags: bool = false) {....raises: [IOError, OSError,
    YamlParserError, YamlPresenterJsonError, YamlPresenterOutputError].}
Parse input as YAML character stream and then dump it to output using the given presentation options. If resolveToCoreYamlTags is true, non-specific tags will be replaced by specific tags according to the YAML core schema.

Made with Nim.