<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Getting started — D:YAML 0.5 documentation</title> <link rel="stylesheet" href="../_static/default.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../', VERSION: '0.5', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <link rel="top" title="D:YAML 0.5 documentation" href="../index.html" /> <link rel="next" title="Custom YAML data types" href="custom_types.html" /> <link rel="prev" title="Welcome to D:YAML documentation!" href="../index.html" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="custom_types.html" title="Custom YAML data types" accesskey="N">next</a></li> <li class="right" > <a href="../index.html" title="Welcome to D:YAML documentation!" accesskey="P">previous</a> |</li> <li><a href="../index.html">D:YAML 0.5 documentation</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="getting-started"> <h1>Getting started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h1> <p>Welcome to D:YAML! D:YAML is a <a class="reference external" href="http://en.wikipedia.org/wiki/YAML">YAML</a> parser library for the <a class="reference external" href="http://dlang.org">D programming language</a>. This tutorial will explain how to set D:YAML up and use it in your projects.</p> <p>This is meant to be the <strong>simplest possible</strong> introduction to D:YAML. Some of this information might already be known to you. Only basic usage is covered.</p> <div class="section" id="setting-up"> <h2>Setting up<a class="headerlink" href="#setting-up" title="Permalink to this headline">¶</a></h2> <div class="section" id="install-the-dmd-compiler"> <h3>Install the DMD compiler<a class="headerlink" href="#install-the-dmd-compiler" title="Permalink to this headline">¶</a></h3> <p>Digital Mars D compiler, or DMD, is the most commonly used D compiler. You can find its newest version <a class="reference external" href="http://dlang.org/download.html">here</a>. Download the version of DMD for your operating system and install it.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">Other D compilers exist, such as <a class="reference external" href="http://gdcproject.org/">GDC</a> and <a class="reference external" href="http://bitbucket.org/goshawk/gdc/wiki/Home">LDC</a>.</p> </div> </div> <div class="section" id="install-dub"> <h3>Install dub<a class="headerlink" href="#install-dub" title="Permalink to this headline">¶</a></h3> <p><a class="reference external" href="http://code.dlang.org/about">dub</a> is a build system and package manager for D. It is the standard way to manage D projects and their dependencies, compilation and so on.</p> <p>DMD may include DUB in future releases, but at this point we need to install it separately. See <a class="reference external" href="https://github.com/D-Programming-Language/dub#installation">installation instructions</a>.</p> </div> </div> <div class="section" id="your-first-d-yaml-project"> <h2>Your first D:YAML project<a class="headerlink" href="#your-first-d-yaml-project" title="Permalink to this headline">¶</a></h2> <p>Create a directory for your project and in that directory, create a new file named <tt class="docutils literal"><span class="pre">input.yaml</span></tt> and paste this code into the file:</p> <div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">Hello World</span> <span class="p-Indicator">:</span> <span class="p-Indicator">[</span><span class="nv">Hello</span><span class="p-Indicator">,</span> <span class="nv">World</span><span class="p-Indicator">]</span> <span class="l-Scalar-Plain">Answer</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">42</span> </pre></div> </div> <p>This will serve as input for our example.</p> <p>Now we need to parse it. Create a new file with name <tt class="docutils literal"><span class="pre">main.d</span></tt>. Paste following code into the file:</p> <div class="highlight-d"><div class="highlight"><pre><span class="k">import</span> <span class="n">std</span><span class="p">.</span><span class="n">stdio</span><span class="p">;</span> <span class="k">import</span> <span class="n">yaml</span><span class="p">;</span> <span class="kt">void</span> <span class="n">main</span><span class="p">()</span> <span class="p">{</span> <span class="c1">//Read the input.</span> <span class="n">Node</span> <span class="n">root</span> <span class="p">=</span> <span class="n">Loader</span><span class="p">(</span><span class="s">"input.yaml"</span><span class="p">).</span><span class="n">load</span><span class="p">();</span> <span class="c1">//Display the data read.</span> <span class="k">foreach</span><span class="p">(</span><span class="nb">string</span> <span class="n">word</span><span class="p">;</span> <span class="n">root</span><span class="p">[</span><span class="s">"Hello World"</span><span class="p">])</span> <span class="p">{</span> <span class="n">writeln</span><span class="p">(</span><span class="n">word</span><span class="p">);</span> <span class="p">}</span> <span class="n">writeln</span><span class="p">(</span><span class="s">"The answer is "</span><span class="p">,</span> <span class="n">root</span><span class="p">[</span><span class="s">"Answer"</span><span class="p">].</span><span class="n">as</span><span class="p">!</span><span class="kt">int</span><span class="p">);</span> <span class="c1">//Dump the loaded document to output.yaml.</span> <span class="n">Dumper</span><span class="p">(</span><span class="s">"output.yaml"</span><span class="p">).</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">);</span> <span class="p">}</span> </pre></div> </div> <div class="section" id="explanation-of-the-code"> <h3>Explanation of the code<a class="headerlink" href="#explanation-of-the-code" title="Permalink to this headline">¶</a></h3> <p>First, we import the <em>dyaml.all</em> module. This is the only D:YAML module you need to import - it automatically imports all needed modules.</p> <p>Next we load the file using the <em>Loader.load()</em> method. <em>Loader</em> is a struct used for parsing YAML documents. The <em>load()</em> method loads the file as <strong>one</strong> YAML document, or throws <em>YAMLException</em>, D:YAML exception type, if the file could not be parsed or contains more than one document. Note that we don’t do any error checking here in order to keep the example as simple as possible.</p> <p><em>Node</em> represents a node in a YAML document. It can be a sequence (array), mapping (associative array) or a scalar (value). Here the root node is a mapping, and we use the index operator to get subnodes with keys “Hello World” and “Answer”. We iterate over the former, as it is a sequence, and use the <em>Node.as()</em> method on the latter to read its value as an integer.</p> <p>You can iterate over a mapping or sequence as if it was an associative or normal array, respectively. If you try to iterate over a scalar, it will throw a <em>YAMLException</em>.</p> <p>You can iterate using <em>Node</em> as the iterated type, or specify the type iterated nodes are expected to have. D:YAML will automatically convert to that type if possible. Here we specify the <em>string</em> type, so we iterate over the “Hello World” sequence as an array of strings. If it is not possible to convert to iterated type, a <em>YAMLException</em> is thrown. For instance, if we specified <em>int</em> here, we would get an error, as “Hello” cannot be converted to an integer.</p> <p>The <em>Node.as()</em> method is used to read value of a scalar node as specified type. If the scalar does not have the specified type, D:YAML will try to convert it, throwing <em>YAMLException</em> if not possible.</p> <p>Finally we dump the document we just read to <tt class="docutils literal"><span class="pre">output.yaml</span></tt> with the <em>Dumper.dump()</em> method. <em>Dumper</em> is a struct used to dump YAML documents. The <em>dump()</em> method writes one or more documents to a file, throwing <em>YAMLException</em> if the file could not be written to.</p> <p>D:YAML tries to preserve style information in documents so e.g. <tt class="docutils literal"><span class="pre">[Hello,</span> <span class="pre">World]</span></tt> is not turned into:</p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">-</span> <span class="pre">Hello</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">-</span> <span class="pre">World</span></tt></div> </div> <p>However, comments are not preserved and neither are any extra formatting whitespace that doesn’t affect the meaning of YAML contents.</p> </div> <div class="section" id="compiling"> <h3>Compiling<a class="headerlink" href="#compiling" title="Permalink to this headline">¶</a></h3> <p>We’re going to use dub, which we installed at the beginning, to compile our project.</p> <p>Create a file called <tt class="docutils literal"><span class="pre">dub.json</span></tt> with the following contents:</p> <div class="highlight-json"><div class="highlight"><pre><span class="p">{</span> <span class="nt">"name"</span><span class="p">:</span> <span class="s2">"getting-started"</span><span class="p">,</span> <span class="nt">"targetType"</span><span class="p">:</span> <span class="s2">"executable"</span><span class="p">,</span> <span class="nt">"sourceFiles"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"main.d"</span><span class="p">],</span> <span class="nt">"mainSourceFile"</span><span class="p">:</span> <span class="s2">"main.d"</span><span class="p">,</span> <span class="nt">"dependencies"</span><span class="p">:</span> <span class="p">{</span> <span class="nt">"dyaml"</span><span class="p">:</span> <span class="p">{</span> <span class="nt">"version"</span> <span class="p">:</span> <span class="s2">"~>0.5.0"</span> <span class="p">},</span> <span class="p">},</span> <span class="p">}</span> </pre></div> </div> <p>This file tells dub that we’re building an executable called <tt class="docutils literal"><span class="pre">getting-started</span></tt> from a D source file <tt class="docutils literal"><span class="pre">main.d</span></tt>, and that our project depends on D:YAML 0.5.0 or any newer, bugfix release of D:YAML 0.5 . DUB will automatically find and download the correct version of D:YAML when the project is built.</p> <p>Now run the following command in your project’s directory:</p> <div class="highlight-python"><div class="highlight"><pre>dub build </pre></div> </div> <p>dub will automatically download D:YAML and compile it, and then then it will compile our program. This will generate an executable called <tt class="docutils literal"><span class="pre">getting-started</span></tt> or <tt class="docutils literal"><span class="pre">getting-started.exe</span></tt> in your directory. When you run it, it should produce the following output:</p> <div class="highlight-python"><div class="highlight"><pre>Hello World The answer is 42 </pre></div> </div> </div> <div class="section" id="conclusion"> <h3>Conclusion<a class="headerlink" href="#conclusion" title="Permalink to this headline">¶</a></h3> <p>You should now have a basic idea about how to use D:YAML. To learn more, look at the <a class="reference external" href="../api/index.html">API documentation</a> and other tutorials. You can find code for this example in the <tt class="docutils literal"><span class="pre">example/getting_started</span></tt> directory in the package.</p> </div> </div> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <p class="logo"><a href="../index.html"> <img class="logo" src="../_static/logo210.png" alt="Logo"/> </a></p> <h3><a href="../index.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">Getting started</a><ul> <li><a class="reference internal" href="#setting-up">Setting up</a><ul> <li><a class="reference internal" href="#install-the-dmd-compiler">Install the DMD compiler</a></li> <li><a class="reference internal" href="#install-dub">Install dub</a></li> </ul> </li> <li><a class="reference internal" href="#your-first-d-yaml-project">Your first D:YAML project</a><ul> <li><a class="reference internal" href="#explanation-of-the-code">Explanation of the code</a></li> <li><a class="reference internal" href="#compiling">Compiling</a></li> <li><a class="reference internal" href="#conclusion">Conclusion</a></li> </ul> </li> </ul> </li> </ul> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="custom_types.html" title="Custom YAML data types" >next</a></li> <li class="right" > <a href="../index.html" title="Welcome to D:YAML documentation!" >previous</a> |</li> <li><a href="../index.html">D:YAML 0.5 documentation</a> »</li> </ul> </div> <div class="footer"> © Copyright 2011-2014, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov. Last updated on Aug 06, 2014. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2. </div> </body> </html>