#![doc = include_str!("../README.md")]
#![allow(clippy::doc_markdown)]
mod pattern;
use crate::pattern::{Pattern, PatternError};
use std::collections::{HashMap, HashSet};
use std::io::{self, BufWriter, Read, Write};
use std::ops::Range;
use std::path::{Path, PathBuf};
use std::rc::Rc;
struct Cache {
tags: HashSet<Rc<str>>,
entries: Vec<DocEntry>,
ranges: HashMap<PathBuf, Range<usize>>,
}
thread_local! {
static CACHE: std::cell::RefCell<Cache> = std::cell::RefCell::new(Cache {
tags: HashSet::new(),
entries: Vec::new(),
ranges: HashMap::new(),
});
}
fn normalize_path(path: &Path) -> io::Result<PathBuf> {
if path == Path::new("-") {
return Ok(PathBuf::from("-"));
}
path.canonicalize()
}
fn intern_tag(pool: &mut HashSet<Rc<str>>, name: &str) -> Rc<str> {
if let Some(existing) = pool.get(name) {
return Rc::clone(existing);
}
let rc: Rc<str> = Rc::from(name.to_string());
pool.insert(Rc::clone(&rc));
rc
}
enum OutputTarget {
File(std::fs::File),
Stdout(std::io::Stdout),
}
impl Write for OutputTarget {
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
match self {
OutputTarget::File(f) => f.write(buf),
OutputTarget::Stdout(s) => s.write(buf),
}
}
fn flush(&mut self) -> io::Result<()> {
match self {
OutputTarget::File(f) => f.flush(),
OutputTarget::Stdout(s) => s.flush(),
}
}
}
struct DocEntry {
tag: Rc<str>,
text: Box<str>,
transient: bool,
}
pub struct Docextract {
output: Option<BufWriter<OutputTarget>>,
rerun_if_changed: bool,
output_filter: Option<Pattern>,
}
fn path_stem(path: &Path) -> String {
path.file_stem()
.and_then(|s| s.to_str())
.unwrap_or("unknown")
.to_string()
}
impl From<PatternError> for io::Error {
fn from(e: PatternError) -> io::Error {
io::Error::new(io::ErrorKind::InvalidInput, e.to_string())
}
}
impl Docextract {
pub fn new(output: impl AsRef<Path>) -> io::Result<Self> {
let target = if output.as_ref() == Path::new("-") {
OutputTarget::Stdout(std::io::stdout())
} else {
OutputTarget::File(std::fs::File::create(output.as_ref())?)
};
let writer = BufWriter::with_capacity(32768, target);
let rerun_if_changed = std::env::var("OUT_DIR").is_ok();
Ok(Docextract {
output: Some(writer),
rerun_if_changed,
output_filter: None,
})
}
pub fn input(&mut self, path: impl AsRef<Path>) -> io::Result<&mut Self> {
if self.output.is_none() {
return Err(io::Error::new(
io::ErrorKind::BrokenPipe,
"output already closed",
));
}
self.input_impl(path.as_ref(), None)
}
pub fn stdin(&mut self) -> io::Result<&mut Self> {
if self.output.is_none() {
return Err(io::Error::new(
io::ErrorKind::BrokenPipe,
"output already closed",
));
}
self.stdin_impl()
}
pub fn filter_output(&mut self, filter: Option<&str>) -> Result<&mut Self, PatternError> {
self.output_filter = match filter {
Some(s) => Some(Pattern::new(s)?),
None => None,
};
Ok(self)
}
pub fn input_filtered(
&mut self,
path: impl AsRef<Path>,
filter: &str,
) -> io::Result<&mut Self> {
if self.output.is_none() {
return Err(io::Error::new(
io::ErrorKind::BrokenPipe,
"output already closed",
));
}
let pattern = Pattern::new(filter)?;
self.input_impl(path.as_ref(), Some(&pattern))
}
pub fn done(&mut self) -> io::Result<&mut Self> {
self.close_output()?;
Ok(self)
}
pub fn rerun_if_changed(&mut self, value: bool) -> &mut Self {
self.rerun_if_changed = value;
self
}
pub fn clear_cache() {
CACHE.with(|c| {
*c.borrow_mut() = Cache {
tags: HashSet::new(),
entries: Vec::new(),
ranges: HashMap::new(),
};
});
}
fn emit_entries(
&mut self,
entries: &[DocEntry],
input_filter: Option<&Pattern>,
any_filter_active: bool,
) -> io::Result<()> {
let output = self.output.as_mut().expect("output not yet closed");
for entry in entries {
if !any_filter_active && entry.transient {
continue;
}
if let Some(f) = input_filter {
if !f.matches(&entry.tag) {
continue;
}
}
if let Some(ref f) = self.output_filter {
if !f.matches(&entry.tag) {
continue;
}
}
output.write_all(entry.text.as_bytes())?;
}
Ok(())
}
fn input_impl(&mut self, path: &Path, input_filter: Option<&Pattern>) -> io::Result<&mut Self> {
let is_stdin = path == Path::new("-");
if is_stdin {
return self.stdin_impl_with_filter(input_filter);
}
let canonical = match normalize_path(path) {
Ok(p) => p,
Err(e) if e.kind() == io::ErrorKind::NotFound => {
eprintln!(
"docextract: warning: input file not found: {}",
path.display()
);
return Ok(self);
}
Err(e) => return Err(e),
};
CACHE.with(|c| {
let mut cache = c.borrow_mut();
if let Some(range) = cache.ranges.get(&canonical).cloned() {
let any_filter_active = self.output_filter.is_some() || input_filter.is_some();
self.emit_entries(&cache.entries[range], input_filter, any_filter_active)?;
return Ok(self);
}
let file = match std::fs::File::open(path) {
Ok(f) => f,
Err(e) if e.kind() == io::ErrorKind::NotFound => {
eprintln!(
"docextract: warning: input file not found: {}",
path.display()
);
return Ok(self);
}
Err(e) => return Err(e),
};
let content = {
let mut buf = String::new();
let mut reader = std::io::BufReader::new(file);
reader.read_to_string(&mut buf)?;
buf
};
if self.rerun_if_changed {
println!("cargo:rerun-if-changed={}", path.display());
}
let initial_tag = path_stem(path);
let new_entries = parse_doc_entries(&mut cache.tags, &content, &initial_tag);
let start = cache.entries.len();
cache.entries.extend(new_entries);
let end = cache.entries.len();
cache.ranges.insert(canonical, start..end);
let any_filter_active = self.output_filter.is_some() || input_filter.is_some();
self.emit_entries(&cache.entries[start..end], input_filter, any_filter_active)?;
Ok(self)
})
}
fn stdin_impl(&mut self) -> io::Result<&mut Self> {
self.stdin_impl_with_filter(None)
}
fn stdin_impl_with_filter(&mut self, input_filter: Option<&Pattern>) -> io::Result<&mut Self> {
let key = PathBuf::from("-");
CACHE.with(|c| {
let mut cache = c.borrow_mut();
if let Some(range) = cache.ranges.get(&key).cloned() {
let any_filter_active = self.output_filter.is_some() || input_filter.is_some();
self.emit_entries(&cache.entries[range], input_filter, any_filter_active)?;
return Ok(self);
}
let mut content = String::new();
io::stdin().read_to_string(&mut content)?;
let new_entries = parse_doc_entries(&mut cache.tags, &content, "-");
let start = cache.entries.len();
cache.entries.extend(new_entries);
let end = cache.entries.len();
cache.ranges.insert(key, start..end);
let any_filter_active = self.output_filter.is_some() || input_filter.is_some();
self.emit_entries(&cache.entries[start..end], input_filter, any_filter_active)?;
Ok(self)
})
}
fn close_output(&mut self) -> io::Result<()> {
match self.output.take() {
Some(mut writer) => {
let result = writer.flush();
drop(writer);
if let Err(ref e) = result {
eprintln!("docextract: error: output: {e}");
}
result
}
None => Ok(()),
}
}
}
impl Drop for Docextract {
fn drop(&mut self) {
let _ = self.close_output();
}
}
#[allow(clippy::too_many_lines)]
fn parse_doc_entries(
pool: &mut HashSet<Rc<str>>,
content: &str,
initial_tag: &str,
) -> Vec<DocEntry> {
let mut entries = Vec::new();
let initial_tag_rc = intern_tag(pool, initial_tag);
let mut current_tag = Rc::clone(&initial_tag_rc);
let mut capture_zone_indent: Option<usize> = None;
for line_slice in content.split_inclusive('\n') {
let after_prefix = try_skip_leading_ws_and_four_slashes(line_slice);
let Some(after) = after_prefix else {
let line_content = strip_trailing_newline(line_slice);
if let Some((captured_code, template)) = try_split_code_capturing(line_content) {
if let Some((tag_name, remaining, is_transient)) = parse_template_tag(template) {
let tag_rc = intern_tag(pool, tag_name);
if is_transient {
let resolved = resolve_placeholders(remaining, captured_code);
let ending = extract_line_ending(line_slice);
let text = format!("{resolved}{ending}");
entries.push(DocEntry {
tag: tag_rc,
text: Box::from(text),
transient: true,
});
} else {
current_tag = tag_rc; }
} else {
let resolved = resolve_placeholders(template, captured_code);
let ending = extract_line_ending(line_slice);
let text = format!("{resolved}{ending}");
entries.push(DocEntry {
tag: Rc::clone(¤t_tag),
text: Box::from(text),
transient: false,
});
}
let indent = line_slice
.bytes()
.take_while(|&b| b == b' ' || b == b'\t')
.count();
capture_zone_indent = Some(indent);
} else {
capture_zone_indent = None;
}
continue;
};
let rest = &line_slice[after..];
if rest.as_bytes().first() == Some(&b'/') {
capture_zone_indent = None;
continue;
}
if let Some(zone_indent) = capture_zone_indent {
let line_indent = after - 4; if line_indent > zone_indent {
let template = match rest.as_bytes().first() {
Some(&b' ' | &b'\t') => strip_trailing_newline(&rest[1..]),
Some(&b'\n' | &b'\r') | None => "",
_ => strip_trailing_newline(rest),
};
if let Some((tag_name, remaining, is_transient)) = parse_template_tag(template) {
let tag_rc = intern_tag(pool, tag_name);
if is_transient {
let resolved = resolve_placeholders(remaining, "");
let ending = extract_line_ending(line_slice);
let text = format!("{resolved}{ending}");
entries.push(DocEntry {
tag: tag_rc,
text: Box::from(text),
transient: true,
});
} else {
current_tag = tag_rc; }
} else {
let resolved = resolve_placeholders(template, "");
let ending = extract_line_ending(line_slice);
let text = format!("{resolved}{ending}");
entries.push(DocEntry {
tag: Rc::clone(¤t_tag),
text: Box::from(text),
transient: false,
});
}
continue; }
capture_zone_indent = None; }
let Some(first_byte) = rest.as_bytes().first().copied() else {
entries.push(DocEntry {
tag: Rc::clone(¤t_tag),
text: Box::from(""),
transient: false,
});
continue;
};
match first_byte {
b' ' | b'\t' => {
let text = &rest[1..]; entries.push(DocEntry {
tag: Rc::clone(¤t_tag),
text: Box::from(text),
transient: false,
});
}
b'\n' | b'\r' => {
entries.push(DocEntry {
tag: Rc::clone(¤t_tag),
text: Box::from(rest),
transient: false,
});
}
_ => {
let (name, text_opt) = parse_tag_directive_from_rest(rest);
let tag_rc = intern_tag(pool, name);
match text_opt {
None => {
current_tag = tag_rc;
}
Some(text) => {
entries.push(DocEntry {
tag: tag_rc,
text: Box::from(text),
transient: true,
});
}
}
}
}
}
entries
}
fn try_skip_leading_ws_and_four_slashes(line: &str) -> Option<usize> {
let b = line.as_bytes();
let mut pos: usize = 0;
while pos < b.len() && (b[pos] == 0x20 || b[pos] == 0x09) {
pos += 1;
}
if pos + 4 > b.len() {
return None;
}
if b[pos] != 0x2F || b[pos + 1] != 0x2F || b[pos + 2] != 0x2F || b[pos + 3] != 0x2F {
return None;
}
Some(pos + 4)
}
fn parse_template_tag(template: &str) -> Option<(&str, &str, bool)> {
let b = template.as_bytes();
if b.is_empty() {
return None;
}
match b[0] {
b'{' | b'/' | b' ' | b'\t' => return None,
_ => {}
}
for (i, &byte) in b.iter().enumerate().skip(1) {
match byte {
b' ' | b'\t' => {
return Some((&template[..i], &template[i + 1..], true));
}
b'\n' | b'\r' => {
return Some((&template[..i], &template[i..], false));
}
_ => {}
}
}
Some((template, "", false))
}
fn parse_tag_directive_from_rest(rest: &str) -> (&str, Option<&str>) {
let raw_tag = rest.trim_end_matches(['\n', '\r']);
if let Some(ws_pos) = raw_tag.find(&[' ', '\t'] as &[char]) {
let name = &raw_tag[..ws_pos];
let text = &rest[ws_pos + 1..];
(name, Some(text))
} else {
(raw_tag, None)
}
}
#[allow(
dead_code,
reason = "only used by tests and code-capturing integration (not yet wired into parse_doc_entries)"
)]
fn trim_trailing_space_tab(bytes: &[u8]) -> usize {
let mut end = bytes.len();
while end > 0 && (bytes[end - 1] == b' ' || bytes[end - 1] == b'\t') {
end -= 1;
}
end
}
#[allow(
dead_code,
reason = "only used by tests and code-capturing integration"
)]
fn trim_leading_space_tab(s: &str) -> &str {
let bytes = s.as_bytes();
let mut start = 0;
while start < bytes.len() && (bytes[start] == b' ' || bytes[start] == b'\t') {
start += 1;
}
&s[start..]
}
#[allow(
dead_code,
reason = "only used by tests and code-capturing integration"
)]
fn try_split_code_capturing(line: &str) -> Option<(&str, &str)> {
let b = line.as_bytes();
for i in (0..=b.len().saturating_sub(4)).rev() {
if i + 3 >= b.len() {
continue;
}
if b[i] == b'/' && b[i + 1] == b'/' && b[i + 2] == b'/' && b[i + 3] == b'/' {
if i == 0 || (b[i - 1] != b' ' && b[i - 1] != b'\t') {
continue;
}
let separator_pos = i - 1;
let after_slashes = i + 4;
let code_end = trim_trailing_space_tab(&b[..separator_pos]);
let captured_code = &line[..code_end];
let template = if after_slashes >= b.len() {
""
} else if b[after_slashes] == b' ' || b[after_slashes] == b'\t' {
&line[after_slashes + 1..]
} else {
&line[after_slashes..]
};
return Some((captured_code, template));
}
}
None
}
fn unescape_delimiter(s: &str, delim: u8) -> String {
let delim_char = delim as char;
let mut result = String::with_capacity(s.len());
let mut iter = s.chars().peekable();
while let Some(ch) = iter.next() {
if ch == '\\' {
if let Some(&next_ch) = iter.peek() {
if next_ch == delim_char {
result.push(delim_char);
iter.next(); continue;
}
}
}
result.push(ch);
}
result
}
#[allow(dead_code, reason = "RED scaffolding; constructed in batch 2")]
struct SedForm {
regex: String,
subst: Option<String>,
}
#[allow(dead_code, reason = "RED scaffolding; constructed in batch 2")]
struct SedError(String);
#[allow(
dead_code,
reason = "only called from cfg(feature = \"regex\") code path"
)]
fn parse_sed_placeholder(content: &str) -> Result<SedForm, SedError> {
let delim = content.as_bytes()[0];
let inner = &content[1..];
let mut regex_end: Option<usize> = None;
let mut i = 0;
while i < inner.len() {
if inner.as_bytes()[i] == delim {
if i > 0 && inner.as_bytes()[i - 1] == b'\\' {
i += 1;
continue;
}
regex_end = Some(i);
break;
}
i += 1;
}
let Some(regex_end) = regex_end else {
return Err(SedError("unterminated regex".to_string()));
};
let regex_raw = &inner[..regex_end];
let after_regex = &inner[regex_end + 1..];
let regex_unescaped = unescape_delimiter(regex_raw, delim);
let mut subst_end: Option<usize> = None;
let mut j = 0;
while j < after_regex.len() {
if after_regex.as_bytes()[j] == delim {
if j > 0 && after_regex.as_bytes()[j - 1] == b'\\' {
j += 1;
continue;
}
subst_end = Some(j);
break;
}
j += 1;
}
match subst_end {
Some(end) => {
let subst_raw = &after_regex[..end];
let subst_unescaped = unescape_delimiter(subst_raw, delim);
Ok(SedForm {
regex: regex_unescaped,
subst: Some(subst_unescaped),
})
}
None => {
Ok(SedForm {
regex: regex_unescaped,
subst: None,
})
}
}
}
#[allow(
dead_code,
reason = "only used by resolve_single_placeholder (itself guarded by dead_code)"
)]
fn is_ascii_punctuation(b: u8) -> bool {
matches!(
b,
b'!' | b'"'
| b'#'
| b'$'
| b'%'
| b'&'
| b'\''
| b'*'
| b'+'
| b','
| b'-'
| b'.'
| b'/'
| b':'
| b';'
| b'<'
| b'='
| b'>'
| b'?'
| b'@'
| b'['
| b'\\'
| b']'
| b'^'
| b'_'
| b'`'
| b'|'
| b'~'
)
}
#[allow(
dead_code,
reason = "only used by tests and resolve_placeholders (not yet wired into parse_doc_entries)"
)]
fn resolve_single_placeholder(content: &str, captured_code: &str) -> String {
if content.is_empty() {
return trim_leading_space_tab(captured_code).to_string();
}
let first_byte = content.as_bytes()[0];
if first_byte.is_ascii_digit() {
let n: usize = content.parse().unwrap_or(usize::MAX);
let char_count = captured_code.chars().count();
if n >= char_count {
return String::new();
}
return captured_code.chars().skip(n).collect();
}
if is_ascii_punctuation(first_byte) {
#[cfg(feature = "regex")]
{
let form = parse_sed_placeholder(content)
.unwrap_or_else(|e| panic!("docextract: invalid sed placeholder: {}", e.0));
return match form.subst {
None => {
let re = regex_lite::Regex::new(&form.regex).unwrap_or_else(|e| {
eprintln!("docextract: warning: invalid regex '{}': {}", form.regex, e);
regex_lite::Regex::new("\\b\\B").expect("\\b\\B is a valid regex pattern")
});
match re.find(captured_code) {
Some(m) => m.as_str().to_string(),
None => String::new(),
}
}
Some(subst) => {
let re = regex_lite::Regex::new(&form.regex).unwrap_or_else(|e| {
eprintln!("docextract: warning: invalid regex '{}': {}", form.regex, e);
regex_lite::Regex::new("\\b\\B").expect("\\b\\B is a valid regex pattern")
});
if let Some(m) = re.find(captured_code) {
re.replace(m.as_str(), subst.as_str()).into_owned()
} else {
String::new()
}
}
};
}
#[cfg(not(feature = "regex"))]
{
panic!(
"docextract: sed-like placeholder '{{{{{content}}}}}' requires the `regex` feature.\n\
Rebuild with default features (cargo build) or use only {{{{}}}} and {{{{N}}}} placeholders."
);
}
}
panic!(
"docextract: reserved placeholder form '{{{{{content}}}}}'.\n\
Use {{{{}}}}, {{{{N}}}}, or a sed-like form {{{{X...X}}}}."
);
}
#[allow(
dead_code,
reason = "only used by tests and code-capturing integration"
)]
fn resolve_placeholders(template: &str, captured_code: &str) -> String {
let mut result = String::new();
let mut pos = 0;
while pos < template.len() {
if template[pos..].starts_with("{{") {
let search_from = pos + 2;
if let Some(close_offset) = template[search_from..].find("}}") {
let close_pos = search_from + close_offset;
let content = &template[search_from..close_pos];
let replacement = resolve_single_placeholder(content, captured_code);
result.push_str(&replacement);
pos = close_pos + 2;
} else {
result.push_str("{{");
pos += 2;
}
} else {
let ch = template[pos..]
.chars()
.next()
.expect("pos < template.len() guarantees at least one char");
result.push(ch);
pos += ch.len_utf8();
}
}
result
}
fn strip_trailing_newline(s: &str) -> &str {
if let Some(stripped) = s.strip_suffix("\r\n") {
stripped
} else if let Some(stripped) = s.strip_suffix('\n') {
stripped
} else {
s
}
}
fn extract_line_ending(s: &str) -> &str {
if s.ends_with("\r\n") {
"\r\n"
} else if s.ends_with('\n') {
"\n"
} else {
""
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used)]
use super::*;
use std::fmt::Write as FmtWrite;
use std::fs;
use std::path::PathBuf;
use std::sync::{Mutex, MutexGuard};
struct TempDir(PathBuf);
impl TempDir {
fn new(name: &str) -> TempDir {
let dir = std::env::temp_dir().join(format!(
"docextract-test-{}-pid{}-{:?}",
name,
std::process::id(),
std::thread::current().id(),
));
fs::create_dir_all(&dir).unwrap();
TempDir(dir)
}
fn file(&self, name: &str) -> PathBuf {
self.0.join(name)
}
fn write(&self, name: &str, content: &str) -> PathBuf {
let path = self.file(name);
fs::write(&path, content).unwrap();
path
}
fn write_bytes(&self, name: &str, content: &[u8]) -> PathBuf {
let path = self.file(name);
fs::write(&path, content).unwrap();
path
}
}
impl Drop for TempDir {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.0);
}
}
fn read_str(path: &Path) -> String {
fs::read_to_string(path).unwrap()
}
static OUT_DIR_LOCK: Mutex<()> = Mutex::new(());
struct OutDirGuard {
prev: Option<std::ffi::OsString>,
_lock: MutexGuard<'static, ()>,
}
impl OutDirGuard {
fn with(value: Option<&std::ffi::OsStr>) -> OutDirGuard {
let lock = OUT_DIR_LOCK.lock().unwrap();
let prev = std::env::var_os("OUT_DIR");
match value {
Some(v) => unsafe { std::env::set_var("OUT_DIR", v) },
None => unsafe { std::env::remove_var("OUT_DIR") },
}
OutDirGuard { prev, _lock: lock }
}
}
impl Drop for OutDirGuard {
fn drop(&mut self) {
match &self.prev {
Some(v) => unsafe { std::env::set_var("OUT_DIR", v) },
None => unsafe { std::env::remove_var("OUT_DIR") },
}
}
}
#[test]
fn b01_single_file_extraction() {
let tmp = TempDir::new("b01");
let src = tmp.write(
"valid.rs",
"//// Hello World\nfn main() {}\n//// Second line\n",
);
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "Hello World\nSecond line\n");
}
#[test]
fn b02_multiple_files_concatenated() {
let tmp = TempDir::new("b02");
let a = tmp.write("a.rs", "//// From A\n");
let b = tmp.write("b.rs", "//// From B\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&a)
.unwrap()
.input(&b)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "From A\nFrom B\n");
}
#[test]
fn b03_missing_file_warns_and_continues() {
let tmp = TempDir::new("b03");
let src = tmp.write("valid.rs", "//// From Valid\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
assert!(builder.input(tmp.file("missing.rs")).is_ok());
builder.input(&src).unwrap();
builder.done().unwrap();
assert_eq!(read_str(&out), "From Valid\n");
}
#[test]
fn b04_zero_inputs_empty_output() {
let tmp = TempDir::new("b04");
let out = tmp.file("out.md");
Docextract::new(&out).unwrap().done().unwrap();
assert!(out.exists());
assert_eq!(read_str(&out), "");
}
#[test]
fn b05_stdin_input() {
let tmp = TempDir::new("b05");
let src = tmp.write("stdin-content.txt", "//// From stdin\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "From stdin\n");
}
#[test]
fn b06_stdin_and_file_combined() {
let tmp = TempDir::new("b06");
let file = tmp.write("file.rs", "//// From File\n");
let stdin_content = tmp.write("stdin.txt", "//// From stdin\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&file)
.unwrap()
.input(&stdin_content)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "From File\nFrom stdin\n");
}
#[test]
fn b07_mixed_valid_and_invalid_inputs() {
let tmp = TempDir::new("b07");
let docs = tmp.write("docs.rs", "//// Kept\n");
let no_docs = tmp.write(
"code.rs",
"fn main() {\n // not a doc\n}\n////Bad\n///// five\n////### Heading\n",
);
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&docs)
.unwrap()
.input(&no_docs)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "Kept\n");
}
#[test]
fn b08_read_error_returns_err() {
let tmp = TempDir::new("b08");
let dir = tmp.file("a_directory");
fs::create_dir_all(&dir).unwrap();
let out = tmp.file("out.md");
assert!(Docextract::new(&out).unwrap().input(&dir).is_err());
}
#[test]
fn b09_output_file_created() {
let tmp = TempDir::new("b09");
let out = tmp.file("out.md");
assert!(!out.exists());
let mut builder = Docextract::new(&out).unwrap();
assert!(out.exists(), "output file must be created by new()");
builder.done().unwrap();
let out2 = tmp.file("pre.md");
fs::write(&out2, "stale content").unwrap();
Docextract::new(&out2).unwrap().done().unwrap();
assert_eq!(read_str(&out2), "");
}
#[test]
fn b10_stdout_output_path() {
let tmp = TempDir::new("b10");
Docextract::new("-")
.unwrap()
.input(tmp.write("in.rs", "//// To stdout\n"))
.unwrap()
.done()
.unwrap();
assert!(
!std::path::Path::new("-").exists(),
"no file named '-' should be created in the working directory"
);
}
#[test]
fn b11_rerun_if_changed_false_suppresses() {
let tmp = TempDir::new("b11");
let src = tmp.write("in.rs", "//// Doc\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
builder.rerun_if_changed(false);
builder.input(&src).unwrap();
builder.done().unwrap();
assert_eq!(read_str(&out), "Doc\n");
}
#[test]
fn b12_last_toggle_wins() {
let tmp = TempDir::new("b12");
let src = tmp.write("in.rs", "//// Doc\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
builder.rerun_if_changed(true);
builder.rerun_if_changed(false);
builder.rerun_if_changed(true);
builder.input(&src).unwrap();
builder.done().unwrap();
assert_eq!(read_str(&out), "Doc\n");
}
#[test]
fn b13_out_dir_set_auto_detects() {
let tmp = TempDir::new("b13");
let src = tmp.write("in.rs", "//// Doc\n");
let out = tmp.file("out.md");
let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
let mut builder = Docextract::new(&out).unwrap();
builder.input(&src).unwrap();
builder.done().unwrap();
assert_eq!(read_str(&out), "Doc\n");
}
#[test]
fn b14_out_dir_unset_default_false() {
let tmp = TempDir::new("b14");
let src = tmp.write("in.rs", "//// Doc\n");
let out = tmp.file("out.md");
let _guard = OutDirGuard::with(None);
let mut builder = Docextract::new(&out).unwrap();
builder.input(&src).unwrap();
builder.done().unwrap();
assert_eq!(read_str(&out), "Doc\n");
}
#[test]
fn b15_done_then_drop_no_double_close() {
let tmp = TempDir::new("b15");
let src = tmp.write("in.rs", "//// Doc\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
builder.input(&src).unwrap();
builder.done().unwrap();
builder.done().unwrap();
assert_eq!(read_str(&out), "Doc\n");
}
#[test]
fn b16_drop_without_done_flushes() {
let tmp = TempDir::new("b16");
let src = tmp.write("in.rs", "//// Doc\n");
let out = tmp.file("out.md");
{
let mut builder = Docextract::new(&out).unwrap();
builder.input(&src).unwrap();
}
assert_eq!(read_str(&out), "Doc\n");
}
#[test]
fn b17_empty_file_no_output() {
let tmp = TempDir::new("b17");
let src = tmp.write("empty.rs", "");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "");
}
#[test]
fn b18_no_doc_lines_empty_output() {
let tmp = TempDir::new("b18");
let src = tmp.write(
"code.rs",
"fn main() {\n println!(\"hi\");\n}\n// regular\n/// rustdoc\n////Bad\n///// five\n",
);
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "");
}
#[test]
fn b19_crlf_preserved() {
let tmp = TempDir::new("b19");
let src = tmp.write(
"crlf.rs",
"//// First\r\n//// Second\r\nlet x = 1;\r\n//// Third\r\n",
);
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "First\r\nSecond\r\nThird\r\n");
}
#[test]
fn b20_invalid_utf8_errors() {
let tmp = TempDir::new("b20");
let src = tmp.write_bytes("binary.rs", b"//// \xFF\xFE not utf8\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
assert!(builder.input(&src).is_err());
builder.done().unwrap();
}
#[test]
fn b21_large_file_processing() {
let tmp = TempDir::new("b21");
let mut content = String::new();
for i in 0..20_000 {
let _ = write!(content, "//// line {i} {}", "x".repeat(40));
content.push('\n');
if i % 5 == 0 {
content.push_str("fn f() {}\n");
}
}
assert!(content.len() >= 1_000_000, "source should be ~1 MiB");
let src = tmp.write("large.rs", &content);
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
let output = read_str(&out);
assert!(output.starts_with("line 0 "));
assert!(output.ends_with(&format!("line 19999 {}\n", "x".repeat(40))));
assert_eq!(output.lines().count(), 20_000);
assert!(
output
.lines()
.filter(|l| !l.is_empty())
.all(|l| l.starts_with("line "))
);
assert!(output.len() > 800_000, "all 20k doc lines must be present");
}
#[test]
fn b22_multiple_inputs_in_loop() {
let tmp = TempDir::new("b22");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
let mut expected = String::new();
for i in 0..10 {
let src = tmp.write(&format!("m{i}.rs"), &format!("//// File {i}\n"));
builder.input(&src).unwrap();
let _ = writeln!(expected, "File {i}");
}
builder.done().unwrap();
assert_eq!(read_str(&out), expected);
}
#[test]
fn b23_done_ok_on_empty_builder() {
let tmp = TempDir::new("b23");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
let result = builder.done();
assert!(result.is_ok());
assert_eq!(read_str(&out), "");
}
#[test]
fn b24_stdin_called_twice_second_noop() {
let tmp = TempDir::new("b24");
let first = tmp.write("first.txt", "//// Only once\n");
let second = tmp.write("second.txt", "fn main() {\n let x = 1;\n}\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&first)
.unwrap()
.input(&second)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "Only once\n");
}
#[test]
fn b25_empty_output_path_errors() {
let result = Docextract::new("");
assert!(result.is_err());
}
#[test]
fn b26_file_vs_stdout_output_paths() {
let tmp = TempDir::new("b26");
let src = tmp.write("in.rs", "//// Doc\n");
let out = tmp.file("out.md");
{
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
}
assert!(out.exists());
assert_eq!(read_str(&out), "Doc\n");
let string_path: String = tmp
.write("str.rs", "//// String Doc\n")
.to_string_lossy()
.into_owned();
let out2 = tmp.file("out2.md");
{
Docextract::new(&out2)
.unwrap()
.input(string_path)
.unwrap()
.done()
.unwrap();
}
assert_eq!(read_str(&out2), "String Doc\n");
{
Docextract::new("-")
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
}
assert!(
!std::path::Path::new("-").exists(),
"stdout target must not create a file named '-' in the working directory"
);
}
#[test]
fn b27_mid_stream_error_preserves_earlier_output() {
let tmp = TempDir::new("b27");
let good = tmp.write("good.rs", "//// From Good\n");
let bad_dir = tmp.file("bad");
fs::create_dir_all(&bad_dir).unwrap();
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
builder.input(&good).unwrap();
assert!(builder.input(&bad_dir).is_err());
builder.done().unwrap();
assert_eq!(read_str(&out), "From Good\n");
}
#[test]
fn b28_all_doc_line_types_in_one_file() {
let tmp = TempDir::new("b28");
let src = tmp.write(
"all.rs",
"//// First\n////\n//// Second\nlet x = 1;\n\t//// Tab Sep\n////\tTab Content\n//// Two Spaces\n////Bad\n///// five\n////",
);
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(
read_str(&out),
"First\n\nSecond\nTab Sep\nTab Content\n Two Spaces\n"
);
}
#[test]
#[cfg(target_os = "linux")]
fn b29_done_flush_error_returns_err() {
let tmp = TempDir::new("b29");
let src = tmp.write("in.rs", "//// Doc\n");
let mut builder = Docextract::new("/dev/full").unwrap();
builder.input(&src).unwrap();
assert!(builder.done().is_err());
}
#[test]
fn b30_all_inputs_missing_warns_and_creates_empty_output() {
let tmp = TempDir::new("b30");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
assert!(builder.input(tmp.file("m1.rs")).is_ok());
assert!(builder.input(tmp.file("m2.rs")).is_ok());
builder.done().unwrap();
assert!(out.exists());
assert_eq!(read_str(&out), "");
}
#[test]
fn b31_out_dir_auto_detect_set_and_clear() {
let tmp = TempDir::new("b31");
let src = tmp.write("in.rs", "//// Doc\n");
let out_set = tmp.file("out-set.md");
{
let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
Docextract::new(&out_set)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
}
let out_clear = tmp.file("out-clear.md");
{
let _guard = OutDirGuard::with(None);
Docextract::new(&out_clear)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
}
assert_eq!(read_str(&out_set), "Doc\n");
assert_eq!(read_str(&out_clear), "Doc\n");
assert_eq!(read_str(&out_set), read_str(&out_clear));
}
#[test]
fn b32_non_notfound_open_error_returns_err() {
let tmp = TempDir::new("b32");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
let nul_path = PathBuf::from("docextract-nul\0path");
assert!(builder.input(nul_path).is_err());
builder.done().unwrap();
}
#[test]
#[cfg(target_os = "linux")]
fn b33_drop_flush_error_reports_to_stderr() {
if std::env::var_os("DOCEXTRACT_SUBPROCESS").is_some() {
let tmp = TempDir::new("b33-child");
let src = tmp.write("in.rs", "//// Doc\n");
let mut builder = Docextract::new("/dev/full").unwrap();
builder.input(&src).unwrap();
return;
}
let exe = std::env::current_exe().unwrap();
let output = std::process::Command::new(&exe)
.env("DOCEXTRACT_SUBPROCESS", "1")
.arg("--exact")
.arg("tests::b33_drop_flush_error_reports_to_stderr")
.arg("--nocapture")
.output()
.unwrap();
assert!(
output.status.success(),
"child test binary must exit 0, got {:?}",
output.status
);
let stderr = String::from_utf8_lossy(&output.stderr);
assert!(
stderr.contains("docextract: error: output:"),
"Drop flush error must be printed to stderr, got: {stderr}"
);
}
mod tag_filter {
use super::*;
use crate::pattern::Pattern;
#[cfg(feature = "regex")]
use crate::pattern::PatternError;
use std::rc::Rc;
fn assert_entries(actual: &[DocEntry], expected: &[(&str, &str, bool)]) {
assert_eq!(
actual.len(),
expected.len(),
"entry count mismatch: got {} expected {}",
actual.len(),
expected.len()
);
for (entry, (tag, text, transient)) in actual.iter().zip(expected) {
assert_eq!(&*entry.tag, *tag, "tag mismatch");
assert_eq!(&*entry.text, *text, "text mismatch");
assert_eq!(entry.transient, *transient, "transient mismatch");
}
}
fn assert_tags(tags: &HashSet<Rc<str>>, expected: &[&str]) {
assert_eq!(tags.len(), expected.len(), "interning pool size mismatch");
for &name in expected {
assert!(tags.contains(name), "tag {name:?} missing from pool");
}
}
#[test]
fn p01_simple_doc_line() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "//// Hello\n", "lib");
assert_entries(&entries, &[("lib", "Hello\n", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p02_four_space_indent() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, " //// Hello\n", "lib");
assert_entries(&entries, &[("lib", "Hello\n", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p03_tab_indent() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "\t//// Hello\n", "lib");
assert_entries(&entries, &[("lib", "Hello\n", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p04_tab_separator() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////\tHello\n", "lib");
assert_entries(&entries, &[("lib", "Hello\n", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p05_empty_doc_line_newline() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////\n", "lib");
assert_entries(&entries, &[("lib", "\n", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p06_empty_doc_line_space_newline() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "//// \n", "lib");
assert_entries(&entries, &[("lib", "\n", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p07_empty_doc_line_at_eof() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////", "lib");
assert_entries(&entries, &[("lib", "", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p08_crlf_preserved() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "//// Hello\r\n", "lib");
assert_entries(&entries, &[("lib", "Hello\r\n", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p09_three_spaces_first_is_separator() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "//// \n", "lib");
assert_entries(&entries, &[("lib", " \n", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p10_two_spaces_second_preserved() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "//// Two Spaces\n", "lib");
assert_entries(&entries, &[("lib", " Two Spaces\n", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p11_long_doc_line_preserved_verbatim() {
let content = "x".repeat(300);
let input = format!("//// {content}\n");
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, &input, "myfile");
assert_entries(&entries, &[("myfile", &format!("{content}\n"), false)]);
assert_tags(&tags, &["myfile"]);
}
#[test]
fn p12_five_slashes_ignored() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "/////\n", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p13_six_slashes_ignored() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "//////\n", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p14_three_slashes_ignored() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "///\n", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p15_non_four_slash_prefix_ignored() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "X///\nfn main() {}\n", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p16_whitespace_only_line_at_eof_ignored() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, " ", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p17_mixed_indent() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, " \t//// Hello\n", "lib");
assert_entries(&entries, &[("lib", "Hello\n", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p18_space_separator_at_eof() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "//// ", "lib");
assert_entries(&entries, &[("lib", "", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p19_tab_separator_at_eof() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////\t", "lib");
assert_entries(&entries, &[("lib", "", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p20_crlf_without_separator() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////\r\n", "lib");
assert_entries(&entries, &[("lib", "\r\n", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p21_cr_at_eof() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////\r", "lib");
assert_entries(&entries, &[("lib", "\r", false)]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p22_persistent_tag_switch() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////foo\n", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib", "foo"]);
}
#[test]
fn p23_persistent_tag_switch_chapter1() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////chapter1\n", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib", "chapter1"]);
}
#[test]
fn p24_transient_tag_with_text() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////foo bar baz\n", "lib");
assert_entries(&entries, &[("foo", "bar baz\n", true)]);
assert_tags(&tags, &["lib", "foo"]);
}
#[test]
fn p25_transient_tag_glossary() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////glossary example\n", "lib");
assert_entries(&entries, &[("glossary", "example\n", true)]);
assert_tags(&tags, &["lib", "glossary"]);
}
#[test]
fn p26_tag_with_hyphen() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////tag-name\n", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib", "tag-name"]);
}
#[test]
fn p27_tag_with_dot() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////tag.name\n", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib", "tag.name"]);
}
#[test]
fn p28_hash_tag() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////### Heading\n", "lib");
assert_entries(&entries, &[("###", "Heading\n", true)]);
assert_tags(&tags, &["lib", "###"]);
}
#[test]
fn p29_numeric_tag() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////42\n", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib", "42"]);
}
#[test]
fn p30_indented_tag_directive() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, " ////foo\n", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib", "foo"]);
}
#[test]
fn p31_hello_repurposed_case_e() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////Hello\n", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib", "Hello"]);
}
#[test]
fn p32_persistent_switch_then_doc_line() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "////foo\n//// bar\n", "lib");
assert_entries(&entries, &[("foo", "bar\n", false)]);
assert_tags(&tags, &["lib", "foo"]);
}
#[test]
fn p33_transient_does_not_change_current_tag() {
let mut tags = HashSet::new();
let entries =
parse_doc_entries(&mut tags, "////foo\n////baz text\n//// after\n", "lib");
assert_entries(
&entries,
&[("baz", "text\n", true), ("foo", "after\n", false)],
);
assert_tags(&tags, &["lib", "foo", "baz"]);
}
#[test]
fn p34_tag_interning_shared_rc() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "//// a\n//// b\n//// c\n", "mod");
assert_eq!(entries.len(), 3);
assert!(Rc::ptr_eq(&entries[0].tag, &entries[1].tag));
assert!(Rc::ptr_eq(&entries[1].tag, &entries[2].tag));
assert_tags(&tags, &["mod"]);
}
#[test]
fn p35_stdin_initial_tag() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "//// hello\n", "-");
assert_entries(&entries, &[("-", "hello\n", false)]);
assert_tags(&tags, &["-"]);
}
#[test]
fn p36_no_doc_lines() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "fn main() {\n let x = 1;\n}\n", "lib");
assert_entries(&entries, &[]);
assert_tags(&tags, &["lib"]);
}
#[test]
fn p37_doc_at_eof_without_newline() {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, "//// text\n////", "lib");
assert_entries(&entries, &[("lib", "text\n", false), ("lib", "", false)]);
assert_tags(&tags, &["lib"]);
}
#[cfg(not(feature = "regex"))]
mod simple_matcher {
use super::*;
fn m(pattern: &str, target: &str) -> bool {
Pattern::new(pattern).unwrap().matches(target)
}
#[test]
fn g01_star_matches_everything() {
assert!(m(".*", "anything"));
}
#[test]
fn g02_star_matches_empty() {
assert!(m(".*", ""));
}
#[test]
fn g03_literal_exact_match() {
assert!(m("foo", "foo"));
}
#[test]
fn g04_literal_no_match() {
assert!(!m("foo", "bar"));
}
#[test]
fn g05_prefix_then_star() {
assert!(m("foo.*", "foobar"));
}
#[test]
fn g06_prefix_then_star_wrong_target() {
assert!(!m("foo.*", "barfoo"));
}
#[test]
fn g07_star_then_suffix() {
assert!(m(".*foo", "barfoo"));
}
#[test]
fn g08_star_sandwich() {
assert!(m(".*foo.*", "barfoobaz"));
}
#[test]
fn g09_optional_any_single_char() {
assert!(m(".?", "a"));
}
#[test]
fn g10_optional_any_empty() {
assert!(m(".?", ""));
}
#[test]
fn g11_optional_any_two_chars() {
assert!(!m(".?", "ab"));
}
#[test]
fn g12_optional_any_middle_filled() {
assert!(m("f.?o", "foo"));
}
#[test]
fn g13_optional_any_middle_other() {
assert!(m("f.?o", "fao"));
}
#[test]
fn g14_optional_any_middle_omitted() {
assert!(m("f.?o", "fo"));
}
#[test]
fn g15_chapter_optional_digit() {
assert!(m("chapter.?", "chapter1"));
}
#[test]
fn g16_chapter_optional_omitted() {
assert!(m("chapter.?", "chapter"));
}
#[test]
fn g17_character_class_member() {
assert!(m("[abc]", "a"));
}
#[test]
fn g18_character_class_non_member() {
assert!(!m("[abc]", "d"));
}
#[test]
fn g19_character_class_range() {
assert!(m("[a-z]", "m"));
}
#[test]
fn g20_character_class_range_case_sensitive() {
assert!(!m("[a-z]", "M"));
}
#[test]
fn g21_negated_class_matches_outside() {
assert!(m("[^abc]", "d"));
}
#[test]
fn g22_negated_class_rejects_member() {
assert!(!m("[^abc]", "a"));
}
#[test]
fn g23_escaped_dot_matches_dot() {
assert!(m("\\.", "."));
}
#[test]
fn g24_escaped_dot_rejects_other() {
assert!(!m("\\.", "a"));
}
#[test]
fn g25_escaped_backslash_matches_backslash() {
assert!(m("\\\\", "\\"));
}
#[test]
fn g26_empty_pattern_empty_target() {
assert!(m("", ""));
}
#[test]
fn g27_empty_pattern_nonempty_target() {
assert!(!m("", "a"));
}
#[test]
fn g28_multiple_stars() {
assert!(m(".*.*", "abc"));
}
#[test]
fn g29_unclosed_bracket_matches_literal() {
assert!(m("[", "["));
}
#[test]
fn g30_unclosed_range_literal_fallback() {
assert!(!m("[a", "["));
}
#[test]
fn g31_star_then_optional() {
assert!(m(".*.?", "a"));
}
#[test]
fn g32_optional_then_star() {
assert!(m(".?.*", "abc"));
}
#[test]
fn g33_unquantified_class_not_empty() {
assert!(!m("[abc]", ""));
}
}
#[cfg(feature = "regex")]
mod regex_matcher {
use super::*;
fn m(pattern: &str, target: &str) -> bool {
Pattern::new(pattern).unwrap().matches(target)
}
#[test]
fn r01_posix_alpha_matches_letter() {
assert!(m("[[:alpha:]]", "a"));
}
#[test]
fn r02_posix_alpha_rejects_digit() {
assert!(!m("[[:alpha:]]", "9"));
}
#[test]
fn r03_alpha_alnum_star_bar() {
assert!(m("[[:alpha:]][[:alnum:]]*_bar", "a1_bar"));
}
#[test]
fn r04_alpha_alnum_star_bar_long() {
assert!(m("[[:alpha:]][[:alnum:]]*_bar", "a123foo_bar"));
}
#[test]
fn r05_alpha_alnum_star_bar_short() {
assert!(m("[[:alpha:]][[:alnum:]]*_bar", "a_bar"));
}
#[test]
fn r06_alpha_alnum_star_bar_digit_start() {
assert!(!m("[[:alpha:]][[:alnum:]]*_bar", "1_bar"));
}
#[test]
fn r07_alpha_alnum_star_bar_wrong_suffix() {
assert!(!m("[[:alpha:]][[:alnum:]]*_bar", "a_baz"));
}
#[test]
fn r08_group_plus_repeated() {
assert!(m("(foo)+", "foofoofoo"));
}
#[test]
fn r09_group_plus_single() {
assert!(m("(foo)+", "foo"));
}
#[test]
fn r10_group_plus_empty() {
assert!(!m("(foo)+", ""));
}
#[test]
fn r11_alternation_first_branch() {
assert!(m("foo|bar", "foo"));
}
#[test]
fn r12_alternation_second_branch() {
assert!(m("foo|bar", "bar"));
}
#[test]
fn r13_alternation_no_branch() {
assert!(!m("foo|bar", "baz"));
}
#[test]
fn r14_digit_plus() {
assert!(m("\\d+", "123"));
}
#[test]
fn r15_digit_plus_rejects_letters() {
assert!(!m("\\d+", "abc"));
}
#[test]
fn r16_word_plus() {
assert!(m("\\w+", "hello_world"));
}
#[test]
fn r17_exact_count_quantifier() {
assert!(m("a{3}", "aaa"));
}
#[test]
fn r18_exact_count_quantifier_short() {
assert!(!m("a{3}", "aa"));
}
#[test]
fn r19_non_capturing_group() {
assert!(m("(?:foo)", "foo"));
}
#[test]
fn r20_unclosed_bracket_is_compile_error() {
let result = Pattern::new("[");
assert!(
matches!(result, Err(PatternError::InvalidSyntax(_))),
"unclosed character class must be a compile error"
);
}
#[test]
fn r21_unclosed_paren_is_compile_error() {
let result = Pattern::new("(");
assert!(
matches!(result, Err(PatternError::InvalidSyntax(_))),
"unclosed group must be a compile error"
);
}
}
#[test]
fn f01_input_filtered_matches_tag() {
let tmp = TempDir::new("f01");
let src = tmp.write("file.rs", "////api intro\n//// core\n////api detail\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input_filtered(&src, "api")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "intro\ndetail\n");
}
#[test]
fn f02_input_filtered_no_matching_tag() {
let tmp = TempDir::new("f02");
let src = tmp.write("file.rs", "//// core\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input_filtered(&src, "api")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "");
}
#[test]
fn f03_output_filter_with_unfiltered_input() {
let tmp = TempDir::new("f03");
let src = tmp.write("file.rs", "////chapter1 a\n//// intro\n////chapter2 b\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.filter_output(Some("chapter.*"))
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "a\nb\n");
}
#[test]
fn f04_output_and_input_filter_and_combine() {
let tmp = TempDir::new("f04");
let src = tmp.write("file.rs", "////chapter1 a\n////chapter2 b\n//// plain\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.filter_output(Some("chapter.*"))
.unwrap()
.input_filtered(&src, "chapter1")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "a\n");
}
#[test]
fn f05_reordering_via_multiple_filtered_reads() {
let tmp = TempDir::new("f05");
let src = tmp.write("f.rs", "////ch1 one\n////ch2 two\n////ch1 three\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
builder.input_filtered(&src, "ch1").unwrap();
fs::write(&src, "////ch1 REWRITTEN\n").unwrap();
builder.input_filtered(&src, "ch1").unwrap();
builder.input_filtered(&src, "ch2").unwrap();
builder.done().unwrap();
assert_eq!(read_str(&out), "one\nthree\none\nthree\ntwo\n");
}
#[test]
fn f06_filtered_then_unfiltered_rerun() {
let tmp = TempDir::new("f06");
let src = tmp.write("f.rs", "////ch1 one\n//// plain\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input_filtered(&src, "ch1")
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "one\nplain\n");
}
#[test]
fn f07_unfiltered_backward_compat() {
let tmp = TempDir::new("f07");
let src = tmp.write("file.rs", "//// hello\n//// world\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "hello\nworld\n");
}
#[test]
fn f08_stdin_unfiltered_backward_compat() {
let tmp = TempDir::new("f08");
let src = tmp.write("stdin-content.txt", "//// persistent\n////t transient\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "persistent\n");
}
#[test]
fn f09_rerun_if_changed_emitted_once() {
if std::env::var_os("DOCEXTRACT_F09_SUBPROCESS").is_some() {
let tmp = TempDir::new("f09-child");
let src = tmp.write("in.rs", "////api doc\n");
let out = tmp.file("out.md");
let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
let mut builder = Docextract::new(&out).unwrap();
builder.input_filtered(&src, "api").unwrap(); builder.input_filtered(&src, "api").unwrap(); builder.done().unwrap();
return;
}
let exe = std::env::current_exe().unwrap();
let output = std::process::Command::new(&exe)
.env("DOCEXTRACT_F09_SUBPROCESS", "1")
.arg("--exact")
.arg("tests::tag_filter::f09_rerun_if_changed_emitted_once")
.arg("--nocapture")
.output()
.unwrap();
assert!(
output.status.success(),
"child test binary must exit 0, got {:?}",
output.status
);
let stdout = String::from_utf8_lossy(&output.stdout);
let directive_count = stdout.matches("cargo:rerun-if-changed=").count();
assert_eq!(
directive_count, 1,
"rerun-if-changed must be emitted exactly once (first access only), got: {stdout}"
);
}
#[test]
fn f10_persistent_tag_switch_mid_file() {
let tmp = TempDir::new("f10");
let src = tmp.write("f.rs", "//// first\n////sec\n//// second\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
builder.input(&src).unwrap(); builder.input_filtered(&src, "sec").unwrap(); builder.done().unwrap();
assert_eq!(read_str(&out), "first\nsecond\nsecond\n");
}
#[test]
fn f11_transient_skipped_when_unfiltered() {
let tmp = TempDir::new("f11");
let src = tmp.write("f.rs", "////t text\n//// regular\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "regular\n");
}
#[test]
fn f11a_transient_included_when_filter_matches() {
let tmp = TempDir::new("f11a");
let src = tmp.write("f.rs", "////t text\n//// regular\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input_filtered(&src, "t")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "text\n");
}
#[test]
fn f12_initial_tag_from_filename_stem() {
let tmp = TempDir::new("f12");
let src = tmp.write("lib.rs", "//// hello\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input_filtered(&src, "lib")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "hello\n");
}
#[test]
fn f13_nonmatching_filter_empty_output() {
let tmp = TempDir::new("f13");
let src = tmp.write("f.rs", "//// hello\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input_filtered(&src, "nonexistent")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "");
}
#[test]
fn f14_filter_output_none_clears_filter() {
let tmp = TempDir::new("f14");
let src = tmp.write("f.rs", "////api a\n//// plain\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
builder.filter_output(Some("api")).unwrap();
builder.input(&src).unwrap();
builder.filter_output(None).unwrap();
builder.input(&src).unwrap();
builder.done().unwrap();
assert_eq!(read_str(&out), "a\nplain\n");
}
#[test]
fn f15_empty_file_with_filter() {
let tmp = TempDir::new("f15");
let src = tmp.write("empty.rs", "");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input_filtered(&src, "api")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "");
}
#[test]
fn f16_only_tag_directives_no_output() {
let tmp = TempDir::new("f16");
let src = tmp.write("f.rs", "////api\n////chapter1\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "");
}
#[test]
fn f17_tag_with_special_chars() {
let tmp = TempDir::new("f17");
let src = tmp.write("f.rs", "////my-tag.v2! entry\n//// plain\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input_filtered(&src, "my-tag.*")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "entry\n");
}
#[test]
fn f18_consecutive_tag_switches_no_output() {
let tmp = TempDir::new("f18");
let src = tmp.write("f.rs", "////a\n////b\n////c\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "");
}
#[test]
fn f19_transient_then_transient_current_tag_unchanged() {
let tmp = TempDir::new("f19");
let src = tmp.write("f.rs", "////t1 one\n////t2 two\n//// final\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
builder.input_filtered(&src, "f").unwrap(); builder.input_filtered(&src, ".*").unwrap(); builder.done().unwrap();
assert_eq!(read_str(&out), "final\none\ntwo\nfinal\n");
}
#[test]
fn f20_no_separator_between_tag_changes() {
let tmp = TempDir::new("f20");
let src = tmp.write("f.rs", "////a one\n////b two\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input_filtered(&src, ".*")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "one\ntwo\n");
}
#[test]
fn f21_explicit_blank_doc_line() {
let tmp = TempDir::new("f21");
let src = tmp.write("f.rs", "//// one\n////\n//// two\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "one\n\ntwo\n");
}
#[test]
fn f22_large_file_filtered_extraction() {
let tmp = TempDir::new("f22");
let mut content = String::new();
let mut expected = String::new();
for i in 0..20_000 {
let text = format!("line {i} {}\n", "x".repeat(40));
let tag = if i % 2 == 0 { "a" } else { "b" };
let _ = write!(content, "////{tag} {text}");
if tag == "a" {
expected.push_str(&text);
}
}
assert!(content.len() >= 1_000_000, "source should be ~1 MiB");
let src = tmp.write("big.rs", &content);
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input_filtered(&src, "a")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), expected);
}
#[test]
fn f23_operation_after_done_returns_broken_pipe() {
let tmp = TempDir::new("f23");
let src = tmp.write("f.rs", "////api a\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
builder.done().unwrap();
let Err(err) = builder.input_filtered(&src, "api") else {
panic!("expected error after done()");
};
assert_eq!(err.kind(), std::io::ErrorKind::BrokenPipe);
}
#[test]
fn f24_blank_line_tagged_with_current_tag() {
let tmp = TempDir::new("f24");
let src = tmp.write("f.rs", "////\n////api\n////\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input_filtered(&src, "api")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "\n");
}
#[test]
fn f25_missing_file_warns_and_continues() {
let tmp = TempDir::new("f25");
let valid = tmp.write("valid.rs", "////api kept\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
assert!(
builder
.input_filtered(tmp.file("missing.rs"), "api")
.is_ok()
);
builder.input_filtered(&valid, "api").unwrap();
builder.done().unwrap();
assert_eq!(read_str(&out), "kept\n");
}
#[test]
fn f26_invalid_utf8_errors() {
let tmp = TempDir::new("f26");
let src = tmp.write_bytes("binary.rs", b"//// \xFF\xFE not utf8\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
let Err(err) = builder.input_filtered(&src, "api") else {
panic!("expected error for invalid UTF-8");
};
assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
builder.done().unwrap();
}
}
mod code_lifting {
use super::*;
#[test]
fn s01_basic_split() {
assert_eq!(
try_split_code_capturing("code; //// {{}}"),
Some(("code;", "{{}}"))
);
}
#[test]
fn s02_trailing_spaces_stripped_from_code() {
assert_eq!(
try_split_code_capturing(" let x = 5; //// {{}}"),
Some((" let x = 5;", "{{}}"))
);
}
#[test]
fn s03_single_space_is_separator() {
assert_eq!(
try_split_code_capturing("fn foo() { //// {{}}"),
Some(("fn foo() {", "{{}}"))
);
}
#[test]
fn s04_tab_separator() {
assert_eq!(
try_split_code_capturing("code\t//// {{}}"),
Some(("code", "{{}}"))
);
}
#[test]
fn s05_empty_template() {
assert_eq!(try_split_code_capturing("code ////"), Some(("code", "")));
}
#[test]
fn s06_no_separator_after_slashes() {
assert_eq!(
try_split_code_capturing("code ////text"),
Some(("code", "text"))
);
}
#[test]
fn s07_rightmost_double_slash_wins() {
assert_eq!(
try_split_code_capturing("code //// inner //// {{}}"),
Some(("code //// inner", "{{}}"))
);
}
#[test]
fn s08_double_slash_inside_string_literal() {
assert_eq!(
try_split_code_capturing(" let x = \"////\"; //// {{}}"),
Some((" let x = \"////\";", "{{}}"))
);
}
#[test]
fn s09_many_trailing_spaces_stripped() {
assert_eq!(
try_split_code_capturing("code; //// {{}}"),
Some(("code;", "{{}}"))
);
}
#[test]
fn s10_no_separator_before_slashes() {
assert_eq!(try_split_code_capturing("code////no-separator"), None);
}
#[test]
fn r01_full_substitution_double_trim() {
assert_eq!(resolve_placeholders("{{}}", " let x = 5;"), "let x = 5;");
}
#[test]
fn r02_full_substitution_plain_code() {
assert_eq!(resolve_placeholders("{{}}", "code"), "code");
}
#[test]
fn r03_full_substitution_empty_code() {
assert_eq!(resolve_placeholders("{{}}", ""), "");
}
#[test]
fn r04_zero_removal() {
assert_eq!(resolve_placeholders("{{0}}", "code"), "code");
}
#[test]
fn r05_remove_four_chars() {
assert_eq!(resolve_placeholders("{{4}}", " code"), "code");
}
#[test]
fn r06_remove_one_char() {
assert_eq!(resolve_placeholders("{{1}}", "abc"), "bc");
}
#[test]
fn r07_n_greater_than_code_length() {
assert_eq!(resolve_placeholders("{{3}}", "ab"), "");
}
#[test]
fn r08_n_much_greater_than_code_length() {
assert_eq!(resolve_placeholders("{{100}}", "short"), "");
}
#[test]
fn r09_placeholder_with_surrounding_text() {
assert_eq!(
resolve_placeholders("prefix {{}} suffix", "code"),
"prefix code suffix"
);
}
#[test]
fn r10_same_code_multiple_placeholders() {
assert_eq!(resolve_placeholders("{{}} and {{}}", "X"), "X and X");
}
#[test]
fn u01_multibyte_char_removed_by_count() {
assert_eq!(resolve_placeholders("{{1}}", "éabc"), "abc");
}
#[test]
fn u02_two_multibyte_chars_removed() {
assert_eq!(resolve_placeholders("{{2}}", "éàbc"), "bc");
}
#[test]
fn u03_astral_char_counts_once() {
assert_eq!(resolve_placeholders("{{3}}", "a😀b"), "");
}
#[test]
fn u04_zero_removal_multibyte_unchanged() {
assert_eq!(resolve_placeholders("{{0}}", "éabc"), "éabc");
}
#[test]
fn u05_n_greater_than_char_count() {
assert_eq!(resolve_placeholders("{{4}}", "a😀b"), "");
}
#[test]
fn trim_leading_space_tab_strips_only_leading_ws() {
assert_eq!(trim_leading_space_tab(" code"), "code");
assert_eq!(trim_leading_space_tab("\tcode"), "code");
assert_eq!(trim_leading_space_tab("code"), "code");
assert_eq!(trim_leading_space_tab(""), "");
}
#[test]
fn unescape_delimiter_unescapes_only_delimiter() {
assert_eq!(unescape_delimiter("foo\\/bar", b'/'), "foo/bar");
assert_eq!(unescape_delimiter("baz/qux", b'/'), "baz/qux");
}
fn assert_parse(input: &str, initial_tag: &str, expected: &[(&str, &str, bool)]) {
let mut tags = HashSet::new();
let entries = parse_doc_entries(&mut tags, input, initial_tag);
assert_eq!(entries.len(), expected.len(), "entry count mismatch");
for (entry, (tag, text, transient)) in entries.iter().zip(expected) {
assert_eq!(&*entry.tag, *tag, "tag mismatch");
assert_eq!(&*entry.text, *text, "text mismatch");
assert_eq!(entry.transient, *transient, "transient mismatch");
}
}
#[test]
fn e01_basic_substitution_with_double_trim() {
assert_parse(
" let x = 5; //// value: {{}}\n",
"lib",
&[("value:", "let x = 5;\n", true)],
);
}
#[test]
fn e02_n_placeholder_character_removal() {
assert_parse(
" let x = 5; //// {{8}}\n",
"lib",
&[("lib", "x = 5;\n", false)],
);
}
#[test]
fn e03_n_exceeds_code_length() {
assert_parse(
" let x = 5; //// {{100}}\n",
"lib",
&[("lib", "\n", false)],
);
}
#[test]
fn e04_code_capture_between_doc_lines() {
assert_parse(
"//// # Before\n code; //// {{}}\n//// # After\n",
"lib",
&[
("lib", "# Before\n", false),
("lib", "code;\n", false),
("lib", "# After\n", false),
],
);
}
#[test]
fn e05_back_to_back_code_captures() {
assert_parse(
" a; //// {{}}\n b; //// {{}}\n",
"lib",
&[("lib", "a;\n", false), ("lib", "b;\n", false)],
);
}
#[test]
fn e06_template_with_no_placeholder() {
assert_parse(
" code; //// just text\n",
"lib",
&[("just", "text\n", true)],
);
}
#[test]
fn e07_empty_template() {
assert_parse(" code; ////\n", "lib", &[("lib", "\n", false)]);
}
#[test]
fn e08_multiple_placeholders() {
assert_parse(" X; //// a{{}}b{{}}c\n", "lib", &[]);
}
#[test]
fn e09_unterminated_double_brace() {
assert_parse(
" X; //// text {{ oops\n",
"lib",
&[("text", "{{ oops\n", true)],
);
}
#[test]
fn e10_code_capture_with_tag_directive() {
assert_parse(
"////foo\n code; //// {{}}\n",
"lib",
&[("foo", "code;\n", false)],
);
}
#[test]
fn e11_backward_compat_doc_lines_only() {
assert_parse(
"//// Hello\n//// World\n",
"lib",
&[("lib", "Hello\n", false), ("lib", "World\n", false)],
);
}
#[test]
fn e12_backward_compat_doc_with_code() {
assert_parse(
"//// Doc\nlet x = 5;\n//// More\n",
"lib",
&[("lib", "Doc\n", false), ("lib", "More\n", false)],
);
}
#[test]
fn e13_doc_line_with_trailing_slashes_not_code_capture() {
assert_parse(
"//// This text ends with ////\n",
"lib",
&[("lib", "This text ends with ////\n", false)],
);
}
#[test]
fn e14_tag_directive_not_code_capture() {
assert_parse("////foo bar\n", "lib", &[("foo", "bar\n", true)]);
}
#[test]
fn e15_crlf_preserved() {
assert_parse(
"code; //// {{}}\r\n",
"lib",
&[("lib", "code;\r\n", false)],
);
}
#[test]
fn e16_no_separator_before_slashes() {
assert_parse("code////no-separator\n", "lib", &[]);
}
#[test]
#[should_panic(expected = "reserved placeholder form")]
fn e17_reserved_form_panics() {
let mut tags = HashSet::new();
let _entries = parse_doc_entries(&mut tags, "code; //// {{abc}}\n", "lib");
}
#[test]
fn e18_capture_zone_continuation() {
assert_parse(
concat!(
"//// lets show the internal code\n",
"//// ```\n",
" code //// {{}}\n",
" //// {{4}} suffix\n",
" more //// {{}}\n",
"//// ```\n",
),
"lib",
&[
("lib", "lets show the internal code\n", false),
("lib", "```\n", false),
("lib", "code\n", false),
("lib", " suffix\n", false),
("lib", "more\n", false),
("lib", "```\n", false),
],
);
}
#[test]
fn e19_transient_tag_on_code_capture() {
assert_parse(
concat!(
"//// lets show the internal code\n",
"//// ```\n",
"fn foo() {\n",
" const FOO:i32=0; ////constants code: {{}}\n",
" let x=1; //// {{4}}\n",
" //// {{4}}\n",
" println!(\"{x}\"); //// {{4}}\n",
"}\n",
"//// ```\n",
),
"lib",
&[
("lib", "lets show the internal code\n", false),
("lib", "```\n", false),
("constants", "code: const FOO:i32=0;\n", true),
("lib", "let x=1;\n", false),
("lib", "\n", false),
("lib", "println!(\"{x}\");\n", false),
("lib", "```\n", false),
],
);
}
#[test]
fn e20_persistent_tag_on_code_capture() {
assert_parse(
concat!(
"//// before\n",
" code; ////mytag\n", " more; //// {{}}\n", ),
"lib",
&[
("lib", "before\n", false),
("mytag", "more;\n", false),
],
);
}
#[test]
fn e21_transient_then_persistent_on_code_capture() {
assert_parse(
concat!(
" a; ////tag1 {{}}\n", " b; ////tag2\n", " c; //// {{}}\n", ),
"lib",
&[
("tag1", "a;\n", true),
("tag2", "c;\n", false),
],
);
}
#[test]
fn e22_continuation_with_persistent_tag() {
assert_parse(
concat!(
" code; //// {{}}\n", " ////mytag\n", " //// {{}}\n", ),
"lib",
&[
("lib", "code;\n", false),
("mytag", "\n", false),
],
);
}
#[test]
fn f01_code_capture_matches_output_filter() {
let tmp = TempDir::new("lift_f01");
let src = tmp.write("f.rs", "////chapter1\n code; //// {{}}\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.filter_output(Some("chapter1"))
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "code;\n");
}
#[test]
fn f02_code_capture_filtered_out_by_tag() {
let tmp = TempDir::new("lift_f02");
let src = tmp.write("f.rs", "////chapter2\n code; //// {{}}\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.filter_output(Some("chapter1"))
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "");
}
#[test]
fn f03_unfiltered_emits_both() {
let tmp = TempDir::new("lift_f03");
let src = tmp.write("f.rs", "//// Doc\n code; //// {{}}\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "Doc\ncode;\n");
}
#[test]
fn f04_input_filtered_code_capture() {
let tmp = TempDir::new("lift_f04");
let src = tmp.write(
"f.rs",
"////api\n//// doc\n code; //// captured\n////core text\n",
);
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input_filtered(&src, "api")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "doc\n");
}
#[test]
fn f05_code_capture_is_persistent() {
let tmp = TempDir::new("lift_f05");
let src = tmp.write("f.rs", "////t transient\n code; //// captured\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "");
}
#[test]
fn f06_code_capture_carries_tag_and_responds_to_filter() {
let tmp = TempDir::new("lift_f06");
let src = tmp.write(
"f.rs",
concat!("////detail\n", " code; //// captured\n", "//// doc\n"),
);
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "doc\n");
let out2 = tmp.file("out2.md");
Docextract::new(&out2)
.unwrap()
.filter_output(Some("detail"))
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out2), "");
}
#[cfg(feature = "regex")]
#[test]
fn ex01_replace_outputs_only_substitution() {
assert_eq!(
resolve_placeholders("{{/fn (.*);/$1/}}", "pub fn new;"),
"new"
);
}
#[cfg(feature = "regex")]
#[test]
fn ex02_replace_no_match_returns_empty() {
assert_eq!(resolve_placeholders("{{/xxx/$1/}}", "pub fn new;"), "");
}
#[cfg(feature = "regex")]
#[test]
fn ex03_extract_still_outputs_match() {
assert_eq!(
resolve_placeholders("{{/fn .*;/}}", "pub fn new;"),
"fn new;"
);
}
}
mod global_cache {
use super::*;
use std::rc::Rc;
fn run_cache_sharing_subprocess(child_env: &str, test_name: &str) -> std::process::Output {
let exe = std::env::current_exe().unwrap();
std::process::Command::new(&exe)
.env(child_env, "1")
.arg("--exact")
.arg(test_name)
.arg("--nocapture")
.output()
.unwrap()
}
#[test]
fn tc01_cache_sharing_two_instances() {
if std::env::var_os("DOCEXTRACT_TC01_SUBPROCESS").is_some() {
let tmp = TempDir::new("tc01");
let src = tmp.write("in.rs", "////api doc\n");
let out1 = tmp.file("out1.md");
let out2 = tmp.file("out2.md");
let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
Docextract::new(&out1)
.unwrap()
.input_filtered(&src, "api")
.unwrap()
.done()
.unwrap();
Docextract::new(&out2)
.unwrap()
.input_filtered(&src, "api")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out1), "doc\n");
assert_eq!(read_str(&out2), "doc\n");
return;
}
let output = run_cache_sharing_subprocess(
"DOCEXTRACT_TC01_SUBPROCESS",
"tests::global_cache::tc01_cache_sharing_two_instances",
);
assert!(output.status.success(), "child failed: {:?}", output.status);
let stdout = String::from_utf8_lossy(&output.stdout);
let directive_count = stdout.matches("cargo:rerun-if-changed=").count();
assert_eq!(
directive_count, 1,
"rerun-if-changed must be emitted exactly once across two instances, got: {stdout}"
);
assert!(
String::from_utf8_lossy(&output.stderr).is_empty(),
"no warnings expected"
);
}
#[test]
fn tc01_cache_sharing_three_instances() {
if std::env::var_os("DOCEXTRACT_TC01B_SUBPROCESS").is_some() {
let tmp = TempDir::new("tc01b");
let src = tmp.write("in.rs", "////api a\n");
let out1 = tmp.file("out1.md");
let out2 = tmp.file("out2.md");
let out3 = tmp.file("out3.md");
let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
Docextract::new(&out1)
.unwrap()
.input_filtered(&src, "api")
.unwrap()
.done()
.unwrap();
Docextract::new(&out2)
.unwrap()
.input_filtered(&src, "api")
.unwrap()
.done()
.unwrap();
Docextract::new(&out3)
.unwrap()
.input_filtered(&src, "api")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out1), "a\n");
assert_eq!(read_str(&out2), "a\n");
assert_eq!(read_str(&out3), "a\n");
return;
}
let output = run_cache_sharing_subprocess(
"DOCEXTRACT_TC01B_SUBPROCESS",
"tests::global_cache::tc01_cache_sharing_three_instances",
);
assert!(output.status.success(), "child failed: {:?}", output.status);
let stdout = String::from_utf8_lossy(&output.stdout);
let directive_count = stdout.matches("cargo:rerun-if-changed=").count();
assert_eq!(
directive_count, 1,
"rerun-if-changed must be emitted exactly once across three instances, got: {stdout}"
);
}
#[test]
fn tc02_clear_cache_then_reparse() {
if std::env::var_os("DOCEXTRACT_TC02_SUBPROCESS").is_some() {
let tmp = TempDir::new("tc02");
let src = tmp.write("in.rs", "////api doc\n");
let out1 = tmp.file("out1.md");
let out2 = tmp.file("out2.md");
let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
Docextract::new(&out1)
.unwrap()
.input_filtered(&src, "api")
.unwrap()
.done()
.unwrap();
Docextract::clear_cache();
Docextract::new(&out2)
.unwrap()
.input_filtered(&src, "api")
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out1), "doc\n");
assert_eq!(read_str(&out2), "doc\n");
return;
}
let output = run_cache_sharing_subprocess(
"DOCEXTRACT_TC02_SUBPROCESS",
"tests::global_cache::tc02_clear_cache_then_reparse",
);
assert!(output.status.success(), "child failed: {:?}", output.status);
let stdout = String::from_utf8_lossy(&output.stdout);
let directive_count = stdout.matches("cargo:rerun-if-changed=").count();
assert_eq!(
directive_count, 2,
"rerun-if-changed must be emitted twice: before and after clear_cache, got: {stdout}"
);
}
#[test]
fn tc02_clear_cache_on_empty_cache_noop() {
Docextract::clear_cache();
Docextract::clear_cache();
}
#[test]
fn tc02_clear_cache_between_inputs_on_same_instance() {
let tmp = TempDir::new("tc02c");
let src = tmp.write("in.rs", "//// doc\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
builder.input(&src).unwrap();
fs::write(&src, "//// new\n").unwrap();
Docextract::clear_cache();
builder.input(&src).unwrap();
builder.done().unwrap();
assert_eq!(read_str(&out), "doc\nnew\n");
}
#[test]
fn tc03_equivalent_paths_share_cache() {
let tmp = TempDir::new("tc03");
let src = tmp.write("file.rs", "//// hello\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
let canonical = std::fs::canonicalize(&src).unwrap();
builder.input(&canonical).unwrap();
builder.input(&src).unwrap();
builder.done().unwrap();
assert_eq!(read_str(&out), "hello\nhello\n");
}
#[test]
fn tc03_dot_slash_path_resolves() {
let tmp = TempDir::new("tc03b");
let subdir = tmp.file("subdir");
fs::create_dir_all(&subdir).unwrap();
let file_in_sub = subdir.join("file.rs");
fs::write(&file_in_sub, "//// data\n").unwrap();
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
let orig_cwd = std::env::current_dir().unwrap();
std::env::set_current_dir(tmp.0.as_path()).unwrap();
builder.input("./subdir/file.rs").unwrap();
builder.input("subdir/file.rs").unwrap();
builder.done().unwrap();
std::env::set_current_dir(orig_cwd).unwrap();
assert_eq!(read_str(&out), "data\ndata\n");
}
#[test]
fn tc04_stdin_twice_on_same_instance() {
}
#[test]
fn tc04_repeated_filtered_stdin_uses_cache() {
let tmp = TempDir::new("tc04");
let src = tmp.write("in.txt", "////api a\n////b b\n");
let out = tmp.file("out.md");
let mut builder = Docextract::new(&out).unwrap();
builder.input_filtered(&src, "api").unwrap();
builder.input_filtered(&src, "b").unwrap();
builder.done().unwrap();
assert_eq!(read_str(&out), "a\nb\n");
}
#[test]
fn tc06_tag_interning_across_instances() {
let tmp = TempDir::new("tc06");
let src1 = tmp.write("a.rs", "////foo bar\n");
let src2 = tmp.write("b.rs", "////foo baz\n");
let content1 = fs::read_to_string(&src1).unwrap();
let content2 = fs::read_to_string(&src2).unwrap();
let mut tags = HashSet::new();
let entries1 = parse_doc_entries(&mut tags, &content1, "a");
let entries2 = parse_doc_entries(&mut tags, &content2, "b");
assert_eq!(entries1.len(), 1);
assert_eq!(entries2.len(), 1);
assert_eq!(&*entries1[0].tag, "foo");
assert_eq!(&*entries2[0].tag, "foo");
assert!(
Rc::ptr_eq(&entries1[0].tag, &entries2[0].tag),
"tag 'foo' from two different parse calls must share the same Rc<str> allocation"
);
}
#[test]
fn tc09_missing_file_returns_ok_on_both_instances() {
let tmp = TempDir::new("tc09");
let out1 = tmp.file("out1.md");
let out2 = tmp.file("out2.md");
let missing = tmp.file("does_not_exist.rs");
let mut builder1 = Docextract::new(&out1).unwrap();
assert!(
builder1.input(&missing).is_ok(),
"missing file must return Ok (warning to stderr)"
);
let mut builder2 = Docextract::new(&out2).unwrap();
assert!(
builder2.input(&missing).is_ok(),
"second instance with missing file must also return Ok"
);
builder1.done().unwrap();
builder2.done().unwrap();
}
#[test]
fn tc08_single_instance_output_unchanged() {
let tmp = TempDir::new("tc08");
let src = tmp.write("in.rs", "//// Hello\n//// World\n");
let out = tmp.file("out.md");
Docextract::new(&out)
.unwrap()
.input(&src)
.unwrap()
.done()
.unwrap();
assert_eq!(read_str(&out), "Hello\nWorld\n");
}
}
}