2016-02-27 12:09:50 +00:00
|
|
|
# NimYAML - YAML implementation in Nim
|
2016-09-21 19:20:57 +00:00
|
|
|
# (c) Copyright 2016 Felix Krause
|
2016-02-27 12:09:50 +00:00
|
|
|
#
|
|
|
|
# See the file "copying.txt", included in this
|
|
|
|
# distribution, for details about the copyright.
|
|
|
|
|
2016-09-21 19:20:57 +00:00
|
|
|
## ===============
|
|
|
|
## Module yaml.dom
|
|
|
|
## ===============
|
|
|
|
##
|
|
|
|
## This is the DOM API, which enables you to load YAML into a tree-like
|
|
|
|
## structure. It can also dump the structure back to YAML. Formally, it
|
|
|
|
## represents the *Representation Graph* as defined in the YAML specification.
|
|
|
|
##
|
2016-11-28 19:17:04 +00:00
|
|
|
## The main interface of this API are ``loadDom`` and ``dumpDom``. The other
|
2016-09-21 19:20:57 +00:00
|
|
|
## exposed procs are low-level and useful if you want to load or generate parts
|
|
|
|
## of a ``YamlStream``.
|
2016-11-28 19:17:04 +00:00
|
|
|
##
|
|
|
|
## The ``YamlNode`` objects in the DOM can be used similarly to the ``JsonNode``
|
|
|
|
## objects of Nim's `json module <http://nim-lang.org/docs/json.html>`_.
|
2016-09-21 19:20:57 +00:00
|
|
|
|
2016-11-28 19:17:04 +00:00
|
|
|
import tables, streams, hashes, sets, strutils
|
2017-02-06 19:39:04 +00:00
|
|
|
import stream, taglib, serialization, private/internal, parser,
|
2016-09-20 19:53:38 +00:00
|
|
|
presenter
|
|
|
|
|
|
|
|
type
|
|
|
|
YamlNodeKind* = enum
|
|
|
|
yScalar, yMapping, ySequence
|
|
|
|
|
|
|
|
YamlNode* = ref YamlNodeObj not nil
|
|
|
|
## Represents a node in a ``YamlDocument``.
|
|
|
|
|
|
|
|
YamlNodeObj* = object
|
|
|
|
tag*: string
|
|
|
|
case kind*: YamlNodeKind
|
|
|
|
of yScalar: content*: string
|
2016-11-28 19:17:04 +00:00
|
|
|
of ySequence: elems*: seq[YamlNode]
|
|
|
|
of yMapping: fields*: TableRef[YamlNode, YamlNode]
|
|
|
|
# compiler does not like Table[YamlNode, YamlNode]
|
2016-09-20 19:53:38 +00:00
|
|
|
|
|
|
|
YamlDocument* = object
|
|
|
|
## Represents a YAML document.
|
|
|
|
root*: YamlNode
|
|
|
|
|
2016-11-28 19:17:04 +00:00
|
|
|
proc hash*(o: YamlNode): Hash =
|
|
|
|
result = o.tag.hash
|
|
|
|
case o.kind
|
|
|
|
of yScalar: result = result !& o.content.hash
|
|
|
|
of yMapping:
|
|
|
|
for key, value in o.fields.pairs:
|
|
|
|
result = result !& key.hash !& value.hash
|
|
|
|
of ySequence:
|
|
|
|
for item in o.elems:
|
|
|
|
result = result !& item.hash
|
|
|
|
result = !$result
|
|
|
|
|
|
|
|
proc eqImpl(x, y: YamlNode, alreadyVisited: var HashSet[pointer]): bool =
|
|
|
|
template compare(a, b: YamlNode) {.dirty.} =
|
|
|
|
if cast[pointer](a) != cast[pointer](b):
|
|
|
|
if cast[pointer](a) in alreadyVisited and
|
|
|
|
cast[pointer](b) in alreadyVisited:
|
|
|
|
# prevent infinite loop!
|
|
|
|
return false
|
|
|
|
elif a != b: return false
|
|
|
|
|
|
|
|
if x.kind != y.kind or x.tag != y.tag: return false
|
|
|
|
alreadyVisited.incl(cast[pointer](x))
|
|
|
|
alreadyVisited.incl(cast[pointer](y))
|
|
|
|
case x.kind
|
|
|
|
of yScalar: result = x.content == y.content
|
|
|
|
of ySequence:
|
|
|
|
if x.elems.len != y.elems.len: return false
|
|
|
|
for i in 0..<x.elems.len:
|
|
|
|
compare(x.elems[i], y.elems[i])
|
|
|
|
of yMapping:
|
|
|
|
if x.fields.len != y.fields.len: return false
|
|
|
|
for xKey, xValue in x.fields.pairs:
|
|
|
|
let xKeyVisited = cast[pointer](xKey) in alreadyVisited
|
|
|
|
var matchingValue: ref YamlNodeObj = nil
|
|
|
|
for yKey, yValue in y.fields.pairs:
|
|
|
|
if cast[pointer](yKey) != cast[pointer](xKey):
|
|
|
|
if cast[pointer](yKey) in alreadyVisited and xKeyVisited:
|
|
|
|
# prevent infinite loop!
|
|
|
|
continue
|
|
|
|
if xKey == yKey:
|
|
|
|
matchingValue = yValue
|
|
|
|
break
|
|
|
|
else:
|
|
|
|
matchingValue = yValue
|
|
|
|
break
|
|
|
|
if isNil(matchingValue): return false
|
|
|
|
compare(xValue, matchingValue)
|
|
|
|
|
|
|
|
proc `==`*(x, y: YamlNode): bool =
|
|
|
|
var alreadyVisited = initSet[pointer]()
|
|
|
|
result = eqImpl(x, y, alreadyVisited)
|
|
|
|
|
|
|
|
proc `$`*(n: YamlNode): string =
|
|
|
|
result = "!<" & n.tag & "> "
|
|
|
|
case n.kind
|
|
|
|
of yScalar: result.add(escape(n.content))
|
|
|
|
of ySequence:
|
|
|
|
result.add('[')
|
|
|
|
for item in n.elems:
|
|
|
|
result.add($item)
|
|
|
|
result.add(", ")
|
|
|
|
result.setLen(result.len - 1)
|
|
|
|
result[^1] = ']'
|
|
|
|
of yMapping:
|
|
|
|
result.add('{')
|
|
|
|
for key, value in n.fields.pairs:
|
|
|
|
result.add($key)
|
|
|
|
result.add(": ")
|
|
|
|
result.add($value)
|
|
|
|
result.add(", ")
|
|
|
|
result.setLen(result.len - 1)
|
|
|
|
result[^1] = '}'
|
|
|
|
|
2016-02-22 20:56:30 +00:00
|
|
|
proc newYamlNode*(content: string, tag: string = "?"): YamlNode =
|
2016-04-03 09:45:48 +00:00
|
|
|
YamlNode(kind: yScalar, content: content, tag: tag)
|
2016-02-22 20:56:30 +00:00
|
|
|
|
2016-11-28 19:17:04 +00:00
|
|
|
proc newYamlNode*(elems: openarray[YamlNode], tag: string = "?"):
|
2016-04-02 15:48:22 +00:00
|
|
|
YamlNode =
|
2016-11-28 19:17:04 +00:00
|
|
|
YamlNode(kind: ySequence, elems: @elems, tag: tag)
|
2016-02-22 20:56:30 +00:00
|
|
|
|
2016-11-28 19:17:04 +00:00
|
|
|
proc newYamlNode*(fields: openarray[(YamlNode, YamlNode)],
|
2016-02-22 20:56:30 +00:00
|
|
|
tag: string = "?"): YamlNode =
|
2016-11-28 19:17:04 +00:00
|
|
|
YamlNode(kind: yMapping, fields: newTable(fields), tag: tag)
|
2016-02-22 20:56:30 +00:00
|
|
|
|
2016-04-02 15:48:22 +00:00
|
|
|
proc initYamlDoc*(root: YamlNode): YamlDocument = result.root = root
|
2016-02-22 20:56:30 +00:00
|
|
|
|
|
|
|
proc composeNode(s: var YamlStream, tagLib: TagLibrary,
|
|
|
|
c: ConstructionContext):
|
2016-04-02 15:48:22 +00:00
|
|
|
YamlNode {.raises: [YamlStreamError, YamlConstructionError].} =
|
2017-03-29 19:42:07 +00:00
|
|
|
template addAnchor(c: ConstructionContext, target: AnchorId): typed =
|
|
|
|
if target != yAnchorNone:
|
|
|
|
when defined(JS):
|
|
|
|
{.emit: [c, """.refs.set(""", target, ", ", result, ");"].}
|
|
|
|
else:
|
|
|
|
yAssert(not c.refs.hasKey(target))
|
|
|
|
c.refs[target] = cast[pointer](result)
|
|
|
|
|
2016-09-14 16:31:09 +00:00
|
|
|
var start: YamlStreamEvent
|
|
|
|
shallowCopy(start, s.next())
|
2016-04-02 15:48:22 +00:00
|
|
|
new(result)
|
|
|
|
try:
|
|
|
|
case start.kind
|
|
|
|
of yamlStartMap:
|
|
|
|
result.tag = tagLib.uri(start.mapTag)
|
|
|
|
result.kind = yMapping
|
2016-11-28 19:17:04 +00:00
|
|
|
result.fields = newTable[YamlNode, YamlNode]()
|
2016-04-02 15:48:22 +00:00
|
|
|
while s.peek().kind != yamlEndMap:
|
|
|
|
let
|
|
|
|
key = composeNode(s, tagLib, c)
|
|
|
|
value = composeNode(s, tagLib, c)
|
2016-11-28 19:17:04 +00:00
|
|
|
if result.fields.hasKeyOrPut(key, value):
|
|
|
|
raise newException(YamlConstructionError,
|
|
|
|
"Duplicate key: " & $key)
|
2016-04-02 15:48:22 +00:00
|
|
|
discard s.next()
|
2017-03-29 19:42:07 +00:00
|
|
|
addAnchor(c, start.mapAnchor)
|
2016-04-02 15:48:22 +00:00
|
|
|
of yamlStartSeq:
|
|
|
|
result.tag = tagLib.uri(start.seqTag)
|
|
|
|
result.kind = ySequence
|
2016-11-28 19:17:04 +00:00
|
|
|
result.elems = newSeq[YamlNode]()
|
2016-04-02 15:48:22 +00:00
|
|
|
while s.peek().kind != yamlEndSeq:
|
2016-11-28 19:17:04 +00:00
|
|
|
result.elems.add(composeNode(s, tagLib, c))
|
2017-03-29 19:42:07 +00:00
|
|
|
addAnchor(c, start.seqAnchor)
|
2016-04-02 15:48:22 +00:00
|
|
|
discard s.next()
|
|
|
|
of yamlScalar:
|
|
|
|
result.tag = tagLib.uri(start.scalarTag)
|
|
|
|
result.kind = yScalar
|
|
|
|
shallowCopy(result.content, start.scalarContent)
|
2017-03-29 19:42:07 +00:00
|
|
|
addAnchor(c, start.scalarAnchor)
|
2016-04-02 15:48:22 +00:00
|
|
|
of yamlAlias:
|
2017-03-29 19:42:07 +00:00
|
|
|
when defined(JS):
|
|
|
|
{.emit: [result, " = ", c, ".refs.get(", start.aliasTarget, ");"].}
|
|
|
|
else:
|
|
|
|
result = cast[YamlNode](c.refs[start.aliasTarget])
|
2016-08-09 18:47:22 +00:00
|
|
|
else: internalError("Malformed YamlStream")
|
2016-04-02 15:48:22 +00:00
|
|
|
except KeyError:
|
|
|
|
raise newException(YamlConstructionError,
|
|
|
|
"Wrong tag library: TagId missing")
|
2016-02-22 20:56:30 +00:00
|
|
|
|
|
|
|
proc compose*(s: var YamlStream, tagLib: TagLibrary): YamlDocument
|
2016-04-02 15:48:22 +00:00
|
|
|
{.raises: [YamlStreamError, YamlConstructionError].} =
|
|
|
|
var context = newConstructionContext()
|
2016-09-14 16:31:09 +00:00
|
|
|
var n: YamlStreamEvent
|
|
|
|
shallowCopy(n, s.next())
|
2016-08-10 18:42:44 +00:00
|
|
|
yAssert n.kind == yamlStartDoc
|
2016-04-02 15:48:22 +00:00
|
|
|
result.root = composeNode(s, tagLib, context)
|
2016-08-10 18:42:44 +00:00
|
|
|
n = s.next()
|
|
|
|
yAssert n.kind == yamlEndDoc
|
2016-02-22 20:56:30 +00:00
|
|
|
|
2016-11-28 19:17:04 +00:00
|
|
|
proc loadDom*(s: Stream | string): YamlDocument
|
2016-04-02 15:48:22 +00:00
|
|
|
{.raises: [IOError, YamlParserError, YamlConstructionError].} =
|
|
|
|
var
|
|
|
|
tagLib = initExtendedTagLibrary()
|
|
|
|
parser = newYamlParser(tagLib)
|
|
|
|
events = parser.parse(s)
|
|
|
|
try: result = compose(events, tagLib)
|
|
|
|
except YamlStreamError:
|
|
|
|
let e = getCurrentException()
|
|
|
|
if e.parent of YamlParserError:
|
|
|
|
raise (ref YamlParserError)(e.parent)
|
|
|
|
elif e.parent of IOError:
|
|
|
|
raise (ref IOError)(e.parent)
|
2016-08-09 18:47:22 +00:00
|
|
|
else: internalError("Unexpected exception: " & e.parent.repr)
|
2016-02-22 20:56:30 +00:00
|
|
|
|
|
|
|
proc serializeNode(n: YamlNode, c: SerializationContext, a: AnchorStyle,
|
2016-09-01 18:56:34 +00:00
|
|
|
tagLib: TagLibrary) {.raises: [].}=
|
2017-03-29 19:42:07 +00:00
|
|
|
var val = yAnchorNone
|
|
|
|
when defined(JS):
|
|
|
|
{.emit: ["""
|
|
|
|
if (""", a, " != ", asNone, " && ", c, ".refs.has(", n, """) {
|
|
|
|
""", val, " = ", c, ".refs.get(", n, """);
|
|
|
|
if (""", c, ".refs.get(", n, ") == ", yAnchorNone, ") {"].}
|
|
|
|
val = c.nextAnchorId
|
|
|
|
{.emit: [c, """.refs.set(""", n, """, """, val, """);"""].}
|
|
|
|
c.nextAnchorId = AnchorId(int(c.nextAnchorId) + 1)
|
|
|
|
{.emit: "}".}
|
|
|
|
c.put(aliasEvent(val))
|
2016-04-02 15:48:22 +00:00
|
|
|
return
|
2017-03-29 19:42:07 +00:00
|
|
|
{.emit: "}".}
|
|
|
|
else:
|
|
|
|
let p = cast[pointer](n)
|
|
|
|
if a != asNone and c.refs.hasKey(p):
|
|
|
|
val = c.refs.getOrDefault(p)
|
|
|
|
if val == yAnchorNone:
|
|
|
|
val = c.nextAnchorId
|
|
|
|
c.refs[p] = val
|
|
|
|
c.nextAnchorId = AnchorId(int(c.nextAnchorId) + 1)
|
|
|
|
c.put(aliasEvent(val))
|
|
|
|
return
|
2016-04-02 15:48:22 +00:00
|
|
|
var
|
|
|
|
tagId: TagId
|
|
|
|
anchor: AnchorId
|
2016-08-09 18:47:22 +00:00
|
|
|
if a == asAlways:
|
2017-03-29 19:42:07 +00:00
|
|
|
when defined(JS):
|
|
|
|
{.emit: [c, ".refs.set(", n, ", ", c.nextAnchorId, ");"].}
|
|
|
|
else:
|
|
|
|
c.refs[p] = c.nextAnchorId
|
2016-08-09 18:47:22 +00:00
|
|
|
c.nextAnchorId = AnchorId(int(c.nextAnchorId) + 1)
|
2017-03-29 19:42:07 +00:00
|
|
|
else:
|
|
|
|
when defined(JS):
|
|
|
|
{.emit: [c, ".refs.set(", n, ", ", yAnchorNone, ");"].}
|
|
|
|
else:
|
|
|
|
c.refs[p] = yAnchorNone
|
2016-08-09 18:47:22 +00:00
|
|
|
tagId = if tagLib.tags.hasKey(n.tag): tagLib.tags.getOrDefault(n.tag) else:
|
|
|
|
tagLib.registerUri(n.tag)
|
|
|
|
case a
|
|
|
|
of asNone: anchor = yAnchorNone
|
|
|
|
of asTidy: anchor = cast[AnchorId](n)
|
2017-03-29 19:42:07 +00:00
|
|
|
of asAlways: anchor = val
|
2016-09-19 17:33:29 +00:00
|
|
|
|
2016-09-01 18:56:34 +00:00
|
|
|
case n.kind
|
|
|
|
of yScalar: c.put(scalarEvent(n.content, tagId, anchor))
|
|
|
|
of ySequence:
|
|
|
|
c.put(startSeqEvent(tagId, anchor))
|
2016-11-28 19:17:04 +00:00
|
|
|
for item in n.elems:
|
2016-09-01 18:56:34 +00:00
|
|
|
serializeNode(item, c, a, tagLib)
|
|
|
|
c.put(endSeqEvent())
|
|
|
|
of yMapping:
|
|
|
|
c.put(startMapEvent(tagId, anchor))
|
2016-11-28 19:17:04 +00:00
|
|
|
for key, value in n.fields.pairs:
|
|
|
|
serializeNode(key, c, a, tagLib)
|
|
|
|
serializeNode(value, c, a, tagLib)
|
2016-09-01 18:56:34 +00:00
|
|
|
c.put(endMapEvent())
|
2016-02-22 20:56:30 +00:00
|
|
|
|
2016-08-17 20:50:37 +00:00
|
|
|
template processAnchoredEvent(target: untyped, c: SerializationContext): typed =
|
2017-03-29 19:42:07 +00:00
|
|
|
var anchorId: AnchorId
|
|
|
|
when defined(JS):
|
|
|
|
{.emit: [anchorId, " = ", c, ".refs.get(", target, ");"].}
|
|
|
|
else:
|
|
|
|
anchorId = c.refs.getOrDefault(cast[pointer](target))
|
2016-08-09 18:47:22 +00:00
|
|
|
if anchorId != yAnchorNone: target = anchorId
|
|
|
|
else: target = yAnchorNone
|
2016-02-22 20:56:30 +00:00
|
|
|
|
|
|
|
proc serialize*(doc: YamlDocument, tagLib: TagLibrary, a: AnchorStyle = asTidy):
|
2016-09-20 19:53:38 +00:00
|
|
|
YamlStream {.raises: [].} =
|
2016-04-02 15:48:22 +00:00
|
|
|
var
|
2016-09-01 18:56:34 +00:00
|
|
|
bys = newBufferYamlStream()
|
|
|
|
c = newSerializationContext(a, proc(e: YamlStreamEvent) {.raises: [].} =
|
2016-09-20 19:53:38 +00:00
|
|
|
bys.put(e)
|
2016-09-01 18:56:34 +00:00
|
|
|
)
|
|
|
|
c.put(startDocEvent())
|
|
|
|
serializeNode(doc.root, c, a, tagLib)
|
|
|
|
c.put(endDocEvent())
|
2016-04-02 15:48:22 +00:00
|
|
|
if a == asTidy:
|
2016-09-20 19:53:38 +00:00
|
|
|
for event in bys.mitems():
|
2016-09-01 18:56:34 +00:00
|
|
|
case event.kind
|
|
|
|
of yamlScalar: processAnchoredEvent(event.scalarAnchor, c)
|
|
|
|
of yamlStartMap: processAnchoredEvent(event.mapAnchor, c)
|
|
|
|
of yamlStartSeq: processAnchoredEvent(event.seqAnchor, c)
|
|
|
|
else: discard
|
|
|
|
result = bys
|
2016-02-22 20:56:30 +00:00
|
|
|
|
2016-11-28 19:17:04 +00:00
|
|
|
proc dumpDom*(doc: YamlDocument, target: Stream,
|
2016-02-26 20:55:59 +00:00
|
|
|
anchorStyle: AnchorStyle = asTidy,
|
|
|
|
options: PresentationOptions = defaultPresentationOptions)
|
2016-08-09 18:47:22 +00:00
|
|
|
{.raises: [YamlPresenterJsonError, YamlPresenterOutputError,
|
|
|
|
YamlStreamError].} =
|
2016-04-02 15:48:22 +00:00
|
|
|
## Dump a YamlDocument as YAML character stream.
|
|
|
|
var
|
|
|
|
tagLib = initExtendedTagLibrary()
|
|
|
|
events = serialize(doc, tagLib,
|
|
|
|
if options.style == psJson: asNone else: anchorStyle)
|
2016-08-09 18:47:22 +00:00
|
|
|
present(events, target, tagLib, options)
|
2016-11-28 19:17:04 +00:00
|
|
|
|
|
|
|
proc `[]`*(node: YamlNode, i: int): YamlNode =
|
|
|
|
## Get the node at index *i* from a sequence. *node* must be a *ySequence*.
|
|
|
|
assert node.kind == ySequence
|
|
|
|
node.elems[i]
|
|
|
|
|
|
|
|
proc `[]=`*(node: var YamlNode, i: int, val: YamlNode) =
|
|
|
|
## Set the node at index *i* of a sequence. *node* must be a *ySequence*.
|
|
|
|
assert node.kind == ySequence
|
|
|
|
node.elems[i] = val
|
|
|
|
|
|
|
|
proc `[]`*(node: YamlNode, key: YamlNode): YamlNode =
|
|
|
|
## Get the value for a key in a mapping. *node* must be a *yMapping*.
|
|
|
|
assert node.kind == yMapping
|
|
|
|
node.fields[key]
|
|
|
|
|
|
|
|
proc `[]=`*(node: YamlNode, key: YamlNode, value: YamlNode) =
|
|
|
|
## Set the value for a key in a mapping. *node* must be a *yMapping*.
|
|
|
|
node.fields[key] = value
|
|
|
|
|
|
|
|
proc `[]`*(node: YamlNode, key: string): YamlNode =
|
|
|
|
## Get the value for a string key in a mapping. *node* must be a *yMapping*.
|
|
|
|
## This searches for a scalar key with content *key* and either no explicit
|
|
|
|
## tag or the explicit tag ``!!str``.
|
|
|
|
assert node.kind == yMapping
|
|
|
|
var keyNode = YamlNode(kind: yScalar, tag: "!", content: key)
|
|
|
|
result = node.fields.getOrDefault(keyNode)
|
|
|
|
if isNil(result):
|
|
|
|
keyNode.tag = "?"
|
|
|
|
result = node.fields.getOrDefault(keyNode)
|
|
|
|
if isNil(result):
|
|
|
|
keyNode.tag = nimTag(yamlTagRepositoryPrefix & "str")
|
|
|
|
result = node.fields.getOrDefault(keyNode)
|
|
|
|
if isNil(result):
|
|
|
|
raise newException(KeyError, "No key " & escape(key) & " exists!")
|
|
|
|
|
|
|
|
proc len*(node: YamlNode): int =
|
|
|
|
## If *node* is a *yMapping*, return the number of key-value pairs. If *node*
|
|
|
|
## is a *ySequence*, return the number of elements. Else, return ``0``
|
|
|
|
case node.kind
|
|
|
|
of yMapping: result = node.fields.len
|
|
|
|
of ySequence: result = node.elems.len
|
|
|
|
of yScalar: result = 0
|
|
|
|
|
|
|
|
iterator items*(node: YamlNode): YamlNode =
|
|
|
|
## Iterates over all items of a sequence. *node* must be a *ySequence*.
|
|
|
|
assert node.kind == ySequence
|
|
|
|
for item in node.elems: yield item
|
|
|
|
|
|
|
|
iterator mitems*(node: var YamlNode): YamlNode =
|
|
|
|
## Iterates over all items of a sequence. *node* must be a *ySequence*.
|
|
|
|
## Values can be modified.
|
|
|
|
assert node.kind == ySequence
|
|
|
|
for item in node.elems.mitems: yield item
|
|
|
|
|
|
|
|
iterator pairs*(node: YamlNode): tuple[key, value: YamlNode] =
|
|
|
|
## Iterates over all key-value pairs of a mapping. *node* must be a
|
|
|
|
## *yMapping*.
|
|
|
|
assert node.kind == yMapping
|
|
|
|
for key, value in node.fields: yield (key, value)
|
|
|
|
|
|
|
|
iterator mpairs*(node: var YamlNode):
|
|
|
|
tuple[key: YamlNode, value: var YamlNode] =
|
|
|
|
## Iterates over all key-value pairs of a mapping. *node* must be a
|
|
|
|
## *yMapping*. Values can be modified.
|
|
|
|
doAssert node.kind == yMapping
|
|
|
|
for key, value in node.fields.mpairs: yield (key, value)
|