Updated 'Getting Started' with dub info.
This commit is contained in:
Ferdinand Majerech
parent
e02bd73096
commit
278b60e896
|
|
@ -2,12 +2,12 @@
|
|||
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://dlang.org>`_.
|
||||
This tutorial will explain how to set D:YAML up and use it in your projects.
|
||||
Welcome to D:YAML! D:YAML is a `YAML <http://en.wikipedia.org/wiki/YAML>`_ parser
|
||||
library for the `D programming language <http://dlang.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
|
||||
this information might already be known to you. Only basic usage is covered.
|
||||
This is meant to be the **simplest possible** introduction to D:YAML. Some of this
|
||||
information might already be known to you. Only basic usage is covered.
|
||||
|
||||
|
||||
----------
|
||||
|
|
@ -18,59 +18,43 @@ 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://dlang.org/download.html>`_.
|
||||
Download the version of DMD for your operating system and install it.
|
||||
Digital Mars D compiler, or DMD, is the most commonly used D compiler. You can find its
|
||||
newest version `here <http://dlang.org/download.html>`_. Download the version of DMD
|
||||
for your operating system and install it.
|
||||
|
||||
.. note::
|
||||
Other D compilers exist, such as
|
||||
`GDC <http://gdcproject.org/>`_ and
|
||||
`LDC <http://bitbucket.org/goshawk/gdc/wiki/Home>`_.
|
||||
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Download and compile D:YAML
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
^^^^^^^^^^^
|
||||
Install dub
|
||||
^^^^^^^^^^^
|
||||
|
||||
The newest version of D:YAML can be found
|
||||
`here <https://github.com/Kiith-Sa/D-YAML>`_. Download a source archive, extract
|
||||
it, and move to the extracted directory.
|
||||
`dub <http://code.dlang.org/about>`_ 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.
|
||||
|
||||
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 compile D:YAML with CDC.
|
||||
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.
|
||||
DMD may include DUB in future releases, but at this point we need to install it
|
||||
separately. See
|
||||
`installation instructions <https://github.com/D-Programming-Language/dub#installation>`_.
|
||||
|
||||
|
||||
-------------------------
|
||||
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:
|
||||
Create a directory for your project and in that directory, create a new file named
|
||||
``input.yaml`` and paste this code into the file:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
Hello World :
|
||||
- Hello
|
||||
- World
|
||||
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
|
||||
Now we need to parse it. Create a new file with name ``main.d``. Paste following code
|
||||
into the file:
|
||||
|
||||
.. code-block:: d
|
||||
|
|
@ -99,73 +83,84 @@ into the file:
|
|||
Explanation of the code
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
First, we import the *dyaml.all* module. This is the only D:YAML module you
|
||||
need to import - it automatically imports all needed modules.
|
||||
First, we import the *dyaml.all* module. This is the only D:YAML module you need to
|
||||
import - it automatically imports all needed modules.
|
||||
|
||||
Next we load the file using the *Loader.load()* method. *Loader* is a struct
|
||||
used for parsing YAML documents. The *load()* method loads the file as
|
||||
**one** YAML document, or 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.
|
||||
Next we load the file using the *Loader.load()* method. *Loader* is a struct used for
|
||||
parsing YAML documents. The *load()* method loads the file as **one** YAML document, or
|
||||
throws *YAMLException*, 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.
|
||||
|
||||
*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
|
||||
*Node.as()* method on the second to read its value as an integer.
|
||||
*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
|
||||
former, as it is a sequence, and use the *Node.as()* method on the latter to read 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 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 *YAMLException*.
|
||||
|
||||
You can iterate over subnodes using *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"
|
||||
You can iterate using *Node* 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 *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 *Node.as()* method is used to read value of a scalar node as specified type.
|
||||
D:YAML will try to return the scalar as this type, converting if needed,
|
||||
throwing *YAMLException* if not possible.
|
||||
The *Node.as()* 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
|
||||
*YAMLException* if not possible.
|
||||
|
||||
Finally we dump the document we just read to ``output.yaml`` with the
|
||||
*Dumper.dump()* method. *Dumper* is a struct used to dump YAML documents.
|
||||
The *dump()* method writes one or more documents to a file, throwing
|
||||
*YAMLException* if the file could not be written to.
|
||||
Finally we dump the document we just read to ``output.yaml`` with the *Dumper.dump()*
|
||||
method. *Dumper* is a struct used to dump YAML documents. The *dump()* method writes
|
||||
one or more documents to a file, throwing *YAMLException* if the file could not be
|
||||
written to.
|
||||
|
||||
D:YAML doesn't preserve style information in documents, so even though
|
||||
``output.yaml`` will contain the same data as ``input.yaml``, it might be
|
||||
formatted differently. Comments are not preserved, either.
|
||||
D:YAML tries to preserve style information in documents so e.g. ``[Hello, World]`` is
|
||||
not turned into:
|
||||
|
||||
| ``- Hello``
|
||||
| ``- World``
|
||||
|
||||
However, comments are not preserved and neither are any extra formatting whitespace that
|
||||
doesn't affect the meaning of YAML contents.
|
||||
|
||||
|
||||
^^^^^^^^^
|
||||
Compiling
|
||||
^^^^^^^^^
|
||||
|
||||
To compile your project, DMD needs to know which directories contain the
|
||||
imported modules and the library. You also need to tell it to link with D:YAML.
|
||||
The import directory should be the ``source`` subdirectory of the D:YAML
|
||||
directory. You can specify it using the ``-I`` option of DMD. The library
|
||||
directory should point to the compiled 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.
|
||||
We're going to use dub, which we installed at the beginning, to compile our project.
|
||||
|
||||
For example, if you extracted and compiled D:YAML in ``/home/xxx/dyaml``, your
|
||||
project is in ``/home/xxx/dyaml-project``, and you are currently in that
|
||||
directory, compile the project with the following command on Unix/Linux::
|
||||
Create a file called ``dub.json`` with the following contents:
|
||||
|
||||
dmd -I../dyaml/source -L-L../dyaml -L-ldyaml main.d
|
||||
.. code-block:: json
|
||||
|
||||
And the following on Windows::
|
||||
{
|
||||
"name": "getting-started",
|
||||
"targetType": "executable",
|
||||
"sourceFiles": ["main.d"],
|
||||
"mainSourceFile": "main.d",
|
||||
"dependencies":
|
||||
{
|
||||
"dyaml": { "version" : "~>0.5.0", "path" : "../../"},
|
||||
},
|
||||
}
|
||||
|
||||
dmd -I../dyaml/source ../dyaml/libdyaml.lib main.d
|
||||
This file tells dub that we're building an executable called ``getting-started`` from
|
||||
a D source file ``main.d``, 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.
|
||||
|
||||
This will produce an executable called ``main`` or ``main.exe`` in your
|
||||
directory. When you run it, it should produce the following output::
|
||||
Now run the following command in your project's directory::
|
||||
|
||||
dub build
|
||||
|
||||
dub will automatically download D:YAML and compile it, and then then it will compile our
|
||||
program. This will generate an executable called ``getting-started`` or
|
||||
``getting-started.exe`` in your directory. When you run it, it should produce the
|
||||
following output::
|
||||
|
||||
Hello
|
||||
World
|
||||
|
|
@ -176,6 +171,6 @@ directory. When you run it, it should produce the following output::
|
|||
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
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue