2011-08-16 12:53:13 +00:00
< !DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2013-12-17 14:19:01 +00:00
2011-08-16 12:53:13 +00:00
< html xmlns = "http://www.w3.org/1999/xhtml" >
< head >
< meta http-equiv = "Content-Type" content = "text/html; charset=utf-8" / >
2014-08-01 01:00:40 +00:00
< title > Getting started — D:YAML 0.5 documentation< / title >
2013-12-17 14:19:01 +00:00
2011-08-16 12:53:13 +00:00
< link rel = "stylesheet" href = "../_static/default.css" type = "text/css" / >
< link rel = "stylesheet" href = "../_static/pygments.css" type = "text/css" / >
2013-12-17 14:19:01 +00:00
2011-08-16 12:53:13 +00:00
< script type = "text/javascript" >
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
2014-08-01 01:00:40 +00:00
VERSION: '0.5',
2011-08-16 12:53:13 +00:00
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 >
2014-08-01 01:00:40 +00:00
< link rel = "top" title = "D:YAML 0.5 documentation" href = "../index.html" / >
2011-08-16 12:53:13 +00:00
< 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 >
2014-08-01 01:00:40 +00:00
< li > < a href = "../index.html" > D:YAML 0.5 documentation< / a > » < / li >
2011-08-16 12:53:13 +00:00
< / 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 >
2014-08-01 15:09:38 +00:00
< 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 >
2011-08-16 12:53:13 +00:00
< 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 >
2014-08-01 15:09:38 +00:00
< 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 >
2011-08-16 12:53:13 +00:00
< div class = "admonition note" >
< p class = "first admonition-title" > Note< / p >
< p class = "last" > Other D compilers exist, such as
2014-08-01 01:00:40 +00:00
< 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 >
2011-08-16 12:53:13 +00:00
< / div >
< / div >
2014-08-01 15:09:38 +00:00
< 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 >
2011-08-16 12:53:13 +00:00
< / 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 >
2014-08-01 15:09:38 +00:00
< 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 >
2011-08-16 12:53:13 +00:00
< 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 >
2014-08-01 15:09:38 +00:00
< 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
2011-08-16 12:53:13 +00:00
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 >
2014-08-01 01:00:40 +00:00
< span class = "k" > import< / span > < span class = "n" > yaml< / span > < span class = "p" > ;< / span >
2011-08-16 12:53:13 +00:00
< span class = "kt" > void< / span > < span class = "n" > main< / span > < span class = "p" > ()< / span >
< span class = "p" > {< / span >
2011-10-15 14:31:23 +00:00
< span class = "c1" > //Read the input.< / span >
2011-10-14 08:34:53 +00:00
< 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 >
2011-10-15 14:31:23 +00:00
< span class = "c1" > //Display the data read.< / span >
2011-08-16 12:53:13 +00:00
< 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 >
2011-10-22 15:06:32 +00:00
< 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 >
2011-10-15 14:31:23 +00:00
< 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 >
2011-08-16 12:53:13 +00:00
< 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 >
2014-08-01 15:09:38 +00:00
< 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”
2011-08-16 12:53:13 +00:00
cannot be converted to an integer.< / p >
2014-08-01 15:09:38 +00:00
< 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 >
2011-08-16 12:53:13 +00:00
< / div >
< div class = "section" id = "compiling" >
< h3 > Compiling< a class = "headerlink" href = "#compiling" title = "Permalink to this headline" > ¶< / a > < / h3 >
2014-08-01 15:09:38 +00:00
< 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 = "nt" > " path" < / span > < span class = "p" > :< / span > < span class = "s2" > " ../../" < / span > < span class = "p" > },< / span >
< span class = "p" > },< / span >
< span class = "p" > }< / span >
2014-08-01 01:00:40 +00:00
< / pre > < / div >
2011-08-16 12:53:13 +00:00
< / div >
2014-08-01 15:09:38 +00:00
< 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
2014-08-01 01:00:40 +00:00
< / pre > < / div >
2011-08-16 12:53:13 +00:00
< / div >
2014-08-01 15:09:38 +00:00
< 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 >
2014-08-01 01:00:40 +00:00
< div class = "highlight-python" > < div class = "highlight" > < pre > Hello
2011-08-16 12:53:13 +00:00
World
2014-08-01 01:00:40 +00:00
The answer is 42
< / pre > < / div >
2011-08-16 12:53:13 +00:00
< / div >
< / div >
< div class = "section" id = "conclusion" >
< h3 > Conclusion< a class = "headerlink" href = "#conclusion" title = "Permalink to this headline" > ¶< / a > < / h3 >
2014-08-01 15:09:38 +00:00
< 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
2011-08-16 12:53:13 +00:00
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 >
2014-08-01 15:09:38 +00:00
< li > < a class = "reference internal" href = "#install-dub" > Install dub< / a > < / li >
2011-08-16 12:53:13 +00:00
< / 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 >
2014-08-01 01:00:40 +00:00
< li > < a href = "../index.html" > D:YAML 0.5 documentation< / a > » < / li >
2011-08-16 12:53:13 +00:00
< / ul >
< / div >
< div class = "footer" >
2014-05-19 17:54:48 +00:00
© Copyright 2011-2014, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
2014-08-01 01:00:40 +00:00
Last updated on Aug 01, 2014.
Created using < a href = "http://sphinx-doc.org/" > Sphinx< / a > 1.2.2.
2011-08-16 12:53:13 +00:00
< / div >
< / body >
< / html >
