From d5be25ef3c89a0f55078f0cf03b5783ffaf2c3f5 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 14 Dec 2014 16:23:25 +0100 Subject: [PATCH 1/7] Documented the characters that provoke a YAML escaping string --- components/yaml/yaml_format.rst | 51 +++++++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 12 deletions(-) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index a86bcd05030..9419526c0cc 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -23,6 +23,9 @@ 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 @@ -31,26 +34,50 @@ Strings 'A singled-quoted string in YAML' -.. tip:: +.. code-block:: yaml - In a single quoted string, a single quote ``'`` must be doubled: + "A double-quoted string in YAML" - .. code-block:: yaml +Quoted styles are useful when a string starts or ends with one or more +relevant spaces, because unquoted strings are trimmed on both ends when parsing +their contents. - 'A single quote '' in a single-quoted string' +When using single-quoted strings, any single quote ``'`` inside its contents +must be doubled to escape it: -.. code-block:: yaml + .. code-block:: yaml - "A double-quoted string in YAML\n" + 'A single quote '' inside a single-quoted string' -Quoted styles are useful when a string starts or ends with one or more -relevant spaces. +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. + +.. code-block:: yaml -.. tip:: + "A double-quoted string in YAML\n" - 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. +If the string contains any of the following characters, it must be escaped with +single quotes: + +===== ===== ===== ===== ===== +``:`` ``{`` ``}`` ``[`` ``]`` +``,`` ``&`` ``*`` ``#`` ``?`` +``|`` ``-`` ``<`` ``>`` ``=`` +``!`` ``%`` ``@`` ``\``` +===== ===== ===== ===== ===== + +If the string contains any of the following control characters, it must be +escaped with double quotes. In addition, the escaping must use a double slash +``\\`` to avoid parsing issues: + +======== ======== ======== ======== ======== ======== ======== ======== +``\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`` +======== ======== ======== ======== ======== ======== ======== ======== 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 From caaa2728fd2b8eabd26940fba6550e4968e3dcad Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 14 Dec 2014 17:02:12 +0100 Subject: [PATCH 2/7] Addressed all the comments made by Wouter --- components/yaml/yaml_format.rst | 84 ++++++++++++++++++++++++--------- 1 file changed, 61 insertions(+), 23 deletions(-) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index 9419526c0cc..c45a45117a2 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -30,12 +30,8 @@ they can also be unquoted: A string in YAML -.. code-block:: yaml - 'A singled-quoted string in YAML' -.. code-block:: yaml - "A double-quoted string in YAML" Quoted styles are useful when a string starts or ends with one or more @@ -45,9 +41,32 @@ their contents. When using single-quoted strings, any single quote ``'`` inside its contents must be doubled to escape it: - .. code-block:: yaml +.. code-block:: yaml - 'A single quote '' inside a single-quoted string' + 'A single quote '' inside a single-quoted string' + +If the string contains any of the following characters, it must be escaped with +single quotes: + +* ``:`` +* ``{`` +* ``}`` +* ``[`` +* ``]`` +* ``,`` +* ``&`` +* ``*`` +* ``#`` +* ``?`` +* ``|`` +* ``-`` +* ``<`` +* ``>`` +* ``=`` +* ``!`` +* ``%`` +* ``@`` +* ``\``` 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 @@ -57,27 +76,46 @@ using ``\`` escape sequences. It is very useful when you need to embed a "A double-quoted string in YAML\n" -If the string contains any of the following characters, it must be escaped with -single quotes: - -===== ===== ===== ===== ===== -``:`` ``{`` ``}`` ``[`` ``]`` -``,`` ``&`` ``*`` ``#`` ``?`` -``|`` ``-`` ``<`` ``>`` ``=`` -``!`` ``%`` ``@`` ``\``` -===== ===== ===== ===== ===== - If the string contains any of the following control characters, it must be escaped with double quotes. In addition, the escaping must use a double slash ``\\`` to avoid parsing issues: -======== ======== ======== ======== ======== ======== ======== ======== -``\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`` -======== ======== ======== ======== ======== ======== ======== ======== +* ``\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`` 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 From ce6e3eba726957c0c5ccec82b55936f523d5b3bb Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 16 Dec 2014 12:19:30 +0100 Subject: [PATCH 3/7] Reworded some explanations to make them more clear --- components/yaml/yaml_format.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index c45a45117a2..7be2f0d931b 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -45,8 +45,9 @@ must be doubled to escape it: 'A single quote '' inside a single-quoted string' -If the string contains any of the following characters, it must be escaped with -single quotes: +Strings containing any of the following characters must be quoted. Although you +can use double quotes, for these characters is more convenient to use single +quotes, which avoids having to escape any backslash ``\``: * ``:`` * ``{`` @@ -69,16 +70,15 @@ single quotes: * ``\``` 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. +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. In addition, the escaping must use a double slash -``\\`` to avoid parsing issues: +escaped with double quotes: * ``\0`` * ``\x01`` From 63ea6597255541a4dc2858fe3e3f3de5ddb5efd4 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 16 Dec 2014 15:37:17 +0100 Subject: [PATCH 4/7] Added a lot more cases for enclosing strings with quotes --- components/yaml/yaml_format.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index 7be2f0d931b..1d45167fc52 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -117,6 +117,19 @@ escaped with double quotes: * ``\L`` * ``\P`` +Finally, there are other cases when the strings must be quoted, no matter if +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: From 044e88bc1cf08a6c469259dc4808a14de368e25d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 16 Dec 2014 16:43:32 +0100 Subject: [PATCH 5/7] Fixed a minor typo --- components/yaml/yaml_format.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index 1d45167fc52..d9a290f9537 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -46,7 +46,7 @@ must be doubled to escape it: '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 is more convenient to use single +can use double quotes, for these characters it is more convenient to use single quotes, which avoids having to escape any backslash ``\``: * ``:`` From 3a40d5a54fe92b4dd42a3f9f25edb2f7a76f7bda Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 29 Dec 2014 16:12:15 +0100 Subject: [PATCH 6/7] MAde some tweaks suggested by Wouter --- components/yaml/yaml_format.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index d9a290f9537..9e01336734e 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -118,16 +118,16 @@ escaped with double quotes: * ``\P`` Finally, there are other cases when the strings must be quoted, no matter if -using single or double quotes: +you're using single or double quotes: -* when the string is ``true`` or ``false`` (otherwise, it would be treated as a +* 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 +* 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.), +* 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 +* 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 From 2824867ce86cf2ab0e2510d8d687d3535174fce0 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 29 Dec 2014 16:47:07 +0100 Subject: [PATCH 7/7] Rewroded some contents and fixed some lists of elements --- components/yaml/yaml_format.rst | 68 +++++---------------------------- 1 file changed, 10 insertions(+), 58 deletions(-) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index 9e01336734e..c8a6f4a0813 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -34,9 +34,9 @@ they can also be unquoted: "A double-quoted string in YAML" -Quoted styles are useful when a string starts or ends with one or more -relevant spaces, because unquoted strings are trimmed on both ends when parsing -their contents. +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: @@ -49,25 +49,8 @@ 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 @@ -80,42 +63,11 @@ when you need to embed a ``\n`` or a Unicode character in a string. 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`` +* ``\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: