From e03965d8bb7b95a74504273d8d34c1055f44383c Mon Sep 17 00:00:00 2001 From: WouterJ Date: Tue, 22 Jan 2013 22:14:11 +0100 Subject: [PATCH 1/4] Moved yaml to his own map --- components/map.rst.inc | 4 ++-- components/yaml/index.rst | 7 +++++++ components/{yaml.rst => yaml/introduction.rst} | 0 3 files changed, 9 insertions(+), 2 deletions(-) create mode 100644 components/yaml/index.rst rename components/{yaml.rst => yaml/introduction.rst} (100%) diff --git a/components/map.rst.inc b/components/map.rst.inc index 8f9e1464da5..cd017ca832a 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -82,6 +82,6 @@ * :doc:`/components/templating` -* **YAML** +* :doc:`/components/yaml/index` - * :doc:`/components/yaml` + * :doc:`/components/yaml/introduction` diff --git a/components/yaml/index.rst b/components/yaml/index.rst new file mode 100644 index 00000000000..fcfb4e284ad --- /dev/null +++ b/components/yaml/index.rst @@ -0,0 +1,7 @@ +Yaml +==== + +.. toctree:: + :maxdepth: 2 + + introduction diff --git a/components/yaml.rst b/components/yaml/introduction.rst similarity index 100% rename from components/yaml.rst rename to components/yaml/introduction.rst From e20e27e86d90b784373d726435c63b399e364298 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Tue, 22 Jan 2013 22:18:34 +0100 Subject: [PATCH 2/4] Moved "The Yaml Format" to its own article --- components/map.rst.inc | 1 + components/yaml/index.rst | 1 + components/yaml/introduction.rst | 267 ------------------------------ components/yaml/yaml_format.rst | 269 +++++++++++++++++++++++++++++++ 4 files changed, 271 insertions(+), 267 deletions(-) create mode 100644 components/yaml/yaml_format.rst diff --git a/components/map.rst.inc b/components/map.rst.inc index cd017ca832a..8dd3ba4b602 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -85,3 +85,4 @@ * :doc:`/components/yaml/index` * :doc:`/components/yaml/introduction` + * :doc:`/components/yaml/yaml_format` diff --git a/components/yaml/index.rst b/components/yaml/index.rst index fcfb4e284ad..ff2cf733138 100644 --- a/components/yaml/index.rst +++ b/components/yaml/index.rst @@ -5,3 +5,4 @@ Yaml :maxdepth: 2 introduction + yaml_format diff --git a/components/yaml/introduction.rst b/components/yaml/introduction.rst index 9c6e88b2d09..81b2f451fa1 100644 --- a/components/yaml/introduction.rst +++ b/components/yaml/introduction.rst @@ -207,272 +207,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 diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst new file mode 100644 index 00000000000..c49e0e94e71 --- /dev/null +++ b/components/yaml/yaml_format.rst @@ -0,0 +1,269 @@ +.. 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". + +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. From a6bde9f823a09edf3839150793b1cb50a2e25e32 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Tue, 22 Jan 2013 22:24:14 +0100 Subject: [PATCH 3/4] Added some interlinking --- book/page_creation.rst | 3 ++- components/yaml/introduction.rst | 5 +++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/book/page_creation.rst b/book/page_creation.rst index ec01b55e01a..a4c44e64a42 100644 --- a/book/page_creation.rst +++ b/book/page_creation.rst @@ -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; diff --git a/components/yaml/introduction.rst b/components/yaml/introduction.rst index 81b2f451fa1..6921f15cc0f 100644 --- a/components/yaml/introduction.rst +++ b/components/yaml/introduction.rst @@ -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 ------------ From 2015c4a13c6a50548222025d1ba23b516fae5ed2 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Tue, 22 Jan 2013 22:27:52 +0100 Subject: [PATCH 4/4] Removed BC in changing url --- redirection_map | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/redirection_map b/redirection_map index 1ba44a5919d..d4587751b1f 100644 --- a/redirection_map +++ b/redirection_map @@ -17,4 +17,5 @@ /components/http_foundation /components/http_foundation/introduction /components/console /components/console/introduction /components/routing /components/routing/introduction -/cookbook/console/generating_urls /cookbook/console/sending_emails \ No newline at end of file +/cookbook/console/generating_urls /cookbook/console/sending_emails +/components/yaml /components/yaml/introduction