Initial commit.

docsrc/tutorials/getting_started.rst

@@ -0,0 +1,168 @@
+===============
+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.