Loader doc style update.
This commit is contained in:
parent
bc7519f561
commit
d2fe876316
|
@ -4,9 +4,7 @@
|
|||
// (See accompanying file LICENSE_1_0.txt or copy at
|
||||
// http://www.boost.org/LICENSE_1_0.txt)
|
||||
|
||||
/**
|
||||
* Class used to load YAML documents.
|
||||
*/
|
||||
/// Class used to load YAML documents.
|
||||
module dyaml.loader;
|
||||
|
||||
|
||||
|
@ -25,66 +23,64 @@ import dyaml.scanner;
|
|||
import dyaml.token;
|
||||
|
||||
|
||||
/**
|
||||
* Loads YAML documents from files or streams.
|
||||
*
|
||||
* User specified Constructor and/or Resolver can be used to support new
|
||||
* tags / data types.
|
||||
*
|
||||
* Examples:
|
||||
*
|
||||
* Load single YAML document from a file:
|
||||
* --------------------
|
||||
* auto rootNode = Loader("file.yaml").load();
|
||||
* ...
|
||||
* --------------------
|
||||
*
|
||||
* Load all YAML documents from a file:
|
||||
* --------------------
|
||||
* auto nodes = Loader("file.yaml").loadAll();
|
||||
* ...
|
||||
* --------------------
|
||||
*
|
||||
* Iterate over YAML documents in a file, lazily loading them:
|
||||
* --------------------
|
||||
* auto loader = Loader("file.yaml");
|
||||
*
|
||||
* foreach(ref node; loader)
|
||||
* {
|
||||
* ...
|
||||
* }
|
||||
* --------------------
|
||||
*
|
||||
* Load YAML from memory:
|
||||
* --------------------
|
||||
* import std.stream;
|
||||
* import std.stdio;
|
||||
*
|
||||
* string yaml_input = "red: '#ff0000'\n"
|
||||
* "green: '#00ff00'\n"
|
||||
* "blue: '#0000ff'";
|
||||
*
|
||||
* auto colors = Loader.fromString(yaml_input).load();
|
||||
*
|
||||
* foreach(string color, string value; colors)
|
||||
* {
|
||||
* writeln(color, " is ", value, " in HTML/CSS");
|
||||
* }
|
||||
* --------------------
|
||||
*
|
||||
* Use a custom constructor/resolver to support custom data types and/or implicit tags:
|
||||
* --------------------
|
||||
* auto constructor = new Constructor();
|
||||
* auto resolver = new Resolver();
|
||||
*
|
||||
* //Add constructor functions / resolver expressions here...
|
||||
*
|
||||
* auto loader = Loader("file.yaml");
|
||||
* loader.constructor = constructor;
|
||||
* loader.resolver = resolver;
|
||||
* auto rootNode = loader.load(node);
|
||||
* --------------------
|
||||
*/
|
||||
/// Loads YAML documents from files or streams.
|
||||
///
|
||||
/// User specified Constructor and/or Resolver can be used to support new
|
||||
/// tags / data types.
|
||||
///
|
||||
/// Examples:
|
||||
///
|
||||
/// Load single YAML document from a file:
|
||||
/// --------------------
|
||||
/// auto rootNode = Loader("file.yaml").load();
|
||||
/// ...
|
||||
/// --------------------
|
||||
///
|
||||
/// Load all YAML documents from a file:
|
||||
/// --------------------
|
||||
/// auto nodes = Loader("file.yaml").loadAll();
|
||||
/// ...
|
||||
/// --------------------
|
||||
///
|
||||
/// Iterate over YAML documents in a file, lazily loading them:
|
||||
/// --------------------
|
||||
/// auto loader = Loader("file.yaml");
|
||||
///
|
||||
/// foreach(ref node; loader)
|
||||
/// {
|
||||
/// ...
|
||||
/// }
|
||||
/// --------------------
|
||||
///
|
||||
/// Load YAML from memory:
|
||||
/// --------------------
|
||||
/// import std.stream;
|
||||
/// import std.stdio;
|
||||
///
|
||||
/// string yaml_input = "red: '#ff0000'\n"
|
||||
/// "green: '#00ff00'\n"
|
||||
/// "blue: '#0000ff'";
|
||||
///
|
||||
/// auto colors = Loader.fromString(yaml_input).load();
|
||||
///
|
||||
/// foreach(string color, string value; colors)
|
||||
/// {
|
||||
/// writeln(color, " is ", value, " in HTML/CSS");
|
||||
/// }
|
||||
/// --------------------
|
||||
///
|
||||
/// Use a custom constructor/resolver to support custom data types and/or implicit tags:
|
||||
/// --------------------
|
||||
/// auto constructor = new Constructor();
|
||||
/// auto resolver = new Resolver();
|
||||
///
|
||||
/// //Add constructor functions / resolver expressions here...
|
||||
///
|
||||
/// auto loader = Loader("file.yaml");
|
||||
/// loader.constructor = constructor;
|
||||
/// loader.resolver = resolver;
|
||||
/// auto rootNode = loader.load(node);
|
||||
/// --------------------
|
||||
struct Loader
|
||||
{
|
||||
private:
|
||||
|
@ -108,13 +104,11 @@ struct Loader
|
|||
@disable int opCmp(ref Loader);
|
||||
@disable bool opEquals(ref Loader);
|
||||
|
||||
/**
|
||||
* Construct a Loader to load YAML from a file.
|
||||
*
|
||||
* Params: filename = Name of the file to load from.
|
||||
*
|
||||
* Throws: YAMLException if the file could not be opened or read.
|
||||
*/
|
||||
/// Construct a Loader to load YAML from a file.
|
||||
///
|
||||
/// Params: filename = Name of the file to load from.
|
||||
///
|
||||
/// Throws: YAMLException if the file could not be opened or read.
|
||||
this(string filename) @trusted
|
||||
{
|
||||
name_ = filename;
|
||||
|
@ -140,13 +134,11 @@ struct Loader
|
|||
assert(Loader.fromString("42").load().as!int == 42);
|
||||
}
|
||||
|
||||
/**
|
||||
* Construct a Loader to load YAML from a _stream.
|
||||
*
|
||||
* Params: stream = Stream to read from. Must be readable and seekable.
|
||||
*
|
||||
* Throws: YAMLException if stream could not be read.
|
||||
*/
|
||||
/// Construct a Loader to load YAML from a _stream.
|
||||
///
|
||||
/// Params: stream = Stream to read from. Must be readable and seekable.
|
||||
///
|
||||
/// Throws: YAMLException if stream could not be read.
|
||||
this(Stream stream) @safe
|
||||
{
|
||||
try
|
||||
|
@ -190,18 +182,16 @@ struct Loader
|
|||
constructor_ = constructor;
|
||||
}
|
||||
|
||||
/**
|
||||
* Load single YAML document.
|
||||
*
|
||||
* If none or more than one YAML document is found, this throws a YAMLException.
|
||||
*
|
||||
* This can only be called once; this is enforced by contract.
|
||||
*
|
||||
* Returns: Root node of the document.
|
||||
*
|
||||
* Throws: YAMLException if there wasn't exactly one document
|
||||
* or on a YAML parsing error.
|
||||
*/
|
||||
/// Load single YAML document.
|
||||
///
|
||||
/// If none or more than one YAML document is found, this throws a YAMLException.
|
||||
///
|
||||
/// This can only be called once; this is enforced by contract.
|
||||
///
|
||||
/// Returns: Root node of the document.
|
||||
///
|
||||
/// Throws: YAMLException if there wasn't exactly one document
|
||||
/// or on a YAML parsing error.
|
||||
Node load() @safe
|
||||
in
|
||||
{
|
||||
|
@ -223,20 +213,18 @@ struct Loader
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Load all YAML documents.
|
||||
*
|
||||
* This is just a shortcut that iterates over all documents and returns
|
||||
* them all at once. Calling loadAll after iterating over the node or
|
||||
* vice versa will not return any documents, as they have all been parsed
|
||||
* already.
|
||||
*
|
||||
* This can only be called once; this is enforced by contract.
|
||||
*
|
||||
* Returns: Array of root nodes of all documents in the file/stream.
|
||||
*
|
||||
* Throws: YAMLException on a parsing error.
|
||||
*/
|
||||
/// Load all YAML documents.
|
||||
///
|
||||
/// This is just a shortcut that iterates over all documents and returns
|
||||
/// them all at once. Calling loadAll after iterating over the node or
|
||||
/// vice versa will not return any documents, as they have all been parsed
|
||||
/// already.
|
||||
///
|
||||
/// This can only be called once; this is enforced by contract.
|
||||
///
|
||||
/// Returns: Array of root nodes of all documents in the file/stream.
|
||||
///
|
||||
/// Throws: YAMLException on a parsing error.
|
||||
Node[] loadAll() @safe
|
||||
{
|
||||
Node[] nodes;
|
||||
|
@ -244,15 +232,13 @@ struct Loader
|
|||
return nodes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Foreach over YAML documents.
|
||||
*
|
||||
* Parses documents lazily, when they are needed.
|
||||
*
|
||||
* Foreach over a Loader can only be used once; this is enforced by contract.
|
||||
*
|
||||
* Throws: YAMLException on a parsing error.
|
||||
*/
|
||||
/// Foreach over YAML documents.
|
||||
///
|
||||
/// Parses documents lazily, when they are needed.
|
||||
///
|
||||
/// Foreach over a Loader can only be used once; this is enforced by contract.
|
||||
///
|
||||
/// Throws: YAMLException on a parsing error.
|
||||
int opApply(int delegate(ref Node) dg) @trusted
|
||||
in
|
||||
{
|
||||
|
|
Loading…
Reference in a new issue