use rowan::ast::AstNode;
use rowan::{TextRange, TextSize};
use super::syntax::{DocumentationLanguage, SyntaxKind, SyntaxNode, SyntaxToken};
macro_rules! ast_node {
($name:ident, $($kind:path)|+) => {
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct $name(SyntaxNode);
impl AstNode for $name {
type Language = DocumentationLanguage;
fn can_cast(kind: SyntaxKind) -> bool {
matches!(kind, $($kind)|+)
}
fn cast(syntax: SyntaxNode) -> Option<Self> {
Self::can_cast(syntax.kind()).then_some(Self(syntax))
}
fn syntax(&self) -> &SyntaxNode {
&self.0
}
}
};
}
ast_node!(Document, SyntaxKind::ROOT);
ast_node!(Paragraph, SyntaxKind::PARAGRAPH);
ast_node!(
Heading,
SyntaxKind::ATX_HEADING | SyntaxKind::SETEXT_HEADING
);
ast_node!(BlockQuote, SyntaxKind::BLOCK_QUOTE);
ast_node!(Admonition, SyntaxKind::ADMONITION);
ast_node!(List, SyntaxKind::LIST);
ast_node!(ListItem, SyntaxKind::LIST_ITEM);
ast_node!(IndentedCodeBlock, SyntaxKind::INDENTED_CODE_BLOCK);
ast_node!(CodeBlock, SyntaxKind::FENCED_CODE_BLOCK);
ast_node!(MathBlock, SyntaxKind::MATH_BLOCK);
ast_node!(FootnoteDefinition, SyntaxKind::FOOTNOTE_DEFINITION);
ast_node!(Table, SyntaxKind::TABLE);
ast_node!(TableRow, SyntaxKind::TABLE_ROW);
ast_node!(TableCell, SyntaxKind::TABLE_CELL);
ast_node!(ThematicBreak, SyntaxKind::THEMATIC_BREAK);
ast_node!(Emphasis, SyntaxKind::EMPHASIS);
ast_node!(Strong, SyntaxKind::STRONG);
ast_node!(InlineCode, SyntaxKind::INLINE_CODE);
ast_node!(InlineMath, SyntaxKind::INLINE_MATH);
ast_node!(Link, SyntaxKind::LINK);
ast_node!(Image, SyntaxKind::IMAGE);
ast_node!(Autolink, SyntaxKind::AUTOLINK);
ast_node!(FootnoteReference, SyntaxKind::FOOTNOTE_REFERENCE);
ast_node!(Interpolation, SyntaxKind::INTERPOLATION);
ast_node!(HardBreak, SyntaxKind::HARD_BREAK);
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum Block {
Paragraph(Paragraph),
Heading(Heading),
BlockQuote(BlockQuote),
Admonition(Admonition),
List(List),
IndentedCodeBlock(IndentedCodeBlock),
CodeBlock(CodeBlock),
MathBlock(MathBlock),
FootnoteDefinition(FootnoteDefinition),
Table(Table),
ThematicBreak(ThematicBreak),
Interpolation(Interpolation),
Other(SyntaxNode),
}
impl Block {
fn cast(syntax: SyntaxNode) -> Self {
match syntax.kind() {
SyntaxKind::PARAGRAPH => Self::Paragraph(Paragraph(syntax)),
SyntaxKind::ATX_HEADING | SyntaxKind::SETEXT_HEADING => Self::Heading(Heading(syntax)),
SyntaxKind::BLOCK_QUOTE => Self::BlockQuote(BlockQuote(syntax)),
SyntaxKind::ADMONITION => Self::Admonition(Admonition(syntax)),
SyntaxKind::LIST => Self::List(List(syntax)),
SyntaxKind::INDENTED_CODE_BLOCK => Self::IndentedCodeBlock(IndentedCodeBlock(syntax)),
SyntaxKind::FENCED_CODE_BLOCK => Self::CodeBlock(CodeBlock(syntax)),
SyntaxKind::MATH_BLOCK => Self::MathBlock(MathBlock(syntax)),
SyntaxKind::FOOTNOTE_DEFINITION => Self::FootnoteDefinition(FootnoteDefinition(syntax)),
SyntaxKind::TABLE => Self::Table(Table(syntax)),
SyntaxKind::THEMATIC_BREAK => Self::ThematicBreak(ThematicBreak(syntax)),
SyntaxKind::INTERPOLATION => Self::Interpolation(Interpolation(syntax)),
_ => Self::Other(syntax),
}
}
pub fn syntax(&self) -> &SyntaxNode {
match self {
Self::Paragraph(node) => node.syntax(),
Self::Heading(node) => node.syntax(),
Self::BlockQuote(node) => node.syntax(),
Self::Admonition(node) => node.syntax(),
Self::List(node) => node.syntax(),
Self::IndentedCodeBlock(node) => node.syntax(),
Self::CodeBlock(node) => node.syntax(),
Self::MathBlock(node) => node.syntax(),
Self::FootnoteDefinition(node) => node.syntax(),
Self::Table(node) => node.syntax(),
Self::ThematicBreak(node) => node.syntax(),
Self::Interpolation(node) => node.syntax(),
Self::Other(node) => node,
}
}
}
impl Document {
pub fn blocks(&self) -> impl Iterator<Item = Block> + '_ {
self.syntax().children().map(Block::cast)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum Inline {
Text(SyntaxToken),
Escape(SyntaxToken),
EnDash(SyntaxToken),
EmDash(SyntaxToken),
SoftBreak(SyntaxToken),
Emphasis(Emphasis),
Strong(Strong),
Code(InlineCode),
Math(InlineMath),
Link(Link),
Image(Image),
Autolink(Autolink),
FootnoteReference(FootnoteReference),
Interpolation(Interpolation),
HardBreak(HardBreak),
}
impl Paragraph {
pub fn inlines(&self) -> impl Iterator<Item = Inline> + '_ {
inline_children(self.syntax())
}
}
impl BlockQuote {
pub fn blocks(&self) -> impl Iterator<Item = Block> + '_ {
self.syntax().children().map(Block::cast)
}
}
impl Heading {
pub fn level(&self) -> u8 {
let marker = token(self.syntax(), SyntaxKind::HEADING_MARKER)
.map(|token| token.text().to_string())
.unwrap_or_default();
if self.syntax().kind() == SyntaxKind::SETEXT_HEADING {
if marker.trim_start().starts_with('=') {
1
} else {
2
}
} else {
marker.bytes().filter(|&byte| byte == b'#').count() as u8
}
}
pub fn content(&self) -> String {
visible_text(self.syntax())
}
pub fn inlines(&self) -> impl Iterator<Item = Inline> + '_ {
inline_children(self.syntax())
}
pub fn slug(&self) -> String {
slug(&self.content())
}
}
pub fn slug(heading: &str) -> String {
let mut out = String::new();
let mut separator = false;
for character in heading.chars().flat_map(char::to_lowercase) {
if character.is_alphanumeric() || character == '_' || character == '-' {
if separator && !out.is_empty() && !out.ends_with('-') {
out.push('-');
}
out.push(character);
separator = false;
} else if character.is_whitespace() {
separator = true;
}
}
out.trim_end_matches('-').to_string()
}
impl Admonition {
pub fn category(&self) -> String {
token(self.syntax(), SyntaxKind::ADMONITION_CATEGORY)
.map(|token| token.text().to_string())
.unwrap_or_default()
}
pub fn title(&self) -> String {
token(self.syntax(), SyntaxKind::ADMONITION_TITLE).map_or_else(
|| uppercase_first(&self.category()),
|token| token.text().trim_matches('"').to_string(),
)
}
pub fn blocks(&self) -> impl Iterator<Item = Block> + '_ {
self.syntax().children().map(Block::cast)
}
}
impl List {
pub fn items(&self) -> impl Iterator<Item = ListItem> + '_ {
self.syntax().children().filter_map(ListItem::cast)
}
pub fn ordered_start(&self) -> Option<u64> {
nested_token(self.syntax(), SyntaxKind::LIST_MARKER)?
.text()
.trim_end_matches(['.', ')'])
.parse()
.ok()
}
pub fn is_loose(&self) -> bool {
self.syntax()
.descendants_with_tokens()
.filter_map(|element| element.into_token())
.any(|token| token.kind() == SyntaxKind::BLANK_LINE)
}
}
impl ListItem {
pub fn inlines(&self) -> impl Iterator<Item = Inline> + '_ {
inline_children(self.syntax())
}
pub fn blocks(&self) -> impl Iterator<Item = Block> + '_ {
self.syntax().children().map(Block::cast)
}
}
impl CodeBlock {
pub fn info(&self) -> String {
token(self.syntax(), SyntaxKind::INFO_STRING)
.map(|token| token.text().trim().to_string())
.unwrap_or_default()
}
pub fn content(&self) -> String {
let mut content = String::new();
for token in self
.syntax()
.children_with_tokens()
.filter_map(|element| element.into_token())
{
if token.kind() == SyntaxKind::CODE_CONTENT {
content.push_str(token.text());
}
}
content.trim_end_matches(['\r', '\n']).to_string()
}
pub fn content_range(&self) -> Option<TextRange> {
let mut tokens = self
.syntax()
.children_with_tokens()
.filter_map(|element| element.into_token())
.filter(|token| token.kind() == SyntaxKind::CODE_CONTENT);
let first = tokens.next()?.text_range();
Some(TextRange::new(
first.start(),
tokens
.last()
.map_or(first.end(), |token| token.text_range().end()),
))
}
pub fn fence_kind(&self) -> FenceKind {
classify_fence(&self.info())
}
}
impl IndentedCodeBlock {
pub fn content(&self) -> String {
let mut out = String::new();
for token in self
.syntax()
.descendants_with_tokens()
.filter_map(|element| element.into_token())
{
if matches!(token.kind(), SyntaxKind::CODE_CONTENT | SyntaxKind::NEWLINE) {
out.push_str(token.text());
}
}
out.trim_end_matches(['\r', '\n']).to_string()
}
}
impl MathBlock {
pub fn content(&self) -> String {
let mut content = String::new();
for token in self
.syntax()
.children_with_tokens()
.filter_map(|element| element.into_token())
{
if token.kind() == SyntaxKind::MATH_CONTENT {
content.push_str(token.text());
}
}
content.trim_end_matches(['\r', '\n']).to_string()
}
}
impl FootnoteDefinition {
pub fn id(&self) -> String {
token(self.syntax(), SyntaxKind::FOOTNOTE_LABEL)
.map(|token| {
token
.text()
.strip_prefix("[^")
.and_then(|text| text.strip_suffix("]:"))
.unwrap_or(token.text())
.to_string()
})
.unwrap_or_default()
}
pub fn blocks(&self) -> impl Iterator<Item = Block> + '_ {
self.syntax().children().map(Block::cast)
}
}
impl Table {
pub fn rows(&self) -> impl Iterator<Item = TableRow> + '_ {
self.syntax().children().filter_map(TableRow::cast)
}
}
impl TableRow {
pub fn cells(&self) -> impl Iterator<Item = TableCell> + '_ {
self.syntax().children().filter_map(TableCell::cast)
}
}
impl TableCell {
pub fn inlines(&self) -> impl Iterator<Item = Inline> + '_ {
inline_children(self.syntax())
}
}
impl InlineCode {
pub fn content(&self) -> String {
inline_payload(self.syntax(), SyntaxKind::CODE_CONTENT)
}
}
impl InlineMath {
pub fn content(&self) -> String {
inline_payload(self.syntax(), SyntaxKind::MATH_CONTENT)
}
}
impl Link {
pub fn destination(&self) -> String {
payload_text(self.syntax(), SyntaxKind::LINK_DESTINATION)
}
pub fn destination_range(&self) -> Option<TextRange> {
let mut tokens = payload_tokens(self.syntax(), SyntaxKind::LINK_DESTINATION);
let first = tokens.next()?.text_range();
Some(TextRange::new(
first.start(),
tokens
.last()
.map_or(first.end(), |token| token.text_range().end()),
))
}
pub fn label(&self) -> impl Iterator<Item = Inline> + '_ {
inline_children(self.syntax())
}
}
impl Image {
pub fn alt(&self) -> String {
payload_text(self.syntax(), SyntaxKind::TEXT)
}
pub fn destination(&self) -> String {
payload_text(self.syntax(), SyntaxKind::LINK_DESTINATION)
}
}
impl Autolink {
pub fn destination(&self) -> String {
payload_text(self.syntax(), SyntaxKind::LINK_DESTINATION)
}
}
impl FootnoteReference {
pub fn id(&self) -> String {
token(self.syntax(), SyntaxKind::FOOTNOTE_LABEL)
.map(|token| {
token
.text()
.strip_prefix("[^")
.and_then(|text| text.strip_suffix(']'))
.unwrap_or(token.text())
.to_string()
})
.unwrap_or_default()
}
}
impl Interpolation {
pub fn expression(&self) -> String {
payload_text(self.syntax(), SyntaxKind::TEXT)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FenceKind {
Plain,
Julia,
JuliaRepl,
JlDoctest {
label: Option<String>,
options: Option<String>,
},
Documenter {
directive: DocumenterDirective,
arguments: Option<String>,
},
DocumenterExtension {
directive: String,
arguments: Option<String>,
},
Other(String),
}
impl FenceKind {
pub fn contains_julia(&self) -> bool {
match self {
Self::Julia | Self::JuliaRepl | Self::JlDoctest { .. } => true,
Self::Documenter { directive, .. } => !matches!(directive, DocumenterDirective::Raw),
Self::Plain | Self::DocumenterExtension { .. } | Self::Other(_) => false,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DocumenterDirective {
Docs,
Autodocs,
Meta,
Index,
Contents,
Example,
Repl,
Setup,
Eval,
Raw,
}
impl Link {
pub fn documenter_link(&self) -> Option<DocumenterLink> {
let text = self.destination();
let destination = self.syntax().clone();
text.trim_start()
.starts_with('@')
.then_some(DocumenterLink { destination, text })
}
}
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct DocumenterLink {
destination: SyntaxNode,
text: String,
}
impl DocumenterLink {
pub fn kind(&self) -> DocumenterLinkKind<'_> {
let (name, _) = split_at_word(self.text.trim());
match name {
"@ref" => DocumenterLinkKind::Ref,
"@id" => DocumenterLinkKind::Id,
other => DocumenterLinkKind::Extension(other.trim_start_matches('@')),
}
}
pub fn target(&self) -> Option<&str> {
let (_, rest) = split_at_word(self.text.trim());
(!rest.is_empty()).then_some(rest)
}
pub fn target_range(&self) -> Option<TextRange> {
let raw = &self.text;
let trimmed_start = raw.len() - raw.trim_start().len();
let trimmed = raw.trim();
let name_end = trimmed.find(char::is_whitespace)?;
let target_start =
name_end + trimmed[name_end..].len() - trimmed[name_end..].trim_start().len();
if target_start >= trimmed.len() {
return None;
}
let target_end = trimmed.trim_end().len();
payload_range(
&self.destination,
SyntaxKind::LINK_DESTINATION,
trimmed_start + target_start,
trimmed_start + target_end,
)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DocumenterLinkKind<'a> {
Ref,
Id,
Extension(&'a str),
}
fn classify_fence(info: &str) -> FenceKind {
if info.is_empty() {
return FenceKind::Plain;
}
if info == "julia" {
return FenceKind::Julia;
}
if info == "julia-repl" {
return FenceKind::JuliaRepl;
}
if info == "jldoctest"
|| info
.strip_prefix("jldoctest")
.is_some_and(|rest| rest.starts_with(|ch: char| ch.is_whitespace() || ch == ';'))
{
let rest = info.strip_prefix("jldoctest").unwrap().trim();
let (label, options) = split_label_options(rest);
return FenceKind::JlDoctest {
label: nonempty(label),
options: nonempty(options),
};
}
if let Some(at) = info.strip_prefix('@') {
let name_end = at
.find(|ch: char| ch.is_whitespace() || ch == ';')
.unwrap_or(at.len());
let name = &at[..name_end];
let arguments = nonempty(at[name_end..].trim().trim_start_matches(';').trim());
let directive = match name {
"docs" => Some(DocumenterDirective::Docs),
"autodocs" => Some(DocumenterDirective::Autodocs),
"meta" => Some(DocumenterDirective::Meta),
"index" => Some(DocumenterDirective::Index),
"contents" => Some(DocumenterDirective::Contents),
"example" => Some(DocumenterDirective::Example),
"repl" => Some(DocumenterDirective::Repl),
"setup" => Some(DocumenterDirective::Setup),
"eval" => Some(DocumenterDirective::Eval),
"raw" => Some(DocumenterDirective::Raw),
_ => None,
};
return match directive {
Some(directive) => FenceKind::Documenter {
directive,
arguments,
},
None => FenceKind::DocumenterExtension {
directive: name.to_string(),
arguments,
},
};
}
FenceKind::Other(info.to_string())
}
fn split_label_options(rest: &str) -> (&str, &str) {
match rest.split_once(';') {
Some((label, options)) => (label.trim(), options.trim()),
None => (rest.trim(), ""),
}
}
fn nonempty(text: &str) -> Option<String> {
(!text.is_empty()).then(|| text.to_string())
}
fn split_at_word(text: &str) -> (&str, &str) {
match text.find(char::is_whitespace) {
Some(index) => (&text[..index], text[index..].trim()),
None => (text, ""),
}
}
fn token(node: &SyntaxNode, kind: SyntaxKind) -> Option<SyntaxToken> {
node.children_with_tokens()
.filter_map(|element| element.into_token())
.find(|token| token.kind() == kind)
}
fn nested_token(node: &SyntaxNode, kind: SyntaxKind) -> Option<SyntaxToken> {
node.descendants_with_tokens()
.filter_map(|element| element.into_token())
.find(|token| token.kind() == kind)
}
fn visible_text(node: &SyntaxNode) -> String {
let mut out = String::new();
for token in node
.descendants_with_tokens()
.filter_map(|element| element.into_token())
{
match token.kind() {
SyntaxKind::TEXT | SyntaxKind::CODE_CONTENT | SyntaxKind::MATH_CONTENT => {
out.push_str(token.text())
}
SyntaxKind::ESCAPE => out.push_str(token.text().trim_start_matches('\\')),
SyntaxKind::EN_DASH => out.push('–'),
SyntaxKind::EM_DASH => out.push('—'),
SyntaxKind::SOFT_BREAK => out.push(' '),
_ => {}
}
}
out.trim().to_string()
}
fn inline_children(node: &SyntaxNode) -> impl Iterator<Item = Inline> + '_ {
node.children_with_tokens()
.filter_map(|element| match element {
rowan::NodeOrToken::Token(token) => match token.kind() {
SyntaxKind::TEXT => Some(Inline::Text(token)),
SyntaxKind::ESCAPE => Some(Inline::Escape(token)),
SyntaxKind::EN_DASH => Some(Inline::EnDash(token)),
SyntaxKind::EM_DASH => Some(Inline::EmDash(token)),
SyntaxKind::SOFT_BREAK => Some(Inline::SoftBreak(token)),
_ => None,
},
rowan::NodeOrToken::Node(node) => match node.kind() {
SyntaxKind::EMPHASIS => Some(Inline::Emphasis(Emphasis(node))),
SyntaxKind::STRONG => Some(Inline::Strong(Strong(node))),
SyntaxKind::INLINE_CODE => Some(Inline::Code(InlineCode(node))),
SyntaxKind::INLINE_MATH => Some(Inline::Math(InlineMath(node))),
SyntaxKind::LINK => Some(Inline::Link(Link(node))),
SyntaxKind::IMAGE => Some(Inline::Image(Image(node))),
SyntaxKind::AUTOLINK => Some(Inline::Autolink(Autolink(node))),
SyntaxKind::FOOTNOTE_REFERENCE => {
Some(Inline::FootnoteReference(FootnoteReference(node)))
}
SyntaxKind::INTERPOLATION => Some(Inline::Interpolation(Interpolation(node))),
SyntaxKind::HARD_BREAK => Some(Inline::HardBreak(HardBreak(node))),
_ => None,
},
})
}
fn inline_payload(node: &SyntaxNode, kind: SyntaxKind) -> String {
payload_text(node, kind).trim().to_string()
}
fn payload_tokens(node: &SyntaxNode, kind: SyntaxKind) -> impl Iterator<Item = SyntaxToken> + '_ {
node.children_with_tokens()
.filter_map(|element| element.into_token())
.filter(move |token| token.kind() == kind || token.kind() == SyntaxKind::NEWLINE)
}
fn payload_text(node: &SyntaxNode, kind: SyntaxKind) -> String {
let mut out = String::new();
for token in payload_tokens(node, kind) {
if token.kind() == SyntaxKind::NEWLINE {
out.push('\n');
} else if matches!(token.text(), "\n" | "\r\n") {
out.push(' ');
} else {
out.push_str(token.text());
}
}
out
}
fn payload_range(
node: &SyntaxNode,
kind: SyntaxKind,
start: usize,
end: usize,
) -> Option<TextRange> {
let mut offset = 0;
let mut source_start = None;
for token in payload_tokens(node, kind) {
let length = if matches!(token.text(), "\n" | "\r\n") {
1
} else {
token.text().len()
};
if source_start.is_none() && start < offset + length {
source_start =
Some(token.text_range().start() + TextSize::from((start - offset) as u32));
}
if end <= offset + length {
let source_end = if end == offset + length {
token.text_range().end()
} else {
token.text_range().start() + TextSize::from((end - offset) as u32)
};
return Some(TextRange::new(source_start?, source_end));
}
offset += length;
}
None
}
fn uppercase_first(text: &str) -> String {
let mut chars = text.chars();
chars
.next()
.map(char::to_uppercase)
.into_iter()
.flatten()
.collect::<String>()
+ chars.as_str()
}