Comprehensively support trailing commas in std/core macros
I carefully organized the changes into four commits:
* Test cases
* Fixes for `macro_rules!` macros
* Fixes for builtin macros
* Docs for builtins
**I can easily scale this back to just the first two commits for now if such is desired.**
### Breaking (?) changes
* This fixes#48042, which is a breaking change that I hope people can agree is just a bugfix for an extremely dark corner case.
* To fix five of the builtins, this changes `syntax::ext::base::get_single_str_from_tts` to accept a trailing comma, and revises the documentation so that this aspect is not surprising. **I made this change under the (hopefully correct) understanding that `libsyntax` is private rustc implementation detail.** After reviewing all call sites (which were, you guessed it, *precisely those five macros*), I believe the revised semantics are closer to the intended spirit of the function.
### Changes which may require concensus
Up until now, it could be argued that some or all the following macros did not conceptually take a comma-separated list, because they only took one argument:
* **`cfg(unix,)`** (most notable since cfg! is unique in taking a meta tag)
* **`include{,_bytes,_str}("file.rs",)`** (in item form this might be written as "`include!{"file.rs",}`" which is even slightly more odd)
* **`compile_error("message",);`**
* **`option_env!("PATH",)`**
* **`try!(Ok(()),)`**
So I think these particular changes may require some sort of consensus. **All of the fixes for builtins are included this list, so if we want to defer these decisions to later then I can scale this PR back to just the first two commits.**
### Other notes/general requests for comment
* Do we have a big checklist somewhere of "things to do when adding macros?" My hope is for `run-pass/macro-comma-support.rs` to remain comprehensive.
* Originally I wanted the tests to also comprehensively forbid double trailing commas. However, this didn't work out too well: [see this gist and the giant FIXME in it](https://gist.github.com/ExpHP/6fc40e82f3d73267c4e590a9a94966f1#file-compile-fail_macro-comma-support-rs-L33-L50)
* I did not touch `select!`. It appears to me to be a complete mess, and its trailing comma mishaps are only the tip of the iceberg.
* There are [some compile-fail test cases](https://github.com/ExpHP/rust/blob/5fa97c35da2f0ee/src/test/compile-fail/macro-comma-behavior.rs#L49-L52) that didn't seem to work (rustc emits errors, but compile-fail doesn't acknowledge them), so they are disabled. Any clues? (Possibly related: These happen to be precisely the set of errors which are tagged by rustc as "this error originates in a macro outside of the current crate".)
---
Fixes#48042Closes#46241
BREAKING CHANGE: (or perhaps, *bugfix*)
In #![no_std] applications, the following calls to `panic!` used
to behave differently; they now behave the same.
Old behavior:
panic!("{{"); // panics with "{{"
panic!("{{",); // panics with "{"
New behavior:
panic!("{{"); // panics with "{{"
panic!("{{",); // panics with "{{"
This only affects calls to `panic!` (and by proxy `assert`
and `debug_assert`) with a single string literal followed by
a trailing comma, and only in `#![no_std]` applications.
assert_eq failure message easier to read
By having the left and right strings aligned with one another it helps spot the difference between the two far quicker than if they are on the same line.
E.g.
Before:
```
thread 'tests::test_safe_filename' panicked at 'assertion failed: `(left == right)` left: `"-aandb--S123.html"` right: `"-aandb-S123.html"`',
```
After:
```
thread 'tests::test_safe_filename' panicked at 'assertion failed: `(left == right)`
left: `"-aandb--S123.html"`
right: `"-aandb-S123.html"`',
```
When the strings are both on the same line it take a lot longer to spot the difference. It is a small change but the small time savings add up with repetition. This would help Rust be an excellent language to write tests in out of the box.
Closes https://github.com/rust-lang/rust/issues/41615
core: allow messages in unimplemented!() macro
This makes `unimplemented!()` match `unreachable!()`, allowing a message and possible formatting to be provided to better explain what and/or why something is not implemented.
I've used this myself in hyper for a while, include the type and method name, to better help while prototyping new modules, like `unimplemented!("Conn::poll_complete")`, or `unimplemented!("Conn::poll; state={:?}", state)`.
By having the left and right strings above and below on the same line it helps spot the difference between the two. E.g.
thread 'tests::test_safe_filename' panicked at 'assertion failed: `(left == right)`
left: `"-aandb--S123.html"`
right: `"-aandb-S123.html"`',
When the strings are both on the same line it take a lot longer to spot the difference. It is a small change but the small time savings add up with repetition. This helps Rust be an excellent language to write tests in.
This change reduces duplication by linking the documentation for
`writeln!` to `write!`. It also restructures the `write!` documentation
to read in a more logical manner.
Updates #29329, #29381
Previously, `assert_eq!(left, right,)` (respectively, `assert_ne!(left,
right,)`; note the trailing comma) would result in a confusing "requires
at least a format string argument" error. In reality, a format string is
optional, but the trailing comma puts us into the "match a token tree of
zero or more tokens" branch of the macro (in order to support the
optional format string), and passing the empty token tree into
`format_args!` results in the confusing error. If instead we match a
token tree of one or more tokens, we get a much more sensible
"unexpected end of macro invocation" error.
While we're here, fix up a stray space before a comma in the match
guards.
Resolves#39369.
Document convention for using both fmt::Write and io::Write
Using a trait's methods (like `Write::write_fmt` as used in `writeln!` and other macros) requires importing that trait directly (not just the module containing it). Both `fmt::Write` and `io::Write` provide compatible `Write::write_fmt` methods, and code can use `writeln!` and other macros on both an object implementing `fmt::Write` (such as a `String`) and an object implementing `io::Write` (such as `Stderr`). However, importing both `Write` traits produces an error due to the name conflict.
The convention I've seen renames both of them on import, to `FmtWrite` and `IoWrite` respectively. Document that convention in the Rust documentation for `write!` and `writeln!`, with examples.
Copyediting on documentation for write! and writeln!
Fix various sentence fragments, missing articles, and other grammatical issues in the documentation for write! and writeln!.
Also fix the links (and link names) for common return types.
(Noticed when preparing https://github.com/rust-lang/rust/pull/37472 ; posted separately to avoid mixing the new documentation with copyedits to existing documentation.)
