mirror of https://github.com/status-im/NimYAML.git
Updated from master
This commit is contained in:
Felix Krause
parent
b5a3eaf15b
commit
97cd593463
2
api.html
2
api.html
|
|
@ -49,7 +49,7 @@
|
|||
<div class="twelve-columns footer">
|
||||
<span class="nim-sprite"></span>
|
||||
<br/>
|
||||
<small>Made with Nim. Generated: 2016-03-20 22:58:28 UTC</small>
|
||||
<small>Made with Nim. Generated: 2016-04-21 19:00:52 UTC</small>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
24
index.html
24
index.html
|
|
@ -156,8 +156,8 @@
|
|||
<span class="Identifier">level</span><span class="Punctuation">,</span> <span class="Identifier">experience</span><span class="Punctuation">:</span> <span class="Identifier">int32</span>
|
||||
<span class="Identifier">drops</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span>
|
||||
|
||||
<span class="Identifier">setTagUriForType</span><span class="Punctuation">(</span><span class="Identifier">Mob</span><span class="Punctuation">,</span> <span class="StringLit">"!Mob"</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">setTagUriForType</span><span class="Punctuation">(</span><span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="StringLit">"!Drops"</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">setTagUri</span><span class="Punctuation">(</span><span class="Identifier">Mob</span><span class="Punctuation">,</span> <span class="StringLit">"!Mob"</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">setTagUri</span><span class="Punctuation">(</span><span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="StringLit">"!Drops"</span><span class="Punctuation">)</span>
|
||||
|
||||
<span class="Keyword">var</span> <span class="Identifier">mob</span> <span class="Operator">=</span> <span class="Identifier">Mob</span><span class="Punctuation">(</span><span class="Identifier">level</span><span class="Punctuation">:</span> <span class="DecNumber">42</span><span class="Punctuation">,</span> <span class="Identifier">experience</span><span class="Punctuation">:</span> <span class="DecNumber">1800</span><span class="Punctuation">,</span> <span class="Identifier">drops</span><span class="Punctuation">:</span>
|
||||
<span class="Operator">@</span><span class="Punctuation">[</span><span class="StringLit">"Sword of Mob Slaying"</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
|
||||
|
|
@ -219,8 +219,7 @@
|
|||
<span class="Keyword">type</span> <span class="Identifier">Person</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="Identifier">setTagUriForType</span><span class="Punctuation">(</span><span class="Identifier">Person</span><span class="Punctuation">,</span> <span class="StringLit">"!nim:demo:Person"</span><span class="Punctuation">,</span>
|
||||
<span class="Identifier">yTagPerson</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">setTagUri</span><span class="Punctuation">(</span><span class="Identifier">Person</span><span class="Punctuation">,</span> <span class="StringLit">"!nim:demo:Person"</span><span class="Punctuation">,</span> <span class="Identifier">yTagPerson</span><span class="Punctuation">)</span>
|
||||
|
||||
<span class="Keyword">var</span>
|
||||
<span class="Identifier">s</span> <span class="Operator">=</span> <span class="Identifier">newFileStream</span><span class="Punctuation">(</span><span class="StringLit">"in.yaml"</span><span class="Punctuation">,</span> <span class="Identifier">fmRead</span><span class="Punctuation">)</span>
|
||||
|
|
@ -234,7 +233,7 @@
|
|||
<span class="Keyword">while</span> <span class="Identifier">nextEvent</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">!=</span> <span class="Identifier">yamlEndSeq</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">var</span> <span class="Identifier">curTag</span> <span class="Operator">=</span> <span class="Identifier">nextEvent</span><span class="Operator">.</span><span class="Identifier">tag</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">if</span> <span class="Identifier">curTag</span> <span class="Operator">==</span> <span class="Identifier">yTagQuestionMark</span><span class="Punctuation">:</span>
|
||||
<span class="Comment"># we only support implicitly tagged scalar events</span>
|
||||
<span class="Comment"># we only support implicitly tagged scalars</span>
|
||||
<span class="Identifier">assert</span> <span class="Identifier">nextEvent</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">==</span> <span class="Identifier">yamlScalar</span>
|
||||
<span class="Keyword">case</span> <span class="Identifier">guessType</span><span class="Punctuation">(</span><span class="Identifier">nextEvent</span><span class="Operator">.</span><span class="Identifier">scalarContent</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">yTypeInteger</span><span class="Punctuation">:</span> <span class="Identifier">curTag</span> <span class="Operator">=</span> <span class="Identifier">yTagInteger</span>
|
||||
|
|
@ -257,14 +256,11 @@
|
|||
<span class="Keyword">var</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">bool</span>
|
||||
<span class="Identifier">events</span><span class="Operator">.</span><span class="Identifier">constructChild</span><span class="Punctuation">(</span><span class="Identifier">context</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">echo</span> <span class="StringLit">"got boolean: "</span><span class="Punctuation">,</span> <span class="Identifier">b</span>
|
||||
<span class="Keyword">else</span><span class="Punctuation">:</span>
|
||||
<span class="Comment"># non-standard tag ids are not available</span>
|
||||
<span class="Comment"># at compile time</span>
|
||||
<span class="Keyword">if</span> <span class="Identifier">curTag</span> <span class="Operator">==</span> <span class="Identifier">yTagPerson</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">var</span> <span class="Identifier">p</span><span class="Punctuation">:</span> <span class="Identifier">Person</span>
|
||||
<span class="Identifier">events</span><span class="Operator">.</span><span class="Identifier">constructChild</span><span class="Punctuation">(</span><span class="Identifier">context</span><span class="Punctuation">,</span> <span class="Identifier">p</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">echo</span> <span class="StringLit">"got Person with name: "</span><span class="Punctuation">,</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">name</span>
|
||||
<span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">assert</span> <span class="Identifier">false</span><span class="Punctuation">,</span> <span class="StringLit">"unsupported tag: "</span> <span class="Operator">&</span> <span class="Operator">$</span><span class="Identifier">curTag</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">yTagPerson</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">var</span> <span class="Identifier">p</span><span class="Punctuation">:</span> <span class="Identifier">Person</span>
|
||||
<span class="Identifier">events</span><span class="Operator">.</span><span class="Identifier">constructChild</span><span class="Punctuation">(</span><span class="Identifier">context</span><span class="Punctuation">,</span> <span class="Identifier">p</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">echo</span> <span class="StringLit">"got Person with name: "</span><span class="Punctuation">,</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">name</span>
|
||||
<span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">assert</span> <span class="Identifier">false</span><span class="Punctuation">,</span> <span class="StringLit">"unsupported tag: "</span> <span class="Operator">&</span> <span class="Operator">$</span><span class="Identifier">curTag</span>
|
||||
<span class="Identifier">nextEvent</span> <span class="Operator">=</span> <span class="Identifier">events</span><span class="Operator">.</span><span class="Identifier">peek</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">assert</span> <span class="Identifier">events</span><span class="Operator">.</span><span class="Identifier">next</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">==</span> <span class="Identifier">yamlEndSeq</span>
|
||||
<span class="Identifier">assert</span> <span class="Identifier">events</span><span class="Operator">.</span><span class="Identifier">next</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">==</span> <span class="Identifier">yamlEndDoc</span>
|
||||
|
|
@ -283,7 +279,7 @@
|
|||
<div class="twelve-columns footer">
|
||||
<span class="nim-sprite"></span>
|
||||
<br/>
|
||||
<small>Made with Nim. Generated: 2016-04-01 22:08:47 UTC</small>
|
||||
<small>Made with Nim. Generated: 2016-04-21 19:00:52 UTC</small>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -37,16 +37,17 @@
|
|||
<p><strong>Important</strong>: NimYAML currently does not support polymorphism or variant object types. 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">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 is <em>not</em> supported, since its sice varies based on the target operation system. This makes it unfit for usage within NimYAML, because a value might not round-trip between a binary for a 32-bit OS and another binary for a 64-bit OS. 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">float32</span></tt> and <tt class="docutils literal"><span class="pre">float64</span></tt> are also supported, but <tt class="docutils literal"><span class="pre">float</span></tt> is not, for the same reason.</p>
|
||||
<p><tt class="docutils literal"><span class="pre">string</span></tt> is supported and one of the few Nim types which directly map to a standard YAML type. <tt class="docutils literal"><span class="pre">char</span></tt> is also supported.</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>
|
||||
<p><tt class="docutils literal"><span class="pre">string</span></tt> is supported and one of the few Nim types which directly map to a standard YAML type. NimYAML is able to handle strings that are <tt class="docutils literal"><span class="pre">nil</span></tt>, they will be serialized with the special tag <tt class="docutils literal"><span class="pre">!nim:nil:string</span></tt>. <tt class="docutils literal"><span class="pre">char</span></tt> is also supported.</p>
|
||||
<p>To support new scalar types, you must implement the <tt class="docutils literal"><span class="pre">constructObject()</span></tt> and <tt class="docutils literal"><span class="pre">representObject()</span></tt> procs on that type (see below).</p>
|
||||
|
||||
<h2 id="collection-types">Collection Types</h2><p>NimYAML supports Nim's <tt class="docutils literal"><span class="pre">seq</span></tt> and <tt class="docutils literal"><span class="pre">Table</span></tt> types out of the box. Unlike the native YAML types <tt class="docutils literal"><span class="pre">!!seq</span></tt> and <tt class="docutils literal"><span class="pre">!!map</span></tt>, <tt class="docutils literal"><span class="pre">seq</span></tt> and <tt class="docutils literal"><span class="pre">Table</span></tt> define the type of all their items (or keys and values). So YAML objects with heterogeneous types in them cannot be loaded to Nim collection types. For example, this sequence:</p>
|
||||
<h2 id="collection-types">Collection Types</h2><p>NimYAML supports Nim's <tt class="docutils literal"><span class="pre">array</span></tt>, <tt class="docutils literal"><span class="pre">set</span></tt>, <tt class="docutils literal"><span class="pre">seq</span></tt>, <tt class="docutils literal"><span class="pre">Table</span></tt> and <tt class="docutils literal"><span class="pre">OrderedTable</span></tt> types out of the box. Unlike the native YAML types <tt class="docutils literal"><span class="pre">!!seq</span></tt> and <tt class="docutils literal"><span class="pre">!!map</span></tt>, Nim's collection types define the type of all their contained items (or keys and values). So YAML objects with heterogeneous types in them cannot be loaded to Nim collection types. For example, this sequence:</p>
|
||||
<pre class = "listing"><span class="Directive">%YAML 1.2</span>
|
||||
<span class="Keyword">---</span> <span class="TagStart">!!seq</span>
|
||||
<span class="Punctuation">-</span> <span class="TagStart">!!int</span> <span class="DecNumber">1</span>
|
||||
<span class="Punctuation">-</span> <span class="TagStart">!!string</span> <span class="StringLit">foo</span></pre><p>Cannot be loaded to a Nim <tt class="docutils literal"><span class="pre">seq</span></tt>. For this reason, you cannot load YAML's native <tt class="docutils literal"><span class="pre">!!map</span></tt> and <tt class="docutils literal"><span class="pre">!!seq</span></tt> types directly into Nim types.</p>
|
||||
<p>Nim <tt class="docutils literal"><span class="pre">seq</span></tt> types may be <tt class="docutils literal"><span class="pre">nil</span></tt>. This is handled by serializing them to an empty scalar with the tag <tt class="docutils literal"><span class="pre">!nim:nil:seq</span></tt>.</p>
|
||||
|
||||
<h2 id="reference-types">Reference Types</h2><p>A reference to any supported non-reference type (including user defined types, see below) is supported by NimYAML. A reference type will be treated like its base type, but NimYAML is able to detect multiple references to the same object and dump the structure properly with anchors and aliases in place. It is possible to dump and load cyclic data structures without further configuration. It is possible for reference types to hold a <tt class="docutils literal"><span class="pre">nil</span></tt> value, which will be mapped to the <tt class="docutils literal"><span class="pre">!!null</span></tt> YAML scalar type.</p>
|
||||
<p>Pointer types are not supported because it seems dangerous to automatically allocate memory which the user must then manually deallocate.</p>
|
||||
|
|
@ -61,8 +62,8 @@
|
|||
|
||||
<h1 id="tags">Tags</h1><p>NimYAML uses local tags to represent Nim types that do not map directly to a YAML type. For example, <tt class="docutils literal"><span class="pre">int8</span></tt> is presented with the tag <tt class="docutils literal"><span class="pre">!nim:system:int8</span></tt>. Tags are mostly unnecessary when loading YAML data because the user already defines the target Nim type which usually defines all types of the structure. However, there is one case where a tag is necessary: A reference type with the value <tt class="docutils literal"><span class="pre">nil</span></tt> is represented in YAML as a <tt class="docutils literal"><span class="pre">!!null</span></tt> scalar. This will be automatically detected by type guessing, but if it is for example a reference to a string with the value <tt class="docutils literal"><span class="pre">"~"</span></tt>, it must be tagged with <tt class="docutils literal"><span class="pre">!!string</span></tt>, because otherwise, it would be loaded as <tt class="docutils literal"><span class="pre">nil</span></tt>.</p>
|
||||
<p>As you might have noticed in the example above, the YAML tag of a <tt class="docutils literal"><span class="pre">seq</span></tt> depends on its generic type parameter. The same applies to <tt class="docutils literal"><span class="pre">Table</span></tt>. So, a table that maps <tt class="docutils literal"><span class="pre">int8</span></tt> to string sequences would be presented with the tag <tt class="docutils literal"><span class="pre">!nim:tables:Table(nim:system:int8,nim:system:seq(tag:yaml.org,2002:string))</span></tt>. These tags are generated on the fly based on the types you instantiate <tt class="docutils literal"><span class="pre">Table</span></tt> or <tt class="docutils literal"><span class="pre">seq</span></tt> with.</p>
|
||||
<p>You may customize the tags used for your types by using the template <a class="reference external" href="yaml.html#setTagUriForType.t,typedesc,string">setTagUriForType</a>. It may not be applied to scalar and collection types implemented by NimYAML, but you can for example use it on a certain <tt class="docutils literal"><span class="pre">seq</span></tt> type:</p>
|
||||
<pre class = "listing"><span class="Identifier">setTagUriForType</span><span class="Punctuation">(</span><span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="StringLit">"!nim:my:seq"</span><span class="Punctuation">)</span></pre>
|
||||
<p>You may customize the tags used for your types by using the template <a class="reference external" href="yaml.html#setTagUri.t,typedesc,string">setTagUri</a>. It may not be applied to scalar and collection types implemented by NimYAML, but you can for example use it on a certain <tt class="docutils literal"><span class="pre">seq</span></tt> type:</p>
|
||||
<pre class = "listing"><span class="Identifier">setTagUri</span><span class="Punctuation">(</span><span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="StringLit">"!nim:my:seq"</span><span class="Punctuation">)</span></pre>
|
||||
<h1 id="customize-serialization">Customize Serialization</h1><p>It is possible to customize the serialization of a type. For this, you need to implement two procs, <tt class="docutils literal"><span class="pre">constructObject̀</span></tt> and <tt class="docutils literal"><span class="pre">representObject</span></tt>. If you only need to process the type in one direction (loading or dumping), you can omit the other proc.</p>
|
||||
|
||||
<h2 id="constructobject">constructObject</h2><pre class = "listing"><span class="Keyword">proc</span> <span class="Identifier">constructObject</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">YamlStream</span><span class="Punctuation">,</span> <span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">ConstructionContext</span><span class="Punctuation">,</span>
|
||||
|
|
@ -127,7 +128,7 @@
|
|||
<div class="twelve-columns footer">
|
||||
<span class="nim-sprite"></span>
|
||||
<br/>
|
||||
<small>Made with Nim. Generated: 2016-04-01 22:08:47 UTC</small>
|
||||
<small>Made with Nim. Generated: 2016-04-21 19:00:52 UTC</small>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
Loading…
Reference in New Issue