Buffer.add_substitute is not surjective and its documentation is incomplete. #6732
Description
Original bug ID: 6732
Reporter: @damiendoligez
Status: acknowledged (set by @damiendoligez on 2015-01-09T17:22:48Z)
Resolution: open
Priority: low
Severity: minor
Version: 4.02.1
Category: standard library
Monitored by: @hcarty @dbuenzli
Bug description
The documentation of Buffer.add_substitute says:
An escaped [$] character is a [$] that immediately follows a backslash
character; it then stands for a plain [$].
This is not true if the $ follows an even number of backslashes.
It also says:
Raise [Not_found] if the closing character of a parenthesized variable
cannot be found.
But Not_found is also be raised if there is an unescaped $ at the end of the string.
The documentation also fails to state that, when Not_found is raised, some characters are still added to the buffer. It also omits the fact that the adding stops silently when it sees an unescaped $ followed by anything else than alphanum, _, { or (.
Finally, the only way to get a single backslash followed by a dollar is by playing with variables, there is no way to get it from a constant string because the quoting conventions are incomplete: backslashes should also be escaped by backslashes.
Some of these problems should be fixed, and the others documented.
Steps to reproduce
OCaml version 4.02.1
# let b = Buffer.create 0;;
val b : Buffer.t = <abstr>
# Buffer.add_substitute b (fun _ -> "") "\n1. \\$";;
- : unit = ()
# Buffer.add_substitute b (fun _ -> "") "\n2. \\\\$";;
Exception: Not_found.
# Buffer.add_substitute b (fun _ -> "") "\n3. \\\\$ ";;
- : unit = ()
# Buffer.add_substitute b (fun _ -> "") "\n3. \\\\$!";;
- : unit = ()
# Buffer.add_substitute b (fun _ -> "") "\n4. \\\\\\$";;
- : unit = ()
# Buffer.add_substitute b (fun _ -> "") "\n5. $}";;
- : unit = ()
# print_endline (Buffer.contents b);;
1. $
2. \\
3. \\
3. \\
4. \\$
5.
- : unit = ()
#