From beb160f1ebfc4fbf95b5d9c360cb26301491cfcc Mon Sep 17 00:00:00 2001 From: Cameron Ross Date: Sun, 13 Jan 2019 03:17:02 -0330 Subject: [PATCH] update documentation (#217) update documentation merged-on-behalf-of: BBasile --- docs/tutorials/getting_started.md | 70 ++++++++++--------------------- docs/tutorials/yaml_syntax.md | 22 +++++----- 2 files changed, 34 insertions(+), 58 deletions(-) diff --git a/docs/tutorials/getting_started.md b/docs/tutorials/getting_started.md index 4441b70..58cf191 100644 --- a/docs/tutorials/getting_started.md +++ b/docs/tutorials/getting_started.md @@ -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, diff --git a/docs/tutorials/yaml_syntax.md b/docs/tutorials/yaml_syntax.md index 84a5665..2df7f8b 100644 --- a/docs/tutorials/yaml_syntax.md +++ b/docs/tutorials/yaml_syntax.md @@ -228,14 +228,14 @@ Implicit tags: 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). -|YAML tag |D type | -|-----------------------|---------------------| -|!!null |yaml.YAMLNull | -|!!bool |bool | -|!!int |long | -|!!float |real | -|!!binary |ubyte[] | -|!!timestamp |std.datetime.SysTime | -|!!map, !!omap, !!pairs |yaml.Node.Pair[] | -|!!seq, !!set |yaml.Node[] | -|!!str |string | +|YAML tag |D type | +|-----------------------|-----------------------| +|!!null |dyaml.node.YAMLNull | +|!!bool |bool | +|!!int |long | +|!!float |real | +|!!binary |ubyte[] | +|!!timestamp |std.datetime.SysTime | +|!!map, !!omap, !!pairs |dyaml.node.Node.Pair[] | +|!!seq, !!set |dyaml.node.Node[] | +|!!str |string |