dyaml/docs/articles/spec_differences.md
Cameron Ross 03c9972485 convert docs to markdown and remove built doc artifacts (#153)
convert docs to markdown and remove built doc artifacts
merged-on-behalf-of: BBasile <BBasile@users.noreply.github.com>
2018-06-12 07:57:28 +02:00

2.2 KiB

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.