Skip to content

Refactor rendering with RenderCtx #1796

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 17, 2025
Merged

Refactor rendering with RenderCtx #1796

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 15 additions & 20 deletions mdbook-spec/src/grammar.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,13 @@ enum Characters {
Range(char, char),
}

#[derive(Debug)]
pub struct RenderCtx {
md_link_map: HashMap<String, String>,
rr_link_map: HashMap<String, String>,
for_summary: bool,
}

impl Grammar {
fn visit_nt(&self, callback: &mut dyn FnMut(&str)) {
for p in self.productions.values() {
Expand Down Expand Up @@ -301,7 +308,7 @@ fn render_names(
output.push_str("<br>\n");

// Convert the link map to add the id.
let updated_link_map = |get_id: fn(&str, bool) -> String| -> HashMap<String, String> {
let update_link_map = |get_id: fn(&str, bool) -> String| -> HashMap<String, String> {
link_map
.iter()
.map(|(name, path)| {
Expand All @@ -316,19 +323,13 @@ fn render_names(
.collect()
};

let markdown_link_map = updated_link_map(render_markdown::markdown_id);
// Modify the link map so that it contains the exact destination needed to
// link to the railroad productions, and to accommodate the summary
// chapter.
let railroad_link_map = updated_link_map(render_railroad::railroad_id);

if let Err(e) = grammar.render_markdown(
&names,
&markdown_link_map,
&railroad_link_map,
&mut output,
let render_ctx = RenderCtx {
md_link_map: update_link_map(render_markdown::markdown_id),
rr_link_map: update_link_map(render_railroad::railroad_id),
for_summary,
) {
};

if let Err(e) = grammar.render_markdown(&render_ctx, &names, &mut output) {
warn_or_err!(
diag,
"grammar failed in chapter {:?}: {e}",
Expand All @@ -348,13 +349,7 @@ fn render_names(
\n",
);

if let Err(e) = grammar.render_railroad(
&names,
&railroad_link_map,
&markdown_link_map,
&mut output,
for_summary,
) {
if let Err(e) = grammar.render_railroad(&render_ctx, &names, &mut output) {
warn_or_err!(
diag,
"grammar failed in chapter {:?}: {e}",
Expand Down
70 changes: 26 additions & 44 deletions mdbook-spec/src/grammar/render_markdown.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,26 @@
//! Renders the grammar to markdown.

use super::{Characters, Expression, ExpressionKind, Production};
use super::{Characters, Expression, ExpressionKind, Production, RenderCtx};
use crate::grammar::Grammar;
use anyhow::bail;
use regex::Regex;
use std::borrow::Cow;
use std::collections::HashMap;
use std::fmt::Write;
use std::sync::LazyLock;

impl Grammar {
pub fn render_markdown(
&self,
cx: &RenderCtx,
names: &[&str],
link_map: &HashMap<String, String>,
rr_link_map: &HashMap<String, String>,
output: &mut String,
for_summary: bool,
) -> anyhow::Result<()> {
let mut iter = names.into_iter().peekable();
while let Some(name) = iter.next() {
let Some(prod) = self.productions.get(*name) else {
bail!("could not find grammar production named `{name}`");
};
prod.render_markdown(link_map, rr_link_map, output, for_summary);
prod.render_markdown(cx, output);
if iter.peek().is_some() {
output.push_str("\n");
}
Expand All @@ -42,14 +39,9 @@ pub fn markdown_id(name: &str, for_summary: bool) -> String {
}

impl Production {
fn render_markdown(
&self,
link_map: &HashMap<String, String>,
rr_link_map: &HashMap<String, String>,
output: &mut String,
for_summary: bool,
) {
let dest = rr_link_map
fn render_markdown(&self, cx: &RenderCtx, output: &mut String) {
let dest = cx
.rr_link_map
.get(&self.name)
.map(|path| path.to_string())
.unwrap_or_else(|| format!("missing"));
Expand All @@ -60,12 +52,11 @@ impl Production {
>\
[{name}]({dest})\
</span> → ",
id = markdown_id(&self.name, for_summary),
id = markdown_id(&self.name, cx.for_summary),
name = self.name,
)
.unwrap();
self.expression
.render_markdown(link_map, output, for_summary);
self.expression.render_markdown(cx, output);
output.push('\n');
}
}
Expand All @@ -92,16 +83,11 @@ impl Expression {
}
}

fn render_markdown(
&self,
link_map: &HashMap<String, String>,
output: &mut String,
for_summary: bool,
) {
fn render_markdown(&self, cx: &RenderCtx, output: &mut String) {
match &self.kind {
ExpressionKind::Grouped(e) => {
output.push_str("( ");
e.render_markdown(link_map, output, for_summary);
e.render_markdown(cx, output);
if !matches!(e.last(), ExpressionKind::Break(_)) {
output.push(' ');
}
Expand All @@ -110,7 +96,7 @@ impl Expression {
ExpressionKind::Alt(es) => {
let mut iter = es.iter().peekable();
while let Some(e) = iter.next() {
e.render_markdown(link_map, output, for_summary);
e.render_markdown(cx, output);
if iter.peek().is_some() {
if !matches!(e.last(), ExpressionKind::Break(_)) {
output.push(' ');
Expand All @@ -122,34 +108,34 @@ impl Expression {
ExpressionKind::Sequence(es) => {
let mut iter = es.iter().peekable();
while let Some(e) = iter.next() {
e.render_markdown(link_map, output, for_summary);
e.render_markdown(cx, output);
if iter.peek().is_some() && !matches!(e.last(), ExpressionKind::Break(_)) {
output.push(' ');
}
}
}
ExpressionKind::Optional(e) => {
e.render_markdown(link_map, output, for_summary);
e.render_markdown(cx, output);
output.push_str("<sup>?</sup>");
}
ExpressionKind::Repeat(e) => {
e.render_markdown(link_map, output, for_summary);
e.render_markdown(cx, output);
output.push_str("<sup>\\*</sup>");
}
ExpressionKind::RepeatNonGreedy(e) => {
e.render_markdown(link_map, output, for_summary);
e.render_markdown(cx, output);
output.push_str("<sup>\\* (non-greedy)</sup>");
}
ExpressionKind::RepeatPlus(e) => {
e.render_markdown(link_map, output, for_summary);
e.render_markdown(cx, output);
output.push_str("<sup>+</sup>");
}
ExpressionKind::RepeatPlusNonGreedy(e) => {
e.render_markdown(link_map, output, for_summary);
e.render_markdown(cx, output);
output.push_str("<sup>+ (non-greedy)</sup>");
}
ExpressionKind::RepeatRange(e, a, b) => {
e.render_markdown(link_map, output, for_summary);
e.render_markdown(cx, output);
write!(
output,
"<sup>{}..{}</sup>",
Expand All @@ -159,7 +145,7 @@ impl Expression {
.unwrap();
}
ExpressionKind::Nt(nt) => {
let dest = link_map.get(nt).map_or("missing", |d| d.as_str());
let dest = cx.md_link_map.get(nt).map_or("missing", |d| d.as_str());
write!(output, "<span class=\"grammar-text\">[{nt}]({dest})</span>").unwrap();
}
ExpressionKind::Terminal(t) => {
Expand All @@ -177,10 +163,10 @@ impl Expression {
output.push_str("\\\n");
output.push_str(&"&nbsp;".repeat(*indent));
}
ExpressionKind::Charset(set) => charset_render_markdown(set, link_map, output),
ExpressionKind::Charset(set) => charset_render_markdown(cx, set, output),
ExpressionKind::NegExpression(e) => {
output.push('~');
e.render_markdown(link_map, output, for_summary);
e.render_markdown(cx, output);
}
ExpressionKind::Unicode(s) => {
output.push_str("U+");
Expand All @@ -190,7 +176,7 @@ impl Expression {
if let Some(suffix) = &self.suffix {
write!(output, "<sub class=\"grammar-text\">{suffix}</sub>").unwrap();
}
if !for_summary {
if !cx.for_summary {
if let Some(footnote) = &self.footnote {
// The `ZeroWidthSpace` is to avoid conflicts with markdown link
// references.
Expand All @@ -200,15 +186,11 @@ impl Expression {
}
}

fn charset_render_markdown(
set: &[Characters],
link_map: &HashMap<String, String>,
output: &mut String,
) {
fn charset_render_markdown(cx: &RenderCtx, set: &[Characters], output: &mut String) {
output.push_str("\\[");
let mut iter = set.iter().peekable();
while let Some(chars) = iter.next() {
chars.render_markdown(link_map, output);
chars.render_markdown(cx, output);
if iter.peek().is_some() {
output.push(' ');
}
Expand All @@ -217,10 +199,10 @@ fn charset_render_markdown(
}

impl Characters {
fn render_markdown(&self, link_map: &HashMap<String, String>, output: &mut String) {
fn render_markdown(&self, cx: &RenderCtx, output: &mut String) {
match self {
Characters::Named(s) => {
let dest = link_map.get(s).map_or("missing", |d| d.as_str());
let dest = cx.md_link_map.get(s).map_or("missing", |d| d.as_str());
write!(output, "[{s}]({dest})").unwrap();
}
Characters::Terminal(s) => write!(
Expand Down
Loading