rustla/parser/
types_and_aliases.rs

1/*!
2A submodule that contains Parser-related type aliases.
3
4Copyright © 2020 Santtu Söderholm
5*/
6
7use super::*;
8
9// =====================================
10//   Type aliases needed by the parser
11// =====================================
12
13/// A function pointer type alias for a State transition method.
14/// `TransitionMethod`s take in the document tree and regex captures
15/// for doctree modifications.
16/// They return a `TransitionResult::{Success, Failure}`, the success variant of which contains a doctree,
17/// a possible next state for the parser, information about manipulating the machine stack and whether to advance the parser line cursor.
18/// If the optional next state is *not* `None`, the current state is either replaced with the new state or
19/// the new state is pushed on top of the machine stack of the parser and parsing proceeds
20/// in that state from the current line.
21pub type TransitionMethod = fn(
22    src_lines: &Vec<String>,
23    base_indent: usize,
24    section_level: &mut usize,
25    line_cursor: &mut LineCursor,
26    doctree: DocTree,
27    captures: &regex::Captures,
28    pattern_name: &Pattern,
29) -> TransitionResult;
30
31/// A type alias for a tuple `(PatternName, Regex, TransitionMethod)`
32pub type Transition = (Pattern, regex::Regex, TransitionMethod);
33
34/// A type alias for a transition `(PatternName, regex_pattern, TransitionMethod)`, whose regex pattern has not
35/// been compiled into a DFA yet.
36pub type UncompiledTransition = (Pattern, &'static str, TransitionMethod);
37
38/// A type alias for a function describing an inline transition.
39/// Returns a node a length of the match, so that the inline parser
40/// could determine how many characters to eat off the start of the
41/// source string.
42pub type InlineParsingMethod = fn(
43    opt_doctree_ref: &mut Option<&mut DocTree>,
44    pattern_name: Pattern,
45    captures: &regex::Captures,
46) -> (Vec<TreeNodeType>, usize);
47
48/// A type alias for a tuple `(PatternName, regex pattern, InlineTransitionMethod)`.
49pub type InlineTransition = (Pattern, &'static str, InlineParsingMethod);
50
51// ====================================================
52//   Types and enums used by submodules of the parser
53// ====================================================
54
55/// An enumeration of the different results, including errors,
56/// that a transition function might have.
57pub enum TransitionResult {
58
59    /// This is returned if nothing goes wrong with a transition method.
60    /// It includes the modified document tree, plus information about
61    /// how to manipulate the parser stack, whether the parser should advance
62    /// its line cursor.
63    Success {
64        doctree: DocTree,
65        push_or_pop: PushOrPop,
66        line_advance: LineAdvance,
67    },
68
69    /// A general failure result. This will be returned if a clear error, such as a completetely invalid enumerator was
70    /// encountered in a transition method functions. Contains an error message and the doctree in its current state.
71    Failure { message: String, doctree: DocTree },
72}
73
74/// An enum for manipulating the machine stack. Transition methods should return this information
75/// with a possible next state, so the parser knows how to proceed. The `Push` variant signifies
76/// a state should be pushed on top of the stack, `Pop` tells of the need to pop from the stack
77/// and `Neither` initiates a transition of the current state into another one.
78#[derive(Debug)]
79pub enum PushOrPop {
80
81    /// Causes `Parser::parse` to push the contained states on top of the parser stack.
82    Push(Vec<State>),
83    /// Causes `Parser::parse` to pop the topmost state from the parser state stack.
84    Pop,
85    /// Signifies to `Parser::parse` that nothing about the stack needs to change.
86    Neither,
87}
88
89/// An enum returned by the transition methods to tell the parser whether
90/// it needs to advance its line cursor after the method execution or not.
91pub enum LineAdvance {
92    Some(usize),
93    None,
94}
95
96/// An enumeration of the different ways an inline parsing function might succeed or fail.
97pub enum InlineParsingResult {
98
99    /// If no doctree was given to the inline parsing function, so tree nodes might be appended to it directly,
100    /// the data of the generated nodes is given to the caller stored in a vector.
101    Nodes(Vec<TreeNodeType>),
102
103    /// If no nodes were discovered and no doctree was given to be modified, this empty variant is returned.
104    NoNodes,
105}
106
107/// A enumeration of the different ways a node's child indentation might
108/// interact with the indentation of the parent.
109pub enum IndentationMatch {
110
111    /// If a (sub)?body node has less indentation than its parent would require,
112    /// it is interpreted as not belonging to the currently focused on node.
113    TooLittle,
114
115    /// This node belongs to the parent node.
116    JustRight,
117
118    /// This node is most likely a block quote.
119    TooMuch,
120}
121
122/// A enumeration of the different ways the function `Parser::read_indented_block` could succeed or fail.
123pub enum IndentedBlockResult {
124    /// The reading of the text block succeeded as intended
125    Ok {
126        lines: Vec<String>,
127        minimum_indent: usize,
128        offset: usize,
129        blank_finish: bool,
130    },
131    /// The given line vector was empty
132    EmptyLinesErr,
133    ///
134    UnfinishedErr {
135        lines: Vec<String>,
136        minimum_indent: usize,
137        offset: usize,
138        blank_finish: bool,
139    }
140}
141
142/// A enumeration of the different ways the function `Parser::read_text_block` could succeed or fail.
143pub enum TextBlockResult {
144    Ok {
145        lines: Vec<String>,
146        offset: usize,
147    },
148    Err {
149        lines: Vec<String>,
150        offset: usize,
151    }
152}
rustla/parser/types_and_aliases.rs

rustla/parser/
types_and_aliases.rs
