rusty_pdfgrep/

lib.rs

//! # rusty-pdfgrep
//!
//! A Rust port of Hans-Peter Deifel's `pdfgrep(1)` — grep through PDF files
//! using page-level text extraction and pluggable regex engines.
//!
//! ## Quick start
//!
//! ```no_run
//! use rusty_pdfgrep::PdfGrepBuilder;
//! use std::path::Path;
//!
//! let pdfgrep = PdfGrepBuilder::new()
//!     .pattern("force majeure")
//!     .case_insensitive(true)
//!     .build()
//!     .unwrap();
//!
//! for result in pdfgrep.search_file(Path::new("contract.pdf")) {
//!     let m = result.unwrap();
//!     println!("{}:{}: {}", m.path.display(), m.page, m.text);
//! }
//! ```
//!
//! ## Stability
//!
//! Library and binary share a single crate version. `lopdf` is pinned to the
//! 0.36 minor; `regex` + `fancy-regex` engines are SemVer-stable. The
//! `PdfGrepError` and `Match` types are `#[non_exhaustive]` — downstream code
//! MUST use a wildcard `_` arm when matching.

#![deny(missing_docs)]

pub mod engine;
pub mod error;
pub mod pdf;

pub use error::PdfGrepError;

use std::path::{Path, PathBuf};

/// A single matched occurrence in a PDF page (FR-040).
///
/// `byte_span` indexes into `Match.text` — slicing `&text[byte_span.0..byte_span.1]`
/// yields the matched substring. UTF-8 codepoint boundaries are aligned.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Match {
    /// Source path of the PDF containing this match.
    pub path: PathBuf,
    /// 1-indexed page number where the match was found.
    pub page: u32,
    /// Full containing line of extracted text (the substring of page text
    /// between adjacent line breaks). When `-o`/`only_matching` is set on the
    /// runner, `text` is the matched span only.
    pub text: String,
    /// `(start, end)` byte offsets within `Match.text` for the matched substring.
    pub byte_span: (usize, usize),
}

/// Configured pattern matcher. Construct via [`PdfGrepBuilder`].
pub struct PdfGrep {
    engine: engine::Engine,
    invert_match: bool,
    only_matching: bool,
    max_count: Option<usize>,
    page_range: Option<(u32, u32)>,
    passwords: Vec<String>,
}

impl PdfGrep {
    /// Search a single PDF file. Returns an iterator yielding matches lazily,
    /// one page of extraction work per `.next()` call (FR-042).
    ///
    /// Peak memory is bounded by `O(one page of text + match buffer)` —
    /// never `O(whole document)`.
    pub fn search_file<'a>(&'a self, path: &Path) -> PageIterator<'a> {
        PageIterator::new(self, path.to_path_buf())
    }

    /// Convenience: run [`search_file`](Self::search_file) and collect into a
    /// `Vec<Match>`. Eager; for large documents, prefer the iterator.
    pub fn search_file_collected(&self, path: &Path) -> Result<Vec<Match>, PdfGrepError> {
        self.search_file(path).collect()
    }

    /// True when `-v`/`--invert-match` is active.
    #[must_use]
    pub fn invert_match(&self) -> bool {
        self.invert_match
    }

    /// True when `-o`/`--only-matching` is active.
    #[must_use]
    pub fn only_matching(&self) -> bool {
        self.only_matching
    }

    /// Configured `-m N` cap.
    #[must_use]
    pub fn max_count(&self) -> Option<usize> {
        self.max_count
    }

    /// Configured `--page-range N-M`.
    #[must_use]
    pub fn page_range(&self) -> Option<(u32, u32)> {
        self.page_range
    }

    /// Configured `--password PWD` list (in flag order).
    #[must_use]
    pub fn passwords(&self) -> &[String] {
        &self.passwords
    }
}

impl std::fmt::Debug for PdfGrep {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PdfGrep")
            .field("invert_match", &self.invert_match)
            .field("only_matching", &self.only_matching)
            .field("max_count", &self.max_count)
            .field("page_range", &self.page_range)
            .field("passwords", &format!("<{} entries>", self.passwords.len()))
            .finish()
    }
}

/// Builder for [`PdfGrep`] (FR-039). All methods are independent and
/// order-agnostic; `password(...)` appends to the retry list and is the only
/// repeatable setter.
#[derive(Debug, Clone, Default)]
pub struct PdfGrepBuilder {
    pattern: Option<String>,
    fixed_strings: bool,
    perl_regexp: bool,
    case_insensitive: bool,
    invert_match: bool,
    only_matching: bool,
    max_count: Option<usize>,
    page_range: Option<(u32, u32)>,
    passwords: Vec<String>,
}

impl PdfGrepBuilder {
    /// Fresh builder with all defaults applied.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Required pattern (PCRE or fixed string per `fixed_strings`/`perl_regexp`).
    #[must_use]
    pub fn pattern(mut self, p: impl Into<String>) -> Self {
        self.pattern = Some(p.into());
        self
    }

    /// `-F`/`--fixed-strings` — escape metacharacters in `pattern`.
    #[must_use]
    pub fn fixed_strings(mut self, on: bool) -> Self {
        self.fixed_strings = on;
        self
    }

    /// `-P`/`--perl-regexp` — use `fancy-regex` engine instead of `regex`.
    #[must_use]
    pub fn perl_regexp(mut self, on: bool) -> Self {
        self.perl_regexp = on;
        self
    }

    /// `-i`/`--ignore-case`.
    #[must_use]
    pub fn case_insensitive(mut self, on: bool) -> Self {
        self.case_insensitive = on;
        self
    }

    /// `-v`/`--invert-match`.
    #[must_use]
    pub fn invert_match(mut self, on: bool) -> Self {
        self.invert_match = on;
        self
    }

    /// `-o`/`--only-matching` — `Match.text` is the matched span only.
    #[must_use]
    pub fn only_matching(mut self, on: bool) -> Self {
        self.only_matching = on;
        self
    }

    /// `-m N`/`--max-count` — stop after N matches.
    #[must_use]
    pub fn max_count(mut self, n: Option<usize>) -> Self {
        self.max_count = n;
        self
    }

    /// `--page-range N-M` (1-indexed inclusive).
    #[must_use]
    pub fn page_range(mut self, range: Option<(u32, u32)>) -> Self {
        self.page_range = range;
        self
    }

    /// `--password PWD` — repeatable; each call APPENDS to the retry list
    /// (FR-025, FR-039 + Clarifications Q4).
    #[must_use]
    pub fn password(mut self, pwd: impl Into<String>) -> Self {
        self.passwords.push(pwd.into());
        self
    }

    /// Build a configured [`PdfGrep`]. FALLIBLE — regex compile failure maps
    /// to `PdfGrepError::RegexCompile`; invalid `page_range` maps to
    /// `PdfGrepError::PageRange`.
    ///
    /// # Errors
    ///
    /// - `PdfGrepError::RegexCompile` if the pattern fails to compile.
    /// - `PdfGrepError::PageRange` if the page range is reverse (start > end).
    pub fn build(self) -> Result<PdfGrep, PdfGrepError> {
        let pattern = self.pattern.unwrap_or_default();
        let engine = engine::compile(
            &pattern,
            self.fixed_strings,
            self.perl_regexp,
            self.case_insensitive,
        )?;
        if let Some((start, end)) = self.page_range {
            if start > end {
                return Err(PdfGrepError::PageRange {
                    value: format!("{start}-{end}"),
                });
            }
        }
        Ok(PdfGrep {
            engine,
            invert_match: self.invert_match,
            only_matching: self.only_matching,
            max_count: self.max_count,
            page_range: self.page_range,
            passwords: self.passwords,
        })
    }
}

/// Lazy per-page iterator returned by [`PdfGrep::search_file`].
///
/// State machine: opens the PDF on first `.next()`, then for each page in
/// the configured range extracts text, finds matches, and yields them one
/// at a time. Advances to the next page only when the current page's
/// matches are exhausted.
pub struct PageIterator<'a> {
    grep: &'a PdfGrep,
    path: PathBuf,
    doc: Option<pdf::PdfDocument>,
    init_error: Option<PdfGrepError>,
    page_idx: usize,
    page_numbers: Vec<u32>,
    current_text: Option<String>,
    current_matches: Vec<(usize, usize)>,
    current_match_idx: usize,
    yielded: usize,
    started: bool,
}

impl<'a> PageIterator<'a> {
    fn new(grep: &'a PdfGrep, path: PathBuf) -> Self {
        PageIterator {
            grep,
            path,
            doc: None,
            init_error: None,
            page_idx: 0,
            page_numbers: Vec::new(),
            current_text: None,
            current_matches: Vec::new(),
            current_match_idx: 0,
            yielded: 0,
            started: false,
        }
    }

    fn ensure_started(&mut self) {
        if self.started {
            return;
        }
        self.started = true;
        match pdf::PdfDocument::open(&self.path, &self.grep.passwords) {
            Ok(doc) => {
                let mut nums: Vec<u32> = doc.page_numbers().to_vec();
                if let Some((start, end)) = self.grep.page_range {
                    nums.retain(|&n| n >= start && n <= end);
                }
                self.page_numbers = nums;
                self.doc = Some(doc);
            }
            Err(e) => {
                self.init_error = Some(e);
            }
        }
    }
}

impl Iterator for PageIterator<'_> {
    type Item = Result<Match, PdfGrepError>;

    fn next(&mut self) -> Option<Self::Item> {
        self.ensure_started();
        if let Some(err) = self.init_error.take() {
            return Some(Err(err));
        }
        let doc = self.doc.as_ref()?;

        // Respect -m N cap.
        if let Some(cap) = self.grep.max_count {
            if self.yielded >= cap {
                return None;
            }
        }

        loop {
            // Try to yield a remaining match from the current page.
            if let Some(text) = &self.current_text {
                if self.current_match_idx < self.current_matches.len() {
                    let (start, end) = self.current_matches[self.current_match_idx];
                    self.current_match_idx += 1;
                    // Construct the Match per FR-007/FR-040: containing line.
                    let line = containing_line(text, start, end);
                    let (line_start, line_end) = line;
                    let line_text = text[line_start..line_end].to_string();
                    let span_in_line = (start - line_start, end - line_start);
                    let m = Match {
                        path: self.path.clone(),
                        page: self
                            .page_numbers
                            .get(self.page_idx - 1)
                            .copied()
                            .unwrap_or(0),
                        text: if self.grep.only_matching {
                            text[start..end].to_string()
                        } else {
                            line_text
                        },
                        byte_span: if self.grep.only_matching {
                            (0, end - start)
                        } else {
                            span_in_line
                        },
                    };
                    self.yielded += 1;
                    return Some(Ok(m));
                }
                // Page exhausted; advance.
                self.current_text = None;
                self.current_matches.clear();
                self.current_match_idx = 0;
            }

            // Advance to next page.
            if self.page_idx >= self.page_numbers.len() {
                return None;
            }
            let page = self.page_numbers[self.page_idx];
            self.page_idx += 1;
            match doc.extract_page(page) {
                Ok(text) => {
                    let matches = self.grep.engine.find_all(&text);
                    if self.grep.invert_match {
                        // -v semantics: emit lines that DON'T match. v0.1.0
                        // simplification: skip the page if any match exists;
                        // refine in iter-2 to per-line inversion.
                        if matches.is_empty() && !text.is_empty() {
                            // Emit one "page-as-line" Match with empty span.
                            let m = Match {
                                path: self.path.clone(),
                                page,
                                text: text.clone(),
                                byte_span: (0, 0),
                            };
                            self.yielded += 1;
                            return Some(Ok(m));
                        }
                        continue;
                    }
                    self.current_text = Some(text);
                    self.current_matches = matches;
                    self.current_match_idx = 0;
                }
                Err(msg) => {
                    eprintln!("rusty-pdfgrep: {}: {msg}", self.path.display());
                    continue;
                }
            }
        }
    }
}

/// Find the byte range `[start, end)` of the line containing the given match
/// span in `text`. Lines are delimited by `\n`; the trailing `\n` is excluded
/// from the returned slice.
fn containing_line(text: &str, match_start: usize, match_end: usize) -> (usize, usize) {
    let line_start = text[..match_start].rfind('\n').map(|i| i + 1).unwrap_or(0);
    let line_end = text[match_end..]
        .find('\n')
        .map(|i| match_end + i)
        .unwrap_or(text.len());
    (line_start, line_end)
}

#[cfg(test)]
mod tests {
    use super::*;
    use static_assertions::assert_impl_all;

    assert_impl_all!(PdfGrep: Send);
    assert_impl_all!(PdfGrepBuilder: Send, Sync);
    assert_impl_all!(Match: Send, Sync);
    assert_impl_all!(PdfGrepError: Send, Sync);

    #[test]
    fn builder_requires_no_pattern_to_build() {
        // Empty pattern compiles to a regex that matches everywhere; not an error.
        let g = PdfGrepBuilder::new().build();
        assert!(g.is_ok());
    }

    #[test]
    fn builder_invalid_regex_returns_err() {
        let err = PdfGrepBuilder::new()
            .pattern("[invalid")
            .build()
            .unwrap_err();
        assert!(matches!(err, PdfGrepError::RegexCompile { .. }));
    }

    #[test]
    fn builder_reverse_page_range_returns_err() {
        let err = PdfGrepBuilder::new()
            .pattern("x")
            .page_range(Some((5, 3)))
            .build()
            .unwrap_err();
        assert!(matches!(err, PdfGrepError::PageRange { .. }));
    }

    #[test]
    fn builder_password_appends_in_order() {
        let g = PdfGrepBuilder::new()
            .pattern("x")
            .password("a")
            .password("b")
            .password("c")
            .build()
            .unwrap();
        assert_eq!(g.passwords(), &["a", "b", "c"]);
    }

    #[test]
    fn containing_line_extracts_correctly() {
        let text = "first line\nsecond match here\nthird line";
        let (s, e) = containing_line(text, 18, 23);
        assert_eq!(&text[s..e], "second match here");
    }

    #[test]
    fn containing_line_no_newlines_returns_full_text() {
        let text = "single line no newlines";
        let (s, e) = containing_line(text, 7, 11);
        assert_eq!((s, e), (0, text.len()));
    }
}