pdf_engine/
api.rs

1//! The ideal top-level API facade for the PDFluent SDK.
2//!
3//! This module defines the intended public surface of the PDFluent library,
4//! following the "Zero-Config First Success", "Pit of Success", and "Progressive Disclosure"
5//! design principles.
6
7use std::path::Path;
8
9pub use crate::api_error::Error;
10
11/// Input source for a PDF document.
12pub enum PdfSource<'a> {
13    Path(&'a Path),
14    Bytes(&'a [u8]),
15}
16
17impl<'a> From<&'a str> for PdfSource<'a> {
18    fn from(s: &'a str) -> Self {
19        PdfSource::Path(Path::new(s))
20    }
21}
22
23impl<'a> From<&'a Path> for PdfSource<'a> {
24    fn from(p: &'a Path) -> Self {
25        PdfSource::Path(p)
26    }
27}
28
29impl<'a> From<&'a [u8]> for PdfSource<'a> {
30    fn from(b: &'a [u8]) -> Self {
31        PdfSource::Bytes(b)
32    }
33}
34
35/// Options for reading a PDF.
36#[derive(Default, Debug, Clone)]
37pub struct ReadOptions {
38    pub(crate) password: Option<String>,
39    pub(crate) repair: bool,
40}
41
42impl ReadOptions {
43    pub fn new() -> Self {
44        Self::default()
45    }
46
47    pub fn password(&mut self, pw: impl Into<String>) -> &mut Self {
48        self.password = Some(pw.into());
49        self
50    }
51
52    pub fn repair(&mut self, repair: bool) -> &mut Self {
53        self.repair = repair;
54        self
55    }
56}
57
58/// Options for saving a PDF.
59#[derive(Default, Debug, Clone)]
60pub struct SaveOptions {
61    pub(crate) format: Option<PdfFormat>,
62    pub(crate) linearize: bool,
63}
64
65impl SaveOptions {
66    pub fn new() -> Self {
67        Self::default()
68    }
69
70    pub fn format(&mut self, format: PdfFormat) -> &mut Self {
71        self.format = Some(format);
72        self
73    }
74
75    pub fn linearize(&mut self, linearize: bool) -> &mut Self {
76        self.linearize = linearize;
77        self
78    }
79}
80
81#[derive(Debug, Clone, Copy, PartialEq, Eq)]
82pub enum PdfFormat {
83    Pdf1_4,
84    Pdf1_7,
85    Pdf2_0,
86    PdfA1b,
87    PdfA2b,
88    PdfA3b,
89}
90
91#[derive(Default, Debug, Clone)]
92pub struct WatermarkOptions {
93    pub opacity: f64,
94    pub rotation: f64,
95}
96
97#[derive(Debug, Clone, Copy, PartialEq, Eq)]
98pub enum ImageFormat {
99    Png,
100    Jpeg,
101}
102
103/// A structured block of text from a PDF.
104pub struct TextBlock {
105    pub text: String,
106    pub bbox: [f64; 4],
107}
108
109/// Document metadata.
110pub struct Metadata {
111    pub title: Option<String>,
112    pub author: Option<String>,
113    pub creation_date: Option<String>,
114}
115
116/// An interactive form field.
117pub struct FormField {
118    pub name: String,
119    pub value: String,
120    pub field_type: String,
121}
122
123/// A digital signature within the document.
124pub struct Signature {
125    pub signer_name: String,
126    pub date: String,
127    pub is_valid: bool,
128}
129
130/// The main entry point for a PDF Document.
131pub struct Document {
132    // Internal handle to actual implementation would go here
133}
134
135impl Document {
136    // === TEKST ===
137
138    /// Extracts plain text from all pages.
139    pub fn text(&self) -> String {
140        unimplemented!("facade")
141    }
142
143    /// Accesses a specific page for text extraction and other operations (1-based index).
144    pub fn page(&self, page_number: usize) -> Page {
145        let _ = page_number;
146        unimplemented!("facade")
147    }
148
149    /// Extracts structured text blocks with coordinates.
150    pub fn structured_text(&self) -> Vec<TextBlock> {
151        unimplemented!("facade")
152    }
153
154    // === METADATA ===
155
156    /// Returns the total number of pages in the document.
157    pub fn page_count(&self) -> usize {
158        unimplemented!("facade")
159    }
160
161    /// Returns the document's metadata.
162    pub fn metadata(&self) -> Metadata {
163        unimplemented!("facade")
164    }
165
166    // === OPSLAAN ===
167
168    /// Saves the document to a file.
169    pub fn save(&self, path: impl AsRef<Path>) -> Result<(), Error> {
170        let _ = path;
171        unimplemented!("facade")
172    }
173
174    /// Saves the document with specific options.
175    pub fn save_with<F>(&self, path: impl AsRef<Path>, build_opts: F) -> Result<(), Error>
176    where
177        F: FnOnce(&mut SaveOptions) -> &mut SaveOptions,
178    {
179        let _ = path;
180        let _ = build_opts;
181        unimplemented!("facade")
182    }
183
184    // === FORMULIEREN ===
185
186    /// Gets all form fields in the document.
187    pub fn form_fields(&self) -> Vec<FormField> {
188        unimplemented!("facade")
189    }
190
191    /// Fills form fields matching the provided name-value pairs.
192    pub fn fill_form(&self, fields: &[(&str, &str)]) -> Result<(), Error> {
193        let _ = fields;
194        unimplemented!("facade")
195    }
196
197    /// Flattens all forms, converting them to static content.
198    pub fn flatten_forms(&self) -> Result<(), Error> {
199        unimplemented!("facade")
200    }
201
202    // === HANDTEKENINGEN ===
203
204    /// Signs the document using the provided certificate and private key.
205    pub fn sign(&self, certificate: &[u8], private_key: &[u8]) -> Result<(), Error> {
206        let _ = certificate;
207        let _ = private_key;
208        unimplemented!("facade")
209    }
210
211    /// Retrieves all signatures from the document.
212    pub fn signatures(&self) -> Vec<Signature> {
213        unimplemented!("facade")
214    }
215
216    /// Verifies the cryptographic validity of all signatures.
217    pub fn verify_signatures(&self) -> Result<bool, Error> {
218        unimplemented!("facade")
219    }
220
221    // === REDACTIE ===
222
223    /// Redacts all occurrences of the specified text.
224    pub fn redact(&self, text: &str) -> Result<(), Error> {
225        let _ = text;
226        unimplemented!("facade")
227    }
228
229    /// Redacts a specific rectangular region on the specified page.
230    pub fn redact_region(&self, page: usize, rect: [f64; 4]) -> Result<(), Error> {
231        let _ = page;
232        let _ = rect;
233        unimplemented!("facade")
234    }
235
236    // === CONVERSIE ===
237
238    /// Converts the document to a DOCX file.
239    pub fn to_docx(&self, path: impl AsRef<Path>) -> Result<(), Error> {
240        let _ = path;
241        unimplemented!("facade")
242    }
243
244    /// Renders the document's pages to images based on a filename pattern.
245    pub fn to_images(&self, pattern: &str, format: ImageFormat) -> Result<(), Error> {
246        let _ = pattern;
247        let _ = format;
248        unimplemented!("facade")
249    }
250
251    /// Checks if the document is PDF/A compliant.
252    pub fn is_pdfa_compliant(&self) -> Result<bool, Error> {
253        unimplemented!("facade")
254    }
255
256    // === MANIPULATIE ===
257
258    /// Merges another document into this one.
259    pub fn merge(&self, other_doc: &Document) -> Result<(), Error> {
260        let _ = other_doc;
261        unimplemented!("facade")
262    }
263
264    /// Splits the document into individual 1-page documents.
265    pub fn split_pages(&self) -> Result<Vec<Document>, Error> {
266        unimplemented!("facade")
267    }
268
269    /// Rotates a specific page by the given angle (in degrees).
270    pub fn rotate_page(&self, page: usize, angle: i32) -> Result<(), Error> {
271        let _ = page;
272        let _ = angle;
273        unimplemented!("facade")
274    }
275
276    /// Adds a watermark to all pages of the document.
277    pub fn add_watermark(&self, text: &str, options: WatermarkOptions) -> Result<(), Error> {
278        let _ = text;
279        let _ = options;
280        unimplemented!("facade")
281    }
282}
283
284/// Represents a single page within a Document.
285pub struct Page {
286    // Internal handle to the specific page
287}
288
289impl Page {
290    /// Extracts plain text from this page only.
291    pub fn text(&self) -> String {
292        unimplemented!("facade")
293    }
294}
295
296// === LEZEN (Top-level functions) ===
297
298/// Reads a PDF document from a file path or bytes, using default options.
299pub fn read<'a, S: Into<PdfSource<'a>>>(input: S) -> Result<Document, Error> {
300    let _ = input;
301    unimplemented!("facade")
302}
303
304/// Reads a PDF document with custom options (e.g., providing a password).
305pub fn read_with<'a, S, F>(input: S, build_opts: F) -> Result<Document, Error>
306where
307    S: Into<PdfSource<'a>>,
308    F: FnOnce(&mut ReadOptions) -> &mut ReadOptions,
309{
310    let _ = input;
311    let _ = build_opts;
312    unimplemented!("facade")
313}
pdf_engine/api.rs

pdf_engine/
api.rs
