.. highlight:: yaml

=====================================================
Differences between D:YAML and the YAML specification
=====================================================

There are some differences between D:YAML and the YAML 1.1 specification. Some 
are caused by difficulty of implementation of some features, such as multiple 
Unicode encodings within single stream, and some by unnecessary restrictions or
ambiguities in the specification. 

Still, D:YAML tries to be as close to the specification as possible. It should
never load documents with different meaning than according to the specification, 
and documents that fail to load should be very rare (for instance, very few 
files use multiple Unicode encodings).


--------------------------
List of known differences:
--------------------------

Differences that can cause valid YAML documents not to load:

* No support for byte order marks and multiple Unicode encodings in a stream.
* Plain scalars in flow context cannot contain ``,``, ``:`` and ``?``.
  This might change with ``:`` in the future. 
  See http://pyyaml.org/wiki/YAMLColonInFlowContext for details.
* The specification does not restrict characters for anchors and
  aliases. This may lead to problems, for instance, the document::

     [ *alias, value ]

  can be interpteted in two ways, as::

     [ "value" ]

  and::

     [ *alias , "value" ]

  Therefore we restrict aliases and anchors to ASCII alphanumeric characters.
* The specification is confusing about tabs in plain scalars. We don't use tabs 
  in plain scalars at all.
* There is no support for recursive data structures in DYAML.

Other differences:

* Indentation is ignored in the flow context, which is less restrictive than the
  specification. This allows code such as::

     key: {
     }

* Indentation rules for quoted scalars are loosed: They don't need to adhere
  indentation as ``"`` and ``'`` clearly mark the beginning and the end of them.
* We allow ``_`` in tag handles.
* Right now, two mappings with the same contents but different orderings are 
  considered unequal, even if they are unordered mappings. This is because all
  mappings are ordered in the D:YAML implementation. This should change in 
  future, once D associative arrays work with variant types or a map class or 
  struct appears in Phobos.
