Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Splitted yaml component documentation #2178

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 4 commits into from
Jan 23, 2013
Merged

Splitted yaml component documentation #2178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e03965d
Moved yaml to his own map
wouterj Jan 22, 2013
e20e27e
Moved "The Yaml Format" to its own article
wouterj Jan 22, 2013
a6bde9f
Added some interlinking
wouterj Jan 22, 2013
2015c4a
Removed BC in changing url
wouterj Jan 22, 2013
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
3 changes: 2 additions & 1 deletion book/page_creation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -830,7 +830,8 @@ options of each feature.
three formats (YAML, XML and PHP). Each has its own advantages and
disadvantages. The choice of which to use is up to you:

* *YAML*: Simple, clean and readable;
* *YAML*: Simple, clean and readable (learn more about yaml in
* ":doc:`/components/yaml/yaml_format`");

* *XML*: More powerful than YAML at times and supports IDE autocompletion;

Expand Down
5 changes: 3 additions & 2 deletions components/map.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@

* :doc:`/components/templating`

* **YAML**
* :doc:`/components/yaml/index`

* :doc:`/components/yaml`
* :doc:`/components/yaml/introduction`
* :doc:`/components/yaml/yaml_format`
8 changes: 8 additions & 0 deletions components/yaml/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
Yaml
====

.. toctree::
:maxdepth: 2

introduction
yaml_format
272 changes: 5 additions & 267 deletions components/yaml.rst → components/yaml/introduction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,11 @@ as INI files.
The Symfony2 YAML Component implements the YAML 1.2 version of the
specification.

.. tip::

Learn more about the Yaml component in the
:doc:`/components/yaml/yaml_format` article.

Installation
------------

Expand Down Expand Up @@ -207,272 +212,5 @@ representation to the inline one:
foo: bar
bar: baz

The YAML Format
---------------

According to the official `YAML`_ website, YAML is "a human friendly data
serialization standard for all programming languages".

Even if the YAML format can describe complex nested data structure, this
chapter only describes the minimum set of features needed to use YAML as a
configuration file format.

YAML is a simple language that describes data. As PHP, it has a syntax for
simple types like strings, booleans, floats, or integers. But unlike PHP, it
makes a difference between arrays (sequences) and hashes (mappings).

Scalars
~~~~~~~

The syntax for scalars is similar to the PHP syntax.

Strings
.......

.. code-block:: yaml

A string in YAML

.. code-block:: yaml

'A singled-quoted string in YAML'

.. tip::

In a single quoted string, a single quote ``'`` must be doubled:

.. code-block:: yaml

'A single quote '' in a single-quoted string'

.. code-block:: yaml

"A double-quoted string in YAML\n"

Quoted styles are useful when a string starts or ends with one or more
relevant spaces.

.. tip::

The double-quoted style provides a way to express arbitrary strings, by
using ``\`` escape sequences. It is very useful when you need to embed a
``\n`` or a unicode character in a string.

When a string contains line breaks, you can use the literal style, indicated
by the pipe (``|``), to indicate that the string will span several lines. In
literals, newlines are preserved:

.. code-block:: yaml

|
\/ /| |\/| |
/ / | | | |__

Alternatively, strings can be written with the folded style, denoted by ``>``,
where each line break is replaced by a space:

.. code-block:: yaml

>
This is a very long sentence
that spans several lines in the YAML
but which will be rendered as a string
without carriage returns.

.. note::

Notice the two spaces before each line in the previous examples. They
won't appear in the resulting PHP strings.

Numbers
.......

.. code-block:: yaml

# an integer
12

.. code-block:: yaml

# an octal
014

.. code-block:: yaml

# an hexadecimal
0xC

.. code-block:: yaml

# a float
13.4

.. code-block:: yaml

# an exponential number
1.2e+34

.. code-block:: yaml

# infinity
.inf

Nulls
.....

Nulls in YAML can be expressed with ``null`` or ``~``.

Booleans
........

Booleans in YAML are expressed with ``true`` and ``false``.

Dates
.....

YAML uses the ISO-8601 standard to express dates:

.. code-block:: yaml

2001-12-14t21:59:43.10-05:00

.. code-block:: yaml

# simple date
2002-12-14

Collections
~~~~~~~~~~~

A YAML file is rarely used to describe a simple scalar. Most of the time, it
describes a collection. A collection can be a sequence or a mapping of
elements. Both sequences and mappings are converted to PHP arrays.

Sequences use a dash followed by a space:

.. code-block:: yaml

- PHP
- Perl
- Python

The previous YAML file is equivalent to the following PHP code:

.. code-block:: php

array('PHP', 'Perl', 'Python');

Mappings use a colon followed by a space (``:`` ) to mark each key/value pair:

.. code-block:: yaml

PHP: 5.2
MySQL: 5.1
Apache: 2.2.20

which is equivalent to this PHP code:

.. code-block:: php

array('PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20');

.. note::

In a mapping, a key can be any valid scalar.

The number of spaces between the colon and the value does not matter:

.. code-block:: yaml

PHP: 5.2
MySQL: 5.1
Apache: 2.2.20

YAML uses indentation with one or more spaces to describe nested collections:

.. code-block:: yaml

"symfony 1.0":
PHP: 5.0
Propel: 1.2
"symfony 1.2":
PHP: 5.2
Propel: 1.3

The following YAML is equivalent to the following PHP code:

.. code-block:: php

array(
'symfony 1.0' => array(
'PHP' => 5.0,
'Propel' => 1.2,
),
'symfony 1.2' => array(
'PHP' => 5.2,
'Propel' => 1.3,
),
);

There is one important thing you need to remember when using indentation in a
YAML file: *Indentation must be done with one or more spaces, but never with
tabulations*.

You can nest sequences and mappings as you like:

.. code-block:: yaml

'Chapter 1':
- Introduction
- Event Types
'Chapter 2':
- Introduction
- Helpers

YAML can also use flow styles for collections, using explicit indicators
rather than indentation to denote scope.

A sequence can be written as a comma separated list within square brackets
(``[]``):

.. code-block:: yaml

[PHP, Perl, Python]

A mapping can be written as a comma separated list of key/values within curly
braces (``{}``):

.. code-block:: yaml

{ PHP: 5.2, MySQL: 5.1, Apache: 2.2.20 }

You can mix and match styles to achieve a better readability:

.. code-block:: yaml

'Chapter 1': [Introduction, Event Types]
'Chapter 2': [Introduction, Helpers]

.. code-block:: yaml

"symfony 1.0": { PHP: 5.0, Propel: 1.2 }
"symfony 1.2": { PHP: 5.2, Propel: 1.3 }

Comments
~~~~~~~~

Comments can be added in YAML by prefixing them with a hash mark (``#``):

.. code-block:: yaml

# Comment on a line
"symfony 1.0": { PHP: 5.0, Propel: 1.2 } # Comment at the end of a line
"symfony 1.2": { PHP: 5.2, Propel: 1.3 }

.. note::

Comments are simply ignored by the YAML parser and do not need to be
indented according to the current level of nesting in a collection.

.. _YAML: http://yaml.org/
.. _Packagist: https://packagist.org/packages/symfony/yaml
Loading