feature #4650 Documented the characters that provoke a YAML escaping string (javiereguiluz)

weaverryan · weaverryan · commit 127ebc1d45e2 · 2015-01-03T15:13:19.000-05:00
This PR was merged into the 2.3 branch. Discussion ---------- Documented the characters that provoke a YAML escaping string | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes | Applies to | all | Fixed tickets | #4197 Commits ------- 2824867 Rewroded some contents and fixed some lists of elements 3a40d5a MAde some tweaks suggested by Wouter 044e88b Fixed a minor typo 63ea659 Added a lot more cases for enclosing strings with quotes ce6e3eb Reworded some explanations to make them more clear caaa272 Addressed all the comments made by Wouter d5be25e Documented the characters that provoke a YAML escaping string
diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst
@@ -23,34 +23,64 @@ 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
 
-.. code-block:: yaml
-
     'A singled-quoted string in YAML'
 
-.. tip::
+    "A double-quoted string in YAML"
 
-    In a single quoted string, a single quote ``'`` must be doubled:
+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.
 
-    .. code-block:: yaml
-
-        '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
 
-    "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.
+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 ``\``:
 
-.. tip::
+* ``:``, ``{``, ``}``, ``[``, ``]``, ``,``, ``&``, ``*``, ``#``, ``?``, ``|``,
+  ``-``, ``<``, ``>``, ``=``, ``!``, ``%``, ``@``, ``\```
+
+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"
 
-    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 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
