169 lines
5.9 KiB
ReStructuredText
169 lines
5.9 KiB
ReStructuredText
===============
|
|
Getting started
|
|
===============
|
|
|
|
Welcome to D:YAML! D:YAML is a `YAML <http://en.wikipedia.org/wiki/YAML>`_ parser
|
|
library for the `D programming language <http://d-p-l.org>`_. This tutorial will
|
|
explain how to set D:YAML up and use it in your projects.
|
|
|
|
This is meant to be the **simplest possible** introduction to D:YAML. Some of the
|
|
information present might already be known to you. Only basic usage is covered.
|
|
More advanced usage is described in other tutorials.
|
|
|
|
|
|
----------
|
|
Setting up
|
|
----------
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
Install the DMD compiler
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Digital Mars D compiler, or DMD, is the most commonly used D compiler. You can
|
|
find its newest version `here <http://www.digitalmars.com/d/download.html>`_.
|
|
Download the version of DMD for your operating system and install it.
|
|
|
|
.. note::
|
|
Other D compilers exist, such as
|
|
`GDC <http://bitbucket.org/goshawk/gdc/wiki/Home>`_ and
|
|
`LDC <http://www.dsource.org/projects/ldc/>`_.
|
|
Setting up with either one of them should be similar to DMD,
|
|
however, at the moment they are not as up to date as DMD.
|
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
Download and compile D:YAML
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The newest version of D:YAML can be found `here <TODO>`_. Download a source
|
|
archive, extract it, and move to the extracted directory.
|
|
|
|
D:YAML uses a modified version of the `CDC <http://dsource.org/projects/cdc/>`_
|
|
script for compilation. To compile D:YAML, you first need to build CDC.
|
|
Do this by typing the following command into the console::
|
|
|
|
dmd cdc.d
|
|
|
|
Now you can use CDC to compile D:YAML.
|
|
To do this on Unix/Linux, use the following command::
|
|
|
|
./cdc
|
|
|
|
On Windows::
|
|
|
|
cdc.exe
|
|
|
|
This will compile the library to a file called ``libdyaml.a`` on Unix/Linux or
|
|
``libdyaml.lib`` on Windows.
|
|
|
|
|
|
-------------------------
|
|
Your first D:YAML project
|
|
-------------------------
|
|
|
|
Create a directory for your project and in that directory, create a file called
|
|
``input.yaml`` with the following contents:
|
|
|
|
.. code-block:: yaml
|
|
|
|
Hello World :
|
|
- Hello
|
|
- World
|
|
Answer: 42
|
|
|
|
This will serve as input for our example.
|
|
|
|
Now we need to parse it. Create a file called "main.d". Paste following code
|
|
into the file:
|
|
|
|
.. code-block:: d
|
|
|
|
import std.stdio;
|
|
import yaml;
|
|
|
|
void main()
|
|
{
|
|
yaml.Node root = yaml.load("input.yaml");
|
|
foreach(string word; root["Hello World"])
|
|
{
|
|
writeln(word);
|
|
}
|
|
writeln("The answer is ", root["Answer"].get!int);
|
|
}
|
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
Explanation of the code
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
First, we import the *yaml* module. This is the only module you need to import
|
|
to use D:YAML - it automatically imports all needed modules.
|
|
|
|
Next we load the file using the *yaml.load()* function - this loads the file as
|
|
**one** YAML document and throws *YAMLException*, D:YAML exception type, if the
|
|
file could not be parsed or does not contain exactly one document. Note that we
|
|
don't do any error checking here in order to keep the example as simple as
|
|
possible.
|
|
|
|
*yaml.Node* 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 first, as it is a sequence, and use the
|
|
*yaml.Node.get()* method on the second to get its value as an integer.
|
|
|
|
You can iterate over a mapping or sequence as if it was an associative or normal
|
|
array. If you try to iterate over a scalar, it will throw a *YAMLException*.
|
|
|
|
You can iterate over subnodes using yaml.Node as the iterated type, or specify
|
|
the type subnodes are expected to have. D:YAML will automatically convert
|
|
iterated subnodes to that type if possible. Here we specify the *string* 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 *YAMLException* is thrown. For
|
|
instance, if we specified *int* here, we would get an error, as "Hello"
|
|
cannot be converted to an integer.
|
|
|
|
The *yaml.Node.get()* method is used to get value of a scalar node as specified
|
|
type. D:YAML will try to return the scalar as specified type, converting if
|
|
needed, throwing *YAMLException* if not possible.
|
|
|
|
|
|
^^^^^^^^^
|
|
Compiling
|
|
^^^^^^^^^
|
|
|
|
To compile your project, you must give DMD the directories containing import
|
|
modules and the library. You also need to tell it to link with D:YAML. The import
|
|
directory should be the D:YAML package directory. You can specify it using the
|
|
``-I`` option of DMD. The library directory should point to where you put the
|
|
compiled D:YAML library. On Unix/Linux you can specify it using the ``-L-L``
|
|
option, and link with D:YAML using the ``-L-l`` option. On Windows, the import
|
|
directory is used as the library directory. To link with the library on Windows,
|
|
just add the path to it relative to the current directory.
|
|
|
|
For example, if you extracted D:YAML to ``/home/xxx/dyaml`` and compiled it in
|
|
that directory, your project is in ``/home/xxx/dyaml-project``, and you are
|
|
currently in that directory, you can compile the project with the following
|
|
command on Unix/Linux::
|
|
|
|
dmd -I../dyaml -L-L../dyaml -L-ldyaml main.d
|
|
|
|
And the following on Windows::
|
|
|
|
dmd -I../dyaml ../dyaml/libdyaml.lib main.d
|
|
|
|
This will produce an executable called ``main`` or ``main.exe`` in your
|
|
directory. When you run it, it should produce the following output::
|
|
|
|
Hello
|
|
World
|
|
The answer is 42
|
|
|
|
|
|
^^^^^^^^^^
|
|
Conclusion
|
|
^^^^^^^^^^
|
|
|
|
You should now have a basic idea about how to use D:YAML. To learn more, look at
|
|
the `API documentation <../api/index.html>`_ and other tutorials. You can find code for this
|
|
example in the ``example/getting_started`` directory in the package.
|