ftml/includes/
parse.rs

1/*
2 * includes/parse.rs
3 *
4 * ftml - Library to parse Wikidot text
5 * Copyright (C) 2019-2025 Wikijump Team
6 *
7 * This program is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU Affero General Public License as published by
9 * the Free Software Foundation, either version 3 of the License, or
10 * (at your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU Affero General Public License for more details.
16 *
17 * You should have received a copy of the GNU Affero General Public License
18 * along with this program. If not, see <http://www.gnu.org/licenses/>.
19 */
20
21//! This module provides functions to parse strings into [`IncludeRef`]s
22
23mod parser {
24    // Since pest generates some code that clippy doesn't like
25    #![allow(clippy::empty_docs)]
26
27    #[derive(Parser, Debug)]
28    #[grammar = "includes/grammar.pest"]
29    pub struct IncludeParser;
30}
31
32use self::parser::*;
33use super::IncludeRef;
34use crate::data::{PageRef, PageRefParseError};
35use crate::settings::WikitextSettings;
36use pest::iterators::Pairs;
37use pest::Parser;
38use std::borrow::Cow;
39use std::collections::HashMap;
40
41/// Parses a single include block in the text.
42///
43/// # Arguments
44/// The "start" argument is the index at which the include block starts.
45/// It does not necessarily relate to the index of the include within the text str.
46///
47/// # Return values
48/// Returns a tuple of an [`IncludeRef`] that represents the included text and a usize that
49/// represents the end index of the include block, such that start..end covers the full include
50/// block (before the include goes through).
51pub fn parse_include_block<'t>(
52    text: &'t str,
53    start: usize,
54    settings: &WikitextSettings,
55) -> Result<(IncludeRef<'t>, usize), IncludeParseError> {
56    let rule = if settings.use_include_compatibility {
57        Rule::include_compatibility
58    } else {
59        Rule::include_normal
60    };
61
62    match IncludeParser::parse(rule, &text[start..]) {
63        Ok(mut pairs) => {
64            // Extract inner pairs
65            // These actually make up the include block's tokens
66            let first = pairs.next().expect("No pairs returned on successful parse");
67            let span = first.as_span();
68
69            debug!("Parsed include block");
70
71            // Convert into an IncludeRef
72            let include = process_pairs(first.into_inner())?;
73
74            // Adjust offset and return
75            Ok((include, start + span.end()))
76        }
77        Err(error) => {
78            warn!("Include block was invalid: {error}");
79            Err(IncludeParseError)
80        }
81    }
82}
83
84/// Creates an [`IncludeRef`] out of pest [`Pairs`].
85fn process_pairs(mut pairs: Pairs<Rule>) -> Result<IncludeRef, IncludeParseError> {
86    let page_raw = pairs.next().ok_or(IncludeParseError)?.as_str();
87    let page_ref = PageRef::parse(page_raw)?;
88
89    trace!("Got page for include {page_ref:?}");
90    let mut arguments = HashMap::new();
91    let mut var_reference = String::new();
92
93    for pair in pairs {
94        debug_assert_eq!(pair.as_rule(), Rule::argument);
95
96        let (key, value) = {
97            let mut argument_pairs = pair.into_inner();
98
99            let key = argument_pairs
100                .next()
101                .expect("Argument pairs terminated early")
102                .as_str();
103
104            let value = argument_pairs
105                .next()
106                .expect("Argument pairs terminated early")
107                .as_str();
108
109            (key, value)
110        };
111
112        trace!("Adding argument for include (key '{key}', value '{value}')");
113
114        // In Wikidot, the first argument takes precedence.
115        //
116        // However, with nested includes, you can set a fallback
117        // by making the first argument its corresponding value.
118        //
119        // For instance, if we're in `component:test`:
120        // ```
121        // [[include component:test-backend
122        //     width={$width} |
123        //     width=300px
124        // ]]
125        // ```
126
127        var_reference.clear();
128        str_write!(var_reference, "{{${key}}}");
129
130        if !arguments.contains_key(key) && value != var_reference {
131            let key = Cow::Borrowed(key);
132            let value = Cow::Borrowed(value);
133
134            arguments.insert(key, value);
135        }
136    }
137
138    Ok(IncludeRef::new(page_ref, arguments))
139}
140
141#[derive(Debug, PartialEq, Eq)]
142pub struct IncludeParseError;
143
144impl From<PageRefParseError> for IncludeParseError {
145    #[inline]
146    fn from(_: PageRefParseError) -> Self {
147        IncludeParseError
148    }
149}
ftml/includes/parse.rs

ftml/includes/
parse.rs
