YamlSerializer for .NET

日本語版はこちら

What is this for?

This class library supports YAML file manipulation in two different contexts.
  • One is to serialize / deserialize C# native objects into / from YAML 1.2 text files. (Most of you need this.) => YamlSerizlizer class
  • The other is to manipulate generic YAML 1.2 documents that does not represent C# object but does some unknown logical data. (You rarely need this.) => YamlNode class

Requirements

.NET 3.5 SP1

What is YAML?

YAML is a human friendly data serialization standard for all programming languages.

There is a good introduction in the YAML for .NET, Visual Studio and Powershell project.

According to that,
  • YAML is easily readable by humans.
  • YAML is consise and compact.
  • YAML is expressive and extensible.

Another introduction can be found at Yaml Cookbook.

See The Official YAML Web Site for the language specification.

Note that the top page of The Official YAML Web Site is written as a valid YAML 1.2 document. It is definitely human friendly.

YamlSerizlizer class 

For the first purpose of this library, System.Yaml.Serialization.YamlSerizlizer class has instance methods YamlSerializer.Serialize and YamlSerializer.Deserialize. With these methods, C# native objects can be converted into / from YAML text without any preparations.

Details => YamlSerizlizer.

// Simple(?) array of objects
object obj = new object[]{ 
    "a", 
    true, 
    1, 
    1.0, 
    new Point(1,3), 
    new YamlScalar("node") 
};

var serializer = new YamlSerializer();

// Serialize it. How difficult!
string yaml = serializer.Serialize( obj );

// %YAML 1.2
// ---
// - "a"
// - true
// - 1
// - !!float 1
// - !System.Drawing.Point 1,3
// - !YamlSerializer.YamlScalar
//   Tag: "tag:yaml.org,2002:str"
//   Value: "node"
// ...

// Deserialize it.
object restored = serializer.Deserialize(yaml)[0];

// In general, you can serialize multiple objects in a YAML stream.
// So the Deserialize method returns an array of objects.

YamlNode class

For the second purpose, System.Yaml.YamlNode class and its descendant classes give the representation of YAML's data nodes.

If you do not know the exact structure of a YAML document and it might contain a special
data tag that do not corresponds to a concrete C# class, you need to go this way.
Although YamlNode is flexible, you have to convert the YamlNodes to C# objects BY YOURSELVES.
So, if you can use YamlSerizlizer class instead, do so because it's easier.

To read / write YAML text to compose / present YamlNode tree, the static method YamlNode.FromYaml and the instance method YamlNode.ToYaml are provided.

Details => YamlNode.

// Construct YAML node tree
YamlNode node = 
    new YamlSequence(                           // !!seq node
        "abc",                                  // !!str node
        123,                                    // !!int node
        1.23,                                   // !!float node
        new YamlSequence(                       // nesting !!seq node
            "def",
            "ghi"
        ),
        new YamlMapping(                        // !!map node
            "key1", "value1",
            "key2", "value2",
            "key3", new YamlMapping(            // nesting !!map node
                "value3key1", "value3value1"
            ),
            "key4", "value4"
        )
    );

// Convert it to a YAML stream
string yaml = node.ToYaml();

// %YAML 1.2
// ---
// - abc
// - 123
// - 1.23
// - - def
//   - ghi
// - key1: value1
//   key2: value2
//   key3:
//     value3key1: value3value1
//   key4: value4
// ...

// Load the YAML nodes from the YAML stream.
// Note that, in general, a YAML stream can contain several YAML documents, 
// each of which contains a root YAML node.
YamlNode[] nodes = YamlNode.FromYaml(yaml);

// The only one root node in the stream is the one we have created above.
Assert.AreEqual(1, nodes.Length);
YamlNode resotred = nodes[0];

// Check if they are equal to each other.
Assert.AreEquel(node, restored);

// Extract sub nodes.
var seq = (YamlSequence)restored;
var map = (YamlMapping)seq[4];
var map2 = (YamlMapping)map["key3"];

// Modify the restored node tree
map2["value3key1"] = "value3value1 modified";

// Now they are not equal to each other.
Assert.AreNotEquel(node, restored);

Last edited Jul 19, 2013 at 2:11 AM by osamu, version 23