-
-
Notifications
You must be signed in to change notification settings - Fork 5.2k
Documented the characters that provoke a YAML escaping string #4650
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 1 commit
d5be25e
caaa272
ce6e3eb
63ea659
044e88b
3a40d5a
2824867
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 commentThe 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 commentThe 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 commentThe reason will be displayed to describe this comment to others. Learn more. What about?
|
||
|
||
'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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. this indentation makes no sense, as it's no longer in an admonition |
||
|
||
"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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. since this applies to single quotes, I would move this up to just after the paragraph and example about single quotes. |
||
single quotes: | ||
|
||
===== ===== ===== ===== ===== | ||
``:`` ``{`` ``}`` ``[`` ``]`` | ||
``,`` ``&`` ``*`` ``#`` ``?`` | ||
``|`` ``-`` ``<`` ``>`` ``=`` | ||
``!`` ``%`` ``@`` ``\``` | ||
===== ===== ===== ===== ===== | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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: " |
||
|
||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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.
why don't you make this part of the previous code block?