From 6abd001b5b2083ef73fc1472f71d897b568ebd70 Mon Sep 17 00:00:00 2001 From: Daniel Alley Date: Tue, 12 Jul 2022 11:32:43 -0400 Subject: [PATCH] Rename functions for consistency "unescape_and_decode" -> "decode_and_unescape" "*_with_custom_entities" -> "*escape_with" --- Changelog.md | 4 +++- examples/custom_entities.rs | 4 ++-- src/events/attributes.rs | 31 ++++++++++++++++--------------- src/events/mod.rs | 23 ++++++++++++----------- src/lib.rs | 2 +- src/reader.rs | 8 ++++---- tests/test.rs | 2 +- tests/unit_tests.rs | 2 +- 8 files changed, 40 insertions(+), 36 deletions(-) diff --git a/Changelog.md b/Changelog.md index 57ffabe7..a5b83307 100644 --- a/Changelog.md +++ b/Changelog.md @@ -111,7 +111,9 @@ - [#412]: Change `read_to_end*` and `read_text_into` to accept `QName` instead of `AsRef<[u8]>` - [#415]: Changed custom entity unescaping API to accept closures rather than a mapping of entity to replacement text. This avoids needing to allocate a map and provides the user with more flexibility. - +- [#415]: Renamed many functions following the pattern `unescape_and_decode*` to `decode_and_unescape*` + to better communicate their function. Renamed functions following the pattern `*_with_custom_entities` + to `decode_and_unescape_with` to be more consistent across the API. - [#416]: `BytesStart::to_borrowed` renamed to `BytesStart::borrow`, the same method added to all events diff --git a/examples/custom_entities.rs b/examples/custom_entities.rs index 4b698842..e82d2561 100644 --- a/examples/custom_entities.rs +++ b/examples/custom_entities.rs @@ -44,7 +44,7 @@ fn main() -> Result<(), Box> { .attributes() .map(|a| { a.unwrap() - .unescape_and_decode_value_with_custom_entities(&reader, |ent| { + .decode_and_unescape_value_with(&reader, |ent| { custom_entities.get(ent).map(|s| s.as_str()) }) .unwrap() @@ -57,7 +57,7 @@ fn main() -> Result<(), Box> { Ok(Event::Text(ref e)) => { println!( "text value: {}", - e.unescape_and_decode_with_custom_entities(&reader, |ent| custom_entities + e.decode_and_unescape_with(&reader, |ent| custom_entities .get(ent) .map(|s| s.as_str())) .unwrap() diff --git a/src/events/attributes.rs b/src/events/attributes.rs index e7790d00..0ef91215 100644 --- a/src/events/attributes.rs +++ b/src/events/attributes.rs @@ -14,11 +14,11 @@ use std::{borrow::Cow, ops::Range}; /// A struct representing a key/value XML attribute. /// /// Field `value` stores raw bytes, possibly containing escape-sequences. Most users will likely -/// want to access the value using one of the [`unescaped_value`] and [`unescape_and_decode_value`] +/// want to access the value using one of the [`unescaped_value`] and [`decode_and_unescape_value`] /// functions. /// /// [`unescaped_value`]: Self::unescaped_value -/// [`unescape_and_decode_value`]: Self::unescape_and_decode_value +/// [`decode_and_unescape_value`]: Self::decode_and_unescape_value #[derive(Clone, PartialEq)] pub struct Attribute<'a> { /// The key to uniquely define the attribute. @@ -37,16 +37,17 @@ impl<'a> Attribute<'a> { /// /// This will allocate if the value contains any escape sequences. /// - /// See also [`unescaped_value_with_custom_entities()`](Self::unescaped_value_with_custom_entities) + /// See also [`unescaped_value_with()`](Self::unescaped_value_with) pub fn unescaped_value(&self) -> XmlResult> { - self.unescaped_value_with_custom_entities(|_| None) + self.unescaped_value_with(|_| None) } /// Returns the unescaped value, using custom entities. /// /// This is normally the value you are interested in. Escape sequences such as `>` are /// replaced with their unescaped equivalents such as `>`. - /// Additional entities can be provided in `custom_entities`. + /// A fallback resolver for additional custom entities can be provided via + /// `resolve_entities`. /// /// This will allocate if the value contains any escape sequences. /// @@ -54,15 +55,15 @@ impl<'a> Attribute<'a> { /// /// # Pre-condition /// - /// The keys and values of `custom_entities`, if any, must be valid UTF-8. - pub fn unescaped_value_with_custom_entities<'s, 'entity>( + /// The implementation of `resolve_entity` is expected to operate over UTF-8 inputs. + pub fn unescaped_value_with<'s, 'entity>( &'s self, resolve_entity: impl Fn(&[u8]) -> Option<&'entity str>, ) -> XmlResult> { unescape_with(&*self.value, resolve_entity).map_err(Error::EscapeError) } - /// Decode then unescapes the value + /// Decodes then unescapes the value /// /// This allocates a `String` in all cases. For performance reasons it might be a better idea to /// instead use one of: @@ -72,25 +73,25 @@ impl<'a> Attribute<'a> { /// /// [`unescaped_value()`]: Self::unescaped_value /// [`Reader::decoder().decode()`]: crate::reader::Decoder::decode - pub fn unescape_and_decode_value(&self, reader: &Reader) -> XmlResult { - self.unescape_and_decode_value_with_custom_entities(reader, |_| None) + pub fn decode_and_unescape_value(&self, reader: &Reader) -> XmlResult { + self.decode_and_unescape_value_with(reader, |_| None) } - /// Decode then unescapes the value with custom entities + /// Decodes then unescapes the value with custom entities /// /// This allocates a `String` in all cases. For performance reasons it might be a better idea to /// instead use one of: /// /// * [`Reader::decoder().decode()`], as it only allocates when the decoding can't be performed otherwise. - /// * [`unescaped_value_with_custom_entities()`], as it doesn't allocate when no escape sequences are used. + /// * [`unescaped_value_with()`], as it doesn't allocate when no escape sequences are used. /// - /// [`unescaped_value_with_custom_entities()`]: Self::unescaped_value_with_custom_entities + /// [`unescaped_value_with()`]: Self::unescaped_value_with /// [`Reader::decoder().decode()`]: crate::reader::Decoder::decode /// /// # Pre-condition /// - /// The keys and values of `custom_entities`, if any, must be valid UTF-8. - pub fn unescape_and_decode_value_with_custom_entities<'entity, B>( + /// The implementation of `resolve_entity` is expected to operate over UTF-8 inputs. + pub fn decode_and_unescape_value_with<'entity, B>( &self, reader: &Reader, resolve_entity: impl Fn(&[u8]) -> Option<&'entity str>, diff --git a/src/events/mod.rs b/src/events/mod.rs index 46b8ee14..c461d88f 100644 --- a/src/events/mod.rs +++ b/src/events/mod.rs @@ -752,23 +752,24 @@ impl<'a> BytesText<'a> { /// Searches for '&' into content and try to escape the coded character if possible /// returns Malformed error with index within element if '&' is not followed by ';' /// - /// See also [`unescaped_with_custom_entities()`](Self::unescaped_with_custom_entities) + /// See also [`unescaped_with()`](Self::unescaped_with) pub fn unescaped(&self) -> Result> { - self.unescaped_with_custom_entities(|_| None) + self.unescaped_with(|_| None) } /// gets escaped content with custom entities /// /// Searches for '&' into content and try to escape the coded character if possible /// returns Malformed error with index within element if '&' is not followed by ';' - /// Additional entities can be provided in `custom_entities`. + /// A fallback resolver for additional custom entities can be provided via + /// `resolve_entities`. /// /// # Pre-condition /// /// The implementation of `resolve_entity` is expected to operate over UTF-8 inputs. /// /// See also [`unescaped()`](Self::unescaped) - pub fn unescaped_with_custom_entities<'s, 'entity>( + pub fn unescaped_with<'s, 'entity>( &'s self, resolve_entity: impl Fn(&[u8]) -> Option<&'entity str>, ) -> Result> { @@ -779,23 +780,23 @@ impl<'a> BytesText<'a> { /// /// for performance reasons (could avoid allocating a `String`), /// it might be wiser to manually use - /// 1. BytesText::unescaped() - /// 2. Reader::decode(...) - pub fn unescape_and_decode(&self, reader: &Reader) -> Result { - self.unescape_and_decode_with_custom_entities(reader, |_| None) + /// 1. Reader::decode(...) + /// 2. BytesText::unescaped() + pub fn decode_and_unescape(&self, reader: &Reader) -> Result { + self.decode_and_unescape_with(reader, |_| None) } /// helper method to unescape then decode self using the reader encoding with custom entities /// /// for performance reasons (could avoid allocating a `String`), /// it might be wiser to manually use - /// 1. BytesText::unescaped() - /// 2. Reader::decode(...) + /// 1. Reader::decode(...) + /// 2. BytesText::unescaped() /// /// # Pre-condition /// /// The implementation of `resolve_entity` is expected to operate over UTF-8 inputs. - pub fn unescape_and_decode_with_custom_entities<'entity, B>( + pub fn decode_and_unescape_with<'entity, B>( &self, reader: &Reader, resolve_entity: impl Fn(&[u8]) -> Option<&'entity str>, diff --git a/src/lib.rs b/src/lib.rs index 383d4a96..57c6f9cd 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -59,7 +59,7 @@ //! } //! }, //! // unescape and decode the text event using the reader encoding -//! Ok(Event::Text(e)) => txt.push(e.unescape_and_decode(&reader).unwrap()), +//! Ok(Event::Text(e)) => txt.push(e.decode_and_unescape(&reader).unwrap()), //! Ok(Event::Eof) => break, // exits the loop when reaching end of file //! Err(e) => panic!("Error at position {}: {:?}", reader.buffer_position(), e), //! _ => (), // There are several other `Event`s we do not consider here diff --git a/src/reader.rs b/src/reader.rs index 9a967fba..b2ac9464 100644 --- a/src/reader.rs +++ b/src/reader.rs @@ -135,7 +135,7 @@ impl EncodingRef { /// _ => (), /// } /// }, -/// Ok(Event::Text(e)) => txt.push(e.unescape_and_decode(&reader).unwrap()), +/// Ok(Event::Text(e)) => txt.push(e.decode_and_unescape(&reader).unwrap()), /// Err(e) => panic!("Error at position {}: {:?}", reader.buffer_position(), e), /// Ok(Event::Eof) => break, /// _ => (), @@ -496,7 +496,7 @@ impl Reader { /// loop { /// match reader.read_event_into(&mut buf) { /// Ok(Event::Start(ref e)) => count += 1, - /// Ok(Event::Text(e)) => txt.push(e.unescape_and_decode(&reader).expect("Error!")), + /// Ok(Event::Text(e)) => txt.push(e.decode_and_unescape(&reader).expect("Error!")), /// Err(e) => panic!("Error at position {}: {:?}", reader.buffer_position(), e), /// Ok(Event::Eof) => break, /// _ => (), @@ -549,7 +549,7 @@ impl Reader { /// panic!("Undeclared namespace prefix {:?}", String::from_utf8(p)) /// } /// Ok((_, Event::Text(e))) => { - /// txt.push(e.unescape_and_decode(&reader).expect("Error!")) + /// txt.push(e.decode_and_unescape(&reader).expect("Error!")) /// }, /// Err(e) => panic!("Error at position {}: {:?}", reader.buffer_position(), e), /// Ok((_, Event::Eof)) => break, @@ -750,7 +750,7 @@ impl Reader { let s = match self.read_event_into(buf) { Err(e) => return Err(e), - Ok(Event::Text(e)) => e.unescape_and_decode(self), + Ok(Event::Text(e)) => e.decode_and_unescape(self), Ok(Event::End(e)) if e.name() == end => return Ok("".to_string()), Ok(Event::Eof) => return Err(Error::UnexpectedEof("Text".to_string())), _ => return Err(Error::TextNotFound), diff --git a/tests/test.rs b/tests/test.rs index f5a91dc7..83261c51 100644 --- a/tests/test.rs +++ b/tests/test.rs @@ -104,7 +104,7 @@ fn test_koi8_r_encoding() { loop { match r.read_event_into(&mut buf) { Ok(Text(e)) => { - e.unescape_and_decode(&r).unwrap(); + e.decode_and_unescape(&r).unwrap(); } Ok(Eof) => break, _ => (), diff --git a/tests/unit_tests.rs b/tests/unit_tests.rs index fc4cb98f..a480adb0 100644 --- a/tests/unit_tests.rs +++ b/tests/unit_tests.rs @@ -653,7 +653,7 @@ fn test_read_write_roundtrip_escape_text() -> Result<()> { match reader.read_event_into(&mut buf)? { Eof => break, Text(e) => { - let t = e.unescape_and_decode(&reader).unwrap(); + let t = e.decode_and_unescape(&reader).unwrap(); assert!(writer .write_event(Text(BytesText::from_plain_str(&t))) .is_ok());