mirror of https://github.com/status-im/NimYAML.git
54 lines
7.3 KiB
HTML
54 lines
7.3 KiB
HTML
<!DOCTYPE html>
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<title>NimYAML - API Overview</title>
|
|
|
|
<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>
|
|
<body>
|
|
<header>
|
|
<a class="pagetitle" href="/">NimYAML</a>
|
|
<a href="index.html">Home</a>
|
|
<a href="testing.html">Testing Ground</a>
|
|
<span>Docs:</span>
|
|
<a href="api.html">Overview</a>
|
|
<a href="serialization.html">Serialization</a>
|
|
<a href="yaml.html">Module yaml</a>
|
|
</header>
|
|
<article id="documentId">
|
|
<div class="container">
|
|
<h1 class="title">API Overview</h1>
|
|
|
|
<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>
|
|
<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>
|
|
<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>
|
|
|
|
|
|
|
|
<div class="row">
|
|
<div class="twelve-columns footer">
|
|
<span class="nim-sprite"></span>
|
|
<br/>
|
|
<small>Made with Nim. Generated: 2016-02-15 22:56:21 UTC</small>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</article>
|
|
</body>
|
|
</html>
|