links-notation 0.22.0

Rust implementation of the Links Notation parser
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

//! Comments, and the rule that decides where one starts.
//!
//! A comment starts at a `#` written where a line or a token starts and runs to
//! the end of the line. The parser never sees it: [`strip_comments`] replaces
//! every byte of every comment with a space before the document is parsed, so
//! the notation itself stays exactly as it was and a position reported by the
//! parser still points at the same character of the document the caller wrote.

use crate::quotes::{DelimitedReferences, QUOTES};

/// The character that opens a comment.
pub const COMMENT: char = '#';

/// What can stand before a delimited reference: the reference is the first
/// thing on a line, follows a space, opens a group or follows a colon.
const BEFORE_REFERENCE: [u8; 6] = *b" \t\n\r(:";

/// What can stand before a comment: the comment is the first thing on a line,
/// or it follows whitespace. A `#` inside a word is part of that word, so
/// `issue#1047` is a reference and not the start of a comment.
const BEFORE_COMMENT: [u8; 4] = *b" \t\n\r";

/// Blanks out every comment in `document`, keeping every other byte where it
/// was.
///
/// Comments are replaced rather than removed so that a byte offset in the
/// result is the same byte offset in `document`: the line and column a parse
/// error reports are the line and column the writer sees in their file.
///
/// A `#` inside a delimited reference is content, so `"# not a comment"` is
/// still one reference.
///
/// # Examples
/// ```
/// use links_notation::comments::strip_comments;
///
/// assert_eq!(strip_comments("a: b # why\n"), "a: b      \n");
/// assert_eq!(strip_comments("\"# kept\"\n"), "\"# kept\"\n");
/// assert_eq!(strip_comments("issue#1047\n"), "issue#1047\n");
/// ```
pub fn strip_comments(document: &str) -> String {
    let mut bytes = document.as_bytes().to_vec();
    let references = DelimitedReferences::new(document);
    let mut position = 0;

    while position < bytes.len() {
        let byte = bytes[position];

        if QUOTES.contains(&byte) && follows(&bytes, position, &BEFORE_REFERENCE) {
            match references.end_at(document, position) {
                Some(end) => position = end,
                None => position += 1,
            }
            continue;
        }

        if byte == COMMENT as u8 && follows(&bytes, position, &BEFORE_COMMENT) {
            while position < bytes.len() && bytes[position] != b'\n' && bytes[position] != b'\r' {
                bytes[position] = b' ';
                position += 1;
            }
            continue;
        }

        position += 1;
    }

    // Only whole comments were replaced, and only by spaces, so what is left is
    // the document it was read from with some of its bytes blanked.
    String::from_utf8(bytes).expect("blanking comment bytes keeps the document valid UTF-8")
}

/// Reports whether the byte before `position` is one of `allowed`, treating the
/// start of the document as one of them.
fn follows(bytes: &[u8], position: usize, allowed: &[u8]) -> bool {
    match position {
        0 => true,
        _ => allowed.contains(&bytes[position - 1]),
    }
}