From 956de74e3e9c25e693a9d3129028c88809d2cea9 Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Sat, 7 Jan 2023 15:35:09 +0100 Subject: [PATCH] Merge YAML docs into one --- components/yaml.rst | 343 ++++++++++++++++++++++++++++++- components/yaml/yaml_format.rst | 344 -------------------------------- configuration.rst | 2 +- 3 files changed, 336 insertions(+), 353 deletions(-) delete mode 100644 components/yaml/yaml_format.rst diff --git a/components/yaml.rst b/components/yaml.rst index c2e38f5c2d5..e5cdc2d1ebc 100644 --- a/components/yaml.rst +++ b/components/yaml.rst @@ -23,8 +23,7 @@ the `YAML 1.2 version specification`_. .. tip:: - Learn more about the Yaml component in the - :doc:`/components/yaml/yaml_format` article. + Learn more about :ref:`YAML specifications `. Installation ------------ @@ -452,14 +451,342 @@ Add the ``--format`` option to get the output in JSON format: YAML files. This may for example be useful for recognizing deprecations of contents of YAML files during automated tests. -Learn More ----------- +.. _yaml-format: -.. toctree:: - :maxdepth: 1 - :glob: +.. index:: + single: Yaml; YAML Format + +The YAML Format +--------------- + +Scalars +~~~~~~~ + +The syntax for scalars is similar to the PHP syntax. + +Strings +....... + +Strings in YAML can be wrapped both in single and double quotes. In some cases, +they can also be unquoted: + +.. code-block:: yaml + + A string in YAML + + 'A single-quoted string in YAML' + + "A double-quoted string in YAML" + +Quoted styles are useful when a string starts or end with one or more relevant +spaces, because unquoted strings are trimmed on both end when parsing their +contents. Quotes are required when the string contains special or reserved characters. + +When using single-quoted strings, any single quote ``'`` inside its contents +must be doubled to escape it: + +.. code-block:: yaml + + 'A single quote '' inside a single-quoted string' + +Strings containing any of the following characters must be quoted. Although you +can use double quotes, for these characters it is more convenient to use single +quotes, which avoids having to escape any backslash ``\``: + +* ``:``, ``{``, ``}``, ``[``, ``]``, ``,``, ``&``, ``*``, ``#``, ``?``, ``|``, + ``-``, ``<``, ``>``, ``=``, ``!``, ``%``, ``@``, ````` + +The double-quoted style provides a way to express arbitrary strings, by +using ``\`` to escape characters and sequences. For instance, it is very useful +when you need to embed a ``\n`` or a Unicode character in a string. + +.. code-block:: yaml + + "A double-quoted string in YAML\n" + +If the string contains any of the following control characters, it must be +escaped with double quotes: + +* ``\0``, ``\x01``, ``\x02``, ``\x03``, ``\x04``, ``\x05``, ``\x06``, ``\a``, + ``\b``, ``\t``, ``\n``, ``\v``, ``\f``, ``\r``, ``\x0e``, ``\x0f``, ``\x10``, + ``\x11``, ``\x12``, ``\x13``, ``\x14``, ``\x15``, ``\x16``, ``\x17``, ``\x18``, + ``\x19``, ``\x1a``, ``\e``, ``\x1c``, ``\x1d``, ``\x1e``, ``\x1f``, ``\N``, + ``\_``, ``\L``, ``\P`` + +Finally, there are other cases when the strings must be quoted, no matter if +you're using single or double quotes: + +* When the string is ``true`` or ``false`` (otherwise, it would be treated as a + boolean value); +* When the string is ``null`` or ``~`` (otherwise, it would be considered as a + ``null`` value); +* When the string looks like a number, such as integers (e.g. ``2``, ``14``, etc.), + floats (e.g. ``2.6``, ``14.9``) and exponential numbers (e.g. ``12e7``, etc.) + (otherwise, it would be treated as a numeric value); +* When the string looks like a date (e.g. ``2014-12-31``) (otherwise it would be + automatically converted into a Unix timestamp). + +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. + + # This will be parsed as follows: (notice the trailing \n) + # "This is a very long sentence that spans several lines in the YAML.\n" + + >- + This is a very long sentence + that spans several lines in the YAML. + + # This will be parsed as follows: (without a trailing \n) + # "This is a very long sentence that spans several lines in the YAML." + +.. 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 + 0o14 + +.. deprecated:: 5.1 + + In YAML 1.1, octal numbers use the notation ``0...``, whereas in YAML 1.2 + the notation changes to ``0o...``. Symfony 5.1 added support for YAML 1.2 + notation and deprecated support for YAML 1.1 notation. + +.. 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 + +.. _yaml-format-collections: + +Collections +~~~~~~~~~~~ + +A YAML file is rarely used to describe a simple scalar. Most of the time, it +describes a collection. YAML collections can be a sequence (indexed arrays in PHP) +or a mapping of elements (associative arrays in PHP). + +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:: + + ['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:: + + ['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 above YAML is equivalent to the following PHP code:: + + [ + 'symfony 1.0' => [ + 'PHP' => 5.0, + 'Propel' => 1.2, + ], + 'symfony 1.2' => [ + '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 +tabulators*. + +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 ignored by the YAML parser and do not need to be indented + according to the current level of nesting in a collection. + +Explicit Typing +~~~~~~~~~~~~~~~ + +The YAML specification defines some tags to set the type of any data explicitly: + +.. code-block:: yaml - yaml/* + data: + # this value is parsed as a string (it's not transformed into a DateTime) + start_date: !!str 2002-12-14 + + # this value is parsed as a float number (it will be 3.0 instead of 3) + price: !!float 3 + + # this value is parsed as binary data encoded in base64 + picture: !!binary | + R0lGODlhDAAMAIQAAP//9/X + 17unp5WZmZgAAAOfn515eXv + Pz7Y6OjuDg4J+fn5OTk6enp + 56enmleECcgggoBADs= + +Unsupported YAML Features +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following YAML features are not supported by the Symfony Yaml component: + +* Multi-documents (``---`` and ``...`` markers); +* Complex mapping keys and complex values starting with ``?``; +* Tagged values as keys; +* The following tags and types: ``!!set``, ``!!omap``, ``!!pairs``, ``!!seq``, + ``!!bool``, ``!!int``, ``!!merge``, ``!!null``, ``!!timestamp``, ``!!value``, ``!!yaml``; +* Tags (``TAG`` directive; example: ``%TAG ! tag:example.com,2000:app/``) + and tag references (example: ``!``); +* Using sequence-like syntax for mapping elements (example: ``{foo, bar}``; use + ``{foo: ~, bar: ~}`` instead). .. _`YAML`: https://yaml.org/ .. _`YAML 1.2 version specification`: https://yaml.org/spec/1.2/spec.html diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst deleted file mode 100644 index 94f5c96574e..00000000000 --- a/components/yaml/yaml_format.rst +++ /dev/null @@ -1,344 +0,0 @@ -.. index:: - single: Yaml; YAML Format - -The YAML Format -=============== - -According to the official `YAML website`_, YAML is "a human friendly data -serialization standard for all programming languages". The Symfony Yaml -component implements a subset of the `YAML specification`_. Specifically, it -implements the minimum set of features needed to use YAML as a configuration -file format. - -Scalars -------- - -The syntax for scalars is similar to the PHP syntax. - -Strings -~~~~~~~ - -Strings in YAML can be wrapped both in single and double quotes. In some cases, -they can also be unquoted: - -.. code-block:: yaml - - A string in YAML - - 'A single-quoted string in YAML' - - "A double-quoted string in YAML" - -Quoted styles are useful when a string starts or end with one or more relevant -spaces, because unquoted strings are trimmed on both end when parsing their -contents. Quotes are required when the string contains special or reserved characters. - -When using single-quoted strings, any single quote ``'`` inside its contents -must be doubled to escape it: - -.. code-block:: yaml - - 'A single quote '' inside a single-quoted string' - -Strings containing any of the following characters must be quoted. Although you -can use double quotes, for these characters it is more convenient to use single -quotes, which avoids having to escape any backslash ``\``: - -* ``:``, ``{``, ``}``, ``[``, ``]``, ``,``, ``&``, ``*``, ``#``, ``?``, ``|``, - ``-``, ``<``, ``>``, ``=``, ``!``, ``%``, ``@``, ````` - -The double-quoted style provides a way to express arbitrary strings, by -using ``\`` to escape characters and sequences. For instance, it is very useful -when you need to embed a ``\n`` or a Unicode character in a string. - -.. code-block:: yaml - - "A double-quoted string in YAML\n" - -If the string contains any of the following control characters, it must be -escaped with double quotes: - -* ``\0``, ``\x01``, ``\x02``, ``\x03``, ``\x04``, ``\x05``, ``\x06``, ``\a``, - ``\b``, ``\t``, ``\n``, ``\v``, ``\f``, ``\r``, ``\x0e``, ``\x0f``, ``\x10``, - ``\x11``, ``\x12``, ``\x13``, ``\x14``, ``\x15``, ``\x16``, ``\x17``, ``\x18``, - ``\x19``, ``\x1a``, ``\e``, ``\x1c``, ``\x1d``, ``\x1e``, ``\x1f``, ``\N``, - ``\_``, ``\L``, ``\P`` - -Finally, there are other cases when the strings must be quoted, no matter if -you're using single or double quotes: - -* When the string is ``true`` or ``false`` (otherwise, it would be treated as a - boolean value); -* When the string is ``null`` or ``~`` (otherwise, it would be considered as a - ``null`` value); -* When the string looks like a number, such as integers (e.g. ``2``, ``14``, etc.), - floats (e.g. ``2.6``, ``14.9``) and exponential numbers (e.g. ``12e7``, etc.) - (otherwise, it would be treated as a numeric value); -* When the string looks like a date (e.g. ``2014-12-31``) (otherwise it would be - automatically converted into a Unix timestamp). - -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. - - # This will be parsed as follows: (notice the trailing \n) - # "This is a very long sentence that spans several lines in the YAML.\n" - - >- - This is a very long sentence - that spans several lines in the YAML. - - # This will be parsed as follows: (without a trailing \n) - # "This is a very long sentence that spans several lines in the YAML." - -.. 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 - 0o14 - -.. deprecated:: 5.1 - - In YAML 1.1, octal numbers use the notation ``0...``, whereas in YAML 1.2 - the notation changes to ``0o...``. Symfony 5.1 added support for YAML 1.2 - notation and deprecated support for YAML 1.1 notation. - -.. 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 - -.. _yaml-format-collections: - -Collections ------------ - -A YAML file is rarely used to describe a simple scalar. Most of the time, it -describes a collection. YAML collections can be a sequence (indexed arrays in PHP) -or a mapping of elements (associative arrays in PHP). - -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:: - - ['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:: - - ['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 above YAML is equivalent to the following PHP code:: - - [ - 'symfony 1.0' => [ - 'PHP' => 5.0, - 'Propel' => 1.2, - ], - 'symfony 1.2' => [ - '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 -tabulators*. - -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 ignored by the YAML parser and do not need to be indented - according to the current level of nesting in a collection. - -Explicit Typing ---------------- - -The YAML specification defines some tags to set the type of any data explicitly: - -.. code-block:: yaml - - data: - # this value is parsed as a string (it's not transformed into a DateTime) - start_date: !!str 2002-12-14 - - # this value is parsed as a float number (it will be 3.0 instead of 3) - price: !!float 3 - - # this value is parsed as binary data encoded in base64 - picture: !!binary | - R0lGODlhDAAMAIQAAP//9/X - 17unp5WZmZgAAAOfn515eXv - Pz7Y6OjuDg4J+fn5OTk6enp - 56enmleECcgggoBADs= - -Unsupported YAML Features -------------------------- - -The following YAML features are not supported by the Symfony Yaml component: - -* Multi-documents (``---`` and ``...`` markers); -* Complex mapping keys and complex values starting with ``?``; -* Tagged values as keys; -* The following tags and types: ``!!set``, ``!!omap``, ``!!pairs``, ``!!seq``, - ``!!bool``, ``!!int``, ``!!merge``, ``!!null``, ``!!timestamp``, ``!!value``, ``!!yaml``; -* Tags (``TAG`` directive; example: ``%TAG ! tag:example.com,2000:app/``) - and tag references (example: ``!``); -* Using sequence-like syntax for mapping elements (example: ``{foo, bar}``; use - ``{foo: ~, bar: ~}`` instead). - -.. _`ISO-8601`: https://www.iso.org/iso-8601-date-and-time-format.html -.. _`YAML website`: https://yaml.org/ -.. _`YAML specification`: https://www.yaml.org/spec/1.2/spec.html diff --git a/configuration.rst b/configuration.rst index f1f66be2fdf..702ba9a3f59 100644 --- a/configuration.rst +++ b/configuration.rst @@ -102,7 +102,7 @@ YAML is used by default when installing packages because it's concise and very readable. These are the main advantages and disadvantages of each format: * **YAML**: simple, clean and readable, but not all IDEs support autocompletion - and validation for it. :doc:`Learn the YAML syntax `; + and validation for it. :ref:`Learn the YAML syntax `; * **XML**: autocompleted/validated by most IDEs and is parsed natively by PHP, but sometimes it generates configuration considered too verbose. `Learn the XML syntax`_; * **PHP**: very powerful and it allows you to create dynamic configuration with