# dyaml.dumper - D:YAML 0.5 API documentation

D:YAML 0.5 API documentation

# dyaml.dumper

YAML dumper.

Code based on PyYAML.

struct Dumper;

  Dumps YAML documents to files or streams.

  User specified Representer and/or Resolver can be used to support new tags / data types.
  Setters are provided to affect output details (style, encoding, etc.).

  Examples:
  Write to a file:

      auto node = Node([1, 2, 3, 4, 5]);
      Dumper("file.yaml").dump(node);

  Write multiple YAML documents to a file:

      auto node1 = Node([1, 2, 3, 4, 5]);
      auto node2 = Node("This document contains only one string");
      Dumper("file.yaml").dump(node1, node2);

      //Or with an array:
      //Dumper("file.yaml").dump([node1, node2]);

  Write to memory:

      import std.stream;
      auto stream = new MemoryStream();
      auto node = Node([1, 2, 3, 4, 5]);
      Dumper(stream).dump(node);

  Use a custom representer/resolver to support custom data types and/or implicit tags:

      auto node = Node([1, 2, 3, 4, 5]);
      auto representer = new Representer();
      auto resolver = new Resolver();

      //Add representer functions / resolver expressions here...

      auto dumper = Dumper("file.yaml");
      dumper.representer = representer;
      dumper.resolver = resolver;
      dumper.dump(node);

  @trusted this(string filename);

    Construct a Dumper writing to a file.

    Parameters:

    string filename | File name to write to.

    Throws:
    YAMLException if the file can not be dumped to (e.g. cannot be opened).
  @safe this(Stream stream);

    Construct a Dumper writing to a stream. This is useful to e.g. write to memory.

  pure nothrow @property @safe void name(string name);

    Set stream name. Used in debugging messages.

  @property @trusted void resolver(Resolver resolver);

    Specify custom Resolver to use.

  @property @trusted void representer(Representer representer);

    Specify custom Representer to use.

  pure nothrow @property @safe void canonical(bool canonical);

    Write scalars in canonical form?

  pure nothrow @property @safe void indent(uint indent);

    Set indentation width. 2 by default. Must not be zero.

  pure nothrow @property @safe void textWidth(uint width);

    Set preferred text width.

  pure nothrow @property @safe void lineBreak(LineBreak lineBreak);

    Set line break to use. Unix by default.

  pure nothrow @property @safe void encoding(Encoding encoding);

    Set character encoding to use. UTF-8 by default.

  pure nothrow @property @safe void explicitStart(bool explicit);

    Always explicitly write document start?

  pure nothrow @property @safe void explicitEnd(bool explicit);

    Always explicitly write document end?

  pure nothrow @property @safe void YAMLVersion(string YAMLVersion);

    Specify YAML version string. "1.1" by default.

  pure @property @trusted void tagDirectives(string[string] tags);

    Specify tag directives.

    A tag directive specifies a shorthand notation for specifying tags. Each tag directive associates a handle with a prefix. This allows for compact tag notation.
    Each handle specified MUST start and end with a '!' character (a single character "!" handle is allowed as well).
    Only alphanumeric characters, '-', and '_' may be used in handles.
    Each prefix MUST not be empty.
    The "!!" handle is used for default YAML tags with prefix "tag:yaml.org,2002:". This can be overridden.

    Parameters:

    string[string] tags | Tag directives (keys are handles, values are prefixes).

    Example:

        Dumper dumper = Dumper("file.yaml");
        string[string] directives;
        directives["!short!"] = "tag:long.org,2011:";
        //This will emit tags starting with "tag:long.org,2011"
        //with a "!short!" prefix instead.
        dumper.tagDirectives(directives);
        dumper.dump(Node("foo"));

  @trusted void dump(Node[] documents...);

    Dump one or more YAML documents to the file/stream.

    Note that while you can call dump() multiple times on the same dumper, you will end up writing multiple YAML "files" to the same file/stream.

    Parameters:

    Node[] documents | Documents to dump (root nodes of the documents).

    Throws:
    YAMLException on error (e.g. invalid nodes, unable to write to file/stream).

Copyright © Ferdinand Majerech 2011-2014. Based on PyYAML by Kirill Simonov. | Page generated by AutoDDoc and Ddoc.