aboutsummaryrefslogtreecommitdiffhomepage
path: root/src/ext_depends/D-YAML/docs/tutorials
diff options
context:
space:
mode:
Diffstat (limited to 'src/ext_depends/D-YAML/docs/tutorials')
-rw-r--r--src/ext_depends/D-YAML/docs/tutorials/custom_types.md258
-rw-r--r--src/ext_depends/D-YAML/docs/tutorials/getting_started.md140
-rw-r--r--src/ext_depends/D-YAML/docs/tutorials/yaml_syntax.md241
3 files changed, 639 insertions, 0 deletions
diff --git a/src/ext_depends/D-YAML/docs/tutorials/custom_types.md b/src/ext_depends/D-YAML/docs/tutorials/custom_types.md
new file mode 100644
index 0000000..7e4e10b
--- /dev/null
+++ b/src/ext_depends/D-YAML/docs/tutorials/custom_types.md
@@ -0,0 +1,258 @@
+# Custom YAML data types
+
+Sometimes you need to serialize complex data types such as classes. To
+do this you could use plain nodes such as mappings with classes' fields.
+YAML also supports custom types with identifiers called *tags*. That is
+the topic of this tutorial.
+
+Each YAML node has a tag specifying its type. For instance: strings use
+the tag `tag:yaml.org,2002:str`. Tags of most default types are
+*implicitly resolved* during parsing - you don't need to specify tag for
+each float, integer, etc. D:YAML can also implicitly resolve custom
+tags, as we will show later.
+
+## Constructor
+
+D:YAML supports conversion to user-defined types. Adding a constructor to read
+the data from the node is all that is needed.
+
+We will implement support for an RGB color type. It is implemented as
+the following struct:
+
+```D
+struct Color
+{
+ ubyte red;
+ ubyte green;
+ ubyte blue;
+}
+```
+
+First, we need our type to have an appropriate constructor. The constructor
+will take a const *Node* to construct from. The node is guaranteed to
+contain either a *string*, an array of *Node* or of *Node.Pair*,
+depending on whether we're constructing our value from a scalar,
+sequence, or mapping, respectively.
+
+In this tutorial, we have a constructor to construct a color from a scalar,
+using CSS-like format, RRGGBB, or from a mapping, where we use the
+following format: {r:RRR, g:GGG, b:BBB} . Code of these functions:
+
+```D
+
+this(const Node node, string tag) @safe
+{
+ if (tag == "!color-mapping")
+ {
+ //Will throw if a value is missing, is not an integer, or is out of range.
+ red = node["r"].as!ubyte;
+ green = node["g"].as!ubyte;
+ blue = node["b"].as!ubyte;
+ }
+ else
+ {
+ string value = node.as!string;
+
+ if(value.length != 6)
+ {
+ throw new Exception("Invalid color: " ~ value);
+ }
+ //We don't need to check for uppercase chars this way.
+ value = value.toLower();
+
+ //Get value of a hex digit.
+ uint hex(char c)
+ {
+ import std.ascii;
+ if(!std.ascii.isHexDigit(c))
+ {
+ throw new Exception("Invalid color: " ~ value);
+ }
+
+ if(std.ascii.isDigit(c))
+ {
+ return c - '0';
+ }
+ return c - 'a' + 10;
+ }
+
+ red = cast(ubyte)(16 * hex(value[0]) + hex(value[1]));
+ green = cast(ubyte)(16 * hex(value[2]) + hex(value[3]));
+ blue = cast(ubyte)(16 * hex(value[4]) + hex(value[5]));
+ }
+}
+```
+
+Next, we need some YAML data using our new tag. Create a file called
+`input.yaml` with the following contents:
+
+```YAML
+scalar-red: !color FF0000
+scalar-orange: !color FFFF00
+mapping-red: !color-mapping {r: 255, g: 0, b: 0}
+mapping-orange:
+ !color-mapping
+ r: 255
+ g: 255
+ b: 0
+```
+
+You can see that we're using tag `!color` for scalar colors, and
+`!color-mapping` for colors expressed as mappings.
+
+Finally, the code to put it all together:
+
+```D
+void main()
+{
+ auto red = Color(255, 0, 0);
+ auto orange = Color(255, 255, 0);
+
+ try
+ {
+ auto root = Loader.fromFile("input.yaml").load();
+
+ if(root["scalar-red"].as!Color == red &&
+ root["mapping-red"].as!Color == red &&
+ root["scalar-orange"].as!Color == orange &&
+ root["mapping-orange"].as!Color == orange)
+ {
+ writeln("SUCCESS");
+ return;
+ }
+ }
+ catch(YAMLException e)
+ {
+ writeln(e.msg);
+ }
+
+ writeln("FAILURE");
+}
+```
+
+First we load the YAML document, and then have the resulting *Node*s converted
+to Colors via their constructor.
+
+You can find the source code for what we've done so far in the
+`examples/constructor` directory in the D:YAML package.
+
+## Resolver
+
+Specifying tag for every color can be tedious. D:YAML can implicitly
+resolve scalar tags using regular expressions. This is how default types
+are resolved. We will use the [Resolver](../api/dyaml.resolver.html)
+class to add implicit tag resolution for the Color data type (in its
+scalar form).
+
+We use the *addImplicitResolver()* method of *Resolver*, passing the
+tag, regular expression the scalar must match to resolve to this tag,
+and a string of possible starting characters of the scalar. Then we pass
+the *Resolver* to *Loader*.
+
+Note that resolvers added first override ones added later. If no
+resolver matches a scalar, YAML string tag is used. Therefore our custom
+values must not be resolvable as any non-string YAML data type.
+
+Add this to your code to add implicit resolution of `!color`.
+
+```D
+import std.regex;
+auto resolver = new Resolver;
+resolver.addImplicitResolver("!color", regex("[0-9a-fA-F]{6}"),
+ "0123456789abcdefABCDEF");
+
+auto loader = Loader.fromFile("input.yaml");
+
+loader.resolver = resolver;
+```
+
+Now, change contents of `input.yaml` to this:
+
+```YAML
+scalar-red: FF0000
+scalar-orange: FFFF00
+mapping-red: !color-mapping {r: 255, g: 0, b: 0}
+mapping-orange:
+ !color-mapping
+ r: 255
+ g: 255
+ b: 0
+```
+
+We no longer need to specify the tag for scalar color values. Compile
+and test the example. If everything went as expected, it should report
+success.
+
+You can find the complete code in the `examples/resolver` directory in
+the D:YAML package.
+
+## Representer
+
+Now that you can load custom data types, it might be good to know how to
+dump them.
+
+The *Node* struct simply attempts to cast all unrecognized types to *Node*.
+This gives each type a consistent and simple way of being represented in a
+document. All we need to do is specify a `Node opCast(T: Node)()` method for
+any types we wish to support. It is also possible to specify specific styles
+for each representation.
+
+Each type may only have one opCast!Node. Default YAML types are already
+supported.
+
+With the following code, we will add support for dumping the our Color
+type.
+
+```D
+Node opCast(T: Node)() const
+{
+ static immutable hex = "0123456789ABCDEF";
+
+ //Using the color format from the Constructor example.
+ string scalar;
+ foreach(channel; [red, green, blue])
+ {
+ scalar ~= hex[channel / 16];
+ scalar ~= hex[channel % 16];
+ }
+
+ //Representing as a scalar, with custom tag to specify this data type.
+ return Node(scalar, "!color");
+}
+```
+
+First we convert the colour data to a string with the CSS-like format we've
+used before. Then, we create a scalar *Node* with our desired tag.
+
+Since a type can only have one opCast!Node method, we don't dump
+*Color* both in the scalar and mapping formats we've used before.
+However, you can decide to dump the node with different formats/tags in
+the method itself. E.g. you could dump the Color as a
+mapping based on some arbitrary condition, such as the color being
+white.
+
+```D
+void main()
+{
+ try
+ {
+ auto dumper = dumper(File("output.yaml", "w").lockingTextWriter);
+
+ auto document = Node([Color(255, 0, 0),
+ Color(0, 255, 0),
+ Color(0, 0, 255)]);
+
+ dumper.dump(document);
+ }
+ catch(YAMLException e)
+ {
+ writeln(e.msg);
+ }
+}
+```
+
+We construct a *Dumper* to file `output.yaml`. Then, we create a simple node
+containing a sequence of colors and finally, we dump it.
+
+Source code for this section can be found in the `examples/representer`
+directory of the D:YAML package.
diff --git a/src/ext_depends/D-YAML/docs/tutorials/getting_started.md b/src/ext_depends/D-YAML/docs/tutorials/getting_started.md
new file mode 100644
index 0000000..58cf191
--- /dev/null
+++ b/src/ext_depends/D-YAML/docs/tutorials/getting_started.md
@@ -0,0 +1,140 @@
+# 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://dlang.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 this information might already be known to you. Only basic usage
+is covered.
+
+## 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://dlang.org/download.html).
+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).
+
+## Your first D:YAML project
+
+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]
+Answer: 42
+```
+
+This will serve as input for our example.
+
+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 dyaml;
+
+void main()
+{
+ //Read the input.
+ Node root = Loader.fromFile("input.yaml").load();
+
+ //Display the data read.
+ foreach(string word; root["Hello World"])
+ {
+ writeln(word);
+ }
+ writeln("The answer is ", root["Answer"].as!int);
+
+ //Dump the loaded document to output.yaml.
+ dumper(File("output.yaml", "w").lockingTextWriter).dump(root);
+}
+```
+
+### Explanation of the code
+
+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.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
+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 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, respectively. If you try to iterate over a scalar, it
+will throw a *YAMLException*.
+
+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. 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. *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:
+
+```YAML
+- Hello
+- World
+```
+
+However, comments are not preserved and neither are any extra formatting
+whitespace that doesn't affect the meaning of YAML contents.
+
+### Compiling
+
+Run the following command in your project's directory:
+
+ dub build
+
+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:
+
+ Hello
+ 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,
+look at the [API documentation](https://dyaml.dpldocs.info/dyaml.html) and other tutorials.
+You can find code for this example in the `example/getting_started`
+directory in the package.
diff --git a/src/ext_depends/D-YAML/docs/tutorials/yaml_syntax.md b/src/ext_depends/D-YAML/docs/tutorials/yaml_syntax.md
new file mode 100644
index 0000000..2df7f8b
--- /dev/null
+++ b/src/ext_depends/D-YAML/docs/tutorials/yaml_syntax.md
@@ -0,0 +1,241 @@
+# YAML syntax
+
+This is an introduction to the most common YAML constructs. For more detailed
+information, see [PyYAML documentation](http://pyyaml.org/wiki/PyYAMLDocumentation),
+which this article is based on,
+[Chapter 2 of the YAML specification](http://yaml.org/spec/1.1/#id857168)
+or the [Wikipedia page](http://en.wikipedia.org/wiki/YAML).
+
+YAML is a data serialization format designed for human readability. YAML is a
+recursive acronym for "YAML Ain't Markup Language".
+
+YAML is similar to JSON, and in fact, JSON is a subset of YAML 1.2; but YAML has
+some more advanced features and is easier to read. However, it is also more
+difficult to parse (and probably somewhat slower). Data is stored in mappings
+(associative arrays), sequences (lists) and scalars (single values). Data
+structure hierarchy depends either on indentation (block context, similar to
+Python code), or nesting of brackets and braces (flow context, similar to JSON).
+YAML comments begin with `#` and continue until the end of line.
+
+
+## Documents
+
+A YAML stream consists of one or more documents starting with `---` and
+optionally ending with `...` . `---` can be left out for the first document.
+
+Single document with no explicit start or end:
+
+```
+ - Red
+ - Green
+ - Blue
+```
+Same document with explicit start and end:
+```
+ ---
+ - Red
+ - Green
+ - Blue
+ ...
+```
+A stream containing multiple documents:
+```
+ ---
+ - Red
+ - Green
+ - Blue
+ ---
+ - Linux
+ - BSD
+ ---
+ answer : 42
+```
+
+## Sequences
+
+Sequences are arrays of nodes of any type, similar e.g. to Python lists.
+In block context, each item begins with hyphen+space "- ". In flow context,
+sequences have syntax similar to D arrays.
+
+```
+ #Block context
+ - Red
+ - Green
+ - Blue
+```
+```
+ #Flow context
+ [Red, Green, Blue]
+```
+```
+ #Nested
+ -
+ - Red
+ - Green
+ - Blue
+ -
+ - Linux
+ - BSD
+```
+```
+ #Nested flow
+ [[Red, Green, Blue], [Linux, BSD]]
+```
+```
+ #Nested in a mapping
+ Colors:
+ - Red
+ - Green
+ - Blue
+ Operating systems:
+ - Linux
+ - BSD
+```
+
+## Mappings
+
+Mappings are associative arrays where each key and value can be of any type,
+similar e.g. to Python dictionaries. In block context, keys and values are
+separated by colon+space ": ". In flow context, mappings have syntax similar
+to D associative arrays, but with braces instead of brackets:
+
+```
+ #Block context
+ CPU: Athlon
+ GPU: Radeon
+ OS: Linux
+
+```
+```
+ #Flow context
+ {CPU: Athlon, GPU: Radeon, OS: Linux}
+
+```
+```
+ #Nested
+ PC:
+ CPU: Athlon
+ GPU: Radeon
+ OS: Debian
+ Phone:
+ CPU: Cortex
+ GPU: PowerVR
+ OS: Android
+
+```
+```
+ #Nested flow
+ {PC: {CPU: Athlon, GPU: Radeon, OS: Debian},
+ Phone: {CPU: Cortex, GPU: PowerVR, OS: Android}}
+```
+```
+ #Nested in a sequence
+ - CPU: Athlon
+ GPU: Radeon
+ OS: Debian
+ - CPU: Cortex
+ GPU: PowerVR
+ OS: Android
+```
+
+Complex keys start with question mark+space "? ".
+
+```
+ #Nested in a sequence
+ ? [CPU, GPU]: [Athlon, Radeon]
+ OS: Debian
+```
+
+## Scalars
+
+Scalars are simple values such as integers, strings, timestamps and so on.
+There are multiple scalar styles.
+
+Plain scalars use no quotes, start with the first non-space and end with the
+last non-space character:
+
+```
+ scalar: Plain scalar
+```
+
+Single quoted scalars start and end with single quotes. A single quote is
+represented by a pair of single quotes ''.
+
+```
+ scalar: 'Single quoted scalar ending with some spaces '
+```
+
+Double quoted scalars support C-style escape sequences.
+
+```
+ scalar: "Double quoted scalar \n with some \\ escape sequences"
+```
+
+Block scalars are convenient for multi-line values. They start either with
+`|` or with `>`. With `|`, the newlines in the scalar are preserved.
+With `>`, the newlines between two non-empty lines are removed.
+
+```
+ scalar: |
+ Newlines are preserved
+ First line
+ Second line
+```
+```
+ scalar: >
+ Newlines are folded
+ This is still the first paragraph
+
+ This is the second
+ paragraph
+```
+
+## Anchors and aliases
+
+Anchors and aliases can reduce size of YAML code by allowing you to define a
+value once, assign an anchor to it and use alias referring to that anchor
+anywhere else you need that value. It is possible to use this to create
+recursive data structures and some parsers support this; however, D:YAML does
+not (this might change in the future, but it is unlikely).
+
+```
+ Person: &AD
+ gender: male
+ name: Arthur Dent
+ Clone: *AD
+```
+
+## Tags
+
+Tags are identifiers that specify data types of YAML nodes. Most default YAML
+tags are resolved implicitly, so there is no need to specify them. D:YAML also
+supports implicit resolution for custom, user specified tags.
+
+Explicitly specified tags:
+
+```
+ answer: !!int "42"
+ name: !!str "Arthur Dent"
+```
+
+Implicit tags:
+
+```
+ answer: 42 #int
+ name: Arthur Dent #string
+```
+
+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 |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 |