From 278b60e89610d9bc80d9aeafedeb1d38286d72ed Mon Sep 17 00:00:00 2001 From: Ferdinand Majerech Date: Fri, 1 Aug 2014 17:07:08 +0200 Subject: [PATCH] Updated 'Getting Started' with dub info. --- docsrc/tutorials/getting_started.rst | 181 +++++++++++++-------------- 1 file changed, 88 insertions(+), 93 deletions(-) diff --git a/docsrc/tutorials/getting_started.rst b/docsrc/tutorials/getting_started.rst index 7134bad..d968fa8 100644 --- a/docsrc/tutorials/getting_started.rst +++ b/docsrc/tutorials/getting_started.rst @@ -1,13 +1,13 @@ =============== -Getting started +Getting started =============== -Welcome to D:YAML! D:YAML is a `YAML `_ -parser library for the `D programming language `_. -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 `_ parser +library for the `D programming language `_. 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 `_. -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 `_. Download the version of DMD +for your operating system and install it. -.. note:: - Other D compilers exist, such as - `GDC `_ and +.. note:: + Other D compilers exist, such as + `GDC `_ and `LDC `_. -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Download and compile D:YAML -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^ +Install dub +^^^^^^^^^^^ -The newest version of D:YAML can be found -`here `_. Download a source archive, extract -it, and move to the extracted directory. +`dub `_ 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 `_ -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 `_. ------------------------- -Your first D:YAML project +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,83 +83,94 @@ 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 - The answer is 42 + 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 +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.