diff --git a/source/dyaml/loader.d b/source/dyaml/loader.d index a7d9fa4..85fb4a7 100644 --- a/source/dyaml/loader.d +++ b/source/dyaml/loader.d @@ -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_ = ""; - ///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