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

/*
 * includes/includer/mod.rs
 *
 * ftml - Library to parse Wikidot text
 * Copyright (C) 2019-2024 Wikijump Team
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */

//! This module contains tools which format pages after they have been referenced in an include
//! block.

mod debug;
mod null;

mod prelude {
    pub use crate::data::PageRef;
    pub use crate::includes::{FetchedPage, IncludeRef, Includer};
    pub use std::borrow::Cow;
}

use crate::includes::{IncludeRef, PageRef};
use std::borrow::Cow;

pub use self::debug::DebugIncluder;
pub use self::null::NullIncluder;

/// A type used by [`Includer`] which represents a page that is ready to be included.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(rename_all = "kebab-case")]
pub struct FetchedPage<'t> {
    pub page_ref: PageRef<'t>,
    pub content: Option<Cow<'t, str>>,
}

/// A trait that handles the formatting of included pages.
pub trait Includer<'t> {
    type Error;

    /// Returns a list of the pages included.
    fn include_pages(
        &mut self,
        includes: &[IncludeRef<'t>],
    ) -> Result<Vec<FetchedPage<'t>>, Self::Error>;

    /// Handles the inclusion of a page not found.
    fn no_such_include(
        &mut self,
        page_ref: &PageRef<'t>,
    ) -> Result<Cow<'t, str>, Self::Error>;
}