php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #36710 self-contradictory documentation of escaping in single-quoted strings
Submitted: 2006-03-13 04:43 UTC Modified: 2006-03-21 01:00 UTC
Votes:2
Avg. Score:3.0 ± 0.0
Reproduced:0 of 0 (0.0%)
From: swift at alum dot mit dot edu Assigned:
Status: No Feedback Package: Documentation problem
PHP Version: Irrelevant OS: Irrelevant
Private report: No CVE-ID: None
Have you experienced this issue?
Rate the importance of this bug to you:

 [2006-03-13 04:43 UTC] swift at alum dot mit dot edu
Description:
------------
I quote from the node on strings in the PHP manual (www.php.net/manual/en/language.types.string.php) where it discusses single-quoted strings:

I break into sentences which I reference below:

(1) To specify a literal single quote, you will need to escape it with a backslash (\), like in many other languages.

(2) If a backslash needs to occur before a single quote or at the end of the string, you need to double it.

(3) Note that if you try to escape any other character, the backslash will also be printed!

(4) So usually there is no need to escape the backslash itself.

Sentence (1) is clear, though "will" should be omitted for better clarity.

Sentence (2) means that a literal backslash needs to be escaped in only two cases: when it appears before a literal single quote and when it is the last character of the string.  This is of course incorrect (it is contradicted by a correct example further down the page whose output is 'You deleted C:\*.*?').  What the author intends to say is much better expressed by the following:  "An escaped backslash (\\) likewise specifies a literal backslash, but it is not normally necessary to escape a literal backslash.  Escaping a backslash is necessary only when the context would otherwise make the backslash into an escape operator -- that is when it appears immediately before another backslash or the single quote terminating the string."

Sentence (3) is unclear because it is unclear whether the reference of "other" is "backslash" or "single quote" or both.  Also "try to escape" is a confusing hypothetical.  A good revision would be:  "A backslash followed by any character besides a single quote or another backslash is a literal backslash."

Sentence (4) is confusing because it's not clear that "the backslash itself" refers to a literal backslash or an escape-operator backslash.  Omit this sentence: this section should deal only with how to specify a single quoted string.      Discussion of applications of strings (such as regexps) which also use the backslash as an escape operator belongs somewhere else -- or at least should be clearly separate from the discussion of simply how to specify the contents of a string.

"Stringing" together the suggested revisions above:

To specify a literal single quote, you need to escape it with a backslash (\), like in many other languages.  An escaped backslash (\\) likewise specifies a literal backslash, but it is not normally necessary to escape a literal backslash.  Escaping a backslash is necessary only when the context would otherwise make the backslash into an escape operator -- that is when it appears immediately before another backslash or the single quote terminating the string.  A backslash followed by any character besides a single quote or another backslash is a literal backslash.



Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2006-03-13 04:48 UTC] swift at alum dot mit dot edu
I quote from the node on strings in the PHP manual
(www.php.net/manual/en/language.types.string.php) where it
discusses single-quoted strings:

I break into sentences which I reference below:

(1) To specify a literal single quote, you will need to
    escape it with a backslash (\), like in many other
    languages.

(2) If a backslash needs to occur before a single quote or
    at the end of the string, you need to double it.

(3) Note that if you try to escape any other character, the
    backslash will also be printed!

(4) So usually there is no need to escape the backslash
    itself.

Sentence (1) is clear, though "will" should be omitted for
better clarity.

Sentence (2) means that a literal backslash needs to be
escaped in only two cases: when it appears before a literal
single quote and when it is the last character of the
string.  This is of course incorrect (it is contradicted by
a correct example further down the page whose output is 'You
deleted C:\*.*?').  What the author intends to say is much
better expressed by the following: "An escaped backslash
(\\) likewise specifies a literal backslash, but it is not
normally necessary to escape a literal backslash.  Escaping
a backslash is necessary only when the context would
otherwise make the backslash into an escape operator -- that
is, when it appears immediately before another backslash or
the single quote terminating the string."

Sentence (3) is unclear because it is unclear whether the
reference of "other" is "backslash" or "single quote" or
both.  Also "try to escape" is a confusing hypothetical.  A
good revision would be: "A backslash followed by any
character besides a single quote or another backslash is a
literal backslash."

Sentence (4) is confusing because it's not clear that "the
backslash itself" refers to a literal backslash or an
escape-operator backslash.  Omit this sentence: this section
should deal only with how to specify a single quoted string.
Discussion of applications of strings (such as regexps)
which also use the backslash as an escape operator belongs
somewhere else -- or at least should be clearly separate
from the discussion of simply how to specify the contents of
a string.

"Stringing" together the suggested revisions above:

To specify a literal single quote, you need to escape it
with a backslash (\), like in many other languages.  An
escaped backslash (\\) likewise specifies a literal
backslash, but it is not normally necessary to escape a
literal backslash.  Escaping a backslash is necessary only
when the context would otherwise make the backslash into an
escape operator -- that is, when it appears immediately
before another backslash or the single quote terminating the
string.  A backslash followed by any character besides a
single quote or another backslash is a literal backslash.
 [2006-03-13 04:52 UTC] swift at alum dot mit dot edu
Argh!  This web interface told me I could "edit my submission".  That's not fully true, since I can't edit the main text, I can only add to it.  So I've now posted two long discussions that differ only by a pair of commas, and I have no way to correct that.  The second submission contains the corrected punctuation.
 [2006-03-13 11:54 UTC] vrana@php.net
Why do you think "a literal backslash needs to be escaped in only two cases: when it appears before a literal single quote and when it is the last character of the string" is "of course incorrect"? It can be escaped on other places too but it NEEDS to be escaped only in these two cases.

Current description is perfectly clear and right from my POV and doesn't need to be changed.
 [2006-03-13 17:26 UTC] colder@php.net
I also think that the actual version is perfectly clear, and even clearer than the one you suggest.

The four statements clearly state that :

1) In a single quoted string, there are 3 contexts where an escaping is *required* :
  a) to escape a single quote : 'Jymm\'s car' -> Jymm's car
  b) to have a backslash at the end of a string : 'foo\\' -> foo\
  b) to have a \ printed before a single quote: 'foo\\\' bar' -> foo\' bar

2) Out of these contexts, it is also _possible_ (not required) to escape a backslash. Otherwise, the backslash won't escape anything and thus will be printed.
 [2006-03-21 01:00 UTC] phpdoc at lists dot php dot net
No feedback was provided for this bug for over a week, so it is
being suspended automatically. If you are able to provide the
information that was originally requested, please do so and change
the status of the bug back to "Open".
 
PHP Copyright © 2001-2019 The PHP Group
All rights reserved.
Last updated: Thu Nov 21 15:01:22 2019 UTC