104 | // someattribute
105 | // | a; b; ...
106 | // | Description of how someattribute applies to a, b, etc.
107 | // | Description if the valid values
108 | // And we want to extract the descriptions so that we can later insert them
109 | // alongside the definitions of attr-a-someattribute, etc.
110 | let row_children = row.children.borrow();
111 | let mut tds = row_children
112 | .iter()
113 | .filter(|c| c.is_html_element(&local_name!("td")));
114 | let (keys_td, description_td) = match (tds.next(), tds.next()) {
115 | (Some(a), Some(b)) => (a, b),
116 | _ => continue,
117 | };
118 |
119 | // If a single row describes the same element multiple times, we don't need to repeat it.
120 | // StrTendril doesn't have logical interior mutability, so this Clippy warning is overzealous.
121 | #[allow(clippy::mutable_key_type)]
122 | let mut seen_this_row: HashSet = HashSet::new();
123 |
124 | // These will be strings like "attr-input-maxlength", which identify particular element-attribute pairs.
125 | let data_x = QualName::new(None, ns!(), LocalName::from("data-x"));
126 | for attr_key in keys_td
127 | .children
128 | .borrow()
129 | .iter()
130 | .filter_map(|c| c.get_attribute(&data_x).filter(|v| !v.is_empty()))
131 | {
132 | // If this row describes the the same attribute, with the same
133 | // identifier, for multiple elements (like attr-fae-form and
134 | // attr-dim-width), these aren't actually distinct descriptions
135 | // and we need not join them.
136 | if !seen_this_row.insert(attr_key.clone()) {
137 | continue;
138 | }
139 |
140 | // Find the comment, if one exists, and extract its contents.
141 | let description = description_td.children.borrow();
142 | let mut variant_comment = None;
143 | let mut variant_str = None;
144 | for node in description.iter() {
145 | if let NodeData::Comment { ref contents } = node.data {
146 | if contents.trim().starts_with("or:") {
147 | variant_comment = Some(node);
148 | variant_str = Some(StrTendril::from(contents.trim()[3..].trim_start()));
149 | }
150 | }
151 | }
152 |
153 | // Store the (already parsed) ordinary description. If a variant
154 | // comment exists, omit it and instead store its unparsed
155 | // string.
156 | let descriptions = Descriptions {
157 | default: description_td
158 | .children
159 | .borrow()
160 | .iter()
161 | .filter(|c| variant_comment.map_or(true, |vc| !Rc::ptr_eq(c, vc)))
162 | .map(|c| c.deep_clone())
163 | .collect(),
164 | variant: variant_str,
165 | };
166 | let existing = self.attributes.entry(attr_key).or_default();
167 | if existing.default.is_empty() {
168 | existing.default = descriptions.default;
169 | } else if !descriptions.default.is_empty() {
170 | if let NodeData::Text { ref contents } = existing.default.last().unwrap().data {
171 | let mut borrow = contents.borrow_mut();
172 | if let Some(last_non_ws) = borrow.rfind(|c: char| !c.is_ascii_whitespace())
173 | {
174 | let to_remove = borrow.len32() - (last_non_ws as u32) - 1;
175 | borrow.pop_back(to_remove);
176 | }
177 | }
178 | existing.default.push(Handle::create_text_node("; "));
179 | existing.default.extend(descriptions.default.into_iter());
180 | }
181 | if existing.variant.is_none() {
182 | existing.variant = descriptions.variant;
183 | } else if descriptions.variant.is_some() {
184 | let existing_variant = existing.variant.as_mut().unwrap();
185 | existing_variant.push_slice("; ");
186 | existing_variant.push_tendril(&descriptions.variant.unwrap());
187 | }
188 | }
189 | }
190 | }
191 |
192 | fn index_attribute_list(&mut self, dt: &Handle) {
193 | // If a contains , it is not annotated.
194 | // If it contains , the description found in a comment is used instead.
195 | // If it mentions "special semantics", it is joined with a colon rather than an em dash.
196 | let data_x = QualName::new(None, ns!(), LocalName::from("data-x"));
197 | let parent = dt.parent_node().unwrap();
198 | let children = parent.children.borrow();
199 | self.edits.extend(
200 | children
201 | .iter()
202 | .skip_while(|n| !Rc::ptr_eq(n, dt))
203 | .skip(1)
204 | .filter(|n| n.is_element())
205 | .take_while(|e| e.is_html_element(&local_name!("dd")))
206 | .filter_map(|dd| {
207 | let mut can_annotate = true;
208 | let mut wants_variant_description = false;
209 | let mut has_special_semantics = false;
210 | let mut key = None;
211 | dom_utils::scan_dom(dd, &mut |n| match &n.data {
212 | NodeData::Comment { ref contents } if contents.trim() == "no-annotate" => {
213 | can_annotate = false;
214 | }
215 | NodeData::Comment { ref contents } if contents.trim() == "variant" => {
216 | wants_variant_description = true;
217 | }
218 | NodeData::Text { ref contents }
219 | if contents.borrow().contains("has special semantics") =>
220 | {
221 | has_special_semantics = true;
222 | }
223 | NodeData::Element { .. } => {
224 | if key.is_none() {
225 | key = n.get_attribute(&data_x);
226 | }
227 | }
228 | _ => (),
229 | });
230 | match (can_annotate, key) {
231 | (true, Some(key)) => Some(Edit {
232 | dd: dd.clone(),
233 | key,
234 | wants_variant_description,
235 | has_special_semantics,
236 | }),
237 | _ => None,
238 | }
239 | }),
240 | );
241 | }
242 |
243 | pub async fn apply(self) -> io::Result<()> {
244 | let em_dash = StrTendril::from(" \u{2014} ");
245 |
246 | for Edit {
247 | dd,
248 | key,
249 | wants_variant_description,
250 | has_special_semantics,
251 | } in self.edits
252 | {
253 | // Find the requested description to insert at this point.
254 | let descriptions = match self.attributes.get(&key) {
255 | Some(descriptions) => descriptions,
256 | None => continue,
257 | };
258 | let mut description: Vec = match descriptions {
259 | Descriptions {
260 | variant: Some(ref variant),
261 | ..
262 | } if wants_variant_description => {
263 | parser::parse_fragment_async(variant[..].as_bytes(), &dd).await?
264 | }
265 | _ if wants_variant_description => {
266 | return Err(io::Error::new(
267 | io::ErrorKind::InvalidData,
268 | format!(
269 | "Attribute {key} wants variant description, but no was found"
270 | ),
271 | ))
272 | }
273 | Descriptions { ref default, .. } => {
274 | default.iter().map(|n| n.deep_clone()).collect()
275 | }
276 | };
277 |
278 | let mut dd_children = dd.children.borrow_mut();
279 | if has_special_semantics {
280 | // Replace the trailing period with a separating colon.
281 | if let Some(NodeData::Text { contents }) = dd_children.last_mut().map(|n| &n.data) {
282 | let mut text = contents.borrow_mut();
283 | *text = StrTendril::from(
284 | text.trim_end_matches(|c: char| c.is_ascii_whitespace() || c == '.'),
285 | );
286 | text.push_slice(": ");
287 | }
288 | } else {
289 | // Insert an em dash.
290 | description.insert(0, Handle::create_text_node(em_dash.clone()));
291 | }
292 |
293 | // Insert the description.
294 | for child in description.iter_mut() {
295 | child.parent.set(Some(Rc::downgrade(&dd)));
296 | }
297 | dd_children.extend(description);
298 | }
299 | Ok(())
300 | }
301 | }
302 |
303 | #[cfg(test)]
304 | mod tests {
305 | use super::*;
306 | use crate::parser::{parse_document_async, tests::serialize_for_test};
307 |
308 | #[tokio::test]
309 | async fn test_simple() -> io::Result<()> {
310 | // This is a simple document with enough stuff in it. Elements are shown
311 | // before and after the attributes table, to demonstrate that this is
312 | // not sensitive to which order they occur in (i.e., these could be
313 | // reordered in the HTML spec).
314 | let document = parse_document_async(
315 | r#"
316 |
317 | The a element
318 |
319 | - Categories
320 |
- Flow content
321 |
- Content attributes
322 |
href
323 |
324 | Attributes
325 |
326 | href | a; area | Destination of the hyperlink
327 | |
|---|
328 | The area element
329 |
330 | - Categories
331 |
- Flow content
332 |
- Content attributes
333 |
href
334 |
335 | "#.trim().as_bytes()).await?;
336 | let mut proc = Processor::new();
337 | dom_utils::scan_dom(&document, &mut |h| proc.visit(h));
338 | proc.apply().await?;
339 | assert_eq!(
340 | serialize_for_test(&[document]),
341 | r#"
342 | The a element
343 |
344 | - Categories
345 |
- Flow content
346 |
- Content attributes
347 |
href
348 | — Destination of the hyperlink
349 |
350 | Attributes
351 |
352 | href | a; area | Destination of the hyperlink
353 | |
|---|
354 | The area element
355 |
356 | - Categories
357 |
- Flow content
358 |
- Content attributes
359 |
href
360 | — Destination of the hyperlink
361 |
362 | "#.trim()
363 | );
364 | Ok(())
365 | }
366 |
367 | #[tokio::test]
368 | async fn test_variant() -> io::Result<()> {
369 | // This checks that and work correctly.
370 | // i.e., the variant description is used where requested
371 | let document = parse_document_async(
372 | r#"
373 |
374 | The a element
375 |
376 | - Content attributes
377 |
href
378 |
379 | Attributes
380 |
381 | href | a; area | Destination of the hyperlink
382 | |
|---|
383 | The area element
384 |
385 | - Content attributes
386 |
href
387 |
388 | "#.trim().as_bytes()).await?;
389 | let mut proc = Processor::new();
390 | dom_utils::scan_dom(&document, &mut |h| proc.visit(h));
391 | proc.apply().await?;
392 | assert_eq!(
393 | serialize_for_test(&[document]),
394 | r#"
395 | The a element
396 |
397 | - Content attributes
398 |
href
399 | — Destination of the hyperlink
400 |
401 | Attributes
402 |
403 | href | a; area | Destination of the hyperlink
404 | |
|---|
405 | The area element
406 |
407 | - Content attributes
408 |
href
409 | — click on shapes!
410 | "#.trim()
411 | );
412 | Ok(())
413 | }
414 |
415 | #[tokio::test]
416 | async fn test_special_semantics() -> io::Result<()> {
417 | // Checks that the special rules for using : instead of an em dash work.
418 | let document = parse_document_async(
419 | r#"
420 |
421 | The a element
422 |
423 | - Content attributes
424 |
- Also, the
name attribute has special semantics on this element.
425 |
426 | Attributes
427 |
428 | name | a | Anchor name
429 | |
|---|
430 | "#.trim().as_bytes()).await?;
431 | let mut proc = Processor::new();
432 | dom_utils::scan_dom(&document, &mut |h| proc.visit(h));
433 | proc.apply().await?;
434 | assert_eq!(
435 | serialize_for_test(&[document]),
436 | r#"
437 | The a element
438 |
439 | - Content attributes
440 |
- Also, the
name attribute has special semantics on this element: Anchor name
441 |
442 | Attributes
443 |
444 | name | a | Anchor name
445 | |
|---|
446 | "#.trim()
447 | );
448 | Ok(())
449 | }
450 |
451 | #[tokio::test]
452 | async fn test_special_semantics_multiple() -> io::Result<()> {
453 | // Checks that the special rules for joining any special semantics with a ; work.
454 | let document = parse_document_async(
455 | r#"
456 |
457 | The a element
458 |
459 | - Content attributes
460 |
- Also, the
name attribute has special semantics on this element.
461 |
462 | Attributes
463 |
464 | name | a | Anchor name
465 | |
|---|
name | a | Name of the anchor
466 | |
|---|
467 | "#.trim().as_bytes()).await?;
468 | let mut proc = Processor::new();
469 | dom_utils::scan_dom(&document, &mut |h| proc.visit(h));
470 | proc.apply().await?;
471 | assert_eq!(
472 | serialize_for_test(&[document]),
473 | r#"
474 | The a element
475 |
476 | - Content attributes
477 |
- Also, the
name attribute has special semantics on this element: Anchor name; Name of the anchor
478 |
479 | Attributes
480 |
481 | name | a | Anchor name
482 | |
|---|
name | a | Name of the anchor
483 | |
|---|
484 | "#.trim()
485 | );
486 | Ok(())
487 | }
488 |
489 | #[tokio::test]
490 | async fn test_identical_links() -> io::Result<()> {
491 | // This checks the same identifier can be linked multiple times without
492 | // repeating the description.
493 | let document = parse_document_async(
494 | r#"
495 |
496 | The img element
497 |
498 | - Content attributes
499 |
width
500 |
501 | The video element
502 |
503 | - Content attributes
504 |
width
505 |
506 | Attributes
507 |
508 | width | img; video | Horizontal dimension
509 | |
|---|
510 | "#.trim().as_bytes()).await?;
511 | let mut proc = Processor::new();
512 | dom_utils::scan_dom(&document, &mut |h| proc.visit(h));
513 | proc.apply().await?;
514 | assert_eq!(
515 | serialize_for_test(&[document]),
516 | r#"
517 | The img element
518 |
519 | - Content attributes
520 |
width
521 | — Horizontal dimension
522 |
523 | The video element
524 |
525 | - Content attributes
526 |
width
527 | — Horizontal dimension
528 |
529 | Attributes
530 |
531 | width | img; video | Horizontal dimension
532 | |
|---|
533 | "#.trim()
534 | );
535 | Ok(())
536 | }
537 | }
538 |
--------------------------------------------------------------------------------
/src/boilerplate.rs:
--------------------------------------------------------------------------------
1 | //! Replaces comments.
2 | //! These can either be comment nodes (in which case the resulting fragment will
3 | //! be inserted), or the complete value of an element's attribute (in which case
4 | //! the text will become the attribute value).
5 |
6 | use std::io;
7 | use std::path::{Path, PathBuf};
8 |
9 | use html5ever::tendril::{self, SendTendril};
10 | use html5ever::{local_name, Attribute, LocalName, QualName};
11 | use markup5ever_rcdom::{Handle, NodeData};
12 | use tokio::fs::File;
13 | use tokio::task::JoinHandle;
14 |
15 | use crate::dom_utils::NodeHandleExt;
16 | use crate::io_utils::{async_error, is_safe_path, read_to_str_tendril};
17 | use crate::parser;
18 |
19 | type SendStrTendril = SendTendril;
20 |
21 | enum Edit {
22 | ReplaceHTML(Handle, JoinHandle>),
23 | ReplaceAttr(Handle, QualName, JoinHandle>),
24 | ReplaceText(Handle, JoinHandle>),
25 | }
26 |
27 | pub struct Processor {
28 | /// Path to look for boilerplate files.
29 | path: PathBuf,
30 |
31 | /// Path to look for example files.
32 | example_path: PathBuf,
33 |
34 | /// Changes to be made in the apply step.
35 | edits: Vec,
36 | }
37 |
38 | impl Processor {
39 | pub fn new(path: impl Into, example_path: impl Into) -> Self {
40 | Self {
41 | path: path.into(),
42 | example_path: example_path.into(),
43 | edits: vec![],
44 | }
45 | }
46 |
47 | /// Should be called for each node in the document.
48 | /// Identifies replacements which will be needed, and starts the necessary
49 | /// I/O.
50 | pub fn visit(&mut self, node: &Handle) {
51 | match node.data {
52 | // BOILERPLATE comments will need to be replaced with their
53 | // corresponding HTML, parsed. Open the file so that we can do so on
54 | // demand.
55 | NodeData::Comment { ref contents } if contents.starts_with("BOILERPLATE ") => {
56 | let path = Path::new(contents[12..].trim());
57 | let file = if is_safe_path(path) {
58 | tokio::spawn(File::open(self.path.join(path)))
59 | } else {
60 | async_error(io::Error::new(
61 | io::ErrorKind::PermissionDenied,
62 | "cannot traverse to a parent directory in {path}",
63 | ))
64 | };
65 | self.edits.push(Edit::ReplaceHTML(node.clone(), file));
66 | }
67 | // Pseudo-comments can also appear in element attributes. These are
68 | // not parsed as HTML, so we simply want to read them into memory so
69 | // they can be replaced.
70 | NodeData::Element { ref attrs, .. } => {
71 | for Attribute {
72 | ref name,
73 | ref value,
74 | } in attrs.borrow().iter()
75 | {
76 | if value.starts_with("") {
77 | let path = Path::new(value[16..value.len() - 3].trim());
78 | let file_contents = if is_safe_path(path) {
79 | read_to_str_tendril(self.path.join(path))
80 | } else {
81 | async_error(io::Error::new(
82 | io::ErrorKind::PermissionDenied,
83 | "cannot traverse to a parent directory in {path}",
84 | ))
85 | };
86 | self.edits.push(Edit::ReplaceAttr(
87 | node.clone(),
88 | name.clone(),
89 | file_contents,
90 | ));
91 | }
92 | }
93 | }
94 | // and which contain EXAMPLE also need to be
95 | // replaced, but as plain text. These are loaded from the "examples"
96 | // directory instead.
97 | NodeData::Text { ref contents } => {
98 | let borrowed_contents = contents.borrow();
99 | let text = borrowed_contents.trim();
100 | if !text.starts_with("EXAMPLE ") {
101 | return;
102 | }
103 | const PRE: LocalName = local_name!("pre");
104 | const CODE: LocalName = local_name!("code");
105 | let has_suitable_parent = node.parent_node().map_or(false, |p| {
106 | p.is_html_element(&PRE)
107 | || (p.is_html_element(&CODE)
108 | && p.parent_node().map_or(false, |p2| p2.is_html_element(&PRE)))
109 | });
110 | if has_suitable_parent {
111 | let path = Path::new(text[8..].trim());
112 | let file_contents = if is_safe_path(path) {
113 | read_to_str_tendril(self.example_path.join(path))
114 | } else {
115 | async_error(io::Error::new(
116 | io::ErrorKind::PermissionDenied,
117 | "cannot traverse to a parent directory in {path}",
118 | ))
119 | };
120 | self.edits
121 | .push(Edit::ReplaceText(node.clone(), file_contents))
122 | }
123 | }
124 | _ => (),
125 | }
126 | }
127 |
128 | /// Applies the required replacements, in order.
129 | pub async fn apply(self) -> io::Result<()> {
130 | for edit in self.edits {
131 | match edit {
132 | // When parsing HTML, we need the context it's in so that the
133 | // context-sensitive parsing behavior works correctly.
134 | Edit::ReplaceHTML(node, replacement) => {
135 | let context = match node.parent_node() {
136 | Some(n) => n,
137 | _ => continue,
138 | };
139 | let file: File = replacement.await??;
140 | let new_children = parser::parse_fragment_async(file, &context).await?;
141 | node.replace_with(new_children);
142 | }
143 | Edit::ReplaceAttr(element, ref attr, replacement) => {
144 | element.set_attribute(attr, replacement.await??.into());
145 | }
146 | Edit::ReplaceText(element, replacement) => match element.data {
147 | NodeData::Text { ref contents } => {
148 | contents.replace(replacement.await??.into());
149 | }
150 | _ => panic!("not text"),
151 | },
152 | }
153 | }
154 | Ok(())
155 | }
156 | }
157 |
158 | #[cfg(test)]
159 | mod tests {
160 | use super::*;
161 | use crate::dom_utils;
162 | use crate::parser::{parse_document_async, tests::serialize_for_test};
163 | use tempfile::TempDir;
164 |
165 | #[tokio::test]
166 | async fn test_replace_boilerplate_comment() -> io::Result<()> {
167 | let boilerplate_dir = TempDir::new()?;
168 | tokio::fs::write(
169 | boilerplate_dir.path().join("languages"),
170 | "| en | English",
171 | )
172 | .await?;
173 | let document = parse_document_async(
174 | "".as_bytes(),
175 | )
176 | .await?;
177 | let mut proc = Processor::new(boilerplate_dir.path(), Path::new("."));
178 | dom_utils::scan_dom(&document, &mut |h| proc.visit(h));
179 | proc.apply().await?;
180 | assert_eq!(
181 | serialize_for_test(&[document]),
182 | "");
183 | Ok(())
184 | }
185 |
186 | #[tokio::test]
187 | async fn test_replace_boilerplate_attribute() -> io::Result<()> {
188 | let boilerplate_dir = TempDir::new()?;
189 | tokio::fs::write(
190 | boilerplate_dir.path().join("data.url"),
191 | "data:text/html,Hello, world!",
192 | )
193 | .await?;
194 | let document = parse_document_async(
195 | "\">hello".as_bytes(),
196 | )
197 | .await?;
198 | let mut proc = Processor::new(boilerplate_dir.path(), Path::new("."));
199 | dom_utils::scan_dom(&document, &mut |h| proc.visit(h));
200 | proc.apply().await?;
201 | assert_eq!(
202 | serialize_for_test(&[document]),
203 | "hello");
204 | Ok(())
205 | }
206 |
207 | #[tokio::test]
208 | async fn test_replace_example() -> io::Result<()> {
209 | let example_dir = TempDir::new()?;
210 | tokio::fs::write(example_dir.path().join("ex1"), "first").await?;
211 | tokio::fs::write(example_dir.path().join("ex2"), "second").await?;
212 | tokio::fs::write(example_dir.path().join("ignored"), "bad").await?;
213 | let document =
214 | parse_document_async("EXAMPLE ex1 \nEXAMPLE ex2
EXAMPLE ignored ".as_bytes())
215 | .await?;
216 | let mut proc = Processor::new(Path::new("."), example_dir.path());
217 | dom_utils::scan_dom(&document, &mut |h| proc.visit(h));
218 | proc.apply().await?;
219 | assert_eq!(
220 | serialize_for_test(&[document]),
221 | "first second
EXAMPLE ignored " );
222 | Ok(())
223 | }
224 |
225 | #[tokio::test]
226 | async fn test_errors_unsafe_paths() -> io::Result<()> {
227 | let bad_path_examples = [
228 | "",
229 | "\"> ",
230 | "EXAMPLE ../foo ",
231 | ];
232 | for example in bad_path_examples {
233 | let document = parse_document_async(example.as_bytes()).await?;
234 | let mut proc = Processor::new(Path::new("."), Path::new("."));
235 | dom_utils::scan_dom(&document, &mut |h| proc.visit(h));
236 | let result = proc.apply().await;
237 | assert!(matches!(result, Err(e) if e.kind() == io::ErrorKind::PermissionDenied));
238 | }
239 | Ok(())
240 | }
241 | }
242 |
--------------------------------------------------------------------------------
/src/dom_utils.rs:
--------------------------------------------------------------------------------
1 | use std::cell::RefCell;
2 | use std::rc::Rc;
3 |
4 | use html5ever::tendril::StrTendril;
5 | use html5ever::{local_name, namespace_url, ns, Attribute, LocalName, QualName};
6 | use markup5ever_rcdom::{Handle, Node, NodeData};
7 |
8 | /// Extensions to the DOM interface to make manipulation more ergonimc.
9 | pub trait NodeHandleExt {
10 | /// Returns a handle to the parent node, if there is one.
11 | fn parent_node(&self) -> Option
12 | where
13 | Self: Sized;
14 |
15 | /// Gets an attribute on the element, or None if absent or not an element.
16 | fn get_attribute(&self, name: &QualName) -> Option;
17 |
18 | /// Returns whether the node has the named attribute.
19 | fn has_attribute(&self, name: &QualName) -> bool {
20 | self.get_attribute(name).is_some()
21 | }
22 |
23 | /// Returns true if the attribute exists and has the value mentioned.
24 | fn attribute_is(&self, name: &QualName, expected: &str) -> bool {
25 | self.get_attribute(name).as_deref() == Some(expected)
26 | }
27 |
28 | /// Sets an attribute on the element. Must be an element.
29 | fn set_attribute(&self, name: &QualName, value: StrTendril);
30 |
31 | /// Returns true if the node is an element.
32 | fn is_element(&self) -> bool;
33 |
34 | /// Returns true if the node is an HTML element with the given tag name.
35 | fn is_html_element(&self, tag_name: &LocalName) -> bool;
36 |
37 | /// Returns true if the node is an element with the given class.
38 | fn has_class(&self, class: &str) -> bool;
39 |
40 | /// Returns true if the node is an element with the given ID.
41 | fn has_id(&self, id: &str) -> bool {
42 | const ID: QualName = QualName {
43 | prefix: None,
44 | ns: ns!(),
45 | local: local_name!("id"),
46 | };
47 | self.attribute_is(&ID, id)
48 | }
49 |
50 | /// If this is a text node, returns its text.
51 | fn node_text(&self) -> Option;
52 |
53 | /// Concatenate the text of the node and its descendants.
54 | fn text_content(&self) -> StrTendril;
55 |
56 | /// True if any child matches the predicate.
57 | fn any_child(&self, f: impl Fn(&Self) -> bool) -> bool;
58 |
59 | /// Appends children (without checking node type).
60 | fn append_children(&self, children: impl Iterator- );
61 |
62 | /// Inserts children before the specified child.
63 | fn insert_children_before(&self, existing: &Self, new: impl Iterator
- );
64 |
65 | /// Removes the node from its parent and replaces it with the nodes provided.
66 | /// Does nothing if the node has no parent.
67 | fn replace_with(&self, replacements: Vec)
68 | where
69 | Self: Sized;
70 |
71 | /// Clones the node and its entire subtree (including template contents).
72 | fn deep_clone(&self) -> Self;
73 |
74 | /// Create a new element, with the given children.
75 | fn create_element(name: LocalName) -> ElementBuilder
76 | where
77 | Self: Sized;
78 |
79 | /// Create a new text node.
80 | fn create_text_node(text: impl Into) -> Self
81 | where
82 | Self: Sized;
83 | }
84 |
85 | /// Convenience helper for constructing nodes. Use like:
86 | /// Handle::create_element(local_name!("a"))
87 | /// .attribute(&local_name!("href"), "/")
88 | /// .text("Home")
89 | /// .build()
90 | pub struct ElementBuilder {
91 | element: T,
92 | }
93 |
94 | impl ElementBuilder {
95 | pub fn attribute(self, name: &LocalName, value: impl Into) -> Self {
96 | self.element
97 | .set_attribute(&QualName::new(None, ns!(), name.clone()), value.into());
98 | self
99 | }
100 |
101 | pub fn children(self, children: impl Iterator
- ) -> Self {
102 | self.element.append_children(children);
103 | self
104 | }
105 |
106 | pub fn child(self, child: T) -> Self {
107 | self.children(std::iter::once(child))
108 | }
109 |
110 | pub fn text(self, text: impl Into) -> Self {
111 | self.child(::create_text_node(text))
112 | }
113 |
114 | pub fn build(self) -> T {
115 | self.element
116 | }
117 | }
118 |
119 | /// Recursively visits every DOM node (preorder). Template contents are visited
120 | /// after children, but there are seldom both.
121 | pub fn scan_dom(handle: &Handle, f: &mut F) {
122 | f(handle);
123 |
124 | for child in handle.children.borrow().iter() {
125 | scan_dom(child, f);
126 | }
127 |
128 | if let NodeData::Element {
129 | template_contents: ref tc,
130 | ..
131 | } = handle.data
132 | {
133 | if let Some(ref tc_handle) = *tc.borrow() {
134 | scan_dom(tc_handle, f);
135 | }
136 | }
137 | }
138 |
139 | /// Given a element, find the corresponding elements.
140 | ///
141 | /// This is more subtle than you might immediately think, because there can be
142 | /// multiple listing various terms with one or more common
143 | /// definitions. We need to find the in the child list, and then skip it
144 | /// and any other , before providing the that follow.
145 | pub fn dt_descriptions(dt: &Handle) -> Vec {
146 | assert!(dt.is_html_element(&local_name!("dt")));
147 | if let Some(ref dl) = dt
148 | .parent_node()
149 | .filter(|n| n.is_html_element(&local_name!("dl")))
150 | {
151 | dl.children
152 | .borrow()
153 | .iter()
154 | .filter(|n| n.is_element())
155 | .skip_while(|n| !Rc::ptr_eq(n, dt))
156 | .skip_while(|n| n.is_html_element(&local_name!("dt")))
157 | .take_while(|n| n.is_html_element(&local_name!("dd")))
158 | .cloned()
159 | .collect()
160 | } else {
161 | Vec::new()
162 | }
163 | }
164 |
165 | /// Returns the heading level (from 1 to 6) that the
|
|