docextract 0.4.0

documentation extractor
Documentation
//! `cargo-docextract` - CLI binary for extracting `////` documentation from
//! Rust source files. Delegates all extraction logic to the `docextract`
//! library's `Docextract` builder.

use std::process::exit;

const HELP_TEXT: &str = "\
cargo-docextract - extract //// documentation from Rust source files

Usage: cargo-docextract <output> [inputs...]

Arguments:
  <output>       Output file path, or '-' for stdout (mandatory).
                 Prefix with 'filter@' for output filtering,
                 e.g., 'chapter.*@output.md'.
  [inputs...]    Input file paths, or '-' for stdin (zero or more).
                 Prefix with 'filter@' to filter by tag pattern,
                 e.g., 'api@src/lib.rs'.

Tag filtering:
  Lines can be tagged with ////tagname directives in source files.
  Use 'filter@path' to extract only lines matching a pattern.
  Multiple filtered reads of the same file reorder output.
  Without '@', behavior is identical to before.

Examples:
  cargo-docextract docs.md src/macros.rs      Extract from one file
  cargo-docextract - src/macros.rs            Extract to stdout
  cargo-docextract api@docs.md src/lib.rs     Filter by 'api' tag
  cargo-docextract 'chapter.*'@out.md chapter1@in.rs chapter2@in.rs
  cargo-docextract -                          Pipe stdin → stdout
  cargo-docextract --help                     Print this help

There are no options or flags. All arguments are positional.
";

fn print_help() {
    println!("{HELP_TEXT}");
}

/// Split an argument at the first `@` character.
/// Returns `(filter_or_none, path)`.
fn split_filter(arg: &str) -> (Option<&str>, &str) {
    if let Some(pos) = arg.find('@') {
        (Some(&arg[..pos]), &arg[pos + 1..])
    } else {
        (None, arg)
    }
}

#[allow(clippy::too_many_lines)]
fn main() {
    let args: Vec<String> = std::env::args().collect();
    // Strip Cargo's injected subcommand name (argv[1] = "docextract" when
    // invoked as `cargo docextract`). The binary name is "cargo-docextract",
    // so stripping the "cargo-" prefix gives "docextract".
    let subcommand_name = std::path::Path::new(&args[0])
        .file_stem()
        .and_then(|s| s.to_str())
        .unwrap_or("")
        .strip_prefix("cargo-")
        .unwrap_or("");
    let skip = if args.len() > 1 && args[1] == subcommand_name {
        2
    } else {
        1
    };
    let user_args: Vec<String> = args.into_iter().skip(skip).collect();

    if user_args.is_empty() || user_args.iter().any(|a| -> bool { a == "--help" }) {
        print_help();
        exit(0);
    }

    // Handle lone "-" shorthand: output="-" and input="-", no filters
    let (output_filter, output_arg, input_args) = if user_args.len() == 1 && user_args[0] == "-" {
        (None, "-", vec![("-", None)])
    } else {
        // Parse output argument with optional filter
        let (output_filter, output_arg) = split_filter(&user_args[0]);

        let inputs: Vec<(&str, Option<&str>)> = user_args[1..]
            .iter()
            .map(|arg| {
                let (filter, path) = split_filter(arg);
                (path, filter)
            })
            .collect();

        (output_filter, output_arg, inputs)
    };

    let mut extractor = match docextract::Docextract::new(output_arg) {
        Ok(e) => e,
        Err(e) => {
            eprintln!("cargo-docextract: error: {output_arg}: {e}");
            exit(2);
        }
    };
    extractor.rerun_if_changed(false);

    // Apply output filter if present
    if let Some(filter) = output_filter {
        if let Err(e) = extractor.filter_output(Some(filter)) {
            eprintln!("cargo-docextract: error: invalid filter pattern '{filter}': {e}");
            exit(2);
        }
    }

    let mut success_count: usize = 0;
    let mut had_hard_error: bool = false;
    let mut stdin_consumed: bool = false;
    let total_inputs = input_args.len();

    for (input_path, input_filter) in &input_args {
        let is_stdin = *input_path == "-";

        if is_stdin {
            if stdin_consumed && input_filter.is_none() {
                success_count += 1;
                continue;
            }
            let result = match input_filter {
                Some(filter) => {
                    if stdin_consumed {
                        extractor.input_filtered("-", filter)
                    } else {
                        stdin_consumed = true;
                        extractor.input_filtered("-", filter)
                    }
                }
                None => {
                    if stdin_consumed {
                        extractor.stdin()
                    } else {
                        stdin_consumed = true;
                        extractor.stdin()
                    }
                }
            };
            match result {
                Ok(_) => success_count += 1,
                Err(e) => {
                    eprintln!("cargo-docextract: error: stdin: {e}");
                    had_hard_error = true;
                    break;
                }
            }
        } else {
            // File input — for unfiltered inputs, pre-check file existence
            // before delegating to the library.
            if input_filter.is_none() {
                let path = std::path::Path::new(input_path);
                if !path.exists() {
                    eprintln!("cargo-docextract: warning: input file not found: {input_path}");
                    continue;
                }
            }

            // Delegate to library for extraction (filtered → input_filtered,
            // unfiltered → input). Filtered path uses K10 behavior (library
            // handles file-not-found internally with its own warning prefix).
            let result = match input_filter {
                Some(filter) => extractor.input_filtered(input_path, filter),
                None => extractor.input(input_path),
            };
            match result {
                Ok(_) => {
                    success_count += 1;
                }
                Err(e) => {
                    eprintln!("cargo-docextract: error: {input_path}: {e}");
                    had_hard_error = true;
                    break;
                }
            }
        }
    }

    // Finalize
    if let Err(e) = extractor.done() {
        eprintln!("cargo-docextract: error: output: {e}");
        exit(2);
    }

    if had_hard_error {
        exit(2);
    }

    if total_inputs == 0 {
        exit(0);
    }

    if success_count == 0 {
        eprintln!("cargo-docextract: error: no input files could be read");
        exit(2);
    }

    exit(0);
}