debian-packages/dyaml
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Loader doc style update.

Browse source
This commit is contained in:
Ferdinand Majerech 2014-07-19 14:32:16 +02:00
parent bc7519f561
commit d2fe876316
1 changed files with 111 additions and 125 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

236
source/dyaml/loader.d
View file

@ -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,82 +23,80 @@ 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:
///Reads character data from a stream.
/// Reads character data from a stream.
Reader reader_;
///Processes character data to YAML tokens.
/// Processes character data to YAML tokens.
Scanner scanner_;
///Processes tokens to YAML events.
/// Processes tokens to YAML events.
Parser parser_;
///Resolves tags (data types).
/// Resolves tags (data types).
Resolver resolver_;
///Constructs YAML data types.
/// Constructs YAML data types.
Constructor constructor_;
///Name of the input file or stream, used in error messages.
/// Name of the input file or stream, used in error messages.
string name_ = "<unknown>";
///Are we done loading?
/// Are we done loading?
bool done_ = false;
public:
@ -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
@ -164,7 +156,7 @@ struct Loader
}
}
///Destroy the Loader.
/// Destroy the Loader.
@trusted ~this()
{
reader_.destroy();
@ -172,36 +164,34 @@ struct Loader
parser_.destroy();
}
///Set stream _name. Used in debugging messages.
/// Set stream _name. Used in debugging messages.
@property void name(string name) pure @safe nothrow
{
name_ = name;
}
///Specify custom Resolver to use.
/// Specify custom Resolver to use.
@property void resolver(Resolver resolver) pure @safe nothrow
{
resolver_ = resolver;
}
///Specify custom Constructor to use.
/// Specify custom Constructor to use.
@property void constructor(Constructor constructor) pure @safe nothrow
{
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
{
@ -283,7 +269,7 @@ struct Loader
}
package:
//Scan and return all tokens. Used for debugging.
// Scan and return all tokens. Used for debugging.
Token[] scan() @safe
{
try
@ -299,7 +285,7 @@ struct Loader
}
}
//Parse and return all events. Used for debugging.
// Parse and return all events. Used for debugging.
immutable(Event)[] parse() @safe
{
try