Add new minimal_escape function to escape only strictly necessary characters

Author: Mingun

Changelog.md

@@ -22,6 +22,8 @@ configuration is serializable.
   direct access to fields of config using `reader.config_mut().<...>`.
 - [#684]: Added a method `Config::enable_all_checks` to turn on or off all
   well-formedness checks.
+- [#362]: Added `escape::minimal_escape()` which escapes only `&` and `<`.
+- [#362]: Added `BytesCData::minimal_escape()` which escapes only `&` and `<`.
 
 ### Bug Fixes
 

src/escapei.rs

@@ -71,6 +71,16 @@ impl std::error::Error for EscapeError {}
 /// | `&`       | `&`
 /// | `'`       | `'`
 /// | `"`       | `"`
+///
+/// This function performs following replacements:
+///
+/// | Character | Replacement
+/// |-----------|------------
+/// | `<`       | `&lt;`
+/// | `>`       | `&gt;`
+/// | `&`       | `&amp;`
+/// | `'`       | `&apos;`
+/// | `"`       | `&quot;`
 pub fn escape(raw: &str) -> Cow<str> {
     _escape(raw, |ch| matches!(ch, b'<' | b'>' | b'&' | b'\'' | b'\"'))
 }
@@ -88,10 +98,35 @@ pub fn escape(raw: &str) -> Cow<str> {
 /// | `<`       | `&lt;`
 /// | `>`       | `&gt;`
 /// | `&`       | `&amp;`
+///
+/// This function performs following replacements:
+///
+/// | Character | Replacement
+/// |-----------|------------
+/// | `<`       | `&lt;`
+/// | `>`       | `&gt;`
+/// | `&`       | `&amp;`
 pub fn partial_escape(raw: &str) -> Cow<str> {
     _escape(raw, |ch| matches!(ch, b'<' | b'>' | b'&'))
 }
 
+/// XML standard [requires] that only `<` and `&` was escaped in text content or
+/// attribute value. All other characters not necessary to be escaped, although
+/// for compatibility with SGML they also should be escaped. Practically, escaping
+/// only those characters is enough.
+///
+/// This function performs following replacements:
+///
+/// | Character | Replacement
+/// |-----------|------------
+/// | `<`       | `&lt;`
+/// | `&`       | `&amp;`
+///
+/// [requires]: https://www.w3.org/TR/xml11/#syntax
+pub fn minimal_escape(raw: &str) -> Cow<str> {
+    _escape(raw, |ch| matches!(ch, b'<' | b'&'))
+}
+
 /// Escapes an `&str` and replaces a subset of xml special characters (`<`, `>`,
 /// `&`, `'`, `"`) with their corresponding xml escaped value.
 pub(crate) fn _escape<F: Fn(u8) -> bool>(raw: &str, escape_chars: F) -> Cow<str> {
@@ -1788,6 +1823,7 @@ fn test_escape() {
     assert_eq!(unchanged, Cow::Borrowed("test"));
     assert!(matches!(unchanged, Cow::Borrowed(_)));
 
+    assert_eq!(escape("<&\"'>"), "&lt;&amp;&quot;&apos;&gt;");
     assert_eq!(escape("<test>"), "&lt;test&gt;");
     assert_eq!(escape("\"a\"bc"), "&quot;a&quot;bc");
     assert_eq!(escape("\"a\"b&c"), "&quot;a&quot;b&amp;c");
@@ -1806,6 +1842,7 @@ fn test_partial_escape() {
     assert_eq!(unchanged, Cow::Borrowed("test"));
     assert!(matches!(unchanged, Cow::Borrowed(_)));
 
+    assert_eq!(partial_escape("<&\"'>"), "&lt;&amp;\"'&gt;");
     assert_eq!(partial_escape("<test>"), "&lt;test&gt;");
     assert_eq!(partial_escape("\"a\"bc"), "\"a\"bc");
     assert_eq!(partial_escape("\"a\"b&c"), "\"a\"b&amp;c");
@@ -1814,3 +1851,16 @@ fn test_partial_escape() {
         "prefix_\"a\"b&amp;&lt;&gt;c"
     );
 }
+
+#[test]
+fn test_minimal_escape() {
+    assert_eq!(minimal_escape("test"), Cow::Borrowed("test"));
+    assert_eq!(minimal_escape("<&\"'>"), "&lt;&amp;\"'>");
+    assert_eq!(minimal_escape("<test>"), "&lt;test>");
+    assert_eq!(minimal_escape("\"a\"bc"), "\"a\"bc");
+    assert_eq!(minimal_escape("\"a\"b&c"), "\"a\"b&amp;c");
+    assert_eq!(
+        minimal_escape("prefix_\"a\"b&<>c"),
+        "prefix_\"a\"b&amp;&lt;>c"
+    );
+}

src/events/mod.rs

@@ -46,7 +46,7 @@ use std::str::from_utf8;
 
 use crate::encoding::Decoder;
 use crate::errors::{Error, IllFormedError, Result};
-use crate::escape::{escape, partial_escape, unescape_with};
+use crate::escape::{escape, minimal_escape, partial_escape, unescape_with};
 use crate::name::{LocalName, QName};
 use crate::reader::is_whitespace;
 use crate::utils::write_cow_string;
@@ -913,6 +913,30 @@ impl<'a> BytesCData<'a> {
         ))
     }
 
+    /// Converts this CDATA content to an escaped version, that can be written
+    /// as an usual text in XML. This method escapes only those characters that
+    /// must be escaped according to the [specification].
+    ///
+    /// This function performs following replacements:
+    ///
+    /// | Character | Replacement
+    /// |-----------|------------
+    /// | `<`       | `&lt;`
+    /// | `&`       | `&amp;`
+    ///
+    /// [specification]: https://www.w3.org/TR/xml11/#syntax
+    pub fn minimal_escape(self) -> Result<BytesText<'a>> {
+        let decoded = self.decode()?;
+        Ok(BytesText::wrap(
+            match minimal_escape(&decoded) {
+                // Because result is borrowed, no replacements was done and we can use original content
+                Cow::Borrowed(_) => self.content,
+                Cow::Owned(escaped) => Cow::Owned(escaped.into_bytes()),
+            },
+            Decoder::utf8(),
+        ))
+    }
+
     /// Gets content of this text buffer in the specified encoding
     pub(crate) fn decode(&self) -> Result<Cow<'a, str>> {
         Ok(match &self.content {

src/lib.rs

@@ -58,7 +58,9 @@ pub mod errors;
 mod escapei;
 pub mod escape {
     //! Manage xml character escapes
-    pub use crate::escapei::{escape, partial_escape, unescape, unescape_with, EscapeError};
+    pub use crate::escapei::{
+        escape, minimal_escape, partial_escape, unescape, unescape_with, EscapeError,
+    };
 }
 pub mod events;
 pub mod name;