pptx-to-md 0.5.1

Parse Microsoft PowerPoint files (.pptx) and OpenDocument Presentations (.odp) into Markdown (.md)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179

use std::path::PathBuf;

/// Determines how images are handled during content export.
///
/// # Members
///
/// | Member                | Description                                                                                                                       |
/// |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------|            
/// | `InMarkdown`          | Images are embedded directly in the Markdown output using standard syntax as `base64` data (`![]()`)                              |            
/// | `Manually`            | Image handling is delegated to the user, requiring manual copying or referencing (as `base64` encoded string)                     |            
/// | `Save`                | Images will be saved in a provided output directory and integrated using `<a>` tag syntax (`<a href="file:///<abs_path>"></a>`)   |            
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ImageHandlingMode {
    InMarkdown,
    Manually,
    Save,
}

/// Configuration options for the PPTX parser.
///
/// Use [`ParserConfig::builder()`] to create a configuration instance.
/// This allows you to customize only the desired fields while falling back to sensible defaults for the rest.
///
/// # Configuration Options
///
/// | Parameter                 | Type                  | Default       | Description                                                                                               |
/// |---------------------------|-----------------------|---------------|-----------------------------------------------------------------------------------------------------------|
/// | `extract_images`          | `bool`                | `true`        | Whether images are extracted from slides or not. If false, images can not be extracted manually either    |
/// | `compress_images`         | `bool`                | `true`        | Whether images are compressed before encoding or not. Effects manually extracted images too               |
/// | `image_quality`           | `u8`                  | `80`          | Compression level (0-100);<br/> higher values retain more detail but increase file size                   |
/// | `image_handling_mode`     | `ImageHandlingMode`   | `InMarkdown`  | Determines how images are handled during content export                                                   |
/// | `image_output_path`       | `Option<PathBuf>`     | `None`        | Output directory path for `ImageHandlingMode::Save` (mandatory for the saving mode)                       |
/// | `include_slide_number_as_comment`   | `bool`                | `true`        | Weather the slide number comment is included or not (`<!-- Slide [n] -->`)                                |
/// | `include_speaker_notes`   | `bool`                | `false`       | Whether speaker notes are appended to Markdown as blockquotes                                               |
/// | `include_comments`        | `bool`                | `false`       | Whether presentation comments are appended to Markdown as blockquotes                                       |
/// | `include_presentation_metadata` | `bool`          | `true`        | Whether presentation-wide Markdown starts with a metadata comment                                            |
///
/// # Example
///
/// ```
/// use std::path::PathBuf;
/// use pptx_to_md::{ImageHandlingMode, ParserConfig};
///
/// let config = ParserConfig::builder()
///     .extract_images(true)
///     .compress_images(true)
///     .quality(75)
///     .image_handling_mode(ImageHandlingMode::Save)
///     .image_output_path(PathBuf::from("/path/to/output/dir/"))
///     .build();
/// ```
#[derive(Debug, Clone)]
pub struct ParserConfig {
    pub extract_images: bool,
    pub compress_images: bool,
    pub quality: u8,
    pub image_handling_mode: ImageHandlingMode,
    pub image_output_path: Option<PathBuf>,
    pub include_slide_number_as_comment: bool,
    pub include_speaker_notes: bool,
    pub include_comments: bool,
    pub include_presentation_metadata: bool,
}

impl Default for ParserConfig {
    fn default() -> Self {
        Self {
            extract_images: true,
            compress_images: true,
            quality: 80,
            image_handling_mode: ImageHandlingMode::InMarkdown,
            image_output_path: None,
            include_slide_number_as_comment: true,
            include_speaker_notes: false,
            include_comments: false,
            include_presentation_metadata: true,
        }
    }
}

impl ParserConfig {
    pub fn builder() -> ParserConfigBuilder {
        ParserConfigBuilder::default()
    }
}

/// Builder for [`ParserConfig`].
///
/// Allows setting individual configuration fields while falling back to defaults for any unspecified values
#[derive(Debug, Default)]
pub struct ParserConfigBuilder {
    extract_images: Option<bool>,
    compress_images: Option<bool>,
    image_quality: Option<u8>,
    image_handling_mode: Option<ImageHandlingMode>,
    image_output_path: Option<PathBuf>,
    include_slide_number_as_comment: Option<bool>,
    include_speaker_notes: Option<bool>,
    include_comments: Option<bool>,
    include_presentation_metadata: Option<bool>,
}

impl ParserConfigBuilder {
    /// Sets weather images should be extracted from the slides.
    pub fn extract_images(mut self, value: bool) -> Self {
        self.extract_images = Some(value);
        self
    }

    /// Sets weather images should be compressed before encoded to base64 or not
    pub fn compress_images(mut self, value: bool) -> Self {
        self.compress_images = Some(value);
        self
    }

    /// Specifies the desired image quality where `100` is the original quality and `50` means half the quality
    /// The lower the quality, the smaller the file size of the output image will be
    pub fn quality(mut self, value: u8) -> Self {
        self.image_quality = Some(value);
        self
    }

    /// Specifies the mode for processing the image after its extracted
    pub fn image_handling_mode(mut self, value: ImageHandlingMode) -> Self {
        self.image_handling_mode = Some(value);
        self
    }

    /// Specifies the output directory for the [`ImageHandlingMode::Save`]
    pub fn image_output_path<P>(mut self, path: P) -> Self
    where
        P: Into<PathBuf>,
    {
        self.image_output_path = Some(path.into());
        self
    }

    /// Sets weather comments with the current slide number are included or not
    pub fn include_slide_number_as_comment(mut self, value: bool) -> Self {
        self.include_slide_number_as_comment = Some(value);
        self
    }

    /// Sets whether speaker notes are appended to Markdown as blockquotes.
    pub fn include_speaker_notes(mut self, value: bool) -> Self {
        self.include_speaker_notes = Some(value);
        self
    }

    /// Sets whether presentation comments are appended to Markdown as blockquotes.
    pub fn include_comments(mut self, value: bool) -> Self {
        self.include_comments = Some(value);
        self
    }

    /// Sets whether presentation-wide Markdown includes the metadata header.
    /// Metadata is parsed regardless of this setting.
    pub fn include_presentation_metadata(mut self, value: bool) -> Self {
        self.include_presentation_metadata = Some(value);
        self
    }

    /// Builds the final [`ParserConfig`] instance, applying default values for any fields that were not set.
    pub fn build(self) -> ParserConfig {
        ParserConfig {
            extract_images: self.extract_images.unwrap_or(true),
            compress_images: self.compress_images.unwrap_or(true),
            quality: self.image_quality.unwrap_or(80),
            image_handling_mode: self
                .image_handling_mode
                .unwrap_or(ImageHandlingMode::InMarkdown),
            image_output_path: self.image_output_path,
            include_slide_number_as_comment: self.include_slide_number_as_comment.unwrap_or(true),
            include_speaker_notes: self.include_speaker_notes.unwrap_or(false),
            include_comments: self.include_comments.unwrap_or(false),
            include_presentation_metadata: self.include_presentation_metadata.unwrap_or(true),
        }
    }
}