djoc 0.1.0

The Djot document compiler
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

//! HTML output functionality for djoc.
//!
//! This module only contains the error types for HTML output and provides the
//! [`Builder::write_html`] method.

use std::{
    error::Error,
    fmt::{self, Display, Formatter},
    io::{self, Write},
};

use jotdown::{html, Container, Event, Parser, Render};
use rayon::prelude::*;

use super::Builder;
use crate::Document;

const MAIN_CSS: &[u8] = include_bytes!("./main.css");
const KATEX_CSS: &[u8] = include_bytes!("./katex.css");

impl Builder {
    /// Build the document as HTML and write it to the given writer.
    ///
    /// # Examples
    ///
    /// ```
    /// use djoc::{Builder, Document};
    ///
    /// let mut builder = Builder::default();
    /// let document = Document::from("Hello, world!".to_string());
    /// builder
    ///     .write_html(&document, &mut std::io::stdout())
    ///     .unwrap();
    /// ```
    pub fn write_html<W: Write + Send>(
        &self,
        document: &Document,
        mut w: W,
    ) -> Result<(), HtmlError> {
        let mut inner = || -> Result<(), HtmlError> {
            writeln!(w, "<!DOCTYPE html>\n<html lang=\"en\">\n<head>")?;
            writeln!(w, "<style>")?;
            w.write_all(MAIN_CSS)?;
            writeln!(w, "</style>")?;
            w.write_all(KATEX_CSS)?;
            writeln!(w, "<body>")?;

            document
                .texts
                .par_iter()
                .try_fold_with(Vec::new(), |mut buf, text| {
                    let mut opts = katex::Opts::default();
                    let mut in_math = false;
                    let events = Parser::new(text).map(|event| match event {
                        Event::Start(Container::Math { display }, attrs) => {
                            opts.set_display_mode(display);
                            in_math = true;
                            Event::Start(Container::RawBlock { format: "html" }, attrs)
                        }
                        Event::End(Container::Math { .. }) => {
                            in_math = false;
                            Event::End(Container::RawBlock { format: "html" })
                        }
                        Event::Str(s) if in_math => {
                            Event::Str(katex::render_with_opts(&s, &opts).unwrap().into())
                        }
                        _ => event,
                    });

                    html::Renderer::default().write(events, &mut buf)?;
                    Ok(buf)
                })
                .collect::<Result<Vec<Vec<u8>>, HtmlError>>()?
                .into_iter()
                .try_for_each(|s| w.write_all(&s))?;

            writeln!(w, "</body>\n</html>")?;
            Ok(())
        };

        inner().map_err(|e| e.document_name(&document.title))
    }
}

/// An error that can occur when rendering HTML.
#[non_exhaustive]
#[derive(Debug)]
pub struct HtmlError {
    /// The title of the document that caused this error.
    pub document_name: Option<String>,
    /// The kind of error that occurred.
    pub kind: HtmlErrorKind,
}

impl HtmlError {
    /// Set the name of the document that caused this error.
    #[must_use]
    pub fn document_name(self, document_name: &str) -> Self {
        Self {
            document_name: Some(document_name.to_string()),
            ..self
        }
    }
}

impl From<io::Error> for HtmlError {
    fn from(e: io::Error) -> Self {
        Self {
            document_name: None,
            kind: HtmlErrorKind::Io(e),
        }
    }
}

impl From<katex::Error> for HtmlError {
    fn from(e: katex::Error) -> Self {
        Self {
            document_name: None,
            kind: HtmlErrorKind::Katex(e),
        }
    }
}

impl Display for HtmlError {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        if let Some(name) = &self.document_name {
            write!(f, "{name} - ")?;
        }
        match &self.kind {
            HtmlErrorKind::Io(e) => write!(f, "io error: {e}"),
            HtmlErrorKind::Katex(_) => write!(f, "failed to render math with katex"),
        }
    }
}

impl Error for HtmlError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match &self.kind {
            HtmlErrorKind::Io(source) => Some(source),
            HtmlErrorKind::Katex(source) => Some(source),
        }
    }
}

/// The kind of error that can occur when rendering HTML.
#[non_exhaustive]
#[derive(Debug)]
pub enum HtmlErrorKind {
    /// An error that occurred while writing to the writer.
    Io(io::Error),
    /// An error that occurred while rendering math with [`katex`].
    Katex(katex::Error),
}