# Motivation
This macro is:
* General-purpose (not domain-specific)
* Simple (the implementation is short)
* Very popular [on crates.io](https://crates.io/crates/matches)
(currently 37th in all-time downloads)
* The two previous points combined make it number one in
[left-pad index](https://twitter.com/bascule/status/1184523027888988160)
score
As such, I feel it is a good candidate for inclusion in the standard library.
In fact I already felt that way five years ago:
https://github.com/rust-lang/rust/pull/14685
(Although the proof of popularity was not as strong at the time.)
Back then, the main concern was that this macro may not be quite
universally-enough useful to belong in the prelude.
# API
Therefore, this PR adds the macro such that using it requires one of:
```
use core::macros::matches;
use std::macros::matches;
```
Like arms of a `match` expression,
the macro supports multiple patterns separated by `|`
and optionally followed by `if` and a guard expression:
```
let foo = 'f';
assert!(matches!(foo, 'A'..='Z' | 'a'..='z'));
let bar = Some(4);
assert!(matches!(bar, Some(x) if x > 2));
```
# Implementation constraints
A combination of reasons make it tricky
for a standard library macro not to be in the prelude.
Currently, all public `macro_rules` macros in the standard library macros
end up “in the prelude” of every crate not through `use std::prelude::v1::*;`
like for other kinds of items,
but through `#[macro_use]` on `extern crate std;`.
(Both are injected by `src/libsyntax_ext/standard_library_imports.rs`.)
`#[macro_use]` seems to import every macro that is available
at the top-level of a crate, even if through a `pub use` re-export.
Therefore, for `matches!` not to be in the prelude, we need it to be
inside of a module rather than at the root of `core` or `std`.
However, the only way to make a `macro_rules` macro public
outside of the crate where it is defined
appears to be `#[macro_export]`.
This exports the macro at the root of the crate
regardless of which module defines it.
See [macro scoping](
https://doc.rust-lang.org/reference/macros-by-example.html#scoping-exporting-and-importing)
in the reference.
Therefore, the macro needs to be defined in a crate
that is not `core` or `std`.
# Implementation
This PR adds a new `matches_macro` crate as a private implementation detail
of the standard library.
This crate is `#![no_core]` so that libcore can depend on it.
It contains a `macro_rules` definition with `#[macro_export]`.
libcore and libstd each have a new public `macros` module
that contains a `pub use` re-export of the macro.
Both the module and the macro are unstable, for now.
The existing private `macros` modules are renamed `prelude_macros`,
though their respective source remains in `macros.rs` files.
Rollup of 14 pull requests
Successful merges:
- #64145 (Target-feature documented as unsafe)
- #65007 (Mention keyword closing policy)
- #65417 (Add more coherence tests)
- #65507 (Fix test style in unused parentheses lint test)
- #65591 (Add long error explanation for E0588)
- #65617 (Fix WASI sleep impl)
- #65656 (Add option to disable keyboard shortcuts in docs)
- #65678 (Add long error explanation for E0728)
- #65681 (Code cleanups following up on #65576.)
- #65686 (refactor and move `maybe_append` )
- #65688 (Add some tests for fixed ICEs)
- #65689 (bring back some Debug instances for Miri)
- #65695 (self-profiling: Remove module names from some event-ids in codegen backend.)
- #65706 (Add missing space in librustdoc)
Failed merges:
r? @ghost
self-profiling: Remove module names from some event-ids in codegen backend.
Event-IDs are not supposed to contain argument values. Event-IDs are the equivalent of function names. Proper support for parameters will be added to self-profiling down the line.
This PR fixes an oversight from https://github.com/rust-lang/rust/pull/64840.
r? @wesleywiser
bring back some Debug instances for Miri
These were erroneously removed in https://github.com/rust-lang/rust/pull/65647, but Miri needs them.
r? @Centril Cc @nnethercote @oli-obk
Add some tests for fixed ICEs
Fixes#41366 from 1.35.0
Fixes#51431 from 1.31.0-nightly (77af31408 2018-10-11) (on my local)
Fixes#52437 from nightly
Fixes#63496 from nightly
r? @Centril
Fix test style in unused parentheses lint test
I think this fixes#63237
I'm not sure if I had to add text after the `//~ ERROR` comments.
This is my first pull request, so I'm open to feedback.
This issues already received one pull request [here](https://github.com/rust-lang/rust/pull/63257) but it was marked as closed for inactivity.
r? @nikomatsakis
Add more coherence tests
I've wrote the missing test cases listed in [this google doc](https://docs.google.com/spreadsheets/d/1WlroTEXE6qxxGvEOhICkUpqguYZP9YOZEvnmEtSNtM0/edit#gid=0)
> The other thing that might be useful is to rename the existing tests so they all fit the new naming scheme we were using.
I'm not entirely sure how to do this. If everything from the google sheet is covered could I just remove the remaining tests in `src/test/ui/coherence` or is there something in there that should remain?
cc #63599
r? @nikomatsakis
Mention keyword closing policy
closes#59233 / https://github.com/rust-lang/rust/issues/59233#issuecomment-478362693
rewording suggestions welcome
> Also in the referenced issue, the commit number of the new commit
> that could close that issue is not really informative. The PR number itself appeared in the issue
> is more informative and concise.
@lzutao what do you mean with that? Is this fixed by the new "May be fixed by #XXXXX"?
