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 Note: Other D compilers exist, such as [GDC](http://gdcproject.org/) and
[LDC](https://github.com/ldc-developers/ldc). [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 ## Your first D:YAML project
Create a directory for your project and in that directory, create a new First, create a directory for your project and navigate to that directory
file named `input.yaml` and paste this code into the file: 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 ```YAML
Hello World : [Hello, World] Hello World : [Hello, World]
@ -42,17 +38,17 @@ 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 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: following code into the file:
```D ```D
import std.stdio; import std.stdio;
import yaml; import dyaml;
void main() void main()
{ {
//Read the input. //Read the input.
Node root = Loader("input.yaml").load(); Node root = Loader.fromFile("input.yaml").load();
//Display the data read. //Display the data read.
foreach(string word; root["Hello World"]) foreach(string word; root["Hello World"])
@ -62,17 +58,18 @@ void main()
writeln("The answer is ", root["Answer"].as!int); writeln("The answer is ", root["Answer"].as!int);
//Dump the loaded document to output.yaml. //Dump the loaded document to output.yaml.
Dumper("output.yaml").dump(root); dumper(File("output.yaml", "w").lockingTextWriter).dump(root);
} }
``` ```
### Explanation of the code ### 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. you need to import - it automatically imports all needed modules.
Next we load the file using the *Loader.load()* method. *Loader* is a Next we load the file using the *Loader.fromFile().load()* method. *Loader* is a
struct used for parsing YAML documents. The *load()* method loads the 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 file as **one** YAML document, or throws *YAMLException*, D:YAML
exception type, if the file could not be parsed or contains more than 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 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 Finally we dump the document we just read to `output.yaml` with the
*Dumper.dump()* method. *Dumper* is a struct used to dump YAML *Dumper.dump()* method. *Dumper* is a struct used to dump YAML
documents. The *dump()* method writes one or more documents to a file, documents. *dumper()* accepts a range to write the document to.
throwing *YAMLException* if the file could not be written 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, D:YAML tries to preserve style information in documents so e.g. `[Hello,
World]` is not turned into: World]` is not turned into:
@ -119,35 +117,11 @@ whitespace that doesn't affect the meaning of YAML contents.
### Compiling ### Compiling
We're going to use dub, which we installed at the beginning, to compile Run the following command in your project's directory:
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:
dub build 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 will compile our program. This will generate an executable called
`getting-started` or `getting-started.exe` in your directory. When you `getting-started` or `getting-started.exe` in your directory. When you
run it, it should produce the following output: run it, it should produce the following output:
@ -156,6 +130,8 @@ run it, it should produce the following output:
World World
The answer is 42 The answer is 42
You may also run ```dub run``` to combine the compile+run steps.
### Conclusion ### Conclusion
You should now have a basic idea about how to use D:YAML. To learn more, You should now have a basic idea about how to use D:YAML. To learn more,

View file

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