eZ components: Yaml (Requirements)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Author:   Josef Roth (webmaster@josef-roth.com)
:Author:   Thomas Nunninger (thomas@nunninger.info)
:Revision: $Rev$
:Date:     $Date$
:Status:   Draft

.. contents::


Scope
=====

The scope of this document is to describe the requirements of a new component
which will be able to read from and write to YAML streams.


Introduction
============

YAML_ (YAML Ain't Markup Language) "is a human friedly data serialization
standard for all programming languages." It is not restricted to reading from
resp. writing to files but each kind of stream can be used.

.. _YAML: http://yaml.org


YAML can be used for different use cases, e.g. configuration, simple documents,
data exchange, or logging. Therefore we decided to create a YAML component on
its own. The YAML component can be used by several other components like
Configuration, Document or EventLog to expand the possibilities of those
components to support the YAML format. As it is a dedicated component, it could
also be used in other projects easily.


Versions
========

There are two final versions of the YAML specification: 1.0 and 1.1.

Additionally there is a version 1.2 that is currently a working draft. Till now
it differs from YAML 1.1 in one single item, `line break characters`_: "YAML
version 1.1 did support the above line break characters; however, JSON does
not. Hence, to ensure JSON compatibility, YAML treats them as non-break
characters as of version 1.2. In theory this would cause incomatibility with
version 1.1; in practice these characters were rarely (if ever) used. YAML
processors parsing a version 1.1 document should therefore treat these line
breaks as non-break characters, with an appropriate warning.

.. _`line break characters`: http://yaml.org/spec/1.2/#id2574462

We want to support 1.0 and 1.1. But we are unsure about 1.2 as it is not final.
It would be nice to support the current state of 1.2 as it ensures JSON
compatibility. But what happens if the specification moves on and a new user
just reads: "YAML 1.2 (Working Draft 2008-05-11) support"? There could be wrong
expectations.


Existing Implementations
========================

Many implementations in different languages exist (have a look on the YAML
website). There are different solutions for PHP that have some disadvantages:

- syck_: This is a PECL extension based on a C library which is not maintained
  any more and that supports YAML 1.0 only. (There is another C library,
  LibYAML_, that supports YAML 1.1 but there are no PHP bindings.)

- spyc_: It is available in version 0.3 and supports YAML 1.0 only.

- sfYaml_: Symfony's rewrite of spyc. But it does not cover the whole
  specification and there is no information on which version it is based.

.. _syck:   http://pecl.php.net/package/syck
.. _spyc:   http://spyc.sourceforge.net/
.. _sfYaml: http://www.symfony-project.org/api/1_2/sfYaml
.. _LibYAML: http://pyyaml.org/wiki/LibYAML


Therefore we plan to write a PHP based YAML component.

Advantages:

- Easier (for us) then writing a PECL extension (based on the LibYAML).
  (Probably it should be possible to replace the YAML parser and dumper if such
  a PECL extension will be created sometimes.)

- No root privileges needed to install.

- Some additional stream related extensions for working with YAML beyond parse
  and dump of the existing solutions.

Disadvantage:

- Probably it is somehow slower than plain C. But this should not be that
  relevant for short documents. (And as written earlier: bindings to LibYAML
  should be integrated easily if available.)


Requirements
============

- The component should parse and dump YAML structures of version 1.0, 1.1.
  Perhaps 1.2 is supported as well.

- You should be able to define your own tag set to handle application specific
  datatypes of nodes.

- You should be able to tell the parser to behave like version X if no version
  information is available in the YAML structure.

- It should be possible to read from and write to arbitrary streams.

- After implementing the YAML component there should be a configuration tie-in,
  as that's the most asked question related to YAML.

- There should be an implementation of at least one other backend - if not only
  to see how feasible it would be to integrate them.

..
   Local Variables:
   mode: rst
   fill-column: 79
   End:
   vim: et syn=rst tw=79