mirror of
https://github.com/status-im/NimYAML.git
synced 2025-02-05 16:04:48 +00:00
updated from devel
This commit is contained in:
Felix Krause
parent
3ae9d68db9
commit
8067815d8c
33
api.html
33
api.html
@ -6,7 +6,7 @@
|
||||
|
||||
<link href="docutils.css" rel="stylesheet" type="text/css"/>
|
||||
<link href="style.css" rel="stylesheet" type="text/css"/>
|
||||
|
||||
|
||||
<link href='http://fonts.googleapis.com/css?family=Raleway:400,600,900' rel='stylesheet' type='text/css'/>
|
||||
<link href='http://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
|
||||
</head>
|
||||
@ -19,7 +19,20 @@
|
||||
<span>Docs:</span>
|
||||
<a href="api.html">Overview</a>
|
||||
<a href="serialization.html">Serialization</a>
|
||||
<a href="yaml.html">Module yaml</a>
|
||||
<span>
|
||||
<a href="#">Modules</a>
|
||||
<ul>
|
||||
<li><a href="yaml.html">yaml</a></li>
|
||||
<li><a href="yaml.dom.html">yaml.dom</a></li>
|
||||
<li><a href="yaml.hints.html">yaml.hints</a></li>
|
||||
<li><a href="yaml.parser.html">yaml.parser</a></li>
|
||||
<li><a href="yaml.presenter.html">yaml.presenter</a></li>
|
||||
<li><a href="yaml.serialization.html">yaml.serialization</a></li>
|
||||
<li><a href="yaml.stream.html">yaml.stream</a></li>
|
||||
<li><a href="yaml.taglib.html">yaml.taglib</a></li>
|
||||
<li><a href="yaml.tojson.html">yaml.tojson</a></li>
|
||||
</ul>
|
||||
</span>
|
||||
</header>
|
||||
<article id="documentId">
|
||||
<div class="container">
|
||||
@ -28,18 +41,18 @@
|
||||
<h1 id="introduction">Introduction</h1><p>NimYAML advocates parsing YAML input into native Nim types. Basic Nim library types like integers, floats and strings, as well as all tuples, enums and objects without private fields are supported out-of-the-box. Reference types are also supported, and NimYAML is able to detect if a reference occurs more than once and will serialize it accordingly. This means that NimYAML is able to dump and load potentially cyclic objects.</p>
|
||||
<p>While loading into and dumping from native Nim types is the preferred way to use NimYAML, it also gives you complete control over each processing step, so that you can for example only use the parser and process its event stream yourself. 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 <em>italic</em>, NimYAML's implementation name is shown in <strong>bold</strong>.</p>
|
||||
<object data="processing.svg" type="image/svg+xml" ></object>
|
||||
<h1 id="intermediate-representation">Intermediate Representation</h1><p>The base of all YAML processing with NimYAML is the <a class="reference external" href="yaml.html#YamlStream">YamlStream</a>. This is basically an iterator over <a class="reference external" href="yaml.html#YamlStreamEvent">YamlStreamEvent</a> objects. Every proc that represents a single stage of the loading or dumping process will either take a <tt class="docutils literal"><span class="pre">YamlStream</span></tt> as input or return a <tt class="docutils literal"><span class="pre">YamlStream</span></tt>. Procs that implement the whole process in one step hide the <tt class="docutils literal"><span class="pre">YamlStream</span></tt> from the user. Every proc that returns a <tt class="docutils literal"><span class="pre">YamlStream</span></tt> guarantees that this stream is well-formed according to the YAML specification.</p>
|
||||
<h1 id="intermediate-representation">Intermediate Representation</h1><p>The base of all YAML processing with NimYAML is the <a class="reference external" href="yaml.stream.html#YamlStream">YamlStream</a>. This is basically an iterator over <a class="reference external" href="yaml.stream.html#YamlStreamEvent">YamlStreamEvent</a> objects. Every proc that represents a single stage of the loading or dumping process will either take a <tt class="docutils literal"><span class="pre">YamlStream</span></tt> as input or return a <tt class="docutils literal"><span class="pre">YamlStream</span></tt>. Procs that implement the whole process in one step hide the <tt class="docutils literal"><span class="pre">YamlStream</span></tt> from the user. Every proc that returns a <tt class="docutils literal"><span class="pre">YamlStream</span></tt> guarantees that this stream is well-formed according to the YAML specification.</p>
|
||||
<p>This stream-oriented API can efficiently be used to parse large amounts of data. The drawback is that errors in the input are only discovered while processing the <tt class="docutils literal"><span class="pre">YamlStream</span></tt>. If the <tt class="docutils literal"><span class="pre">YamlStream</span></tt> encounters an exception while producing the next event, it will throw a <tt class="docutils literal"><span class="pre">YamlStreamError</span></tt> which contains the original exception as <tt class="docutils literal"><span class="pre">parent</span></tt>. The caller should know which exceptions are possible as parents of <tt class="docutils literal"><span class="pre">YamlStream</span></tt> because they know the source of the <tt class="docutils literal"><span class="pre">YamlStream</span></tt> they provided.</p>
|
||||
|
||||
<h1 id="loading-yaml">Loading YAML</h1><p>If you want to load YAML character data directly into a native Nim variable, you can use <a class="reference external" href="yaml.html#load,Stream,K">load</a>. This is the easiest and recommended way to load YAML data. The following paragraphs will explain the steps involved.</p>
|
||||
<p>For parsing, a <a class="reference external" href="yaml.html#YamlParser">YamlParser</a> object is needed. This object stores some state while parsing that may be useful for error reporting to the user. The <a class="reference external" href="yaml.html#parse,YamlParser,Stream">parse</a> proc implements the YAML processing step of the same name. All syntax errors in the input character stream are processed by <tt class="docutils literal"><span class="pre">parse</span></tt>, which will raise a <tt class="docutils literal"><span class="pre">YamlParserError</span></tt> if it encounters a syntax error.</p>
|
||||
<h1 id="loading-yaml">Loading YAML</h1><p>If you want to load YAML character data directly into a native Nim variable, you can use <a class="reference external" href="yaml.serialization.html#load,,K">load</a>. This is the easiest and recommended way to load YAML data. This section gives an overview about how <tt class="docutils literal"><span class="pre">load</span></tt> is implemented. It is absolutely possible to reimplement the loading step using the low-level API.</p>
|
||||
<p>For parsing, a <a class="reference external" href="yaml.parser.html#YamlParser">YamlParser</a> object is needed. This object stores some state while parsing that may be useful for error reporting to the user. The <a class="reference external" href="yaml.parser.html#parse,YamlParser,Stream">parse</a> proc implements the YAML processing step of the same name. All syntax errors in the input character stream are processed by <tt class="docutils literal"><span class="pre">parse</span></tt>, which will raise a <tt class="docutils literal"><span class="pre">YamlParserError</span></tt> if it encounters a syntax error.</p>
|
||||
<p>Transforming a <tt class="docutils literal"><span class="pre">YamlStream</span></tt> to a native YAML object is done via <tt class="docutils literal"><span class="pre">construct</span></tt>. It skips the <tt class="docutils literal"><span class="pre">compose</span></tt> step for efficiency reasons. As Nim is statically typed, you have to know the target type when you write your loading code. This is different from YAML APIs of dynamically typed languages. If you cannot know the type of your YAML input at compile time, you have to manually process the <tt class="docutils literal"><span class="pre">YamlStream</span></tt> to serve your needs.</p>
|
||||
|
||||
<h1 id="dumping-yaml">Dumping YAML</h1><p>Dumping is preferredly done with <a class="reference external" href="yaml.html#dump,K,Stream,PresentationStyle,TagStyle,AnchorStyle,int">dump</a>, which serializes a native Nim variable to a character stream. Like <tt class="docutils literal"><span class="pre">load</span></tt>, you can use the steps involved separately.</p>
|
||||
<p>You transform a variable into a <tt class="docutils literal"><span class="pre">YamlStream</span></tt> with <a class="reference external" href="yaml.html#represent,T,TagStyle,AnchorStyle">represent</a>. Depending on the <tt class="docutils literal"><span class="pre">AnchorStyle</span></tt> you specify, this will transform <tt class="docutils literal"><span class="pre">ref</span></tt> variables with multiple instances into anchored elements and aliases (for <tt class="docutils literal"><span class="pre">asTidy</span></tt> and <tt class="docutils literal"><span class="pre">asAlways</span></tt>) or write the same element into all places it occurs (for <tt class="docutils literal"><span class="pre">asNone</span></tt>). Be aware that if you use <tt class="docutils literal"><span class="pre">asNone</span></tt>, the value you serialize might not round-trip.</p>
|
||||
<p>Transforming a <tt class="docutils literal"><span class="pre">YamlStream</span></tt> into YAML character data is done with <a class="reference external" href="yaml.html#present,YamlStream,Stream,TagLibrary,PresentationStyle,int">present</a>. You can choose from multiple presentation styles. <tt class="docutils literal"><span class="pre">psJson</span></tt> is not able to process some features of <tt class="docutils literal"><span class="pre">YamlStream</span></tt> s, the other styles support all features and are guaranteed to round-trip to the same <tt class="docutils literal"><span class="pre">YamlStream</span></tt> if you parse the generated YAML character stream again.</p>
|
||||
<h1 id="dumping-yaml">Dumping YAML</h1><p>Dumping is preferredly done with <a class="reference external" href="yaml.serialization.html#dump,K,Stream,TagStyle,AnchorStyle,PresentationOptions">dump</a>, which serializes a native Nim variable to a character stream. As with <tt class="docutils literal"><span class="pre">load</span></tt>, the following paragraph describes how <tt class="docutils literal"><span class="pre">dump</span></tt> is implemented using the low-level API.</p>
|
||||
<p>A Nim value is transformed into a <tt class="docutils literal"><span class="pre">YamlStream</span></tt> with <a class="reference external" href="yaml.serialization.html#represent,T,TagStyle,AnchorStyle">represent</a>. Depending on the <tt class="docutils literal"><span class="pre">AnchorStyle</span></tt> you specify, this will transform <tt class="docutils literal"><span class="pre">ref</span></tt> variables with multiple instances into anchored elements and aliases (for <tt class="docutils literal"><span class="pre">asTidy</span></tt> and <tt class="docutils literal"><span class="pre">asAlways</span></tt>) or write the same element into all places it occurs (for <tt class="docutils literal"><span class="pre">asNone</span></tt>). Be aware that if you use <tt class="docutils literal"><span class="pre">asNone</span></tt>, the value you serialize might not round-trip.</p>
|
||||
<p>Transforming a <tt class="docutils literal"><span class="pre">YamlStream</span></tt> into YAML character data is done with <a class="reference external" href="yaml.presenter.html#present,YamlStream,Stream,TagLibrary,PresentationOptions">present</a>. You can choose from multiple presentation styles. <tt class="docutils literal"><span class="pre">psJson</span></tt> is not able to process some features of <tt class="docutils literal"><span class="pre">YamlStream</span></tt> s, the other styles support all features and are guaranteed to round-trip to the same <tt class="docutils literal"><span class="pre">YamlStream</span></tt> if you parse the generated YAML character stream again.</p>
|
||||
|
||||
<h1 id="the-document-object-model">The Document Object Model</h1><p>Much like XML, YAML also defines a <em>document object model</em>. If you cannot or do not want to load a YAML character stream to native Nim types, you can instead load it into a <tt class="docutils literal"><span class="pre">YamlDocument</span></tt>. This <tt class="docutils literal"><span class="pre">YamlDocument</span></tt> can also be serialized into a YAML character stream. All tags will be preserved exactly as they are when transforming from and to a <tt class="docutils literal"><span class="pre">YamlDocument</span></tt>. The only important thing to remember is that when a value has no tag, it will get the non-specific tag <tt class="docutils literal"><span class="pre">"!"</span></tt> for quoted scalars and <tt class="docutils literal"><span class="pre">"?"</span></tt> for all other nodes.</p>
|
||||
<h1 id="the-document-object-model">The Document Object Model</h1><p>Much like XML, YAML also defines a <em>document object model</em>. If you cannot or do not want to load a YAML character stream to native Nim types, you can instead load it into a <a class="reference external" href="yaml.dom.html#YamlDocument">YamlDocument</a>. This <tt class="docutils literal"><span class="pre">YamlDocument</span></tt> can also be serialized into a YAML character stream. All tags will be preserved exactly as they are when transforming from and to a <tt class="docutils literal"><span class="pre">YamlDocument</span></tt>. The only important thing to remember is that when a value has no tag, it will get the non-specific tag <tt class="docutils literal"><span class="pre">"!"</span></tt> for quoted scalars and <tt class="docutils literal"><span class="pre">"?"</span></tt> for all other nodes.</p>
|
||||
<p>While tags are preserved, anchors will be resolved during loading and re-added during serialization. It is allowed for a <tt class="docutils literal"><span class="pre">YamlNode</span></tt> to occur multiple times within a <tt class="docutils literal"><span class="pre">YamlDocument</span></tt>, in which case it will be serialized once and referred to afterwards via aliases.</p>
|
||||
<p>The document object model is provided for completeness, but you are encouraged to use native Nim types as start- or endpoint instead. That may be significantly faster, as every <tt class="docutils literal"><span class="pre">YamlNode</span></tt> is allocated on the heap and subject to garbage collection.</p>
|
||||
|
||||
@ -49,7 +62,7 @@
|
||||
<div class="twelve-columns footer">
|
||||
<span class="nim-sprite"></span>
|
||||
<br/>
|
||||
<small>Made with Nim. Generated: 2016-04-21 19:00:52 UTC</small>
|
||||
<small>Made with Nim. Generated: 2016-10-01 15:20:07 UTC</small>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
19
index.html
19
index.html
@ -6,7 +6,7 @@
|
||||
|
||||
<link href="docutils.css" rel="stylesheet" type="text/css"/>
|
||||
<link href="style.css" rel="stylesheet" type="text/css"/>
|
||||
|
||||
|
||||
<link href='http://fonts.googleapis.com/css?family=Raleway:400,600,900' rel='stylesheet' type='text/css'/>
|
||||
<link href='http://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
|
||||
</head>
|
||||
@ -19,7 +19,20 @@
|
||||
<span>Docs:</span>
|
||||
<a href="api.html">Overview</a>
|
||||
<a href="serialization.html">Serialization</a>
|
||||
<a href="yaml.html">Module yaml</a>
|
||||
<span>
|
||||
<a href="#">Modules</a>
|
||||
<ul>
|
||||
<li><a href="yaml.html">yaml</a></li>
|
||||
<li><a href="yaml.dom.html">yaml.dom</a></li>
|
||||
<li><a href="yaml.hints.html">yaml.hints</a></li>
|
||||
<li><a href="yaml.parser.html">yaml.parser</a></li>
|
||||
<li><a href="yaml.presenter.html">yaml.presenter</a></li>
|
||||
<li><a href="yaml.serialization.html">yaml.serialization</a></li>
|
||||
<li><a href="yaml.stream.html">yaml.stream</a></li>
|
||||
<li><a href="yaml.taglib.html">yaml.taglib</a></li>
|
||||
<li><a href="yaml.tojson.html">yaml.tojson</a></li>
|
||||
</ul>
|
||||
</span>
|
||||
</header>
|
||||
<article id="documentId">
|
||||
<div class="container">
|
||||
@ -326,7 +339,7 @@
|
||||
<div class="twelve-columns footer">
|
||||
<span class="nim-sprite"></span>
|
||||
<br/>
|
||||
<small>Made with Nim. Generated: 2016-06-05 19:42:50 UTC</small>
|
||||
<small>Made with Nim. Generated: 2016-10-01 15:20:07 UTC</small>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@ -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 |
@ -6,7 +6,7 @@
|
||||
|
||||
<link href="docutils.css" rel="stylesheet" type="text/css"/>
|
||||
<link href="style.css" rel="stylesheet" type="text/css"/>
|
||||
|
||||
|
||||
<link href='http://fonts.googleapis.com/css?family=Raleway:400,600,900' rel='stylesheet' type='text/css'/>
|
||||
<link href='http://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
|
||||
</head>
|
||||
@ -19,13 +19,26 @@
|
||||
<span>Docs:</span>
|
||||
<a href="api.html">Overview</a>
|
||||
<a href="serialization.html">Serialization</a>
|
||||
<a href="yaml.html">Module yaml</a>
|
||||
<span>
|
||||
<a href="#">Modules</a>
|
||||
<ul>
|
||||
<li><a href="yaml.html">yaml</a></li>
|
||||
<li><a href="yaml.dom.html">yaml.dom</a></li>
|
||||
<li><a href="yaml.hints.html">yaml.hints</a></li>
|
||||
<li><a href="yaml.parser.html">yaml.parser</a></li>
|
||||
<li><a href="yaml.presenter.html">yaml.presenter</a></li>
|
||||
<li><a href="yaml.serialization.html">yaml.serialization</a></li>
|
||||
<li><a href="yaml.stream.html">yaml.stream</a></li>
|
||||
<li><a href="yaml.taglib.html">yaml.taglib</a></li>
|
||||
<li><a href="yaml.tojson.html">yaml.tojson</a></li>
|
||||
</ul>
|
||||
</span>
|
||||
</header>
|
||||
<article id="documentId">
|
||||
<div class="container">
|
||||
<h1 class="title">Serialization Overview</h1>
|
||||
|
||||
<h1 id="introduction">Introduction</h1><p>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 <a class="reference external" href="yaml.html#dump,K,Stream,PresentationStyle,TagStyle,AnchorStyle,int">dump</a> and <a class="reference external" href="yaml.html#load,Stream,K">load</a>. 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.</p>
|
||||
<h1 id="introduction">Introduction</h1><p>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 <a class="reference external" href="yaml.serialization.html#dump,K,Stream,TagStyle,AnchorStyle,PresentationOptions">dump</a> and <a class="reference external" href="yaml.serialization.html#load,,K">load</a>. 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.</p>
|
||||
<p>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 resulting type beforehand. For example, if you want to load this piece of YAML:</p>
|
||||
<pre class = "listing"><span class="Directive">%YAML 1.2</span>
|
||||
<span class="Keyword">---</span> <span class="TagStart">!nim:system:seq(nim:system:int8)</span>
|
||||
@ -35,7 +48,7 @@
|
||||
|
||||
<h1 id="supported-types">Supported Types</h1><p>NimYAML supports a growing number of types of Nim's <tt class="docutils literal"><span class="pre">system</span></tt> module and standard library, and it also supports user-defined object, tuple and enum types out of the box.</p>
|
||||
<p><strong>Important</strong>: NimYAML currently does not support polymorphism. This may be added in the future.</p>
|
||||
<p>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.</p>
|
||||
<p>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, given that all fields of the object are accessible at the code point where NimYAML's facilities are invoked.</p>
|
||||
|
||||
<h2 id="scalar-types">Scalar Types</h2><p>The following integer types are supported by NimYAML: <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">int8</span></tt>, <tt class="docutils literal"><span class="pre">int16</span></tt>, <tt class="docutils literal"><span class="pre">int32</span></tt>, <tt class="docutils literal"><span class="pre">int64</span></tt>, <tt class="docutils literal"><span class="pre">uint8</span></tt>, <tt class="docutils literal"><span class="pre">uint16</span></tt>, <tt class="docutils literal"><span class="pre">uint32</span></tt>, <tt class="docutils literal"><span class="pre">uint64</span></tt>. Note that the <tt class="docutils literal"><span class="pre">int</span></tt> type has a variable size dependent on the target operation system. To make sure that it round-trips properly between 32-bit and 64-bit operating systems, it will be converted to an <tt class="docutils literal"><span class="pre">int32</span></tt> during loading and dumping. This will raise an exception for values outside of the range <tt class="docutils literal"><span class="pre">int32.low .. int32.high</span></tt>! If you define the types you serialize yourself, always consider using an integer type with explicit length. The same goes for <tt class="docutils literal"><span class="pre">uint</span></tt>.</p>
|
||||
<p>The floating point types <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">float32</span></tt> and <tt class="docutils literal"><span class="pre">float64</span></tt> are also supported. There is currently no problem with <tt class="docutils literal"><span class="pre">float</span></tt>, because it is always a <tt class="docutils literal"><span class="pre">float64</span></tt>.</p>
|
||||
@ -145,40 +158,33 @@
|
||||
<span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">item</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">discard</span> <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">next</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre>
|
||||
<h2 id="representobject">representObject</h2><pre class = "listing"><span class="Keyword">proc</span> <span class="Identifier">representObject</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">value</span><span class="Punctuation">:</span> <span class="Identifier">MyObject</span><span class="Punctuation">,</span> <span class="Identifier">ts</span><span class="Punctuation">:</span> <span class="Identifier">TagStyle</span> <span class="Operator">=</span> <span class="Identifier">tsNone</span><span class="Punctuation">,</span>
|
||||
<span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">SerializationContext</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">RawYamlStream</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span></pre><p>This proc should return an iterator over <tt class="docutils literal"><span class="pre">YamlStreamEvent</span></tt> which represents the type. Follow the following guidelines when implementing a custom <tt class="docutils literal"><span class="pre">representObject</span></tt> proc:</p>
|
||||
<span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">SerializationContext</span><span class="Punctuation">,</span> <span class="Identifier">tag</span><span class="Punctuation">:</span> <span class="Identifier">TagId</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span></pre><p>This proc should push a list of tokens that represent the type into the serialization context via <tt class="docutils literal"><span class="pre">c.put</span></tt>. Follow the following guidelines when implementing a custom <tt class="docutils literal"><span class="pre">representObject</span></tt> proc:</p>
|
||||
<ul class="simple"><li>You can use the helper template <a class="reference external" href="yaml.html#presentTag,typedesc,TagStyle">presentTag</a> for outputting the tag.</li>
|
||||
<li>Always output the first tag with a <tt class="docutils literal"><span class="pre">yAnchorNone</span></tt>. Anchors will be set automatically by <tt class="docutils literal"><span class="pre">ref</span></tt> type handling.</li>
|
||||
<li>Always output the first token with a <tt class="docutils literal"><span class="pre">yAnchorNone</span></tt>. Anchors will be set automatically by <tt class="docutils literal"><span class="pre">ref</span></tt> type handling.</li>
|
||||
<li>When outputting non-scalar types, you should use the <tt class="docutils literal"><span class="pre">representObject</span></tt> implementation of the child types, if possible.</li>
|
||||
<li>Check if the given <tt class="docutils literal"><span class="pre">TagStyle</span></tt> equals <tt class="docutils literal"><span class="pre">tsRootOnly</span></tt> and if yes, change it to <tt class="docutils literal"><span class="pre">tsNone</span></tt> for the child values.</li>
|
||||
<li>Always use the <tt class="docutils literal"><span class="pre">tag</span></tt> parameter as tag for the first token you generate.</li>
|
||||
<li>Never write a <tt class="docutils literal"><span class="pre">representObject</span></tt> proc for <tt class="docutils literal"><span class="pre">ref</span></tt> types.</li>
|
||||
</ul>
|
||||
<p>The following example for representing to a YAML scalar is the actual implementation of representing <tt class="docutils literal"><span class="pre">int</span></tt> types:</p>
|
||||
<pre class = "listing"><span class="Keyword">proc</span> <span class="Identifier">representObject</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">uint8</span><span class="Operator">|</span><span class="Identifier">uint16</span><span class="Operator">|</span><span class="Identifier">uint32</span><span class="Operator">|</span><span class="Identifier">uint64</span><span class="Punctuation">]</span><span class="Punctuation">(</span>
|
||||
<span class="Identifier">value</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">,</span> <span class="Identifier">ts</span><span class="Punctuation">:</span> <span class="Identifier">TagStyle</span><span class="Punctuation">,</span> <span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">SerializationContext</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
|
||||
<span class="Identifier">RawYamlStream</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
|
||||
<span class="Identifier">result</span> <span class="Operator">=</span> <span class="Keyword">iterator</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">YamlStreamEvent</span> <span class="Operator">=</span>
|
||||
<span class="Keyword">yield</span> <span class="Identifier">scalarEvent</span><span class="Punctuation">(</span><span class="Operator">$</span><span class="Identifier">value</span><span class="Punctuation">,</span> <span class="Identifier">presentTag</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">,</span> <span class="Identifier">ts</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">yAnchorNone</span><span class="Punctuation">)</span></pre><p>The following example for representing to a YAML non-scalar is the actual implementation of representing <tt class="docutils literal"><span class="pre">seq</span></tt> types:</p>
|
||||
<pre class = "listing"><span class="Keyword">proc</span> <span class="Identifier">representObject</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">value</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">ts</span><span class="Punctuation">:</span> <span class="Identifier">TagStyle</span><span class="Punctuation">,</span>
|
||||
<span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">SerializationContext</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">RawYamlStream</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
|
||||
<span class="Identifier">result</span> <span class="Operator">=</span> <span class="Keyword">iterator</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">YamlStreamEvent</span> <span class="Operator">=</span>
|
||||
<span class="Keyword">let</span> <span class="Identifier">childTagStyle</span> <span class="Operator">=</span> <span class="Keyword">if</span> <span class="Identifier">ts</span> <span class="Operator">==</span> <span class="Identifier">tsRootOnly</span><span class="Punctuation">:</span> <span class="Identifier">tsNone</span> <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">ts</span>
|
||||
<span class="Keyword">yield</span> <span class="Identifier">YamlStreamEvent</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">yamlStartSequence</span><span class="Punctuation">,</span>
|
||||
<span class="Identifier">seqTag</span><span class="Punctuation">:</span> <span class="Identifier">presentTag</span><span class="Punctuation">(</span><span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">ts</span><span class="Punctuation">)</span><span class="Punctuation">,</span>
|
||||
<span class="Identifier">seqAnchor</span><span class="Punctuation">:</span> <span class="Identifier">yAnchorNone</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">for</span> <span class="Identifier">item</span> <span class="Keyword">in</span> <span class="Identifier">value</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">var</span> <span class="Identifier">events</span> <span class="Operator">=</span> <span class="Identifier">representObject</span><span class="Punctuation">(</span><span class="Identifier">item</span><span class="Punctuation">,</span> <span class="Identifier">childTagStyle</span><span class="Punctuation">,</span> <span class="Identifier">c</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">while</span> <span class="Identifier">true</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">let</span> <span class="Identifier">event</span> <span class="Operator">=</span> <span class="Identifier">events</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">if</span> <span class="Identifier">finished</span><span class="Punctuation">(</span><span class="Identifier">events</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">break</span>
|
||||
<span class="Keyword">yield</span> <span class="Identifier">event</span>
|
||||
<span class="Keyword">yield</span> <span class="Identifier">YamlStreamEvent</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">yamlEndSequence</span><span class="Punctuation">)</span></pre>
|
||||
<pre class = "listing"><span class="Keyword">proc</span> <span class="Identifier">representObject</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">int8</span><span class="Operator">|</span><span class="Identifier">int16</span><span class="Operator">|</span><span class="Identifier">int32</span><span class="Operator">|</span><span class="Identifier">int64</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">value</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">,</span> <span class="Identifier">ts</span><span class="Punctuation">:</span> <span class="Identifier">TagStyle</span><span class="Punctuation">,</span>
|
||||
<span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">SerializationContext</span><span class="Punctuation">,</span> <span class="Identifier">tag</span><span class="Punctuation">:</span> <span class="Identifier">TagId</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
|
||||
<span class="Comment">## represents an integer value as YAML scalar</span>
|
||||
<span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">put</span><span class="Punctuation">(</span><span class="Identifier">scalarEvent</span><span class="Punctuation">(</span><span class="Operator">$</span><span class="Identifier">value</span><span class="Punctuation">,</span> <span class="Identifier">tag</span><span class="Punctuation">,</span> <span class="Identifier">yAnchorNone</span><span class="Punctuation">)</span><span class="Punctuation">)</span></pre><p>The following example for representing to a YAML non-scalar is the actual implementation of representing <tt class="docutils literal"><span class="pre">seq</span></tt> and <tt class="docutils literal"><span class="pre">set</span></tt> types:</p>
|
||||
<pre class = "listing"><span class="Keyword">proc</span> <span class="Identifier">representObject</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">value</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Operator">|</span><span class="Identifier">set</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">ts</span><span class="Punctuation">:</span> <span class="Identifier">TagStyle</span><span class="Punctuation">,</span>
|
||||
<span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">SerializationContext</span><span class="Punctuation">,</span> <span class="Identifier">tag</span><span class="Punctuation">:</span> <span class="Identifier">TagId</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">YamlStreamError</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
|
||||
<span class="Comment">## represents a Nim seq as YAML sequence</span>
|
||||
<span class="Keyword">let</span> <span class="Identifier">childTagStyle</span> <span class="Operator">=</span> <span class="Keyword">if</span> <span class="Identifier">ts</span> <span class="Operator">==</span> <span class="Identifier">tsRootOnly</span><span class="Punctuation">:</span> <span class="Identifier">tsNone</span> <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">ts</span>
|
||||
<span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">put</span><span class="Punctuation">(</span><span class="Identifier">startSeqEvent</span><span class="Punctuation">(</span><span class="Identifier">tag</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">for</span> <span class="Identifier">item</span> <span class="Keyword">in</span> <span class="Identifier">value</span><span class="Punctuation">:</span>
|
||||
<span class="Identifier">representChild</span><span class="Punctuation">(</span><span class="Identifier">item</span><span class="Punctuation">,</span> <span class="Identifier">childTagStyle</span><span class="Punctuation">,</span> <span class="Identifier">c</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">put</span><span class="Punctuation">(</span><span class="Identifier">endSeqEvent</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">)</span></pre>
|
||||
|
||||
|
||||
<div class="row">
|
||||
<div class="twelve-columns footer">
|
||||
<span class="nim-sprite"></span>
|
||||
<br/>
|
||||
<small>Made with Nim. Generated: 2016-06-08 21:28:44 UTC</small>
|
||||
<small>Made with Nim. Generated: 2016-10-01 15:20:07 UTC</small>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
33
style.css
33
style.css
@ -18,6 +18,11 @@ header a {
|
||||
padding-right: 5px;
|
||||
}
|
||||
|
||||
header a.active {
|
||||
background: #877 !important;
|
||||
color: black !important;
|
||||
}
|
||||
|
||||
header span {
|
||||
display: inline-block;
|
||||
line-height: 50px;
|
||||
@ -27,6 +32,34 @@ header span {
|
||||
padding-right: 5px;
|
||||
}
|
||||
|
||||
header span a {
|
||||
display: block;
|
||||
}
|
||||
|
||||
header span ul {
|
||||
display: none;
|
||||
position: absolute;
|
||||
top: 100%;
|
||||
list-style: none;
|
||||
background: #111;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
header span ul:after {
|
||||
content: ""; clear: both; display: block;
|
||||
}
|
||||
|
||||
header span:hover > ul {
|
||||
display: block;
|
||||
}
|
||||
|
||||
header span ul a {
|
||||
font-size: smaller;
|
||||
font-family: "Source Code Pro", Menlo, "Courier New", Courier, monospace;
|
||||
padding: 0 10px;
|
||||
line-height: 40px;
|
||||
}
|
||||
|
||||
header a:link,
|
||||
header a:visited {
|
||||
background: inherit;
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user