Merge pull request #627 from swimos/docs

Tidy up of crate/module API: Stage 1

Author: horned-sphere

api/formats/swimos_msgpack/src/lib.rs

@@ -12,13 +12,43 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! MessagePack support for Swim serialization.
+//!
+//! Provides a MessagesPack backend for the Swim serialization system. This consists of two parts:
+//!
+//! - A function [`read_from_msg_pack`] that will attempt to deserialize any type that implements
+//!  [`swimos_form::structural::read::StructuralReadable`] from a buffer containing MessagePack data.
+//! - The type [`MsgPackInterpreter`] that implements [`swimos_form::structural::write::StructuralWriter`]
+//! allowing any type that implements [`swimos_form::structural::write::StructuralWritable`] to be
+//! serialized as MessagePack.
+//!
+//! # Examples
+//!
+//! ```
+//! use bytes::{BufMut, BytesMut};
+//! use swimos_form::structural::write::StructuralWritable;
+//! use swimos_msgpack::{read_from_msg_pack, MsgPackInterpreter};
+//!
+//! let mut buffer = BytesMut::with_capacity(128);
+//! let data = vec!["first".to_owned(), "second".to_owned(), "third".to_owned()];
+//! let mut writer = (&mut buffer).writer();
+//!
+//! let interpreter = MsgPackInterpreter::new(&mut writer);
+//! assert!(data.write_with(interpreter).is_ok());
+//!
+//! let mut bytes = buffer.split().freeze();
+//! let restored = read_from_msg_pack::<Vec<String>, _>(&mut bytes);
+//!
+//! assert_eq!(restored, Ok(data));
+//! ```
+
 mod reader;
 #[cfg(test)]
 mod tests;
 mod writer;
 
 pub use reader::{read_from_msg_pack, MsgPackReadError};
-pub use writer::{MsgPackBodyInterpreter, MsgPackInterpreter, MsgPackWriteError};
+pub use writer::{MsgPackInterpreter, MsgPackWriteError};
 
 const BIG_INT_EXT: i8 = 0;
 const BIG_UINT_EXT: i8 = 1;

api/formats/swimos_msgpack/src/reader/mod.rs

@@ -52,6 +52,9 @@ fn feed<T, E: Into<MsgPackReadError>>(maybe: Option<Result<T, E>>) -> Result<(),
 }
 
 /// Attempt to read a [`StructuralReadable`] type from MessagePack data in a buffer.
+///
+/// # Arguments
+/// * `input` - The buffer containing the MessagePack data.
 pub fn read_from_msg_pack<T: StructuralReadable, R: Buf>(
     input: &mut R,
 ) -> Result<T, MsgPackReadError> {
@@ -179,9 +182,11 @@ where
     })
 }
 
+/// Reading MessagePack data can fail if the bytes do not constitute valid MessagePack or the buffer contains
+/// an incomplete record.
 #[derive(Debug, PartialEq)]
 pub enum MsgPackReadError {
-    /// The parsed strucuture was not valid for the target type.
+    /// The parsed structure was not valid for the target type.
     Structure(ReadError),
     /// The MessagePack data contained invalid UTF8 in a string.
     StringDecode(Utf8Error),

api/formats/swimos_recon/Cargo.toml

@@ -6,21 +6,21 @@ edition = "2021"
 
 [features]
 default = []
-async_parser = ["futures", "tokio", "tokio-util", "bytes"]
 
 [dependencies]
 base64 = { workspace = true }
 either = { workspace = true }
 swimos_form = { path = "../../swimos_form" }
 swimos_model = { path = "../../swimos_model" }
+swimos_utilities = { path = "../../../swimos_utilities", features = ["encoding"] }
 nom = { workspace = true }
 nom_locate = { workspace = true }
 num-traits = { workspace = true }
 ryu = "1.0"
-futures = { workspace = true, optional = true }
-tokio = { workspace = true, features = ["io-util"], optional = true }
-tokio-util = { workspace = true, optional = true, features = ["codec"] }
-bytes = { workspace = true, optional = true }
+futures = { workspace = true }
+tokio = { workspace = true, features = ["io-util"] }
+tokio-util = { workspace = true, features = ["codec"] }
+bytes = { workspace = true }
 smallvec = { workspace = true }
 thiserror = { workspace = true }
 

api/formats/swimos_recon/src/comparator/mod.rs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use crate::parser::Span;
+use crate::recon_parser::{record::ParseIterator, Span};
 use smallvec::SmallVec;
 use std::iter::Peekable;
 use swimos_form::structural::read::event::ReadEvent;
@@ -24,10 +24,10 @@ mod tests;
 ///
 /// * `first` - The first recon value.
 /// * `second` - The second recon value.
-pub fn compare_values(first: &str, second: &str) -> bool {
+pub fn compare_recon_values(first: &str, second: &str) -> bool {
     match incremental_compare(
-        &mut crate::parser::ParseIterator::new(Span::new(first), false).peekable(),
-        &mut crate::parser::ParseIterator::new(Span::new(second), false).peekable(),
+        &mut ParseIterator::new(Span::new(first), false).peekable(),
+        &mut ParseIterator::new(Span::new(second), false).peekable(),
     ) {
         Some(eq) => eq,
         None => first == second,

api/formats/swimos_recon/src/comparator/tests.rs

@@ -12,24 +12,24 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use crate::comparator::{compare_values, incremental_compare};
-use crate::parser::{ParseError, ParseIterator, Span};
+use crate::comparator::{compare_recon_values, incremental_compare};
+use crate::recon_parser::record::ParseIterator;
+use crate::recon_parser::{parse_recognize, ParseError, Span};
 use nom::error::ErrorKind;
 use std::borrow::Cow;
 use swimos_form::structural::read::event::{NumericValue, ReadEvent};
 use swimos_model::Value;
 
 fn value_from_string(rep: &str) -> Result<Value, ParseError> {
-    let span = Span::new(rep);
-    crate::parser::parse_recognize(span, false)
+    parse_recognize(rep, false)
 }
 
 #[test]
 fn cmp_simple() {
     let first = "@name(a: 1, b: 2)";
     let second = "@name(a: 1, b: 2)";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -38,7 +38,7 @@ fn cmp_simple() {
     let first = "\"test\"";
     let second = "test";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -50,7 +50,7 @@ fn cmp_complex() {
     let first = "{a:2}";
     let second = "{ a: 2 }";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -59,7 +59,7 @@ fn cmp_complex() {
     let first = "@tag(){}:1";
     let second = "@tag{}:1";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -68,7 +68,7 @@ fn cmp_complex() {
     let first = "@name(a: 1, b: 2)";
     let second = "@name({a: 1, b: 2})";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -77,7 +77,7 @@ fn cmp_complex() {
     let first = "@first(1)@second(2)";
     let second = "@first(1)@second(2) {}";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -86,7 +86,7 @@ fn cmp_complex() {
     let first = "{ @inner(0), after }";
     let second = "{ @inner(0) {}, after }";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -95,7 +95,7 @@ fn cmp_complex() {
     let first = "@outer(@inner)";
     let second = "@outer(@inner {})";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -104,7 +104,7 @@ fn cmp_complex() {
     let first = "@foo({one: 1, two: @bar(1,2,3), three: 3, four: {@baz({1,2})}})";
     let second = "@foo(one: 1, two: @bar({1,2,3}), three: 3, four: {@baz(1,2)})";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -113,7 +113,7 @@ fn cmp_complex() {
     let first = "@foo(1,2)";
     let second = "@foo({1,2})";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -122,7 +122,7 @@ fn cmp_complex() {
     let first = "@foo({one: 1, two: @bar(1,2,3)})";
     let second = "@foo(one: 1, two: @bar({1,2,3}))";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -131,7 +131,7 @@ fn cmp_complex() {
     let first = "@name(@foo,@bar)";
     let second = "@name({@foo, @bar})";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -140,7 +140,7 @@ fn cmp_complex() {
     let first = "@name(1, @foo@bar)";
     let second = "@name({1, @foo@bar})";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -149,7 +149,7 @@ fn cmp_complex() {
     let first = "@name(@foo@bar({@bar, 1, @baz()}), @bar@foo()@baz)";
     let second = "@name({@foo@bar(@bar, 1, @baz()), @bar@foo()@baz})";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -158,7 +158,7 @@ fn cmp_complex() {
     let first = "@foo(1, @bar(2,3), 4, 5)";
     let second = "@foo(1, @bar({2,3}), 4, 5)";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -167,7 +167,7 @@ fn cmp_complex() {
     let first = "@name(a: @foo)";
     let second = "@name({a: @foo})";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -176,7 +176,7 @@ fn cmp_complex() {
     let first = "@name(b: @foo@bar@baz, @foo(1,2), @bar@baz))";
     let second = "@name({b: @foo@bar@baz, @foo({1,2}), @bar@baz})";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -185,7 +185,7 @@ fn cmp_complex() {
     let first = "@name(b: )";
     let second = "@name({b: })";
 
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let result_1 = value_from_string(first).unwrap();
     let result_2 = value_from_string(second).unwrap();
@@ -326,34 +326,34 @@ fn cmp_early_termination_complex() {
 fn cmp_invalid_eq() {
     let first = ":5";
     let second = ":5";
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let first = ")10";
     let second = ")10";
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 
     let first = "@foo}20";
     let second = "@foo}20";
-    assert!(compare_values(first, second));
+    assert!(compare_recon_values(first, second));
 }
 
 #[test]
 fn cmp_invalid_not_eq() {
     let first = ":5, 30";
     let second = ":10, 30";
-    assert!(!compare_values(first, second));
+    assert!(!compare_recon_values(first, second));
 
     let first = ")15";
     let second = ")20";
-    assert!(!compare_values(first, second));
+    assert!(!compare_recon_values(first, second));
 
     let first = "@foo-30";
     let second = "@foo-35";
-    assert!(!compare_values(first, second));
+    assert!(!compare_recon_values(first, second));
 
     let first = "@foo(1, 2, 3){-}";
     let second = "@foo({1, 2, 3}){-}";
-    assert!(!compare_values(first, second));
+    assert!(!compare_recon_values(first, second));
 }
 
 #[test]