diff --git a/autoddoc.cfg b/autoddoc.cfg index 741fd31..15aea1f 100644 --- a/autoddoc.cfg +++ b/autoddoc.cfg @@ -29,7 +29,7 @@ links = ../index.html Documentation home # Source files or patterns to ignore. Supports regexp syntax. # E.g; To ignore main.d and all source files in the test/ directory, # you would use: "main.d test/*" -ignore = test/*, examples/*, docsrc/*, autoddoc/*, yaml.d, unittest.d, cdc.d, dyaml/composer.d, dyaml/event.d, dyaml/parser.d, dyaml/reader.d, dyaml/scanner.d, dyaml/token.d, dyaml/util.d, dyaml/anchor.d, dyaml/emitter.d, dyaml/flags.d, dyaml/serializer.d, dyaml/sharedobject.d, dyaml/tag.d, dyaml/tagdirectives.d, dyaml/queue.d, dyaml/escapes.d, dyaml/fastcharsearch.d, dyaml/style.d +ignore = test/*, examples/*, docsrc/*, autoddoc/*, yaml.d, unittest.d, cdc.d, dyaml/composer.d, dyaml/event.d, dyaml/parser.d, dyaml/reader.d, dyaml/scanner.d, dyaml/token.d, dyaml/util.d, dyaml/anchor.d, dyaml/emitter.d, dyaml/flags.d, dyaml/serializer.d, dyaml/sharedobject.d, dyaml/tag.d, dyaml/tagdirectives.d, dyaml/queue.d, dyaml/escapes.d, dyaml/fastcharsearch.d [DDOC] # Command to use to generate the documentation. diff --git a/doc/doctrees/environment.pickle b/doc/doctrees/environment.pickle index 2c074b7..ecdd68c 100644 Binary files a/doc/doctrees/environment.pickle and b/doc/doctrees/environment.pickle differ diff --git a/doc/doctrees/tutorials/custom_types.doctree b/doc/doctrees/tutorials/custom_types.doctree index 98e74fb..3fe2c1c 100644 Binary files a/doc/doctrees/tutorials/custom_types.doctree and b/doc/doctrees/tutorials/custom_types.doctree differ diff --git a/doc/html/_sources/tutorials/custom_types.txt b/doc/html/_sources/tutorials/custom_types.txt index 35d48e0..9b3eaf5 100644 --- a/doc/html/_sources/tutorials/custom_types.txt +++ b/doc/html/_sources/tutorials/custom_types.txt @@ -2,15 +2,15 @@ Custom YAML data types ====================== -Often you might want to serialize complex data types such as classes. You can -use functions to process nodes such as a mapping containing class data members -indexed by name. Alternatively, YAML supports custom data types using -identifiers called *tags*. That is the topic of this tutorial. +Sometimes you need to serialize complex data types such as classes. To do this +you could use plain nodes such as mappings with class data members. However, +YAML 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, so you don't need to specify tag for each float, integer, etc. -It is also possible to implicitly resolve custom tags, as we will show later. +D:YAML can also implicitly resolve custom tags, as we will show later. ----------- @@ -18,16 +18,16 @@ Constructor ----------- D:YAML uses the `Constructor <../api/dyaml.constructor.html>`_ class to process -each node to hold data type corresponding to its tag. *Constructor* stores a -function for each supported tag to process it. These functions are supplied by -the user using the *addConstructorXXX()* methods, where *XXX* is *Scalar*, -*Sequence* or *Mapping*. *Constructor* is then passed to *Loader*, which parses -YAML input. +each node to hold data type corresponding to its tag. *Constructor* stores +functions to process each supported tag. These are supplied by the user using +the *addConstructorXXX()* methods, where *XXX* is *Scalar*, *Sequence* or +*Mapping*. *Constructor* is then passed to *Loader*, which parses YAML input. Struct types have no specific requirements for YAML support. Class types should define the *opEquals()* operator, as this is used in equality comparisons of nodes. Default class *opEquals()* compares references, which means two identical -objects might be considered unequal. +objects might be considered unequal. (Default struct *opEquals()* compares +byte-by-byte, sometimes you might want to override that as well.) We will implement support for an RGB color type. It is implemented as the following struct: @@ -173,10 +173,10 @@ You can find the source code for what we've done so far in the Resolver -------- -Specifying tag for every color value can be tedious. D:YAML can implicitly -resolve scalar tags using regular expressions. This is how default types such as -int 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). +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 @@ -228,9 +228,9 @@ D:YAML package. Representer ----------- -Now that you know how to load custom data types, it might also be useful to know -how to dump them. D:YAML uses the `Representer <../api/dyaml.representer.html>`_ -class for this purpose. +Now that you can load custom data types, it might be good to know how to dump +them. D:YAML uses the `Representer <../api/dyaml.representer.html>`_ class for +this purpose. *Representer* processes YAML nodes into plain mapping, sequence or scalar nodes ready for output. Just like with *Constructor*, this is done by user specified @@ -239,15 +239,14 @@ functions. These functions take references to a node to process and to the Representer functions can be added with the *addRepresenter()* method. The *Representer* is then passed to *Dumper*, which dumps YAML documents. Only one -representer can be added for a type. This is asserted in *addRepresenter()* -preconditions. By default, the default YAML types already have representer -functions, but you can disable them by constructing *Representer* with the +function per type can be specified. This is asserted in *addRepresenter()* +preconditions. Default YAML types already have representer functions specified, +but you can disable them by constructing *Representer* with the *useDefaultRepresenters* parameter set to false. -By default, tags are explicitly specified for all non-default types. If you -want the tags to be implicit, you can pass a *Resolver* that will resolve them -implicitly. Of course, you will then need to use an identical *Resolver* when -loading the output. +By default, tags are explicitly output for all non-default types. To make dumped +tags implicit, you can pass a *Resolver* that will resolve them implicitly. Of +course, you will need to use an identical *Resolver* when loading the output. With the following code, we will add support for dumping the our Color type. @@ -274,10 +273,10 @@ With the following code, we will add support for dumping the our Color type. First we get the *Color* from the node. Then we convert it to a string with the CSS-like format we've used before. Finally, we use the *representScalar()* -method of *Representer* to get a scalar node ready for output. -There are corresponding *representMapping()* and *representSequence()* methods +method of *Representer* to get a scalar node ready for output. There are +corresponding *representMapping()* and *representSequence()* methods as well, with examples in the -`Resolver API documentation <../api/dyaml.resolver.html>`_. +`Resolver API documentation <../api/dyaml.resolver.html>`_. Since a type can only have one representer function, we don't dump *Color* both in the scalar and mapping formats we've used before. However, you can decide to diff --git a/doc/html/api/dyaml.constructor.html b/doc/html/api/dyaml.constructor.html index 63d0eca..da144bb 100644 --- a/doc/html/api/dyaml.constructor.html +++ b/doc/html/api/dyaml.constructor.html @@ -32,6 +32,8 @@
Construct a Constructor.
@@ -89,7 +91,7 @@ defaultConstructors to disable constructor functions for these. -Parameters:bool defaultConstructors | +Parameters:
const(bool) defaultConstructors | Use constructors for default YAML tags? |
Position in a YAML stream, used for error messages.
-Construct a Mark with specified line and column in the file.
diff --git a/doc/html/api/dyaml.linebreak.html b/doc/html/api/dyaml.linebreak.html index 8e14db5..13e4e4f 100644 --- a/doc/html/api/dyaml.linebreak.html +++ b/doc/html/api/dyaml.linebreak.html @@ -32,6 +32,8 @@Construct a Loader to load YAML from a file.
-Parameters:string filename | +Parameters:
const(immutable(char)[]) filename | Name of the file to load from. |
Value node.
Construct a Pair from two values. Will be converted to Nodes if needed.
@@ -96,7 +98,7 @@Node collection style. Used to remember style this node was loaded with.
Construct a Node from a value.
@@ -124,7 +126,7 @@Construct a node from an array.
@@ -154,7 +156,7 @@Construct a node from an associative array.
@@ -186,7 +188,7 @@Construct a node from arrays of keys and values.
diff --git a/doc/html/api/dyaml.representer.html b/doc/html/api/dyaml.representer.html index 8f8f002..a97ceb6 100644 --- a/doc/html/api/dyaml.representer.html +++ b/doc/html/api/dyaml.representer.html @@ -32,6 +32,8 @@Set default style for scalars. Invalid means the style is chosen automatically.
+Set default style for scalars. Invalid means the style is chosen automatically.
Set default style for collections. Invalid means the style is chosen automatically.
+Set default style for collections. Invalid means the style is chosen automatically.
Can be used to implicitly resolve custom data types of scalar values.
-Construct a Resolver.
@@ -60,7 +62,7 @@ you can use defaultImplicitResolvers to disable default resolvers. -Parameters:bool defaultImplicitResolvers | +Parameters:
const(bool) defaultImplicitResolvers | Use default YAML implicit resolvers? |