1#![doc = include_str!("../README.md")]
2#![allow(clippy::doc_markdown)]
3
4mod pattern;
5
6use crate::pattern::{Pattern, PatternError};
7use std::collections::{HashMap, HashSet};
8use std::io::{self, BufWriter, Read, Write};
9use std::ops::Range;
10use std::path::{Path, PathBuf};
11use std::rc::Rc;
12
13struct Cache {
16 tags: HashSet<Rc<str>>,
19
20 entries: Vec<DocEntry>,
23
24 ranges: HashMap<PathBuf, Range<usize>>,
27}
28
29thread_local! {
30 static CACHE: std::cell::RefCell<Cache> = std::cell::RefCell::new(Cache {
34 tags: HashSet::new(),
35 entries: Vec::new(),
36 ranges: HashMap::new(),
37 });
38}
39
40fn normalize_path(path: &Path) -> io::Result<PathBuf> {
45 if path == Path::new("-") {
46 return Ok(PathBuf::from("-"));
47 }
48 path.canonicalize()
49}
50
51fn intern_tag(pool: &mut HashSet<Rc<str>>, name: &str) -> Rc<str> {
53 if let Some(existing) = pool.get(name) {
54 return Rc::clone(existing);
55 }
56 let rc: Rc<str> = Rc::from(name.to_string());
57 pool.insert(Rc::clone(&rc));
58 rc
59}
60
61enum OutputTarget {
65 File(std::fs::File),
66 Stdout(std::io::Stdout),
67}
68
69impl Write for OutputTarget {
70 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
71 match self {
72 OutputTarget::File(f) => f.write(buf),
73 OutputTarget::Stdout(s) => s.write(buf),
74 }
75 }
76
77 fn flush(&mut self) -> io::Result<()> {
78 match self {
79 OutputTarget::File(f) => f.flush(),
80 OutputTarget::Stdout(s) => s.flush(),
81 }
82 }
83}
84
85struct DocEntry {
87 tag: Rc<str>,
89 text: Box<str>,
91 transient: bool,
94}
95
96pub struct Docextract {
110 output: Option<BufWriter<OutputTarget>>,
111 rerun_if_changed: bool,
112 output_filter: Option<Pattern>,
113}
114
115fn path_stem(path: &Path) -> String {
117 path.file_stem()
118 .and_then(|s| s.to_str())
119 .unwrap_or("unknown")
120 .to_string()
121}
122
123impl From<PatternError> for io::Error {
124 fn from(e: PatternError) -> io::Error {
125 io::Error::new(io::ErrorKind::InvalidInput, e.to_string())
126 }
127}
128
129impl Docextract {
130 pub fn new(output: impl AsRef<Path>) -> io::Result<Self> {
140 let target = if output.as_ref() == Path::new("-") {
141 OutputTarget::Stdout(std::io::stdout())
142 } else {
143 OutputTarget::File(std::fs::File::create(output.as_ref())?)
144 };
145
146 let writer = BufWriter::with_capacity(32768, target);
147
148 let rerun_if_changed = std::env::var("OUT_DIR").is_ok();
149
150 Ok(Docextract {
151 output: Some(writer),
152 rerun_if_changed,
153 output_filter: None,
154 })
155 }
156
157 pub fn input(&mut self, path: impl AsRef<Path>) -> io::Result<&mut Self> {
168 if self.output.is_none() {
169 return Err(io::Error::new(
170 io::ErrorKind::BrokenPipe,
171 "output already closed",
172 ));
173 }
174 self.input_impl(path.as_ref(), None)
175 }
176
177 pub fn stdin(&mut self) -> io::Result<&mut Self> {
184 if self.output.is_none() {
185 return Err(io::Error::new(
186 io::ErrorKind::BrokenPipe,
187 "output already closed",
188 ));
189 }
190 self.stdin_impl()
191 }
192
193 pub fn filter_output(&mut self, filter: Option<&str>) -> Result<&mut Self, PatternError> {
206 self.output_filter = match filter {
207 Some(s) => Some(Pattern::new(s)?),
208 None => None,
209 };
210 Ok(self)
211 }
212
213 pub fn input_filtered(
233 &mut self,
234 path: impl AsRef<Path>,
235 filter: &str,
236 ) -> io::Result<&mut Self> {
237 if self.output.is_none() {
238 return Err(io::Error::new(
239 io::ErrorKind::BrokenPipe,
240 "output already closed",
241 ));
242 }
243 let pattern = Pattern::new(filter)?;
244 self.input_impl(path.as_ref(), Some(&pattern))
245 }
246
247 pub fn done(&mut self) -> io::Result<&mut Self> {
256 self.close_output()?;
257 Ok(self)
258 }
259
260 pub fn rerun_if_changed(&mut self, value: bool) -> &mut Self {
262 self.rerun_if_changed = value;
263 self
264 }
265
266 pub fn clear_cache() {
294 CACHE.with(|c| {
295 *c.borrow_mut() = Cache {
296 tags: HashSet::new(),
297 entries: Vec::new(),
298 ranges: HashMap::new(),
299 };
300 });
301 }
302
303 fn emit_entries(
307 &mut self,
308 entries: &[DocEntry],
309 input_filter: Option<&Pattern>,
310 any_filter_active: bool,
311 ) -> io::Result<()> {
312 let output = self.output.as_mut().expect("output not yet closed");
313
314 for entry in entries {
315 if !any_filter_active && entry.transient {
317 continue;
318 }
319
320 if let Some(f) = input_filter {
322 if !f.matches(&entry.tag) {
323 continue;
324 }
325 }
326 if let Some(ref f) = self.output_filter {
327 if !f.matches(&entry.tag) {
328 continue;
329 }
330 }
331
332 output.write_all(entry.text.as_bytes())?;
333 }
334
335 Ok(())
336 }
337
338 fn input_impl(&mut self, path: &Path, input_filter: Option<&Pattern>) -> io::Result<&mut Self> {
340 let is_stdin = path == Path::new("-");
341
342 if is_stdin {
343 return self.stdin_impl_with_filter(input_filter);
344 }
345
346 let canonical = match normalize_path(path) {
347 Ok(p) => p,
348 Err(e) if e.kind() == io::ErrorKind::NotFound => {
349 eprintln!(
350 "docextract: warning: input file not found: {}",
351 path.display()
352 );
353 return Ok(self);
354 }
355 Err(e) => return Err(e),
356 };
357
358 CACHE.with(|c| {
359 let mut cache = c.borrow_mut();
360
361 if let Some(range) = cache.ranges.get(&canonical).cloned() {
363 let any_filter_active = self.output_filter.is_some() || input_filter.is_some();
364 self.emit_entries(&cache.entries[range], input_filter, any_filter_active)?;
365 return Ok(self);
366 }
367
368 let file = match std::fs::File::open(path) {
370 Ok(f) => f,
371 Err(e) if e.kind() == io::ErrorKind::NotFound => {
372 eprintln!(
373 "docextract: warning: input file not found: {}",
374 path.display()
375 );
376 return Ok(self);
377 }
378 Err(e) => return Err(e),
379 };
380
381 let content = {
382 let mut buf = String::new();
383 let mut reader = std::io::BufReader::new(file);
384 reader.read_to_string(&mut buf)?;
385 buf
386 };
387
388 if self.rerun_if_changed {
389 println!("cargo:rerun-if-changed={}", path.display());
390 }
391
392 let initial_tag = path_stem(path);
393 let new_entries = parse_doc_entries(&mut cache.tags, &content, &initial_tag);
394 let start = cache.entries.len();
395 cache.entries.extend(new_entries);
396 let end = cache.entries.len();
397 cache.ranges.insert(canonical, start..end);
398
399 let any_filter_active = self.output_filter.is_some() || input_filter.is_some();
400 self.emit_entries(&cache.entries[start..end], input_filter, any_filter_active)?;
401
402 Ok(self)
403 })
404 }
405
406 fn stdin_impl(&mut self) -> io::Result<&mut Self> {
407 self.stdin_impl_with_filter(None)
408 }
409
410 fn stdin_impl_with_filter(&mut self, input_filter: Option<&Pattern>) -> io::Result<&mut Self> {
411 let key = PathBuf::from("-");
412
413 CACHE.with(|c| {
414 let mut cache = c.borrow_mut();
415
416 if let Some(range) = cache.ranges.get(&key).cloned() {
418 let any_filter_active = self.output_filter.is_some() || input_filter.is_some();
419 self.emit_entries(&cache.entries[range], input_filter, any_filter_active)?;
420 return Ok(self);
421 }
422
423 let mut content = String::new();
425 io::stdin().read_to_string(&mut content)?;
426
427 let new_entries = parse_doc_entries(&mut cache.tags, &content, "-");
428 let start = cache.entries.len();
429 cache.entries.extend(new_entries);
430 let end = cache.entries.len();
431 cache.ranges.insert(key, start..end);
432
433 let any_filter_active = self.output_filter.is_some() || input_filter.is_some();
434 self.emit_entries(&cache.entries[start..end], input_filter, any_filter_active)?;
435
436 Ok(self)
437 })
438 }
439
440 fn close_output(&mut self) -> io::Result<()> {
443 match self.output.take() {
444 Some(mut writer) => {
445 let result = writer.flush();
446 drop(writer);
447 if let Err(ref e) = result {
448 eprintln!("docextract: error: output: {e}");
449 }
450 result
451 }
452 None => Ok(()),
453 }
454 }
455}
456
457impl Drop for Docextract {
458 fn drop(&mut self) {
464 let _ = self.close_output();
465 }
466}
467
468#[allow(clippy::too_many_lines)]
473fn parse_doc_entries(
474 pool: &mut HashSet<Rc<str>>,
475 content: &str,
476 initial_tag: &str,
477) -> Vec<DocEntry> {
478 let mut entries = Vec::new();
479
480 let initial_tag_rc = intern_tag(pool, initial_tag);
481 let mut current_tag = Rc::clone(&initial_tag_rc);
482 let mut capture_zone_indent: Option<usize> = None;
483
484 for line_slice in content.split_inclusive('\n') {
485 let after_prefix = try_skip_leading_ws_and_four_slashes(line_slice);
487 let Some(after) = after_prefix else {
488 let line_content = strip_trailing_newline(line_slice);
490 if let Some((captured_code, template)) = try_split_code_capturing(line_content) {
491 if let Some((tag_name, remaining, is_transient)) = parse_template_tag(template) {
492 let tag_rc = intern_tag(pool, tag_name);
493 if is_transient {
494 let resolved = resolve_placeholders(remaining, captured_code);
495 let ending = extract_line_ending(line_slice);
496 let text = format!("{resolved}{ending}");
497 entries.push(DocEntry {
498 tag: tag_rc,
499 text: Box::from(text),
500 transient: true,
501 });
502 } else {
503 current_tag = tag_rc; }
505 } else {
506 let resolved = resolve_placeholders(template, captured_code);
507 let ending = extract_line_ending(line_slice);
508 let text = format!("{resolved}{ending}");
509 entries.push(DocEntry {
510 tag: Rc::clone(¤t_tag),
511 text: Box::from(text),
512 transient: false,
513 });
514 }
515 let indent = line_slice
517 .bytes()
518 .take_while(|&b| b == b' ' || b == b'\t')
519 .count();
520 capture_zone_indent = Some(indent);
521 } else {
522 capture_zone_indent = None;
523 }
524 continue;
525 };
526
527 let rest = &line_slice[after..];
528
529 if rest.as_bytes().first() == Some(&b'/') {
531 capture_zone_indent = None;
532 continue;
533 }
534
535 if let Some(zone_indent) = capture_zone_indent {
539 let line_indent = after - 4; if line_indent > zone_indent {
541 let template = match rest.as_bytes().first() {
544 Some(&b' ' | &b'\t') => strip_trailing_newline(&rest[1..]),
545 Some(&b'\n' | &b'\r') | None => "",
546 _ => strip_trailing_newline(rest),
547 };
548 if let Some((tag_name, remaining, is_transient)) = parse_template_tag(template) {
549 let tag_rc = intern_tag(pool, tag_name);
550 if is_transient {
551 let resolved = resolve_placeholders(remaining, "");
552 let ending = extract_line_ending(line_slice);
553 let text = format!("{resolved}{ending}");
554 entries.push(DocEntry {
555 tag: tag_rc,
556 text: Box::from(text),
557 transient: true,
558 });
559 } else {
560 current_tag = tag_rc; }
562 } else {
563 let resolved = resolve_placeholders(template, "");
564 let ending = extract_line_ending(line_slice);
565 let text = format!("{resolved}{ending}");
566 entries.push(DocEntry {
567 tag: Rc::clone(¤t_tag),
568 text: Box::from(text),
569 transient: false,
570 });
571 }
572 continue; }
574 capture_zone_indent = None; }
576
577 let Some(first_byte) = rest.as_bytes().first().copied() else {
579 entries.push(DocEntry {
582 tag: Rc::clone(¤t_tag),
583 text: Box::from(""),
584 transient: false,
585 });
586 continue;
587 };
588
589 match first_byte {
590 b' ' | b'\t' => {
591 let text = &rest[1..]; entries.push(DocEntry {
594 tag: Rc::clone(¤t_tag),
595 text: Box::from(text),
596 transient: false,
597 });
598 }
599 b'\n' | b'\r' => {
600 entries.push(DocEntry {
602 tag: Rc::clone(¤t_tag),
603 text: Box::from(rest),
604 transient: false,
605 });
606 }
607 _ => {
608 let (name, text_opt) = parse_tag_directive_from_rest(rest);
610
611 let tag_rc = intern_tag(pool, name);
613
614 match text_opt {
615 None => {
616 current_tag = tag_rc;
618 }
619 Some(text) => {
620 entries.push(DocEntry {
622 tag: tag_rc,
623 text: Box::from(text),
624 transient: true,
625 });
626 }
627 }
628 }
629 }
630 }
631
632 entries
633}
634
635fn try_skip_leading_ws_and_four_slashes(line: &str) -> Option<usize> {
638 let b = line.as_bytes();
639 let mut pos: usize = 0;
640
641 while pos < b.len() && (b[pos] == 0x20 || b[pos] == 0x09) {
643 pos += 1;
644 }
645
646 if pos + 4 > b.len() {
648 return None;
649 }
650 if b[pos] != 0x2F || b[pos + 1] != 0x2F || b[pos + 2] != 0x2F || b[pos + 3] != 0x2F {
651 return None;
652 }
653
654 Some(pos + 4)
655}
656
657fn parse_template_tag(template: &str) -> Option<(&str, &str, bool)> {
667 let b = template.as_bytes();
668 if b.is_empty() {
669 return None;
670 }
671 match b[0] {
672 b'{' | b'/' | b' ' | b'\t' => return None,
673 _ => {}
674 }
675 for (i, &byte) in b.iter().enumerate().skip(1) {
677 match byte {
678 b' ' | b'\t' => {
679 return Some((&template[..i], &template[i + 1..], true));
680 }
681 b'\n' | b'\r' => {
682 return Some((&template[..i], &template[i..], false));
683 }
684 _ => {}
685 }
686 }
687 Some((template, "", false))
689}
690
691fn parse_tag_directive_from_rest(rest: &str) -> (&str, Option<&str>) {
696 let raw_tag = rest.trim_end_matches(['\n', '\r']);
698
699 if let Some(ws_pos) = raw_tag.find(&[' ', '\t'] as &[char]) {
701 let name = &raw_tag[..ws_pos];
702 let text = &rest[ws_pos + 1..];
704 (name, Some(text))
705 } else {
706 (raw_tag, None)
707 }
708}
709
710#[allow(
729 dead_code,
730 reason = "only used by tests and code-capturing integration (not yet wired into parse_doc_entries)"
731)]
732fn trim_trailing_space_tab(bytes: &[u8]) -> usize {
733 let mut end = bytes.len();
734 while end > 0 && (bytes[end - 1] == b' ' || bytes[end - 1] == b'\t') {
735 end -= 1;
736 }
737 end
738}
739
740#[allow(
745 dead_code,
746 reason = "only used by tests and code-capturing integration"
747)]
748fn trim_leading_space_tab(s: &str) -> &str {
749 let bytes = s.as_bytes();
750 let mut start = 0;
751 while start < bytes.len() && (bytes[start] == b' ' || bytes[start] == b'\t') {
752 start += 1;
753 }
754 &s[start..]
755}
756
757#[allow(
767 dead_code,
768 reason = "only used by tests and code-capturing integration"
769)]
770fn try_split_code_capturing(line: &str) -> Option<(&str, &str)> {
771 let b = line.as_bytes();
772
773 for i in (0..=b.len().saturating_sub(4)).rev() {
774 if i + 3 >= b.len() {
776 continue;
777 }
778 if b[i] == b'/' && b[i + 1] == b'/' && b[i + 2] == b'/' && b[i + 3] == b'/' {
779 if i == 0 || (b[i - 1] != b' ' && b[i - 1] != b'\t') {
781 continue;
782 }
783
784 let separator_pos = i - 1;
785 let after_slashes = i + 4;
786
787 let code_end = trim_trailing_space_tab(&b[..separator_pos]);
789 let captured_code = &line[..code_end];
790
791 let template = if after_slashes >= b.len() {
793 ""
794 } else if b[after_slashes] == b' ' || b[after_slashes] == b'\t' {
795 &line[after_slashes + 1..]
796 } else {
797 &line[after_slashes..]
798 };
799
800 return Some((captured_code, template));
801 }
802 }
803
804 None
805}
806
807fn unescape_delimiter(s: &str, delim: u8) -> String {
815 let delim_char = delim as char;
816 let mut result = String::with_capacity(s.len());
817 let mut iter = s.chars().peekable();
818 while let Some(ch) = iter.next() {
819 if ch == '\\' {
820 if let Some(&next_ch) = iter.peek() {
821 if next_ch == delim_char {
822 result.push(delim_char);
823 iter.next(); continue;
825 }
826 }
827 }
828 result.push(ch);
829 }
830 result
831}
832
833#[allow(dead_code, reason = "RED scaffolding; constructed in batch 2")]
840struct SedForm {
841 regex: String,
842 subst: Option<String>,
843}
844
845#[allow(dead_code, reason = "RED scaffolding; constructed in batch 2")]
847struct SedError(String);
848
849#[allow(
856 dead_code,
857 reason = "only called from cfg(feature = \"regex\") code path"
858)]
859fn parse_sed_placeholder(content: &str) -> Result<SedForm, SedError> {
860 let delim = content.as_bytes()[0];
861 let inner = &content[1..];
862
863 let mut regex_end: Option<usize> = None;
865 let mut i = 0;
866 while i < inner.len() {
867 if inner.as_bytes()[i] == delim {
868 if i > 0 && inner.as_bytes()[i - 1] == b'\\' {
870 i += 1;
871 continue;
872 }
873 regex_end = Some(i);
874 break;
875 }
876 i += 1;
877 }
878
879 let Some(regex_end) = regex_end else {
880 return Err(SedError("unterminated regex".to_string()));
881 };
882
883 let regex_raw = &inner[..regex_end];
884 let after_regex = &inner[regex_end + 1..];
885
886 let regex_unescaped = unescape_delimiter(regex_raw, delim);
888
889 let mut subst_end: Option<usize> = None;
891 let mut j = 0;
892 while j < after_regex.len() {
893 if after_regex.as_bytes()[j] == delim {
894 if j > 0 && after_regex.as_bytes()[j - 1] == b'\\' {
895 j += 1;
896 continue;
897 }
898 subst_end = Some(j);
899 break;
900 }
901 j += 1;
902 }
903
904 match subst_end {
905 Some(end) => {
906 let subst_raw = &after_regex[..end];
908 let subst_unescaped = unescape_delimiter(subst_raw, delim);
909 Ok(SedForm {
910 regex: regex_unescaped,
911 subst: Some(subst_unescaped),
912 })
913 }
914 None => {
915 Ok(SedForm {
917 regex: regex_unescaped,
918 subst: None,
919 })
920 }
921 }
922}
923
924#[allow(
930 dead_code,
931 reason = "only used by resolve_single_placeholder (itself guarded by dead_code)"
932)]
933fn is_ascii_punctuation(b: u8) -> bool {
934 matches!(
935 b,
936 b'!' | b'"'
937 | b'#'
938 | b'$'
939 | b'%'
940 | b'&'
941 | b'\''
942 | b'*'
943 | b'+'
944 | b','
945 | b'-'
946 | b'.'
947 | b'/'
948 | b':'
949 | b';'
950 | b'<'
951 | b'='
952 | b'>'
953 | b'?'
954 | b'@'
955 | b'['
956 | b'\\'
957 | b']'
958 | b'^'
959 | b'_'
960 | b'`'
961 | b'|'
962 | b'~'
963 )
964}
965
966#[allow(
972 dead_code,
973 reason = "only used by tests and resolve_placeholders (not yet wired into parse_doc_entries)"
974)]
975fn resolve_single_placeholder(content: &str, captured_code: &str) -> String {
976 if content.is_empty() {
980 return trim_leading_space_tab(captured_code).to_string();
981 }
982
983 let first_byte = content.as_bytes()[0];
984
985 if first_byte.is_ascii_digit() {
987 let n: usize = content.parse().unwrap_or(usize::MAX);
988 let char_count = captured_code.chars().count();
989 if n >= char_count {
990 return String::new();
991 }
992 return captured_code.chars().skip(n).collect();
993 }
994
995 if is_ascii_punctuation(first_byte) {
997 #[cfg(feature = "regex")]
998 {
999 let form = parse_sed_placeholder(content)
1000 .unwrap_or_else(|e| panic!("docextract: invalid sed placeholder: {}", e.0));
1001
1002 return match form.subst {
1003 None => {
1004 let re = regex_lite::Regex::new(&form.regex).unwrap_or_else(|e| {
1006 eprintln!("docextract: warning: invalid regex '{}': {}", form.regex, e);
1007 regex_lite::Regex::new("\\b\\B").expect("\\b\\B is a valid regex pattern")
1008 });
1009 match re.find(captured_code) {
1010 Some(m) => m.as_str().to_string(),
1011 None => String::new(),
1012 }
1013 }
1014 Some(subst) => {
1015 let re = regex_lite::Regex::new(&form.regex).unwrap_or_else(|e| {
1018 eprintln!("docextract: warning: invalid regex '{}': {}", form.regex, e);
1019 regex_lite::Regex::new("\\b\\B").expect("\\b\\B is a valid regex pattern")
1020 });
1021 if let Some(m) = re.find(captured_code) {
1022 re.replace(m.as_str(), subst.as_str()).into_owned()
1023 } else {
1024 String::new()
1025 }
1026 }
1027 };
1028 }
1029 #[cfg(not(feature = "regex"))]
1030 {
1031 panic!(
1032 "docextract: sed-like placeholder '{{{{{content}}}}}' requires the `regex` feature.\n\
1033 Rebuild with default features (cargo build) or use only {{{{}}}} and {{{{N}}}} placeholders."
1034 );
1035 }
1036 }
1037
1038 panic!(
1040 "docextract: reserved placeholder form '{{{{{content}}}}}'.\n\
1041 Use {{{{}}}}, {{{{N}}}}, or a sed-like form {{{{X...X}}}}."
1042 );
1043}
1044
1045#[allow(
1052 dead_code,
1053 reason = "only used by tests and code-capturing integration"
1054)]
1055fn resolve_placeholders(template: &str, captured_code: &str) -> String {
1056 let mut result = String::new();
1057 let mut pos = 0;
1058
1059 while pos < template.len() {
1060 if template[pos..].starts_with("{{") {
1061 let search_from = pos + 2;
1062 if let Some(close_offset) = template[search_from..].find("}}") {
1063 let close_pos = search_from + close_offset;
1064 let content = &template[search_from..close_pos];
1065 let replacement = resolve_single_placeholder(content, captured_code);
1066 result.push_str(&replacement);
1067 pos = close_pos + 2;
1068 } else {
1069 result.push_str("{{");
1071 pos += 2;
1072 }
1073 } else {
1074 let ch = template[pos..]
1075 .chars()
1076 .next()
1077 .expect("pos < template.len() guarantees at least one char");
1078 result.push(ch);
1079 pos += ch.len_utf8();
1080 }
1081 }
1082
1083 result
1084}
1085
1086fn strip_trailing_newline(s: &str) -> &str {
1091 if let Some(stripped) = s.strip_suffix("\r\n") {
1092 stripped
1093 } else if let Some(stripped) = s.strip_suffix('\n') {
1094 stripped
1095 } else {
1096 s
1097 }
1098}
1099
1100fn extract_line_ending(s: &str) -> &str {
1102 if s.ends_with("\r\n") {
1103 "\r\n"
1104 } else if s.ends_with('\n') {
1105 "\n"
1106 } else {
1107 ""
1108 }
1109}
1110
1111#[cfg(test)]
1112mod tests {
1113 #![allow(clippy::unwrap_used)]
1114
1115 use super::*;
1118 use std::fmt::Write as FmtWrite;
1119 use std::fs;
1120 use std::path::PathBuf;
1121 use std::sync::{Mutex, MutexGuard};
1122
1123 struct TempDir(PathBuf);
1125
1126 impl TempDir {
1127 fn new(name: &str) -> TempDir {
1128 let dir = std::env::temp_dir().join(format!(
1129 "docextract-test-{}-pid{}-{:?}",
1130 name,
1131 std::process::id(),
1132 std::thread::current().id(),
1133 ));
1134 fs::create_dir_all(&dir).unwrap();
1135 TempDir(dir)
1136 }
1137
1138 fn file(&self, name: &str) -> PathBuf {
1139 self.0.join(name)
1140 }
1141
1142 fn write(&self, name: &str, content: &str) -> PathBuf {
1143 let path = self.file(name);
1144 fs::write(&path, content).unwrap();
1145 path
1146 }
1147
1148 fn write_bytes(&self, name: &str, content: &[u8]) -> PathBuf {
1149 let path = self.file(name);
1150 fs::write(&path, content).unwrap();
1151 path
1152 }
1153 }
1154
1155 impl Drop for TempDir {
1156 fn drop(&mut self) {
1157 let _ = fs::remove_dir_all(&self.0);
1158 }
1159 }
1160
1161 fn read_str(path: &Path) -> String {
1162 fs::read_to_string(path).unwrap()
1163 }
1164
1165 static OUT_DIR_LOCK: Mutex<()> = Mutex::new(());
1168
1169 struct OutDirGuard {
1172 prev: Option<std::ffi::OsString>,
1173 _lock: MutexGuard<'static, ()>,
1174 }
1175
1176 impl OutDirGuard {
1177 fn with(value: Option<&std::ffi::OsStr>) -> OutDirGuard {
1178 let lock = OUT_DIR_LOCK.lock().unwrap();
1179 let prev = std::env::var_os("OUT_DIR");
1180 match value {
1181 Some(v) => unsafe { std::env::set_var("OUT_DIR", v) },
1182 None => unsafe { std::env::remove_var("OUT_DIR") },
1183 }
1184 OutDirGuard { prev, _lock: lock }
1185 }
1186 }
1187
1188 impl Drop for OutDirGuard {
1189 fn drop(&mut self) {
1190 match &self.prev {
1191 Some(v) => unsafe { std::env::set_var("OUT_DIR", v) },
1192 None => unsafe { std::env::remove_var("OUT_DIR") },
1193 }
1194 }
1195 }
1196
1197 #[test]
1198 fn b01_single_file_extraction() {
1199 let tmp = TempDir::new("b01");
1204 let src = tmp.write(
1205 "valid.rs",
1206 "//// Hello World\nfn main() {}\n//// Second line\n",
1207 );
1208 let out = tmp.file("out.md");
1209 Docextract::new(&out)
1210 .unwrap()
1211 .input(&src)
1212 .unwrap()
1213 .done()
1214 .unwrap();
1215 assert_eq!(read_str(&out), "Hello World\nSecond line\n");
1217 }
1218
1219 #[test]
1220 fn b02_multiple_files_concatenated() {
1221 let tmp = TempDir::new("b02");
1223 let a = tmp.write("a.rs", "//// From A\n");
1224 let b = tmp.write("b.rs", "//// From B\n");
1225 let out = tmp.file("out.md");
1226 Docextract::new(&out)
1227 .unwrap()
1228 .input(&a)
1229 .unwrap()
1230 .input(&b)
1231 .unwrap()
1232 .done()
1233 .unwrap();
1234 assert_eq!(read_str(&out), "From A\nFrom B\n");
1235 }
1236
1237 #[test]
1238 fn b03_missing_file_warns_and_continues() {
1239 let tmp = TempDir::new("b03");
1241 let src = tmp.write("valid.rs", "//// From Valid\n");
1242 let out = tmp.file("out.md");
1243 let mut builder = Docextract::new(&out).unwrap();
1244 assert!(builder.input(tmp.file("missing.rs")).is_ok());
1246 builder.input(&src).unwrap();
1248 builder.done().unwrap();
1249 assert_eq!(read_str(&out), "From Valid\n");
1250 }
1251
1252 #[test]
1253 fn b04_zero_inputs_empty_output() {
1254 let tmp = TempDir::new("b04");
1256 let out = tmp.file("out.md");
1257 Docextract::new(&out).unwrap().done().unwrap();
1258 assert!(out.exists());
1259 assert_eq!(read_str(&out), "");
1260 }
1261
1262 #[test]
1263 fn b05_stdin_input() {
1264 let tmp = TempDir::new("b05");
1266 let src = tmp.write("stdin-content.txt", "//// From stdin\n");
1267 let out = tmp.file("out.md");
1268 Docextract::new(&out)
1269 .unwrap()
1270 .input(&src)
1271 .unwrap()
1272 .done()
1273 .unwrap();
1274 assert_eq!(read_str(&out), "From stdin\n");
1275 }
1276
1277 #[test]
1278 fn b06_stdin_and_file_combined() {
1279 let tmp = TempDir::new("b06");
1281 let file = tmp.write("file.rs", "//// From File\n");
1282 let stdin_content = tmp.write("stdin.txt", "//// From stdin\n");
1283 let out = tmp.file("out.md");
1284 Docextract::new(&out)
1285 .unwrap()
1286 .input(&file)
1287 .unwrap()
1288 .input(&stdin_content)
1289 .unwrap()
1290 .done()
1291 .unwrap();
1292 assert_eq!(read_str(&out), "From File\nFrom stdin\n");
1293 }
1294
1295 #[test]
1296 fn b07_mixed_valid_and_invalid_inputs() {
1297 let tmp = TempDir::new("b07");
1299 let docs = tmp.write("docs.rs", "//// Kept\n");
1300 let no_docs = tmp.write(
1301 "code.rs",
1302 "fn main() {\n // not a doc\n}\n////Bad\n///// five\n////### Heading\n",
1303 );
1304 let out = tmp.file("out.md");
1305 Docextract::new(&out)
1306 .unwrap()
1307 .input(&docs)
1308 .unwrap()
1309 .input(&no_docs)
1310 .unwrap()
1311 .done()
1312 .unwrap();
1313 assert_eq!(read_str(&out), "Kept\n");
1316 }
1317
1318 #[test]
1319 fn b08_read_error_returns_err() {
1320 let tmp = TempDir::new("b08");
1322 let dir = tmp.file("a_directory");
1323 fs::create_dir_all(&dir).unwrap();
1324 let out = tmp.file("out.md");
1325 assert!(Docextract::new(&out).unwrap().input(&dir).is_err());
1326 }
1327
1328 #[test]
1329 fn b09_output_file_created() {
1330 let tmp = TempDir::new("b09");
1332 let out = tmp.file("out.md");
1333 assert!(!out.exists());
1334 let mut builder = Docextract::new(&out).unwrap();
1335 assert!(out.exists(), "output file must be created by new()");
1336 builder.done().unwrap();
1337 let out2 = tmp.file("pre.md");
1339 fs::write(&out2, "stale content").unwrap();
1340 Docextract::new(&out2).unwrap().done().unwrap();
1341 assert_eq!(read_str(&out2), "");
1342 }
1343
1344 #[test]
1345 fn b10_stdout_output_path() {
1346 let tmp = TempDir::new("b10");
1348 Docextract::new("-")
1349 .unwrap()
1350 .input(tmp.write("in.rs", "//// To stdout\n"))
1351 .unwrap()
1352 .done()
1353 .unwrap();
1354 assert!(
1355 !std::path::Path::new("-").exists(),
1356 "no file named '-' should be created in the working directory"
1357 );
1358 }
1359
1360 #[test]
1361 fn b11_rerun_if_changed_false_suppresses() {
1362 let tmp = TempDir::new("b11");
1364 let src = tmp.write("in.rs", "//// Doc\n");
1365 let out = tmp.file("out.md");
1366 let mut builder = Docextract::new(&out).unwrap();
1367 builder.rerun_if_changed(false);
1368 builder.input(&src).unwrap();
1369 builder.done().unwrap();
1370 assert_eq!(read_str(&out), "Doc\n");
1371 }
1372
1373 #[test]
1374 fn b12_last_toggle_wins() {
1375 let tmp = TempDir::new("b12");
1377 let src = tmp.write("in.rs", "//// Doc\n");
1378 let out = tmp.file("out.md");
1379 let mut builder = Docextract::new(&out).unwrap();
1380 builder.rerun_if_changed(true);
1381 builder.rerun_if_changed(false);
1382 builder.rerun_if_changed(true);
1383 builder.input(&src).unwrap();
1384 builder.done().unwrap();
1385 assert_eq!(read_str(&out), "Doc\n");
1386 }
1387
1388 #[test]
1389 fn b13_out_dir_set_auto_detects() {
1390 let tmp = TempDir::new("b13");
1392 let src = tmp.write("in.rs", "//// Doc\n");
1393 let out = tmp.file("out.md");
1394 let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
1395 let mut builder = Docextract::new(&out).unwrap();
1396 builder.input(&src).unwrap();
1397 builder.done().unwrap();
1398 assert_eq!(read_str(&out), "Doc\n");
1399 }
1400
1401 #[test]
1402 fn b14_out_dir_unset_default_false() {
1403 let tmp = TempDir::new("b14");
1405 let src = tmp.write("in.rs", "//// Doc\n");
1406 let out = tmp.file("out.md");
1407 let _guard = OutDirGuard::with(None);
1408 let mut builder = Docextract::new(&out).unwrap();
1409 builder.input(&src).unwrap();
1410 builder.done().unwrap();
1411 assert_eq!(read_str(&out), "Doc\n");
1412 }
1413
1414 #[test]
1415 fn b15_done_then_drop_no_double_close() {
1416 let tmp = TempDir::new("b15");
1418 let src = tmp.write("in.rs", "//// Doc\n");
1419 let out = tmp.file("out.md");
1420 let mut builder = Docextract::new(&out).unwrap();
1421 builder.input(&src).unwrap();
1422 builder.done().unwrap();
1423 builder.done().unwrap();
1424 assert_eq!(read_str(&out), "Doc\n");
1425 }
1426
1427 #[test]
1428 fn b16_drop_without_done_flushes() {
1429 let tmp = TempDir::new("b16");
1431 let src = tmp.write("in.rs", "//// Doc\n");
1432 let out = tmp.file("out.md");
1433 {
1434 let mut builder = Docextract::new(&out).unwrap();
1435 builder.input(&src).unwrap();
1436 }
1438 assert_eq!(read_str(&out), "Doc\n");
1439 }
1440
1441 #[test]
1442 fn b17_empty_file_no_output() {
1443 let tmp = TempDir::new("b17");
1445 let src = tmp.write("empty.rs", "");
1446 let out = tmp.file("out.md");
1447 Docextract::new(&out)
1448 .unwrap()
1449 .input(&src)
1450 .unwrap()
1451 .done()
1452 .unwrap();
1453 assert_eq!(read_str(&out), "");
1454 }
1455
1456 #[test]
1457 fn b18_no_doc_lines_empty_output() {
1458 let tmp = TempDir::new("b18");
1462 let src = tmp.write(
1463 "code.rs",
1464 "fn main() {\n println!(\"hi\");\n}\n// regular\n/// rustdoc\n////Bad\n///// five\n",
1465 );
1466 let out = tmp.file("out.md");
1467 Docextract::new(&out)
1468 .unwrap()
1469 .input(&src)
1470 .unwrap()
1471 .done()
1472 .unwrap();
1473 assert_eq!(read_str(&out), "");
1474 }
1475
1476 #[test]
1477 fn b19_crlf_preserved() {
1478 let tmp = TempDir::new("b19");
1481 let src = tmp.write(
1482 "crlf.rs",
1483 "//// First\r\n//// Second\r\nlet x = 1;\r\n//// Third\r\n",
1484 );
1485 let out = tmp.file("out.md");
1486 Docextract::new(&out)
1487 .unwrap()
1488 .input(&src)
1489 .unwrap()
1490 .done()
1491 .unwrap();
1492 assert_eq!(read_str(&out), "First\r\nSecond\r\nThird\r\n");
1493 }
1494
1495 #[test]
1496 fn b20_invalid_utf8_errors() {
1497 let tmp = TempDir::new("b20");
1499 let src = tmp.write_bytes("binary.rs", b"//// \xFF\xFE not utf8\n");
1500 let out = tmp.file("out.md");
1501 let mut builder = Docextract::new(&out).unwrap();
1502 assert!(builder.input(&src).is_err());
1503 builder.done().unwrap();
1504 }
1505
1506 #[test]
1507 fn b21_large_file_processing() {
1508 let tmp = TempDir::new("b21");
1512 let mut content = String::new();
1513 for i in 0..20_000 {
1514 let _ = write!(content, "//// line {i} {}", "x".repeat(40));
1515 content.push('\n');
1516 if i % 5 == 0 {
1517 content.push_str("fn f() {}\n");
1518 }
1519 }
1520 assert!(content.len() >= 1_000_000, "source should be ~1 MiB");
1521 let src = tmp.write("large.rs", &content);
1522 let out = tmp.file("out.md");
1523 Docextract::new(&out)
1524 .unwrap()
1525 .input(&src)
1526 .unwrap()
1527 .done()
1528 .unwrap();
1529 let output = read_str(&out);
1530 assert!(output.starts_with("line 0 "));
1531 assert!(output.ends_with(&format!("line 19999 {}\n", "x".repeat(40))));
1532 assert_eq!(output.lines().count(), 20_000);
1534 assert!(
1536 output
1537 .lines()
1538 .filter(|l| !l.is_empty())
1539 .all(|l| l.starts_with("line "))
1540 );
1541 assert!(output.len() > 800_000, "all 20k doc lines must be present");
1542 }
1543
1544 #[test]
1545 fn b22_multiple_inputs_in_loop() {
1546 let tmp = TempDir::new("b22");
1548 let out = tmp.file("out.md");
1549 let mut builder = Docextract::new(&out).unwrap();
1550 let mut expected = String::new();
1551 for i in 0..10 {
1552 let src = tmp.write(&format!("m{i}.rs"), &format!("//// File {i}\n"));
1553 builder.input(&src).unwrap();
1554 let _ = writeln!(expected, "File {i}");
1555 }
1556 builder.done().unwrap();
1557 assert_eq!(read_str(&out), expected);
1558 }
1559
1560 #[test]
1561 fn b23_done_ok_on_empty_builder() {
1562 let tmp = TempDir::new("b23");
1564 let out = tmp.file("out.md");
1565 let mut builder = Docextract::new(&out).unwrap();
1566 let result = builder.done();
1567 assert!(result.is_ok());
1568 assert_eq!(read_str(&out), "");
1569 }
1570
1571 #[test]
1572 fn b24_stdin_called_twice_second_noop() {
1573 let tmp = TempDir::new("b24");
1576 let first = tmp.write("first.txt", "//// Only once\n");
1577 let second = tmp.write("second.txt", "fn main() {\n let x = 1;\n}\n");
1578 let out = tmp.file("out.md");
1579 Docextract::new(&out)
1580 .unwrap()
1581 .input(&first)
1582 .unwrap()
1583 .input(&second)
1584 .unwrap()
1585 .done()
1586 .unwrap();
1587 assert_eq!(read_str(&out), "Only once\n");
1588 }
1589
1590 #[test]
1591 fn b25_empty_output_path_errors() {
1592 let result = Docextract::new("");
1594 assert!(result.is_err());
1595 }
1596
1597 #[test]
1598 fn b26_file_vs_stdout_output_paths() {
1599 let tmp = TempDir::new("b26");
1601 let src = tmp.write("in.rs", "//// Doc\n");
1602 let out = tmp.file("out.md");
1603 {
1604 Docextract::new(&out)
1605 .unwrap()
1606 .input(&src)
1607 .unwrap()
1608 .done()
1609 .unwrap();
1610 }
1611 assert!(out.exists());
1612 assert_eq!(read_str(&out), "Doc\n");
1613 let string_path: String = tmp
1614 .write("str.rs", "//// String Doc\n")
1615 .to_string_lossy()
1616 .into_owned();
1617 let out2 = tmp.file("out2.md");
1618 {
1619 Docextract::new(&out2)
1620 .unwrap()
1621 .input(string_path)
1622 .unwrap()
1623 .done()
1624 .unwrap();
1625 }
1626 assert_eq!(read_str(&out2), "String Doc\n");
1627 {
1628 Docextract::new("-")
1629 .unwrap()
1630 .input(&src)
1631 .unwrap()
1632 .done()
1633 .unwrap();
1634 }
1635 assert!(
1636 !std::path::Path::new("-").exists(),
1637 "stdout target must not create a file named '-' in the working directory"
1638 );
1639 }
1640
1641 #[test]
1642 fn b27_mid_stream_error_preserves_earlier_output() {
1643 let tmp = TempDir::new("b27");
1646 let good = tmp.write("good.rs", "//// From Good\n");
1647 let bad_dir = tmp.file("bad");
1648 fs::create_dir_all(&bad_dir).unwrap();
1649 let out = tmp.file("out.md");
1650 let mut builder = Docextract::new(&out).unwrap();
1651 builder.input(&good).unwrap();
1652 assert!(builder.input(&bad_dir).is_err());
1653 builder.done().unwrap();
1654 assert_eq!(read_str(&out), "From Good\n");
1655 }
1656
1657 #[test]
1658 fn b28_all_doc_line_types_in_one_file() {
1659 let tmp = TempDir::new("b28");
1664 let src = tmp.write(
1665 "all.rs",
1666 "//// First\n////\n//// Second\nlet x = 1;\n\t//// Tab Sep\n////\tTab Content\n//// Two Spaces\n////Bad\n///// five\n////",
1667 );
1668 let out = tmp.file("out.md");
1669 Docextract::new(&out)
1670 .unwrap()
1671 .input(&src)
1672 .unwrap()
1673 .done()
1674 .unwrap();
1675 assert_eq!(
1679 read_str(&out),
1680 "First\n\nSecond\nTab Sep\nTab Content\n Two Spaces\n"
1681 );
1682 }
1683
1684 #[test]
1685 #[cfg(target_os = "linux")]
1686 fn b29_done_flush_error_returns_err() {
1687 let tmp = TempDir::new("b29");
1689 let src = tmp.write("in.rs", "//// Doc\n");
1690 let mut builder = Docextract::new("/dev/full").unwrap();
1691 builder.input(&src).unwrap();
1692 assert!(builder.done().is_err());
1693 }
1694
1695 #[test]
1696 fn b30_all_inputs_missing_warns_and_creates_empty_output() {
1697 let tmp = TempDir::new("b30");
1699 let out = tmp.file("out.md");
1700 let mut builder = Docextract::new(&out).unwrap();
1701 assert!(builder.input(tmp.file("m1.rs")).is_ok());
1702 assert!(builder.input(tmp.file("m2.rs")).is_ok());
1703 builder.done().unwrap();
1704 assert!(out.exists());
1705 assert_eq!(read_str(&out), "");
1706 }
1707
1708 #[test]
1709 fn b31_out_dir_auto_detect_set_and_clear() {
1710 let tmp = TempDir::new("b31");
1712 let src = tmp.write("in.rs", "//// Doc\n");
1713 let out_set = tmp.file("out-set.md");
1714 {
1715 let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
1716 Docextract::new(&out_set)
1717 .unwrap()
1718 .input(&src)
1719 .unwrap()
1720 .done()
1721 .unwrap();
1722 }
1723 let out_clear = tmp.file("out-clear.md");
1724 {
1725 let _guard = OutDirGuard::with(None);
1726 Docextract::new(&out_clear)
1727 .unwrap()
1728 .input(&src)
1729 .unwrap()
1730 .done()
1731 .unwrap();
1732 }
1733 assert_eq!(read_str(&out_set), "Doc\n");
1734 assert_eq!(read_str(&out_clear), "Doc\n");
1735 assert_eq!(read_str(&out_set), read_str(&out_clear));
1736 }
1737
1738 #[test]
1739 fn b32_non_notfound_open_error_returns_err() {
1740 let tmp = TempDir::new("b32");
1742 let out = tmp.file("out.md");
1743 let mut builder = Docextract::new(&out).unwrap();
1744 let nul_path = PathBuf::from("docextract-nul\0path");
1745 assert!(builder.input(nul_path).is_err());
1746 builder.done().unwrap();
1747 }
1748
1749 #[test]
1750 #[cfg(target_os = "linux")]
1751 fn b33_drop_flush_error_reports_to_stderr() {
1752 if std::env::var_os("DOCEXTRACT_SUBPROCESS").is_some() {
1755 let tmp = TempDir::new("b33-child");
1757 let src = tmp.write("in.rs", "//// Doc\n");
1758 let mut builder = Docextract::new("/dev/full").unwrap();
1759 builder.input(&src).unwrap();
1760 return;
1762 }
1763 let exe = std::env::current_exe().unwrap();
1765 let output = std::process::Command::new(&exe)
1766 .env("DOCEXTRACT_SUBPROCESS", "1")
1767 .arg("--exact")
1768 .arg("tests::b33_drop_flush_error_reports_to_stderr")
1769 .arg("--nocapture")
1770 .output()
1771 .unwrap();
1772 assert!(
1773 output.status.success(),
1774 "child test binary must exit 0, got {:?}",
1775 output.status
1776 );
1777 let stderr = String::from_utf8_lossy(&output.stderr);
1778 assert!(
1779 stderr.contains("docextract: error: output:"),
1780 "Drop flush error must be printed to stderr, got: {stderr}"
1781 );
1782 }
1783
1784 mod tag_filter {
1793 use super::*;
1794 use crate::pattern::Pattern;
1795 #[cfg(feature = "regex")]
1796 use crate::pattern::PatternError;
1797 use std::rc::Rc;
1798
1799 fn assert_entries(actual: &[DocEntry], expected: &[(&str, &str, bool)]) {
1802 assert_eq!(
1803 actual.len(),
1804 expected.len(),
1805 "entry count mismatch: got {} expected {}",
1806 actual.len(),
1807 expected.len()
1808 );
1809 for (entry, (tag, text, transient)) in actual.iter().zip(expected) {
1810 assert_eq!(&*entry.tag, *tag, "tag mismatch");
1811 assert_eq!(&*entry.text, *text, "text mismatch");
1812 assert_eq!(entry.transient, *transient, "transient mismatch");
1813 }
1814 }
1815
1816 fn assert_tags(tags: &HashSet<Rc<str>>, expected: &[&str]) {
1818 assert_eq!(tags.len(), expected.len(), "interning pool size mismatch");
1819 for &name in expected {
1820 assert!(tags.contains(name), "tag {name:?} missing from pool");
1821 }
1822 }
1823
1824 #[test]
1827 fn p01_simple_doc_line() {
1828 let mut tags = HashSet::new();
1830 let entries = parse_doc_entries(&mut tags, "//// Hello\n", "lib");
1831 assert_entries(&entries, &[("lib", "Hello\n", false)]);
1832 assert_tags(&tags, &["lib"]);
1833 }
1834
1835 #[test]
1836 fn p02_four_space_indent() {
1837 let mut tags = HashSet::new();
1839 let entries = parse_doc_entries(&mut tags, " //// Hello\n", "lib");
1840 assert_entries(&entries, &[("lib", "Hello\n", false)]);
1841 assert_tags(&tags, &["lib"]);
1842 }
1843
1844 #[test]
1845 fn p03_tab_indent() {
1846 let mut tags = HashSet::new();
1848 let entries = parse_doc_entries(&mut tags, "\t//// Hello\n", "lib");
1849 assert_entries(&entries, &[("lib", "Hello\n", false)]);
1850 assert_tags(&tags, &["lib"]);
1851 }
1852
1853 #[test]
1854 fn p04_tab_separator() {
1855 let mut tags = HashSet::new();
1857 let entries = parse_doc_entries(&mut tags, "////\tHello\n", "lib");
1858 assert_entries(&entries, &[("lib", "Hello\n", false)]);
1859 assert_tags(&tags, &["lib"]);
1860 }
1861
1862 #[test]
1863 fn p05_empty_doc_line_newline() {
1864 let mut tags = HashSet::new();
1866 let entries = parse_doc_entries(&mut tags, "////\n", "lib");
1867 assert_entries(&entries, &[("lib", "\n", false)]);
1868 assert_tags(&tags, &["lib"]);
1869 }
1870
1871 #[test]
1872 fn p06_empty_doc_line_space_newline() {
1873 let mut tags = HashSet::new();
1875 let entries = parse_doc_entries(&mut tags, "//// \n", "lib");
1876 assert_entries(&entries, &[("lib", "\n", false)]);
1877 assert_tags(&tags, &["lib"]);
1878 }
1879
1880 #[test]
1881 fn p07_empty_doc_line_at_eof() {
1882 let mut tags = HashSet::new();
1884 let entries = parse_doc_entries(&mut tags, "////", "lib");
1885 assert_entries(&entries, &[("lib", "", false)]);
1886 assert_tags(&tags, &["lib"]);
1887 }
1888
1889 #[test]
1890 fn p08_crlf_preserved() {
1891 let mut tags = HashSet::new();
1893 let entries = parse_doc_entries(&mut tags, "//// Hello\r\n", "lib");
1894 assert_entries(&entries, &[("lib", "Hello\r\n", false)]);
1895 assert_tags(&tags, &["lib"]);
1896 }
1897
1898 #[test]
1899 fn p09_three_spaces_first_is_separator() {
1900 let mut tags = HashSet::new();
1902 let entries = parse_doc_entries(&mut tags, "//// \n", "lib");
1903 assert_entries(&entries, &[("lib", " \n", false)]);
1904 assert_tags(&tags, &["lib"]);
1905 }
1906
1907 #[test]
1908 fn p10_two_spaces_second_preserved() {
1909 let mut tags = HashSet::new();
1911 let entries = parse_doc_entries(&mut tags, "//// Two Spaces\n", "lib");
1912 assert_entries(&entries, &[("lib", " Two Spaces\n", false)]);
1913 assert_tags(&tags, &["lib"]);
1914 }
1915
1916 #[test]
1917 fn p11_long_doc_line_preserved_verbatim() {
1918 let content = "x".repeat(300);
1920 let input = format!("//// {content}\n");
1921 let mut tags = HashSet::new();
1922 let entries = parse_doc_entries(&mut tags, &input, "myfile");
1923 assert_entries(&entries, &[("myfile", &format!("{content}\n"), false)]);
1924 assert_tags(&tags, &["myfile"]);
1925 }
1926
1927 #[test]
1928 fn p12_five_slashes_ignored() {
1929 let mut tags = HashSet::new();
1931 let entries = parse_doc_entries(&mut tags, "/////\n", "lib");
1932 assert_entries(&entries, &[]);
1933 assert_tags(&tags, &["lib"]);
1934 }
1935
1936 #[test]
1937 fn p13_six_slashes_ignored() {
1938 let mut tags = HashSet::new();
1940 let entries = parse_doc_entries(&mut tags, "//////\n", "lib");
1941 assert_entries(&entries, &[]);
1942 assert_tags(&tags, &["lib"]);
1943 }
1944
1945 #[test]
1946 fn p14_three_slashes_ignored() {
1947 let mut tags = HashSet::new();
1949 let entries = parse_doc_entries(&mut tags, "///\n", "lib");
1950 assert_entries(&entries, &[]);
1951 assert_tags(&tags, &["lib"]);
1952 }
1953
1954 #[test]
1955 fn p15_non_four_slash_prefix_ignored() {
1956 let mut tags = HashSet::new();
1958 let entries = parse_doc_entries(&mut tags, "X///\nfn main() {}\n", "lib");
1959 assert_entries(&entries, &[]);
1960 assert_tags(&tags, &["lib"]);
1961 }
1962
1963 #[test]
1964 fn p16_whitespace_only_line_at_eof_ignored() {
1965 let mut tags = HashSet::new();
1968 let entries = parse_doc_entries(&mut tags, " ", "lib");
1969 assert_entries(&entries, &[]);
1970 assert_tags(&tags, &["lib"]);
1971 }
1972
1973 #[test]
1974 fn p17_mixed_indent() {
1975 let mut tags = HashSet::new();
1977 let entries = parse_doc_entries(&mut tags, " \t//// Hello\n", "lib");
1978 assert_entries(&entries, &[("lib", "Hello\n", false)]);
1979 assert_tags(&tags, &["lib"]);
1980 }
1981
1982 #[test]
1983 fn p18_space_separator_at_eof() {
1984 let mut tags = HashSet::new();
1986 let entries = parse_doc_entries(&mut tags, "//// ", "lib");
1987 assert_entries(&entries, &[("lib", "", false)]);
1988 assert_tags(&tags, &["lib"]);
1989 }
1990
1991 #[test]
1992 fn p19_tab_separator_at_eof() {
1993 let mut tags = HashSet::new();
1995 let entries = parse_doc_entries(&mut tags, "////\t", "lib");
1996 assert_entries(&entries, &[("lib", "", false)]);
1997 assert_tags(&tags, &["lib"]);
1998 }
1999
2000 #[test]
2001 fn p20_crlf_without_separator() {
2002 let mut tags = HashSet::new();
2004 let entries = parse_doc_entries(&mut tags, "////\r\n", "lib");
2005 assert_entries(&entries, &[("lib", "\r\n", false)]);
2006 assert_tags(&tags, &["lib"]);
2007 }
2008
2009 #[test]
2010 fn p21_cr_at_eof() {
2011 let mut tags = HashSet::new();
2013 let entries = parse_doc_entries(&mut tags, "////\r", "lib");
2014 assert_entries(&entries, &[("lib", "\r", false)]);
2015 assert_tags(&tags, &["lib"]);
2016 }
2017
2018 #[test]
2019 fn p22_persistent_tag_switch() {
2020 let mut tags = HashSet::new();
2023 let entries = parse_doc_entries(&mut tags, "////foo\n", "lib");
2024 assert_entries(&entries, &[]);
2025 assert_tags(&tags, &["lib", "foo"]);
2026 }
2027
2028 #[test]
2029 fn p23_persistent_tag_switch_chapter1() {
2030 let mut tags = HashSet::new();
2032 let entries = parse_doc_entries(&mut tags, "////chapter1\n", "lib");
2033 assert_entries(&entries, &[]);
2034 assert_tags(&tags, &["lib", "chapter1"]);
2035 }
2036
2037 #[test]
2038 fn p24_transient_tag_with_text() {
2039 let mut tags = HashSet::new();
2042 let entries = parse_doc_entries(&mut tags, "////foo bar baz\n", "lib");
2043 assert_entries(&entries, &[("foo", "bar baz\n", true)]);
2044 assert_tags(&tags, &["lib", "foo"]);
2045 }
2046
2047 #[test]
2048 fn p25_transient_tag_glossary() {
2049 let mut tags = HashSet::new();
2051 let entries = parse_doc_entries(&mut tags, "////glossary example\n", "lib");
2052 assert_entries(&entries, &[("glossary", "example\n", true)]);
2053 assert_tags(&tags, &["lib", "glossary"]);
2054 }
2055
2056 #[test]
2057 fn p26_tag_with_hyphen() {
2058 let mut tags = HashSet::new();
2060 let entries = parse_doc_entries(&mut tags, "////tag-name\n", "lib");
2061 assert_entries(&entries, &[]);
2062 assert_tags(&tags, &["lib", "tag-name"]);
2063 }
2064
2065 #[test]
2066 fn p27_tag_with_dot() {
2067 let mut tags = HashSet::new();
2069 let entries = parse_doc_entries(&mut tags, "////tag.name\n", "lib");
2070 assert_entries(&entries, &[]);
2071 assert_tags(&tags, &["lib", "tag.name"]);
2072 }
2073
2074 #[test]
2075 fn p28_hash_tag() {
2076 let mut tags = HashSet::new();
2078 let entries = parse_doc_entries(&mut tags, "////### Heading\n", "lib");
2079 assert_entries(&entries, &[("###", "Heading\n", true)]);
2080 assert_tags(&tags, &["lib", "###"]);
2081 }
2082
2083 #[test]
2084 fn p29_numeric_tag() {
2085 let mut tags = HashSet::new();
2087 let entries = parse_doc_entries(&mut tags, "////42\n", "lib");
2088 assert_entries(&entries, &[]);
2089 assert_tags(&tags, &["lib", "42"]);
2090 }
2091
2092 #[test]
2093 fn p30_indented_tag_directive() {
2094 let mut tags = HashSet::new();
2096 let entries = parse_doc_entries(&mut tags, " ////foo\n", "lib");
2097 assert_entries(&entries, &[]);
2098 assert_tags(&tags, &["lib", "foo"]);
2099 }
2100
2101 #[test]
2102 fn p31_hello_repurposed_case_e() {
2103 let mut tags = HashSet::new();
2106 let entries = parse_doc_entries(&mut tags, "////Hello\n", "lib");
2107 assert_entries(&entries, &[]);
2108 assert_tags(&tags, &["lib", "Hello"]);
2109 }
2110
2111 #[test]
2112 fn p32_persistent_switch_then_doc_line() {
2113 let mut tags = HashSet::new();
2116 let entries = parse_doc_entries(&mut tags, "////foo\n//// bar\n", "lib");
2117 assert_entries(&entries, &[("foo", "bar\n", false)]);
2118 assert_tags(&tags, &["lib", "foo"]);
2119 }
2120
2121 #[test]
2122 fn p33_transient_does_not_change_current_tag() {
2123 let mut tags = HashSet::new();
2126 let entries =
2127 parse_doc_entries(&mut tags, "////foo\n////baz text\n//// after\n", "lib");
2128 assert_entries(
2129 &entries,
2130 &[("baz", "text\n", true), ("foo", "after\n", false)],
2131 );
2132 assert_tags(&tags, &["lib", "foo", "baz"]);
2133 }
2134
2135 #[test]
2136 fn p34_tag_interning_shared_rc() {
2137 let mut tags = HashSet::new();
2140 let entries = parse_doc_entries(&mut tags, "//// a\n//// b\n//// c\n", "mod");
2141 assert_eq!(entries.len(), 3);
2142 assert!(Rc::ptr_eq(&entries[0].tag, &entries[1].tag));
2143 assert!(Rc::ptr_eq(&entries[1].tag, &entries[2].tag));
2144 assert_tags(&tags, &["mod"]);
2145 }
2146
2147 #[test]
2148 fn p35_stdin_initial_tag() {
2149 let mut tags = HashSet::new();
2151 let entries = parse_doc_entries(&mut tags, "//// hello\n", "-");
2152 assert_entries(&entries, &[("-", "hello\n", false)]);
2153 assert_tags(&tags, &["-"]);
2154 }
2155
2156 #[test]
2157 fn p36_no_doc_lines() {
2158 let mut tags = HashSet::new();
2160 let entries = parse_doc_entries(&mut tags, "fn main() {\n let x = 1;\n}\n", "lib");
2161 assert_entries(&entries, &[]);
2162 assert_tags(&tags, &["lib"]);
2163 }
2164
2165 #[test]
2166 fn p37_doc_at_eof_without_newline() {
2167 let mut tags = HashSet::new();
2170 let entries = parse_doc_entries(&mut tags, "//// text\n////", "lib");
2171 assert_entries(&entries, &[("lib", "text\n", false), ("lib", "", false)]);
2172 assert_tags(&tags, &["lib"]);
2173 }
2174
2175 #[cfg(not(feature = "regex"))]
2178 mod simple_matcher {
2179 use super::*;
2180
2181 fn m(pattern: &str, target: &str) -> bool {
2184 Pattern::new(pattern).unwrap().matches(target)
2185 }
2186
2187 #[test]
2188 fn g01_star_matches_everything() {
2189 assert!(m(".*", "anything"));
2190 }
2191
2192 #[test]
2193 fn g02_star_matches_empty() {
2194 assert!(m(".*", ""));
2195 }
2196
2197 #[test]
2198 fn g03_literal_exact_match() {
2199 assert!(m("foo", "foo"));
2200 }
2201
2202 #[test]
2203 fn g04_literal_no_match() {
2204 assert!(!m("foo", "bar"));
2205 }
2206
2207 #[test]
2208 fn g05_prefix_then_star() {
2209 assert!(m("foo.*", "foobar"));
2210 }
2211
2212 #[test]
2213 fn g06_prefix_then_star_wrong_target() {
2214 assert!(!m("foo.*", "barfoo"));
2215 }
2216
2217 #[test]
2218 fn g07_star_then_suffix() {
2219 assert!(m(".*foo", "barfoo"));
2220 }
2221
2222 #[test]
2223 fn g08_star_sandwich() {
2224 assert!(m(".*foo.*", "barfoobaz"));
2225 }
2226
2227 #[test]
2228 fn g09_optional_any_single_char() {
2229 assert!(m(".?", "a"));
2230 }
2231
2232 #[test]
2233 fn g10_optional_any_empty() {
2234 assert!(m(".?", ""));
2235 }
2236
2237 #[test]
2238 fn g11_optional_any_two_chars() {
2239 assert!(!m(".?", "ab"));
2240 }
2241
2242 #[test]
2243 fn g12_optional_any_middle_filled() {
2244 assert!(m("f.?o", "foo"));
2245 }
2246
2247 #[test]
2248 fn g13_optional_any_middle_other() {
2249 assert!(m("f.?o", "fao"));
2250 }
2251
2252 #[test]
2253 fn g14_optional_any_middle_omitted() {
2254 assert!(m("f.?o", "fo"));
2255 }
2256
2257 #[test]
2258 fn g15_chapter_optional_digit() {
2259 assert!(m("chapter.?", "chapter1"));
2260 }
2261
2262 #[test]
2263 fn g16_chapter_optional_omitted() {
2264 assert!(m("chapter.?", "chapter"));
2265 }
2266
2267 #[test]
2268 fn g17_character_class_member() {
2269 assert!(m("[abc]", "a"));
2270 }
2271
2272 #[test]
2273 fn g18_character_class_non_member() {
2274 assert!(!m("[abc]", "d"));
2275 }
2276
2277 #[test]
2278 fn g19_character_class_range() {
2279 assert!(m("[a-z]", "m"));
2280 }
2281
2282 #[test]
2283 fn g20_character_class_range_case_sensitive() {
2284 assert!(!m("[a-z]", "M"));
2285 }
2286
2287 #[test]
2288 fn g21_negated_class_matches_outside() {
2289 assert!(m("[^abc]", "d"));
2290 }
2291
2292 #[test]
2293 fn g22_negated_class_rejects_member() {
2294 assert!(!m("[^abc]", "a"));
2295 }
2296
2297 #[test]
2298 fn g23_escaped_dot_matches_dot() {
2299 assert!(m("\\.", "."));
2300 }
2301
2302 #[test]
2303 fn g24_escaped_dot_rejects_other() {
2304 assert!(!m("\\.", "a"));
2305 }
2306
2307 #[test]
2308 fn g25_escaped_backslash_matches_backslash() {
2309 assert!(m("\\\\", "\\"));
2310 }
2311
2312 #[test]
2313 fn g26_empty_pattern_empty_target() {
2314 assert!(m("", ""));
2315 }
2316
2317 #[test]
2318 fn g27_empty_pattern_nonempty_target() {
2319 assert!(!m("", "a"));
2320 }
2321
2322 #[test]
2323 fn g28_multiple_stars() {
2324 assert!(m(".*.*", "abc"));
2325 }
2326
2327 #[test]
2328 fn g29_unclosed_bracket_matches_literal() {
2329 assert!(m("[", "["));
2330 }
2331
2332 #[test]
2333 fn g30_unclosed_range_literal_fallback() {
2334 assert!(!m("[a", "["));
2335 }
2336
2337 #[test]
2338 fn g31_star_then_optional() {
2339 assert!(m(".*.?", "a"));
2340 }
2341
2342 #[test]
2343 fn g32_optional_then_star() {
2344 assert!(m(".?.*", "abc"));
2345 }
2346
2347 #[test]
2348 fn g33_unquantified_class_not_empty() {
2349 assert!(!m("[abc]", ""));
2350 }
2351 }
2352
2353 #[cfg(feature = "regex")]
2356 mod regex_matcher {
2357 use super::*;
2358
2359 fn m(pattern: &str, target: &str) -> bool {
2362 Pattern::new(pattern).unwrap().matches(target)
2363 }
2364
2365 #[test]
2366 fn r01_posix_alpha_matches_letter() {
2367 assert!(m("[[:alpha:]]", "a"));
2368 }
2369
2370 #[test]
2371 fn r02_posix_alpha_rejects_digit() {
2372 assert!(!m("[[:alpha:]]", "9"));
2373 }
2374
2375 #[test]
2376 fn r03_alpha_alnum_star_bar() {
2377 assert!(m("[[:alpha:]][[:alnum:]]*_bar", "a1_bar"));
2378 }
2379
2380 #[test]
2381 fn r04_alpha_alnum_star_bar_long() {
2382 assert!(m("[[:alpha:]][[:alnum:]]*_bar", "a123foo_bar"));
2383 }
2384
2385 #[test]
2386 fn r05_alpha_alnum_star_bar_short() {
2387 assert!(m("[[:alpha:]][[:alnum:]]*_bar", "a_bar"));
2388 }
2389
2390 #[test]
2391 fn r06_alpha_alnum_star_bar_digit_start() {
2392 assert!(!m("[[:alpha:]][[:alnum:]]*_bar", "1_bar"));
2393 }
2394
2395 #[test]
2396 fn r07_alpha_alnum_star_bar_wrong_suffix() {
2397 assert!(!m("[[:alpha:]][[:alnum:]]*_bar", "a_baz"));
2398 }
2399
2400 #[test]
2401 fn r08_group_plus_repeated() {
2402 assert!(m("(foo)+", "foofoofoo"));
2403 }
2404
2405 #[test]
2406 fn r09_group_plus_single() {
2407 assert!(m("(foo)+", "foo"));
2408 }
2409
2410 #[test]
2411 fn r10_group_plus_empty() {
2412 assert!(!m("(foo)+", ""));
2413 }
2414
2415 #[test]
2416 fn r11_alternation_first_branch() {
2417 assert!(m("foo|bar", "foo"));
2418 }
2419
2420 #[test]
2421 fn r12_alternation_second_branch() {
2422 assert!(m("foo|bar", "bar"));
2423 }
2424
2425 #[test]
2426 fn r13_alternation_no_branch() {
2427 assert!(!m("foo|bar", "baz"));
2428 }
2429
2430 #[test]
2431 fn r14_digit_plus() {
2432 assert!(m("\\d+", "123"));
2433 }
2434
2435 #[test]
2436 fn r15_digit_plus_rejects_letters() {
2437 assert!(!m("\\d+", "abc"));
2438 }
2439
2440 #[test]
2441 fn r16_word_plus() {
2442 assert!(m("\\w+", "hello_world"));
2443 }
2444
2445 #[test]
2446 fn r17_exact_count_quantifier() {
2447 assert!(m("a{3}", "aaa"));
2448 }
2449
2450 #[test]
2451 fn r18_exact_count_quantifier_short() {
2452 assert!(!m("a{3}", "aa"));
2453 }
2454
2455 #[test]
2456 fn r19_non_capturing_group() {
2457 assert!(m("(?:foo)", "foo"));
2458 }
2459
2460 #[test]
2461 fn r20_unclosed_bracket_is_compile_error() {
2462 let result = Pattern::new("[");
2463 assert!(
2464 matches!(result, Err(PatternError::InvalidSyntax(_))),
2465 "unclosed character class must be a compile error"
2466 );
2467 }
2468
2469 #[test]
2470 fn r21_unclosed_paren_is_compile_error() {
2471 let result = Pattern::new("(");
2472 assert!(
2473 matches!(result, Err(PatternError::InvalidSyntax(_))),
2474 "unclosed group must be a compile error"
2475 );
2476 }
2477 }
2478
2479 #[test]
2482 fn f01_input_filtered_matches_tag() {
2483 let tmp = TempDir::new("f01");
2486 let src = tmp.write("file.rs", "////api intro\n//// core\n////api detail\n");
2487 let out = tmp.file("out.md");
2488 Docextract::new(&out)
2489 .unwrap()
2490 .input_filtered(&src, "api")
2491 .unwrap()
2492 .done()
2493 .unwrap();
2494 assert_eq!(read_str(&out), "intro\ndetail\n");
2495 }
2496
2497 #[test]
2498 fn f02_input_filtered_no_matching_tag() {
2499 let tmp = TempDir::new("f02");
2501 let src = tmp.write("file.rs", "//// core\n");
2502 let out = tmp.file("out.md");
2503 Docextract::new(&out)
2504 .unwrap()
2505 .input_filtered(&src, "api")
2506 .unwrap()
2507 .done()
2508 .unwrap();
2509 assert_eq!(read_str(&out), "");
2510 }
2511
2512 #[test]
2513 fn f03_output_filter_with_unfiltered_input() {
2514 let tmp = TempDir::new("f03");
2517 let src = tmp.write("file.rs", "////chapter1 a\n//// intro\n////chapter2 b\n");
2518 let out = tmp.file("out.md");
2519 Docextract::new(&out)
2520 .unwrap()
2521 .filter_output(Some("chapter.*"))
2522 .unwrap()
2523 .input(&src)
2524 .unwrap()
2525 .done()
2526 .unwrap();
2527 assert_eq!(read_str(&out), "a\nb\n");
2528 }
2529
2530 #[test]
2531 fn f04_output_and_input_filter_and_combine() {
2532 let tmp = TempDir::new("f04");
2535 let src = tmp.write("file.rs", "////chapter1 a\n////chapter2 b\n//// plain\n");
2536 let out = tmp.file("out.md");
2537 Docextract::new(&out)
2538 .unwrap()
2539 .filter_output(Some("chapter.*"))
2540 .unwrap()
2541 .input_filtered(&src, "chapter1")
2542 .unwrap()
2543 .done()
2544 .unwrap();
2545 assert_eq!(read_str(&out), "a\n");
2546 }
2547
2548 #[test]
2549 fn f05_reordering_via_multiple_filtered_reads() {
2550 let tmp = TempDir::new("f05");
2553 let src = tmp.write("f.rs", "////ch1 one\n////ch2 two\n////ch1 three\n");
2554 let out = tmp.file("out.md");
2555 let mut builder = Docextract::new(&out).unwrap();
2556 builder.input_filtered(&src, "ch1").unwrap();
2557 fs::write(&src, "////ch1 REWRITTEN\n").unwrap();
2559 builder.input_filtered(&src, "ch1").unwrap();
2560 builder.input_filtered(&src, "ch2").unwrap();
2561 builder.done().unwrap();
2562 assert_eq!(read_str(&out), "one\nthree\none\nthree\ntwo\n");
2563 }
2564
2565 #[test]
2566 fn f06_filtered_then_unfiltered_rerun() {
2567 let tmp = TempDir::new("f06");
2571 let src = tmp.write("f.rs", "////ch1 one\n//// plain\n");
2572 let out = tmp.file("out.md");
2573 Docextract::new(&out)
2574 .unwrap()
2575 .input_filtered(&src, "ch1")
2576 .unwrap()
2577 .input(&src)
2578 .unwrap()
2579 .done()
2580 .unwrap();
2581 assert_eq!(read_str(&out), "one\nplain\n");
2582 }
2583
2584 #[test]
2585 fn f07_unfiltered_backward_compat() {
2586 let tmp = TempDir::new("f07");
2590 let src = tmp.write("file.rs", "//// hello\n//// world\n");
2591 let out = tmp.file("out.md");
2592 Docextract::new(&out)
2593 .unwrap()
2594 .input(&src)
2595 .unwrap()
2596 .done()
2597 .unwrap();
2598 assert_eq!(read_str(&out), "hello\nworld\n");
2599 }
2600
2601 #[test]
2602 fn f08_stdin_unfiltered_backward_compat() {
2603 let tmp = TempDir::new("f08");
2606 let src = tmp.write("stdin-content.txt", "//// persistent\n////t transient\n");
2607 let out = tmp.file("out.md");
2608 Docextract::new(&out)
2609 .unwrap()
2610 .input(&src)
2611 .unwrap()
2612 .done()
2613 .unwrap();
2614 assert_eq!(read_str(&out), "persistent\n");
2615 }
2616
2617 #[test]
2618 fn f09_rerun_if_changed_emitted_once() {
2619 if std::env::var_os("DOCEXTRACT_F09_SUBPROCESS").is_some() {
2622 let tmp = TempDir::new("f09-child");
2625 let src = tmp.write("in.rs", "////api doc\n");
2626 let out = tmp.file("out.md");
2627 let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
2628 let mut builder = Docextract::new(&out).unwrap();
2629 builder.input_filtered(&src, "api").unwrap(); builder.input_filtered(&src, "api").unwrap(); builder.done().unwrap();
2632 return;
2633 }
2634 let exe = std::env::current_exe().unwrap();
2636 let output = std::process::Command::new(&exe)
2637 .env("DOCEXTRACT_F09_SUBPROCESS", "1")
2638 .arg("--exact")
2639 .arg("tests::tag_filter::f09_rerun_if_changed_emitted_once")
2640 .arg("--nocapture")
2641 .output()
2642 .unwrap();
2643 assert!(
2644 output.status.success(),
2645 "child test binary must exit 0, got {:?}",
2646 output.status
2647 );
2648 let stdout = String::from_utf8_lossy(&output.stdout);
2649 let directive_count = stdout.matches("cargo:rerun-if-changed=").count();
2650 assert_eq!(
2651 directive_count, 1,
2652 "rerun-if-changed must be emitted exactly once (first access only), got: {stdout}"
2653 );
2654 }
2655
2656 #[test]
2657 fn f10_persistent_tag_switch_mid_file() {
2658 let tmp = TempDir::new("f10");
2661 let src = tmp.write("f.rs", "//// first\n////sec\n//// second\n");
2662 let out = tmp.file("out.md");
2663 let mut builder = Docextract::new(&out).unwrap();
2664 builder.input(&src).unwrap(); builder.input_filtered(&src, "sec").unwrap(); builder.done().unwrap();
2667 assert_eq!(read_str(&out), "first\nsecond\nsecond\n");
2668 }
2669
2670 #[test]
2671 fn f11_transient_skipped_when_unfiltered() {
2672 let tmp = TempDir::new("f11");
2674 let src = tmp.write("f.rs", "////t text\n//// regular\n");
2675 let out = tmp.file("out.md");
2676 Docextract::new(&out)
2677 .unwrap()
2678 .input(&src)
2679 .unwrap()
2680 .done()
2681 .unwrap();
2682 assert_eq!(read_str(&out), "regular\n");
2683 }
2684
2685 #[test]
2686 fn f11a_transient_included_when_filter_matches() {
2687 let tmp = TempDir::new("f11a");
2690 let src = tmp.write("f.rs", "////t text\n//// regular\n");
2691 let out = tmp.file("out.md");
2692 Docextract::new(&out)
2693 .unwrap()
2694 .input_filtered(&src, "t")
2695 .unwrap()
2696 .done()
2697 .unwrap();
2698 assert_eq!(read_str(&out), "text\n");
2699 }
2700
2701 #[test]
2702 fn f12_initial_tag_from_filename_stem() {
2703 let tmp = TempDir::new("f12");
2705 let src = tmp.write("lib.rs", "//// hello\n");
2706 let out = tmp.file("out.md");
2707 Docextract::new(&out)
2708 .unwrap()
2709 .input_filtered(&src, "lib")
2710 .unwrap()
2711 .done()
2712 .unwrap();
2713 assert_eq!(read_str(&out), "hello\n");
2714 }
2715
2716 #[test]
2717 fn f13_nonmatching_filter_empty_output() {
2718 let tmp = TempDir::new("f13");
2720 let src = tmp.write("f.rs", "//// hello\n");
2721 let out = tmp.file("out.md");
2722 Docextract::new(&out)
2723 .unwrap()
2724 .input_filtered(&src, "nonexistent")
2725 .unwrap()
2726 .done()
2727 .unwrap();
2728 assert_eq!(read_str(&out), "");
2729 }
2730
2731 #[test]
2732 fn f14_filter_output_none_clears_filter() {
2733 let tmp = TempDir::new("f14");
2735 let src = tmp.write("f.rs", "////api a\n//// plain\n");
2736 let out = tmp.file("out.md");
2737 let mut builder = Docextract::new(&out).unwrap();
2738 builder.filter_output(Some("api")).unwrap();
2739 builder.input(&src).unwrap();
2740 builder.filter_output(None).unwrap();
2741 builder.input(&src).unwrap();
2742 builder.done().unwrap();
2743 assert_eq!(read_str(&out), "a\nplain\n");
2744 }
2745
2746 #[test]
2747 fn f15_empty_file_with_filter() {
2748 let tmp = TempDir::new("f15");
2750 let src = tmp.write("empty.rs", "");
2751 let out = tmp.file("out.md");
2752 Docextract::new(&out)
2753 .unwrap()
2754 .input_filtered(&src, "api")
2755 .unwrap()
2756 .done()
2757 .unwrap();
2758 assert_eq!(read_str(&out), "");
2759 }
2760
2761 #[test]
2762 fn f16_only_tag_directives_no_output() {
2763 let tmp = TempDir::new("f16");
2765 let src = tmp.write("f.rs", "////api\n////chapter1\n");
2766 let out = tmp.file("out.md");
2767 Docextract::new(&out)
2768 .unwrap()
2769 .input(&src)
2770 .unwrap()
2771 .done()
2772 .unwrap();
2773 assert_eq!(read_str(&out), "");
2774 }
2775
2776 #[test]
2777 fn f17_tag_with_special_chars() {
2778 let tmp = TempDir::new("f17");
2780 let src = tmp.write("f.rs", "////my-tag.v2! entry\n//// plain\n");
2781 let out = tmp.file("out.md");
2782 Docextract::new(&out)
2783 .unwrap()
2784 .input_filtered(&src, "my-tag.*")
2785 .unwrap()
2786 .done()
2787 .unwrap();
2788 assert_eq!(read_str(&out), "entry\n");
2789 }
2790
2791 #[test]
2792 fn f18_consecutive_tag_switches_no_output() {
2793 let tmp = TempDir::new("f18");
2796 let src = tmp.write("f.rs", "////a\n////b\n////c\n");
2797 let out = tmp.file("out.md");
2798 Docextract::new(&out)
2799 .unwrap()
2800 .input(&src)
2801 .unwrap()
2802 .done()
2803 .unwrap();
2804 assert_eq!(read_str(&out), "");
2805 }
2806
2807 #[test]
2808 fn f19_transient_then_transient_current_tag_unchanged() {
2809 let tmp = TempDir::new("f19");
2813 let src = tmp.write("f.rs", "////t1 one\n////t2 two\n//// final\n");
2814 let out = tmp.file("out.md");
2815 let mut builder = Docextract::new(&out).unwrap();
2816 builder.input_filtered(&src, "f").unwrap(); builder.input_filtered(&src, ".*").unwrap(); builder.done().unwrap();
2819 assert_eq!(read_str(&out), "final\none\ntwo\nfinal\n");
2820 }
2821
2822 #[test]
2823 fn f20_no_separator_between_tag_changes() {
2824 let tmp = TempDir::new("f20");
2827 let src = tmp.write("f.rs", "////a one\n////b two\n");
2828 let out = tmp.file("out.md");
2829 Docextract::new(&out)
2830 .unwrap()
2831 .input_filtered(&src, ".*")
2832 .unwrap()
2833 .done()
2834 .unwrap();
2835 assert_eq!(read_str(&out), "one\ntwo\n");
2836 }
2837
2838 #[test]
2839 fn f21_explicit_blank_doc_line() {
2840 let tmp = TempDir::new("f21");
2842 let src = tmp.write("f.rs", "//// one\n////\n//// two\n");
2843 let out = tmp.file("out.md");
2844 Docextract::new(&out)
2845 .unwrap()
2846 .input(&src)
2847 .unwrap()
2848 .done()
2849 .unwrap();
2850 assert_eq!(read_str(&out), "one\n\ntwo\n");
2851 }
2852
2853 #[test]
2854 fn f22_large_file_filtered_extraction() {
2855 let tmp = TempDir::new("f22");
2858 let mut content = String::new();
2859 let mut expected = String::new();
2860 for i in 0..20_000 {
2861 let text = format!("line {i} {}\n", "x".repeat(40));
2862 let tag = if i % 2 == 0 { "a" } else { "b" };
2863 let _ = write!(content, "////{tag} {text}");
2864 if tag == "a" {
2865 expected.push_str(&text);
2866 }
2867 }
2868 assert!(content.len() >= 1_000_000, "source should be ~1 MiB");
2869 let src = tmp.write("big.rs", &content);
2870 let out = tmp.file("out.md");
2871 Docextract::new(&out)
2872 .unwrap()
2873 .input_filtered(&src, "a")
2874 .unwrap()
2875 .done()
2876 .unwrap();
2877 assert_eq!(read_str(&out), expected);
2878 }
2879
2880 #[test]
2881 fn f23_operation_after_done_returns_broken_pipe() {
2882 let tmp = TempDir::new("f23");
2885 let src = tmp.write("f.rs", "////api a\n");
2886 let out = tmp.file("out.md");
2887 let mut builder = Docextract::new(&out).unwrap();
2888 builder.done().unwrap();
2889 let Err(err) = builder.input_filtered(&src, "api") else {
2890 panic!("expected error after done()");
2891 };
2892 assert_eq!(err.kind(), std::io::ErrorKind::BrokenPipe);
2893 }
2894
2895 #[test]
2896 fn f24_blank_line_tagged_with_current_tag() {
2897 let tmp = TempDir::new("f24");
2900 let src = tmp.write("f.rs", "////\n////api\n////\n");
2901 let out = tmp.file("out.md");
2902 Docextract::new(&out)
2903 .unwrap()
2904 .input_filtered(&src, "api")
2905 .unwrap()
2906 .done()
2907 .unwrap();
2908 assert_eq!(read_str(&out), "\n");
2909 }
2910
2911 #[test]
2912 fn f25_missing_file_warns_and_continues() {
2913 let tmp = TempDir::new("f25");
2916 let valid = tmp.write("valid.rs", "////api kept\n");
2917 let out = tmp.file("out.md");
2918 let mut builder = Docextract::new(&out).unwrap();
2919 assert!(
2920 builder
2921 .input_filtered(tmp.file("missing.rs"), "api")
2922 .is_ok()
2923 );
2924 builder.input_filtered(&valid, "api").unwrap();
2925 builder.done().unwrap();
2926 assert_eq!(read_str(&out), "kept\n");
2927 }
2928
2929 #[test]
2930 fn f26_invalid_utf8_errors() {
2931 let tmp = TempDir::new("f26");
2934 let src = tmp.write_bytes("binary.rs", b"//// \xFF\xFE not utf8\n");
2935 let out = tmp.file("out.md");
2936 let mut builder = Docextract::new(&out).unwrap();
2937 let Err(err) = builder.input_filtered(&src, "api") else {
2938 panic!("expected error for invalid UTF-8");
2939 };
2940 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
2941 builder.done().unwrap();
2943 }
2944 }
2945
2946 mod code_lifting {
2954 use super::*;
2955
2956 #[test]
2959 fn s01_basic_split() {
2960 assert_eq!(
2962 try_split_code_capturing("code; //// {{}}"),
2963 Some(("code;", "{{}}"))
2964 );
2965 }
2966
2967 #[test]
2968 fn s02_trailing_spaces_stripped_from_code() {
2969 assert_eq!(
2972 try_split_code_capturing(" let x = 5; //// {{}}"),
2973 Some((" let x = 5;", "{{}}"))
2974 );
2975 }
2976
2977 #[test]
2978 fn s03_single_space_is_separator() {
2979 assert_eq!(
2982 try_split_code_capturing("fn foo() { //// {{}}"),
2983 Some(("fn foo() {", "{{}}"))
2984 );
2985 }
2986
2987 #[test]
2988 fn s04_tab_separator() {
2989 assert_eq!(
2991 try_split_code_capturing("code\t//// {{}}"),
2992 Some(("code", "{{}}"))
2993 );
2994 }
2995
2996 #[test]
2997 fn s05_empty_template() {
2998 assert_eq!(try_split_code_capturing("code ////"), Some(("code", "")));
3000 }
3001
3002 #[test]
3003 fn s06_no_separator_after_slashes() {
3004 assert_eq!(
3007 try_split_code_capturing("code ////text"),
3008 Some(("code", "text"))
3009 );
3010 }
3011
3012 #[test]
3013 fn s07_rightmost_double_slash_wins() {
3014 assert_eq!(
3017 try_split_code_capturing("code //// inner //// {{}}"),
3018 Some(("code //// inner", "{{}}"))
3019 );
3020 }
3021
3022 #[test]
3023 fn s08_double_slash_inside_string_literal() {
3024 assert_eq!(
3027 try_split_code_capturing(" let x = \"////\"; //// {{}}"),
3028 Some((" let x = \"////\";", "{{}}"))
3029 );
3030 }
3031
3032 #[test]
3033 fn s09_many_trailing_spaces_stripped() {
3034 assert_eq!(
3037 try_split_code_capturing("code; //// {{}}"),
3038 Some(("code;", "{{}}"))
3039 );
3040 }
3041
3042 #[test]
3043 fn s10_no_separator_before_slashes() {
3044 assert_eq!(try_split_code_capturing("code////no-separator"), None);
3047 }
3048
3049 #[test]
3052 fn r01_full_substitution_double_trim() {
3053 assert_eq!(resolve_placeholders("{{}}", " let x = 5;"), "let x = 5;");
3056 }
3057
3058 #[test]
3059 fn r02_full_substitution_plain_code() {
3060 assert_eq!(resolve_placeholders("{{}}", "code"), "code");
3062 }
3063
3064 #[test]
3065 fn r03_full_substitution_empty_code() {
3066 assert_eq!(resolve_placeholders("{{}}", ""), "");
3068 }
3069
3070 #[test]
3071 fn r04_zero_removal() {
3072 assert_eq!(resolve_placeholders("{{0}}", "code"), "code");
3074 }
3075
3076 #[test]
3077 fn r05_remove_four_chars() {
3078 assert_eq!(resolve_placeholders("{{4}}", " code"), "code");
3081 }
3082
3083 #[test]
3084 fn r06_remove_one_char() {
3085 assert_eq!(resolve_placeholders("{{1}}", "abc"), "bc");
3087 }
3088
3089 #[test]
3090 fn r07_n_greater_than_code_length() {
3091 assert_eq!(resolve_placeholders("{{3}}", "ab"), "");
3093 }
3094
3095 #[test]
3096 fn r08_n_much_greater_than_code_length() {
3097 assert_eq!(resolve_placeholders("{{100}}", "short"), "");
3099 }
3100
3101 #[test]
3102 fn r09_placeholder_with_surrounding_text() {
3103 assert_eq!(
3105 resolve_placeholders("prefix {{}} suffix", "code"),
3106 "prefix code suffix"
3107 );
3108 }
3109
3110 #[test]
3111 fn r10_same_code_multiple_placeholders() {
3112 assert_eq!(resolve_placeholders("{{}} and {{}}", "X"), "X and X");
3114 }
3115
3116 #[test]
3119 fn u01_multibyte_char_removed_by_count() {
3120 assert_eq!(resolve_placeholders("{{1}}", "éabc"), "abc");
3123 }
3124
3125 #[test]
3126 fn u02_two_multibyte_chars_removed() {
3127 assert_eq!(resolve_placeholders("{{2}}", "éàbc"), "bc");
3129 }
3130
3131 #[test]
3132 fn u03_astral_char_counts_once() {
3133 assert_eq!(resolve_placeholders("{{3}}", "a😀b"), "");
3136 }
3137
3138 #[test]
3139 fn u04_zero_removal_multibyte_unchanged() {
3140 assert_eq!(resolve_placeholders("{{0}}", "éabc"), "éabc");
3142 }
3143
3144 #[test]
3145 fn u05_n_greater_than_char_count() {
3146 assert_eq!(resolve_placeholders("{{4}}", "a😀b"), "");
3149 }
3150
3151 #[test]
3154 fn trim_leading_space_tab_strips_only_leading_ws() {
3155 assert_eq!(trim_leading_space_tab(" code"), "code");
3157 assert_eq!(trim_leading_space_tab("\tcode"), "code");
3158 assert_eq!(trim_leading_space_tab("code"), "code");
3159 assert_eq!(trim_leading_space_tab(""), "");
3160 }
3161
3162 #[test]
3169 fn unescape_delimiter_unescapes_only_delimiter() {
3170 assert_eq!(unescape_delimiter("foo\\/bar", b'/'), "foo/bar");
3173 assert_eq!(unescape_delimiter("baz/qux", b'/'), "baz/qux");
3174 }
3175
3176 fn assert_parse(input: &str, initial_tag: &str, expected: &[(&str, &str, bool)]) {
3181 let mut tags = HashSet::new();
3182 let entries = parse_doc_entries(&mut tags, input, initial_tag);
3183 assert_eq!(entries.len(), expected.len(), "entry count mismatch");
3184 for (entry, (tag, text, transient)) in entries.iter().zip(expected) {
3185 assert_eq!(&*entry.tag, *tag, "tag mismatch");
3186 assert_eq!(&*entry.text, *text, "text mismatch");
3187 assert_eq!(entry.transient, *transient, "transient mismatch");
3188 }
3189 }
3190
3191 #[test]
3192 fn e01_basic_substitution_with_double_trim() {
3193 assert_parse(
3197 " let x = 5; //// value: {{}}\n",
3198 "lib",
3199 &[("value:", "let x = 5;\n", true)],
3200 );
3201 }
3202
3203 #[test]
3204 fn e02_n_placeholder_character_removal() {
3205 assert_parse(
3207 " let x = 5; //// {{8}}\n",
3208 "lib",
3209 &[("lib", "x = 5;\n", false)],
3210 );
3211 }
3212
3213 #[test]
3214 fn e03_n_exceeds_code_length() {
3215 assert_parse(
3217 " let x = 5; //// {{100}}\n",
3218 "lib",
3219 &[("lib", "\n", false)],
3220 );
3221 }
3222
3223 #[test]
3224 fn e04_code_capture_between_doc_lines() {
3225 assert_parse(
3227 "//// # Before\n code; //// {{}}\n//// # After\n",
3228 "lib",
3229 &[
3230 ("lib", "# Before\n", false),
3231 ("lib", "code;\n", false),
3232 ("lib", "# After\n", false),
3233 ],
3234 );
3235 }
3236
3237 #[test]
3238 fn e05_back_to_back_code_captures() {
3239 assert_parse(
3241 " a; //// {{}}\n b; //// {{}}\n",
3242 "lib",
3243 &[("lib", "a;\n", false), ("lib", "b;\n", false)],
3244 );
3245 }
3246
3247 #[test]
3248 fn e06_template_with_no_placeholder() {
3249 assert_parse(
3253 " code; //// just text\n",
3254 "lib",
3255 &[("just", "text\n", true)],
3256 );
3257 }
3258
3259 #[test]
3260 fn e07_empty_template() {
3261 assert_parse(" code; ////\n", "lib", &[("lib", "\n", false)]);
3263 }
3264
3265 #[test]
3266 fn e08_multiple_placeholders() {
3267 assert_parse(" X; //// a{{}}b{{}}c\n", "lib", &[]);
3270 }
3271
3272 #[test]
3273 fn e09_unterminated_double_brace() {
3274 assert_parse(
3278 " X; //// text {{ oops\n",
3279 "lib",
3280 &[("text", "{{ oops\n", true)],
3281 );
3282 }
3283
3284 #[test]
3285 fn e10_code_capture_with_tag_directive() {
3286 assert_parse(
3288 "////foo\n code; //// {{}}\n",
3289 "lib",
3290 &[("foo", "code;\n", false)],
3291 );
3292 }
3293
3294 #[test]
3295 fn e11_backward_compat_doc_lines_only() {
3296 assert_parse(
3298 "//// Hello\n//// World\n",
3299 "lib",
3300 &[("lib", "Hello\n", false), ("lib", "World\n", false)],
3301 );
3302 }
3303
3304 #[test]
3305 fn e12_backward_compat_doc_with_code() {
3306 assert_parse(
3308 "//// Doc\nlet x = 5;\n//// More\n",
3309 "lib",
3310 &[("lib", "Doc\n", false), ("lib", "More\n", false)],
3311 );
3312 }
3313
3314 #[test]
3315 fn e13_doc_line_with_trailing_slashes_not_code_capture() {
3316 assert_parse(
3318 "//// This text ends with ////\n",
3319 "lib",
3320 &[("lib", "This text ends with ////\n", false)],
3321 );
3322 }
3323
3324 #[test]
3325 fn e14_tag_directive_not_code_capture() {
3326 assert_parse("////foo bar\n", "lib", &[("foo", "bar\n", true)]);
3328 }
3329
3330 #[test]
3331 fn e15_crlf_preserved() {
3332 assert_parse(
3334 "code; //// {{}}\r\n",
3335 "lib",
3336 &[("lib", "code;\r\n", false)],
3337 );
3338 }
3339
3340 #[test]
3341 fn e16_no_separator_before_slashes() {
3342 assert_parse("code////no-separator\n", "lib", &[]);
3344 }
3345
3346 #[test]
3347 #[should_panic(expected = "reserved placeholder form")]
3348 fn e17_reserved_form_panics() {
3349 let mut tags = HashSet::new();
3351 let _entries = parse_doc_entries(&mut tags, "code; //// {{abc}}\n", "lib");
3352 }
3353
3354 #[test]
3357 fn e18_capture_zone_continuation() {
3358 assert_parse(
3366 concat!(
3367 "//// lets show the internal code\n",
3368 "//// ```\n",
3369 " code //// {{}}\n",
3370 " //// {{4}} suffix\n",
3371 " more //// {{}}\n",
3372 "//// ```\n",
3373 ),
3374 "lib",
3375 &[
3376 ("lib", "lets show the internal code\n", false),
3377 ("lib", "```\n", false),
3378 ("lib", "code\n", false),
3379 ("lib", " suffix\n", false),
3381 ("lib", "more\n", false),
3382 ("lib", "```\n", false),
3383 ],
3384 );
3385 }
3386
3387 #[test]
3390 fn e19_transient_tag_on_code_capture() {
3391 assert_parse(
3395 concat!(
3396 "//// lets show the internal code\n",
3397 "//// ```\n",
3398 "fn foo() {\n",
3399 " const FOO:i32=0; ////constants code: {{}}\n",
3400 " let x=1; //// {{4}}\n",
3401 " //// {{4}}\n",
3402 " println!(\"{x}\"); //// {{4}}\n",
3403 "}\n",
3404 "//// ```\n",
3405 ),
3406 "lib",
3407 &[
3408 ("lib", "lets show the internal code\n", false),
3409 ("lib", "```\n", false),
3410 ("constants", "code: const FOO:i32=0;\n", true),
3412 ("lib", "let x=1;\n", false),
3414 ("lib", "\n", false),
3416 ("lib", "println!(\"{x}\");\n", false),
3418 ("lib", "```\n", false),
3419 ],
3420 );
3421 }
3422
3423 #[test]
3424 fn e20_persistent_tag_on_code_capture() {
3425 assert_parse(
3429 concat!(
3430 "//// before\n",
3431 " code; ////mytag\n", " more; //// {{}}\n", ),
3434 "lib",
3435 &[
3436 ("lib", "before\n", false),
3437 ("mytag", "more;\n", false),
3440 ],
3441 );
3442 }
3443
3444 #[test]
3445 fn e21_transient_then_persistent_on_code_capture() {
3446 assert_parse(
3448 concat!(
3449 " a; ////tag1 {{}}\n", " b; ////tag2\n", " c; //// {{}}\n", ),
3453 "lib",
3454 &[
3455 ("tag1", "a;\n", true),
3456 ("tag2", "c;\n", false),
3458 ],
3459 );
3460 }
3461
3462 #[test]
3463 fn e22_continuation_with_persistent_tag() {
3464 assert_parse(
3466 concat!(
3467 " code; //// {{}}\n", " ////mytag\n", " //// {{}}\n", ),
3471 "lib",
3472 &[
3473 ("lib", "code;\n", false),
3474 ("mytag", "\n", false),
3477 ],
3478 );
3479 }
3480
3481 #[test]
3484 fn f01_code_capture_matches_output_filter() {
3485 let tmp = TempDir::new("lift_f01");
3488 let src = tmp.write("f.rs", "////chapter1\n code; //// {{}}\n");
3489 let out = tmp.file("out.md");
3490 Docextract::new(&out)
3491 .unwrap()
3492 .filter_output(Some("chapter1"))
3493 .unwrap()
3494 .input(&src)
3495 .unwrap()
3496 .done()
3497 .unwrap();
3498 assert_eq!(read_str(&out), "code;\n");
3499 }
3500
3501 #[test]
3502 fn f02_code_capture_filtered_out_by_tag() {
3503 let tmp = TempDir::new("lift_f02");
3506 let src = tmp.write("f.rs", "////chapter2\n code; //// {{}}\n");
3507 let out = tmp.file("out.md");
3508 Docextract::new(&out)
3509 .unwrap()
3510 .filter_output(Some("chapter1"))
3511 .unwrap()
3512 .input(&src)
3513 .unwrap()
3514 .done()
3515 .unwrap();
3516 assert_eq!(read_str(&out), "");
3517 }
3518
3519 #[test]
3520 fn f03_unfiltered_emits_both() {
3521 let tmp = TempDir::new("lift_f03");
3524 let src = tmp.write("f.rs", "//// Doc\n code; //// {{}}\n");
3525 let out = tmp.file("out.md");
3526 Docextract::new(&out)
3527 .unwrap()
3528 .input(&src)
3529 .unwrap()
3530 .done()
3531 .unwrap();
3532 assert_eq!(read_str(&out), "Doc\ncode;\n");
3533 }
3534
3535 #[test]
3536 fn f04_input_filtered_code_capture() {
3537 let tmp = TempDir::new("lift_f04");
3544 let src = tmp.write(
3545 "f.rs",
3546 "////api\n//// doc\n code; //// captured\n////core text\n",
3547 );
3548 let out = tmp.file("out.md");
3549 Docextract::new(&out)
3550 .unwrap()
3551 .input_filtered(&src, "api")
3552 .unwrap()
3553 .done()
3554 .unwrap();
3555 assert_eq!(read_str(&out), "doc\n");
3556 }
3557
3558 #[test]
3559 fn f05_code_capture_is_persistent() {
3560 let tmp = TempDir::new("lift_f05");
3565 let src = tmp.write("f.rs", "////t transient\n code; //// captured\n");
3566 let out = tmp.file("out.md");
3567 Docextract::new(&out)
3568 .unwrap()
3569 .input(&src)
3570 .unwrap()
3571 .done()
3572 .unwrap();
3573 assert_eq!(read_str(&out), "");
3575 }
3576
3577 #[test]
3578 fn f06_code_capture_carries_tag_and_responds_to_filter() {
3579 let tmp = TempDir::new("lift_f06");
3583 let src = tmp.write(
3584 "f.rs",
3585 concat!("////detail\n", " code; //// captured\n", "//// doc\n"),
3586 );
3587 let out = tmp.file("out.md");
3588 Docextract::new(&out)
3591 .unwrap()
3592 .input(&src)
3593 .unwrap()
3594 .done()
3595 .unwrap();
3596 assert_eq!(read_str(&out), "doc\n");
3597 let out2 = tmp.file("out2.md");
3599 Docextract::new(&out2)
3600 .unwrap()
3601 .filter_output(Some("detail"))
3602 .unwrap()
3603 .input(&src)
3604 .unwrap()
3605 .done()
3606 .unwrap();
3607 assert_eq!(read_str(&out2), "");
3608 }
3609
3610 #[cfg(feature = "regex")]
3613 #[test]
3614 fn ex01_replace_outputs_only_substitution() {
3615 assert_eq!(
3619 resolve_placeholders("{{/fn (.*);/$1/}}", "pub fn new;"),
3620 "new"
3621 );
3622 }
3623
3624 #[cfg(feature = "regex")]
3625 #[test]
3626 fn ex02_replace_no_match_returns_empty() {
3627 assert_eq!(resolve_placeholders("{{/xxx/$1/}}", "pub fn new;"), "");
3629 }
3630
3631 #[cfg(feature = "regex")]
3632 #[test]
3633 fn ex03_extract_still_outputs_match() {
3634 assert_eq!(
3637 resolve_placeholders("{{/fn .*;/}}", "pub fn new;"),
3638 "fn new;"
3639 );
3640 }
3641 }
3642
3643 mod global_cache {
3650 use super::*;
3651 use std::rc::Rc;
3652
3653 fn run_cache_sharing_subprocess(child_env: &str, test_name: &str) -> std::process::Output {
3658 let exe = std::env::current_exe().unwrap();
3659 std::process::Command::new(&exe)
3660 .env(child_env, "1")
3661 .arg("--exact")
3662 .arg(test_name)
3663 .arg("--nocapture")
3664 .output()
3665 .unwrap()
3666 }
3667
3668 #[test]
3669 fn tc01_cache_sharing_two_instances() {
3670 if std::env::var_os("DOCEXTRACT_TC01_SUBPROCESS").is_some() {
3672 let tmp = TempDir::new("tc01");
3674 let src = tmp.write("in.rs", "////api doc\n");
3675 let out1 = tmp.file("out1.md");
3676 let out2 = tmp.file("out2.md");
3677 let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
3678
3679 Docextract::new(&out1)
3680 .unwrap()
3681 .input_filtered(&src, "api")
3682 .unwrap()
3683 .done()
3684 .unwrap();
3685 Docextract::new(&out2)
3686 .unwrap()
3687 .input_filtered(&src, "api")
3688 .unwrap()
3689 .done()
3690 .unwrap();
3691
3692 assert_eq!(read_str(&out1), "doc\n");
3693 assert_eq!(read_str(&out2), "doc\n");
3694 return;
3695 }
3696 let output = run_cache_sharing_subprocess(
3697 "DOCEXTRACT_TC01_SUBPROCESS",
3698 "tests::global_cache::tc01_cache_sharing_two_instances",
3699 );
3700 assert!(output.status.success(), "child failed: {:?}", output.status);
3701 let stdout = String::from_utf8_lossy(&output.stdout);
3702 let directive_count = stdout.matches("cargo:rerun-if-changed=").count();
3703 assert_eq!(
3704 directive_count, 1,
3705 "rerun-if-changed must be emitted exactly once across two instances, got: {stdout}"
3706 );
3707 assert!(
3708 String::from_utf8_lossy(&output.stderr).is_empty(),
3709 "no warnings expected"
3710 );
3711 }
3712
3713 #[test]
3714 fn tc01_cache_sharing_three_instances() {
3715 if std::env::var_os("DOCEXTRACT_TC01B_SUBPROCESS").is_some() {
3716 let tmp = TempDir::new("tc01b");
3717 let src = tmp.write("in.rs", "////api a\n");
3718 let out1 = tmp.file("out1.md");
3719 let out2 = tmp.file("out2.md");
3720 let out3 = tmp.file("out3.md");
3721 let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
3722
3723 Docextract::new(&out1)
3724 .unwrap()
3725 .input_filtered(&src, "api")
3726 .unwrap()
3727 .done()
3728 .unwrap();
3729 Docextract::new(&out2)
3730 .unwrap()
3731 .input_filtered(&src, "api")
3732 .unwrap()
3733 .done()
3734 .unwrap();
3735 Docextract::new(&out3)
3736 .unwrap()
3737 .input_filtered(&src, "api")
3738 .unwrap()
3739 .done()
3740 .unwrap();
3741
3742 assert_eq!(read_str(&out1), "a\n");
3743 assert_eq!(read_str(&out2), "a\n");
3744 assert_eq!(read_str(&out3), "a\n");
3745 return;
3746 }
3747 let output = run_cache_sharing_subprocess(
3748 "DOCEXTRACT_TC01B_SUBPROCESS",
3749 "tests::global_cache::tc01_cache_sharing_three_instances",
3750 );
3751 assert!(output.status.success(), "child failed: {:?}", output.status);
3752 let stdout = String::from_utf8_lossy(&output.stdout);
3753 let directive_count = stdout.matches("cargo:rerun-if-changed=").count();
3754 assert_eq!(
3755 directive_count, 1,
3756 "rerun-if-changed must be emitted exactly once across three instances, got: {stdout}"
3757 );
3758 }
3759
3760 #[test]
3763 fn tc02_clear_cache_then_reparse() {
3764 if std::env::var_os("DOCEXTRACT_TC02_SUBPROCESS").is_some() {
3765 let tmp = TempDir::new("tc02");
3766 let src = tmp.write("in.rs", "////api doc\n");
3767 let out1 = tmp.file("out1.md");
3768 let out2 = tmp.file("out2.md");
3769 let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
3770
3771 Docextract::new(&out1)
3772 .unwrap()
3773 .input_filtered(&src, "api")
3774 .unwrap()
3775 .done()
3776 .unwrap();
3777 Docextract::clear_cache();
3778 Docextract::new(&out2)
3779 .unwrap()
3780 .input_filtered(&src, "api")
3781 .unwrap()
3782 .done()
3783 .unwrap();
3784
3785 assert_eq!(read_str(&out1), "doc\n");
3786 assert_eq!(read_str(&out2), "doc\n");
3787 return;
3788 }
3789 let output = run_cache_sharing_subprocess(
3790 "DOCEXTRACT_TC02_SUBPROCESS",
3791 "tests::global_cache::tc02_clear_cache_then_reparse",
3792 );
3793 assert!(output.status.success(), "child failed: {:?}", output.status);
3794 let stdout = String::from_utf8_lossy(&output.stdout);
3795 let directive_count = stdout.matches("cargo:rerun-if-changed=").count();
3796 assert_eq!(
3797 directive_count, 2,
3798 "rerun-if-changed must be emitted twice: before and after clear_cache, got: {stdout}"
3799 );
3800 }
3801
3802 #[test]
3803 fn tc02_clear_cache_on_empty_cache_noop() {
3804 Docextract::clear_cache();
3806 Docextract::clear_cache();
3807 }
3809
3810 #[test]
3811 fn tc02_clear_cache_between_inputs_on_same_instance() {
3812 let tmp = TempDir::new("tc02c");
3815 let src = tmp.write("in.rs", "//// doc\n");
3816 let out = tmp.file("out.md");
3817
3818 let mut builder = Docextract::new(&out).unwrap();
3819 builder.input(&src).unwrap();
3820
3821 fs::write(&src, "//// new\n").unwrap();
3823
3824 Docextract::clear_cache();
3826 builder.input(&src).unwrap();
3827 builder.done().unwrap();
3828
3829 assert_eq!(read_str(&out), "doc\nnew\n");
3831 }
3832
3833 #[test]
3836 fn tc03_equivalent_paths_share_cache() {
3837 let tmp = TempDir::new("tc03");
3840 let src = tmp.write("file.rs", "//// hello\n");
3841 let out = tmp.file("out.md");
3842
3843 let mut builder = Docextract::new(&out).unwrap();
3844
3845 let canonical = std::fs::canonicalize(&src).unwrap();
3847 builder.input(&canonical).unwrap();
3848
3849 builder.input(&src).unwrap();
3851 builder.done().unwrap();
3852
3853 assert_eq!(read_str(&out), "hello\nhello\n");
3854 }
3855
3856 #[test]
3857 fn tc03_dot_slash_path_resolves() {
3858 let tmp = TempDir::new("tc03b");
3861 let subdir = tmp.file("subdir");
3862 fs::create_dir_all(&subdir).unwrap();
3863 let file_in_sub = subdir.join("file.rs");
3864 fs::write(&file_in_sub, "//// data\n").unwrap();
3865
3866 let out = tmp.file("out.md");
3867 let mut builder = Docextract::new(&out).unwrap();
3868
3869 let orig_cwd = std::env::current_dir().unwrap();
3871 std::env::set_current_dir(tmp.0.as_path()).unwrap();
3872
3873 builder.input("./subdir/file.rs").unwrap();
3875
3876 builder.input("subdir/file.rs").unwrap();
3878 builder.done().unwrap();
3879
3880 std::env::set_current_dir(orig_cwd).unwrap();
3882
3883 assert_eq!(read_str(&out), "data\ndata\n");
3884 }
3885
3886 #[test]
3889 fn tc04_stdin_twice_on_same_instance() {
3890 }
3900
3901 #[test]
3902 fn tc04_repeated_filtered_stdin_uses_cache() {
3903 let tmp = TempDir::new("tc04");
3906 let src = tmp.write("in.txt", "////api a\n////b b\n");
3907 let out = tmp.file("out.md");
3908
3909 let mut builder = Docextract::new(&out).unwrap();
3910 builder.input_filtered(&src, "api").unwrap();
3911 builder.input_filtered(&src, "b").unwrap();
3912 builder.done().unwrap();
3913
3914 assert_eq!(read_str(&out), "a\nb\n");
3915 }
3916
3917 #[test]
3920 fn tc06_tag_interning_across_instances() {
3921 let tmp = TempDir::new("tc06");
3925 let src1 = tmp.write("a.rs", "////foo bar\n");
3926 let src2 = tmp.write("b.rs", "////foo baz\n");
3927
3928 let content1 = fs::read_to_string(&src1).unwrap();
3932 let content2 = fs::read_to_string(&src2).unwrap();
3933 let mut tags = HashSet::new();
3934 let entries1 = parse_doc_entries(&mut tags, &content1, "a");
3935 let entries2 = parse_doc_entries(&mut tags, &content2, "b");
3936
3937 assert_eq!(entries1.len(), 1);
3938 assert_eq!(entries2.len(), 1);
3939 assert_eq!(&*entries1[0].tag, "foo");
3940 assert_eq!(&*entries2[0].tag, "foo");
3941 assert!(
3943 Rc::ptr_eq(&entries1[0].tag, &entries2[0].tag),
3944 "tag 'foo' from two different parse calls must share the same Rc<str> allocation"
3945 );
3946 }
3947
3948 #[test]
3951 fn tc09_missing_file_returns_ok_on_both_instances() {
3952 let tmp = TempDir::new("tc09");
3957 let out1 = tmp.file("out1.md");
3958 let out2 = tmp.file("out2.md");
3959 let missing = tmp.file("does_not_exist.rs");
3960
3961 let mut builder1 = Docextract::new(&out1).unwrap();
3962 assert!(
3963 builder1.input(&missing).is_ok(),
3964 "missing file must return Ok (warning to stderr)"
3965 );
3966
3967 let mut builder2 = Docextract::new(&out2).unwrap();
3968 assert!(
3969 builder2.input(&missing).is_ok(),
3970 "second instance with missing file must also return Ok"
3971 );
3972
3973 builder1.done().unwrap();
3974 builder2.done().unwrap();
3975 }
3976
3977 #[test]
3980 fn tc08_single_instance_output_unchanged() {
3981 let tmp = TempDir::new("tc08");
3984 let src = tmp.write("in.rs", "//// Hello\n//// World\n");
3985 let out = tmp.file("out.md");
3986
3987 Docextract::new(&out)
3988 .unwrap()
3989 .input(&src)
3990 .unwrap()
3991 .done()
3992 .unwrap();
3993
3994 assert_eq!(read_str(&out), "Hello\nWorld\n");
3995 }
3996 }
3997}