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 // (See accompanying file LICENSE_1_0.txt or copy at
// http://www.boost.org/LICENSE_1_0.txt) // http://www.boost.org/LICENSE_1_0.txt)
/** /// Class used to load YAML documents.
* Class used to load YAML documents.
*/
module dyaml.loader; module dyaml.loader;
@ -25,82 +23,80 @@ import dyaml.scanner;
import dyaml.token; import dyaml.token;
/** /// Loads YAML documents from files or streams.
* Loads YAML documents from files or streams. ///
* /// User specified Constructor and/or Resolver can be used to support new
* User specified Constructor and/or Resolver can be used to support new /// tags / data types.
* tags / data types. ///
* /// Examples:
* Examples: ///
* /// Load single YAML document from a file:
* Load single YAML document from a file: /// --------------------
* -------------------- /// auto rootNode = Loader("file.yaml").load();
* auto rootNode = Loader("file.yaml").load(); /// ...
* ... /// --------------------
* -------------------- ///
* /// Load all YAML documents from a file:
* Load all YAML documents from a file: /// --------------------
* -------------------- /// auto nodes = Loader("file.yaml").loadAll();
* auto nodes = Loader("file.yaml").loadAll(); /// ...
* ... /// --------------------
* -------------------- ///
* /// Iterate over YAML documents in a file, lazily loading them:
* Iterate over YAML documents in a file, lazily loading them: /// --------------------
* -------------------- /// auto loader = Loader("file.yaml");
* auto loader = Loader("file.yaml"); ///
* /// foreach(ref node; loader)
* foreach(ref node; loader) /// {
* { /// ...
* ... /// }
* } /// --------------------
* -------------------- ///
* /// Load YAML from memory:
* Load YAML from memory: /// --------------------
* -------------------- /// import std.stream;
* import std.stream; /// import std.stdio;
* import std.stdio; ///
* /// string yaml_input = "red: '#ff0000'\n"
* string yaml_input = "red: '#ff0000'\n" /// "green: '#00ff00'\n"
* "green: '#00ff00'\n" /// "blue: '#0000ff'";
* "blue: '#0000ff'"; ///
* /// auto colors = Loader.fromString(yaml_input).load();
* auto colors = Loader.fromString(yaml_input).load(); ///
* /// foreach(string color, string value; colors)
* foreach(string color, string value; colors) /// {
* { /// writeln(color, " is ", value, " in HTML/CSS");
* writeln(color, " is ", value, " in HTML/CSS"); /// }
* } /// --------------------
* -------------------- ///
* /// Use a custom constructor/resolver to support custom data types and/or implicit tags:
* Use a custom constructor/resolver to support custom data types and/or implicit tags: /// --------------------
* -------------------- /// auto constructor = new Constructor();
* auto constructor = new Constructor(); /// auto resolver = new Resolver();
* auto resolver = new Resolver(); ///
* /// //Add constructor functions / resolver expressions here...
* //Add constructor functions / resolver expressions here... ///
* /// auto loader = Loader("file.yaml");
* auto loader = Loader("file.yaml"); /// loader.constructor = constructor;
* loader.constructor = constructor; /// loader.resolver = resolver;
* loader.resolver = resolver; /// auto rootNode = loader.load(node);
* auto rootNode = loader.load(node); /// --------------------
* --------------------
*/
struct Loader struct Loader
{ {
private: private:
///Reads character data from a stream. /// Reads character data from a stream.
Reader reader_; Reader reader_;
///Processes character data to YAML tokens. /// Processes character data to YAML tokens.
Scanner scanner_; Scanner scanner_;
///Processes tokens to YAML events. /// Processes tokens to YAML events.
Parser parser_; Parser parser_;
///Resolves tags (data types). /// Resolves tags (data types).
Resolver resolver_; Resolver resolver_;
///Constructs YAML data types. /// Constructs YAML data types.
Constructor constructor_; 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>"; string name_ = "<unknown>";
///Are we done loading? /// Are we done loading?
bool done_ = false; bool done_ = false;
public: public:
@ -108,13 +104,11 @@ struct Loader
@disable int opCmp(ref Loader); @disable int opCmp(ref Loader);
@disable bool opEquals(ref Loader); @disable bool opEquals(ref Loader);
/** /// Construct a Loader to load YAML from a file.
* Construct a Loader to load YAML from a file. ///
* /// Params: filename = Name of the file to load from.
* Params: filename = Name of the file to load from. ///
* /// Throws: YAMLException if the file could not be opened or read.
* Throws: YAMLException if the file could not be opened or read.
*/
this(string filename) @trusted this(string filename) @trusted
{ {
name_ = filename; name_ = filename;
@ -140,13 +134,11 @@ struct Loader
assert(Loader.fromString("42").load().as!int == 42); assert(Loader.fromString("42").load().as!int == 42);
} }
/** /// Construct a Loader to load YAML from a _stream.
* Construct a Loader to load YAML from a _stream. ///
* /// Params: stream = Stream to read from. Must be readable and seekable.
* Params: stream = Stream to read from. Must be readable and seekable. ///
* /// Throws: YAMLException if stream could not be read.
* Throws: YAMLException if stream could not be read.
*/
this(Stream stream) @safe this(Stream stream) @safe
{ {
try try
@ -164,7 +156,7 @@ struct Loader
} }
} }
///Destroy the Loader. /// Destroy the Loader.
@trusted ~this() @trusted ~this()
{ {
reader_.destroy(); reader_.destroy();
@ -172,36 +164,34 @@ struct Loader
parser_.destroy(); parser_.destroy();
} }
///Set stream _name. Used in debugging messages. /// Set stream _name. Used in debugging messages.
@property void name(string name) pure @safe nothrow @property void name(string name) pure @safe nothrow
{ {
name_ = name; name_ = name;
} }
///Specify custom Resolver to use. /// Specify custom Resolver to use.
@property void resolver(Resolver resolver) pure @safe nothrow @property void resolver(Resolver resolver) pure @safe nothrow
{ {
resolver_ = resolver; resolver_ = resolver;
} }
///Specify custom Constructor to use. /// Specify custom Constructor to use.
@property void constructor(Constructor constructor) pure @safe nothrow @property void constructor(Constructor constructor) pure @safe nothrow
{ {
constructor_ = constructor; constructor_ = constructor;
} }
/** /// Load single YAML document.
* Load single YAML document. ///
* /// If none or more than one YAML document is found, this throws a YAMLException.
* 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.
* This can only be called once; this is enforced by contract. ///
* /// Returns: Root node of the document.
* Returns: Root node of the document. ///
* /// Throws: YAMLException if there wasn't exactly one document
* Throws: YAMLException if there wasn't exactly one document /// or on a YAML parsing error.
* or on a YAML parsing error.
*/
Node load() @safe Node load() @safe
in in
{ {
@ -223,20 +213,18 @@ struct Loader
} }
} }
/** /// Load all YAML documents.
* Load all YAML documents. ///
* /// This is just a shortcut that iterates over all documents and returns
* This is just a shortcut that iterates over all documents and returns /// them all at once. Calling loadAll after iterating over the node or
* 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
* vice versa will not return any documents, as they have all been parsed /// already.
* already. ///
* /// This can only be called once; this is enforced by contract.
* This can only be called once; this is enforced by contract. ///
* /// Returns: Array of root nodes of all documents in the file/stream.
* Returns: Array of root nodes of all documents in the file/stream. ///
* /// Throws: YAMLException on a parsing error.
* Throws: YAMLException on a parsing error.
*/
Node[] loadAll() @safe Node[] loadAll() @safe
{ {
Node[] nodes; Node[] nodes;
@ -244,15 +232,13 @@ struct Loader
return nodes; return nodes;
} }
/** /// Foreach over YAML documents.
* Foreach over YAML documents. ///
* /// Parses documents lazily, when they are needed.
* Parses documents lazily, when they are needed. ///
* /// Foreach over a Loader can only be used once; this is enforced by contract.
* Foreach over a Loader can only be used once; this is enforced by contract. ///
* /// Throws: YAMLException on a parsing error.
* Throws: YAMLException on a parsing error.
*/
int opApply(int delegate(ref Node) dg) @trusted int opApply(int delegate(ref Node) dg) @trusted
in in
{ {
@ -283,7 +269,7 @@ struct Loader
} }
package: package:
//Scan and return all tokens. Used for debugging. // Scan and return all tokens. Used for debugging.
Token[] scan() @safe Token[] scan() @safe
{ {
try 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 immutable(Event)[] parse() @safe
{ {
try try