First stab at a basic yaml dom api

Jan 6, 2009 at 7:46 PM
Edited Jan 7, 2009 at 9:02 PM
A C# yaml api:
 Design Goals:
  - Ease of use for the map and the list.
  - Similar to Lua Table and Python dictionary semantics.
  - using only the types from the Core Schema as possible values for given
    nodes. i.e. Doing var c = new ComplexObject(); yamlNode.Add(c);
    would error since CompelxObject is not in the Core Schema.
  - In order to support complex types the below functions could be wrapped
    within a more robust object that would support complex object serialization
    into the types native to yaml, the Core Schema.
  - Useful methods to create and link anchors into a given document.
 The Yaml Node Member List:
  General Functions:
   - An iterator with the type KeyValuePair<object,object> this would work for both lists and maps. This is similar to the table construct in Lua.
   - The overloaded [] operator doing duty for lists and maps. Allow access to keys
     and indexes depending on the context.
   - Use of the below functions outside their indented context would
     generate an error.
   - CreateEmptyList() sets the given node to the list type.
   - CreateEmptyMap() sets the given node to the map type.
  List Only:
   - Add( object o )
   - Remove( int index )
  Map Only:
   - Add( object key, object value) Fails if the object already exists. While
     node["foo"] = "bar" would either create a new key value or set an existing
   - Remove( object key )
  Scalar Only:
   - Value a property with the get and set exposed.
  Drawbacks and Areas that need more thought:
   Within this early framework the burden in on the user code to know and
   convert to the types that appear from the various accesor methods. I have
   considered getting rid of the [] and replacing it with a methods like
   DesiredType Get<DesiredType>( int index )
   and DesiredType Get<DesiredType>( object key ). These methods would give us
   the static typing we need in C# but erase the clean code found through using
   []. We could always do both.
  Under the  covers of Add(....):
   Each of the functions that take objects to be set into the dom will
   need to do type checking and appropriate tag resolution. For example
   Add( 1 ) and Add("1") would need to assign the int tag to the first and
   the tag str to the second in the underlying node structure. Another bit of
   complexity would be, var d = new Dictionary<int,int>(); yamlNode.Add( d );
   This seems like a good idea but I do not think we want to enforce our own
   runtime type checking. Calling Add( object o ) on an empty node with no
   underlying type ( map, list, scalar) would set that node the type indicated
   by the method.
 The whole reason I post this is to find out what is wrong with it and where it can be better. Plus it is valid yaml!
Jan 7, 2009 at 6:57 PM
- Thanks for the input, I'll digest it and reply with more detail soon.  

- If the question at the end is "is the document valid yaml?", it sure looks valid.  
  I checked it against my scanner, and with, a cool tool for
  such purposes.

- You can force text info a fixed with font (like this) which makes YAML a bit easier
  to read by switching into HTML view and putting in a <code></code> pair.  Someday,
  we may even be able to get Codeplex to do color support color highlighting of YAML
  like they do for other languages.
Jan 7, 2009 at 8:08 PM
One of the coolest things about YAML is that by design, its capable of supporting a languages native data types.  
For this reason, I wasn't planning a DOM as such, but rather to be able to serialize the .NET data types (including
the rich set of available collection data types) directly.  

Diagram 3.1 (in either version YAML 1.1 or 1.2 spec) describes some important aspect of this, providing a conceptual
framework with several stages in the process of loading and dumping data in YAML.   It also says those stages can
be optimized away if certain restrictions are followed.  While I definitely want to support Anchors & Aliases, thinking
of them as properties of nodes seems to run counter the ideas presented in that chapter.   The actual anchors names
associated with to nodes is a presentation detail that is supposed to be abstracted away in the serialize and compose
steps.   We should probably reword the last of your design goals