Skip to content

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

Merged
merged 7 commits into from
Jan 3, 2015
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 39 additions & 12 deletions components/yaml/yaml_format.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -31,26 +34,50 @@ Strings

'A singled-quoted string in YAML'

.. tip::
.. code-block:: yaml
Copy link
Member

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?


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.
Copy link
Member

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

Copy link
Member

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."

Copy link
Member Author

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!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about?

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.


'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
Copy link
Member

Choose a reason for hiding this comment

The 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
Copy link
Member

Choose a reason for hiding this comment

The 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:

===== ===== ===== ===== =====
``:`` ``{`` ``}`` ``[`` ``]``
``,`` ``&`` ``*`` ``#`` ``?``
``|`` ``-`` ``<`` ``>`` ``=``
``!`` ``%`` ``@`` ``\```
===== ===== ===== ===== =====
Copy link
Member

Choose a reason for hiding this comment

The 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: ":, {, }, [, ], ,, ... and \" or a multiline 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:
Copy link
Member

Choose a reason for hiding this comment

The 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
Expand Down