1use rowan::ast::AstNode;
4use rowan::{TextRange, TextSize};
5
6use super::syntax::{DocumentationLanguage, SyntaxKind, SyntaxNode, SyntaxToken};
7
8macro_rules! ast_node {
9 ($name:ident, $($kind:path)|+) => {
10 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
11 pub struct $name(SyntaxNode);
12
13 impl AstNode for $name {
14 type Language = DocumentationLanguage;
15
16 fn can_cast(kind: SyntaxKind) -> bool {
17 matches!(kind, $($kind)|+)
18 }
19
20 fn cast(syntax: SyntaxNode) -> Option<Self> {
21 Self::can_cast(syntax.kind()).then_some(Self(syntax))
22 }
23
24 fn syntax(&self) -> &SyntaxNode {
25 &self.0
26 }
27 }
28 };
29}
30
31ast_node!(Document, SyntaxKind::ROOT);
32ast_node!(Paragraph, SyntaxKind::PARAGRAPH);
33ast_node!(
34 Heading,
35 SyntaxKind::ATX_HEADING | SyntaxKind::SETEXT_HEADING
36);
37ast_node!(BlockQuote, SyntaxKind::BLOCK_QUOTE);
38ast_node!(Admonition, SyntaxKind::ADMONITION);
39ast_node!(List, SyntaxKind::LIST);
40ast_node!(ListItem, SyntaxKind::LIST_ITEM);
41ast_node!(IndentedCodeBlock, SyntaxKind::INDENTED_CODE_BLOCK);
42ast_node!(CodeBlock, SyntaxKind::FENCED_CODE_BLOCK);
43ast_node!(MathBlock, SyntaxKind::MATH_BLOCK);
44ast_node!(FootnoteDefinition, SyntaxKind::FOOTNOTE_DEFINITION);
45ast_node!(Table, SyntaxKind::TABLE);
46ast_node!(TableRow, SyntaxKind::TABLE_ROW);
47ast_node!(TableCell, SyntaxKind::TABLE_CELL);
48ast_node!(ThematicBreak, SyntaxKind::THEMATIC_BREAK);
49ast_node!(Emphasis, SyntaxKind::EMPHASIS);
50ast_node!(Strong, SyntaxKind::STRONG);
51ast_node!(InlineCode, SyntaxKind::INLINE_CODE);
52ast_node!(InlineMath, SyntaxKind::INLINE_MATH);
53ast_node!(Link, SyntaxKind::LINK);
54ast_node!(Image, SyntaxKind::IMAGE);
55ast_node!(Autolink, SyntaxKind::AUTOLINK);
56ast_node!(FootnoteReference, SyntaxKind::FOOTNOTE_REFERENCE);
57ast_node!(Interpolation, SyntaxKind::INTERPOLATION);
58ast_node!(HardBreak, SyntaxKind::HARD_BREAK);
59
60#[derive(Debug, Clone, PartialEq, Eq, Hash)]
62pub enum Block {
63 Paragraph(Paragraph),
64 Heading(Heading),
65 BlockQuote(BlockQuote),
66 Admonition(Admonition),
67 List(List),
68 IndentedCodeBlock(IndentedCodeBlock),
69 CodeBlock(CodeBlock),
70 MathBlock(MathBlock),
71 FootnoteDefinition(FootnoteDefinition),
72 Table(Table),
73 ThematicBreak(ThematicBreak),
74 Interpolation(Interpolation),
75 Other(SyntaxNode),
77}
78
79impl Block {
80 fn cast(syntax: SyntaxNode) -> Self {
81 match syntax.kind() {
82 SyntaxKind::PARAGRAPH => Self::Paragraph(Paragraph(syntax)),
83 SyntaxKind::ATX_HEADING | SyntaxKind::SETEXT_HEADING => Self::Heading(Heading(syntax)),
84 SyntaxKind::BLOCK_QUOTE => Self::BlockQuote(BlockQuote(syntax)),
85 SyntaxKind::ADMONITION => Self::Admonition(Admonition(syntax)),
86 SyntaxKind::LIST => Self::List(List(syntax)),
87 SyntaxKind::INDENTED_CODE_BLOCK => Self::IndentedCodeBlock(IndentedCodeBlock(syntax)),
88 SyntaxKind::FENCED_CODE_BLOCK => Self::CodeBlock(CodeBlock(syntax)),
89 SyntaxKind::MATH_BLOCK => Self::MathBlock(MathBlock(syntax)),
90 SyntaxKind::FOOTNOTE_DEFINITION => Self::FootnoteDefinition(FootnoteDefinition(syntax)),
91 SyntaxKind::TABLE => Self::Table(Table(syntax)),
92 SyntaxKind::THEMATIC_BREAK => Self::ThematicBreak(ThematicBreak(syntax)),
93 SyntaxKind::INTERPOLATION => Self::Interpolation(Interpolation(syntax)),
94 _ => Self::Other(syntax),
95 }
96 }
97
98 pub fn syntax(&self) -> &SyntaxNode {
100 match self {
101 Self::Paragraph(node) => node.syntax(),
102 Self::Heading(node) => node.syntax(),
103 Self::BlockQuote(node) => node.syntax(),
104 Self::Admonition(node) => node.syntax(),
105 Self::List(node) => node.syntax(),
106 Self::IndentedCodeBlock(node) => node.syntax(),
107 Self::CodeBlock(node) => node.syntax(),
108 Self::MathBlock(node) => node.syntax(),
109 Self::FootnoteDefinition(node) => node.syntax(),
110 Self::Table(node) => node.syntax(),
111 Self::ThematicBreak(node) => node.syntax(),
112 Self::Interpolation(node) => node.syntax(),
113 Self::Other(node) => node,
114 }
115 }
116}
117
118impl Document {
119 pub fn blocks(&self) -> impl Iterator<Item = Block> + '_ {
121 self.syntax().children().map(Block::cast)
122 }
123}
124
125#[derive(Debug, Clone, PartialEq, Eq, Hash)]
127pub enum Inline {
128 Text(SyntaxToken),
129 Escape(SyntaxToken),
130 EnDash(SyntaxToken),
132 EmDash(SyntaxToken),
134 SoftBreak(SyntaxToken),
135 Emphasis(Emphasis),
136 Strong(Strong),
137 Code(InlineCode),
138 Math(InlineMath),
139 Link(Link),
140 Image(Image),
141 Autolink(Autolink),
142 FootnoteReference(FootnoteReference),
143 Interpolation(Interpolation),
144 HardBreak(HardBreak),
145}
146
147impl Paragraph {
148 pub fn inlines(&self) -> impl Iterator<Item = Inline> + '_ {
150 inline_children(self.syntax())
151 }
152}
153
154impl BlockQuote {
155 pub fn blocks(&self) -> impl Iterator<Item = Block> + '_ {
157 self.syntax().children().map(Block::cast)
158 }
159}
160
161impl Heading {
162 pub fn level(&self) -> u8 {
164 let marker = token(self.syntax(), SyntaxKind::HEADING_MARKER)
165 .map(|token| token.text().to_string())
166 .unwrap_or_default();
167 if self.syntax().kind() == SyntaxKind::SETEXT_HEADING {
168 if marker.trim_start().starts_with('=') {
169 1
170 } else {
171 2
172 }
173 } else {
174 marker.bytes().filter(|&byte| byte == b'#').count() as u8
175 }
176 }
177
178 pub fn content(&self) -> String {
180 visible_text(self.syntax())
181 }
182
183 pub fn inlines(&self) -> impl Iterator<Item = Inline> + '_ {
185 inline_children(self.syntax())
186 }
187
188 pub fn slug(&self) -> String {
194 slug(&self.content())
195 }
196}
197
198pub fn slug(heading: &str) -> String {
200 let mut out = String::new();
201 let mut separator = false;
202 for character in heading.chars().flat_map(char::to_lowercase) {
203 if character.is_alphanumeric() || character == '_' || character == '-' {
204 if separator && !out.is_empty() && !out.ends_with('-') {
205 out.push('-');
206 }
207 out.push(character);
208 separator = false;
209 } else if character.is_whitespace() {
210 separator = true;
211 }
212 }
213 out.trim_end_matches('-').to_string()
214}
215
216impl Admonition {
217 pub fn category(&self) -> String {
219 token(self.syntax(), SyntaxKind::ADMONITION_CATEGORY)
220 .map(|token| token.text().to_string())
221 .unwrap_or_default()
222 }
223
224 pub fn title(&self) -> String {
226 token(self.syntax(), SyntaxKind::ADMONITION_TITLE).map_or_else(
227 || uppercase_first(&self.category()),
228 |token| token.text().trim_matches('"').to_string(),
229 )
230 }
231
232 pub fn blocks(&self) -> impl Iterator<Item = Block> + '_ {
234 self.syntax().children().map(Block::cast)
235 }
236}
237
238impl List {
239 pub fn items(&self) -> impl Iterator<Item = ListItem> + '_ {
241 self.syntax().children().filter_map(ListItem::cast)
242 }
243
244 pub fn ordered_start(&self) -> Option<u64> {
246 nested_token(self.syntax(), SyntaxKind::LIST_MARKER)?
247 .text()
248 .trim_end_matches(['.', ')'])
249 .parse()
250 .ok()
251 }
252
253 pub fn is_loose(&self) -> bool {
255 self.syntax()
256 .descendants_with_tokens()
257 .filter_map(|element| element.into_token())
258 .any(|token| token.kind() == SyntaxKind::BLANK_LINE)
259 }
260}
261
262impl ListItem {
263 pub fn inlines(&self) -> impl Iterator<Item = Inline> + '_ {
265 inline_children(self.syntax())
266 }
267
268 pub fn blocks(&self) -> impl Iterator<Item = Block> + '_ {
270 self.syntax().children().map(Block::cast)
271 }
272}
273
274impl CodeBlock {
275 pub fn info(&self) -> String {
277 token(self.syntax(), SyntaxKind::INFO_STRING)
278 .map(|token| token.text().trim().to_string())
279 .unwrap_or_default()
280 }
281
282 pub fn content(&self) -> String {
284 token(self.syntax(), SyntaxKind::CODE_CONTENT)
285 .map(|token| token.text().trim_end_matches(['\r', '\n']).to_string())
286 .unwrap_or_default()
287 }
288
289 pub fn content_range(&self) -> Option<TextRange> {
291 token(self.syntax(), SyntaxKind::CODE_CONTENT).map(|token| token.text_range())
292 }
293
294 pub fn fence_kind(&self) -> FenceKind {
296 classify_fence(&self.info())
297 }
298}
299
300impl IndentedCodeBlock {
301 pub fn content(&self) -> String {
303 let mut out = String::new();
304 for token in self
305 .syntax()
306 .descendants_with_tokens()
307 .filter_map(|element| element.into_token())
308 {
309 if matches!(token.kind(), SyntaxKind::CODE_CONTENT | SyntaxKind::NEWLINE) {
310 out.push_str(token.text());
311 }
312 }
313 out.trim_end_matches(['\r', '\n']).to_string()
314 }
315}
316
317impl MathBlock {
318 pub fn content(&self) -> String {
320 token(self.syntax(), SyntaxKind::MATH_CONTENT)
321 .map(|token| token.text().trim_end_matches(['\r', '\n']).to_string())
322 .unwrap_or_default()
323 }
324}
325
326impl FootnoteDefinition {
327 pub fn id(&self) -> String {
329 token(self.syntax(), SyntaxKind::FOOTNOTE_LABEL)
330 .map(|token| {
331 token
332 .text()
333 .strip_prefix("[^")
334 .and_then(|text| text.strip_suffix("]:"))
335 .unwrap_or(token.text())
336 .to_string()
337 })
338 .unwrap_or_default()
339 }
340
341 pub fn blocks(&self) -> impl Iterator<Item = Block> + '_ {
343 self.syntax().children().map(Block::cast)
344 }
345}
346
347impl Table {
348 pub fn rows(&self) -> impl Iterator<Item = TableRow> + '_ {
350 self.syntax().children().filter_map(TableRow::cast)
351 }
352}
353
354impl TableRow {
355 pub fn cells(&self) -> impl Iterator<Item = TableCell> + '_ {
357 self.syntax().children().filter_map(TableCell::cast)
358 }
359}
360
361impl TableCell {
362 pub fn inlines(&self) -> impl Iterator<Item = Inline> + '_ {
364 inline_children(self.syntax())
365 }
366}
367
368impl InlineCode {
369 pub fn content(&self) -> String {
371 inline_payload(self.syntax(), SyntaxKind::CODE_CONTENT)
372 }
373}
374
375impl InlineMath {
376 pub fn content(&self) -> String {
378 inline_payload(self.syntax(), SyntaxKind::MATH_CONTENT)
379 }
380}
381
382impl Link {
383 pub fn destination(&self) -> String {
385 token(self.syntax(), SyntaxKind::LINK_DESTINATION)
386 .map(|token| token.text().to_string())
387 .unwrap_or_default()
388 }
389
390 pub fn destination_range(&self) -> Option<TextRange> {
392 token(self.syntax(), SyntaxKind::LINK_DESTINATION).map(|token| token.text_range())
393 }
394
395 pub fn label(&self) -> impl Iterator<Item = Inline> + '_ {
397 inline_children(self.syntax())
398 }
399}
400
401impl Image {
402 pub fn alt(&self) -> String {
404 token(self.syntax(), SyntaxKind::TEXT)
405 .map(|token| token.text().to_string())
406 .unwrap_or_default()
407 }
408
409 pub fn destination(&self) -> String {
411 token(self.syntax(), SyntaxKind::LINK_DESTINATION)
412 .map(|token| token.text().to_string())
413 .unwrap_or_default()
414 }
415}
416
417impl Autolink {
418 pub fn destination(&self) -> String {
420 token(self.syntax(), SyntaxKind::LINK_DESTINATION)
421 .map(|token| token.text().to_string())
422 .unwrap_or_default()
423 }
424}
425
426impl FootnoteReference {
427 pub fn id(&self) -> String {
429 token(self.syntax(), SyntaxKind::FOOTNOTE_LABEL)
430 .map(|token| {
431 token
432 .text()
433 .strip_prefix("[^")
434 .and_then(|text| text.strip_suffix(']'))
435 .unwrap_or(token.text())
436 .to_string()
437 })
438 .unwrap_or_default()
439 }
440}
441
442impl Interpolation {
443 pub fn expression(&self) -> String {
445 token(self.syntax(), SyntaxKind::TEXT)
446 .map(|token| token.text().to_string())
447 .unwrap_or_default()
448 }
449}
450
451#[derive(Debug, Clone, PartialEq, Eq)]
453pub enum FenceKind {
454 Plain,
455 Julia,
456 JuliaRepl,
457 JlDoctest {
458 label: Option<String>,
459 options: Option<String>,
460 },
461 Documenter {
462 directive: DocumenterDirective,
463 arguments: Option<String>,
464 },
465 DocumenterExtension {
466 directive: String,
467 arguments: Option<String>,
468 },
469 Other(String),
470}
471
472impl FenceKind {
473 pub fn contains_julia(&self) -> bool {
475 match self {
476 Self::Julia | Self::JuliaRepl | Self::JlDoctest { .. } => true,
477 Self::Documenter { directive, .. } => !matches!(directive, DocumenterDirective::Raw),
478 Self::Plain | Self::DocumenterExtension { .. } | Self::Other(_) => false,
479 }
480 }
481}
482
483#[derive(Debug, Clone, Copy, PartialEq, Eq)]
485pub enum DocumenterDirective {
486 Docs,
487 Autodocs,
488 Meta,
489 Index,
490 Contents,
491 Example,
492 Repl,
493 Setup,
494 Eval,
495 Raw,
496}
497
498impl Link {
499 pub fn documenter_link(&self) -> Option<DocumenterLink> {
501 let destination = token(self.syntax(), SyntaxKind::LINK_DESTINATION)?;
502 destination
503 .text()
504 .trim_start()
505 .starts_with('@')
506 .then_some(DocumenterLink { destination })
507 }
508}
509
510#[derive(Debug, Clone, PartialEq, Eq, Hash)]
512pub struct DocumenterLink {
513 destination: SyntaxToken,
514}
515
516impl DocumenterLink {
517 pub fn kind(&self) -> DocumenterLinkKind<'_> {
519 let (name, _) = split_at_word(self.destination.text().trim());
520 match name {
521 "@ref" => DocumenterLinkKind::Ref,
522 "@id" => DocumenterLinkKind::Id,
523 other => DocumenterLinkKind::Extension(other.trim_start_matches('@')),
524 }
525 }
526
527 pub fn target(&self) -> Option<&str> {
529 let (_, rest) = split_at_word(self.destination.text().trim());
530 (!rest.is_empty()).then_some(rest)
531 }
532
533 pub fn target_range(&self) -> Option<TextRange> {
535 let raw = self.destination.text();
536 let trimmed_start = raw.len() - raw.trim_start().len();
537 let trimmed = raw.trim();
538 let name_end = trimmed.find(char::is_whitespace)?;
539 let target_start =
540 name_end + trimmed[name_end..].len() - trimmed[name_end..].trim_start().len();
541 if target_start >= trimmed.len() {
542 return None;
543 }
544 let target_end = trimmed.trim_end().len();
545 let base: u32 = self.destination.text_range().start().into();
546 Some(TextRange::new(
547 TextSize::from(base + (trimmed_start + target_start) as u32),
548 TextSize::from(base + (trimmed_start + target_end) as u32),
549 ))
550 }
551}
552
553#[derive(Debug, Clone, Copy, PartialEq, Eq)]
555pub enum DocumenterLinkKind<'a> {
556 Ref,
557 Id,
558 Extension(&'a str),
559}
560
561fn classify_fence(info: &str) -> FenceKind {
562 if info.is_empty() {
563 return FenceKind::Plain;
564 }
565 if info == "julia" {
566 return FenceKind::Julia;
567 }
568 if info == "julia-repl" {
569 return FenceKind::JuliaRepl;
570 }
571 if info == "jldoctest"
572 || info
573 .strip_prefix("jldoctest")
574 .is_some_and(|rest| rest.starts_with(|ch: char| ch.is_whitespace() || ch == ';'))
575 {
576 let rest = info.strip_prefix("jldoctest").unwrap().trim();
577 let (label, options) = split_label_options(rest);
578 return FenceKind::JlDoctest {
579 label: nonempty(label),
580 options: nonempty(options),
581 };
582 }
583 if let Some(at) = info.strip_prefix('@') {
584 let name_end = at
585 .find(|ch: char| ch.is_whitespace() || ch == ';')
586 .unwrap_or(at.len());
587 let name = &at[..name_end];
588 let arguments = nonempty(at[name_end..].trim().trim_start_matches(';').trim());
589 let directive = match name {
590 "docs" => Some(DocumenterDirective::Docs),
591 "autodocs" => Some(DocumenterDirective::Autodocs),
592 "meta" => Some(DocumenterDirective::Meta),
593 "index" => Some(DocumenterDirective::Index),
594 "contents" => Some(DocumenterDirective::Contents),
595 "example" => Some(DocumenterDirective::Example),
596 "repl" => Some(DocumenterDirective::Repl),
597 "setup" => Some(DocumenterDirective::Setup),
598 "eval" => Some(DocumenterDirective::Eval),
599 "raw" => Some(DocumenterDirective::Raw),
600 _ => None,
601 };
602 return match directive {
603 Some(directive) => FenceKind::Documenter {
604 directive,
605 arguments,
606 },
607 None => FenceKind::DocumenterExtension {
608 directive: name.to_string(),
609 arguments,
610 },
611 };
612 }
613 FenceKind::Other(info.to_string())
614}
615
616fn split_label_options(rest: &str) -> (&str, &str) {
617 match rest.split_once(';') {
618 Some((label, options)) => (label.trim(), options.trim()),
619 None => (rest.trim(), ""),
620 }
621}
622
623fn nonempty(text: &str) -> Option<String> {
624 (!text.is_empty()).then(|| text.to_string())
625}
626
627fn split_at_word(text: &str) -> (&str, &str) {
628 match text.find(char::is_whitespace) {
629 Some(index) => (&text[..index], text[index..].trim()),
630 None => (text, ""),
631 }
632}
633
634fn token(node: &SyntaxNode, kind: SyntaxKind) -> Option<SyntaxToken> {
640 node.children_with_tokens()
641 .filter_map(|element| element.into_token())
642 .find(|token| token.kind() == kind)
643}
644
645fn nested_token(node: &SyntaxNode, kind: SyntaxKind) -> Option<SyntaxToken> {
647 node.descendants_with_tokens()
648 .filter_map(|element| element.into_token())
649 .find(|token| token.kind() == kind)
650}
651
652fn visible_text(node: &SyntaxNode) -> String {
653 let mut out = String::new();
654 for token in node
655 .descendants_with_tokens()
656 .filter_map(|element| element.into_token())
657 {
658 match token.kind() {
659 SyntaxKind::TEXT | SyntaxKind::CODE_CONTENT | SyntaxKind::MATH_CONTENT => {
660 out.push_str(token.text())
661 }
662 SyntaxKind::ESCAPE => out.push_str(token.text().trim_start_matches('\\')),
663 SyntaxKind::EN_DASH => out.push('–'),
664 SyntaxKind::EM_DASH => out.push('—'),
665 SyntaxKind::SOFT_BREAK => out.push(' '),
666 _ => {}
667 }
668 }
669 out.trim().to_string()
670}
671
672fn inline_children(node: &SyntaxNode) -> impl Iterator<Item = Inline> + '_ {
673 node.children_with_tokens()
674 .filter_map(|element| match element {
675 rowan::NodeOrToken::Token(token) => match token.kind() {
676 SyntaxKind::TEXT => Some(Inline::Text(token)),
677 SyntaxKind::ESCAPE => Some(Inline::Escape(token)),
678 SyntaxKind::EN_DASH => Some(Inline::EnDash(token)),
679 SyntaxKind::EM_DASH => Some(Inline::EmDash(token)),
680 SyntaxKind::SOFT_BREAK => Some(Inline::SoftBreak(token)),
681 _ => None,
682 },
683 rowan::NodeOrToken::Node(node) => match node.kind() {
684 SyntaxKind::EMPHASIS => Some(Inline::Emphasis(Emphasis(node))),
685 SyntaxKind::STRONG => Some(Inline::Strong(Strong(node))),
686 SyntaxKind::INLINE_CODE => Some(Inline::Code(InlineCode(node))),
687 SyntaxKind::INLINE_MATH => Some(Inline::Math(InlineMath(node))),
688 SyntaxKind::LINK => Some(Inline::Link(Link(node))),
689 SyntaxKind::IMAGE => Some(Inline::Image(Image(node))),
690 SyntaxKind::AUTOLINK => Some(Inline::Autolink(Autolink(node))),
691 SyntaxKind::FOOTNOTE_REFERENCE => {
692 Some(Inline::FootnoteReference(FootnoteReference(node)))
693 }
694 SyntaxKind::INTERPOLATION => Some(Inline::Interpolation(Interpolation(node))),
695 SyntaxKind::HARD_BREAK => Some(Inline::HardBreak(HardBreak(node))),
696 _ => None,
697 },
698 })
699}
700
701fn inline_payload(node: &SyntaxNode, kind: SyntaxKind) -> String {
702 token(node, kind)
703 .map(|token| token.text().trim().to_string())
704 .unwrap_or_default()
705}
706
707fn uppercase_first(text: &str) -> String {
708 let mut chars = text.chars();
709 chars
710 .next()
711 .map(char::to_uppercase)
712 .into_iter()
713 .flatten()
714 .collect::<String>()
715 + chars.as_str()
716}