update documentation (#217)

update documentation
merged-on-behalf-of: BBasile <BBasile@users.noreply.github.com>
This commit is contained in:
Cameron Ross 2019-01-13 03:17:02 -03:30 committed by The Dlang Bot
parent 8ed381bd56
commit beb160f1eb
2 changed files with 34 additions and 58 deletions

View file

@ -20,20 +20,16 @@ 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](https://github.com/ldc-developers/ldc).
### Install dub
[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.
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 new
file named `input.yaml` and paste this code into the file:
First, create a directory for your project and navigate to that directory
using your preferred command line. Then simply execute these two commands:
dub init
dub add dyaml
In that directory, create a new file named `input.yaml` and paste this data
into the file:
```YAML
Hello World : [Hello, World]
@ -42,17 +38,17 @@ Answer: 42
This will serve as input for our example.
Now we need to parse it. Create a new file with name `main.d`. Paste
Now we need to parse it. Open the file named `source/app.d` and paste the
following code into the file:
```D
import std.stdio;
import yaml;
import dyaml;
void main()
{
//Read the input.
Node root = Loader("input.yaml").load();
Node root = Loader.fromFile("input.yaml").load();
//Display the data read.
foreach(string word; root["Hello World"])
@ -62,17 +58,18 @@ void main()
writeln("The answer is ", root["Answer"].as!int);
//Dump the loaded document to output.yaml.
Dumper("output.yaml").dump(root);
dumper(File("output.yaml", "w").lockingTextWriter).dump(root);
}
```
### Explanation of the code
First, we import the *dyaml.all* module. This is the only D:YAML module
First, we import the *dyaml* 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
Next we load the file using the *Loader.fromFile().load()* method. *Loader* is a
struct used for parsing YAML documents. The *fromFile()* method loads the
document from a file. 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
@ -103,8 +100,9 @@ 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.
documents. *dumper()* accepts a range to write the document to.
The *dump()* method writes one or more documents to the range,
throwing *YAMLException* if it could not be written to.
D:YAML tries to preserve style information in documents so e.g. `[Hello,
World]` is not turned into:
@ -119,35 +117,11 @@ whitespace that doesn't affect the meaning of YAML contents.
### Compiling
We're going to use dub, which we installed at the beginning, to compile
our project.
Create a file called `dub.json` with the following contents:
```JSON
{
"name": "getting-started",
"targetType": "executable",
"sourceFiles": ["main.d"],
"mainSourceFile": "main.d",
"dependencies":
{
"dyaml": { "version" : "~>0.5.0" },
},
}
```
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.
Now run the following command in your project's directory:
Run the following command in your project's directory:
dub build
dub will automatically download D:YAML and compile it, and then then it
DUB will automatically download D:YAML and compile it, and 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:
@ -156,6 +130,8 @@ run it, it should produce the following output:
World
The answer is 42
You may also run ```dub run``` to combine the compile+run steps.
### Conclusion
You should now have a basic idea about how to use D:YAML. To learn more,

View file

@ -229,13 +229,13 @@ This table shows D types stored in *yaml.Node* default YAML tags are converted t
Some of these might change in the future (especially !!map and !!set).
|YAML tag |D type |
|-----------------------|---------------------|
|!!null |yaml.YAMLNull |
|-----------------------|-----------------------|
|!!null |dyaml.node.YAMLNull |
|!!bool |bool |
|!!int |long |
|!!float |real |
|!!binary |ubyte[] |
|!!timestamp |std.datetime.SysTime |
|!!map, !!omap, !!pairs |yaml.Node.Pair[] |
|!!seq, !!set |yaml.Node[] |
|!!map, !!omap, !!pairs |dyaml.node.Node.Pair[] |
|!!seq, !!set |dyaml.node.Node[] |
|!!str |string |