diff --git a/yaml.html b/yaml.html index 2c1ebb4..efdc90e 100644 --- a/yaml.html +++ b/yaml.html @@ -6,7 +6,7 @@ - + @@ -19,13 +19,37 @@ Docs: Overview Serialization - Module yaml + + Modules + +

Module yaml

+
+ Search: +
+
+ Group by: + +
-
  • - Types - -
    • -
  • - Vars - -
    • -
  • - Consts - -
    • -
  • - Procs - -
    • -
  • - Iterators - -
    • -
  • - Templates - -
    • -

    This module provides facilities to generate and interpret YAML character streams. All primitive operations on data objects use a YamlStream either as source or as output. Because this stream is implemented as iterator, it is possible to process YAML input and output sequentially, i.e. without loading the processed data structure completely into RAM. This supports the processing of large data structures.

    -

    As YAML is a strict superset of JSON, JSON input is automatically supported. While JSON is less readable than YAML, this enhances interoperability with other languages.

    +
    +

    This is the parent module of NimYAML, a package that provides facilities to generate and interpret YAML character streams. Importing this package will import everything from all subpackages.

    +

    There are three high-level APIs which are probably most useful:

    +
    • The serialization API in serialization enables you to load YAML data directly into native Nim types, and reversely dump native Nim types as YAML.
      • +
    • The DOM API in dom parses YAML files in a tree structure which you can navigate.
      • +
    • The JSON API in tojson parses YAML files into the Nim stdlib's JSON structure, which may be useful if you have other modules which expect JSON input. Note that the serialization API is able to write and load JSON; you do not need the JSON API for that.
      • +
    +

    Apart from those high-level APIs, NimYAML implements a low-level API which enables you to process YAML input as data stream which does not need to be loaded into RAM completely at once. It consists of the following modules:

    +
    • The stream API in stream defines the central type for stream processing, YamlStream. It also contains definitions and constructor procs for stream events.
      • +
    • The parser API in parser gives you direct access to the YAML parser's output.
      • +
    • The presenter API in presenter gives you direct access to the presenter, i.e. the module that renders a YAML character stream.
      • +
    • The taglib API in taglib provides a data structure for keeping track of YAML tags that are generated by the parser or used in the presenter.
      • +
    • The hints API in hints provides a simple proc for guessing the type of a scalar value.
      • +

    Imports

    -streams, unicode, lexbase, tables, strutils, json, hashes, queues, macros, typetraits, parseutils -
    -
    -

    Types

    -
    -
    TypeHint = enum
-  yTypeInteger, yTypeFloat, yTypeFloatInf, yTypeFloatNaN, yTypeBoolTrue,
-  yTypeBoolFalse, yTypeNull, yTypeUnknown
    -
    -

    A type hint can be computed from scalar content and tells you what NimYAML thinks the scalar's type is. It is generated by guessType The first matching RegEx in the following table will be the type hint of a scalar string.

    -

    You can use it to determine the type of YAML scalars that have a '?' non-specific tag, but using this feature is completely optional.

    - - - - - - - - - -
    NameRegEx
    yTypeInteger0 | -? [1-9] [0-9]*
    yTypeFloat-? [1-9] ( \. [0-9]* [1-9] )? ( e [-+] [1-9] [0-9]* )?
    yTypeFloatInf-? \. (inf | Inf | INF)
    yTypeFloatNaN-? \. (nan | NaN | NAN)
    yTypeBoolTruey|Y|yes|Yes|YES|true|True|TRUE|on|On|ON
    yTypeBoolFalsen|N|no|No|NO|false|False|FALSE|off|Off|OFF
    yTypeNull~ | null | Null | NULL
    yTypeUnknown*
    -  Source -
    -
    YamlStreamEventKind = enum
-  yamlStartDoc, yamlEndDoc, yamlStartMap, yamlEndMap, yamlStartSeq, yamlEndSeq,
-  yamlScalar, yamlAlias
    -
    -Kinds of YAML events that may occur in an YamlStream. Event kinds are discussed in YamlStreamEvent. -  Source -
    -
    TagId = distinct int
    -
    -

    -A TagId identifies a tag URI, like for example "tag:yaml.org,2002:str". The URI corresponding to a TagId can be queried from the TagLibrary which was used to create this TagId; e.g. when you parse a YAML character stream, the TagLibrary of the parser is the one which generates the resulting TagId s.

    -

    URI strings are mapped to TagId s for efficiency reasons (you do not need to compare strings every time) and to be able to discover unknown tag URIs early in the parsing process.

    - -  Source -
    -
    AnchorId = distinct int
    -
    - -An AnchorId identifies an anchor in the current document. It becomes invalid as soon as the current document scope is invalidated (for example, because the parser yielded a yamlEndDocument event). AnchorId s exists because of efficiency, much like TagId s. The actual anchor name is a presentation detail and cannot be queried by the user. -  Source -
    -
    YamlStreamEvent = object
-  case kind*: YamlStreamEventKind
-  of yamlStartMap:
-      mapAnchor*: AnchorId
-      mapTag*: TagId
-
-  of yamlStartSeq:
-      seqAnchor*: AnchorId
-      seqTag*: TagId
-
-  of yamlScalar:
-      scalarAnchor*: AnchorId
-      scalarTag*: TagId
-      scalarContent*: string
-
-  of yamlEndMap, yamlEndSeq, yamlStartDoc, yamlEndDoc:
-    nil
-  of yamlAlias:
-      aliasTarget*: AnchorId
-
-
    -
    -

    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 non-existing tag in the YAML character stream will be resolved to 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.

    - -  Source -
    -
    YamlStream = object
-  backend: iterator (): YamlStreamEvent
-  peeked: bool
-  cached: YamlStreamEvent
-
    -
    -

    -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.

    - -  Source -
    -
    TagLibrary = ref object
-  tags*: Table[string, TagId]
-  nextCustomTagId*: TagId
-  secondaryPrefix*: string
-
    -
    -

    A TagLibrary maps tag URIs to TagId s.

    -

    When YamlParser encounters tags not existing in the tag library, it will use registerUri to add the tag to the library.

    -

    You can base your tag library on common tag libraries by initializing them with initFailsafeTagLibrary, initCoreTagLibrary or initExtendedTagLibrary.

    - -  Source -
    -
    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.
      • -
    - -  Source -
    -
    YamlParser = ref object
-  tagLib: TagLibrary
-  callback: WarningCallback
-  lexer: BaseLexer
-  tokenstart: int
-  content, after: string
-  ancestry: seq[FastParseLevel]
-  level: FastParseLevel
-  tagUri: string
-  tag: TagId
-  anchor: AnchorId
-  shorthands: Table[string, string]
-  anchors: Table[string, AnchorId]
-  nextAnchorId: AnchorId
-  newlines: int
-  indentation: int
-
    -
    -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 -
    -
    PresentationStyle = enum
-  psMinimal, psCanonical, psDefault, psJson, psBlockOnly
    -
    -Different styles for YAML character stream output.
    • ypsMinimal: Single-line flow-only output which tries to use as few characters as possible.
      • -
    • ypsCanonical: Canonical YAML output. Writes all tags except for the non-specific tags ? and !, uses flow style, quotes all string scalars.
      • -
    • ypsDefault: Tries to be as human-readable as possible. Uses block style by default, but tries to condense mappings and sequences which only contain scalar nodes into a single line using flow style.
      • -
    • ypsJson: Omits the %YAML directive and the --- marker. Uses flow style. Flattens anchors and aliases, omits tags. Output will be parseable as JSON. YamlStream to dump may only contain one document.
      • -
    • ypsBlockOnly: Formats all output in block style, does not use flow style at all.
      • -
    - -  Source -
    -
    TagStyle = enum
-  tsNone, tsRootOnly, tsAll
    -
    -Whether object should be serialized with explicit tags.
    • tsNone: No tags will be outputted unless necessary.
      • -
    • tsRootOnly: A tag will only be outputted for the root tag and where necessary.
      • -
    • tsAll: Tags will be outputted for every object.
      • -
    - -  Source -
    -
    AnchorStyle = enum
-  asNone, asTidy, asAlways
    -
    -How ref object should be serialized.
    • asNone: No anchors will be outputted. Values present at multiple places in the content that should be serialized will be fully serialized at every occurence. If the content is cyclic, this will lead to an endless loop!
      • -
    • asTidy: Anchors will only be generated for objects that actually occur more than once in the content to be serialized. This is a bit slower and needs more memory than asAlways.
      • -
    • asAlways: Achors will be generated for every ref object in the content to be serialized, regardless of whether the object is referenced again afterwards
      • -
    - -  Source -
    -
    NewLineStyle = enum
-  nlLF, nlCRLF, nlOSDefault
    -
    -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).
      • -
    - -  Source -
    -
    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).

    - -  Source -
    -
    PresentationOptions = object
-  style*: PresentationStyle
-  indentationStep*: int
-  newlines*: NewLineStyle
-  outputVersion*: OutputYamlVersion
-
    -
    -Options for generating a YAML character stream -  Source -
    -
    ConstructionContext = ref object
-  refs: Table[AnchorId, pointer]
-
    -
    -Context information for the process of constructing Nim values from YAML. -  Source -
    -
    SerializationContext = ref object
-  refs: Table[pointer, AnchorId]
-  style: AnchorStyle
-  nextAnchorId: AnchorId
-
    -
    -Context information for the process of serializing YAML from Nim values. -  Source -
    -
    RawYamlStream = iterator (): YamlStreamEvent {.raises: [].}
    -
    - -Stream of YamlStreamEvent``s returned by ``representObject procs. -  Source -
    -
    YamlNodeKind = enum
-  yScalar, yMapping, ySequence
    -
    - -  Source -
    -
    YamlNode = ref YamlNodeObj not nil
    -
    -Represents a node in a YamlDocument. -  Source -
    -
    YamlNodeObj = object
-  tag*: string
-  case kind*: YamlNodeKind
-  of yScalar: content*: string
-  of ySequence: children*: seq[YamlNode]
-  of yMapping: pairs*: seq[tuple[key, value: YamlNode]]
-
    -
    - -  Source -
    -
    YamlDocument = object
-  root*: YamlNode
-
    -
    -Represents a YAML document. -  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 -
    -
    YamlPresenterJsonError = object of Exception
-
    -
    -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
      • -
    - -  Source -
    -
    YamlPresenterOutputError = object of Exception
-
    -
    -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. -  Source -
    -
    YamlStreamError = object of Exception
-
    -
    -Exception that may be raised by a YamlStream when the underlying backend raises an exception. The error that has occurred is available from parent. -  Source -
    -
    YamlConstructionError = object of YamlLoadingError
-
    -
    -Exception that may be raised when constructing data objects from a YamlStream. The fields line, column and lineContent are only available if the costructing proc also does parsing, because otherwise this information is not available to the costruction proc. -  Source -
    - -
    -
    -

    Vars

    -
    -
    serializationTagLibrary = initSerializationTagLibrary()
    -
    -

    -contains all local tags that are used for type serialization. Does not contain any of the specific default tags for sequences or maps, as those are not suited for Nim's static type system.

    -

    Should not be modified manually. Will be extended by serializable.

    - -  Source -
    - -
    -
    -

    Consts

    -
    -
    yTagExclamationMark: TagId = 0
    -
    -! non-specific tag -  Source -
    -
    yTagQuestionMark: TagId = 1
    -
    -? non-specific tag -  Source -
    -
    yTagString: TagId = 2
    -
    - -!!str tag -  Source -
    -
    yTagSequence: TagId = 3
    -
    - -!!seq tag -  Source -
    -
    yTagMapping: TagId = 4
    -
    - -!!map tag -  Source -
    -
    yTagNull: TagId = 5
    -
    - -!!null tag -  Source -
    -
    yTagBoolean: TagId = 6
    -
    - -!!bool tag -  Source -
    -
    yTagInteger: TagId = 7
    -
    - -!!int tag -  Source -
    -
    yTagFloat: TagId = 8
    -
    - -!!float tag -  Source -
    -
    yTagOrderedMap: TagId = 9
    -
    - -!!omap tag -  Source -
    -
    yTagPairs: TagId = 10
    -
    - -!!pairs tag -  Source -
    -
    yTagSet: TagId = 11
    -
    - -!!set tag -  Source -
    -
    yTagBinary: TagId = 12
    -
    - -!!binary tag -  Source -
    -
    yTagMerge: TagId = 13
    -
    - -!!merge tag -  Source -
    -
    yTagTimestamp: TagId = 14
    -
    - -!!timestamp tag -  Source -
    -
    yTagValue: TagId = 15
    -
    - -!!value tag -  Source -
    -
    yTagYaml: TagId = 16
    -
    - -!!yaml tag -  Source -
    -
    yTagNimField: TagId = 100
    -
    - -This tag is used in serialization for the name of a field of an object. It may contain any string scalar that is a valid Nim symbol. -  Source -
    -
    yTagNimNilString: TagId = 101
    -
    -for strings that are nil -  Source -
    -
    yTagNimNilSeq: TagId = 102
    -
    - -for seqs that are nil. This tag is used regardless of the seq's generic type parameter. -  Source -
    -
    yFirstCustomTagId: TagId = 1000
    -
    - -The first TagId which should be assigned to an URI that does not exist in the YamlTagLibrary which is used for parsing. -  Source -
    -
    yAnchorNone: AnchorId = -1
    -
    - -yielded when no anchor was defined for a YAML node -  Source -
    -
    yamlTagRepositoryPrefix = "tag:yaml.org,2002:"
    -
    - -  Source -
    -
    defaultPresentationOptions = PresentationOptions(style: psDefault,
-    indentationStep: 2, newlines: nlOSDefault)
    -
    - -  Source -
    -
    yTagNimChar = 100
    -
    - -  Source -
    -
    yTagNimInt8 = 101
    -
    - -  Source -
    -
    yTagNimInt16 = 102
    -
    - -  Source -
    -
    yTagNimInt32 = 103
    -
    - -  Source -
    -
    yTagNimInt64 = 104
    -
    - -  Source -
    -
    yTagNimUInt8 = 105
    -
    - -  Source -
    -
    yTagNimUInt16 = 106
    -
    - -  Source -
    -
    yTagNimUInt32 = 107
    -
    - -  Source -
    -
    yTagNimUInt64 = 108
    -
    - -  Source -
    -
    yTagNimFloat32 = 109
    -
    - -  Source -
    -
    yTagNimFloat64 = 110
    -
    - -  Source -
    - -
    -
    -

    Procs

    -
    -
    proc `==`(left, right: TagId): bool {.borrow.}
    -
    - -  Source -
    -
    proc hash(id: TagId): Hash {.borrow.}
    -
    - -  Source -
    -
    proc `==`(left, right: AnchorId): bool {.borrow.}
    -
    - -  Source -
    -
    proc `$`(id: AnchorId): string {.borrow.}
    -
    - -  Source -
    -
    proc hash(id: AnchorId): Hash {.borrow.}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[char]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[int8]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[int16]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[int32]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[int64]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[uint8]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[uint16]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[uint32]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[uint64]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[float32]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[float64]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc `$`(id: TagId): string {.raises: [], tags: [].}
    -
    - -  Source -
    -
    proc initTagLibrary(): TagLibrary {.raises: [], tags: [].}
    -
    -initializes the tags table and sets nextCustomTagId to yFirstCustomTagId. -  Source -
    -
    proc registerUri(tagLib: TagLibrary; uri: string): TagId {.raises: [], tags: [].}
    -
    -registers a custom tag URI with a TagLibrary. The URI will get the TagId nextCustomTagId, which will be incremented. -  Source -
    -
    proc uri(tagLib: TagLibrary; id: TagId): string {.raises: [KeyError], tags: [].}
    -
    -retrieve the URI a TagId maps to. -  Source -
    -
    proc initFailsafeTagLibrary(): TagLibrary {.raises: [], tags: [].}
    -
    -Contains only:
    • !
      • -
    • ?
      • -
    • !!str
      • -
    • !!map
      • -
    • !!seq
      • -
    - -  Source -
    -
    proc initCoreTagLibrary(): TagLibrary {.raises: [], tags: [].}
    -
    -Contains everything in initFailsafeTagLibrary plus:
    • !!null
      • -
    • !!bool
      • -
    • !!int
      • -
    • !!float
      • -
    - -  Source -
    -
    proc initExtendedTagLibrary(): TagLibrary {.raises: [], tags: [].}
    -
    -Contains everything from initCoreTagLibrary plus:
    • !!omap
      • -
    • !!pairs
      • -
    • !!set
      • -
    • !!binary
      • -
    • !!merge
      • -
    • !!timestamp
      • -
    • !!value
      • -
    • !!yaml
      • -
    - -  Source -
    -
    proc `==`(left: YamlStreamEvent; right: YamlStreamEvent): bool {.raises: [], tags: [].}
    -
    -compares all existing fields of the given items -  Source -
    -
    proc `$`(event: YamlStreamEvent): string {.raises: [], tags: [].}
    -
    -outputs a human-readable string describing the given event -  Source -
    -
    proc tag(event: YamlStreamEvent): TagId {.raises: [FieldError], tags: [].}
    -
    - -  Source -
    -
    proc startDocEvent(): YamlStreamEvent {.inline, raises: [], tags: [].}
    -
    - -  Source -
    -
    proc endDocEvent(): YamlStreamEvent {.inline, raises: [], tags: [].}
    -
    - -  Source -
    -
    proc startMapEvent(tag: TagId = yTagQuestionMark; anchor: AnchorId = yAnchorNone): YamlStreamEvent {.
-    inline, raises: [], tags: [].}
    -
    - -  Source -
    -
    proc endMapEvent(): YamlStreamEvent {.inline, raises: [], tags: [].}
    -
    - -  Source -
    -
    proc startSeqEvent(tag: TagId = yTagQuestionMark; anchor: AnchorId = yAnchorNone): YamlStreamEvent {.
-    inline, raises: [], tags: [].}
    -
    - -  Source -
    -
    proc endSeqEvent(): YamlStreamEvent {.inline, raises: [], tags: [].}
    -
    - -  Source -
    -
    proc scalarEvent(content: string = ""; tag: TagId = yTagQuestionMark;
-                anchor: AnchorId = yAnchorNone): YamlStreamEvent {.inline, raises: [],
-    tags: [].}
    -
    - -  Source -
    -
    proc aliasEvent(anchor: AnchorId): YamlStreamEvent {.inline, raises: [], tags: [].}
    -
    - -  Source -
    -
    proc constructJson(s: var YamlStream): seq[JsonNode] {.
-    raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect].}
    -
    -

    Construct an in-memory JSON tree from a YAML event stream. The stream may not contain any tags apart from those in coreTagLibrary. Anchors and aliases will be resolved. Maps in the input must not contain non-scalars as keys. Each element of the result represents one document in the YAML stream.

    -

    Warning: The special float values [+-]Inf and NaN will be parsed into Nim's JSON structure without error. However, they cannot be rendered to a JSON character stream, because these values are not part of the JSON specification. Nim's JSON implementation currently does not check for these values and will output invalid JSON when rendering one of these values into a JSON character stream.

    - -  Source -
    -
    proc loadToJson(s: Stream): seq[JsonNode] {.raises: [], tags: [RootEffect].}
    -
    -Uses YamlParser and constructJson to construct an in-memory JSON tree from a YAML character stream. -  Source -
    -
    proc defineOptions(style: PresentationStyle = psDefault; indentationStep: int = 2;
-                  newlines: NewLineStyle = nlOSDefault;
-                  outputVersion: OutputYamlVersion = ov1_2): PresentationOptions {.
-    raises: [], tags: [].}
    -
    -Define a set of options for presentation. Convenience proc that requires you to only set those values that should not equal the default. -  Source -
    -
    proc present(s: var YamlStream; target: Stream; tagLib: TagLibrary;
-            options: PresentationOptions = defaultPresentationOptions) {.raises: [
-    YamlPresenterJsonError, YamlPresenterOutputError, YamlStreamError],
-    tags: [RootEffect, WriteIOEffect].}
    -
    -Convert s to a YAML character stream and write it to target. -  Source -
    -
    proc transform(input: Stream; output: Stream;
-              options: PresentationOptions = defaultPresentationOptions) {.raises: [
-    IOError, YamlParserError, YamlPresenterJsonError, YamlPresenterOutputError],
-    tags: [RootEffect, WriteIOEffect].}
    -
    -Parser input as YAML character stream and then dump it to output while resolving non-specific tags to the ones in the YAML core tag library. -  Source -
    -
    proc guessType(scalar: string): TypeHint {.raises: [], tags: [].}
    -
    -Parse scalar string according to the RegEx table documented at TypeHint. -  Source -
    -
    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 getLineNumber(p: YamlParser): int {.raises: [], tags: [].}
    -
    -Get the line number (1-based) of the recently yielded parser token. Useful for error reporting at later loading stages. -  Source -
    -
    proc getColNumber(p: YamlParser): int {.raises: [], tags: [].}
    -
    -Get the column number (1-based) of the recently yielded parser token. Useful for error reporting at later parsing stages. -  Source -
    -
    proc getLineContent(p: YamlParser; marker: bool = true): string {.raises: [], tags: [].}
    -
    -Get the content of the input line containing the recently yielded parser token. Useful for error reporting at later parsing stages. The line will be terminated by "\n". If marker is true, a second line will be returned containing a ^ at the position of the recent parser token. -  Source -
    -
    proc parse(p: YamlParser; s: Stream): YamlStream {.raises: [],
-    tags: [RootEffect, ReadIOEffect].}
    -
    -Parse the given stream as YAML character stream. -  Source -
    -
    proc initYamlStream(backend: iterator (): YamlStreamEvent): YamlStream {.raises: [],
-    tags: [].}
    -
    -Creates a new YamlStream that uses the given iterator as backend. -  Source -
    -
    proc next(s: var YamlStream): YamlStreamEvent {.raises: [YamlStreamError],
-    tags: [RootEffect].}
    -
    -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. -  Source -
    -
    proc peek(s: var YamlStream): YamlStreamEvent {.raises: [YamlStreamError],
-    tags: [RootEffect].}
    -
    -Get the next item of the stream without advancing the stream. Requires finished(s) == true. Handles exceptions of the backend like next(). -  Source -
    -
    proc peek=(s: var YamlStream; value: YamlStreamEvent) {.raises: [], tags: [].}
    -
    -Set the next item of the stream. Will replace a previously peeked item, if one exists. -  Source -
    -
    proc finished(s: var YamlStream): bool {.raises: [YamlStreamError], tags: [RootEffect].}
    -
    -true if no more items are available in the stream. Handles exceptions of the backend like next(). -  Source -
    -
    proc newConstructionContext(): ConstructionContext {.raises: [], tags: [].}
    -
    - -  Source -
    -
    proc newSerializationContext(s: AnchorStyle): SerializationContext {.raises: [],
-    tags: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[string]): TagId {.inline, noSideEffect, raises: [].}
    -
    - -  Source -
    -
    proc constructObject(s: var YamlStream; c: ConstructionContext; result: var string) {.
-    raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect].}
    -
    -costructs a string from a YAML scalar -  Source -
    -
    proc representObject(value: string; ts: TagStyle; c: SerializationContext; tag: TagId): RawYamlStream {.
-    raises: [], tags: [].}
    -
    -represents a string as YAML scalar -  Source -
    -
    proc constructObject[T: int8 | int16 | int32 | int64](s: var YamlStream;
-    c: ConstructionContext; result: var T) {.raises: [YamlConstructionError,
-    YamlStreamError].}
    -
    -constructs an integer value from a YAML scalar -  Source -
    -
    proc constructObject(s: var YamlStream; c: ConstructionContext; result: var int) {.
-    raises: [YamlConstructionError, YamlStreamError], inline, tags: [RootEffect].}
    -
    -constructs an integer of architecture-defined length by loading it into int32 and then converting it. -  Source -
    -
    proc representObject[T: int8 | int16 | int32 | int64](value: T; ts: TagStyle;
-    c: SerializationContext; tag: TagId): RawYamlStream {.raises: [].}
    -
    -represents an integer value as YAML scalar -  Source -
    -
    proc representObject(value: int; tagStyle: TagStyle; c: SerializationContext;
-                    tag: TagId): RawYamlStream {.raises: [], inline, tags: [].}
    -
    -represent an integer of architecture-defined length by casting it to int32. on 64-bit systems, this may cause a type conversion error. -  Source -
    -
    proc constructObject[T: uint8 | uint16 | uint32 | uint64](s: var YamlStream;
-    c: ConstructionContext; result: var T) {.raises: [YamlConstructionError,
-    YamlStreamError].}
    -
    -construct an unsigned integer value from a YAML scalar -  Source -
    -
    proc constructObject(s: var YamlStream; c: ConstructionContext; result: var uint) {.
-    raises: [YamlConstructionError, YamlStreamError], inline, tags: [RootEffect].}
    -
    -represent an unsigned integer of architecture-defined length by loading it into uint32 and then converting it. -  Source -
    -
    proc representObject[T: uint8 | uint16 | uint32 | uint64](value: T; ts: TagStyle;
-    c: SerializationContext; tag: TagId): RawYamlStream {.raises: [].}
    -
    -represents an unsigned integer value as YAML scalar -  Source -
    -
    proc representObject(value: uint; ts: TagStyle; c: SerializationContext; tag: TagId): RawYamlStream {.
-    raises: [], inline, tags: [].}
    -
    -represent an unsigned integer of architecture-defined length by casting it to int32. on 64-bit systems, this may cause a type conversion error. -  Source -
    -
    proc constructObject[T: float | float32 | float64](s: var YamlStream;
-    c: ConstructionContext; result: var T) {.raises: [YamlConstructionError,
-    YamlStreamError].}
    -
    -construct a float value from a YAML scalar -  Source -
    -
    proc representObject[T: float | float32 | float64](value: T; ts: TagStyle;
-    c: SerializationContext; tag: TagId): RawYamlStream {.raises: [].}
    -
    -represents a float value as YAML scalar -  Source -
    -
    proc yamlTag[](T: typedesc[bool]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc constructObject(s: var YamlStream; c: ConstructionContext; result: var bool) {.
-    raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect].}
    -
    -constructs a bool value from a YAML scalar -  Source -
    -
    proc representObject(value: bool; ts: TagStyle; c: SerializationContext; tag: TagId): RawYamlStream {.
-    raises: [], tags: [].}
    -
    -represents a bool value as a YAML scalar -  Source -
    -
    proc constructObject(s: var YamlStream; c: ConstructionContext; result: var char) {.
-    raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect].}
    -
    -constructs a char value from a YAML scalar -  Source -
    -
    proc representObject(value: char; ts: TagStyle; c: SerializationContext; tag: TagId): RawYamlStream {.
-    raises: [], tags: [].}
    -
    -represents a char value as YAML scalar -  Source -
    -
    proc yamlTag[I](T: typedesc[seq[I]]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[I](T: typedesc[set[I]]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc constructObject[T](s: var YamlStream; c: ConstructionContext; result: var seq[T]) {.
-    raises: [YamlConstructionError, YamlStreamError].}
    -
    -constructs a Nim seq from a YAML sequence -  Source -
    -
    proc constructObject[T](s: var YamlStream; c: ConstructionContext; result: var set[T]) {.
-    raises: [YamlConstructionError, YamlStreamError].}
    -
    -constructs a Nim seq from a YAML sequence -  Source -
    -
    proc representObject[T](value: seq[T] | set[T]; ts: TagStyle; c: SerializationContext;
-                       tag: TagId): RawYamlStream {.raises: [].}
    -
    -represents a Nim seq as YAML sequence -  Source -
    -
    proc yamlTag[I, V](T: typedesc[array[I, V]]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc constructObject[I, T](s: var YamlStream; c: ConstructionContext;
-                         result: var array[I, T]) {.
-    raises: [YamlConstructionError, YamlStreamError].}
    -
    -constructs a Nim array from a YAML sequence -  Source -
    -
    proc representObject[I, T](value: array[I, T]; ts: TagStyle; c: SerializationContext;
-                         tag: TagId): RawYamlStream {.raises: [].}
    -
    -represents a Nim array as YAML sequence -  Source -
    -
    proc yamlTag[K, V](T: typedesc[Table[K, V]]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc constructObject[K, V](s: var YamlStream; c: ConstructionContext;
-                         result: var Table[K, V]) {.
-    raises: [YamlConstructionError, YamlStreamError].}
    -
    -constructs a Nim Table from a YAML mapping -  Source -
    -
    proc representObject[K, V](value: Table[K, V]; ts: TagStyle; c: SerializationContext;
-                         tag: TagId): RawYamlStream {.raises: [].}
    -
    -represents a Nim Table as YAML mapping -  Source -
    -
    proc yamlTag[K, V](T: typedesc[OrderedTable[K, V]]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc constructObject[K, V](s: var YamlStream; c: ConstructionContext;
-                         result: var OrderedTable[K, V]) {.
-    raises: [YamlConstructionError, YamlStreamError].}
    -
    -constructs a Nim OrderedTable from a YAML mapping -  Source -
    -
    proc representObject[K, V](value: OrderedTable[K, V]; ts: TagStyle;
-                         c: SerializationContext; tag: TagId): RawYamlStream {.
-    raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[object | enum]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc yamlTag[](T: typedesc[tuple]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc constructObject[O: object | tuple](s: var YamlStream; c: ConstructionContext;
-                                    result: var O) {.
-    raises: [YamlConstructionError, YamlStreamError].}
    -
    -constructs a Nim object or tuple from a YAML mapping -  Source -
    -
    proc representObject[O: object | tuple](value: O; ts: TagStyle; c: SerializationContext;
-                                    tag: TagId): RawYamlStream {.raises: [].}
    -
    -represents a Nim object or tuple as YAML mapping -  Source -
    -
    proc constructObject[O: enum](s: var YamlStream; c: ConstructionContext; result: var O) {.
-    raises: [YamlConstructionError, YamlStreamError].}
    -
    -constructs a Nim enum from a YAML scalar -  Source -
    -
    proc representObject[O: enum](value: O; ts: TagStyle; c: SerializationContext;
-                            tag: TagId): RawYamlStream {.raises: [].}
    -
    -represents a Nim enum as YAML scalar -  Source -
    -
    proc yamlTag[O](T: typedesc[ref O]): TagId {.inline, raises: [].}
    -
    - -  Source -
    -
    proc constructChild[T](s: var YamlStream; c: ConstructionContext; result: var T) {.
-    raises: [YamlConstructionError, YamlStreamError].}
    -
    -Constructs an arbitrary Nim value from a part of a YAML stream. The stream will advance until after the finishing token that was used for constructing the value. The ConstructionContext is needed for potential child objects which may be refs. -  Source -
    -
    proc constructChild(s: var YamlStream; c: ConstructionContext; result: var string) {.
-    raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect].}
    -
    -Constructs a Nim value that is a string from a part of a YAML stream. This specialization takes care of possible nil strings. -  Source -
    -
    proc constructChild[T](s: var YamlStream; c: ConstructionContext; result: var seq[T]) {.
-    raises: [YamlConstructionError, YamlStreamError].}
    -
    -Constructs a Nim value that is a string from a part of a YAML stream. This specialization takes care of possible nil seqs. -  Source -
    -
    proc constructChild[O](s: var YamlStream; c: ConstructionContext; result: var ref O) {.
-    raises: [YamlConstructionError, YamlStreamError].}
    -
    -Constructs an arbitrary Nim value from a part of a YAML stream. The stream will advance until after the finishing token that was used for constructing the value. The object may be constructed from an alias node which will be resolved using the ConstructionContext. -  Source -
    -
    proc representChild(value: string; ts: TagStyle; c: SerializationContext): RawYamlStream {.
-    inline, raises: [], tags: [].}
    -
    -Represents a Nim string. Supports nil strings. -  Source -
    -
    proc representChild[T](value: seq[T]; ts: TagStyle; c: SerializationContext): RawYamlStream
    -
    - -  Source -
    -
    proc representChild[O](value: ref O; ts: TagStyle; c: SerializationContext): RawYamlStream {.
-    raises: [].}
    -
    -Represents an arbitrary Nim reference value as YAML object. The object may be represented as alias node if it is already present in the SerializationContext. -  Source -
    -
    proc representChild[O](value: O; ts: TagStyle; c: SerializationContext): RawYamlStream {.
-    raises: [].}
    -
    -Represents an arbitrary Nim object as YAML object. -  Source -
    -
    proc construct[T](s: var YamlStream; target: var T) {.
-    raises: [YamlConstructionError, YamlStreamError].}
    -
    -Constructs a Nim value from a YAML stream. -  Source -
    -
    proc load[K](input: Stream; target: var K) {.raises: [YamlConstructionError, IOError,
-    YamlParserError].}
    -
    -Loads a Nim value from a YAML character stream. -  Source -
    -
    proc represent[T](value: T; ts: TagStyle = tsRootOnly; a: AnchorStyle = asTidy): YamlStream {.
-    raises: [].}
    -
    -Represents a Nim value as YamlStream -  Source -
    -
    proc dump[K](value: K; target: Stream; tagStyle: TagStyle = tsRootOnly;
-            anchorStyle: AnchorStyle = asTidy;
-            options: PresentationOptions = defaultPresentationOptions) {.
-    raises: [YamlPresenterJsonError, YamlPresenterOutputError].}
    -
    -Dump a Nim value as YAML character stream. -  Source -
    -
    proc newYamlNode(content: string; tag: string = "?"): YamlNode {.raises: [], tags: [].}
    -
    - -  Source -
    -
    proc newYamlNode(children: openArray[YamlNode]; tag: string = "?"): YamlNode {.
-    raises: [], tags: [].}
    -
    - -  Source -
    -
    proc newYamlNode(pairs: openArray[tuple[key, value: YamlNode]]; tag: string = "?"): YamlNode {.
-    raises: [], tags: [].}
    -
    - -  Source -
    -
    proc initYamlDoc(root: YamlNode): YamlDocument {.raises: [], tags: [].}
    -
    - -  Source -
    -
    proc compose(s: var YamlStream; tagLib: TagLibrary): YamlDocument {.
-    raises: [YamlStreamError, YamlConstructionError], tags: [RootEffect].}
    -
    - -  Source -
    -
    proc loadDOM(s: Stream): YamlDocument {.raises: [IOError, YamlParserError,
-    YamlConstructionError], tags: [RootEffect, ReadIOEffect].}
    -
    - -  Source -
    -
    proc serialize(doc: YamlDocument; tagLib: TagLibrary; a: AnchorStyle = asTidy): YamlStream {.
-    raises: [], tags: [RootEffect].}
    -
    - -  Source -
    -
    proc dumpDOM(doc: YamlDocument; target: Stream; anchorStyle: AnchorStyle = asTidy;
-            options: PresentationOptions = defaultPresentationOptions) {.
-    raises: [YamlPresenterJsonError, YamlPresenterOutputError],
-    tags: [RootEffect, WriteIOEffect].}
    -
    -Dump a YamlDocument as YAML character stream. -  Source -
    - -
    -
    -

    Iterators

    -
    -
    iterator items(s: var YamlStream): YamlStreamEvent {.raises: [YamlStreamError],
-    tags: [RootEffect].}
    -
    -Iterate over all items of the stream. You may not use peek() on the stream while iterating. -  Source -
    - -
    -
    -

    Templates

    -
    -
    template setTagUri[](t: typedesc; uri: string): stmt
    -
    -Associate the given uri with a certain type. This uri is used as YAML tag when loading and dumping values of this type. -  Source -
    -
    template setTagUri[](t: typedesc; uri: string; idName: expr): stmt
    -
    -Like setTagUri, but lets you choose a symbol for the TagId of the uri. This is only necessary if you want to implement serialization / construction yourself. -  Source -
    -
    template markAsImplicit[](t: typedesc): stmt
    -
    -Mark a variant object type as implicit. This requires the type to consist of nothing but a case expression and each branch of the case expression containing exactly one field - with the exception that one branch may contain zero fields. -  Source -
    -
    template presentTag[](t: typedesc; ts: TagStyle): TagId
    -
    -Get the TagId that represents the given type in the given style -  Source -
    -
    template constructScalarItem[](s: var YamlStream; i: expr; t: typedesc; content: untyped)
    -
    -Helper template for implementing constructObject for types that are constructed from a scalar. i is the identifier that holds the scalar as YamlStreamEvent in the content. Exceptions raised in the content will be automatically catched and wrapped in YamlConstructionError, which will then be raised. -  Source -
    - +yaml/dom, yaml/hints, yaml/parser, yaml/presenter, yaml/serialization, yaml/stream, yaml/taglib, yaml/tojson
    @@ -2113,7 +90,7 @@ class="link-seesrc" target="_blank">Source

    - Made with Nim. Generated: 2016-06-08 21:28:44 UTC + Made with Nim. Generated: 2016-10-01 15:20:03 UTC