Repository navigation
Description
For the token sequence #! to start a shebang which would get stripped, it must be located at the very start of the file (modulo Unicode BOM) and not be followed by (whitespace | line_comment | block_comment)* [. If that's not given, the lexer won't remove it for the parser to digest instead. Meaning if the #! doesn't start an inner attribute, the parser will emit a relatively opaque / terse error of the form expected `[`, found $ACTUAL.
The most common trigger would be leading whitespace (incl. leading newlines). Example:
#!/usr/bin/env -S cargo +nightly -Zscripterror: expected `[`, found `/`
--> src/lib.rs:1:4
|
1 | #!/usr/bin/env -S cargo +nightly -Zscript
| ^ expected `[`
Ideally the parser would helpfully point out that the #! doesn't start a shebang here because $reasons.
I suspect this to get hit increasingly more often with the advent of RFC3424 Cargo scripts but we're generally still in uncommon and P-low territory I'd say.
This diagnostic was originally encountered by @epage in the context of doctests (source). Example reproducer:
//! ```
//! #!/usr/bin/env -S cargo +nightly -Zscript
//! fn main() {}
//! ```
rustdoc file.rs --test currently yields (abbreviated):
---- file.rs - (line 1) stdout ----
error: expected `[`, found `/`
--> file.rs:2:3
|
2 | #!/usr/bin/env rustc
| ^ expected `[`
error: aborting due to 1 previous error
Couldn't compile the test.
NB: Whether rustdoc should interpret the #! in #[doc = "#!..."] (notice: no leading space!) or equivalently /// #!... as the start of a shebang (right now it doesn't) assuming the doc attr/comment is sandwiched in between /// ``` of course is a separate question for T-rustdoc to decide.#! will likely never start a shebang inside doctests and that's good, too.
Once rustc supports frontmatter (#136889) which will get treated very similarly, we can think about improving diagnostics for their "lookalikes", too (i.e., detecting "stray" --- (etc.) in the parser).
Activity
[-]Provide a more helpful diagnostic on "shebang lookalikes" (and "frontmatter lookalikes" soon too )[/-][+]Provide a more helpful diagnostic on "shebang lookalikes" (and soon "frontmatter lookalikes" too)[/+]theemathas commentedon Feb 19, 2025
fmease commentedon Feb 19, 2025
I'm not sure how that's related apart from the word "exclamation mark"?
#!(Pound, Bang) falls into a different lexical / syntactic category and is much simpler to robustly detect and deal with by several orders of magnitude.epage commentedon Feb 19, 2025
Overall, I feel like the lookalikes are most likely to happen in rustdoc that I suspect focusing on that can offer better results if its done before the conversion to test code. Frontmatters in rustdoc is being discussed on zulip
fmease commentedon Feb 19, 2025
I'm not sure I completely agree but I do see your point. As long as the checks are robust enough I'd be okay with that as well. E.g., we shouldn't start rejecting the following code:
There's no shebang here.
Just note that handling this inside rustc would get us two for one.
Pyr0de commentedon Feb 22, 2025
I'd like to give try solving this issue.
Should I replace the current error message, produced here with another error message? and what should the error message be?
@rustbot claim
fmease commentedon Feb 23, 2025
I think I would keep the message and simply attach a (subdiagnostic) note because it wouldn't be super high-confidence (since it likely admits several false positives (which is okay)). Thanks for taking a shot at it :)
Pyr0de commentedon Feb 24, 2025
If
strip_shebangreturns None here, we could try to strip the leading whitespaces(and maybe comments?) and check withstrip_shebangagain to know if there is a shebang with leading whitespaces to then emit a warningbut this would not give a warning for a shebang which is written after some valid syntax like
Is it needed to check for shebang throughout the file or just at the start?
epage commentedon Feb 24, 2025
@Pyr0de , If this is being used to help with errors in doctests, then a shebang can appear anywhere rustdoc would be injecting it.
@fmease I overlooked this previously:
rustc's
strip_shebangwill not strip the shebang in that case because it looks for#!followed by a[, allowing for whitespace and comments in between.Rollup merge of rust-lang#137619 - Pyr0de:issue_137249, r=fmease
Unrolled build for rust-lang#137619
[-]Provide a more helpful diagnostic on "shebang lookalikes" (and soon "frontmatter lookalikes" too)[/-][+]Provide a more helpful diagnostic on "shebang lookalikes"[/+]epage commentedon Oct 23, 2025
While the tests show that we improved shebang handling generally, it looks like this doesn't help with rustdoc.
fmease commentedon Oct 23, 2025
@epage Right, that's because we unfortunately strip shebang and frontmatter in doctests now … accidentally, CC #147014.
epage commentedon Oct 23, 2025
Should we re-open this since the intended use case (doctests) isn't fixed or create a new issue to track this?
fmease commentedon Oct 23, 2025
I would create a new issue. It does depend on how we want to solve #147014: If we end up reverting to the previous behavior of not stripping these, then PR #137619 should kick in. If we don't, then this diagnostic issue remains and we should do something about it (I'm omitting some other considerations).
So opening a new issue is a safe choice regardless (I might do so later unless you're faster).
epage commentedon Oct 23, 2025
Created #148053