1#![deny(missing_docs)]
17#![deny(
18 clippy::unwrap_used,
19 clippy::expect_used,
20 clippy::panic,
21 clippy::todo,
22 clippy::unimplemented
23)]
24
25mod emoji;
26mod emoji_data;
27mod github;
28mod prose;
29mod toc;
30mod typography;
31
32pub use emoji::EmojiShortcodesPass;
33pub use github::{GitHubReferencesPass, InvalidGitHubRepository};
34pub use toc::{TableOfContentsError, build_table_of_contents};
35pub use typography::{
36 TypographyLanguage, TypographyOptions, TypographyPass, UnsupportedTypographyLanguage,
37};
38
39use std::borrow::Cow;
40use std::error::Error;
41use std::fmt;
42use std::ops::Range;
43
44use ferromark::ast::{Document, Link, Node, Span, Text};
45use ferromark::{Allocator, AutolinkMatcher, HtmlRendererOptions};
46
47pub type BoxError = Box<dyn Error + Send + Sync + 'static>;
49
50pub trait TransformPass: Send {
60 fn name(&self) -> &'static str;
62
63 fn apply<'arena>(
65 &mut self,
66 document: &mut Document<'arena>,
67 context: &TransformContext<'arena>,
68 ) -> Result<(), BoxError>;
69}
70
71#[derive(Default)]
73pub struct TransformPipeline {
74 passes: Vec<Box<dyn TransformPass>>,
75}
76
77impl TransformPipeline {
78 #[must_use]
80 pub fn new() -> Self {
81 Self::default()
82 }
83
84 pub fn add<P: TransformPass + 'static>(&mut self, pass: P) {
86 self.passes.push(Box::new(pass));
87 }
88
89 #[must_use]
91 pub fn len(&self) -> usize {
92 self.passes.len()
93 }
94
95 #[must_use]
97 pub fn is_empty(&self) -> bool {
98 self.passes.is_empty()
99 }
100
101 pub fn run<'arena>(
108 &mut self,
109 document: &mut Document<'arena>,
110 context: &TransformContext<'arena>,
111 ) -> Result<(), TransformError> {
112 for (pass_index, pass) in self.passes.iter_mut().enumerate() {
113 let pass_name = pass.name();
114 if let Err(source) = pass.apply(document, context) {
115 return Err(TransformError {
116 pass_index,
117 pass_name,
118 source,
119 });
120 }
121 }
122
123 Ok(())
124 }
125}
126
127pub struct TransformContext<'arena> {
134 allocator: &'arena Allocator,
135 source: &'arena str,
136 autolink_matcher: Option<AutolinkMatcher>,
137}
138
139impl<'arena> TransformContext<'arena> {
140 #[must_use]
149 pub fn new(
150 allocator: &'arena Allocator,
151 source: &'arena str,
152 renderer_options: &HtmlRendererOptions,
153 ) -> Self {
154 Self {
155 allocator,
156 source,
157 autolink_matcher: renderer_options.autolink_matcher(),
158 }
159 }
160
161 #[must_use]
163 pub const fn source(&self) -> &'arena str {
164 self.source
165 }
166
167 #[must_use]
169 pub fn alloc_str(&self, value: &str) -> &'arena str {
170 let allocator: &'arena Allocator = self.allocator;
171 allocator.alloc_str(value)
172 }
173
174 #[must_use]
176 pub fn replacement_text(&self, value: &str, span: Span) -> Text<'arena> {
177 Text {
178 value: self.alloc_str(value),
179 span,
180 }
181 }
182
183 #[must_use]
188 pub fn generated_text(&self, value: &str) -> Text<'arena> {
189 self.replacement_text(value, Span::empty())
190 }
191
192 pub fn replace_text_value(&self, text: &mut Text<'arena>, value: &str) {
194 text.value = self.alloc_str(value);
195 }
196
197 pub fn replace_text_range(
208 &self,
209 nodes: &mut ferromark::allocator::Vec<'arena, Node<'arena>>,
210 node_range: Range<usize>,
211 byte_range: Range<usize>,
212 replacement: &str,
213 ) -> Result<Span, TextReplacementError> {
214 Self::replace_text_range_with_node(nodes, node_range, byte_range, |span| {
215 (!replacement.is_empty()).then(|| Node::Text(self.replacement_text(replacement, span)))
216 })
217 }
218
219 pub(crate) fn replace_text_range_with_node(
220 nodes: &mut ferromark::allocator::Vec<'arena, Node<'arena>>,
221 node_range: Range<usize>,
222 byte_range: Range<usize>,
223 replacement: impl FnOnce(Span) -> Option<Node<'arena>>,
224 ) -> Result<Span, TextReplacementError> {
225 validate_node_range(nodes, &node_range)?;
226 validate_text_byte_range(nodes, &node_range, &byte_range)?;
227
228 let replacement_span = span_for_byte_range(nodes, &node_range, &byte_range);
229 let replacement = replacement(replacement_span);
230 if byte_range.is_empty() {
231 if let Some(node) = replacement {
232 insert_node_at_text_offset(nodes, &node_range, byte_range.start, node);
233 }
234 return Ok(Span::empty());
235 }
236
237 let (first, last, first_offset, last_offset) =
238 overlapping_text_nodes(nodes, &node_range, &byte_range)?;
239 let (first_value, first_span) = match &nodes[first] {
240 Node::Text(text) => (text.value, text.span),
241 _ => return Err(TextReplacementError::NonTextNode { index: first }),
242 };
243 let (last_value, last_span) = match &nodes[last] {
244 Node::Text(text) => (text.value, text.span),
245 _ => return Err(TextReplacementError::NonTextNode { index: last }),
246 };
247
248 let mut replacements = std::vec::Vec::with_capacity(last - first + 3);
252 let prefix = &first_value[..first_offset];
253 if !prefix.is_empty() {
254 replacements.push(Node::Text(Text {
255 value: prefix,
256 span: first_span,
257 }));
258 }
259 if let Some(replacement) = replacement {
260 replacements.push(replacement);
261 }
262 if first < last {
263 for node in &nodes[first + 1..last] {
264 if let Node::Text(text) = node
265 && text.value.is_empty()
266 {
267 replacements.push(Node::Text(Text {
268 value: text.value,
269 span: text.span,
270 }));
271 }
272 }
273 }
274 let suffix = &last_value[last_offset..];
275 if !suffix.is_empty() {
276 replacements.push(Node::Text(Text {
277 value: suffix,
278 span: last_span,
279 }));
280 }
281
282 drop(nodes.splice(first..last + 1, replacements));
283
284 Ok(replacement_span)
285 }
286
287 pub(crate) fn text_link_node(&self, label: &str, url: &str, span: Span) -> Node<'arena> {
288 let mut children = self.allocator.new_vec();
289 children.push(Node::Text(self.replacement_text(label, span)));
290 Node::Link(self.allocator.boxed(Link {
291 url: self.alloc_str(url),
292 title: None,
293 attributes: None,
294 children,
295 span,
296 }))
297 }
298}
299
300pub struct TextRun<'nodes, 'arena> {
307 nodes: &'nodes [Node<'arena>],
308 node_range: Range<usize>,
309}
310
311impl<'nodes, 'arena> TextRun<'nodes, 'arena> {
312 #[must_use]
314 pub fn node_range(&self) -> Range<usize> {
315 self.node_range.clone()
316 }
317
318 pub fn segments(&self) -> impl Iterator<Item = TextSegment<'arena>> + '_ {
320 self.nodes.iter().filter_map(|node| {
321 if let Node::Text(text) = node {
322 Some(TextSegment {
323 value: text.value,
324 span: text.span,
325 })
326 } else {
327 None
328 }
329 })
330 }
331
332 #[must_use]
339 pub fn protected_url_ranges(&self, context: &TransformContext<'_>) -> Vec<Range<usize>> {
340 let mut ranges = Vec::new();
341 let Some(matcher) = &context.autolink_matcher else {
342 return ranges;
343 };
344
345 let mut offset = 0;
346 for segment in self.segments() {
347 ranges.extend(
348 matcher
349 .find_ranges(segment.value)
350 .into_iter()
351 .map(|range| range.start + offset..range.end + offset),
352 );
353 offset += segment.value.len();
354 }
355 ranges
356 }
357
358 #[must_use]
360 pub fn value(&self) -> Cow<'arena, str> {
361 if let [Node::Text(text)] = self.nodes {
362 return Cow::Borrowed(text.value);
363 }
364
365 let capacity = self.segments().map(|segment| segment.value.len()).sum();
366 let mut value = String::with_capacity(capacity);
367 for segment in self.segments() {
368 value.push_str(segment.value);
369 }
370 Cow::Owned(value)
371 }
372
373 #[must_use]
375 pub fn source_span(&self) -> Span {
376 span_for_byte_range(self.nodes, &(0..self.nodes.len()), &self.value_range())
377 }
378
379 pub fn span_for_bytes(&self, range: Range<usize>) -> Result<Span, TextReplacementError> {
383 let value = self.value();
384 validate_byte_range(&value, &range)?;
385 Ok(span_for_byte_range(
386 self.nodes,
387 &(0..self.nodes.len()),
388 &range,
389 ))
390 }
391
392 fn value_range(&self) -> Range<usize> {
393 0..self.segments().map(|segment| segment.value.len()).sum()
394 }
395}
396
397#[derive(Debug, Clone, Copy, PartialEq, Eq)]
399pub struct TextSegment<'arena> {
400 pub value: &'arena str,
402 pub span: Span,
404}
405
406pub struct TextRuns<'nodes, 'arena> {
408 nodes: &'nodes [Node<'arena>],
409 cursor: usize,
410}
411
412impl<'nodes, 'arena> Iterator for TextRuns<'nodes, 'arena> {
413 type Item = TextRun<'nodes, 'arena>;
414
415 fn next(&mut self) -> Option<Self::Item> {
416 while self.cursor < self.nodes.len() && !matches!(self.nodes[self.cursor], Node::Text(_)) {
417 self.cursor += 1;
418 }
419 if self.cursor == self.nodes.len() {
420 return None;
421 }
422
423 let start = self.cursor;
424 while self.cursor < self.nodes.len() && matches!(self.nodes[self.cursor], Node::Text(_)) {
425 self.cursor += 1;
426 }
427
428 Some(TextRun {
429 nodes: &self.nodes[start..self.cursor],
430 node_range: start..self.cursor,
431 })
432 }
433}
434
435#[must_use]
437pub fn text_runs<'nodes, 'arena>(nodes: &'nodes [Node<'arena>]) -> TextRuns<'nodes, 'arena> {
438 TextRuns { nodes, cursor: 0 }
439}
440
441#[derive(Debug, Clone, PartialEq, Eq)]
443#[non_exhaustive]
444pub enum TextReplacementError {
445 InvalidNodeRange {
447 start: usize,
449 end: usize,
451 node_count: usize,
453 },
454 NonTextNode {
456 index: usize,
458 },
459 ReversedByteRange {
461 start: usize,
463 end: usize,
465 },
466 ByteRangeOutOfBounds {
468 end: usize,
470 text_len: usize,
472 },
473 NotCharBoundary {
475 offset: usize,
477 },
478}
479
480impl fmt::Display for TextReplacementError {
481 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
482 match self {
483 Self::InvalidNodeRange {
484 start,
485 end,
486 node_count,
487 } => write!(
488 formatter,
489 "text node range {start}..{end} is invalid for {node_count} nodes"
490 ),
491 Self::NonTextNode { index } => {
492 write!(formatter, "node {index} in the selected range is not text")
493 }
494 Self::ReversedByteRange { start, end } => {
495 write!(formatter, "text byte range {start}..{end} is reversed")
496 }
497 Self::ByteRangeOutOfBounds { end, text_len } => write!(
498 formatter,
499 "text byte range ends at {end}, past the {text_len}-byte value"
500 ),
501 Self::NotCharBoundary { offset } => {
502 write!(
503 formatter,
504 "text byte offset {offset} is not a UTF-8 boundary"
505 )
506 }
507 }
508 }
509}
510
511impl Error for TextReplacementError {}
512
513fn validate_node_range(
514 nodes: &[Node<'_>],
515 range: &Range<usize>,
516) -> Result<(), TextReplacementError> {
517 if range.start >= range.end || range.end > nodes.len() {
518 return Err(TextReplacementError::InvalidNodeRange {
519 start: range.start,
520 end: range.end,
521 node_count: nodes.len(),
522 });
523 }
524 for (index, node) in nodes.iter().enumerate().take(range.end).skip(range.start) {
525 if !matches!(node, Node::Text(_)) {
526 return Err(TextReplacementError::NonTextNode { index });
527 }
528 }
529 Ok(())
530}
531
532fn validate_text_byte_range(
533 nodes: &[Node<'_>],
534 node_range: &Range<usize>,
535 byte_range: &Range<usize>,
536) -> Result<(), TextReplacementError> {
537 if byte_range.start > byte_range.end {
538 return Err(TextReplacementError::ReversedByteRange {
539 start: byte_range.start,
540 end: byte_range.end,
541 });
542 }
543
544 let text_len = text_len_in_range(nodes, node_range);
545 if byte_range.end > text_len {
546 return Err(TextReplacementError::ByteRangeOutOfBounds {
547 end: byte_range.end,
548 text_len,
549 });
550 }
551
552 for offset in [byte_range.start, byte_range.end] {
553 if !is_text_char_boundary(nodes, node_range, offset) {
554 return Err(TextReplacementError::NotCharBoundary { offset });
555 }
556 }
557 Ok(())
558}
559
560fn text_len_in_range(nodes: &[Node<'_>], node_range: &Range<usize>) -> usize {
561 nodes[node_range.clone()]
562 .iter()
563 .map(|node| match node {
564 Node::Text(text) => text.value.len(),
565 _ => 0,
566 })
567 .sum()
568}
569
570fn is_text_char_boundary(nodes: &[Node<'_>], node_range: &Range<usize>, offset: usize) -> bool {
571 let mut cursor = 0;
572 for node in &nodes[node_range.clone()] {
573 let Node::Text(text) = node else {
574 return false;
575 };
576 let end = cursor + text.value.len();
577 if offset <= end {
578 return text.value.is_char_boundary(offset - cursor);
579 }
580 cursor = end;
581 }
582 offset == cursor
583}
584
585fn overlapping_text_nodes(
586 nodes: &[Node<'_>],
587 node_range: &Range<usize>,
588 byte_range: &Range<usize>,
589) -> Result<(usize, usize, usize, usize), TextReplacementError> {
590 let mut cursor = 0;
591 let mut first = None;
592 let mut last = None;
593 let mut first_offset = 0;
594 let mut last_offset = 0;
595
596 for index in node_range.clone() {
597 let Node::Text(text) = &nodes[index] else {
598 continue;
599 };
600 let end = cursor + text.value.len();
601 if cursor < byte_range.end && end > byte_range.start {
602 if first.is_none() {
603 first = Some(index);
604 first_offset = byte_range.start - cursor;
605 }
606 last = Some(index);
607 last_offset = byte_range.end.min(end) - cursor;
608 }
609 cursor = end;
610 }
611
612 let Some(first) = first else {
613 return Err(TextReplacementError::ByteRangeOutOfBounds {
614 end: byte_range.end,
615 text_len: text_len_in_range(nodes, node_range),
616 });
617 };
618 let Some(last) = last else {
619 return Err(TextReplacementError::ByteRangeOutOfBounds {
620 end: byte_range.end,
621 text_len: text_len_in_range(nodes, node_range),
622 });
623 };
624 Ok((first, last, first_offset, last_offset))
625}
626
627fn insert_node_at_text_offset<'arena>(
628 nodes: &mut ferromark::allocator::Vec<'arena, Node<'arena>>,
629 node_range: &Range<usize>,
630 offset: usize,
631 inserted: Node<'arena>,
632) {
633 let text_len = text_len_in_range(nodes, node_range);
634 if offset == 0 {
635 drop(nodes.splice(
636 node_range.start..node_range.start,
637 std::iter::once(inserted),
638 ));
639 return;
640 }
641 if offset == text_len {
642 drop(nodes.splice(node_range.end..node_range.end, std::iter::once(inserted)));
643 return;
644 }
645
646 let mut cursor = 0;
647 for index in node_range.clone() {
648 let Node::Text(text) = &nodes[index] else {
649 continue;
650 };
651 let end = cursor + text.value.len();
652 if cursor < offset && offset < end {
653 let (prefix, suffix, span) = (
654 &text.value[..offset - cursor],
655 &text.value[offset - cursor..],
656 text.span,
657 );
658 let parts = [
659 Some(Node::Text(Text {
660 value: prefix,
661 span,
662 })),
663 Some(inserted),
664 Some(Node::Text(Text {
665 value: suffix,
666 span,
667 })),
668 ];
669 drop(nodes.splice(index..index + 1, parts.into_iter().flatten()));
670 return;
671 }
672 cursor = end;
673 if cursor == offset {
674 drop(nodes.splice(index + 1..index + 1, std::iter::once(inserted)));
675 return;
676 }
677 }
678
679 drop(nodes.splice(node_range.end..node_range.end, std::iter::once(inserted)));
682}
683
684fn validate_byte_range(value: &str, range: &Range<usize>) -> Result<(), TextReplacementError> {
685 if range.start > range.end {
686 return Err(TextReplacementError::ReversedByteRange {
687 start: range.start,
688 end: range.end,
689 });
690 }
691 if range.end > value.len() {
692 return Err(TextReplacementError::ByteRangeOutOfBounds {
693 end: range.end,
694 text_len: value.len(),
695 });
696 }
697 for offset in [range.start, range.end] {
698 if !value.is_char_boundary(offset) {
699 return Err(TextReplacementError::NotCharBoundary { offset });
700 }
701 }
702 Ok(())
703}
704
705fn span_for_byte_range(
706 nodes: &[Node<'_>],
707 node_range: &Range<usize>,
708 byte_range: &Range<usize>,
709) -> Span {
710 if byte_range.is_empty() {
711 return Span::empty();
712 }
713
714 let mut byte_cursor = 0;
715 let mut span = None;
716 for node in nodes.iter().take(node_range.end).skip(node_range.start) {
717 if let Node::Text(text) = node {
718 let segment_end = byte_cursor + text.value.len();
719 if byte_cursor < byte_range.end
720 && segment_end > byte_range.start
721 && !text.span.is_empty()
722 {
723 span = Some(span.map_or(text.span, |current: Span| current.merge(text.span)));
724 }
725 byte_cursor = segment_end;
726 }
727 }
728 span.unwrap_or_else(Span::empty)
729}
730
731#[derive(Debug)]
733pub struct TransformError {
734 pass_index: usize,
735 pass_name: &'static str,
736 source: BoxError,
737}
738
739impl TransformError {
740 #[must_use]
742 pub const fn pass_index(&self) -> usize {
743 self.pass_index
744 }
745
746 #[must_use]
748 pub const fn pass_name(&self) -> &'static str {
749 self.pass_name
750 }
751}
752
753impl fmt::Display for TransformError {
754 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
755 write!(
756 formatter,
757 "transform pass {} ({:?}) failed: {}",
758 self.pass_index, self.pass_name, self.source
759 )
760 }
761}
762
763impl Error for TransformError {
764 fn source(&self) -> Option<&(dyn Error + 'static)> {
765 Some(&*self.source)
766 }
767}