Skip to main content

mariadb_cli/exec/
script_split.rs

1//! Cutting a file of statements into the statements it carries.
2//!
3//! # The cut is made over the blanked text, never over the raw one
4//!
5//! A separator inside a text literal, a quoted name or a comment is not a
6//! separator. [`crate::sql::strip()`] replaces every such region with as many
7//! spaces as it had bytes, so the blanked text keeps the offsets of the
8//! original: the search runs over the blanked text, the cut is applied to the
9//! original, and every byte the caller wrote survives.
10//!
11//! # Why the separator can be redefined
12//!
13//! A routine body carries separators of its own. Without a way to redefine the
14//! separator, such a file would be cut in the middle of the body and each
15//! fragment sent as a statement of its own. The redefinition is a directive of
16//! the file, is never sent to the server, and applies only inside the file it
17//! appears in. It never relaxes the rule that one call carries one statement.
18//!
19//! Running the statements this module produces is [`super::script`]. Cutting a
20//! file and running it are different jobs: the cut is pure and provable without
21//! a server, and everything here is tested that way.
22
23use crate::error::{Failure, Result};
24use crate::sql::strip::strip;
25
26/// The directive that redefines the separator inside a file.
27const DIRECTIVE: &str = "delimiter";
28
29/// One statement taken out of a file.
30#[derive(Debug, Clone, PartialEq, Eq)]
31pub struct Piece {
32    /// Its position in the file, counted from one.
33    pub index: usize,
34    /// The line the statement starts on, counted from one.
35    pub line: usize,
36    /// The statement itself, exactly as the caller wrote it.
37    pub sql: String,
38}
39
40/// Refuses a separator that could never separate anything.
41///
42/// # Errors
43///
44/// Returns a usage failure for an empty separator, before any file is read.
45pub fn validate_delimiter(delimiter: &str) -> Result<()> {
46    if delimiter.trim().is_empty() {
47        return Err(Failure::usage(
48            "usage.empty_delimiter",
49            "the statement separator is empty, so it could never separate anything",
50        )
51        .with_hint("give a separator such as ; or $$"));
52    }
53    Ok(())
54}
55
56/// Cuts a file into the statements it carries, one at a time.
57///
58/// The statements are produced as they are asked for, so what a run of a long
59/// file costs is its longest statement and never the whole file cut up. Every
60/// refusal the file can earn is still decided here, before the first statement
61/// is handed out: a caller that gets a walk has a file that will not be refused
62/// halfway through, once part of it has already reached the server.
63///
64/// # Errors
65///
66/// Returns a usage failure for an empty separator, and a validation failure
67/// when a region of the file is left open or when a redefined separator is
68/// never restored.
69pub fn split<'a>(text: &'a str, delimiter: &str) -> Result<Statements<'a>> {
70    validate_delimiter(delimiter)?;
71    let blanked = strip(text);
72    blanked.refuse_if_unterminated()?;
73
74    let mut cut = Cut::new(text, blanked.text().to_owned(), delimiter);
75    // The refusal a redefined separator earns belongs to the file as a whole,
76    // so it is decided by a walk that keeps no statement rather than by the
77    // walk the caller consumes. Deciding it lazily would let the statements
78    // before the offending line reach the server and only then refuse the file.
79    while cut.next_piece().is_some() {}
80    if let Some(line) = cut.redefined_at {
81        return Err(Failure::validation(
82            "script.delimiter_not_restored",
83            format!("the separator was redefined on line {line} and never restored"),
84        )
85        .with_detail("detail", format!("L{line}"))
86        .with_hint("add a line restoring the separator before the file ends"));
87    }
88    cut.rewind();
89    Ok(Statements { cut })
90}
91
92/// The statements of one file, produced one at a time.
93///
94/// Holding this holds the file's text and its blanked twin, both of which the
95/// cut reads without copying. What it never holds is the statements: each one
96/// is built when it is asked for and dropped when the caller is done with it.
97#[derive(Debug)]
98pub struct Statements<'a> {
99    cut: Cut<'a>,
100}
101
102impl Iterator for Statements<'_> {
103    type Item = Piece;
104
105    fn next(&mut self) -> Option<Piece> {
106        self.cut.next_piece()
107    }
108}
109
110/// The walk over one file, carrying where it is and nothing it has passed.
111#[derive(Debug)]
112struct Cut<'a> {
113    original: &'a str,
114    masked: String,
115    initial: String,
116    active: String,
117    /// Where the directive last changed the separator, when it did.
118    redefined_at: Option<usize>,
119    /// Where the statement being cut begins.
120    start: usize,
121    /// Where the line being read begins.
122    offset: usize,
123    /// Where the search for a separator resumes, once a line is being read.
124    cursor: Option<usize>,
125    /// Where the line being read ends.
126    line_end: usize,
127    /// How many statements have been handed out, which is the next index.
128    handed_out: usize,
129    /// Whether the tail has been reached.
130    spent: bool,
131    /// How many line breaks lie before [`Self::counted_upto`].
132    breaks_before: usize,
133    /// How far the count of line breaks has been carried.
134    counted_upto: usize,
135}
136
137impl<'a> Cut<'a> {
138    fn new(original: &'a str, masked: String, delimiter: &str) -> Self {
139        Self {
140            original,
141            masked,
142            initial: delimiter.to_owned(),
143            active: delimiter.to_owned(),
144            redefined_at: None,
145            start: 0,
146            offset: 0,
147            cursor: None,
148            line_end: 0,
149            handed_out: 0,
150            spent: false,
151            breaks_before: 0,
152            counted_upto: 0,
153        }
154    }
155
156    /// Puts the walk back at the start of the file.
157    fn rewind(&mut self) {
158        self.active.clone_from(&self.initial);
159        self.redefined_at = None;
160        self.start = 0;
161        self.offset = 0;
162        self.cursor = None;
163        self.line_end = 0;
164        self.handed_out = 0;
165        self.spent = false;
166        self.breaks_before = 0;
167        self.counted_upto = 0;
168    }
169
170    /// The next statement, or nothing once the file is spent.
171    ///
172    /// The walk is line by line, because the directive is line-shaped, and it
173    /// resumes inside a line, because a line may end more than one statement.
174    fn next_piece(&mut self) -> Option<Piece> {
175        loop {
176            if self.spent {
177                return None;
178            }
179            if self.offset >= self.masked.len() {
180                // A last statement written without a separator is not lost.
181                self.spent = true;
182                return self.take(self.start..self.original.len());
183            }
184            let Some(cursor) = self.cursor else {
185                self.line_end = self.masked[self.offset..]
186                    .find('\n')
187                    .map_or(self.masked.len(), |found| self.offset + found);
188                if self.take_directive(self.offset, self.line_end) {
189                    self.offset = self.line_end + 1;
190                } else {
191                    self.cursor = Some(self.offset);
192                }
193                continue;
194            };
195            let Some(found) = self.masked[cursor..self.line_end].find(self.active.as_str()) else {
196                self.cursor = None;
197                self.offset = self.line_end + 1;
198                continue;
199            };
200            let at = cursor + found;
201            let region = self.start..at;
202            self.cursor = Some(at + self.active.len());
203            self.start = at + self.active.len();
204            if let Some(piece) = self.take(region) {
205                return Some(piece);
206            }
207        }
208    }
209
210    /// Consumes a separator directive, when this line is one.
211    ///
212    /// The directive counts only where a statement could begin, so the same
213    /// word inside a statement is left alone.
214    fn take_directive(&mut self, from: usize, to: usize) -> bool {
215        if !self.masked[self.start..from].trim().is_empty() {
216            return false;
217        }
218        let line = self.masked[from..to].trim_start();
219        let leading = to - from - line.len();
220        if line.len() < DIRECTIVE.len()
221            || !line[..DIRECTIVE.len()].eq_ignore_ascii_case(DIRECTIVE)
222            || !line[DIRECTIVE.len()..].starts_with(char::is_whitespace)
223        {
224            return false;
225        }
226
227        let declared = self.original[from + leading + DIRECTIVE.len()..to].trim();
228        if declared.is_empty() {
229            return false;
230        }
231        self.active = declared.to_owned();
232        self.redefined_at = (self.active != self.initial).then(|| self.line_of(from));
233        self.start = to.min(self.masked.len());
234        true
235    }
236
237    /// Builds one statement, unless the region holds nothing but blank space.
238    ///
239    /// The line reported is the one the statement starts on, not the one the
240    /// region does: a region begins right after the previous separator, so its
241    /// own line is the line the predecessor ended on.
242    fn take(&mut self, region: std::ops::Range<usize>) -> Option<Piece> {
243        let whole = &self.original[region.clone()];
244        let text = whole.trim();
245        if text.is_empty() {
246            return None;
247        }
248        let leading = whole.len() - whole.trim_start().len();
249        let sql = text.to_owned();
250        let line = self.line_of(region.start + leading);
251        self.handed_out += 1;
252        Some(Piece {
253            index: self.handed_out,
254            line,
255            sql,
256        })
257    }
258
259    /// The line one offset falls on, counted from one.
260    ///
261    /// The count is carried forward rather than made from the start of the
262    /// file each time, or a file of many statements would cost the square of
263    /// its length to cut. The walk only ever moves forward, and the guard is
264    /// there so that a caller who rewinds it still gets the right line.
265    fn line_of(&mut self, offset: usize) -> usize {
266        if offset < self.counted_upto {
267            self.counted_upto = 0;
268            self.breaks_before = 0;
269        }
270        self.breaks_before += self.original[self.counted_upto..offset]
271            .matches('\n')
272            .count();
273        self.counted_upto = offset;
274        self.breaks_before + 1
275    }
276}
277
278#[cfg(test)]
279mod tests {
280    use super::*;
281
282    fn pieces(text: &str, delimiter: &str) -> Vec<Piece> {
283        split(text, delimiter)
284            .expect("the file must split")
285            .collect()
286    }
287
288    fn statements(text: &str, delimiter: &str) -> Vec<String> {
289        pieces(text, delimiter).into_iter().map(|p| p.sql).collect()
290    }
291
292    #[test]
293    fn a_file_is_cut_at_every_separator_and_each_piece_knows_its_position() {
294        let cut = pieces("SELECT 1;\nSELECT 2;\n", ";");
295        assert_eq!(cut.len(), 2);
296        assert_eq!(
297            cut[0],
298            Piece {
299                index: 1,
300                line: 1,
301                sql: "SELECT 1".to_owned()
302            }
303        );
304        assert_eq!(
305            cut[1],
306            Piece {
307                index: 2,
308                line: 2,
309                sql: "SELECT 2".to_owned()
310            }
311        );
312
313        assert_eq!(
314            statements("SELECT 1;\nSELECT 2", ";"),
315            vec!["SELECT 1".to_owned(), "SELECT 2".to_owned()],
316            "a last statement written without a separator is not lost"
317        );
318        for nothing in ["", "\n\n  \n", ";;;"] {
319            assert!(pieces(nothing, ";").is_empty(), "input {nothing:?}");
320        }
321    }
322
323    /// A separator inside a literal, a quoted name or a comment is not a
324    /// separator, or a legitimate file would be cut in the middle.
325    #[test]
326    fn a_separator_that_is_not_one_never_cuts_the_file() {
327        for (file, whole) in [
328            ("SELECT 'a;b' AS note;\n", "SELECT 'a;b' AS note"),
329            ("SELECT 1 AS `a;b`;\n", "SELECT 1 AS `a;b`"),
330            ("SELECT 1 -- ; not a cut\n;\n", "SELECT 1 -- ; not a cut"),
331            ("SELECT /* ; */ 1;\n", "SELECT /* ; */ 1"),
332        ] {
333            assert_eq!(
334                statements(file, ";"),
335                vec![whole.to_owned()],
336                "input {file:?}"
337            );
338        }
339    }
340
341    /// The reason the directive exists: a routine body carries separators of
342    /// its own and must reach the server whole.
343    #[test]
344    fn a_routine_body_with_inner_separators_reaches_the_server_whole() {
345        let file = "DELIMITER $$\n\
346                    CREATE PROCEDURE p()\n\
347                    BEGIN\n\
348                      SELECT 1;\n\
349                      SELECT 2;\n\
350                    END$$\n\
351                    DELIMITER ;\n\
352                    SELECT 3;\n";
353        let cut = statements(file, ";");
354        assert_eq!(cut.len(), 2, "the body is one statement, got {cut:?}");
355        assert!(cut[0].starts_with("CREATE PROCEDURE p()"));
356        assert!(
357            cut[0].contains("SELECT 1;") && cut[0].contains("SELECT 2;"),
358            "the inner separators survive: {}",
359            cut[0]
360        );
361        assert_eq!(cut[1], "SELECT 3");
362
363        // Redefined and never restored, the file is refused with its line.
364        //
365        // The refusal is earned by the whole file and is decided before the
366        // walk is handed over, so no statement of a file that will be refused
367        // can reach the server first. That is what `expect_err` proves here:
368        // there is no walk at all to take a statement from.
369        let unrestored = "SELECT 1;\nDELIMITER $$\nCREATE PROCEDURE p() BEGIN SELECT 1; END$$\n";
370        let failure = split(unrestored, ";").expect_err("must refuse");
371        assert_eq!(failure.code(), "script.delimiter_not_restored");
372        assert!(failure.message().contains('2'), "the line is named");
373    }
374
375    /// The walk is asked twice for the same file and answers the same way.
376    ///
377    /// The refusal a redefined separator earns is decided by a walk of its own,
378    /// so the walk the caller consumes is the second one over the same text.
379    /// A position or an index carried over from the first would show here.
380    #[test]
381    fn the_walk_handed_to_the_caller_starts_where_the_file_does() {
382        let file = "-- a note\nSELECT 1;\n\n\nDELIMITER $$\nSELECT 2$$\nDELIMITER ;\nSELECT 3;\n";
383        let once = pieces(file, ";");
384        let twice = pieces(file, ";");
385        assert_eq!(once, twice, "the same file cut twice is the same cut");
386        assert_eq!(
387            once.iter().map(|p| (p.index, p.line)).collect::<Vec<_>>(),
388            vec![(1, 1), (2, 6), (3, 8)],
389            "got {once:?}"
390        );
391    }
392
393    /// The directive belongs to the file and is never a statement; the same
394    /// word inside a statement is not a directive at all.
395    #[test]
396    fn the_directive_is_never_sent_and_the_same_word_inside_a_statement_is_not_one() {
397        for statement in statements("DELIMITER $$\nSELECT 1$$\nDELIMITER ;\n", ";") {
398            assert!(
399                !statement.to_lowercase().starts_with(DIRECTIVE),
400                "the directive leaked into a statement: {statement}"
401            );
402        }
403        assert_eq!(
404            statements("SELECT a\nFROM delimiter x;\n", ";"),
405            vec!["SELECT a\nFROM delimiter x".to_owned()]
406        );
407        assert_eq!(
408            statements("SELECT 1$$SELECT 2$$", "$$"),
409            vec!["SELECT 1".to_owned(), "SELECT 2".to_owned()],
410            "a file may use a separator of its own from the start"
411        );
412    }
413
414    #[test]
415    fn a_file_that_could_never_be_split_is_refused_rather_than_cut_into_nonsense() {
416        let failure = validate_delimiter("").expect_err("must refuse");
417        assert_eq!(failure.code(), "usage.empty_delimiter");
418        assert_eq!(failure.exit_number().code(), 2);
419        assert_eq!(
420            split("SELECT 1", "  ").expect_err("must refuse").code(),
421            "usage.empty_delimiter"
422        );
423        assert_eq!(
424            split("SELECT 'never closed;\n", ";")
425                .expect_err("must refuse")
426                .code(),
427            "sql.unterminated_region"
428        );
429    }
430
431    /// The line reported is the one the statement starts on, and a leading
432    /// comment is part of the statement it introduces.
433    #[test]
434    fn the_positions_reported_survive_blank_lines_and_comments() {
435        let file = "-- a note\n\n\nSELECT 1;\n\n-- another\nSELECT 2;\n";
436        let cut = pieces(file, ";");
437        assert_eq!(cut[0].line, 1, "a leading comment belongs to the statement");
438        assert_eq!(cut[1].line, 6);
439        assert!(cut[1].sql.starts_with("-- another"));
440
441        // A statement is never reported on the line its predecessor ended on.
442        let spaced = pieces("SELECT 1;\n\n\nSELECT 2;\n", ";");
443        assert_eq!((spaced[0].line, spaced[1].line), (1, 4));
444    }
445}