Documented the characters that provoke a YAML escaping string #4650
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -23,34 +23,99 @@ 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 singled-quoted string in YAML' | ||
|
|
||
| "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. | ||
|
|
||
| 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' | ||
|
|
||
| If the string contains any of the following characters, it must be escaped with | ||
| single quotes: | ||
|
There was a problem hiding this comment. Most of the times, using double quotes does the same. There was a problem hiding this comment. To be honest, I have some problems understanding the code of the component. Sometimes they escape with single quotes (https://github.com/symfony/symfony/blob/f940d92a32e4d70cbe045ab8e1b3c70d3eb6061e/src/Symfony/Component/Yaml/Escaper.php#L66) and others with double quotes (https://github.com/symfony/symfony/blob/f940d92a32e4d70cbe045ab8e1b3c70d3eb6061e/src/Symfony/Component/Yaml/Escaper.php#L42). There was a problem hiding this comment. Yeah, I really understand that. I read some parts of the specs when fixing some issues in the component. But I'm really far from understanding them in depth though. Hopefully, @stof can have a look at this pull request and provide some feedback. Please. :) There was a problem hiding this comment. To be more precise in the things that I remember: You can safely use double quotes when the string contains There was a problem hiding this comment. technically, you can use double quotes all the time if you want. But it makes the escaping harder, because you need to escape |
||
|
|
||
| * ``:`` | ||
| * ``{`` | ||
| * ``}`` | ||
| * ``[`` | ||
| * ``]`` | ||
| * ``,`` | ||
| * ``&`` | ||
| * ``*`` | ||
| * ``#`` | ||
| * ``?`` | ||
| * ``|`` | ||
| * ``-`` | ||
| * ``<`` | ||
| * ``>`` | ||
| * ``=`` | ||
| * ``!`` | ||
| * ``%`` | ||
| * ``@`` | ||
| * ``\``` | ||
|
There was a problem hiding this comment. I prefer to use a single line list here. There was a problem hiding this comment. I think it's confusing to put all these chars in a single line and separate them with a comma. You never know if the comma is a comma or a special char or part of other special char. That's why I used a table originally ;) In any case, tables, single-item lists or multiple-items lists all look awful to me in this case. I can't think of anything that makes this look OK. There was a problem hiding this comment. i think if you wrap every item as a literal using "``" and seperate them with a comma its much more readable |
||
|
|
||
| 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 | ||
|
|
||
| "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: | ||
|
There was a problem hiding this comment. I don't understand what you mean with your last sentence |
||
|
|
||
| * ``\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 | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
and also when they contain special chars
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@javiereguiluz can you please add something about that in this sentence. E.g. "[...] and also if the string contains special or reserved characters."
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't understand your comments. When you say: "... and also if it contains special chars" ... are you referring to "quoted styles are useful in that case too" or "they are trimmed on both ends in that case too". I think that the resulting phrase would be too long and complex. Could we reword it in two or three short sentences? Thanks!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What about?