sidoc 0.1.3

Generate structured/scoped indented documents.
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
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198

use crate::{Doc, Error, Node};

/// Constructor for `Doc` objects.
#[derive(Default)]
pub struct Builder {
  nodes: Vec<Node>,
  scope_stack: Vec<Option<String>>
}

impl Builder {
  /// Create a new `Doc` builder context.
  #[must_use]
  pub fn new() -> Self {
    Self::default()
  }

  /// Begin a scope, pushing an optional scope terminator to the internal scope
  /// stack.
  ///
  /// If the scope generated using a terminator line, that line will appended
  /// to the document when the scope is closed using the `exit()` method.
  #[allow(clippy::needless_pass_by_value)]
  pub fn scope<L: ToString, K: ToString>(
    &mut self,
    begin_line: L,
    term_line: Option<K>
  ) -> &mut Self {
    self.nodes.push(Node::BeginScope(begin_line.to_string()));
    if let Some(ln) = term_line {
      self.scope_stack.push(Some(ln.to_string()));
    } else {
      self.scope_stack.push(None);
    }
    self
  }

  /// Wrap [`Builder::scope()`] and [`Builder::exit()`].
  ///
  /// Initialize a new scope, call caller-supplied closure, and automatically
  /// exit scope before returning.
  ///
  /// ```
  /// use std::sync::Arc;
  /// use sidoc::{Builder, RenderContext};
  ///
  /// let mut bldr = Builder::new();
  ///
  /// bldr
  ///   .line("<!DOCTYPE html>")
  ///   .autoscope("<html>", Some("</html>"), |bldr| {
  ///     bldr.autoscope("<head>", Some("</head>"), |bldr| {
  ///       bldr.line("<title>hello</title>");
  ///     });
  ///   });
  ///
  /// let doc = bldr.build().unwrap();
  /// let mut r = RenderContext::new();
  /// r.doc("root", Arc::new(doc));
  /// let buf = r.render("root").unwrap();
  ///
  /// assert_eq!(
  ///   buf,
  ///   "<!DOCTYPE html>\n<html>\n  <head>\n    <title>hello</title>\n  </head>\n</html>\n"
  /// );
  /// ```
  #[allow(clippy::needless_pass_by_value)]
  pub fn autoscope<F, L: ToString, K: ToString>(
    &mut self,
    begin_line: L,
    term_line: Option<K>,
    f: F
  ) -> &mut Self
  where
    F: FnOnce(&mut Self)
  {
    self.scope(begin_line, term_line);
    f(self);
    self.exit();
    self
  }

  /// Same as [`Builder::autoscope()`], but only init scope and call closure if
  /// predicate is true.
  #[allow(clippy::needless_pass_by_value)]
  pub fn autoscope_if<F, L: ToString, K: ToString>(
    &mut self,
    pred: bool,
    begin_line: L,
    term_line: Option<K>,
    f: F
  ) -> &mut Self
  where
    F: FnOnce(&mut Self)
  {
    if pred {
      self.scope(begin_line, term_line);
      f(self);
      self.exit();
    }
    self
  }

  /// Same as [`Builder::autoscope()`], but only init scope and call closure if
  /// `opt` is `Some(T)`.  `T` will be passed to the closure.
  #[allow(clippy::needless_pass_by_value)]
  pub fn autoscope_opt<F, T, L: ToString, K: ToString>(
    &mut self,
    opt: Option<T>,
    begin_line: L,
    term_line: Option<K>,
    f: F
  ) -> &mut Self
  where
    F: FnOnce(&mut Self, T)
  {
    if let Some(o) = opt {
      self.scope(begin_line, term_line);
      f(self, o);
      self.exit();
    }
    self
  }

  /// Leave a previously entered scope.
  ///
  /// If the `scope()` call that created the current scope
  ///
  /// # Panics
  /// The scope stack must not be empty.
  pub fn exit(&mut self) -> &mut Self {
    if let Some(s) = self.scope_stack.pop().unwrap() {
      self.nodes.push(Node::EndScope(Some(s)));
    } else {
      self.nodes.push(Node::EndScope(None));
    }
    self
  }

  /// Leave previously entered scope, adding a line passed by the caller rather
  /// than the scope stack.
  ///
  /// # Panics
  /// The scope stack must not be empty.
  #[allow(clippy::needless_pass_by_value)]
  pub fn exit_line<L: ToString>(&mut self, line: L) -> &mut Self {
    let _ = self.scope_stack.pop().unwrap();
    self.nodes.push(Node::EndScope(Some(line.to_string())));
    self
  }

  /// Add a new line at current scope.
  #[allow(clippy::needless_pass_by_value)]
  pub fn line<L: ToString>(&mut self, line: L) -> &mut Self {
    self.nodes.push(Node::Line(line.to_string()));
    self
  }

  /// Add a named optional reference.
  ///
  /// References are placeholders for other documents.  An optional reference
  /// means that this reference does not need to be resolved by the renderer.
  #[allow(clippy::needless_pass_by_value)]
  pub fn optref<N: ToString>(&mut self, name: N) -> &mut Self {
    self.nodes.push(Node::OptRef(name.to_string()));
    self
  }

  /// Add a named required reference.
  ///
  /// References are placeholders for other documents.  A required reference
  /// must be resolved by the renderer or it will return an error to its
  /// caller.
  #[allow(clippy::needless_pass_by_value)]
  pub fn reqref<N: ToString>(&mut self, name: N) -> &mut Self {
    self.nodes.push(Node::ReqRef(name.to_string()));
    self
  }

  /// Generate a `Doc` object from this document.
  ///
  /// The document must be properly nested before calling this function,
  /// meaning all scopes it opened must be closed.
  ///
  /// # Errors
  /// [`Error::BadNesting`] means one or more scopes are still open.
  pub fn build(self) -> Result<Doc, Error> {
    if self.scope_stack.is_empty() {
      Ok(Doc { nodes: self.nodes })
    } else {
      Err(Error::BadNesting(format!(
        "{} scope(s) remaining",
        self.scope_stack.len()
      )))
    }
  }
}

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :