From 44a7659d1ce018c27ae1f7e7913884bdedf72d71 Mon Sep 17 00:00:00 2001 From: Ivan Nikulin Date: Wed, 13 Sep 2023 19:39:57 +0100 Subject: [PATCH] Add missing docs + release 1.2.0 (#196) * Add missing docs for public API. Make StartTag::encoding non-public * Release 1.2.0 --- CHANGELOG.md | 6 ++++++ Cargo.toml | 2 +- src/html/text_type.rs | 3 +++ src/lib.rs | 3 +-- src/rewritable_units/element.rs | 2 +- src/rewritable_units/tokens/end_tag.rs | 5 +++++ src/rewritable_units/tokens/start_tag.rs | 15 +++++++++++++++ src/rewriter/mod.rs | 1 + src/rewriter/settings.rs | 10 ++++++++++ 9 files changed, 43 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 77c877cd..f6e7bf05 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## v1.2.0 + +- Expose `is_self_closing` and `can_have_content` in C api. +- Make `ElementContentHandlers` and `DocumentContentHandlers` fields public. +- Add missing docs to public API. + ## v1.1.1 ### Fixed diff --git a/Cargo.toml b/Cargo.toml index 6b081fb3..c72197d7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "lol_html" -version = "1.1.1" +version = "1.2.0" authors = ["Ivan Nikulin "] license = "BSD-3-Clause" description = "Streaming HTML rewriter/parser with CSS selector-based API" diff --git a/src/html/text_type.rs b/src/html/text_type.rs index c2ea1937..cfa826d8 100644 --- a/src/html/text_type.rs +++ b/src/html/text_type.rs @@ -37,6 +37,9 @@ pub enum TextType { } impl TextType { + /// Returns `true` if the text type allows [HTML entities]. + /// + /// [HTML entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity #[inline] pub fn allows_html_entities(self) -> bool { self == TextType::Data || self == TextType::RCData diff --git a/src/lib.rs b/src/lib.rs index 038cfaa3..084b83ce 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -17,8 +17,7 @@ //! [`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))] +#![cfg_attr(not(any(feature = "integration_test", test)), warn(missing_docs))] #[macro_use] mod base; diff --git a/src/rewritable_units/element.rs b/src/rewritable_units/element.rs index 977295c2..ed3bb295 100644 --- a/src/rewritable_units/element.rs +++ b/src/rewritable_units/element.rs @@ -179,7 +179,7 @@ impl<'r, 't> Element<'r, 't> { /// Sets `value` of element's attribute with `name`. /// - /// If element doesn't have an attribute with the `name`, method adds new attribute + /// If element doesn't have an attribute with the `name`, method adds a new attribute /// to the element with `name` and `value`. #[inline] pub fn set_attribute(&mut self, name: &str, value: &str) -> Result<(), AttributeNameError> { diff --git a/src/rewritable_units/tokens/end_tag.rs b/src/rewritable_units/tokens/end_tag.rs index e75989b9..48bd9acf 100644 --- a/src/rewritable_units/tokens/end_tag.rs +++ b/src/rewritable_units/tokens/end_tag.rs @@ -4,6 +4,9 @@ use crate::rewritable_units::ContentType; use encoding_rs::Encoding; use std::fmt::{self, Debug}; +/// An HTML end tag rewritable unit. +/// +/// Exposes API for examination and modification of a parsed HTML end tag. pub struct EndTag<'i> { name: Bytes<'i>, raw: Option>, @@ -37,12 +40,14 @@ impl<'i> EndTag<'i> { self.name.as_string(self.encoding) } + /// Sets the name of the tag. #[inline] pub fn set_name(&mut self, name: Bytes<'static>) { self.name = name; self.raw = None; } + /// Sets the name of the tag by encoding the given string. #[inline] pub fn set_name_str(&mut self, name: String) { self.set_name(Bytes::from_string(name, self.encoding)) diff --git a/src/rewritable_units/tokens/start_tag.rs b/src/rewritable_units/tokens/start_tag.rs index aa297c33..f36c0b6f 100644 --- a/src/rewritable_units/tokens/start_tag.rs +++ b/src/rewritable_units/tokens/start_tag.rs @@ -6,6 +6,9 @@ use crate::rewritable_units::ContentType; use encoding_rs::Encoding; use std::fmt::{self, Debug}; +/// An HTML start tag rewritable unit. +/// +/// Exposes API for examination and modification of a parsed HTML start tag. pub struct StartTag<'i> { name: Bytes<'i>, attributes: Attributes<'i>, @@ -37,6 +40,7 @@ impl<'i> StartTag<'i> { } #[inline] + #[doc(hidden)] pub fn encoding(&self) -> &'static Encoding { self.encoding } @@ -53,22 +57,31 @@ impl<'i> StartTag<'i> { self.name.as_string(self.encoding) } + /// Sets the name of the tag. #[inline] pub fn set_name(&mut self, name: Bytes<'static>) { self.name = name; self.raw = None; } + /// Returns the [namespace URI] of the tag's element. + /// + /// [namespace URI]: https://developer.mozilla.org/en-US/docs/Web/API/Element/namespaceURI #[inline] pub fn namespace_uri(&self) -> &'static str { self.ns.uri() } + /// Returns an immutable collection of tag's attributes. #[inline] pub fn attributes(&self) -> &[Attribute<'i>] { &self.attributes } + /// Sets `value` of tag's attribute with `name`. + /// + /// If tag doesn't have an attribute with the `name`, method adds a new attribute + /// to the tag with `name` and `value`. #[inline] pub fn set_attribute(&mut self, name: &str, value: &str) -> Result<(), AttributeNameError> { self.attributes.set_attribute(name, value, self.encoding)?; @@ -77,6 +90,7 @@ impl<'i> StartTag<'i> { Ok(()) } + /// Removes an attribute with the `name` if it is present. #[inline] pub fn remove_attribute(&mut self, name: &str) { if self.attributes.remove_attribute(name) { @@ -84,6 +98,7 @@ impl<'i> StartTag<'i> { } } + /// Whether the tag is explicitly self-closing, e.g. ``. #[inline] pub fn self_closing(&self) -> bool { self.self_closing diff --git a/src/rewriter/mod.rs b/src/rewriter/mod.rs index 9e4d11dc..0cb733b8 100644 --- a/src/rewriter/mod.rs +++ b/src/rewriter/mod.rs @@ -45,6 +45,7 @@ impl AsciiCompatibleEncoding { .and_then(AsciiCompatibleEncoding::new) } + /// Returns the most commonly used UTF-8 encoding. pub fn utf_8() -> AsciiCompatibleEncoding { Self(encoding_rs::UTF_8) } diff --git a/src/rewriter/settings.rs b/src/rewriter/settings.rs index dc2df0c5..89d1cf55 100644 --- a/src/rewriter/settings.rs +++ b/src/rewriter/settings.rs @@ -533,6 +533,11 @@ pub struct Settings<'h, 's> { /// `true` when constructed with `Settings::default()`. pub strict: bool, + /// If enabled the rewriter enables support for [Edge Side Includes] tags, treating them as + /// [void elements] and allowing them to be replaced with desired content. + /// + /// [Edge Side Includes]: https://www.w3.org/TR/esi-lang/ + /// [void elements]: https://developer.mozilla.org/en-US/docs/Glossary/Void_element pub enable_esi_tags: bool, /// If enabled the rewriter will dynamically change the charset when it encounters a `meta` tag @@ -683,6 +688,11 @@ pub struct RewriteStrSettings<'h, 's> { /// `true` when constructed with `Settings::default()`. pub strict: bool, + /// If enabled the rewriter enables support for [Edge Side Includes] tags, treating them as + /// [void elements] and allowing them to be replaced with desired content. + /// + /// [Edge Side Includes]: https://www.w3.org/TR/esi-lang/ + /// [void elements]: https://developer.mozilla.org/en-US/docs/Glossary/Void_element pub enable_esi_tags: bool, }