1 // Copyright 2014-2017 The html5ever Project Developers. See the 2 // COPYRIGHT file at the top-level directory of this distribution. 3 // 4 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or 5 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license 6 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your 7 // option. This file may not be copied, modified, or distributed 8 // except according to those terms. 9 //! Traits for serializing elements. The serializer expects the data to be xml-like (with a name, 10 //! and optional children, attrs, text, comments, doctypes, and [processing instructions]). It uses 11 //! the visitor pattern, where the serializer and the serializable objects are decoupled and 12 //! implement their own traits. 13 //! 14 //! [processing instructions]: https://en.wikipedia.org/wiki/Processing_Instruction 15 16 use crate::QualName; 17 use std::io; 18 19 //§ serializing-html-fragments 20 /// Used as a parameter to `serialize`, telling it if we want to skip the parent. 21 #[derive(Clone, PartialEq)] 22 pub enum TraversalScope { 23 /// Include the parent node when serializing. 24 IncludeNode, 25 /// Only serialize the children of the node, treating any provided qualified name as the 26 /// parent while serializing. 27 /// 28 /// This is used in the implementation of [`html5ever::serialize::serialize`] 29 /// 30 /// [`html5ever::serialize::serialize`]: ../../html5ever/serialize/fn.serialize.html 31 ChildrenOnly(Option<QualName>), 32 } 33 34 /// Types that can be serialized (according to the xml-like scheme in `Serializer`) implement this 35 /// trait. 36 pub trait Serialize { 37 /// Take the serializer and call its methods to serialize this type. The type will dictate 38 /// which methods are called and with what parameters. serialize<S>(&self, serializer: &mut S, traversal_scope: TraversalScope) -> io::Result<()> where S: Serializer39 fn serialize<S>(&self, serializer: &mut S, traversal_scope: TraversalScope) -> io::Result<()> 40 where 41 S: Serializer; 42 } 43 44 /// Types that are capable of serializing implement this trait 45 pub trait Serializer { 46 /// Serialize the start of an element, for example `<div class="test">`. start_elem<'a, AttrIter>(&mut self, name: QualName, attrs: AttrIter) -> io::Result<()> where AttrIter: Iterator<Item = AttrRef<'a>>47 fn start_elem<'a, AttrIter>(&mut self, name: QualName, attrs: AttrIter) -> io::Result<()> 48 where 49 AttrIter: Iterator<Item = AttrRef<'a>>; 50 51 /// Serialize the end of an element, for example `</div>`. end_elem(&mut self, name: QualName) -> io::Result<()>52 fn end_elem(&mut self, name: QualName) -> io::Result<()>; 53 54 /// Serialize a plain text node. write_text(&mut self, text: &str) -> io::Result<()>55 fn write_text(&mut self, text: &str) -> io::Result<()>; 56 57 /// Serialize a comment node, for example `<!-- comment -->`. write_comment(&mut self, text: &str) -> io::Result<()>58 fn write_comment(&mut self, text: &str) -> io::Result<()>; 59 60 /// Serialize a doctype node, for example `<!doctype html>`. write_doctype(&mut self, name: &str) -> io::Result<()>61 fn write_doctype(&mut self, name: &str) -> io::Result<()>; 62 63 /// Serialize a processing instruction node, for example 64 /// `<?xml-stylesheet type="text/xsl" href="style.xsl"?>`. write_processing_instruction(&mut self, target: &str, data: &str) -> io::Result<()>65 fn write_processing_instruction(&mut self, target: &str, data: &str) -> io::Result<()>; 66 } 67 68 /// A type alias for an attribute name and value (e.g. the `class="test"` in `<div class="test">` 69 /// is represented as `(<QualName of type class>, "test")`. 70 /// 71 /// This is used in [`Serializer::start_elem`] where the value being serialized must supply an 72 /// iterator over the attributes for the current element 73 /// 74 /// [`Serializer::start_elem`]: trait.Serializer.html#tymethod.start_elem 75 pub type AttrRef<'a> = (&'a QualName, &'a str); 76