mirror of https://github.com/status-im/NimYAML.git
Fixed links in documentation
This commit is contained in:
Felix Krause
parent
1dc8ddc6ea
commit
9fffc7b127
|
|
@ -22,7 +22,11 @@ task documentation, "Generate documentation":
|
|||
exec "mkdir -p docout"
|
||||
exec r"nim doc2 -o:docout/yaml.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml"
|
||||
# bash! ah-ah \\ savior of the universe
|
||||
exec r"find yaml -type f -print0 | while read -d '' -r f; do a=${f#yaml/}; nim doc2 -o:docout/yaml.${a%%.nim}.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/yaml/`git log -n 1 --format=%H` $f; done"
|
||||
for file in listFiles("yaml"):
|
||||
let packageName = file[5..^5]
|
||||
exec r"nim doc2 -o:docout/yaml." & packageName &
|
||||
".html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/yaml/`git log -n 1 --format=%H` " &
|
||||
file
|
||||
exec r"nim rst2html -o:docout/index.html doc/index.txt"
|
||||
exec r"nim rst2html -o:docout/api.html doc/api.txt"
|
||||
exec r"nim rst2html -o:docout/serialization.html doc/serialization.txt"
|
||||
|
|
|
|||
56
doc/api.txt
56
doc/api.txt
|
|
@ -25,8 +25,8 @@ Intermediate Representation
|
|||
===========================
|
||||
|
||||
The base of all YAML processing with NimYAML is the
|
||||
`YamlStream <yaml.html#YamlStream>`_. This is basically an iterator over
|
||||
`YamlStreamEvent <yaml.html#YamlStreamEvent>`_ objects. Every proc that
|
||||
`YamlStream <yaml.stream.html#YamlStream>`_. This is basically an iterator over
|
||||
`YamlStreamEvent <yaml.stream.html#YamlStreamEvent>`_ objects. Every proc that
|
||||
represents a single stage of the loading or dumping process will either take a
|
||||
``YamlStream`` as input or return a ``YamlStream``. Procs that implement the
|
||||
whole process in one step hide the ``YamlStream`` from the user. Every proc that
|
||||
|
|
@ -45,16 +45,17 @@ Loading YAML
|
|||
============
|
||||
|
||||
If you want to load YAML character data directly into a native Nim variable, you
|
||||
can use `load <yaml.html#load,Stream,K>`_. This is the easiest and recommended
|
||||
way to load YAML data. The following paragraphs will explain the steps involved.
|
||||
can use `load <yaml.serialization.html#load,,K>`_. This is the easiest and
|
||||
recommended way to load YAML data. This section gives an overview about how
|
||||
``load`` is implemented. It is absolutely possible to reimplement the loading
|
||||
step using the low-level API.
|
||||
|
||||
For parsing, a `YamlParser <yaml.html#YamlParser>`_ object is needed. This
|
||||
object stores some state while parsing that may be useful for error reporting to
|
||||
the user. The
|
||||
`parse <yaml.html#parse,YamlParser,Stream>`_ proc implements the YAML processing
|
||||
step of the same name. All syntax errors in the input character stream are
|
||||
processed by ``parse``, which will raise a ``YamlParserError`` if it encounters
|
||||
a syntax error.
|
||||
For parsing, a `YamlParser <yaml.parser.html#YamlParser>`_ object is needed.
|
||||
This object stores some state while parsing that may be useful for error
|
||||
reporting to the user. The `parse <yaml.parser.html#parse,YamlParser,Stream>`_
|
||||
proc implements the YAML processing step of the same name. All syntax errors in
|
||||
the input character stream are processed by ``parse``, which will raise a
|
||||
``YamlParserError`` if it encounters a syntax error.
|
||||
|
||||
Transforming a ``YamlStream`` to a native YAML object is done via
|
||||
``construct``. It skips the ``compose`` step for efficiency reasons. As Nim is
|
||||
|
|
@ -67,19 +68,21 @@ Dumping YAML
|
|||
============
|
||||
|
||||
Dumping is preferredly done with
|
||||
`dump <yaml.html#dump,K,Stream,PresentationStyle,TagStyle,AnchorStyle,int>`_,
|
||||
which serializes a native Nim variable to a character stream. Like ``load``, you
|
||||
can use the steps involved separately.
|
||||
`dump <yaml.serialization.html#dump,K,Stream,TagStyle,AnchorStyle,PresentationOptions>`_,
|
||||
which serializes a native Nim variable to a character stream. As with ``load``,
|
||||
the following paragraph describes how ``dump`` is implemented using the
|
||||
low-level API.
|
||||
|
||||
You transform a variable into a ``YamlStream`` with
|
||||
`represent <yaml.html#represent,T,TagStyle,AnchorStyle>`_. Depending on the
|
||||
``AnchorStyle`` you specify, this will transform ``ref`` variables with multiple
|
||||
instances into anchored elements and aliases (for ``asTidy`` and ``asAlways``)
|
||||
or write the same element into all places it occurs (for ``asNone``). Be aware
|
||||
that if you use ``asNone``, the value you serialize might not round-trip.
|
||||
A Nim value is transformed into a ``YamlStream`` with
|
||||
`represent <yaml.serialization.html#represent,T,TagStyle,AnchorStyle>`_.
|
||||
Depending on the ``AnchorStyle`` you specify, this will transform ``ref``
|
||||
variables with multiple instances into anchored elements and aliases (for
|
||||
``asTidy`` and ``asAlways``) or write the same element into all places it
|
||||
occurs (for ``asNone``). Be aware that if you use ``asNone``, the value you
|
||||
serialize might not round-trip.
|
||||
|
||||
Transforming a ``YamlStream`` into YAML character data is done with
|
||||
`present <yaml.html#present,YamlStream,Stream,TagLibrary,PresentationStyle,int>`_.
|
||||
`present <yaml.presenter.html#present,YamlStream,Stream,TagLibrary,PresentationOptions>`_.
|
||||
You can choose from multiple presentation styles. ``psJson`` is not able to
|
||||
process some features of ``YamlStream`` s, the other styles support all features
|
||||
and are guaranteed to round-trip to the same ``YamlStream`` if you parse the
|
||||
|
|
@ -90,11 +93,12 @@ The Document Object Model
|
|||
|
||||
Much like XML, YAML also defines a *document object model*. If you cannot or do
|
||||
not want to load a YAML character stream to native Nim types, you can instead
|
||||
load it into a ``YamlDocument``. This ``YamlDocument`` can also be serialized
|
||||
into a YAML character stream. All tags will be preserved exactly as they are
|
||||
when transforming from and to a ``YamlDocument``. The only important thing to
|
||||
remember is that when a value has no tag, it will get the non-specific tag
|
||||
``"!"`` for quoted scalars and ``"?"`` for all other nodes.
|
||||
load it into a `YamlDocument <yaml.dom.html#YamlDocument>`_. This
|
||||
``YamlDocument`` can also be serialized into a YAML character stream. All tags
|
||||
will be preserved exactly as they are when transforming from and to a
|
||||
``YamlDocument``. The only important thing to remember is that when a value has
|
||||
no tag, it will get the non-specific tag ``"!"`` for quoted scalars and ``"?"``
|
||||
for all other nodes.
|
||||
|
||||
While tags are preserved, anchors will be resolved during loading and re-added
|
||||
during serialization. It is allowed for a ``YamlNode`` to occur multiple times
|
||||
|
|
|
|||
|
|
@ -68,18 +68,18 @@
|
|||
<line x1="375" y1="20" x2="595" y2="20" stroke="black" stroke-width="2"/>
|
||||
</g>
|
||||
</defs>
|
||||
|
||||
|
||||
<line x1="145" y1="0" x2="145" y2="420" 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 190)">
|
||||
<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>
|
||||
|
|
@ -87,7 +87,7 @@
|
|||
<text x="60" y="45" font-weight="bold">YamlDocument</text>
|
||||
</a>
|
||||
</g>
|
||||
|
||||
|
||||
<g id="serialization" transform="translate(320 0)">
|
||||
<use xlink:href="#box"/>
|
||||
<text x="60" y="25" font-style="italic">Serialization</text>
|
||||
|
|
@ -95,7 +95,7 @@
|
|||
<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>
|
||||
|
|
@ -104,87 +104,87 @@
|
|||
</a>
|
||||
</g>
|
||||
</g>
|
||||
|
||||
|
||||
<g id="atomics" text-anchor="middle" transform="translate(0 130)">
|
||||
<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"/>
|
||||
<a xlink:href="yaml.html#serialize,YamlDocument,TagLibrary,AnchorStyle" target="_top">
|
||||
<a xlink:href="yaml.dom.html#serialize,YamlDocument,TagLibrary,AnchorStyle" target="_top">
|
||||
<text x="70" y="25" font-style="italic" font-weight="bold">serialize</text>
|
||||
</a>
|
||||
</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">
|
||||
<a xlink:href="yaml.presenter.html#present,YamlStream,Stream,TagLibrary,PresentationOptions" 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"/>
|
||||
<a xlink:href="yaml.html#compose,YamlStream,TagLibrary" target="_top">
|
||||
<a xlink:href="yaml.dom.html#compose,YamlStream,TagLibrary" target="_top">
|
||||
<text x="70" y="35" font-style="italic" font-weight="bold">compose</text>
|
||||
</a>
|
||||
</g>
|
||||
|
||||
|
||||
<g id="parse" transform="translate(385 120)">
|
||||
<use xlink:href="#atomic-left"/>
|
||||
<a xlink:href="yaml.html#parse,YamlParser,Stream" target="_top">
|
||||
<a xlink:href="yaml.parser.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 90)">
|
||||
<g id="skipping-represent" transform="translate(55 10)">
|
||||
<use xlink:href="#skipping-right"/>
|
||||
<a xlink:href="yaml.html#represent,T,TagStyle,AnchorStyle" target="_top">
|
||||
<a xlink:href="yaml.serialization.html#represent,T,TagStyle,AnchorStyle" target="_top">
|
||||
<text x="175" y="25" font-weight="bold">represent</text>
|
||||
</a>
|
||||
</g>
|
||||
<g id="skipping-construct" transform="translate(55 160)">
|
||||
<use xlink:href="#skipping-left"/>
|
||||
<a xlink:href="yaml.html#construct,YamlStream,T" target="_top">
|
||||
<a xlink:href="yaml.serialization.html#construct,YamlStream,T" target="_top">
|
||||
<text x="175" y="75" font-weight="bold">construct</text>
|
||||
</a>
|
||||
</g>
|
||||
</g>
|
||||
|
||||
|
||||
<g id="whole-lines" text-anchor="middle" transform="translate(0 20)">
|
||||
<g id="dump">
|
||||
<use xlink:href="#whole-right"/>
|
||||
<a xlink:href="yaml.html#dump,K,Stream,PresentationStyle,TagStyle,AnchorStyle,int" target="_top">
|
||||
<a xlink:href="yaml.serialization.html#dump,K,Stream,TagStyle,AnchorStyle,PresentationOptions" target="_top">
|
||||
<text x="325" y="25" font-style="italic" font-weight="bold">dump</text>
|
||||
</a>
|
||||
</g>
|
||||
<g id="dumpDOM">
|
||||
<use xlink:href="#dom-right"/>
|
||||
<a xlink:href="yaml.html#dumpDOM,YamlDocument,Stream,PresentationStyle,AnchorStyle,int" target="_top">
|
||||
<text x="380" y="65" font-weight="bold">dumpDOM</text>
|
||||
<a xlink:href="yaml.dom.html#dumpDOM,YamlDocument,Stream,AnchorStyle,PresentationOptions" target="_top">
|
||||
<text x="380" y="65" font-weight="bold">dumpDOM</text>
|
||||
</a>
|
||||
</g>
|
||||
<g id="loadDOM" transform="translate(0 320)">
|
||||
<use xlink:href="#dom-left"/>
|
||||
<a xlink:href="yaml.html#loadDOM,Stream" target="_top">
|
||||
<a xlink:href="yaml.dom.html#loadDOM," target="_top">
|
||||
<text x="380" y="25" font-weight="bold">loadDOM</text>
|
||||
</a>
|
||||
</g>
|
||||
<g id="load" transform="translate(0 360)">
|
||||
<use xlink:href="#whole-left"/>
|
||||
<a xlink:href="yaml.html#load,Stream,K" target="_top">
|
||||
<a xlink:href="yaml.serialization.html#load,,K" target="_top">
|
||||
<text x="325" y="25" font-style="italic" font-weight="bold">load</text>
|
||||
</a>
|
||||
</g>
|
||||
</g>
|
||||
|
||||
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 8.5 KiB After Width: | Height: | Size: 8.5 KiB |
|
|
@ -8,10 +8,11 @@ Introduction
|
|||
NimYAML tries hard to make transforming YAML characters streams to native Nim
|
||||
types and vice versa as easy as possible. In simple scenarios, you might not
|
||||
need anything else than the two procs
|
||||
`dump <yaml.html#dump,K,Stream,PresentationStyle,TagStyle,AnchorStyle,int>`_ and
|
||||
`load <yaml.html#load,Stream,K>`_. On the other side, the process should be as
|
||||
customizable as possible to allow the user to tightly control how the generated
|
||||
YAML character stream will look and how a YAML character stream is interpreted.
|
||||
`dump <yaml.serialization.html#dump,K,Stream,TagStyle,AnchorStyle,PresentationOptions>`_
|
||||
and `load <yaml.serialization.html#load,,K>`_. On the other side, the process
|
||||
should be as customizable as possible to allow the user to tightly control how
|
||||
the generated YAML character stream will look and how a YAML character stream is
|
||||
interpreted.
|
||||
|
||||
An important thing to remember in NimYAML is that unlike in interpreted
|
||||
languages like Ruby, Nim cannot load a YAML character stream without knowing the
|
||||
|
|
@ -42,7 +43,8 @@ added in the future.
|
|||
|
||||
This also means that NimYAML is generally able to work with object, tuple and
|
||||
enum types defined in the standard library or a third-party library without
|
||||
further configuration.
|
||||
further configuration, given that all fields of the object are accessible at the
|
||||
code point where NimYAML's facilities are invoked.
|
||||
|
||||
Scalar Types
|
||||
------------
|
||||
|
|
@ -113,7 +115,7 @@ For an object or tuple type to be directly usable with NimYAML, the following
|
|||
conditions must be met:
|
||||
|
||||
- Every type contained in the object/tuple must be supported
|
||||
- All fields of an object type must be accessible from the code position where
|
||||
- All fields of an object type must be accessible from the code position where
|
||||
you call NimYAML. If an object has non-public member fields, it can only be
|
||||
processed in the module where it is defined.
|
||||
- The object may not have a generic parameter
|
||||
|
|
@ -141,7 +143,7 @@ For example, this type:
|
|||
type
|
||||
AnimalKind = enum
|
||||
akCat, akDog
|
||||
|
||||
|
||||
Animal = object
|
||||
name: string
|
||||
case kind: AnimalKind
|
||||
|
|
@ -175,7 +177,7 @@ list in order to load it:
|
|||
|
||||
.. code-block:: nim
|
||||
import yaml
|
||||
|
||||
|
||||
type
|
||||
ContainerKind = enum
|
||||
ckInt, ckString, ckNone
|
||||
|
|
@ -187,9 +189,9 @@ list in order to load it:
|
|||
strVal: string
|
||||
of ckNone:
|
||||
discard
|
||||
|
||||
|
||||
markAsImplicit(Container)
|
||||
|
||||
|
||||
var
|
||||
list: seq[Container]
|
||||
s = newFileStream("in.yaml")
|
||||
|
|
@ -232,7 +234,7 @@ otherwise, it would be loaded as ``nil``.
|
|||
As you might have noticed in the example above, the YAML tag of a ``seq``
|
||||
depends on its generic type parameter. The same applies to ``Table``. So, a
|
||||
table that maps ``int8`` to string sequences would be presented with the tag
|
||||
``!nim:tables:Table(nim:system:int8,nim:system:seq(tag:yaml.org,2002:string))``.
|
||||
``!nim:tables:Table(nim:system:int8,nim:system:seq(tag:yaml.org,2002:string))``.
|
||||
These tags are generated on the fly based on the types you instantiate
|
||||
``Table`` or ``seq`` with.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue