Documented the characters that provoke a YAML escaping string #4650
Conversation
javiereguiluz
commented
Dec 14, 2014
| Q | A |
|---|---|
| Doc fix? | no |
| New docs? | yes |
| Applies to | all |
| Fixed tickets | #4197 |
| ``,`` ``&`` ``*`` ``#`` ``?`` | ||
| ``|`` ``-`` ``<`` ``>`` ``=`` | ||
| ``!`` ``%`` ``@`` ``\``` | ||
| ===== ===== ===== ===== ===== |
There was a problem hiding this comment.
I don't like this table (and sphinx doesn't like it that there is an empty cell). It's a list, not a table imo. So either use an inline list: ":, {, }, [, ], ,, ... and \" or a multiline list
|
Thanks, @javiereguiluz ! I've always wondered about the exact rules, as the Yaml specs are not very clear :) The diff was hard to read, but I tried to make sense of it and review it nonetheless. I may have commented on a wrong diff. |
|
@wouterj thanks for the detailed review! I've added everything you said. |
| '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 :, {, }, [, ], ,, #, -, % and @.
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 \ in it (because of control sequences) instead of just escaping single quotes
|
I've added all the comments that you made. I think explanations are now much better. If you agree, let's merge and close some issues :) |
|
There are a few other cases where using quotes is necessary. This is when the unquoted value would be parsed as another type than a string:
|
|
@stof thanks for your list of cases where we should enclose strings with quotes. I've just updated the docs. |
|
👍 |
| '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 |
There was a problem hiding this comment.
[...] characters it is more convenient [...]
| * ``!`` | ||
| * ``%`` | ||
| * ``@`` | ||
| * ``\``` |
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
|
WOW :) |
…string (javiereguiluz) 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