Add a separate example section for escaping of characters

See also merged PR https://github.com/php/php-src/pull/7420 (d3a6054d44)

Closes GH-898.
This commit is contained in:
Denis Ryabov 2021-09-04 15:53:55 +03:00 committed by GitHub
parent 08a941584f
commit 33225f7c57
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -227,7 +227,7 @@ echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . P
</para>
<para>
<example>
<title>value interpolation</title>
<title>Value Interpolation</title>
<para>
In addition to evaluating constants, certain characters have special meaning in an ini value.
Additionally, environment variables and previously defined values may be read using
@ -250,10 +250,6 @@ negative_two = ~1
; () is used for grouping
seven = (8|7)&(6|5)
; \ is used to escape a value.
newline_is = "\\n" ; results in the string "\n", not a newline character.
with quotes = "She said \"Exactly my point\"." ; Results in a string with quote marks in it.
path = ${PATH}
also_five = ${five}
@ -261,6 +257,59 @@ also_five = ${five}
</programlisting>
</example>
</para>
<para>
<example>
<title>Escaping Characters</title>
<para>
Some characters have special meaning in double-quoted strings and must be escaped by the backslash prefix.
First of all, these are the double quote <code>"</code> as the boundary marker, and the backslash <code>\</code> itself
(if followed by one of the special characters):
</para>
<programlisting>
<![CDATA[
quoted = "She said \"Exactly my point\"." ; Results in a string with quote marks in it.
hint = "Use \\\" to escape double quote" ; Results in: Use \" to escape double quote
]]>
</programlisting>
<para>
There is an exception made for Windows-like paths: it's possible to not escape trailing backslash
if the quoted string is directly followed by a linebreak:
</para>
<programlisting>
<![CDATA[
save_path = "C:\Temp\"
]]>
</programlisting>
<para>
If one does need to escape double quote followed by linebreak in a multiline value,
it's possible to use value concatenation in the following way
(there is one double-quoted string directly followed by another one):
</para>
<programlisting>
<![CDATA[
long_text = "Lorem \"ipsum\"""
dolor" ; Results in: Lorem "ipsum"\n dolor
]]>
</programlisting>
<para>
Another character with special meaning is <code>$</code> (the dollar sign).
It must be escaped if followed by the open curly brace:
</para>
<programlisting>
<![CDATA[
code = "\${test}"
]]>
</programlisting>
<para>
Escaping characters is not supported in the <constant>INI_SCANNER_RAW</constant> mode
(in this mode all characters are processed "as is").
</para>
<para>
Note that the ini parser doesn't support standard escape sequences (<code>\n</code>, <code>\t</code>, etc.).
If necessary, post-process the result of <function>parse_ini_file</function> with <function>stripcslashes</function> function.
</para>
</example>
</para>
</refsect1>
<refsect1 role="notes">