status-im
/
NimYAML
mirror of https://github.com/status-im/NimYAML.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated from master

This commit is contained in:
Felix Krause 2016-06-08 21:30:04 +02:00
parent 5dc0297651
commit 53c57cbb66
2 changed files with 353 additions and 292 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
serialization.html
View File

@ -34,7 +34,7 @@
<span class="Punctuation">-</span> <span class="DecNumber">3</span></pre><p>You would need to know that it will load a <tt class="docutils literal"><span class="pre">seq[int8]</span></tt> <em>at compile time</em>. This is not really a problem because without knowing which type you will load, you cannot do anything useful with the result afterwards in the code. But it may be unfamiliar for programmers who are used to the YAML libraries of Python or Ruby.</p>
<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 or variant object types. This may be added in the future.</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>
<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>
@ -59,8 +59,25 @@
</ul>
<p>NimYAML will present enum types as YAML scalars, and tuple and object types as YAML maps. Some of the conditions above may be loosened in future releases.</p>
<h3 id="variant-object-types">Variant Object Types</h3><p>A <em>variant object type</em> is an object type that contains one or more <tt class="docutils literal"><span class="pre">case</span></tt> clauses. NimYAML currently supports variant object types. However, this feature is <strong>highly experimental</strong>. Only the currently accessible fields of a variant object type are dumped, and only those may be present when loading. The discriminator field(s) are treated like all other fields. The value of a discriminator field must occur before any value of a field that depends on it. This violates the YAML specification and therefore will be changed in the future.</p>
<p>While dumping variant object types directly is currently not production ready, you can use them for processing heterogeneous data sets. For example, if you have a YAML document which contains differently typed values in the same list like this:</p>
<h3 id="variant-object-types">Variant Object Types</h3><p>A <em>variant object type</em> is an object type that contains one or more <tt class="docutils literal"><span class="pre">case</span></tt> clauses. NimYAML supports variant object types. Only the currently accessible fields of a variant object type are dumped, and only those may be present when loading.</p>
<p>The value of a discriminator field must be loaded before any value of a field that depends on it. Therefore, a YAML mapping cannot be used to serialize variant object types - the YAML specification explicitly states that the order of key-value pairs in a mapping must not be used to convey content information. So, any variant object type is serialized as a list of key-value pairs.</p>
<p>For example, this type:</p>
<pre class = "listing"><span class="Keyword">type</span>
<span class="Identifier">AnimalKind</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
<span class="Identifier">akCat</span><span class="Punctuation">,</span> <span class="Identifier">akDog</span>
<span class="Identifier">Animal</span> <span class="Operator">=</span> <span class="Keyword">object</span>
<span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
<span class="Keyword">case</span> <span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">AnimalKind</span>
<span class="Keyword">of</span> <span class="Identifier">akCat</span><span class="Punctuation">:</span>
<span class="Identifier">purringIntensity</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
<span class="Keyword">of</span> <span class="Identifier">akDog</span><span class="Punctuation">:</span>
<span class="Identifier">barkometer</span><span class="Punctuation">:</span> <span class="Identifier">int</span></pre><p>will be serialized as:</p>
<pre class = "listing"><span class="Directive">%YAML 1.2</span>
<span class="Keyword">---</span> <span class="TagStart">!nim:custom:Animal</span>
<span class="Punctuation">-</span> <span class="StringLit">name</span><span class="Punctuation">:</span> <span class="StringLit">Bastet</span>
<span class="Punctuation">-</span> <span class="StringLit">kind</span><span class="Punctuation">:</span> <span class="StringLit">akCat</span>
<span class="Punctuation">-</span> <span class="StringLit">purringIntensity</span><span class="Punctuation">:</span> <span class="DecNumber">7</span></pre><p>You can also use variant object types for processing heterogeneous data sets. For example, if you have a YAML document which contains differently typed values in the same list like this:</p>
<pre class = "listing"><span class="Directive">%YAML 1.2</span>
<span class="Keyword">---</span>
<span class="Punctuation">-</span> <span class="DecNumber">42</span>
@ -161,7 +178,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-06-08 21:28:44 UTC</small>
</div>
</div>
</div>

620
yaml.html
View File

File diff suppressed because it is too large Load Diff