mirror of https://github.com/status-im/NimYAML.git
Improved documentation
This commit is contained in:
Felix Krause
parent
32c42054f7
commit
cb18c5cb9c
|
|
@ -23,7 +23,7 @@ task documentation, "Generate documentation":
|
||||||
exec r"nim doc2 -o:docout/yaml.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml"
|
exec r"nim doc2 -o:docout/yaml.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml"
|
||||||
exec r"nim doc2 -o:docout/serialization.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml/serialization.nim"
|
exec r"nim doc2 -o:docout/serialization.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml/serialization.nim"
|
||||||
exec r"nim rst2html -o:docout/index.html doc/index.txt"
|
exec r"nim rst2html -o:docout/index.html doc/index.txt"
|
||||||
exec "cp doc/docutils.css doc/style.css doc/testing.html docout"
|
exec "cp doc/docutils.css doc/style.css doc/testing.html doc/processing.svg docout"
|
||||||
setCommand "nop"
|
setCommand "nop"
|
||||||
|
|
||||||
task bench, "Benchmarking":
|
task bench, "Benchmarking":
|
||||||
|
|
|
||||||
|
|
@ -2,4 +2,18 @@
|
||||||
NimYAML
|
NimYAML
|
||||||
=======
|
=======
|
||||||
|
|
||||||
TBD: General information here. Possibly move text from yaml.html. Eat pizza.
|
Overview
|
||||||
|
========
|
||||||
|
|
||||||
|
**NimYAML** is a pure YAML implementation for Nim. It is able to read from and
|
||||||
|
write to YAML character streams, and to serialize from and construct to native
|
||||||
|
Nim types. It exclusively supports
|
||||||
|
`YAML 1.2 <#http://www.yaml.org/spec/1.2/spec.html>`_. NimYAML exposes all
|
||||||
|
processing steps defined by the YAML specification to the user, so it is
|
||||||
|
possible to customize the processing pipeline. The following diagram gives an
|
||||||
|
overview of NimYAML's features based on the YAML processing pipeline. The items
|
||||||
|
and terminology YAML defines is shown in black, NimYAML's implementation is
|
||||||
|
shown in red.
|
||||||
|
|
||||||
|
.. image:: processing.svg
|
||||||
|
:align: center
|
||||||
|
|
@ -0,0 +1,154 @@
|
||||||
|
<svg version="1.1"
|
||||||
|
baseProfile="full"
|
||||||
|
width="600" height="340"
|
||||||
|
xmlns="http://www.w3.org/2000/svg"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||||
|
<defs>
|
||||||
|
<marker id="Triangle" viewBox="0 0 10 10" refX="1" refY="5"
|
||||||
|
markerWidth="6" markerHeight="6" orient="auto">
|
||||||
|
<path d="M 0 0 L 10 5 L 0 10 z" />
|
||||||
|
</marker>
|
||||||
|
<g id="box">
|
||||||
|
<rect x="0" y="0" width="120" height="60" stroke="black" fill="white" stroke-width="2"/>
|
||||||
|
</g>
|
||||||
|
<g id="atomic-right-long">
|
||||||
|
<rect x="30" y="5" width="100" height="30" stroke="black" fill="white" stroke-width="1"/>
|
||||||
|
<path d="M 0 50 v -20 q 0 -10 10 -10 h 20" fill="transparent" stroke="black"/>
|
||||||
|
<path d="M 130 20 h 20 q 10 0 10 10" fill="transparent" stroke="black"/>
|
||||||
|
<line x1="160" y1="30" x2="160" y2="44" stroke="black" marker-end="url(#Triangle)"/>
|
||||||
|
</g>
|
||||||
|
<g id="atomic-right">
|
||||||
|
<rect x="30" y="5" width="80" height="30" stroke="black" fill="white" stroke-width="1"/>
|
||||||
|
<path d="M 5 50 v -20 q 0 -10 10 -10 h 15" fill="transparent" stroke="black"/>
|
||||||
|
<path d="M 110 20 h 15 q 10 0 10 10" fill="transparent" stroke="black"/>
|
||||||
|
<line x1="135" y1="30" x2="135" y2="44" stroke="black" marker-end="url(#Triangle)"/>
|
||||||
|
</g>
|
||||||
|
<g id="atomic-left-long">
|
||||||
|
<rect x="30" y="15" width="100" height="30" stroke="black" fill="white" stroke-width="1"/>
|
||||||
|
<line x1="0" y1="20" x2="0" y2="6" stroke="black" marker-end="url(#Triangle)"/>
|
||||||
|
<path d="M 0 20 q 0 10 10 10 h 20" fill="transparent" stroke="black"/>
|
||||||
|
<path d="M 130 30 h 20 q 10 0 10 -10 v -20" fill="transparent" stroke="black"/>
|
||||||
|
</g>
|
||||||
|
<g id="atomic-left">
|
||||||
|
<rect x="30" y="15" width="80" height="30" stroke="black" fill="white" stroke-width="1"/>
|
||||||
|
<line x1="5" y1="20" x2="5" y2="6" stroke="black" marker-end="url(#Triangle)"/>
|
||||||
|
<path d="M 5 20 q 0 10 10 10 h 15" fill="transparent" stroke="black"/>
|
||||||
|
<path d="M 110 30 h 15 q 10 0 10 -10 v -20" fill="transparent" stroke="black"/>
|
||||||
|
</g>
|
||||||
|
<g id="skipping-right">
|
||||||
|
<rect x="125" y="5" width="100" height="30" stroke="black" fill="white" stroke-width="1"/>
|
||||||
|
<path d="M 0 90 v -60 q 0 -10 10 -10 h 115" fill="transparent" stroke="black"/>
|
||||||
|
<path d="M 225 20 h 90 q 10 0 10 10" fill="transparent" stroke="black"/>
|
||||||
|
<line x1="325" y1="30" x2="325" y2="84" stroke="black" marker-end="url(#Triangle)"/>
|
||||||
|
</g>
|
||||||
|
<g id="skipping-left">
|
||||||
|
<rect x="125" y="55" width="100" height="30" stroke="black" fill="white" stroke-width="1"/>
|
||||||
|
<line x1="0" y1="60" x2="0" y2="6" stroke="black" marker-end="url(#Triangle)"/>
|
||||||
|
<path d="M 0 60 q 0 10 10 10 h 115" fill="transparent" stroke="black"/>
|
||||||
|
<path d="M 225 70 h 90 q 10 0 10 -10 v -60" fill="transparent" stroke="black"/>
|
||||||
|
</g>
|
||||||
|
<g id="whole-right">
|
||||||
|
<rect x="275" y="5" width="100" height="30" stroke="black" fill="white" stroke-width="1"/>
|
||||||
|
<line x1="5" y1="20" x2="275" y2="20" stroke="black" stroke-width="2"/>
|
||||||
|
<line x1="375" y1="20" x2="583" y2="20" stroke="black" stroke-width="2" marker-end="url(#Triangle)"/>
|
||||||
|
</g>
|
||||||
|
<g id="whole-left">
|
||||||
|
<rect x="275" y="5" width="100" height="30" stroke="black" fill="white" stroke-width="1"/>
|
||||||
|
<line x1="275" y1="20" x2="17" y2="20" stroke="black" stroke-width="2" marker-end="url(#Triangle)"/>
|
||||||
|
<line x1="375" y1="20" x2="595" y2="20" stroke="black" stroke-width="2"/>
|
||||||
|
</g>
|
||||||
|
</defs>
|
||||||
|
|
||||||
|
<line x1="145" y1="0" x2="145" y2="340" stroke="gray"/>
|
||||||
|
<text x="55" y="25" fill="gray">Application</text>
|
||||||
|
<text x="160" y="25" fill="gray">YAML</text>
|
||||||
|
|
||||||
|
<g id="boxes" text-anchor="middle" transform="translate(0 150)">
|
||||||
|
<g id="native" transform="translate(0 0)">
|
||||||
|
<use xlink:href="#box"/>
|
||||||
|
<text x="60" y="25" font-style="italic">Native</text>
|
||||||
|
<text x="60" y="45" font-weight="bold">Nim Types</text>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<g id="representation" transform="translate(170 0)">
|
||||||
|
<use xlink:href="#box"/>
|
||||||
|
<text x="60" y="25" font-style="italic">Representation</text>
|
||||||
|
<text x="60" y="45" font-weight="bold">not implemented</text>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<g id="serialization" transform="translate(320 0)">
|
||||||
|
<use xlink:href="#box"/>
|
||||||
|
<text x="60" y="25" font-style="italic">Serialization</text>
|
||||||
|
<a xlink:href="yaml.html#YamlStream" target="_top">
|
||||||
|
<text x="60" y="45" font-weight="bold">YamlStream</text>
|
||||||
|
</a>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<g id="presentation" transform="translate(470 0)">
|
||||||
|
<use xlink:href="#box"/>
|
||||||
|
<text x="60" y="25" font-style="italic">Presentation</text>
|
||||||
|
<a xlink:href="http://nim-lang.org/docs/streams.html#Stream" target="_top">
|
||||||
|
<text x="60" y="45" font-weight="bold">Stream</text>
|
||||||
|
</a>
|
||||||
|
</g>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<g id="atomics" text-anchor="middle" transform="translate(0 90)">
|
||||||
|
<g id="represent" transform="translate(65 10)">
|
||||||
|
<use xlink:href="#atomic-right-long"/>
|
||||||
|
<text x="80" y="25" font-style="italic">represent</text>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<g id="serialize" transform="translate(235 10)">
|
||||||
|
<use xlink:href="#atomic-right"/>
|
||||||
|
<text x="70" y="25" font-style="italic" font-weight="bold">serialize</text>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<g id="present" transform="translate(385 10)">
|
||||||
|
<use xlink:href="#atomic-right"/>
|
||||||
|
<a xlink:href="yaml.html#present,YamlStream,Stream,TagLibrary,PresentationStyle,int" target="_top">
|
||||||
|
<text x="70" y="25" font-style="italic" font-weight="bold">present</text>
|
||||||
|
</a>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<g id="construct" transform="translate(65 120)">
|
||||||
|
<use xlink:href="#atomic-left-long"/>
|
||||||
|
<text x="80" y="35" font-style="italic">construct</text>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<g id="compose" transform="translate(235 120)">
|
||||||
|
<use xlink:href="#atomic-left"/>
|
||||||
|
<text x="70" y="35" font-style="italic" font-weight="bold">compose</text>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<g id="parse" transform="translate(385 120)">
|
||||||
|
<use xlink:href="#atomic-left"/>
|
||||||
|
<a xlink:href="yaml.html#parse,YamlParser,Stream" target="_top">
|
||||||
|
<text x="70" y="35" font-style="italic" font-weight="bold">parse</text>
|
||||||
|
</a>
|
||||||
|
</g>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<g id="skipping-things" text-anchor="middle" transform="translate(0 50)">
|
||||||
|
<g id="skipping-represent" transform="translate(55 10)">
|
||||||
|
<use xlink:href="#skipping-right"/>
|
||||||
|
<text x="175" y="25" font-weight="bold">represent</text>
|
||||||
|
</g>
|
||||||
|
<g id="skipping-construct" transform="translate(55 160)">
|
||||||
|
<use xlink:href="#skipping-left"/>
|
||||||
|
<text x="175" y="75" font-weight="bold">construct</text>
|
||||||
|
</g>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<g id="whole-lines" text-anchor="middle" transform="translate(0 20)">
|
||||||
|
<g id="dump">
|
||||||
|
<use xlink:href="#whole-right"/>
|
||||||
|
<text x="325" y="25" font-style="italic" font-weight="bold">dump</text>
|
||||||
|
</g>
|
||||||
|
<g id="load" transform="translate(0 280)">
|
||||||
|
<use xlink:href="#whole-left"/>
|
||||||
|
<text x="325" y="25" font-style="italic" font-weight="bold">load</text>
|
||||||
|
</g>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
</svg>
|
||||||
|
After Width: | Height: | Size: 6.8 KiB |
19
yaml.nim
19
yaml.nim
|
|
@ -338,9 +338,6 @@ proc registerUri*(tagLib: TagLibrary, uri: string): TagId {.raises: [].}
|
||||||
proc uri*(tagLib: TagLibrary, id: TagId): string {.raises: [KeyError].}
|
proc uri*(tagLib: TagLibrary, id: TagId): string {.raises: [KeyError].}
|
||||||
## retrieve the URI a ``TagId`` maps to.
|
## retrieve the URI a ``TagId`` maps to.
|
||||||
|
|
||||||
# these should be consts, but the Nim VM still has problems handling tables
|
|
||||||
# properly, so we use let instead.
|
|
||||||
|
|
||||||
proc initFailsafeTagLibrary*(): TagLibrary {.raises: [].}
|
proc initFailsafeTagLibrary*(): TagLibrary {.raises: [].}
|
||||||
## Contains only:
|
## Contains only:
|
||||||
## - ``!``
|
## - ``!``
|
||||||
|
|
@ -366,16 +363,32 @@ proc initExtendedTagLibrary*(): TagLibrary {.raises: [].}
|
||||||
## - ``!!yaml``
|
## - ``!!yaml``
|
||||||
|
|
||||||
proc guessType*(scalar: string): TypeHint {.raises: [].}
|
proc guessType*(scalar: string): TypeHint {.raises: [].}
|
||||||
|
## Parse scalar string according to the RegEx table documented at
|
||||||
|
## `TypeHint <#TypeHind>`_.
|
||||||
|
|
||||||
proc newYamlParser*(tagLib: TagLibrary = initExtendedTagLibrary(),
|
proc newYamlParser*(tagLib: TagLibrary = initExtendedTagLibrary(),
|
||||||
callback: WarningCallback = nil): YamlParser {.raises: [].}
|
callback: WarningCallback = nil): YamlParser {.raises: [].}
|
||||||
|
## Creates a YAML parser. if ``callback`` is not ``nil``, it will be called
|
||||||
|
## whenever the parser yields a warning.
|
||||||
|
|
||||||
proc getLineNumber*(p: YamlParser): int {.raises: [].}
|
proc getLineNumber*(p: YamlParser): int {.raises: [].}
|
||||||
|
## Get the line number (1-based) of the recently yielded parser token.
|
||||||
|
## Useful for error reporting at later loading stages.
|
||||||
|
|
||||||
proc getColNumber*(p: YamlParser): int {.raises: [].}
|
proc getColNumber*(p: YamlParser): int {.raises: [].}
|
||||||
|
## Get the column number (1-based) of the recently yielded parser token.
|
||||||
|
## Useful for error reporting at later parsing stages.
|
||||||
|
|
||||||
proc getLineContent*(p: YamlParser, marker: bool = true): string {.raises: [].}
|
proc getLineContent*(p: YamlParser, marker: bool = true): string {.raises: [].}
|
||||||
|
## 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.
|
||||||
|
|
||||||
proc parse*(p: YamlParser, s: Stream):
|
proc parse*(p: YamlParser, s: Stream):
|
||||||
YamlStream {.raises: [IOError, YamlParserError].}
|
YamlStream {.raises: [IOError, YamlParserError].}
|
||||||
|
## Parse the given stream as YAML character stream.
|
||||||
|
|
||||||
proc constructJson*(s: YamlStream): seq[JsonNode]
|
proc constructJson*(s: YamlStream): seq[JsonNode]
|
||||||
{.raises: [YamlConstructionError, YamlConstructionStreamError].}
|
{.raises: [YamlConstructionError, YamlConstructionStreamError].}
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue