combi 1.0.2

A combinators library with an included rust token parsing implementation
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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180

//! Parser combinators for consuming [tokenstreams](TokenStream) to create [rust compiler diagnostics](Diagnostic).
//! - No backtracking is permitted
//! - 1-token of lookahead provided by [TokenIter::peek_next]

use proc_macro2::{token_stream::IntoIter, Span, TokenStream, TokenTree};
use proc_macro_error2::Diagnostic;
use std::collections::LinkedList;

use crate::{Combi, CombiCon, CombiErr};

pub mod basic;
pub mod derived;
pub mod error;
pub mod matcher;
pub mod options;
pub mod recovery;

/// A wrapper for [TokenStream] that allows for 1-token lookahead, and records the current and last [Span]s.
pub struct TokenIter {
    next: Option<TokenTree>,
    iter: IntoIter,
    curr_span: Span,
    prev_span: Option<Span>,
}

impl TokenIter {
    pub fn from(ts: TokenStream, start_span: Span) -> Self {
        let mut iter = ts.into_iter();
        Self {
            next: iter.next(),
            iter,
            curr_span: start_span,
            prev_span: Some(start_span),
        }
    }

    /// Advance to the next token, and return `Some(token)` if present, otherwise return `None` and do not advance.
    #[allow(clippy::should_implement_trait)]
    pub fn next(&mut self) -> Option<TokenTree> {
        if let Some(ref tk) = self.next {
            self.prev_span = Some(self.curr_span);
            self.curr_span = tk.span();
            let mut some_tk = self.iter.next();
            std::mem::swap(&mut self.next, &mut some_tk);
            some_tk
        } else {
            None
        }
    }

    pub fn peek_next(&self) -> &Option<TokenTree> {
        &self.next
    }

    /// The span of the last token from [Self::next()].
    pub fn cur_span(&self) -> &Span {
        &self.curr_span
    }

    /// The span of the last, last token found from [Self::next()].
    pub fn last_span(&self) -> &Option<Span> {
        &self.prev_span
    }

    pub fn extract_iter(self) -> IntoIter {
        self.iter
    }
}

/// Both an [error](Combi::Err) and [continuation](Combi::Con) that contains compiler diagnostcs.
#[derive(Debug)]
pub struct TokenDiagnostic {
    main: Diagnostic,
    prev: LinkedList<Diagnostic>,
}

impl TokenDiagnostic {
    fn from(main: Diagnostic) -> Self {
        Self {
            main,
            prev: LinkedList::new(),
        }
    }

    fn combine(mut self, mut other: Self) -> Self {
        Self {
            main: self.main,
            prev: {
                self.prev.push_back(other.main);
                self.prev.append(&mut other.prev);
                self.prev
            },
        }
    }

    pub fn into_list(self) -> LinkedList<Diagnostic> {
        let mut list = self.prev;
        list.push_back(self.main);
        list
    }

    pub fn from_list(mut list: LinkedList<Diagnostic>) -> Option<Self> {
        list.pop_front().map(|main| Self { main, prev: list })
    }
}

impl CombiErr<TokenDiagnostic> for TokenDiagnostic {
    fn inherit_con(self, con: TokenDiagnostic) -> Self {
        self.combine(con)
    }

    fn catch_con(con: TokenDiagnostic) -> Self {
        con
    }
}

impl<S> CombiCon<S, TokenDiagnostic> for TokenDiagnostic {
    fn combine_suc(self, _: S) -> Self {
        self
    }

    fn combine_con(self, con: TokenDiagnostic) -> Self {
        self.combine(con)
    }
}

// NOTE: Potential rustc issue, when O is made a generic, we get an error as
//       TokenParser may be implemented for the combi::core types by a
//       downstream crate.
//       See: https://github.com/rust-lang/rust/issues/50237
// NOTE: Ideally I would make an alias, that binds the associated types of a
//       Combi impl, then implement that, however we run into significant issues
//       with potentially conflicting traits
// TODO: create a binding for recovery and parsers, like with:
//       ```rust
//       trait Alias: Trait<Item=char> {}
//       impl<T: Trait<Item=char>> Alias for T {}
//       ```

/// An alias for the [Combi] trait, for token parsers
pub trait TokenParser<S>:
    Combi<Suc = S, Err = TokenDiagnostic, Con = TokenDiagnostic, Inp = TokenIter, Out = TokenIter>
{
}
impl<
        S,
        T: Combi<
            Suc = S,
            Err = TokenDiagnostic,
            Con = TokenDiagnostic,
            Inp = TokenIter,
            Out = TokenIter,
        >,
    > TokenParser<S> for T
{
}

/// An alias for the [Combi] trait, for recovery parsers
pub trait TokenRecover<S>:
    Combi<
    Suc = S,
    Err = TokenDiagnostic,
    Con = TokenDiagnostic,
    Inp = (TokenDiagnostic, TokenIter),
    Out = TokenIter,
>
{
}
impl<
        S,
        T: Combi<
            Suc = S,
            Err = TokenDiagnostic,
            Con = TokenDiagnostic,
            Inp = (TokenDiagnostic, TokenIter),
            Out = TokenIter,
        >,
    > TokenRecover<S> for T
{
}