diff --git a/src/base/encoding.rs b/src/base/encoding.rs index b99d4a02..34878f0f 100644 --- a/src/base/encoding.rs +++ b/src/base/encoding.rs @@ -4,6 +4,11 @@ use std::cell::Cell; use std::ops::Deref; use std::rc::Rc; +/// A charset encoding that can be shared and modified. +/// +/// This is, for instance, used to adapt the charset dynamically in a [crate::HtmlRewriter] if it +/// encounters a `meta` tag that specifies the charset (that behavior is dependent on +/// [crate::Settings::adjust_charset_on_meta_tag]). #[derive(Clone)] pub struct SharedEncoding { encoding: Rc>, diff --git a/src/lib.rs b/src/lib.rs index e81e5ab4..038cfaa3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -17,6 +17,9 @@ //! [`HtmlRewriter`]: struct.HtmlRewriter.html //! [`rewrite_str`]: fn.rewrite_str.html +// TODO Uncomment this once we have all items documented. +// #![cfg_attr(not(any(feature = "integration_test", test)), warn(missing_docs))] + #[macro_use] mod base; @@ -34,8 +37,9 @@ mod transform_stream; use cfg_if::cfg_if; pub use self::rewriter::{ - rewrite_str, AsciiCompatibleEncoding, DocumentContentHandlers, ElementContentHandlers, - HtmlRewriter, MemorySettings, RewriteStrSettings, Settings, + rewrite_str, AsciiCompatibleEncoding, CommentHandler, DoctypeHandler, DocumentContentHandlers, + ElementContentHandlers, ElementHandler, EndHandler, EndTagHandler, HandlerResult, HtmlRewriter, + MemorySettings, RewriteStrSettings, Settings, TextHandler, }; pub use self::selectors_vm::Selector; pub use self::transform_stream::OutputSink; @@ -165,7 +169,6 @@ cfg_if! { EndTag, Serialize, StartTag, Token, TokenCaptureFlags, Mutations }; - pub use self::base::Bytes; pub use self::memory::MemoryLimiter; pub use self::html::{LocalName, LocalNameHash, Tag, Namespace}; } else { diff --git a/src/rewritable_units/tokens/end_tag.rs b/src/rewritable_units/tokens/end_tag.rs index 1c46640c..e75989b9 100644 --- a/src/rewritable_units/tokens/end_tag.rs +++ b/src/rewritable_units/tokens/end_tag.rs @@ -48,16 +48,25 @@ impl<'i> EndTag<'i> { self.set_name(Bytes::from_string(name, self.encoding)) } + /// Inserts `content` before the end tag. + /// + /// Consequent calls to the method append `content` to the previously inserted content. #[inline] pub fn before(&mut self, content: &str, content_type: ContentType) { self.mutations.before(content, content_type); } + /// Inserts `content` after the end tag. + /// + /// Consequent calls to the method prepend `content` to the previously inserted content. #[inline] pub fn after(&mut self, content: &str, content_type: ContentType) { self.mutations.after(content, content_type); } + /// Replaces the end tag with `content`. + /// + /// Consequent calls to the method overwrite previous replacement content. #[inline] pub fn replace(&mut self, content: &str, content_type: ContentType) { self.mutations.replace(content, content_type); diff --git a/src/rewritable_units/tokens/start_tag.rs b/src/rewritable_units/tokens/start_tag.rs index d4882b72..aa297c33 100644 --- a/src/rewritable_units/tokens/start_tag.rs +++ b/src/rewritable_units/tokens/start_tag.rs @@ -89,16 +89,25 @@ impl<'i> StartTag<'i> { self.self_closing } + /// Inserts `content` before the start tag. + /// + /// Consequent calls to the method append `content` to the previously inserted content. #[inline] pub fn before(&mut self, content: &str, content_type: ContentType) { self.mutations.before(content, content_type); } + /// Inserts `content` after the start tag. + /// + /// Consequent calls to the method prepend `content` to the previously inserted content. #[inline] pub fn after(&mut self, content: &str, content_type: ContentType) { self.mutations.after(content, content_type); } + /// Replaces the start tag with `content`. + /// + /// Consequent calls to the method overwrite previous replacement content. #[inline] pub fn replace(&mut self, content: &str, content_type: ContentType) { self.mutations.replace(content, content_type); diff --git a/src/rewritable_units/tokens/text_chunk.rs b/src/rewritable_units/tokens/text_chunk.rs index fd01228e..7d24f332 100644 --- a/src/rewritable_units/tokens/text_chunk.rs +++ b/src/rewritable_units/tokens/text_chunk.rs @@ -335,7 +335,11 @@ mod tests { use super::super::Token; let encoding = Encoding::for_label_no_replacement("utf-8".as_bytes()).unwrap(); - let Token::TextChunk(mut chunk) = TextChunk::new_token("original text", TextType::PlainText, true, encoding) else { unreachable!() }; + let Token::TextChunk(mut chunk) = + TextChunk::new_token("original text", TextType::PlainText, true, encoding) + else { + unreachable!() + }; assert_eq!(chunk.as_str(), "original text"); chunk.set_str("hello".to_owned()); diff --git a/src/rewriter/settings.rs b/src/rewriter/settings.rs index 090aaabb..dc2df0c5 100644 --- a/src/rewriter/settings.rs +++ b/src/rewriter/settings.rs @@ -5,20 +5,32 @@ use super::AsciiCompatibleEncoding; use std::borrow::Cow; use std::error::Error; -pub(crate) type HandlerResult = Result<(), Box>; +/// The result of a handler. +pub type HandlerResult = Result<(), Box>; +/// Handler for the [document type declaration]. +/// +/// [document type declaration]: https://developer.mozilla.org/en-US/docs/Glossary/Doctype pub type DoctypeHandler<'h> = Box HandlerResult + 'h>; +/// Handler for HTML comments. pub type CommentHandler<'h> = Box HandlerResult + 'h>; +/// Handler for text chunks present the HTML. pub type TextHandler<'h> = Box HandlerResult + 'h>; +/// Handler for elements matched by a selector. pub type ElementHandler<'h> = Box HandlerResult + 'h>; +/// Handler for an end tag. pub type EndTagHandler<'h> = Box HandlerResult + 'h>; +/// Handler for the document end, which is called after the last chunk is processed. pub type EndHandler<'h> = Box HandlerResult + 'h>; /// Specifies element content handlers associated with a selector. #[derive(Default)] pub struct ElementContentHandlers<'h> { - pub(super) element: Option>, - pub(super) comments: Option>, - pub(super) text: Option>, + /// Element handler. See [ElementHandler]. + pub element: Option>, + /// Comment handler. See [CommentHandler]. + pub comments: Option>, + /// Text handler. See [TextHandler]. + pub text: Option>, } impl<'h> ElementContentHandlers<'h> { @@ -64,10 +76,14 @@ impl<'h> ElementContentHandlers<'h> { /// ``` #[derive(Default)] pub struct DocumentContentHandlers<'h> { - pub(super) doctype: Option>, - pub(super) comments: Option>, - pub(super) text: Option>, - pub(super) end: Option>, + /// Doctype handler. See [DoctypeHandler]. + pub doctype: Option>, + /// Comment handler. See [CommentHandler]. + pub comments: Option>, + /// Text handler. See [TextHandler]. + pub text: Option>, + /// End handler. See [EndHandler]. + pub end: Option>, } impl<'h> DocumentContentHandlers<'h> { diff --git a/src/selectors_vm/compiler.rs b/src/selectors_vm/compiler.rs index 12065ec9..c1558a2b 100644 --- a/src/selectors_vm/compiler.rs +++ b/src/selectors_vm/compiler.rs @@ -989,27 +989,27 @@ mod tests { } { - let (jumps, hereditary_jumps) = exec!("
", program.entry_points, vec![]); + let (jumps, hereditary_jumps) = exec!("
", program.entry_points, []); assert_eq!(jumps.len(), 1); assert_eq!(hereditary_jumps.len(), 1); { - let (jumps, hereditary_jumps) = exec!("", jumps[0], vec![0, 1]); + let (jumps, hereditary_jumps) = exec!("", jumps[0], [0, 1]); assert_eq!(jumps.len(), 0); assert_eq!(hereditary_jumps.len(), 0); } { - let (jumps, hereditary_jumps) = exec!("", jumps[0], vec![1]); + let (jumps, hereditary_jumps) = exec!("", jumps[0], [1]); assert_eq!(jumps.len(), 0); assert_eq!(hereditary_jumps.len(), 0); } { - let (jumps, hereditary_jumps) = exec!("

", hereditary_jumps[0], vec![3]); + let (jumps, hereditary_jumps) = exec!("

", hereditary_jumps[0], [3]); assert_eq!(jumps.len(), 0); assert_eq!(hereditary_jumps.len(), 0); @@ -1017,27 +1017,26 @@ mod tests { } { - let (jumps, hereditary_jumps) = exec!("
", program.entry_points, vec![]); + let (jumps, hereditary_jumps) = exec!("
", program.entry_points, []); assert_eq!(jumps.len(), 1); assert_eq!(hereditary_jumps.len(), 2); } { - let (jumps, hereditary_jumps) = exec!("", program.entry_points, vec![]); + let (jumps, hereditary_jumps) = exec!("", program.entry_points, []); assert_eq!(jumps.len(), 0); assert_eq!(hereditary_jumps.len(), 1); { - let (jumps, hereditary_jumps) = - exec!("", hereditary_jumps[0], vec![]); + let (jumps, hereditary_jumps) = exec!("
", hereditary_jumps[0], []); assert_eq!(jumps.len(), 1); assert_eq!(hereditary_jumps.len(), 0); { - let (jumps, hereditary_jumps) = exec!("", jumps[0], vec![4]); + let (jumps, hereditary_jumps) = exec!("", jumps[0], [4]); assert_eq!(jumps.len(), 0); assert_eq!(hereditary_jumps.len(), 0);