PageRenderTime 76ms CodeModel.GetById 21ms RepoModel.GetById 1ms app.codeStats 0ms

/doc/html/tutorials/getting_started.html

http://github.com/kiith-sa/D-YAML
HTML | 241 lines | 228 code | 13 blank | 0 comment | 0 complexity | aa139915f18dfcbc8b25360465150aaa MD5 | raw file
    

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    2. 

  2.   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    3. 

  3. 

  4. 

  5. <html xmlns="http://www.w3.org/1999/xhtml">
    6. 

  6.   <head>
    7. 

  7.     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    8. 

  8.     
    9. 

  9.     <title>Getting started &mdash; D:YAML 0.5 documentation</title>
    10. 

  10.     
    11. 

  11.     <link rel="stylesheet" href="../_static/default.css" type="text/css" />
    12. 

  12.     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    13. 

  13.     
    14. 

  14.     <script type="text/javascript">
    15. 

  15.       var DOCUMENTATION_OPTIONS = {
    16. 

  16.         URL_ROOT:    '../',
    17. 

  17.         VERSION:     '0.5',
    18. 

  18.         COLLAPSE_INDEX: false,
    19. 

  19.         FILE_SUFFIX: '.html',
    20. 

  20.         HAS_SOURCE:  true
    21. 

  21.       };
    22. 

  22.     </script>
    23. 

  23.     <script type="text/javascript" src="../_static/jquery.js"></script>
    24. 

  24.     <script type="text/javascript" src="../_static/underscore.js"></script>
    25. 

  25.     <script type="text/javascript" src="../_static/doctools.js"></script>
    26. 

  26.     <link rel="top" title="D:YAML 0.5 documentation" href="../index.html" />
    27. 

  27.     <link rel="next" title="Custom YAML data types" href="custom_types.html" />
    28. 

  28.     <link rel="prev" title="Welcome to D:YAML documentation!" href="../index.html" /> 
    29. 

  29.   </head>
    30. 

  30.   <body>
    31. 

  31.     <div class="related">
    32. 

  32.       <h3>Navigation</h3>
    33. 

  33.       <ul>
    34. 

  34.         <li class="right" style="margin-right: 10px">
    35. 

  35.           <a href="custom_types.html" title="Custom YAML data types"
    36. 

  36.              accesskey="N">next</a></li>
    37. 

  37.         <li class="right" >
    38. 

  38.           <a href="../index.html" title="Welcome to D:YAML documentation!"
    39. 

  39.              accesskey="P">previous</a> |</li>
    40. 

  40.         <li><a href="../index.html">D:YAML 0.5 documentation</a> &raquo;</li> 
    41. 

  41.       </ul>
    42. 

  42.     </div>  
    43. 

  43. 

  44.     <div class="document">
    45. 

  45.       <div class="documentwrapper">
    46. 

  46.         <div class="bodywrapper">
    47. 

  47.           <div class="body">
    48. 

  48.             
    49. 

  49.   <div class="section" id="getting-started">
    50. 

  50. <h1>Getting started<a class="headerlink" href="#getting-started" title="Permalink to this headline"></a></h1>
    51. 

  51. <p>Welcome to D:YAML! D:YAML is a <a class="reference external" href="http://en.wikipedia.org/wiki/YAML">YAML</a> parser
    52. 

  52. library for the <a class="reference external" href="http://dlang.org">D programming language</a>.  This tutorial will
    53. 

  53. explain how to set D:YAML up and use it in your projects.</p>
    54. 

  54. <p>This is meant to be the <strong>simplest possible</strong> introduction to D:YAML. Some of this
    55. 

  55. information might already be known to you. Only basic usage is covered.</p>
    56. 

  56. <div class="section" id="setting-up">
    57. 

  57. <h2>Setting up<a class="headerlink" href="#setting-up" title="Permalink to this headline"></a></h2>
    58. 

  58. <div class="section" id="install-the-dmd-compiler">
    59. 

  59. <h3>Install the DMD compiler<a class="headerlink" href="#install-the-dmd-compiler" title="Permalink to this headline"></a></h3>
    60. 

  60. <p>Digital Mars D compiler, or DMD, is the most commonly used D compiler. You can find its
    61. 

  61. newest version <a class="reference external" href="http://dlang.org/download.html">here</a>.  Download the version of DMD
    62. 

  62. for your operating system and install it.</p>
    63. 

  63. <div class="admonition note">
    64. 

  64. <p class="first admonition-title">Note</p>
    65. 

  65. <p class="last">Other D compilers exist, such as
    66. 

  66. <a class="reference external" href="http://gdcproject.org/">GDC</a> and
    67. 

  67. <a class="reference external" href="http://bitbucket.org/goshawk/gdc/wiki/Home">LDC</a>.</p>
    68. 

  68. </div>
    69. 

  69. </div>
    70. 

  70. <div class="section" id="install-dub">
    71. 

  71. <h3>Install dub<a class="headerlink" href="#install-dub" title="Permalink to this headline"></a></h3>
    72. 

  72. <p><a class="reference external" href="http://code.dlang.org/about">dub</a> is a build system and package manager for D.
    73. 

  73. It is the standard way to manage D projects and their dependencies, compilation and so
    74. 

  74. on.</p>
    75. 

  75. <p>DMD may include DUB in future releases, but at this point we need to install it
    76. 

  76. separately. See
    77. 

  77. <a class="reference external" href="https://github.com/D-Programming-Language/dub#installation">installation instructions</a>.</p>
    78. 

  78. </div>
    79. 

  79. </div>
    80. 

  80. <div class="section" id="your-first-d-yaml-project">
    81. 

  81. <h2>Your first D:YAML project<a class="headerlink" href="#your-first-d-yaml-project" title="Permalink to this headline"></a></h2>
    82. 

  82. <p>Create a directory for your project and in that directory, create a new file named
    83. 

  83. <tt class="docutils literal"><span class="pre">input.yaml</span></tt> and paste this code into the file:</p>
    84. 

  84. <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>
    85. 

  85. <span class="l-Scalar-Plain">Answer</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">42</span>
    86. 

  86. </pre></div>
    87. 

  87. </div>
    88. 

  88. <p>This will serve as input for our example.</p>
    89. 

  89. <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
    90. 

  90. into the file:</p>
    91. 

  91. <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>
    92. 

  92. <span class="k">import</span> <span class="n">yaml</span><span class="p">;</span>
    93. 

  93. 

  94. <span class="kt">void</span> <span class="n">main</span><span class="p">()</span>
    95. 

  95. <span class="p">{</span>
    96. 

  96.     <span class="c1">//Read the input.</span>
    97. 

  97.     <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">&quot;input.yaml&quot;</span><span class="p">).</span><span class="n">load</span><span class="p">();</span>
    98. 

  98. 

  99.     <span class="c1">//Display the data read.</span>
    100. 

  100.     <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">&quot;Hello World&quot;</span><span class="p">])</span>
    101. 

  101.     <span class="p">{</span>
    102. 

  102.         <span class="n">writeln</span><span class="p">(</span><span class="n">word</span><span class="p">);</span>
    103. 

  103.     <span class="p">}</span>
    104. 

  104.     <span class="n">writeln</span><span class="p">(</span><span class="s">&quot;The answer is &quot;</span><span class="p">,</span> <span class="n">root</span><span class="p">[</span><span class="s">&quot;Answer&quot;</span><span class="p">].</span><span class="n">as</span><span class="p">!</span><span class="kt">int</span><span class="p">);</span>
    105. 

  105. 

  106.     <span class="c1">//Dump the loaded document to output.yaml.</span>
    107. 

  107.     <span class="n">Dumper</span><span class="p">(</span><span class="s">&quot;output.yaml&quot;</span><span class="p">).</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">);</span>
    108. 

  108. <span class="p">}</span>
    109. 

  109. </pre></div>
    110. 

  110. </div>
    111. 

  111. <div class="section" id="explanation-of-the-code">
    112. 

  112. <h3>Explanation of the code<a class="headerlink" href="#explanation-of-the-code" title="Permalink to this headline"></a></h3>
    113. 

  113. <p>First, we import the <em>dyaml.all</em> module. This is the only D:YAML module you need to
    114. 

  114. import - it automatically imports all needed modules.</p>
    115. 

  115. <p>Next we load the file using the <em>Loader.load()</em> method. <em>Loader</em> is a struct used for
    116. 

  116. parsing YAML documents. The <em>load()</em> method loads the file as <strong>one</strong> YAML document, or
    117. 

  117. throws <em>YAMLException</em>, D:YAML exception type, if the file could not be parsed or
    118. 

  118. contains more than one document.  Note that we don&#8217;t do any error checking here in order
    119. 

  119. to keep the example as simple as possible.</p>
    120. 

  120. <p><em>Node</em> represents a node in a YAML document. It can be a sequence (array), mapping
    121. 

  121. (associative array) or a scalar (value). Here the root node is a mapping, and we use the
    122. 

  122. index operator to get subnodes with keys &#8220;Hello World&#8221; and &#8220;Answer&#8221;. We iterate over the
    123. 

  123. former, as it is a sequence, and use the <em>Node.as()</em> method on the latter to read its
    124. 

  124. value as an integer.</p>
    125. 

  125. <p>You can iterate over a mapping or sequence as if it was an associative or normal array,
    126. 

  126. respectively.  If you try to iterate over a scalar, it will throw a <em>YAMLException</em>.</p>
    127. 

  127. <p>You can iterate using <em>Node</em> as the iterated type, or specify the type iterated nodes
    128. 

  128. are expected to have. D:YAML will automatically convert to that type if possible. Here
    129. 

  129. we specify the <em>string</em> type, so we iterate over the &#8220;Hello World&#8221; sequence as an array
    130. 

  130. of strings. If it is not possible to convert to iterated type, a <em>YAMLException</em> is
    131. 

  131. thrown. For instance, if we specified <em>int</em> here, we would get an error, as &#8220;Hello&#8221;
    132. 

  132. cannot be converted to an integer.</p>
    133. 

  133. <p>The <em>Node.as()</em> method is used to read value of a scalar node as specified type.  If the
    134. 

  134. scalar does not have the specified type, D:YAML will try to convert it, throwing
    135. 

  135. <em>YAMLException</em> if not possible.</p>
    136. 

  136. <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>
    137. 

  137. method. <em>Dumper</em> is a struct used to dump YAML documents.  The <em>dump()</em> method writes
    138. 

  138. one or more documents to a file, throwing <em>YAMLException</em> if the file could not be
    139. 

  139. written to.</p>
    140. 

  140. <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
    141. 

  141. not turned into:</p>
    142. 

  142. <div class="line-block">
    143. 

  143. <div class="line"><tt class="docutils literal"><span class="pre">-</span> <span class="pre">Hello</span></tt></div>
    144. 

  144. <div class="line"><tt class="docutils literal"><span class="pre">-</span> <span class="pre">World</span></tt></div>
    145. 

  145. </div>
    146. 

  146. <p>However, comments are not preserved and neither are any extra formatting whitespace that
    147. 

  147. doesn&#8217;t affect the meaning of YAML contents.</p>
    148. 

  148. </div>
    149. 

  149. <div class="section" id="compiling">
    150. 

  150. <h3>Compiling<a class="headerlink" href="#compiling" title="Permalink to this headline"></a></h3>
    151. 

  151. <p>We&#8217;re going to use dub, which we installed at the beginning, to compile our project.</p>
    152. 

  152. <p>Create a file called <tt class="docutils literal"><span class="pre">dub.json</span></tt> with the following contents:</p>
    153. 

  153. <div class="highlight-json"><div class="highlight"><pre><span class="p">{</span>
    154. 

  154.     <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;getting-started&quot;</span><span class="p">,</span>
    155. 

  155.     <span class="nt">&quot;targetType&quot;</span><span class="p">:</span> <span class="s2">&quot;executable&quot;</span><span class="p">,</span>
    156. 

  156.     <span class="nt">&quot;sourceFiles&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;main.d&quot;</span><span class="p">],</span>
    157. 

  157.     <span class="nt">&quot;mainSourceFile&quot;</span><span class="p">:</span> <span class="s2">&quot;main.d&quot;</span><span class="p">,</span>
    158. 

  158.     <span class="nt">&quot;dependencies&quot;</span><span class="p">:</span>
    159. 

  159.     <span class="p">{</span>
    160. 

  160.         <span class="nt">&quot;dyaml&quot;</span><span class="p">:</span> <span class="p">{</span> <span class="nt">&quot;version&quot;</span> <span class="p">:</span> <span class="s2">&quot;~&gt;0.5.0&quot;</span> <span class="p">},</span>
    161. 

  161.     <span class="p">},</span>
    162. 

  162. <span class="p">}</span>
    163. 

  163. </pre></div>
    164. 

  164. </div>
    165. 

  165. <p>This file tells dub that we&#8217;re building an executable called <tt class="docutils literal"><span class="pre">getting-started</span></tt> from
    166. 

  166. 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,
    167. 

  167. bugfix release of D:YAML 0.5 . DUB will automatically find and download the correct
    168. 

  168. version of D:YAML when the project is built.</p>
    169. 

  169. <p>Now run the following command in your project&#8217;s directory:</p>
    170. 

  170. <div class="highlight-python"><div class="highlight"><pre>dub build
    171. 

  171. </pre></div>
    172. 

  172. </div>
    173. 

  173. <p>dub will automatically download D:YAML and compile it, and then then it will compile our
    174. 

  174. program.  This will generate an executable called <tt class="docutils literal"><span class="pre">getting-started</span></tt> or
    175. 

  175. <tt class="docutils literal"><span class="pre">getting-started.exe</span></tt> in your directory.  When you run it, it should produce the
    176. 

  176. following output:</p>
    177. 

  177. <div class="highlight-python"><div class="highlight"><pre>Hello
    178. 

  178. World
    179. 

  179. The answer is 42
    180. 

  180. </pre></div>
    181. 

  181. </div>
    182. 

  182. </div>
    183. 

  183. <div class="section" id="conclusion">
    184. 

  184. <h3>Conclusion<a class="headerlink" href="#conclusion" title="Permalink to this headline"></a></h3>
    185. 

  185. <p>You should now have a basic idea about how to use D:YAML. To learn more, look at the
    186. 

  186. <a class="reference external" href="../api/index.html">API documentation</a> and other tutorials. You can find code for this
    187. 

  187. example in the <tt class="docutils literal"><span class="pre">example/getting_started</span></tt> directory in the package.</p>
    188. 

  188. </div>
    189. 

  189. </div>
    190. 

  190. </div>
    191. 

  191. 

  192. 

  193.           </div>
    194. 

  194.         </div>
    195. 

  195.       </div>
    196. 

  196.       <div class="sphinxsidebar">
    197. 

  197.         <div class="sphinxsidebarwrapper">
    198. 

  198.             <p class="logo"><a href="../index.html">
    199. 

  199.               <img class="logo" src="../_static/logo210.png" alt="Logo"/>
    200. 

  200.             </a></p>
    201. 

  201.   <h3><a href="../index.html">Table Of Contents</a></h3>
    202. 

  202.   <ul>
    203. 

  203. <li><a class="reference internal" href="#">Getting started</a><ul>
    204. 

  204. <li><a class="reference internal" href="#setting-up">Setting up</a><ul>
    205. 

  205. <li><a class="reference internal" href="#install-the-dmd-compiler">Install the DMD compiler</a></li>
    206. 

  206. <li><a class="reference internal" href="#install-dub">Install dub</a></li>
    207. 

  207. </ul>
    208. 

  208. </li>
    209. 

  209. <li><a class="reference internal" href="#your-first-d-yaml-project">Your first D:YAML project</a><ul>
    210. 

  210. <li><a class="reference internal" href="#explanation-of-the-code">Explanation of the code</a></li>
    211. 

  211. <li><a class="reference internal" href="#compiling">Compiling</a></li>
    212. 

  212. <li><a class="reference internal" href="#conclusion">Conclusion</a></li>
    213. 

  213. </ul>
    214. 

  214. </li>
    215. 

  215. </ul>
    216. 

  216. </li>
    217. 

  217. </ul>
    218. 

  218. 

  219.         </div>
    220. 

  220.       </div>
    221. 

  221.       <div class="clearer"></div>
    222. 

  222.     </div>
    223. 

  223.     <div class="related">
    224. 

  224.       <h3>Navigation</h3>
    225. 

  225.       <ul>
    226. 

  226.         <li class="right" style="margin-right: 10px">
    227. 

  227.           <a href="custom_types.html" title="Custom YAML data types"
    228. 

  228.              >next</a></li>
    229. 

  229.         <li class="right" >
    230. 

  230.           <a href="../index.html" title="Welcome to D:YAML documentation!"
    231. 

  231.              >previous</a> |</li>
    232. 

  232.         <li><a href="../index.html">D:YAML 0.5 documentation</a> &raquo;</li> 
    233. 

  233.       </ul>
    234. 

  234.     </div>
    235. 

  235.     <div class="footer">
    236. 

  236.         &copy; Copyright 2011-2014, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
    237. 

  237.       Last updated on Aug 06, 2014.
    238. 

  238.       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
    239. 

  239.     </div>
    240. 

  240.   </body>
    241. 

  241. </html>
    242.