oxidize_pdf/

lib.rs

//! # oxidize-pdf
//!
//! A comprehensive, pure Rust PDF library for generation, parsing, and manipulation with zero external PDF dependencies.
//!
//! ## Features
//!
//! - **PDF Generation**: Create multi-page documents with text, graphics, and images
//! - **PDF Parsing**: Complete parser supporting rendering and content extraction
//! - **PDF Operations**: Split, merge, rotate, and extract pages
//! - **Text Extraction**: Extract text with position and formatting information
//! - **Image Extraction**: Extract images in JPEG, PNG, and TIFF formats
//! - **Page Analysis**: Detect scanned vs text content with intelligent classification
//! - **OCR Integration**: Pluggable OCR support with Tesseract for processing scanned documents (v0.1.3+)
//! - **Resource Access**: Work with fonts, images, and other PDF resources
//! - **Pure Rust**: No C dependencies or external libraries
//! - **100% Native**: Complete PDF implementation from scratch
//!
//! ## Quick Start
//!
//! ### Creating PDFs
//!
//! ```rust
//! use oxidize_pdf::{Document, Page, Font, Color, Result};
//!
//! # fn main() -> Result<()> {
//! // Create a new document
//! let mut doc = Document::new();
//! doc.set_title("My PDF");
//!
//! // Create a page
//! let mut page = Page::a4();
//!
//! // Add text
//! page.text()
//!     .set_font(Font::Helvetica, 24.0)
//!     .at(50.0, 700.0)
//!     .write("Hello, PDF!")?;
//!
//! // Add graphics
//! page.graphics()
//!     .set_fill_color(Color::rgb(0.0, 0.5, 1.0))
//!     .circle(300.0, 400.0, 50.0)
//!     .fill();
//!
//! // Save the document
//! doc.add_page(page);
//! doc.save("output.pdf")?;
//! # Ok(())
//! # }
//! ```
//!
//! ### Parsing PDFs
//!
//! ```rust,no_run
//! use oxidize_pdf::parser::{PdfDocument, PdfReader};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Open and parse a PDF
//! let reader = PdfReader::open("document.pdf")?;
//! let document = PdfDocument::new(reader);
//!
//! // Get document information
//! println!("Pages: {}", document.page_count()?);
//! println!("Version: {}", document.version()?);
//!
//! // Process pages
//! for i in 0..document.page_count()? {
//!     let page = document.get_page(i)?;
//!     println!("Page {} size: {}x{} points", i+1, page.width(), page.height());
//! }
//!
//! // Extract text
//! let text_pages = document.extract_text()?;
//! for (i, page_text) in text_pages.iter().enumerate() {
//!     println!("Page {} text: {}", i+1, page_text.text);
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ## Modules
//!
//! ### Generation Modules
//! - [`document`] - PDF document creation and management
//! - [`page`] - Page creation and layout
//! - [`graphics`] - Vector graphics and images
//! - [`text`] - Text rendering and flow
//! - [`writer`] - Low-level PDF writing
//!
//! ### Parsing Modules
//! - [`parser`] - Complete PDF parsing and reading
//!   - [`parser::PdfDocument`] - High-level document interface
//!   - [`parser::ParsedPage`] - Page representation with resources
//!   - [`parser::ContentParser`] - Content stream parsing
//!   - [`parser::PdfObject`] - Low-level PDF objects
//!
//! ### Manipulation Modules
//! - [`operations`] - PDF manipulation (split, merge, rotate, extract images)
//! - [`operations::page_analysis`] - Page content analysis and scanned page detection
//! - [`text::extraction`] - Text extraction with positioning
//!
//! ### OCR Modules (v0.1.3+)
//! - [`text::ocr`] - OCR trait system and types
//! - [`text::tesseract_provider`] - Tesseract OCR provider (requires `ocr-tesseract` feature)
//! - [`text::ocr`] - OCR integration for scanned documents
//!
//! ## Examples
//!
//! ### Content Stream Processing
//!
//! ```rust,no_run
//! use oxidize_pdf::parser::{PdfDocument, PdfReader};
//! use oxidize_pdf::parser::content::{ContentParser, ContentOperation};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let reader = PdfReader::open("document.pdf")?;
//! let document = PdfDocument::new(reader);
//! let page = document.get_page(0)?;
//!
//! // Get and parse content streams
//! let streams = page.content_streams_with_document(&document)?;
//! for stream in streams {
//!     let operations = ContentParser::parse(&stream)?;
//!     
//!     for op in operations {
//!         match op {
//!             ContentOperation::ShowText(text) => {
//!                 println!("Text: {:?}", String::from_utf8_lossy(&text));
//!             }
//!             ContentOperation::SetFont(name, size) => {
//!                 println!("Font: {} at {} pt", name, size);
//!             }
//!             ContentOperation::MoveTo(x, y) => {
//!                 println!("Move to ({}, {})", x, y);
//!             }
//!             _ => {} // Handle other operations
//!         }
//!     }
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ### Resource Access
//!
//! ```rust,no_run
//! use oxidize_pdf::parser::{PdfDocument, PdfReader};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let reader = PdfReader::open("document.pdf")?;
//! let document = PdfDocument::new(reader);
//! let page = document.get_page(0)?;
//!
//! // Access page resources
//! if let Some(resources) = page.get_resources() {
//!     // Check fonts
//!     if let Some(fonts) = resources.get("Font").and_then(|f| f.as_dict()) {
//!         for (name, _) in &fonts.0 {
//!             println!("Font resource: {}", name.as_str());
//!         }
//!     }
//!     
//!     // Check images/XObjects
//!     if let Some(xobjects) = resources.get("XObject").and_then(|x| x.as_dict()) {
//!         for (name, _) in &xobjects.0 {
//!             println!("XObject resource: {}", name.as_str());
//!         }
//!     }
//! }
//! # Ok(())
//! # }
//! ```

pub mod document;
pub mod error;
pub mod graphics;
pub mod objects;
pub mod operations;
pub mod page;
pub mod parser;
pub mod text;
pub mod writer;

#[cfg(feature = "semantic")]
pub mod semantic;

// Re-export generation types
pub use document::{Document, DocumentMetadata};
pub use error::{OxidizePdfError, PdfError, Result};
pub use graphics::{Color, GraphicsContext, Image, ImageColorSpace, ImageFormat};
pub use page::{Margins, Page};
pub use text::{
    measure_text, split_into_words, Font, FontFamily, FragmentType, ImagePreprocessing,
    MockOcrProvider, OcrEngine, OcrError, OcrOptions, OcrProcessingResult, OcrProvider, OcrResult,
    OcrTextFragment, TextAlign, TextContext, TextFlowContext,
};

// Re-export parsing types
pub use parser::{
    ContentOperation, ContentParser, DocumentMetadata as ParsedDocumentMetadata, ParsedPage,
    PdfArray, PdfDictionary, PdfDocument, PdfName, PdfObject, PdfReader, PdfStream, PdfString,
};

// Re-export operations
pub use operations::{merge_pdfs, rotate_pdf_pages, split_pdf};

/// Current version of oxidize-pdf
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// Scanned page analysis and OCR example
///
/// ```rust,no_run
/// use oxidize_pdf::operations::page_analysis::{PageContentAnalyzer, PageType};
/// use oxidize_pdf::text::{MockOcrProvider, OcrOptions};
/// use oxidize_pdf::parser::PdfReader;
///
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let document = PdfReader::open_document("scanned.pdf")?;
/// let analyzer = PageContentAnalyzer::new(document);
///
/// // Analyze pages for scanned content
/// let analyses = analyzer.analyze_document()?;
/// for analysis in analyses {
///     match analysis.page_type {
///         PageType::Scanned => {
///             println!("Page {} is scanned - applying OCR", analysis.page_number);
///             
///             // Process with OCR
///             let ocr_provider = MockOcrProvider::new();
///             let ocr_result = analyzer.extract_text_from_scanned_page(
///                 analysis.page_number,
///                 &ocr_provider
///             )?;
///             
///             println!("OCR extracted: {}", ocr_result.text);
///             println!("Confidence: {:.1}%", ocr_result.confidence * 100.0);
///         }
///         PageType::Text => println!("Page {} has vector text", analysis.page_number),
///         PageType::Mixed => println!("Page {} has mixed content", analysis.page_number),
///     }
/// }
/// # Ok(())
/// # }
/// ```
/// Supported PDF versions
pub mod pdf_version {
    /// PDF 1.0 - 1.7 are fully supported
    pub const SUPPORTED_VERSIONS: &[&str] =
        &["1.0", "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7"];
    /// PDF 2.0 support is planned
    pub const PLANNED_VERSIONS: &[&str] = &["2.0"];
}

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

    #[test]
    fn test_create_empty_document() {
        let doc = Document::new();
        assert_eq!(doc.pages.len(), 0);
    }

    #[test]
    fn test_create_page() {
        let page = Page::new(595.0, 842.0);
        assert_eq!(page.width(), 595.0);
        assert_eq!(page.height(), 842.0);
    }

    #[test]
    fn test_version_info() {
        assert!(!VERSION.is_empty());
        assert!(pdf_version::SUPPORTED_VERSIONS.contains(&"1.7"));
    }

    #[test]
    fn test_pdf_version_constants() {
        // Test that all expected PDF versions are supported
        let expected_versions = ["1.0", "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7"];
        
        for version in expected_versions {
            assert!(pdf_version::SUPPORTED_VERSIONS.contains(&version),
                   "Expected PDF version {} to be supported", version);
        }
        
        // Test that we have exactly 8 supported versions
        assert_eq!(pdf_version::SUPPORTED_VERSIONS.len(), 8);
        
        // Test planned versions
        assert!(pdf_version::PLANNED_VERSIONS.contains(&"2.0"));
        assert_eq!(pdf_version::PLANNED_VERSIONS.len(), 1);
    }

    #[test]
    fn test_document_with_metadata() {
        let mut doc = Document::new();
        doc.set_title("Test Document");
        doc.set_author("Test Author");
        doc.set_subject("Test Subject");
        
        // Verify metadata is set (checking internal state)
        assert_eq!(doc.pages.len(), 0);
        // Note: We can't directly test metadata without exposing getters
        // This test ensures the methods don't panic
    }

    #[test]
    fn test_page_creation_variants() {
        // Test different page creation methods
        let page_a4 = Page::a4();
        let page_letter = Page::letter();
        let page_custom = Page::new(400.0, 600.0);
        
        // A4 dimensions: 595.276 x 841.89 points (approximation)
        assert!((page_a4.width() - 595.0).abs() < 10.0);
        assert!((page_a4.height() - 842.0).abs() < 10.0);
        
        // Letter dimensions: 612 x 792 points
        assert_eq!(page_letter.width(), 612.0);
        assert_eq!(page_letter.height(), 792.0);
        
        // Custom dimensions
        assert_eq!(page_custom.width(), 400.0);
        assert_eq!(page_custom.height(), 600.0);
    }

    #[test]
    fn test_color_creation() {
        let red = Color::rgb(1.0, 0.0, 0.0);
        let green = Color::rgb(0.0, 1.0, 0.0);
        let blue = Color::rgb(0.0, 0.0, 1.0);
        let black = Color::rgb(0.0, 0.0, 0.0);
        let white = Color::rgb(1.0, 1.0, 1.0);
        
        // Test color creation doesn't panic
        let _colors = [red, green, blue, black, white];
        
        // Test CMYK color (if available)
        let cyan = Color::cmyk(1.0, 0.0, 0.0, 0.0);
        let _cmyk_test = cyan;
    }

    #[test]
    fn test_font_types() {
        let helvetica = Font::Helvetica;
        let times = Font::TimesRoman;
        let courier = Font::Courier;
        
        // Test font creation doesn't panic
        let _fonts = [helvetica, times, courier];
        
        // Test font family
        let helvetica_family = FontFamily::Helvetica;
        let times_family = FontFamily::Times;
        let courier_family = FontFamily::Courier;
        
        let _families = [helvetica_family, times_family, courier_family];
    }

    #[test]
    fn test_error_types() {
        // Test that error types can be created
        let pdf_error = PdfError::InvalidStructure("test error".to_string());
        let _error_test = pdf_error;
        
        // Test result type
        let ok_result: Result<i32> = Ok(42);
        let err_result: Result<i32> = Err(PdfError::InvalidStructure("test error".to_string()));
        
        assert!(ok_result.is_ok());
        assert!(err_result.is_err());
    }

    #[test]
    fn test_module_exports() {
        // Test that all major types are properly exported
        let _doc = Document::new();
        let _page = Page::new(100.0, 100.0);
        let _color = Color::rgb(0.5, 0.5, 0.5);
        let _font = Font::Helvetica;
        
        // Test parsing types
        let _array = PdfArray::new();
        let _dict = PdfDictionary::new();
        let _name = PdfName::new("Test".to_string());
        let _string = PdfString::new(b"Test".to_vec());
        
        // Test operation types
        let _margins = Margins { top: 10.0, right: 10.0, bottom: 10.0, left: 10.0 };
        let _align = TextAlign::Left;
    }

    #[test]
    fn test_ocr_types() {
        // Test OCR-related types
        let _mock_ocr = MockOcrProvider::new();
        let _ocr_options = OcrOptions::default();
        let _ocr_engine = OcrEngine::Tesseract;
        
        // Test fragment types
        let _fragment_type = FragmentType::Word;
        let _image_preprocessing = ImagePreprocessing::default();
    }

    #[test]
    fn test_text_utilities() {
        // Test text utility functions
        let text = "Hello world test";
        let words = split_into_words(text);
        assert!(words.len() > 0);
        assert!(words.contains(&"Hello"));
        assert!(words.contains(&"world"));
        
        // Test text measurement (with mock font)
        let font = Font::Helvetica;
        let size = 12.0;
        let width = measure_text(text, font, size);
        assert!(width > 0.0);
    }

    #[test]
    fn test_image_types() {
        // Test image-related types
        let _format = ImageFormat::Jpeg;
        let _color_space = ImageColorSpace::DeviceRGB;
        
        // Test that image creation doesn't panic
        let image_data = vec![0u8; 100];
        let _image = Image::from_jpeg_data(image_data);
    }

    #[test]
    fn test_version_string_format() {
        // Test that version string follows semantic versioning
        let version_parts: Vec<&str> = VERSION.split('.').collect();
        assert!(version_parts.len() >= 2, "Version should have at least major.minor format");
        
        // Test that major and minor are numeric
        assert!(version_parts[0].parse::<u32>().is_ok(), "Major version should be numeric");
        assert!(version_parts[1].parse::<u32>().is_ok(), "Minor version should be numeric");
        
        // Test that version is not empty
        assert!(!VERSION.is_empty());
        assert!(VERSION.len() > 0);
    }
}