Skip to content

Added a note about the lacking features of Yaml Component #4208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 15, 2014
Merged

Added a note about the lacking features of Yaml Component #4208

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions components/yaml/introduction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,24 @@
single: Yaml
single: Components; Yaml

The YAML Component
The Yaml Component
==================

The YAML Component loads and dumps YAML files.
The Yaml Component loads and dumps YAML files.

What is It?
-----------

The Symfony2 YAML Component parses YAML strings to convert them to PHP arrays.
The Symfony2 Yaml Component parses YAML strings to convert them to PHP arrays.
It is also able to convert PHP arrays to YAML strings.

`YAML`_, *YAML Ain't Markup Language*, is a human friendly data serialization
standard for all programming languages. YAML is a great format for your
configuration files. YAML files are as expressive as XML files and as readable
as INI files.

The Symfony2 YAML Component implements the YAML 1.2 version of the
specification.
The Symfony2 Yaml Component implements a selected subset of features defined in
the `YAML 1.2 version specification`_.

.. tip::

Expand All @@ -40,8 +40,10 @@ Why?
Fast
~~~~

One of the goal of Symfony YAML is to find the right balance between speed and
features. It supports just the needed feature to handle configuration files.
One of the goals of Symfony Yaml is to find the right balance between speed and
features. It supports just the needed features to handle configuration files.
Notable lacking features are: document directives, multi-line quoted messages,
compact block collections and multi-document files.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think multi-line quoted messages and compact block collections could be fixed easily. I'll have a look at both issues. For the rest, I think we can improve the user experience a lot if we provide more sensible exception messages like the one I mentioned in symfony/symfony#8076.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree! But for now, we could add this note to prevent misunderstandings when using this component.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with you. We can update it whenever something changes in the code.


Real Parser
~~~~~~~~~~~
Expand Down Expand Up @@ -78,7 +80,7 @@ yourself by referencing common configuration bits.
Using the Symfony2 YAML Component
---------------------------------

The Symfony2 YAML Component is very simple and consists of two main classes:
The Symfony2 Yaml Component is very simple and consists of two main classes:
one parses YAML strings (:class:`Symfony\\Component\\Yaml\\Parser`), and the
other dumps a PHP array to a YAML string
(:class:`Symfony\\Component\\Yaml\\Dumper`).
Expand Down Expand Up @@ -163,7 +165,7 @@ array to its YAML representation:

.. note::

Of course, the Symfony2 YAML dumper is not able to dump resources. Also,
Of course, the Symfony2 Yaml dumper is not able to dump resources. Also,
even if the dumper is able to dump PHP objects, it is considered to be a
not supported feature.

Expand Down Expand Up @@ -213,3 +215,4 @@ representation to the inline one:

.. _YAML: http://yaml.org/
.. _Packagist: https://packagist.org/packages/symfony/yaml
.. _`YAML 1.2 version specification`: http://yaml.org/spec/1.2/spec.html