Updated 'Getting Started' with dub info.
This commit is contained in:
parent
e02bd73096
commit
278b60e896
|
@ -1,13 +1,13 @@
|
||||||
===============
|
===============
|
||||||
Getting started
|
Getting started
|
||||||
===============
|
===============
|
||||||
|
|
||||||
Welcome to D:YAML! D:YAML is a `YAML <http://en.wikipedia.org/wiki/YAML>`_
|
Welcome to D:YAML! D:YAML is a `YAML <http://en.wikipedia.org/wiki/YAML>`_ parser
|
||||||
parser library for the `D programming language <http://dlang.org>`_.
|
library for the `D programming language <http://dlang.org>`_. This tutorial will
|
||||||
This tutorial will explain how to set D:YAML up and use it in your projects.
|
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 is meant to be the **simplest possible** introduction to D:YAML. Some of this
|
||||||
this information might already be known to you. Only basic usage is covered.
|
information might already be known to you. Only basic usage is covered.
|
||||||
|
|
||||||
|
|
||||||
----------
|
----------
|
||||||
|
@ -18,59 +18,43 @@ Setting up
|
||||||
Install the DMD compiler
|
Install the DMD compiler
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Digital Mars D compiler, or DMD, is the most commonly used D compiler. You can
|
Digital Mars D compiler, or DMD, is the most commonly used D compiler. You can find its
|
||||||
find its newest version `here <http://dlang.org/download.html>`_.
|
newest version `here <http://dlang.org/download.html>`_. Download the version of DMD
|
||||||
Download the version of DMD for your operating system and install it.
|
for your operating system and install it.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
Other D compilers exist, such as
|
Other D compilers exist, such as
|
||||||
`GDC <http://gdcproject.org/>`_ and
|
`GDC <http://gdcproject.org/>`_ and
|
||||||
`LDC <http://bitbucket.org/goshawk/gdc/wiki/Home>`_.
|
`LDC <http://bitbucket.org/goshawk/gdc/wiki/Home>`_.
|
||||||
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^
|
||||||
Download and compile D:YAML
|
Install dub
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^
|
||||||
|
|
||||||
The newest version of D:YAML can be found
|
`dub <http://code.dlang.org/about>`_ is a build system and package manager for D.
|
||||||
`here <https://github.com/Kiith-Sa/D-YAML>`_. Download a source archive, extract
|
It is the standard way to manage D projects and their dependencies, compilation and so
|
||||||
it, and move to the extracted directory.
|
on.
|
||||||
|
|
||||||
D:YAML uses a modified version of the `CDC <http://dsource.org/projects/cdc/>`_
|
DMD may include DUB in future releases, but at this point we need to install it
|
||||||
script for compilation. To compile D:YAML, you first need to build CDC.
|
separately. See
|
||||||
Do this by typing the following command into the console::
|
`installation instructions <https://github.com/D-Programming-Language/dub#installation>`_.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
|
|
||||||
-------------------------
|
-------------------------
|
||||||
Your first D:YAML project
|
Your first D:YAML project
|
||||||
-------------------------
|
-------------------------
|
||||||
|
|
||||||
Create a directory for your project and in that directory, create a file called
|
Create a directory for your project and in that directory, create a new file named
|
||||||
``input.yaml`` with the following contents:
|
``input.yaml`` and paste this code into the file:
|
||||||
|
|
||||||
.. code-block:: yaml
|
.. code-block:: yaml
|
||||||
|
|
||||||
Hello World :
|
Hello World : [Hello, World]
|
||||||
- Hello
|
|
||||||
- World
|
|
||||||
Answer: 42
|
Answer: 42
|
||||||
|
|
||||||
This will serve as input for our example.
|
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:
|
into the file:
|
||||||
|
|
||||||
.. code-block:: d
|
.. code-block:: d
|
||||||
|
@ -99,83 +83,94 @@ into the file:
|
||||||
Explanation of the code
|
Explanation of the code
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
First, we import the *dyaml.all* module. This is the only D:YAML module you
|
First, we import the *dyaml.all* module. This is the only D:YAML module you need to
|
||||||
need to import - it automatically imports all needed modules.
|
import - it automatically imports all needed modules.
|
||||||
|
|
||||||
Next we load the file using the *Loader.load()* method. *Loader* is a struct
|
Next we load the file using the *Loader.load()* method. *Loader* is a struct used for
|
||||||
used for parsing YAML documents. The *load()* method loads the file as
|
parsing YAML documents. The *load()* method loads the file as **one** YAML document, or
|
||||||
**one** YAML document, or throws *YAMLException*, D:YAML exception type, if the
|
throws *YAMLException*, D:YAML exception type, if the file could not be parsed or
|
||||||
file could not be parsed or does not contain exactly one document. Note that we
|
contains more than one document. Note that we don't do any error checking here in order
|
||||||
don't do any error checking here in order to keep the example as simple as
|
to keep the example as simple as possible.
|
||||||
possible.
|
|
||||||
|
|
||||||
*Node* represents a node in a YAML document. It can be a sequence (array),
|
*Node* represents a node in a YAML document. It can be a sequence (array), mapping
|
||||||
mapping (associative array) or a scalar (value). Here the root node is a
|
(associative array) or a scalar (value). Here the root node is a mapping, and we use the
|
||||||
mapping, and we use the index operator to get subnodes with keys "Hello World"
|
index operator to get subnodes with keys "Hello World" and "Answer". We iterate over the
|
||||||
and "Answer". We iterate over the first, as it is a sequence, and use the
|
former, as it is a sequence, and use the *Node.as()* method on the latter to read its
|
||||||
*Node.as()* method on the second to read its value as an integer.
|
value as an integer.
|
||||||
|
|
||||||
You can iterate over a mapping or sequence as if it was an associative or normal
|
You can iterate over a mapping or sequence as if it was an associative or normal array,
|
||||||
array. If you try to iterate over a scalar, it will throw a *YAMLException*.
|
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
|
You can iterate using *Node* as the iterated type, or specify the type iterated nodes
|
||||||
the type subnodes are expected to have. D:YAML will automatically convert
|
are expected to have. D:YAML will automatically convert to that type if possible. Here
|
||||||
iterated subnodes to that type if possible. Here we specify the *string* type,
|
we specify the *string* type, so we iterate over the "Hello World" sequence as an array
|
||||||
so we iterate over the "Hello World" sequence as an array of strings. If it is
|
of strings. If it is not possible to convert to iterated type, a *YAMLException* is
|
||||||
not possible to convert to iterated type, a *YAMLException* is thrown. For
|
thrown. For instance, if we specified *int* here, we would get an error, as "Hello"
|
||||||
instance, if we specified *int* here, we would get an error, as "Hello"
|
|
||||||
cannot be converted to an integer.
|
cannot be converted to an integer.
|
||||||
|
|
||||||
The *Node.as()* method is used to read value of a scalar node as specified type.
|
The *Node.as()* method is used to read value of a scalar node as specified type. If the
|
||||||
D:YAML will try to return the scalar as this type, converting if needed,
|
scalar does not have the specified type, D:YAML will try to convert it, throwing
|
||||||
throwing *YAMLException* if not possible.
|
*YAMLException* if not possible.
|
||||||
|
|
||||||
Finally we dump the document we just read to ``output.yaml`` with the
|
Finally we dump the document we just read to ``output.yaml`` with the *Dumper.dump()*
|
||||||
*Dumper.dump()* method. *Dumper* is a struct used to dump YAML documents.
|
method. *Dumper* is a struct used to dump YAML documents. The *dump()* method writes
|
||||||
The *dump()* method writes one or more documents to a file, throwing
|
one or more documents to a file, throwing *YAMLException* if the file could not be
|
||||||
*YAMLException* if the file could not be written to.
|
written to.
|
||||||
|
|
||||||
D:YAML doesn't preserve style information in documents, so even though
|
D:YAML tries to preserve style information in documents so e.g. ``[Hello, World]`` is
|
||||||
``output.yaml`` will contain the same data as ``input.yaml``, it might be
|
not turned into:
|
||||||
formatted differently. Comments are not preserved, either.
|
|
||||||
|
| ``- Hello``
|
||||||
|
| ``- World``
|
||||||
|
|
||||||
|
However, comments are not preserved and neither are any extra formatting whitespace that
|
||||||
|
doesn't affect the meaning of YAML contents.
|
||||||
|
|
||||||
|
|
||||||
^^^^^^^^^
|
^^^^^^^^^
|
||||||
Compiling
|
Compiling
|
||||||
^^^^^^^^^
|
^^^^^^^^^
|
||||||
|
|
||||||
To compile your project, DMD needs to know which directories contain the
|
We're going to use dub, which we installed at the beginning, to compile our project.
|
||||||
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.
|
|
||||||
|
|
||||||
For example, if you extracted and compiled D:YAML in ``/home/xxx/dyaml``, your
|
Create a file called ``dub.json`` with the following contents:
|
||||||
project is in ``/home/xxx/dyaml-project``, and you are currently in that
|
|
||||||
directory, compile the project with the following command on Unix/Linux::
|
|
||||||
|
|
||||||
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
|
Now run the following command in your project's directory::
|
||||||
directory. When you run it, it should produce the following output::
|
|
||||||
|
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
|
Hello
|
||||||
World
|
World
|
||||||
The answer is 42
|
The answer is 42
|
||||||
|
|
||||||
|
|
||||||
^^^^^^^^^^
|
^^^^^^^^^^
|
||||||
Conclusion
|
Conclusion
|
||||||
^^^^^^^^^^
|
^^^^^^^^^^
|
||||||
|
|
||||||
You should now have a basic idea about how to use D:YAML. To learn more, look at
|
You should now have a basic idea about how to use D:YAML. To learn more, look at the
|
||||||
the `API documentation <../api/index.html>`_ and other tutorials. You can find code for this
|
`API documentation <../api/index.html>`_ and other tutorials. You can find code for this
|
||||||
example in the ``example/getting_started`` directory in the package.
|
example in the ``example/getting_started`` directory in the package.
|
||||||
|
|
Loading…
Reference in a new issue