use std::borrow::Cow;
use std::collections::VecDeque;
use std::fmt::Write;
use std::iter::Peekable;
use std::ops::{ControlFlow, Range};
use std::path::PathBuf;
use std::str::{self, CharIndices};
use pulldown_cmark::{
BrokenLink, CodeBlockKind, CowStr, Event, LinkType, Options, Parser, Tag, TagEnd, html,
};
use rustc_data_structures::fx::FxHashMap;
use rustc_errors::{Diag, DiagMessage};
use rustc_hir::def_id::LocalDefId;
use rustc_middle::ty::TyCtxt;
pub(crate) use rustc_resolve::rustdoc::main_body_opts;
use rustc_resolve::rustdoc::may_be_doc_link;
use rustc_span::edition::Edition;
use rustc_span::{Span, Symbol};
use tracing::{debug, trace};
use crate::clean::RenderedLink;
use crate::doctest;
use crate::doctest::GlobalTestOptions;
use crate::html::escape::{Escape, EscapeBodyText};
use crate::html::format::Buffer;
use crate::html::highlight;
use crate::html::length_limit::HtmlWithLimit;
use crate::html::render::small_url_encode;
use crate::html::toc::{Toc, TocBuilder};
mod footnotes;
#[cfg(test)]
mod tests;
const MAX_HEADER_LEVEL: u32 = 6;
pub(crate) fn summary_opts() -> Options {
Options::ENABLE_TABLES
| Options::ENABLE_FOOTNOTES
| Options::ENABLE_STRIKETHROUGH
| Options::ENABLE_TASKLISTS
| Options::ENABLE_SMART_PUNCTUATION
}
#[derive(Debug, Clone, Copy)]
pub enum HeadingOffset {
H1 = 0,
H2,
H3,
H4,
H5,
H6,
}
pub struct Markdown<'a> {
pub content: &'a str,
pub links: &'a [RenderedLink],
pub ids: &'a mut IdMap,
pub error_codes: ErrorCodes,
pub edition: Edition,
pub playground: &'a Option<Playground>,
pub heading_offset: HeadingOffset,
}
pub(crate) struct MarkdownWithToc<'a> {
pub(crate) content: &'a str,
pub(crate) links: &'a [RenderedLink],
pub(crate) ids: &'a mut IdMap,
pub(crate) error_codes: ErrorCodes,
pub(crate) edition: Edition,
pub(crate) playground: &'a Option<Playground>,
}
pub(crate) struct MarkdownItemInfo<'a>(pub(crate) &'a str, pub(crate) &'a mut IdMap);
pub(crate) struct MarkdownSummaryLine<'a>(pub &'a str, pub &'a [RenderedLink]);
#[derive(Copy, Clone, PartialEq, Debug)]
pub enum ErrorCodes {
Yes,
No,
}
impl ErrorCodes {
pub(crate) fn from(b: bool) -> Self {
match b {
true => ErrorCodes::Yes,
false => ErrorCodes::No,
}
}
pub(crate) fn as_bool(self) -> bool {
match self {
ErrorCodes::Yes => true,
ErrorCodes::No => false,
}
}
}
enum Line<'a> {
Hidden(&'a str),
Shown(Cow<'a, str>),
}
impl<'a> Line<'a> {
fn for_html(self) -> Option<Cow<'a, str>> {
match self {
Line::Shown(l) => Some(l),
Line::Hidden(_) => None,
}
}
fn for_code(self) -> Cow<'a, str> {
match self {
Line::Shown(l) => l,
Line::Hidden(l) => Cow::Borrowed(l),
}
}
}
fn map_line(s: &str) -> Line<'_> {
let trimmed = s.trim();
if trimmed.starts_with("##") {
Line::Shown(Cow::Owned(s.replacen("##", "#", 1)))
} else if let Some(stripped) = trimmed.strip_prefix("# ") {
Line::Hidden(stripped)
} else if trimmed == "#" {
Line::Hidden("")
} else {
Line::Shown(Cow::Borrowed(s))
}
}
fn slugify(c: char) -> Option<char> {
if c.is_alphanumeric() || c == '-' || c == '_' {
if c.is_ascii() { Some(c.to_ascii_lowercase()) } else { Some(c) }
} else if c.is_whitespace() && c.is_ascii() {
Some('-')
} else {
None
}
}
#[derive(Clone, Debug)]
pub struct Playground {
pub crate_name: Option<Symbol>,
pub url: String,
}
struct CodeBlocks<'p, 'a, I: Iterator<Item = Event<'a>>> {
inner: I,
check_error_codes: ErrorCodes,
edition: Edition,
playground: &'p Option<Playground>,
}
impl<'p, 'a, I: Iterator<Item = Event<'a>>> CodeBlocks<'p, 'a, I> {
fn new(
iter: I,
error_codes: ErrorCodes,
edition: Edition,
playground: &'p Option<Playground>,
) -> Self {
CodeBlocks { inner: iter, check_error_codes: error_codes, edition, playground }
}
}
impl<'a, I: Iterator<Item = Event<'a>>> Iterator for CodeBlocks<'_, 'a, I> {
type Item = Event<'a>;
fn next(&mut self) -> Option<Self::Item> {
let event = self.inner.next();
let Some(Event::Start(Tag::CodeBlock(kind))) = event else {
return event;
};
let mut original_text = String::new();
for event in &mut self.inner {
match event {
Event::End(TagEnd::CodeBlock) => break,
Event::Text(ref s) => {
original_text.push_str(s);
}
_ => {}
}
}
let LangString { added_classes, compile_fail, should_panic, ignore, edition, .. } =
match kind {
CodeBlockKind::Fenced(ref lang) => {
let parse_result =
LangString::parse_without_check(lang, self.check_error_codes, false);
if !parse_result.rust {
let added_classes = parse_result.added_classes;
let lang_string = if let Some(lang) = parse_result.unknown.first() {
format!("language-{}", lang)
} else {
String::new()
};
let whitespace = if added_classes.is_empty() { "" } else { " " };
return Some(Event::Html(
format!(
"<div class=\"example-wrap\">\
<pre class=\"{lang_string}{whitespace}{added_classes}\">\
<code>{text}</code>\
</pre>\
</div>",
added_classes = added_classes.join(" "),
text = Escape(
original_text.strip_suffix('\n').unwrap_or(&original_text)
),
)
.into(),
));
}
parse_result
}
CodeBlockKind::Indented => Default::default(),
};
let lines = original_text.lines().filter_map(|l| map_line(l).for_html());
let text = lines.intersperse("\n".into()).collect::<String>();
let explicit_edition = edition.is_some();
let edition = edition.unwrap_or(self.edition);
let playground_button = self.playground.as_ref().and_then(|playground| {
let krate = &playground.crate_name;
let url = &playground.url;
if url.is_empty() {
return None;
}
let test = original_text
.lines()
.map(|l| map_line(l).for_code())
.intersperse("\n".into())
.collect::<String>();
let krate = krate.as_ref().map(|s| s.as_str());
let opts = GlobalTestOptions {
crate_name: krate.map(String::from).unwrap_or_default(),
no_crate_inject: false,
insert_indent_space: true,
attrs: vec![],
args_file: PathBuf::new(),
};
let doctest = doctest::DocTestBuilder::new(&test, krate, edition, false, None, None);
let (test, _) = doctest.generate_unique_doctest(&test, false, &opts, krate);
let channel = if test.contains("#![feature(") { "&version=nightly" } else { "" };
let test_escaped = small_url_encode(test);
Some(format!(
"<a class=\"test-arrow\" \
target=\"_blank\" \
title=\"Run code\" \
href=\"{url}?code={test_escaped}{channel}&edition={edition}\"></a>",
))
});
let tooltip = if ignore != Ignore::None {
highlight::Tooltip::Ignore
} else if compile_fail {
highlight::Tooltip::CompileFail
} else if should_panic {
highlight::Tooltip::ShouldPanic
} else if explicit_edition {
highlight::Tooltip::Edition(edition)
} else {
highlight::Tooltip::None
};
let mut s = Buffer::new();
s.push('\n');
highlight::render_example_with_highlighting(
&text,
&mut s,
tooltip,
playground_button.as_deref(),
&added_classes,
);
Some(Event::Html(s.into_inner().into()))
}
}
struct LinkReplacer<'a, I: Iterator<Item = Event<'a>>> {
inner: I,
links: &'a [RenderedLink],
shortcut_link: Option<&'a RenderedLink>,
}
impl<'a, I: Iterator<Item = Event<'a>>> LinkReplacer<'a, I> {
fn new(iter: I, links: &'a [RenderedLink]) -> Self {
LinkReplacer { inner: iter, links, shortcut_link: None }
}
}
impl<'a, I: Iterator<Item = Event<'a>>> Iterator for LinkReplacer<'a, I> {
type Item = Event<'a>;
fn next(&mut self) -> Option<Self::Item> {
let mut event = self.inner.next();
match &mut event {
Some(Event::Start(Tag::Link {
link_type: LinkType::ShortcutUnknown | LinkType::CollapsedUnknown,
dest_url,
title,
..
})) => {
debug!("saw start of shortcut link to {dest_url} with title {title}");
let link = self.links.iter().find(|&link| *link.href == **dest_url);
if let Some(link) = link {
trace!("it matched");
assert!(self.shortcut_link.is_none(), "shortcut links cannot be nested");
self.shortcut_link = Some(link);
if title.is_empty() && !link.tooltip.is_empty() {
*title = CowStr::Borrowed(link.tooltip.as_ref());
}
}
}
Some(Event::End(TagEnd::Link)) if self.shortcut_link.is_some() => {
debug!("saw end of shortcut link");
self.shortcut_link = None;
}
Some(Event::Code(text)) => {
trace!("saw code {text}");
if let Some(link) = self.shortcut_link {
if let Some(link) = self.links.iter().find(|l| {
l.href == link.href
&& Some(&**text) == l.original_text.get(1..l.original_text.len() - 1)
}) {
debug!("replacing {text} with {new_text}", new_text = link.new_text);
*text = CowStr::Borrowed(&link.new_text);
}
}
}
Some(Event::Text(text)) => {
trace!("saw text {text}");
if let Some(link) = self.shortcut_link {
if let Some(link) = self
.links
.iter()
.find(|l| l.href == link.href && **text == *l.original_text)
{
debug!("replacing {text} with {new_text}", new_text = link.new_text);
*text = CowStr::Borrowed(&link.new_text);
}
}
}
Some(Event::Start(Tag::Link { dest_url, title, .. })) => {
if let Some(link) =
self.links.iter().find(|&link| *link.original_text == **dest_url)
{
*dest_url = CowStr::Borrowed(link.href.as_ref());
if title.is_empty() && !link.tooltip.is_empty() {
*title = CowStr::Borrowed(link.tooltip.as_ref());
}
}
}
_ => {}
}
event
}
}
struct TableWrapper<'a, I: Iterator<Item = Event<'a>>> {
inner: I,
stored_events: VecDeque<Event<'a>>,
}
impl<'a, I: Iterator<Item = Event<'a>>> TableWrapper<'a, I> {
fn new(iter: I) -> Self {
Self { inner: iter, stored_events: VecDeque::new() }
}
}
impl<'a, I: Iterator<Item = Event<'a>>> Iterator for TableWrapper<'a, I> {
type Item = Event<'a>;
fn next(&mut self) -> Option<Self::Item> {
if let Some(first) = self.stored_events.pop_front() {
return Some(first);
}
let event = self.inner.next()?;
Some(match event {
Event::Start(Tag::Table(t)) => {
self.stored_events.push_back(Event::Start(Tag::Table(t)));
Event::Html(CowStr::Borrowed("<div>"))
}
Event::End(TagEnd::Table) => {
self.stored_events.push_back(Event::Html(CowStr::Borrowed("</div>")));
Event::End(TagEnd::Table)
}
e => e,
})
}
}
type SpannedEvent<'a> = (Event<'a>, Range<usize>);
struct HeadingLinks<'a, 'b, 'ids, I> {
inner: I,
toc: Option<&'b mut TocBuilder>,
buf: VecDeque<SpannedEvent<'a>>,
id_map: &'ids mut IdMap,
heading_offset: HeadingOffset,
}
impl<'b, 'ids, I> HeadingLinks<'_, 'b, 'ids, I> {
fn new(
iter: I,
toc: Option<&'b mut TocBuilder>,
ids: &'ids mut IdMap,
heading_offset: HeadingOffset,
) -> Self {
HeadingLinks { inner: iter, toc, buf: VecDeque::new(), id_map: ids, heading_offset }
}
}
impl<'a, I: Iterator<Item = SpannedEvent<'a>>> Iterator for HeadingLinks<'a, '_, '_, I> {
type Item = SpannedEvent<'a>;
fn next(&mut self) -> Option<Self::Item> {
if let Some(e) = self.buf.pop_front() {
return Some(e);
}
let event = self.inner.next();
if let Some((Event::Start(Tag::Heading { level, .. }), _)) = event {
let mut id = String::new();
for event in &mut self.inner {
match &event.0 {
Event::End(TagEnd::Heading(_)) => break,
Event::Text(text) | Event::Code(text) => {
id.extend(text.chars().filter_map(slugify));
self.buf.push_back(event);
}
_ => self.buf.push_back(event),
}
}
let id = self.id_map.derive(id);
if let Some(ref mut builder) = self.toc {
let mut text_header = String::new();
plain_text_from_events(self.buf.iter().map(|(ev, _)| ev.clone()), &mut text_header);
let mut html_header = String::new();
html_text_from_events(self.buf.iter().map(|(ev, _)| ev.clone()), &mut html_header);
let sec = builder.push(level as u32, text_header, html_header, id.clone());
self.buf.push_front((Event::Html(format!("{sec} ").into()), 0..0));
}
let level =
std::cmp::min(level as u32 + (self.heading_offset as u32), MAX_HEADER_LEVEL);
self.buf.push_back((Event::Html(format!("</h{level}>").into()), 0..0));
let start_tags =
format!("<h{level} id=\"{id}\"><a class=\"doc-anchor\" href=\"#{id}\">§</a>");
return Some((Event::Html(start_tags.into()), 0..0));
}
event
}
}
struct SummaryLine<'a, I: Iterator<Item = Event<'a>>> {
inner: I,
started: bool,
depth: u32,
skipped_tags: u32,
}
impl<'a, I: Iterator<Item = Event<'a>>> SummaryLine<'a, I> {
fn new(iter: I) -> Self {
SummaryLine { inner: iter, started: false, depth: 0, skipped_tags: 0 }
}
}
fn check_if_allowed_tag(t: &TagEnd) -> bool {
matches!(
t,
TagEnd::Paragraph
| TagEnd::Emphasis
| TagEnd::Strong
| TagEnd::Strikethrough
| TagEnd::Link
| TagEnd::BlockQuote
)
}
fn is_forbidden_tag(t: &TagEnd) -> bool {
matches!(
t,
TagEnd::CodeBlock
| TagEnd::Table
| TagEnd::TableHead
| TagEnd::TableRow
| TagEnd::TableCell
| TagEnd::FootnoteDefinition
)
}
impl<'a, I: Iterator<Item = Event<'a>>> Iterator for SummaryLine<'a, I> {
type Item = Event<'a>;
fn next(&mut self) -> Option<Self::Item> {
if self.started && self.depth == 0 {
return None;
}
if !self.started {
self.started = true;
}
if let Some(event) = self.inner.next() {
let mut is_start = true;
let is_allowed_tag = match event {
Event::Start(ref c) => {
if is_forbidden_tag(&c.to_end()) {
self.skipped_tags += 1;
return None;
}
self.depth += 1;
check_if_allowed_tag(&c.to_end())
}
Event::End(ref c) => {
if is_forbidden_tag(c) {
self.skipped_tags += 1;
return None;
}
self.depth -= 1;
is_start = false;
check_if_allowed_tag(c)
}
Event::FootnoteReference(_) => {
self.skipped_tags += 1;
false
}
_ => true,
};
if !is_allowed_tag {
self.skipped_tags += 1;
}
return if !is_allowed_tag {
if is_start {
Some(Event::Start(Tag::Paragraph))
} else {
Some(Event::End(TagEnd::Paragraph))
}
} else {
Some(event)
};
}
None
}
}
pub(crate) struct MdRelLine {
offset: usize,
}
impl MdRelLine {
pub(crate) const fn new(offset: usize) -> Self {
Self { offset }
}
pub(crate) const fn offset(self) -> usize {
self.offset
}
}
pub(crate) fn find_testable_code<T: doctest::DocTestVisitor>(
doc: &str,
tests: &mut T,
error_codes: ErrorCodes,
enable_per_target_ignores: bool,
extra_info: Option<&ExtraInfo<'_>>,
) {
find_codes(doc, tests, error_codes, enable_per_target_ignores, extra_info, false)
}
pub(crate) fn find_codes<T: doctest::DocTestVisitor>(
doc: &str,
tests: &mut T,
error_codes: ErrorCodes,
enable_per_target_ignores: bool,
extra_info: Option<&ExtraInfo<'_>>,
include_non_rust: bool,
) {
let mut parser = Parser::new(doc).into_offset_iter();
let mut prev_offset = 0;
let mut nb_lines = 0;
let mut register_header = None;
while let Some((event, offset)) = parser.next() {
match event {
Event::Start(Tag::CodeBlock(kind)) => {
let block_info = match kind {
CodeBlockKind::Fenced(ref lang) => {
if lang.is_empty() {
Default::default()
} else {
LangString::parse(
lang,
error_codes,
enable_per_target_ignores,
extra_info,
)
}
}
CodeBlockKind::Indented => Default::default(),
};
if !include_non_rust && !block_info.rust {
continue;
}
let mut test_s = String::new();
while let Some((Event::Text(s), _)) = parser.next() {
test_s.push_str(&s);
}
let text = test_s
.lines()
.map(|l| map_line(l).for_code())
.collect::<Vec<Cow<'_, str>>>()
.join("\n");
nb_lines += doc[prev_offset..offset.start].lines().count();
if nb_lines != 0 && !&doc[prev_offset..offset.start].ends_with('\n') {
nb_lines -= 1;
}
let line = MdRelLine::new(nb_lines);
tests.visit_test(text, block_info, line);
prev_offset = offset.start;
}
Event::Start(Tag::Heading { level, .. }) => {
register_header = Some(level as u32);
}
Event::Text(ref s) if register_header.is_some() => {
let level = register_header.unwrap();
tests.visit_header(s, level);
register_header = None;
}
_ => {}
}
}
}
pub(crate) struct ExtraInfo<'tcx> {
def_id: LocalDefId,
sp: Span,
tcx: TyCtxt<'tcx>,
}
impl<'tcx> ExtraInfo<'tcx> {
pub(crate) fn new(tcx: TyCtxt<'tcx>, def_id: LocalDefId, sp: Span) -> ExtraInfo<'tcx> {
ExtraInfo { def_id, sp, tcx }
}
fn error_invalid_codeblock_attr(&self, msg: impl Into<DiagMessage>) {
self.tcx.node_span_lint(
crate::lint::INVALID_CODEBLOCK_ATTRIBUTES,
self.tcx.local_def_id_to_hir_id(self.def_id),
self.sp,
|lint| {
lint.primary_message(msg);
},
);
}
fn error_invalid_codeblock_attr_with_help(
&self,
msg: impl Into<DiagMessage>,
f: impl for<'a, 'b> FnOnce(&'b mut Diag<'a, ()>),
) {
self.tcx.node_span_lint(
crate::lint::INVALID_CODEBLOCK_ATTRIBUTES,
self.tcx.local_def_id_to_hir_id(self.def_id),
self.sp,
|lint| {
lint.primary_message(msg);
f(lint);
},
);
}
}
#[derive(Eq, PartialEq, Clone, Debug)]
pub(crate) struct LangString {
pub(crate) original: String,
pub(crate) should_panic: bool,
pub(crate) no_run: bool,
pub(crate) ignore: Ignore,
pub(crate) rust: bool,
pub(crate) test_harness: bool,
pub(crate) compile_fail: bool,
pub(crate) standalone_crate: bool,
pub(crate) error_codes: Vec<String>,
pub(crate) edition: Option<Edition>,
pub(crate) added_classes: Vec<String>,
pub(crate) unknown: Vec<String>,
}
#[derive(Eq, PartialEq, Clone, Debug)]
pub(crate) enum Ignore {
All,
None,
Some(Vec<String>),
}
pub(crate) struct TagIterator<'a, 'tcx> {
inner: Peekable<CharIndices<'a>>,
data: &'a str,
is_in_attribute_block: bool,
extra: Option<&'a ExtraInfo<'tcx>>,
is_error: bool,
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub(crate) enum LangStringToken<'a> {
LangToken(&'a str),
ClassAttribute(&'a str),
KeyValueAttribute(&'a str, &'a str),
}
fn is_leading_char(c: char) -> bool {
c == '_' || c == '-' || c == ':' || c.is_ascii_alphabetic() || c.is_ascii_digit()
}
fn is_bareword_char(c: char) -> bool {
is_leading_char(c) || ".!#$%&*+/;<>?@^|~".contains(c)
}
fn is_separator(c: char) -> bool {
c == ' ' || c == ',' || c == '\t'
}
struct Indices {
start: usize,
end: usize,
}
impl<'a, 'tcx> TagIterator<'a, 'tcx> {
pub(crate) fn new(data: &'a str, extra: Option<&'a ExtraInfo<'tcx>>) -> Self {
Self {
inner: data.char_indices().peekable(),
data,
is_in_attribute_block: false,
extra,
is_error: false,
}
}
fn emit_error(&mut self, err: impl Into<DiagMessage>) {
if let Some(extra) = self.extra {
extra.error_invalid_codeblock_attr(err);
}
self.is_error = true;
}
fn skip_separators(&mut self) -> Option<usize> {
while let Some((pos, c)) = self.inner.peek() {
if !is_separator(*c) {
return Some(*pos);
}
self.inner.next();
}
None
}
fn parse_string(&mut self, start: usize) -> Option<Indices> {
for (pos, c) in self.inner.by_ref() {
if c == '"' {
return Some(Indices { start: start + 1, end: pos });
}
}
self.emit_error("unclosed quote string `\"`");
None
}
fn parse_class(&mut self, start: usize) -> Option<LangStringToken<'a>> {
while let Some((pos, c)) = self.inner.peek().copied() {
if is_bareword_char(c) {
self.inner.next();
} else {
let class = &self.data[start + 1..pos];
if class.is_empty() {
self.emit_error(format!("unexpected `{c}` character after `.`"));
return None;
} else if self.check_after_token() {
return Some(LangStringToken::ClassAttribute(class));
} else {
return None;
}
}
}
let class = &self.data[start + 1..];
if class.is_empty() {
self.emit_error("missing character after `.`");
None
} else if self.check_after_token() {
Some(LangStringToken::ClassAttribute(class))
} else {
None
}
}
fn parse_token(&mut self, start: usize) -> Option<Indices> {
while let Some((pos, c)) = self.inner.peek() {
if !is_bareword_char(*c) {
return Some(Indices { start, end: *pos });
}
self.inner.next();
}
self.emit_error("unexpected end");
None
}
fn parse_key_value(&mut self, c: char, start: usize) -> Option<LangStringToken<'a>> {
let key_indices =
if c == '"' { self.parse_string(start)? } else { self.parse_token(start)? };
if key_indices.start == key_indices.end {
self.emit_error("unexpected empty string as key");
return None;
}
if let Some((_, c)) = self.inner.next() {
if c != '=' {
self.emit_error(format!("expected `=`, found `{}`", c));
return None;
}
} else {
self.emit_error("unexpected end");
return None;
}
let value_indices = match self.inner.next() {
Some((pos, '"')) => self.parse_string(pos)?,
Some((pos, c)) if is_bareword_char(c) => self.parse_token(pos)?,
Some((_, c)) => {
self.emit_error(format!("unexpected `{c}` character after `=`"));
return None;
}
None => {
self.emit_error("expected value after `=`");
return None;
}
};
if value_indices.start == value_indices.end {
self.emit_error("unexpected empty string as value");
None
} else if self.check_after_token() {
Some(LangStringToken::KeyValueAttribute(
&self.data[key_indices.start..key_indices.end],
&self.data[value_indices.start..value_indices.end],
))
} else {
None
}
}
fn check_after_token(&mut self) -> bool {
if let Some((_, c)) = self.inner.peek().copied() {
if c == '}' || is_separator(c) || c == '(' {
true
} else {
self.emit_error(format!("unexpected `{c}` character"));
false
}
} else {
true
}
}
fn parse_in_attribute_block(&mut self) -> Option<LangStringToken<'a>> {
if let Some((pos, c)) = self.inner.next() {
if c == '}' {
self.is_in_attribute_block = false;
return self.next();
} else if c == '.' {
return self.parse_class(pos);
} else if c == '"' || is_leading_char(c) {
return self.parse_key_value(c, pos);
} else {
self.emit_error(format!("unexpected character `{c}`"));
return None;
}
}
self.emit_error("unclosed attribute block (`{}`): missing `}` at the end");
None
}
fn skip_paren_block(&mut self) -> bool {
for (_, c) in self.inner.by_ref() {
if c == ')' {
return true;
}
}
self.emit_error("unclosed comment: missing `)` at the end");
false
}
fn parse_outside_attribute_block(&mut self, start: usize) -> Option<LangStringToken<'a>> {
while let Some((pos, c)) = self.inner.next() {
if c == '"' {
if pos != start {
self.emit_error("expected ` `, `{` or `,` found `\"`");
return None;
}
let indices = self.parse_string(pos)?;
if let Some((_, c)) = self.inner.peek().copied()
&& c != '{'
&& !is_separator(c)
&& c != '('
{
self.emit_error(format!("expected ` `, `{{` or `,` after `\"`, found `{c}`"));
return None;
}
return Some(LangStringToken::LangToken(&self.data[indices.start..indices.end]));
} else if c == '{' {
self.is_in_attribute_block = true;
return self.next();
} else if is_separator(c) {
if pos != start {
return Some(LangStringToken::LangToken(&self.data[start..pos]));
}
return self.next();
} else if c == '(' {
if !self.skip_paren_block() {
return None;
}
if pos != start {
return Some(LangStringToken::LangToken(&self.data[start..pos]));
}
return self.next();
} else if (pos == start && is_leading_char(c)) || (pos != start && is_bareword_char(c))
{
continue;
} else {
self.emit_error(format!("unexpected character `{c}`"));
return None;
}
}
let token = &self.data[start..];
if token.is_empty() { None } else { Some(LangStringToken::LangToken(&self.data[start..])) }
}
}
impl<'a> Iterator for TagIterator<'a, '_> {
type Item = LangStringToken<'a>;
fn next(&mut self) -> Option<Self::Item> {
if self.is_error {
return None;
}
let Some(start) = self.skip_separators() else {
if self.is_in_attribute_block {
self.emit_error("unclosed attribute block (`{}`): missing `}` at the end");
}
return None;
};
if self.is_in_attribute_block {
self.parse_in_attribute_block()
} else {
self.parse_outside_attribute_block(start)
}
}
}
impl Default for LangString {
fn default() -> Self {
Self {
original: String::new(),
should_panic: false,
no_run: false,
ignore: Ignore::None,
rust: true,
test_harness: false,
compile_fail: false,
standalone_crate: false,
error_codes: Vec::new(),
edition: None,
added_classes: Vec::new(),
unknown: Vec::new(),
}
}
}
impl LangString {
fn parse_without_check(
string: &str,
allow_error_code_check: ErrorCodes,
enable_per_target_ignores: bool,
) -> Self {
Self::parse(string, allow_error_code_check, enable_per_target_ignores, None)
}
fn parse(
string: &str,
allow_error_code_check: ErrorCodes,
enable_per_target_ignores: bool,
extra: Option<&ExtraInfo<'_>>,
) -> Self {
let allow_error_code_check = allow_error_code_check.as_bool();
let mut seen_rust_tags = false;
let mut seen_other_tags = false;
let mut seen_custom_tag = false;
let mut data = LangString::default();
let mut ignores = vec![];
data.original = string.to_owned();
let mut call = |tokens: &mut dyn Iterator<Item = LangStringToken<'_>>| {
for token in tokens {
match token {
LangStringToken::LangToken("should_panic") => {
data.should_panic = true;
seen_rust_tags = !seen_other_tags;
}
LangStringToken::LangToken("no_run") => {
data.no_run = true;
seen_rust_tags = !seen_other_tags;
}
LangStringToken::LangToken("ignore") => {
data.ignore = Ignore::All;
seen_rust_tags = !seen_other_tags;
}
LangStringToken::LangToken(x) if x.starts_with("ignore-") => {
if enable_per_target_ignores {
ignores.push(x.trim_start_matches("ignore-").to_owned());
seen_rust_tags = !seen_other_tags;
}
}
LangStringToken::LangToken("rust") => {
data.rust = true;
seen_rust_tags = true;
}
LangStringToken::LangToken("custom") => {
seen_custom_tag = true;
}
LangStringToken::LangToken("test_harness") => {
data.test_harness = true;
seen_rust_tags = !seen_other_tags || seen_rust_tags;
}
LangStringToken::LangToken("compile_fail") => {
data.compile_fail = true;
seen_rust_tags = !seen_other_tags || seen_rust_tags;
data.no_run = true;
}
LangStringToken::LangToken("standalone_crate") => {
data.standalone_crate = true;
seen_rust_tags = !seen_other_tags || seen_rust_tags;
}
LangStringToken::LangToken(x) if x.starts_with("edition") => {
data.edition = x[7..].parse::<Edition>().ok();
}
LangStringToken::LangToken(x)
if x.starts_with("rust") && x[4..].parse::<Edition>().is_ok() =>
{
if let Some(extra) = extra {
extra.error_invalid_codeblock_attr_with_help(
format!("unknown attribute `{x}`"),
|lint| {
lint.help(format!(
"there is an attribute with a similar name: `edition{}`",
&x[4..],
));
},
);
}
}
LangStringToken::LangToken(x)
if allow_error_code_check && x.starts_with('E') && x.len() == 5 =>
{
if x[1..].parse::<u32>().is_ok() {
data.error_codes.push(x.to_owned());
seen_rust_tags = !seen_other_tags || seen_rust_tags;
} else {
seen_other_tags = true;
}
}
LangStringToken::LangToken(x) if extra.is_some() => {
let s = x.to_lowercase();
if let Some(help) = match s.as_str() {
"compile-fail" | "compile_fail" | "compilefail" => Some(
"use `compile_fail` to invert the results of this test, so that it \
passes if it cannot be compiled and fails if it can",
),
"should-panic" | "should_panic" | "shouldpanic" => Some(
"use `should_panic` to invert the results of this test, so that if \
passes if it panics and fails if it does not",
),
"no-run" | "no_run" | "norun" => Some(
"use `no_run` to compile, but not run, the code sample during \
testing",
),
"test-harness" | "test_harness" | "testharness" => Some(
"use `test_harness` to run functions marked `#[test]` instead of a \
potentially-implicit `main` function",
),
"standalone" | "standalone_crate" | "standalone-crate" => {
if let Some(extra) = extra
&& extra.sp.at_least_rust_2024()
{
Some(
"use `standalone_crate` to compile this code block \
separately",
)
} else {
None
}
}
_ => None,
} {
if let Some(extra) = extra {
extra.error_invalid_codeblock_attr_with_help(
format!("unknown attribute `{x}`"),
|lint| {
lint.help(help).help(
"this code block may be skipped during testing, \
because unknown attributes are treated as markers for \
code samples written in other programming languages, \
unless it is also explicitly marked as `rust`",
);
},
);
}
}
seen_other_tags = true;
data.unknown.push(x.to_owned());
}
LangStringToken::LangToken(x) => {
seen_other_tags = true;
data.unknown.push(x.to_owned());
}
LangStringToken::KeyValueAttribute(key, value) => {
if key == "class" {
data.added_classes.push(value.to_owned());
} else if let Some(extra) = extra {
extra.error_invalid_codeblock_attr(format!(
"unsupported attribute `{key}`"
));
}
}
LangStringToken::ClassAttribute(class) => {
data.added_classes.push(class.to_owned());
}
}
}
};
let mut tag_iter = TagIterator::new(string, extra);
call(&mut tag_iter);
if !ignores.is_empty() {
data.ignore = Ignore::Some(ignores);
}
data.rust &= !seen_custom_tag && (!seen_other_tags || seen_rust_tags) && !tag_iter.is_error;
data
}
}
impl Markdown<'_> {
pub fn into_string(self) -> String {
let Markdown {
content: md,
links,
ids,
error_codes: codes,
edition,
playground,
heading_offset,
} = self;
if md.is_empty() {
return String::new();
}
let mut replacer = |broken_link: BrokenLink<'_>| {
links
.iter()
.find(|link| *link.original_text == *broken_link.reference)
.map(|link| (link.href.as_str().into(), link.tooltip.as_str().into()))
};
let p = Parser::new_with_broken_link_callback(md, main_body_opts(), Some(&mut replacer));
let p = p.into_offset_iter();
let mut s = String::with_capacity(md.len() * 3 / 2);
ids.handle_footnotes(|ids, existing_footnotes| {
let p = HeadingLinks::new(p, None, ids, heading_offset);
let p = footnotes::Footnotes::new(p, existing_footnotes);
let p = LinkReplacer::new(p.map(|(ev, _)| ev), links);
let p = TableWrapper::new(p);
let p = CodeBlocks::new(p, codes, edition, playground);
html::push_html(&mut s, p);
});
s
}
}
impl MarkdownWithToc<'_> {
pub(crate) fn into_parts(self) -> (Toc, String) {
let MarkdownWithToc { content: md, links, ids, error_codes: codes, edition, playground } =
self;
if md.is_empty() {
return (Toc { entries: Vec::new() }, String::new());
}
let mut replacer = |broken_link: BrokenLink<'_>| {
links
.iter()
.find(|link| *link.original_text == *broken_link.reference)
.map(|link| (link.href.as_str().into(), link.tooltip.as_str().into()))
};
let p = Parser::new_with_broken_link_callback(md, main_body_opts(), Some(&mut replacer));
let p = p.into_offset_iter();
let mut s = String::with_capacity(md.len() * 3 / 2);
let mut toc = TocBuilder::new();
ids.handle_footnotes(|ids, existing_footnotes| {
let p = HeadingLinks::new(p, Some(&mut toc), ids, HeadingOffset::H1);
let p = footnotes::Footnotes::new(p, existing_footnotes);
let p = TableWrapper::new(p.map(|(ev, _)| ev));
let p = CodeBlocks::new(p, codes, edition, playground);
html::push_html(&mut s, p);
});
(toc.into_toc(), s)
}
pub(crate) fn into_string(self) -> String {
let (toc, s) = self.into_parts();
format!("<nav id=\"rustdoc\">{toc}</nav>{s}", toc = toc.print())
}
}
impl MarkdownItemInfo<'_> {
pub(crate) fn into_string(self) -> String {
let MarkdownItemInfo(md, ids) = self;
if md.is_empty() {
return String::new();
}
let p = Parser::new_ext(md, main_body_opts()).into_offset_iter();
let p = p.map(|event| match event.0 {
Event::Html(text) | Event::InlineHtml(text) => (Event::Text(text), event.1),
_ => event,
});
let mut s = String::with_capacity(md.len() * 3 / 2);
ids.handle_footnotes(|ids, existing_footnotes| {
let p = HeadingLinks::new(p, None, ids, HeadingOffset::H1);
let p = footnotes::Footnotes::new(p, existing_footnotes);
let p = TableWrapper::new(p.map(|(ev, _)| ev));
let p = p.filter(|event| {
!matches!(event, Event::Start(Tag::Paragraph) | Event::End(TagEnd::Paragraph))
});
html::push_html(&mut s, p);
});
s
}
}
impl MarkdownSummaryLine<'_> {
pub(crate) fn into_string_with_has_more_content(self) -> (String, bool) {
let MarkdownSummaryLine(md, links) = self;
if md.is_empty() {
return (String::new(), false);
}
let mut replacer = |broken_link: BrokenLink<'_>| {
links
.iter()
.find(|link| *link.original_text == *broken_link.reference)
.map(|link| (link.href.as_str().into(), link.tooltip.as_str().into()))
};
let p = Parser::new_with_broken_link_callback(md, summary_opts(), Some(&mut replacer))
.peekable();
let mut summary = SummaryLine::new(p);
let mut s = String::new();
let without_paragraphs = LinkReplacer::new(&mut summary, links).filter(|event| {
!matches!(event, Event::Start(Tag::Paragraph) | Event::End(TagEnd::Paragraph))
});
html::push_html(&mut s, without_paragraphs);
let has_more_content =
matches!(summary.inner.peek(), Some(Event::Start(_))) || summary.skipped_tags > 0;
(s, has_more_content)
}
pub(crate) fn into_string(self) -> String {
self.into_string_with_has_more_content().0
}
}
fn markdown_summary_with_limit(
md: &str,
link_names: &[RenderedLink],
length_limit: usize,
) -> (String, bool) {
if md.is_empty() {
return (String::new(), false);
}
let mut replacer = |broken_link: BrokenLink<'_>| {
link_names
.iter()
.find(|link| *link.original_text == *broken_link.reference)
.map(|link| (link.href.as_str().into(), link.tooltip.as_str().into()))
};
let p = Parser::new_with_broken_link_callback(md, summary_opts(), Some(&mut replacer));
let mut p = LinkReplacer::new(p, link_names);
let mut buf = HtmlWithLimit::new(length_limit);
let mut stopped_early = false;
p.try_for_each(|event| {
match &event {
Event::Text(text) => {
let r =
text.split_inclusive(char::is_whitespace).try_for_each(|word| buf.push(word));
if r.is_break() {
stopped_early = true;
}
return r;
}
Event::Code(code) => {
buf.open_tag("code");
let r = buf.push(code);
if r.is_break() {
stopped_early = true;
} else {
buf.close_tag();
}
return r;
}
Event::Start(tag) => match tag {
Tag::Emphasis => buf.open_tag("em"),
Tag::Strong => buf.open_tag("strong"),
Tag::CodeBlock(..) => return ControlFlow::Break(()),
_ => {}
},
Event::End(tag) => match tag {
TagEnd::Emphasis | TagEnd::Strong => buf.close_tag(),
TagEnd::Paragraph | TagEnd::Heading(_) => return ControlFlow::Break(()),
_ => {}
},
Event::HardBreak | Event::SoftBreak => buf.push(" ")?,
_ => {}
};
ControlFlow::Continue(())
});
(buf.finish(), stopped_early)
}
pub(crate) fn short_markdown_summary(markdown: &str, link_names: &[RenderedLink]) -> String {
let (mut s, was_shortened) = markdown_summary_with_limit(markdown, link_names, 59);
if was_shortened {
s.push('…');
}
s
}
pub(crate) fn plain_text_summary(md: &str, link_names: &[RenderedLink]) -> String {
if md.is_empty() {
return String::new();
}
let mut s = String::with_capacity(md.len() * 3 / 2);
let mut replacer = |broken_link: BrokenLink<'_>| {
link_names
.iter()
.find(|link| *link.original_text == *broken_link.reference)
.map(|link| (link.href.as_str().into(), link.tooltip.as_str().into()))
};
let p = Parser::new_with_broken_link_callback(md, summary_opts(), Some(&mut replacer));
plain_text_from_events(p, &mut s);
s
}
pub(crate) fn plain_text_from_events<'a>(
events: impl Iterator<Item = pulldown_cmark::Event<'a>>,
s: &mut String,
) {
for event in events {
match &event {
Event::Text(text) => s.push_str(text),
Event::Code(code) => {
s.push('`');
s.push_str(code);
s.push('`');
}
Event::HardBreak | Event::SoftBreak => s.push(' '),
Event::Start(Tag::CodeBlock(..)) => break,
Event::End(TagEnd::Paragraph) => break,
Event::End(TagEnd::Heading(..)) => break,
_ => (),
}
}
}
pub(crate) fn html_text_from_events<'a>(
events: impl Iterator<Item = pulldown_cmark::Event<'a>>,
s: &mut String,
) {
for event in events {
match &event {
Event::Text(text) => {
write!(s, "{}", EscapeBodyText(text)).expect("string alloc infallible")
}
Event::Code(code) => {
s.push_str("<code>");
write!(s, "{}", EscapeBodyText(code)).expect("string alloc infallible");
s.push_str("</code>");
}
Event::HardBreak | Event::SoftBreak => s.push(' '),
Event::Start(Tag::CodeBlock(..)) => break,
Event::End(TagEnd::Paragraph) => break,
Event::End(TagEnd::Heading(..)) => break,
_ => (),
}
}
}
#[derive(Debug)]
pub(crate) struct MarkdownLink {
pub kind: LinkType,
pub link: String,
pub range: MarkdownLinkRange,
}
#[derive(Clone, Debug)]
pub(crate) enum MarkdownLinkRange {
Destination(Range<usize>),
WholeLink(Range<usize>),
}
impl MarkdownLinkRange {
pub fn inner_range(&self) -> &Range<usize> {
match self {
MarkdownLinkRange::Destination(range) => range,
MarkdownLinkRange::WholeLink(range) => range,
}
}
}
pub(crate) fn markdown_links<'md, R>(
md: &'md str,
preprocess_link: impl Fn(MarkdownLink) -> Option<R>,
) -> Vec<R> {
if md.is_empty() {
return vec![];
}
let locate = |s: &str, fallback: Range<usize>| unsafe {
let s_start = s.as_ptr();
let s_end = s_start.add(s.len());
let md_start = md.as_ptr();
let md_end = md_start.add(md.len());
if md_start <= s_start && s_end <= md_end {
let start = s_start.offset_from(md_start) as usize;
let end = s_end.offset_from(md_start) as usize;
MarkdownLinkRange::Destination(start..end)
} else {
MarkdownLinkRange::WholeLink(fallback)
}
};
let span_for_link = |link: &CowStr<'_>, span: Range<usize>| {
match link {
CowStr::Borrowed(s) => locate(s, span),
CowStr::Boxed(_) | CowStr::Inlined(_) => MarkdownLinkRange::WholeLink(span),
}
};
let span_for_offset_backward = |span: Range<usize>, open: u8, close: u8| {
let mut open_brace = !0;
let mut close_brace = !0;
for (i, b) in md.as_bytes()[span.clone()].iter().copied().enumerate().rev() {
let i = i + span.start;
if b == close {
close_brace = i;
break;
}
}
if close_brace < span.start || close_brace >= span.end {
return MarkdownLinkRange::WholeLink(span);
}
let mut nesting = 1;
for (i, b) in md.as_bytes()[span.start..close_brace].iter().copied().enumerate().rev() {
let i = i + span.start;
if b == close {
nesting += 1;
}
if b == open {
nesting -= 1;
}
if nesting == 0 {
open_brace = i;
break;
}
}
assert!(open_brace != close_brace);
if open_brace < span.start || open_brace >= span.end {
return MarkdownLinkRange::WholeLink(span);
}
let range = (open_brace + 1)..close_brace;
MarkdownLinkRange::Destination(range)
};
let span_for_offset_forward = |span: Range<usize>, open: u8, close: u8| {
let mut open_brace = !0;
let mut close_brace = !0;
for (i, b) in md.as_bytes()[span.clone()].iter().copied().enumerate() {
let i = i + span.start;
if b == open {
open_brace = i;
break;
}
}
if open_brace < span.start || open_brace >= span.end {
return MarkdownLinkRange::WholeLink(span);
}
let mut nesting = 0;
for (i, b) in md.as_bytes()[open_brace..span.end].iter().copied().enumerate() {
let i = i + open_brace;
if b == close {
nesting -= 1;
}
if b == open {
nesting += 1;
}
if nesting == 0 {
close_brace = i;
break;
}
}
assert!(open_brace != close_brace);
if open_brace < span.start || open_brace >= span.end {
return MarkdownLinkRange::WholeLink(span);
}
let range = (open_brace + 1)..close_brace;
MarkdownLinkRange::Destination(range)
};
let mut broken_link_callback = |link: BrokenLink<'md>| Some((link.reference, "".into()));
let event_iter = Parser::new_with_broken_link_callback(
md,
main_body_opts(),
Some(&mut broken_link_callback),
)
.into_offset_iter();
let mut links = Vec::new();
for (event, span) in event_iter {
match event {
Event::Start(Tag::Link { link_type, dest_url, .. }) if may_be_doc_link(link_type) => {
let range = match link_type {
LinkType::ReferenceUnknown | LinkType::ShortcutUnknown => {
span_for_offset_backward(span, b'[', b']')
}
LinkType::CollapsedUnknown => span_for_offset_forward(span, b'[', b']'),
LinkType::Inline => span_for_offset_backward(span, b'(', b')'),
LinkType::Reference | LinkType::Collapsed | LinkType::Shortcut => {
span_for_link(&dest_url, span)
}
LinkType::Autolink | LinkType::Email => unreachable!(),
};
if let Some(link) = preprocess_link(MarkdownLink {
kind: link_type,
link: dest_url.into_string(),
range,
}) {
links.push(link);
}
}
_ => {}
}
}
links
}
#[derive(Debug)]
pub(crate) struct RustCodeBlock {
pub(crate) range: Range<usize>,
pub(crate) code: Range<usize>,
pub(crate) is_fenced: bool,
pub(crate) lang_string: LangString,
}
pub(crate) fn rust_code_blocks(md: &str, extra_info: &ExtraInfo<'_>) -> Vec<RustCodeBlock> {
let mut code_blocks = vec![];
if md.is_empty() {
return code_blocks;
}
let mut p = Parser::new_ext(md, main_body_opts()).into_offset_iter();
while let Some((event, offset)) = p.next() {
if let Event::Start(Tag::CodeBlock(syntax)) = event {
let (lang_string, code_start, code_end, range, is_fenced) = match syntax {
CodeBlockKind::Fenced(syntax) => {
let syntax = syntax.as_ref();
let lang_string = if syntax.is_empty() {
Default::default()
} else {
LangString::parse(syntax, ErrorCodes::Yes, false, Some(extra_info))
};
if !lang_string.rust {
continue;
}
let (code_start, mut code_end) = match p.next() {
Some((Event::Text(_), offset)) => (offset.start, offset.end),
Some((_, sub_offset)) => {
let code = Range { start: sub_offset.start, end: sub_offset.start };
code_blocks.push(RustCodeBlock {
is_fenced: true,
range: offset,
code,
lang_string,
});
continue;
}
None => {
let code = Range { start: offset.end, end: offset.end };
code_blocks.push(RustCodeBlock {
is_fenced: true,
range: offset,
code,
lang_string,
});
continue;
}
};
while let Some((Event::Text(_), offset)) = p.next() {
code_end = offset.end;
}
(lang_string, code_start, code_end, offset, true)
}
CodeBlockKind::Indented => {
if offset.end > offset.start && md.get(offset.end..=offset.end) == Some("\n") {
(
LangString::default(),
offset.start,
offset.end,
Range { start: offset.start, end: offset.end - 1 },
false,
)
} else {
(LangString::default(), offset.start, offset.end, offset, false)
}
}
};
code_blocks.push(RustCodeBlock {
is_fenced,
range,
code: Range { start: code_start, end: code_end },
lang_string,
});
}
}
code_blocks
}
#[derive(Clone, Default, Debug)]
pub struct IdMap {
map: FxHashMap<String, usize>,
existing_footnotes: usize,
}
fn is_default_id(id: &str) -> bool {
matches!(
id,
"help"
| "settings"
| "not-displayed"
| "alternative-display"
| "search"
| "crate-search"
| "crate-search-div"
| "themeStyle"
| "settings-menu"
| "help-button"
| "sidebar-button"
| "main-content"
| "toggle-all-docs"
| "all-types"
| "default-settings"
| "sidebar-vars"
| "copy-path"
| "rustdoc-toc"
| "rustdoc-modnav"
| "fields"
| "variants"
| "implementors-list"
| "synthetic-implementors-list"
| "foreign-impls"
| "implementations"
| "trait-implementations"
| "synthetic-implementations"
| "blanket-implementations"
| "required-associated-types"
| "provided-associated-types"
| "provided-associated-consts"
| "required-associated-consts"
| "required-methods"
| "provided-methods"
| "dyn-compatibility"
| "implementors"
| "synthetic-implementors"
| "implementations-list"
| "trait-implementations-list"
| "synthetic-implementations-list"
| "blanket-implementations-list"
| "deref-methods"
| "layout"
| "aliased-type"
)
}
impl IdMap {
pub fn new() -> Self {
IdMap { map: FxHashMap::default(), existing_footnotes: 0 }
}
pub(crate) fn derive<S: AsRef<str> + ToString>(&mut self, candidate: S) -> String {
let id = match self.map.get_mut(candidate.as_ref()) {
None => {
let candidate = candidate.to_string();
if is_default_id(&candidate) {
let id = format!("{}-{}", candidate, 1);
self.map.insert(candidate.into(), 2);
id
} else {
candidate
}
}
Some(a) => {
let id = format!("{}-{}", candidate.as_ref(), *a);
*a += 1;
id
}
};
self.map.insert(id.clone().into(), 1);
id
}
pub(crate) fn handle_footnotes<F: FnOnce(&mut Self, &mut usize)>(&mut self, closure: F) {
let mut existing_footnotes = self.existing_footnotes;
closure(self, &mut existing_footnotes);
self.existing_footnotes = existing_footnotes;
}
pub(crate) fn clear(&mut self) {
self.map.clear();
self.existing_footnotes = 0;
}
}