mdiu 0.1.2

Build documents with gemtext
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

//! Build documents with [Gemtext]
//!
//! `mdiu` provides a correct and flexible approach to creating small documents with Gemtext.
//!
//! Named after the [Manual Data Insertion Unit], part of Gemini's on-board computer.
//!
//! # Examples
//!
//! Create a document with a builder
//! ```
//! # fn main() -> mdiu::Result<()> {
//! use mdiu::{Document, Gemtext, ToMarkup};
//!
//! let gemtext = Document::new()
//!     .h1("my gemlog")
//!     .text("welcome")
//!     .build()?
//!     .to_markup::<Gemtext>();
//!
//! assert_eq!(gemtext, "# my gemlog\nwelcome\n");
//! # Ok(())
//! # }
//! ```
//!
//! Create a document block by block
//! ```
//! # fn main() -> mdiu::Result<()> {
//! use mdiu::{Block, Content, Gemtext, Level, Markup};
//!
//! let h1 = Block::Heading(Level::One, "my gemlog".parse()?);
//! let text = Block::Text(Content::new("welcome")?);
//! let doc = vec![h1, text];
//!
//! let gemtext = <Gemtext>::markup(&doc);
//!
//! assert_eq!(gemtext, "# my gemlog\nwelcome\n");
//! # Ok(())
//! # }
//! ```
//!
//! # Features
//!
//! Formatting to [`Gemtext`] is supported by default.
//! Additional features are available for the following formats:
//!
//! * `html`
//! * `markdown`
//!
//! A Gemtext `parsing` feature is planned but not yet implemented.
//!
//! # Alternatives
//!
//! While `mdiu` only covers Gemtext, the following crates cover the full Gemini protocol:
//!
//! * [gmi](https://crates.io/crates/gmi)
//! * [gemini](https://crates.io/crates/gemini)
//!
//! [Gemtext]: https://gemini.circumlunar.space/docs/gemtext.gmi
//! [Manual Data Insertion Unit]: https://web.archive.org/web/20220201083102/https://www.ibiblio.org/apollo/Gemini.html

mod content;
pub use content::Content;

mod document;
pub use document::Document;

mod error;
pub use error::{Error, Result};

mod link;
pub use link::Link;

mod preformatted;
pub use preformatted::Preformatted;

mod gemtext;
pub use gemtext::Gemtext;

#[cfg(feature = "html")]
mod html;
#[cfg(feature = "html")]
pub use html::Html;

#[cfg(feature = "markdown")]
mod markdown;
#[cfg(feature = "markdown")]
pub use markdown::Markdown;

/// A Gemtext element
#[derive(Clone, Debug)]
pub enum Block {
    Text(Content),
    Link(Link),
    Heading(Level, Content),
    ListItem(Content),
    Quote(Content),
    Preformatted(Preformatted),
    Empty,
}

/// Heading level of a [`Block::Heading`]
#[derive(Clone, Debug)]
pub enum Level {
    One,
    Two,
    Three,
}

/// Format an iterator of [`Block`]s
///
/// # Example
///
/// See example usage in [crate documentation](./index.html#examples).
pub trait Markup {
    // This takes an iter of Blocks so the formatter can handle adjacent Blocks,
    // for example wrapping lists with <ul> in HTML
    fn markup(blocks: &[Block]) -> String;
}

/// Create [`Markup`]-formatted strings
///
/// This trait is sealed and cannot be implemented for types outside this crate.
///
/// # Example
///
/// See example usage in [crate documentation](./index.html#examples).
pub trait ToMarkup: private::Sealed {
    fn to_markup<F>(self) -> String
    where
        F: Markup;
}

impl<T> ToMarkup for T
where
    T: std::ops::Deref<Target = [Block]>,
{
    fn to_markup<F>(self) -> String
    where
        F: Markup,
    {
        <F>::markup(&self)
    }
}

mod private {
    use super::Block;

    pub trait Sealed {}

    impl<T> Sealed for T where T: std::ops::Deref<Target = [Block]> {}
}