simplify link transformation

Remove `LinkTransform::Reference`, replacing it with
`LinkTransform::NeverInline`. This keeps collapsed and shortcut links as
they were (unlike `Reference`, which replaced them with `[full
references][1]`).

Additionally, collapsed and shortcut links whose display text is just a
number (e.g. `[1][]` or `[2]`) will now reserve that number, rather than
having it be renumbered as a full-style link. Otherwise, the link
transformer would change something like `[3]` to `[3][1]` (if that
shortcut `[3]` link happened to be the first link in the document),
which would result in confusing markdown. Full-style links like `[some
text][4]` will still be renumbered.

This simplifies link transformation, and also provides for a nicer user
experience. Resolves #390.

## Breaking changes

- `LinkTransform::Reference` has been removed

Author: yshavit

src/md_elem/tree.rs

@@ -47,12 +47,24 @@ impl MdContext {
         self.footnotes.get(footnote_id).unwrap_or(&self.empty_md_elems)
     }
 
+    /// Creates a new MdContext with a default guess as to allocations and
     fn new() -> Self {
         Self {
             footnotes: HashMap::with_capacity(4), // total guess
             empty_md_elems: Vec::new(),
         }
     }
+
+    /// Creates an empty context, which will not allocate.
+    ///
+    /// This is intentionally not a `Default::default()`, because I want to make it explicit that it is a non-allocating
+    /// function.
+    pub(crate) fn empty() -> Self {
+        Self {
+            footnotes: HashMap::with_capacity(0),
+            empty_md_elems: Vec::new(),
+        }
+    }
 }
 
 /// A fully parsed Markdown document.
@@ -1987,13 +1999,6 @@ mod tests {
     use crate::util::utils_for_test::*;
 
     impl MdContext {
-        pub(crate) fn empty() -> Self {
-            Self {
-                footnotes: Default::default(),
-                empty_md_elems: vec![],
-            }
-        }
-
         pub(crate) fn with<S: Into<FootnoteId>>(mut self, footnote_id: S, body: Vec<MdElem>) -> Self {
             self.footnotes.insert(footnote_id.into(), body);
             self

src/output/find_numbered_links.rs

@@ -0,0 +1,228 @@
+use crate::md_elem::elem::{FootnoteId, Inline, Link, LinkReference, StandardLink};
+use crate::md_elem::{MdContext, MdElem};
+use crate::output::{inlines_to_string, InlineElemOptions, LinkTransform, MdInlinesWriter};
+use std::collections::{BTreeSet, HashSet};
+use std::str::FromStr;
+
+/// Find all numbers that should not be used when generating `[full links][123]`.
+pub(crate) fn find_reserved_link_numbers<'md>(
+    nodes: impl IntoIterator<Item = &'md MdElem>,
+    ctx: &'md MdContext,
+) -> BTreeSet<u64> {
+    let mut finder = ReservedLinkNumbers {
+        result: BTreeSet::new(),
+        seen_footnotes: HashSet::new(),
+        ctx,
+    };
+    finder.build_from_nodes(nodes);
+    finder.result
+}
+
+struct ReservedLinkNumbers<'md> {
+    result: BTreeSet<u64>,
+    seen_footnotes: HashSet<&'md FootnoteId>,
+    ctx: &'md MdContext,
+}
+
+impl<'md> ReservedLinkNumbers<'md> {
+    fn build_from_nodes(&mut self, nodes: impl IntoIterator<Item = &'md MdElem>) {
+        for node in nodes.into_iter() {
+            match node {
+                MdElem::Doc(doc) => self.build_from_nodes(doc),
+                MdElem::BlockQuote(block) => self.build_from_nodes(&block.body),
+                MdElem::List(list) => {
+                    for li in &list.items {
+                        self.build_from_nodes(&li.item);
+                    }
+                }
+                MdElem::Section(section) => {
+                    self.build_from_inlines(&section.title);
+                    self.build_from_nodes(&section.body);
+                }
+                MdElem::Paragraph(p) => self.build_from_inlines(&p.body),
+                MdElem::Table(table) => {
+                    for row in &table.rows {
+                        for col in row {
+                            self.build_from_inlines(col);
+                        }
+                    }
+                }
+                MdElem::Inline(inline) => self.build_from_inlines(std::iter::once(inline)),
+                MdElem::ThematicBreak | MdElem::CodeBlock(_) | MdElem::FrontMatter(_) | MdElem::BlockHtml(_) => {}
+            }
+        }
+    }
+
+    fn build_from_inlines(&mut self, inline: impl IntoIterator<Item = &'md Inline>) {
+        for inline in inline.into_iter() {
+            match inline {
+                Inline::Footnote(footnote) => {
+                    if self.seen_footnotes.insert(footnote) {
+                        self.build_from_nodes(self.ctx.get_footnote(footnote));
+                    }
+                }
+                Inline::Span(span) => self.build_from_inlines(&span.children),
+                Inline::Link(link) => {
+                    match link {
+                        Link::Standard(link) => self.build_from_link(link),
+                        Link::Autolink(_) => {} // autolinks are never just numeric
+                    }
+                }
+                Inline::Image(_) | Inline::Text(_) => {}
+            }
+        }
+    }
+
+    fn build_from_link(&mut self, link: &StandardLink) {
+        match &link.link.reference {
+            LinkReference::Inline => {
+                // inline links are never numeric
+            }
+            LinkReference::Full(_) | LinkReference::Collapsed | LinkReference::Shortcut => {
+                // For full links, collapsed links, and shortcuts: if the display text is numeric, we'll reserve it.
+                // (that will prevent output like `[123][4]`, which could be confusing. Otherwise, we won't.
+                // Note that something like `[foo bar][1]` will not reserve the 1. That's because we'll be renumbering
+                // it anyway.
+                static OPTIONS: InlineElemOptions = InlineElemOptions {
+                    link_format: LinkTransform::Keep,
+                    renumber_footnotes: false,
+                };
+                // This is slightly inefficient; we could use a lighter-weight inlines writer mechanism, in principle.
+                // But this is good enough for now.
+                let empty_context = MdContext::empty();
+                let mut writer = MdInlinesWriter::new(&empty_context, OPTIONS, &[]);
+                let text = inlines_to_string(&mut writer, &link.display);
+                self.build_from_text(&text);
+            }
+        }
+    }
+
+    fn build_from_text(&mut self, text: &str) {
+        if let Ok(num) = u64::from_str(text) {
+            self.result.insert(num);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::md_elem::{MdDoc, ParseOptions};
+    use indoc::indoc;
+
+    #[test]
+    fn no_links() {
+        check_link_nums("some markdown", []);
+    }
+
+    #[test]
+    fn autolink() {
+        check_link_nums("<https://example.com>", []);
+    }
+
+    #[test]
+    fn collapsed_not_num() {
+        check_link_nums(
+            indoc! {r#"
+            [apple][]
+
+            [apple]: https://example.com"#},
+            [],
+        );
+    }
+
+    #[test]
+    fn collapsed_with_num() {
+        check_link_nums(
+            indoc! {r#"
+            [123][]
+
+            [123]: https://example.com"#},
+            [123],
+        );
+    }
+
+    #[test]
+    fn shortcut_not_num() {
+        check_link_nums(
+            indoc! {r#"
+            [apple]
+
+            [apple]: https://example.com"#},
+            [],
+        );
+    }
+
+    #[test]
+    fn shortcut_with_num() {
+        check_link_nums(
+            indoc! {r#"
+            [123]
+
+            [123]: https://example.com"#},
+            [123],
+        );
+    }
+
+    #[test]
+    fn full_not_num() {
+        check_link_nums(
+            indoc! {r#"
+            [display text][a]
+
+            [a]: https://example.com"#},
+            [],
+        );
+    }
+
+    #[test]
+    fn full_with_num() {
+        check_link_nums(
+            indoc! {r#"
+            [display text][123]
+
+            [123]: https://example.com"#},
+            [],
+        );
+    }
+
+    #[test]
+    fn full_with_num_display() {
+        check_link_nums(
+            indoc! {r#"
+            [123][a]
+
+            [456][7]
+
+            [a]: https://example.com
+            [7]: https://example.com"#},
+            [123, 456], // but not 7; that link will turn into a collapsed
+        );
+    }
+
+    #[test]
+    fn within_some_nested_items() {
+        check_link_nums(
+            indoc! {r#"
+            > Some quoting
+            >
+            > - list item including [123][] collapsed link
+
+            # Section with [456] shortcut link
+
+            Some text under it.
+
+            [123]: https://example.com/a
+            [456]: https://example.com/b
+            "#},
+            [123, 456],
+        );
+    }
+
+    /// Simple little check based on parsed markdown. This makes it not quite unit-y, but very easy to create tests.
+    fn check_link_nums<const N: usize>(md_text: &str, expected: [u64; N]) {
+        let MdDoc { roots, ctx } = MdDoc::parse(md_text, &ParseOptions::gfm()).unwrap();
+        let actual = find_reserved_link_numbers(&roots, &ctx);
+        assert_eq!(actual, expected.into());
+    }
+}

src/output/fmt_md.rs

@@ -1976,7 +1976,7 @@ pub(crate) mod tests {
         fn two_links_doc_pos_no_thematic_break() {
             let mut options = MdWriterOptions::default_for_tests();
             options.include_thematic_breaks = false;
-            options.inline_options.link_format = LinkTransform::Reference;
+            options.inline_options.link_format = LinkTransform::NeverInline;
             options.link_reference_placement = ReferencePlacement::Doc;
             check_render_refs_with(
                 options,
@@ -2011,7 +2011,7 @@ pub(crate) mod tests {
         #[test]
         fn reference_transform_smoke_test() {
             check_render_refs_with(
-                MdWriterOptions::new_with(|mdo| mdo.inline_options.link_format = LinkTransform::Reference),
+                MdWriterOptions::new_with(|mdo| mdo.inline_options.link_format = LinkTransform::NeverInline),
                 vec![link_elem(Link::Standard(StandardLink {
                     display: vec![mdq_inline!("link text")],
                     link: LinkDefinition {
@@ -2091,7 +2091,7 @@ pub(crate) mod tests {
         #[test]
         fn reference_transform_smoke_test() {
             check_render_refs_with(
-                MdWriterOptions::new_with(|mdo| mdo.inline_options.link_format = LinkTransform::Reference),
+                MdWriterOptions::new_with(|mdo| mdo.inline_options.link_format = LinkTransform::NeverInline),
                 vec![image_elem(Image {
                     alt: "alt text".to_string(),
                     link: LinkDefinition {

src/output/fmt_md_inlines.rs

@@ -1,7 +1,7 @@
 use crate::md_elem::elem::*;
 use crate::md_elem::*;
 use crate::output::footnote_transform::FootnoteTransformer;
-use crate::output::link_transform::{LinkLabel, LinkTransform, LinkTransformation, LinkTransformer};
+use crate::output::link_transform::{LinkLabel, LinkTransform, LinkTransformer};
 use crate::util::output::{Output, SimpleWrite};
 use derive_builder::Builder;
 use serde::Serialize;
@@ -80,7 +80,7 @@ impl<'md> MdInlinesWriter<'md> {
             seen_links: HashSet::with_capacity(pending_refs_capacity),
             seen_footnotes: HashSet::with_capacity(pending_refs_capacity),
             pending_references: PendingReferences::with_capacity(pending_refs_capacity),
-            link_transformer: LinkTransformer::new(options.link_format, nodes),
+            link_transformer: LinkTransformer::new(options.link_format, nodes, ctx),
             footnote_transformer: FootnoteTransformer::new(options.renumber_footnotes),
         }
     }
@@ -312,8 +312,7 @@ impl<'md> MdInlinesWriter<'md> {
 
             out.write_char(']');
 
-            let link_ref = LinkTransformation::new(self.link_transformer.transform_variant(), self, link_like)
-                .apply(&mut self.link_transformer, &link.reference);
+            let link_ref = self.link_transformer.apply(&link.reference);
             let reference_to_add = match link_ref {
                 LinkReference::Inline => {
                     out.write_char('(');