C# Class System.Yaml.YamlNode

Abstract base class of YAML data nodes.

See YamlScalar, YamlSequence and YamlMapping for actual data classes.

YAML data model

See http://yaml.org/ for the official definition of Information Models of YAML.

YAML data structure is defined as follows. Note that this does not represents the text syntax of YAML text but does logical data structure.

yaml-stream ::= yaml-document*
yaml-document ::= yaml-directive* yaml-node
yaml-directive ::= YAML-directive | TAG-directive | user-defined-directive
yaml-node ::= yaml-scalar | yaml-sequence | yaml-mapping
yaml-scalar ::= yaml-tag yaml-value
yaml-sequence ::= yaml-tag yaml-node*
yaml-mapping ::= yaml-tag ( yaml-node yaml-node )*
yaml-tag ::= yaml-global-tag yaml-local-tag
yaml-global-tag ::= "tag:" taggingEntity ":" specific [ "#" fragment ]
yaml-local-tag ::= "!" yaml-local-tag-name

Namely,

A YAML stream consists of zero or more YAML documents.
A YAML documents have zero or more YAML directives and a root YAML node.
A YAML directive is either YAML-directive, TAG-directive or user-defined-directive.
A YAML node is either YAML scalar, YAML sequence or YAML mapping.
A YAML scalar consists of a YAML tag and a scalar value.
A YAML sequence consists of a YAML tag and zero or more child YAML nodes.
A YAML mapping cosists of a YAML tag and zero or more key/value pairs of YAML nodes.
A YAML tag is either a YAML global tag or a YAML local tag.
A YAML global tag starts with "tag:" and described in the "tag:" URI scheme defined in RFC4151.
A YAML local tag starts with "!" with a YAML local tag name

// Construct YAML node tree YamlNode node = new YamlSequence( // !!seq node new YamlScalar("abc"), // !!str node new YamlScalar("!!int", "123"), // !!int node new YamlScalar("!!float", "1.23"), // !!float node new YamlSequence( // nesting !!seq node new YamlScalar("def"), new YamlScalar("ghi") ), new YamlMapping( // !!map node new YamlScalar("key1"), new YamlScalar("value1"), new YamlScalar("key2"), new YamlScalar("value2"), new YamlScalar("key3"), new YamlMapping( // nesting !!map node new YamlScalar("value3key1"), new YamlScalar("value3value1") ), new YamlScalar("key4"), new YamlScalar("value4") ) ); // Convert it to 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 node from the YAML stream. // Note that a YAML stream can contain several YAML documents each of which // contains a root YAML node. YamlNode[] nodes = YamlNode.FromYaml(yaml); // The only one node in the stream is the one we have presented 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[new YamlScalar("key3")]; // Modify the restored node tree map2[new YamlScalar("value3key1")] = new YamlScalar("value3value1 modified"); // Now they are not equal to each other. Assert.AreNotEquel(node, restored);

YamlNode class

YamlNode is an abstract class that represents a YAML node.

In reality, a YamlNode is either YamlScalar, YamlSequence or YamlMapping.

All YamlNode has YamlNode.Tag property that denotes the actual data type represented in the YAML node.

Default Tag value for YamlScalar, YamlSequence or YamlMapping are "tag:yaml.org,2002:str", "tag:yaml.org,2002:seq", "tag:yaml.org,2002:map".

Global tags that starts with "tag:yaml.org,2002:" ( = YamlNode.DefaultTagPrefix) are defined in the YAML tag repository at http://yaml.org/type/. In this library, such a tags can be also represented in a short form that starts with "!!", like "!!str", "!!seq" and "!!map". Tags in the formal style and the shorthand form can be converted to each other by the static methods of YamlNode.ExpandTag and YamlNode.ShorthandTag(string). In addition to these three basic tags, this library uses "!!null", "!!bool", "!!int", "!!float" and "!!timestamp" tags, by default.

YamlNodes can be read from a YAML stream with YamlNode.FromYaml(string), YamlNode.FromYaml(Stream), YamlNode.FromYaml(TextReader) and YamlNode.FromYamlFile(string) static methods. Since a YAML stream generally consist of multiple YAML documents, each of which has a root YAML node, these methods return an array of YamlNode that is contained in the stream.

YamlNodes can be written to a YAML stream with YamlNode.ToYaml(), YamlNode.ToYaml(Stream), YamlNode.ToYaml(TextWriter) and YamlNode.ToYamlFile(string).

The way of serialization can be configured in some aspects. The custom settings are specified by an instance of YamlConfig class. The serialization methods introduced above has overloaded styles that accepts YamlConfig instance to customize serialization. It is also possible to change the default serialization method by modifying YamlNode.DefaultConfig static property.

A YamlScalar has YamlScalar.Value property, which holds the string expression of the node value.

A YamlSequence implements IList<YamlNode> interface to access the child nodes.

YamlMapping implements IDictionary<YamlNode,YamlNode> interface to access the key/value pairs under the node.

Implicit conversion from C# native object to YamlScalar

Implicit cast operators from string, bool, int, double and DateTime to YamlNode is defined. Thus, anytime YamlNode is required in C# source, naked scalar value can be written. Namely, methods of YamlSequence and YamlMapping accept such C# native types as arguments in addition to YamlNode types.

var map = new YamlMapping(); map["Time"] = DateTime.Now; // implicitly converted to YamlScalar Assert.IsTrue(map.ContainsKey(new YamlScalar("Time"))); Assert.IsTrue(map.ContainsKey("Time")); // implicitly converted to YamlScalar

Equality of YamlNodes

Equality of YamlNodes are evaluated on the content base. Different YamlNode objects that have the same content are evaluated to be equal. Use Equals(object) method for equality evaluation.

In detail, two YamlNodes are logically equal to each other when the YamlNode and its child nodes have the same contents (YamlNode.Tag and YamlScalar.Value) and their node graph topology is exactly same.

YamlNode a1 = "a"; // implicit conversion YamlNode a2 = "a"; // implicit conversion YamlNode a3 = new YamlNode("!char", "a"); YamlNode b = "b"; // implicit conversion Assert.IsTrue(a1 != a2); // different objects Assert.IsTrue(a1.Equals(a2)); // different objects having same content Assert.IsFalse(a1.Equals(a3)); // Tag is different Assert.IsFalse(a1.Equals(b)); // Value is different var s1 = new YamlMapping(a1, new YamlSequence(a1, a2)); var s2 = new YamlMapping(a1, new YamlSequence(a2, a1)); var s3 = new YamlMapping(a2, new YamlSequence(a1, a2)); Assert.IsFalse(s1.Equals(s2)); // node graph topology is different Assert.IsFalse(s1.Equals(s3)); // node graph topology is different Assert.IsTrue(s2.Equals(s3)); // different objects having same content and node graph topology
Inheritance: IRehashableKey
Mostrar archivo Open project: jbruening/YamlSerializer-Fork Class Usage Examples

Private Properties

Property Type Description
Equals bool
EqualsSub bool
OnLoaded void
ToString string
YamlNode System.Collections.Generic

Public Methods

Method Description
Equals ( object obj ) : bool

Returns true if obj is of same type as the YamlNode and its content is also logically same.

Two YamlNode's are logically equal when the YamlNode and its child nodes have the same contents (YamlNode.Tag and YamlScalar.Value) and their node graph topology is exactly same as the other.

ExpandTag ( string tag ) : string

Convert shorthand tag starting with "!!" to the formal style that starts with "tag:yaml.org,2002:".

When tag starts with "!!", it is converted into formal style. Otherwise, tag is returned as is.

FromYaml ( Stream s ) : System.Yaml.YamlNode[]

Convert YAML text yaml to a list of YamlNode.

FromYaml ( Stream s, YamlConfig config ) : System.Yaml.YamlNode[]

Convert YAML text yaml to a list of YamlNode.

FromYaml ( TextReader tr ) : System.Yaml.YamlNode[]

Convert YAML text yaml to a list of YamlNode.

FromYaml ( TextReader tr, YamlConfig config ) : System.Yaml.YamlNode[]

Convert YAML text yaml to a list of YamlNode.

FromYaml ( string yaml ) : System.Yaml.YamlNode[]

Convert YAML text yaml to a list of YamlNode.

FromYaml ( string yaml, YamlConfig config ) : System.Yaml.YamlNode[]

Convert YAML text yaml to a list of YamlNode.

FromYamlFile ( string FileName ) : System.Yaml.YamlNode[]

Convert YAML text yaml to a list of YamlNode.

FromYamlFile ( string FileName, YamlConfig config ) : System.Yaml.YamlNode[]

Convert YAML text yaml to a list of YamlNode.

GetHashCode ( ) : int

Serves as a hash function for a particular type. Hash code is calculated using Tag and Value properties.

ShorthandTag ( ) : string

YAML Tag for this node, which represents the type of node's value. The Tag property is returned in a shorthand style.

ShorthandTag ( string tag ) : string

Convert a formal style tag that starts with "tag:yaml.org,2002:" to the shorthand style that starts with "!!".

When tag contains YAML standard types, it is converted into !!xxx style. Otherwise, tag is returned as is.

ToString ( ) : string

Returns a String that represents the current Object.

ToYaml ( ) : string

Convert YamlNode to a YAML text.

ToYaml ( YamlConfig config ) : string

Convert YamlNode to a YAML text.

ToYaml ( Stream s ) : void

Convert YamlNode to a YAML text and save it to Stream s.

ToYaml ( Stream s, YamlConfig config ) : void

Convert YamlNode to a YAML text and save it to Stream s.

ToYaml ( TextWriter tw ) : void

Convert YamlNode to a YAML text and save it to TextWriter tw.

ToYaml ( TextWriter tw, YamlConfig config ) : void

Convert YamlNode to a YAML text and save it to TextWriter tw.

ToYamlFile ( string FileName ) : void

Convert YamlNode to a YAML text and save it to the file.

ToYamlFile ( string FileName, YamlConfig config ) : void

Convert YamlNode to a YAML text and save it to the file.

Protected Methods

Method Description
GetHashCodeCore ( ) : int

Return the hash code. The returned value will be cached until OnChanged is called.

OnChanged ( ) : void

Call this function when the content of the node is changed.

Private Methods

Method Description
Equals ( YamlNode b, ObjectRepository repository ) : bool

Returns true if b is of same type as the YamlNode and its content is also logically same.

EqualsSub ( YamlNode b, ObjectRepository repository, bool &skip ) : bool

Returns true if b is of same type as the YamlNode and its Tag is same as the node. It returns true for skip if they both already appeared in the node trees and were compared.

OnLoaded ( ) : void

Called when the node is loaded from a document.

ToString ( int &length ) : string
YamlNode ( ) : System.Collections.Generic

Method Details

Equals() public method

Returns true if obj is of same type as the YamlNode and its content is also logically same.
Two YamlNode's are logically equal when the YamlNode and its child nodes have the same contents (YamlNode.Tag and YamlScalar.Value) and their node graph topology is exactly same as the other.
public Equals ( object obj ) : bool
obj object Object to be compared.
return bool

ExpandTag() public static method

Convert shorthand tag starting with "!!" to the formal style that starts with "tag:yaml.org,2002:".
When tag starts with "!!", it is converted into formal style. Otherwise, tag is returned as is.
public static ExpandTag ( string tag ) : string
tag string Tag in the shorthand style.
return string

FromYaml() public static method

Convert YAML text yaml to a list of YamlNode.
public static FromYaml ( Stream s ) : System.Yaml.YamlNode[]
s System.IO.Stream from which YAML document is read.
return System.Yaml.YamlNode[]

FromYaml() public static method

Convert YAML text yaml to a list of YamlNode.
public static FromYaml ( Stream s, YamlConfig config ) : System.Yaml.YamlNode[]
s System.IO.Stream from which YAML document is read.
config YamlConfig YAML configuration to customize serialization.
return System.Yaml.YamlNode[]

FromYaml() public static method

Convert YAML text yaml to a list of YamlNode.
public static FromYaml ( TextReader tr ) : System.Yaml.YamlNode[]
tr System.IO.TextReader from which YAML document is read.
return System.Yaml.YamlNode[]

FromYaml() public static method

Convert YAML text yaml to a list of YamlNode.
public static FromYaml ( TextReader tr, YamlConfig config ) : System.Yaml.YamlNode[]
tr System.IO.TextReader from which YAML document is read.
config YamlConfig YAML configuration to customize serialization.
return System.Yaml.YamlNode[]

FromYaml() public static method

Convert YAML text yaml to a list of YamlNode.
public static FromYaml ( string yaml ) : System.Yaml.YamlNode[]
yaml string YAML text
return System.Yaml.YamlNode[]

FromYaml() public static method

Convert YAML text yaml to a list of YamlNode.
public static FromYaml ( string yaml, YamlConfig config ) : System.Yaml.YamlNode[]
yaml string YAML text
config YamlConfig YAML configuration to customize serialization.
return System.Yaml.YamlNode[]

FromYamlFile() public static method

Convert YAML text yaml to a list of YamlNode.
public static FromYamlFile ( string FileName ) : System.Yaml.YamlNode[]
FileName string YAML File Name
return System.Yaml.YamlNode[]

FromYamlFile() public static method

Convert YAML text yaml to a list of YamlNode.
public static FromYamlFile ( string FileName, YamlConfig config ) : System.Yaml.YamlNode[]
FileName string YAML File Name
config YamlConfig YAML configuration to customize serialization.
return System.Yaml.YamlNode[]

GetHashCode() public method

Serves as a hash function for a particular type. Hash code is calculated using Tag and Value properties.
public GetHashCode ( ) : int
return int

GetHashCodeCore() protected abstract method

Return the hash code. The returned value will be cached until OnChanged is called.
protected abstract GetHashCodeCore ( ) : int
return int

OnChanged() protected method

Call this function when the content of the node is changed.
protected OnChanged ( ) : void
return void

ShorthandTag() public method

YAML Tag for this node, which represents the type of node's value. The Tag property is returned in a shorthand style.
public ShorthandTag ( ) : string
return string

ShorthandTag() public static method

Convert a formal style tag that starts with "tag:yaml.org,2002:" to the shorthand style that starts with "!!".
When tag contains YAML standard types, it is converted into !!xxx style. Otherwise, tag is returned as is.
public static ShorthandTag ( string tag ) : string
tag string Tag in formal style.
return string

ToString() public method

Returns a String that represents the current Object.
public ToString ( ) : string
return string

ToYaml() public method

Convert YamlNode to a YAML text.
public ToYaml ( ) : string
return string

ToYaml() public method

Convert YamlNode to a YAML text.
public ToYaml ( YamlConfig config ) : string
config YamlConfig YAML configuration to customize serialization.
return string

ToYaml() public method

Convert YamlNode to a YAML text and save it to Stream s.
public ToYaml ( Stream s ) : void
s System.IO.Stream to output.
return void

ToYaml() public method

Convert YamlNode to a YAML text and save it to Stream s.
public ToYaml ( Stream s, YamlConfig config ) : void
s System.IO.Stream to output.
config YamlConfig YAML configuration to customize serialization.
return void

ToYaml() public method

Convert YamlNode to a YAML text and save it to TextWriter tw.
public ToYaml ( TextWriter tw ) : void
tw System.IO.TextWriter to output.
return void

ToYaml() public method

Convert YamlNode to a YAML text and save it to TextWriter tw.
public ToYaml ( TextWriter tw, YamlConfig config ) : void
tw System.IO.TextWriter to output.
config YamlConfig YAML configuration to customize serialization.
return void

ToYamlFile() public method

Convert YamlNode to a YAML text and save it to the file.
public ToYamlFile ( string FileName ) : void
FileName string Name of the file to output
return void

ToYamlFile() public method

Convert YamlNode to a YAML text and save it to the file.
public ToYamlFile ( string FileName, YamlConfig config ) : void
FileName string Name of the file to output
config YamlConfig YAML configuration to customize serialization.
return void