fabpot-yaml/doc/02-YAML.markdown

The YAML Format
===============

According to the official [YAML](http://yaml.org/) 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

    [yml]
    A string in YAML

-

    [yml]
    'A singled-quoted string in YAML'

>**TIP**
>In a single quoted string, a single quote `'` must be doubled:
>
>     [yml]
>     'A single quote '' in a single-quoted string'

    [yml]
    "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:

    [yml]
    |
      \/ /| |\/| |
      / / | |  | |__

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

    [yml]
    >
      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

    [yml]
    # an integer
    12

-

    [yml]
    # an octal
    014

-

    [yml]
    # an hexadecimal
    0xC

-

    [yml]
    # a float
    13.4

-

    [yml]
    # an exponential number
    1.2e+34

-

    [yml]
    # infinity
    .inf

### Nulls

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

### Booleans

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

>**NOTE**
>The symfony YAML parser also recognize `on`, `off`, `yes`, and `no` but
>it is strongly discouraged to use them as it has been removed from the
>1.2 YAML specifications.

### Dates

YAML uses the ISO-8601 standard to express dates:

    [yml]
    2001-12-14t21:59:43.10-05:00

-

    [yml]
    # 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 (`- `):

    [yml]
    - PHP
    - Perl
    - Python

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

    [php]
    array('PHP', 'Perl', 'Python');

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

    [yml]
    PHP: 5.2
    MySQL: 5.1
    Apache: 2.2.20

which is equivalent to this PHP code:

    [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:

    [yml]
    PHP:    5.2
    MySQL:  5.1
    Apache: 2.2.20

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

    [yml]
    "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:

    [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:

    [yml]
    '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
(`[]`):

    [yml]
    [PHP, Perl, Python]

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

    [yml]
    { PHP: 5.2, MySQL: 5.1, Apache: 2.2.20 }

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

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

-

    [yml]
    "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 (`#`):

    [yml]
    # 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.

Dynamic YAML files
------------------

In symfony, a YAML file can contain PHP code that is evaluated just before the
parsing occurs:

    [php]
    1.0:
      version: <?php echo file_get_contents('1.0/VERSION')."\n" ?>
    1.1:
      version: "<?php echo file_get_contents('1.1/VERSION') ?>"

Be careful to not mess up with the indentation. Keep in mind the following
simple tips when adding PHP code to a YAML file:

 * The `<?php ?>` statements must always start the line or be embedded in a
   value.

 * If a `<?php ?>` statement ends a line, you need to explicitly output a new
   line ("\n").

<div class="pagebreak"></div>

A Full Length Example
---------------------

The following example illustrates most YAML notations explained in this
document:

    [yml]
    "symfony 1.0":
      end_of_maintainance: 2010-01-01
      is_stable:           true
      release_manager:     "Grégoire Hubert"
      description: >
        This stable version is the right choice for projects
        that need to be maintained for a long period of time.
      latest_beta:         ~
      latest_minor:        1.0.20
      supported_orms:      [Propel]
      archives:            { source: [zip, tgz], sandbox: [zip, tgz] }

    "symfony 1.2":
      end_of_maintainance: 2008-11-01
      is_stable:           true
      release_manager:     'Fabian Lange'
      description: >
        This stable version is the right choice
        if you start a new project today.
      latest_beta:         null
      latest_minor:        1.2.5
      supported_orms:
        - Propel
        - Doctrine
      archives:
        source:
          - zip
          - tgz
        sandbox:
          - zip
          - tgz
1	The YAML Format
2	===============
3
4	According to the official [YAML](http://yaml.org/) website, YAML is "a human
5	friendly data serialization standard for all programming languages".
6
7	Even if the YAML format can describe complex nested data structure, this
8	chapter only describes the minimum set of features needed to use YAML as a
9	configuration file format.
10
11	YAML is a simple language that describes data. As PHP, it has a syntax for
12	simple types like strings, booleans, floats, or integers. But unlike PHP, it
13	makes a difference between arrays (sequences) and hashes (mappings).
14
15	Scalars
16	-------
17
18	The syntax for scalars is similar to the PHP syntax.
19
20	### Strings
21
22	[yml]
23	A string in YAML
24
25	-
26
27	[yml]
28	'A singled-quoted string in YAML'
29
30	>TIP
31	>In a single quoted string, a single quote `'` must be doubled:
32	>
33	> [yml]
34	> 'A single quote '' in a single-quoted string'
35
36	[yml]
37	"A double-quoted string in YAML\n"
38
39	Quoted styles are useful when a string starts or ends with one or more
40	relevant spaces.
41
42	>TIP
43	>The double-quoted style provides a way to express arbitrary strings, by
44	>using `\` escape sequences. It is very useful when you need to embed a
45	>`\n` or a unicode character in a string.
46
47	When a string contains line breaks, you can use the literal style, indicated
48	by the pipe (`\|`), to indicate that the string will span several lines. In
49	literals, newlines are preserved:
50
51	[yml]
52	\|
53	\/ /\| \|\/\| \|
54	/ / \| \| \| \|__
55
56	Alternatively, strings can be written with the folded style, denoted by `>`,
57	where each line break is replaced by a space:
58
59	[yml]
60	>
61	This is a very long sentence
62	that spans several lines in the YAML
63	but which will be rendered as a string
64	without carriage returns.
65
66	>NOTE
67	>Notice the two spaces before each line in the previous examples. They
68	>won't appear in the resulting PHP strings.
69
70	### Numbers
71
72	[yml]
73	# an integer
74	12
75
76	-
77
78	[yml]
79	# an octal
80	014
81
82	-
83
84	[yml]
85	# an hexadecimal
86	0xC
87
88	-
89
90	[yml]
91	# a float
92	13.4
93
94	-
95
96	[yml]
97	# an exponential number
98	1.2e+34
99
100	-
101
102	[yml]
103	# infinity
104	.inf
105
106	### Nulls
107
108	Nulls in YAML can be expressed with `null` or `~`.
109
110	### Booleans
111
112	Booleans in YAML are expressed with `true` and `false`.
113
114	>NOTE
115	>The symfony YAML parser also recognize `on`, `off`, `yes`, and `no` but
116	>it is strongly discouraged to use them as it has been removed from the
117	>1.2 YAML specifications.
118
119	### Dates
120
121	YAML uses the ISO-8601 standard to express dates:
122
123	[yml]
124	2001-12-14t21:59:43.10-05:00
125
126	-
127
128	[yml]
129	# simple date
130	2002-12-14
131
132	Collections
133	-----------
134
135	A YAML file is rarely used to describe a simple scalar. Most of the time, it
136	describes a collection. A collection can be a sequence or a mapping of
137	elements. Both sequences and mappings are converted to PHP arrays.
138
139	Sequences use a dash followed by a space (`- `):
140
141	[yml]
142	- PHP
143	- Perl
144	- Python
145
146	The previous YAML file is equivalent to the following PHP code:
147
148	[php]
149	array('PHP', 'Perl', 'Python');
150
151	Mappings use a colon followed by a space (`: `) to mark each key/value pair:
152
153	[yml]
154	PHP: 5.2
155	MySQL: 5.1
156	Apache: 2.2.20
157
158	which is equivalent to this PHP code:
159
160	[php]
161	array('PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20');
162
163	>NOTE
164	>In a mapping, a key can be any valid scalar.
165
166	The number of spaces between the colon and the value does not matter:
167
168	[yml]
169	PHP: 5.2
170	MySQL: 5.1
171	Apache: 2.2.20
172
173	YAML uses indentation with one or more spaces to describe nested collections:
174
175	[yml]
176	"symfony 1.0":
177	PHP: 5.0
178	Propel: 1.2
179	"symfony 1.2":
180	PHP: 5.2
181	Propel: 1.3
182
183	The following YAML is equivalent to the following PHP code:
184
185	[php]
186	array(
187	'symfony 1.0' => array(
188	'PHP' => 5.0,
189	'Propel' => 1.2,
190	),
191	'symfony 1.2' => array(
192	'PHP' => 5.2,
193	'Propel' => 1.3,
194	),
195	);
196
197	There is one important thing you need to remember when using indentation in a
198	YAML file: *Indentation must be done with one or more spaces, but never with
199	tabulations*.
200
201	You can nest sequences and mappings as you like:
202
203	[yml]
204	'Chapter 1':
205	- Introduction
206	- Event Types
207	'Chapter 2':
208	- Introduction
209	- Helpers
210
211	YAML can also use flow styles for collections, using explicit indicators
212	rather than indentation to denote scope.
213
214	A sequence can be written as a comma separated list within square brackets
215	(`[]`):
216
217	[yml]
218	[PHP, Perl, Python]
219
220	A mapping can be written as a comma separated list of key/values within curly
221	braces (`{}`):
222
223	[yml]
224	{ PHP: 5.2, MySQL: 5.1, Apache: 2.2.20 }
225
226	You can mix and match styles to achieve a better readability:
227
228	[yml]
229	'Chapter 1': [Introduction, Event Types]
230	'Chapter 2': [Introduction, Helpers]
231
232	-
233
234	[yml]
235	"symfony 1.0": { PHP: 5.0, Propel: 1.2 }
236	"symfony 1.2": { PHP: 5.2, Propel: 1.3 }
237
238	Comments
239	--------
240
241	Comments can be added in YAML by prefixing them with a hash mark (`#`):
242
243	[yml]
244	# Comment on a line
245	"symfony 1.0": { PHP: 5.0, Propel: 1.2 } # Comment at the end of a line
246	"symfony 1.2": { PHP: 5.2, Propel: 1.3 }
247
248	>NOTE
249	>Comments are simply ignored by the YAML parser and do not need to be
250	>indented according to the current level of nesting in a collection.
251
252	Dynamic YAML files
253	------------------
254
255	In symfony, a YAML file can contain PHP code that is evaluated just before the
256	parsing occurs:
257
258	[php]
259	1.0:
260	version: <?php echo file_get_contents('1.0/VERSION')."\n" ?>
261	1.1:
262	version: "<?php echo file_get_contents('1.1/VERSION') ?>"
263
264	Be careful to not mess up with the indentation. Keep in mind the following
265	simple tips when adding PHP code to a YAML file:
266
267	* The `<?php ?>` statements must always start the line or be embedded in a
268	value.
269
270	* If a `<?php ?>` statement ends a line, you need to explicitly output a new
271	line ("\n").
272
273	<div class="pagebreak"></div>
274
275	A Full Length Example
276	---------------------
277
278	The following example illustrates most YAML notations explained in this
279	document:
280
281	[yml]
282	"symfony 1.0":
283	end_of_maintainance: 2010-01-01
284	is_stable: true
285	release_manager: "Grégoire Hubert"
286	description: >
287	This stable version is the right choice for projects
288	that need to be maintained for a long period of time.
289	latest_beta: ~
290	latest_minor: 1.0.20
291	supported_orms: [Propel]
292	archives: { source: [zip, tgz], sandbox: [zip, tgz] }
293
294	"symfony 1.2":
295	end_of_maintainance: 2008-11-01
296	is_stable: true
297	release_manager: 'Fabian Lange'
298	description: >
299	This stable version is the right choice
300	if you start a new project today.
301	latest_beta: null
302	latest_minor: 1.2.5
303	supported_orms:
304	- Propel
305	- Doctrine
306	archives:
307	source:
308	- zip
309	- tgz
310	sandbox:
311	- zip
312	- tgz