aboutsummaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/declaration.rs7
-rw-r--r--src/element.rs70
-rw-r--r--src/error.rs39
-rw-r--r--src/lib.rs39
-rw-r--r--src/reader.rs63
-rw-r--r--src/writer.rs97
-rw-r--r--src/writer/endable.rs (renamed from src/endable.rs)4
-rw-r--r--src/writer/loggable.rs (renamed from src/loggable.rs)9
-rw-r--r--src/xml/composers.rs4
-rw-r--r--src/xml/mod.rs4
-rw-r--r--src/xml/parsers.rs4
-rw-r--r--src/xml/parsers_complete.rs4
12 files changed, 280 insertions, 64 deletions
diff --git a/src/declaration.rs b/src/declaration.rs
index 2c0855f..fe3aac8 100644
--- a/src/declaration.rs
+++ b/src/declaration.rs
@@ -1,9 +1,15 @@
+// SPDX-FileCopyrightText: 2025 cel <cel@bunny.garden>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/// An XML declaration.
pub struct Declaration {
pub version_info: VersionInfo,
pub encoding_decl: Option<String>,
pub sd_decl: Option<bool>,
}
+/// An XML version.
#[derive(Clone, Copy)]
pub enum VersionInfo {
One,
@@ -11,6 +17,7 @@ pub enum VersionInfo {
}
impl Declaration {
+ /// Create an XML declaration from a version.
pub fn version(version: VersionInfo) -> Self {
Self {
version_info: version,
diff --git a/src/element.rs b/src/element.rs
index 1c1366a..3621da5 100644
--- a/src/element.rs
+++ b/src/element.rs
@@ -1,3 +1,7 @@
+// SPDX-FileCopyrightText: 2025 cel <cel@bunny.garden>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
/// elements resemble a final tree, including inherited namespace information
use std::{
collections::{HashMap, HashSet, VecDeque},
@@ -11,12 +15,15 @@ use crate::{
Result,
};
+/// Result type for the `FromElement` trait.
pub type DeserializeResult<T> = std::result::Result<T, DeserializeError>;
+/// Trait for conversion from an `Element` into another type, for deserialisation from a `Reader`.
pub trait FromElement: Sized {
fn from_element(element: Element) -> DeserializeResult<Self>;
}
+/// Trait for conversion from a type into an `Element`, for serialisation into a `Writer`.
pub trait IntoElement {
fn builder(&self) -> ElementBuilder;
@@ -45,18 +52,24 @@ pub struct Name {
pub local_name: String,
}
+/// `Content` represents anything that can be the content of an XML element.
#[derive(Debug, Clone)]
pub enum Content {
+ /// A child element.
Element(Element),
+ /// A text value.
Text(String),
+ /// A processing instruction.
PI,
+ /// A comment.
Comment(String),
}
// should this be a trait?
+/// `Element` represents an XML element that can be written to a `Writer` or read from a `Reader`.
#[derive(Debug, Clone)]
pub struct Element {
- pub name: Name,
+ pub(crate) name: Name,
// namespace: Name,
// each element once created contains the qualified namespace information for that element
// the name contains the qualified namespace so this is unnecessary
@@ -64,15 +77,15 @@ pub struct Element {
// hashmap of explicit namespace declarations on the element itself only
// possibly not needed as can be calculated at write time depending on context and qualified namespace, and for reading, element validity and namespaces are kept track of by the reader.
// change this to custom namespace declarations only, so you can override the definition of namespaces if you wish
- pub namespace_declaration_overrides: HashSet<NamespaceDeclaration>,
+ pub(crate) namespace_declaration_overrides: HashSet<NamespaceDeclaration>,
// attributes can be in a different namespace than the element. how to make sure they are valid?
// maybe include the namespace instead of or with the prefix
// you can calculate the prefix from the namespaced name and the current writer context
// you can validate the prefix and calculate the namespace from the current reader context
// this results in readers and writers being able to return qualification errors as they aren't able to create elements until every part is qualified.
- pub attributes: HashMap<Name, String>,
+ pub(crate) attributes: HashMap<Name, String>,
// TODO: make a hashmap maybe? to be able to address parts of the content individually
- pub content: VecDeque<Content>,
+ pub(crate) content: VecDeque<Content>,
}
impl FromElement for Element {
@@ -82,10 +95,12 @@ impl FromElement for Element {
}
impl Element {
+ /// Return the namespace the xml element is qualified by, and the localname, for matching on the element when you don't know which kind of element to expect.
pub fn identify(&self) -> (Option<&str>, &str) {
(self.name.namespace.as_deref(), &self.name.local_name)
}
+ /// Check the localname of the element.
pub fn check_name(&self, name: &str) -> DeserializeResult<()> {
if self.name.local_name == name {
Ok(())
@@ -97,6 +112,7 @@ impl Element {
}
}
+ /// Check the element is qualified by a namespace.
pub fn check_namespace(&self, namespace: &str) -> DeserializeResult<()> {
if self.name.namespace.as_deref() == Some(namespace) {
return Ok(());
@@ -114,6 +130,7 @@ impl Element {
}
}
+ /// Optionally extract an attribute from the element.
pub fn attribute_opt<V: FromStr>(&mut self, att_name: &str) -> DeserializeResult<Option<V>> {
if let Some(att_value) = self.attributes.remove(&Name {
namespace: None,
@@ -127,6 +144,7 @@ impl Element {
}
}
+ /// Optionally extract a namespaced attribute from the elmeent.
pub fn attribute_opt_namespaced<V: FromStr>(
&mut self,
att_name: &str,
@@ -144,6 +162,7 @@ impl Element {
}
}
+ /// Extract an attribute from the element.
pub fn attribute<V: FromStr>(&mut self, att_name: &str) -> DeserializeResult<V> {
let name = Name {
namespace: None,
@@ -158,6 +177,7 @@ impl Element {
}
}
+ /// Extract a namespaced attribute from the element.
pub fn attribute_namespaced<V: FromStr>(
&mut self,
att_name: &str,
@@ -176,6 +196,7 @@ impl Element {
}
}
+ /// Ensure there are no more attributes on the element.
pub fn no_more_attributes(self) -> DeserializeResult<Self> {
if self.attributes.is_empty() {
Ok(self)
@@ -186,6 +207,8 @@ impl Element {
// for xs:any
+ /// Extract a child of type `T` from the element.
+ /// E.g. when there is an xs:any.
pub fn child_one<T: FromElement>(&mut self) -> DeserializeResult<T> {
if let Some(position) = self.content.iter().position(|content| match content {
Content::Element(element) => <T as FromElement>::from_element(element.clone()).is_ok(),
@@ -204,6 +227,8 @@ impl Element {
}
}
+ /// Optionally extract a child of type `T` from the element.
+ /// E.g. when there is an xs:any.
pub fn child_opt<T: FromElement>(&mut self) -> DeserializeResult<Option<T>> {
if let Some(position) = self.content.iter().position(|content| match content {
Content::Element(element) => <T as FromElement>::from_element(element.clone()).is_ok(),
@@ -222,6 +247,7 @@ impl Element {
}
}
+ /// Extract several children of type `T` from the element.
pub fn children<T: FromElement>(&mut self) -> DeserializeResult<Vec<T>> {
let (children, rest): (VecDeque<_>, VecDeque<_>) = self
.content
@@ -252,6 +278,7 @@ impl Element {
Ok(children)
}
+ /// Extract a text value from the element.
pub fn value<V: FromStr>(&mut self) -> DeserializeResult<V> {
if let Some(position) = self.content.iter().position(|content| match content {
Content::Element(_) => false,
@@ -270,6 +297,7 @@ impl Element {
}
}
+ /// Optionally extract a text value from the element.
pub fn value_opt<V: FromStr>(&mut self) -> DeserializeResult<Option<V>> {
if let Some(position) = self.content.iter().position(|content| match content {
Content::Element(_) => false,
@@ -290,6 +318,8 @@ impl Element {
// for xs:sequence
+ /// Pop a child element of type `T` from the element.
+ /// E.g. when there is an xs:sequence.
pub fn pop_child_one<T: FromElement>(&mut self) -> DeserializeResult<T> {
loop {
let child = self
@@ -307,6 +337,8 @@ impl Element {
}
}
+ /// Optionally pop a child element of type `T` from the element.
+ /// E.g. when there is an xs:sequence.
pub fn pop_child_opt<T: FromElement>(&mut self) -> DeserializeResult<Option<T>> {
loop {
let child = self.content.pop_front();
@@ -327,6 +359,8 @@ impl Element {
}
}
+ /// Pop several children of type `T` from the element.
+ /// E.g. when there is an xs:sequence.
pub fn pop_children<T: FromElement>(&mut self) -> DeserializeResult<Vec<T>> {
let mut children = Vec::new();
loop {
@@ -360,6 +394,8 @@ impl Element {
}
}
+ /// Pop a text value from the element.
+ /// E.g. when there is an xs:sequence.
pub fn pop_value<V: FromStr>(&mut self) -> DeserializeResult<V> {
loop {
let child = self
@@ -381,6 +417,8 @@ impl Element {
}
}
+ /// Optionally pop a text value from the element.
+ /// E.g. when there is an xs:sequence.
pub fn pop_value_opt<V: FromStr>(&mut self) -> DeserializeResult<Option<V>> {
loop {
let child = self.content.pop_front();
@@ -404,6 +442,7 @@ impl Element {
}
}
+ /// Ensure there is no more element content left.
pub fn no_more_content(self) -> DeserializeResult<Self> {
if self
.content
@@ -423,11 +462,13 @@ impl Element {
}
}
+ /// Create a new `ElementBuilder`.
pub fn builder(name: impl ToString, namespace: Option<impl ToString>) -> ElementBuilder {
ElementBuilder::new(name, namespace)
}
}
+/// Builder for the `Element` type.
pub struct ElementBuilder {
name: Name,
namespace_declaration_overrides: Vec<NamespaceDeclaration>,
@@ -436,6 +477,7 @@ pub struct ElementBuilder {
}
impl ElementBuilder {
+ /// Create a new `ElementBuilder`.
pub fn new(name: impl ToString, namespace: Option<impl ToString>) -> Self {
Self {
name: Name {
@@ -448,6 +490,7 @@ impl ElementBuilder {
}
}
+ /// Push a namespace declaration override onto the element builder.
pub fn push_namespace_declaration_override(
mut self,
prefix: Option<impl ToString>,
@@ -461,6 +504,7 @@ impl ElementBuilder {
self
}
+ /// Push an attribute onto the element builder.
pub fn push_attribute<N: ToString, V: ToString>(mut self, name: N, value: V) -> Self {
self.attributes.push((
// TODO: make sure name is a valid name, same for prefixes
@@ -473,6 +517,7 @@ impl ElementBuilder {
self
}
+ /// Push a namespaced attribute onto the element builder.
pub fn push_attribute_namespaced(
mut self,
namespace: impl ToString,
@@ -490,17 +535,20 @@ impl ElementBuilder {
}
// TODO: use references for everything to avoid cloning
+ /// Push a child element onto the element builder.
pub fn push_child(mut self, child: impl IntoElement) -> Self {
self.content.push(ContentBuilder::Element(child.builder()));
self
}
// TODO: better way for push_text to work, empty string should be empty element no matter what
+ /// Push a text value onto the element builder.
pub fn push_text(mut self, text: impl ToString) -> Self {
self.content.push(ContentBuilder::Text(text.to_string()));
self
}
+ /// Optionally push an attribute onto the element builder.
pub fn push_attribute_opt(self, name: impl ToString, value: Option<impl ToString>) -> Self {
if let Some(value) = value {
self.push_attribute(name, value)
@@ -509,6 +557,7 @@ impl ElementBuilder {
}
}
+ /// Optionally push a namespaced attribute onto the element builder.
pub fn push_attribute_opt_namespaced(
self,
namespace: impl ToString,
@@ -522,6 +571,7 @@ impl ElementBuilder {
}
}
+ /// Optionally push a child onto the element builder.
pub fn push_child_opt(self, child: Option<impl IntoElement>) -> Self {
if let Some(child) = child {
self.push_child(child)
@@ -530,6 +580,7 @@ impl ElementBuilder {
}
}
+ /// Optionally push a text value onto the element builder.
pub fn push_text_opt(self, text: Option<impl ToString>) -> Self {
if let Some(text) = text {
self.push_text(text)
@@ -538,11 +589,13 @@ impl ElementBuilder {
}
}
+ /// Optionally push a content item onto the element builder.
pub fn push_content(mut self, content: ContentBuilder) -> Self {
self.content.push(content);
self
}
+ /// Optionally push content items onto the element builder.
pub fn push_children(self, children: Vec<impl IntoContent>) -> Self {
let mut element_builder = self;
for child in children {
@@ -551,6 +604,7 @@ impl ElementBuilder {
element_builder
}
+ /// Build an `Element` from the `ElementBuilder`.
pub fn build(&self) -> Result<Element> {
let mut namespace_declaration_overrides = HashSet::new();
for namespace_declaration in &self.namespace_declaration_overrides {
@@ -588,6 +642,7 @@ impl ElementBuilder {
}
}
+/// Trait for conversion from a type into an (`Element`) `Content` item.
pub trait IntoContent {
fn into_content(&self) -> Content {
self.builder().build().unwrap()
@@ -605,17 +660,23 @@ where
}
}
+/// Trait for conversion from some `Element` `Content` into another type.
pub trait FromContent: Sized {
fn from_content(content: Content) -> DeserializeResult<Self>;
}
+/// Builder for `Content`.
pub enum ContentBuilder {
+ /// A child element.
Element(ElementBuilder),
+ /// A text value.
Text(String),
+ /// A comment.
Comment(String),
}
impl ContentBuilder {
+ /// Build a `Content` item from the builder.
pub fn build(&self) -> Result<Content> {
match self {
ContentBuilder::Element(element_builder) => {
@@ -627,6 +688,7 @@ impl ContentBuilder {
}
}
+/// Escape a str into an XML escaped string.
pub fn escape_str(s: &str) -> String {
let mut string = String::new();
for str in s.split_inclusive(|c| c == '<' || c == '&' || c == '>') {
diff --git a/src/error.rs b/src/error.rs
index 4976a78..c8a88fe 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -1,6 +1,9 @@
+// SPDX-FileCopyrightText: 2025 cel <cel@bunny.garden>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
use std::{
collections::{HashMap, VecDeque},
- fmt,
num::ParseIntError,
str::Utf8Error,
sync::Arc,
@@ -15,38 +18,55 @@ use crate::{
Element,
};
+/// Error type for the `FromElement` trait. Used when deserialising from an `Element`.
#[derive(Error, Debug, Clone)]
pub enum DeserializeError {
+ /// Could not parse string.
#[error("could not parse string {0:?} to requested value")]
FromStr(String),
+ /// Unexpected attributes.
#[error("unexpected attributes {0:?}")]
UnexpectedAttributes(HashMap<Name, String>),
+ /// Unexpected element content.
#[error("unexpected element content: {0:?}")]
UnexpectedContent(VecDeque<Content>),
+ /// Missing attribute.
#[error("attribute `{0:?}` missing")]
MissingAttribute(Name),
+ /// Incorrect localname encountered.
#[error("incorrect localname: expected `{expected:?}`, found `{found:?}`")]
IncorrectName { expected: String, found: String },
+ /// Incorrect namespace encountered.
#[error("incorrect namespace: expected `{expected:?}`, found `{found:?}`")]
IncorrectNamespace { expected: String, found: String },
+ /// Unqualified namespace when expecting qualified namespace.
#[error("unqualified namespace: expected `{expected:?}`")]
Unqualified { expected: String },
+ /// Element missing expected child.
#[error("element missing expected child")]
MissingChild,
+ /// Element missing expected text value.
#[error("element missing expected text value")]
MissingValue,
// not used by crate (yet), but may be used by consumers implementing FromElement
+ /// Unexpected element.
#[error("unexpected element: {0:?}")]
UnexpectedElement(Element),
+ /// Attribute is an empty string.
#[error("attribute `{0}` is an empty string")]
AttributeEmptyString(String),
+ /// Empty string.
#[error("empty string")]
EmptyString,
}
+/// General error type for functions in the crate.
// TODO: add error context (usually the stanza)
#[derive(Error, Debug, Clone)]
pub enum Error {
+ #[cfg(target_arch = "wasm32")]
+ #[error("websocket closed")]
+ WebSocketClosed,
#[error("io: {0}")]
// TODO: is this okay?
ReadError(Arc<std::io::Error>),
@@ -79,23 +99,28 @@ pub enum Error {
Websocket(#[from] WebsocketError),
}
+/// Websocket-related errors.
#[cfg(target_arch = "wasm32")]
#[derive(Error, Debug, Clone)]
pub enum WebsocketError {
- #[error("write: {0:?}")]
- Write(JsValue),
+ /// Websocket write error.
+ #[error("write")]
+ Write,
+ /// Invalid encoding.
#[error("invalid encoding")]
InvalidEncoding,
+ /// Can't decode blob.
#[error("can't decode blob")]
CantDecodeBlob,
+ /// Unknown data type.
#[error("unknown data type")]
UnknownDataType,
}
#[cfg(target_arch = "wasm32")]
impl From<JsValue> for Error {
- fn from(e: JsValue) -> Self {
- Self::Websocket(WebsocketError::Write(e))
+ fn from(_e: JsValue) -> Self {
+ Self::Websocket(WebsocketError::Write)
}
}
@@ -105,12 +130,16 @@ impl From<std::io::Error> for Error {
}
}
+/// Character reference decode error.
#[derive(Error, Debug, Clone)]
pub enum CharRefError {
+ /// Int parsing.
#[error("int parsing: {0}")]
ParseInt(#[from] ParseIntError),
+ /// Integer is not a valid char.
#[error("u32 `{0}` does not represent a valid char")]
IntegerNotAChar(u32),
+ /// Character is an invalid XML char.
#[error("`{0}` is not a valid xml char")]
InvalidXMLChar(char),
}
diff --git a/src/lib.rs b/src/lib.rs
index 8d95d0b..7785e17 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,19 +1,48 @@
+// SPDX-FileCopyrightText: 2025 cel <cel@bunny.garden>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! # peanuts: An ergonomic (async) xml reader/writer library.
+//!
+//! Features:
+//!
+//! - Serialisation
+//! - Deserialisation
+//! - DOM navigation
+//! - Namespacing
+//! - Websocket framing
+
+/// XML prolog declaration types.
pub mod declaration;
-pub mod element;
-mod endable;
+mod element;
mod error;
-pub mod loggable;
-pub mod reader;
+mod reader;
mod writer;
-pub mod xml;
+// TODO: alternative raw xml API
+mod xml;
+/// Result type for the crate.
pub type Result<T> = std::result::Result<T, error::Error>;
+/// XML namespace URI for the `xml:` namespace prefix.
pub const XML_NS: &str = "http://www.w3.org/XML/1998/namespace";
+/// XML namespace URI for the `xmlns:` namespace prefix.
pub const XMLNS_NS: &str = "http://www.w3.org/2000/xmlns/";
+pub use element::Content;
+pub use element::ContentBuilder;
+pub use element::DeserializeResult;
pub use element::Element;
+pub use element::ElementBuilder;
+pub use element::FromContent;
+pub use element::FromElement;
+pub use element::IntoContent;
+pub use element::IntoElement;
pub use error::DeserializeError;
pub use error::Error;
+pub use reader::ReadableString;
pub use reader::Reader;
+#[cfg(target_arch = "wasm32")]
+pub use reader::WebSocketOnMessageRead;
+pub use writer::Loggable;
pub use writer::Writer;
diff --git a/src/reader.rs b/src/reader.rs
index 62b4e08..f863ccc 100644
--- a/src/reader.rs
+++ b/src/reader.rs
@@ -1,4 +1,7 @@
-#[cfg(target_arch = "wasm32")]
+// SPDX-FileCopyrightText: 2025 cel <cel@bunny.garden>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
use std::io::Write;
use circular::Buffer;
@@ -9,10 +12,10 @@ use std::{
collections::{HashMap, HashSet, VecDeque},
str,
};
-use tokio::io::{AsyncRead, AsyncReadExt};
+use tokio::io::AsyncRead;
#[cfg(target_arch = "wasm32")]
use tokio::sync::mpsc;
-use tracing::{debug, info, trace};
+use tracing::{info, trace};
#[cfg(target_arch = "wasm32")]
use wasm_bindgen::{closure::Closure, JsCast};
#[cfg(target_arch = "wasm32")]
@@ -30,11 +33,11 @@ use crate::{
static MAX_STANZA_SIZE: usize = 65536;
-/// streaming reader that tracks depth and available namespaces at current depth
+/// Reader that tracks depth and corresponding declared/available namespaces.
#[derive(Debug)]
pub struct Reader<R> {
inner: R,
- pub buffer: Buffer,
+ buffer: Buffer,
// holds which tags we are in atm over depth
// to have names reference namespaces could
depth: Vec<Name>,
@@ -103,12 +106,14 @@ impl TryFrom<MessageEvent> for WsMessage {
#[cfg(target_arch = "wasm32")]
#[derive(Debug)]
+/// Receiver for websocket frames. Implements `Readable` for asynchronous XML reading.
pub struct WebSocketOnMessageRead {
queue: mpsc::UnboundedReceiver<WsMessage>,
}
#[cfg(target_arch = "wasm32")]
impl WebSocketOnMessageRead {
+ /// Create a new `WebsocketOnMessageRead` with corresponding `on_message` event closure.
pub fn new() -> (Closure<dyn FnMut(MessageEvent)>, Self) {
let (send, recv) = mpsc::unbounded_channel();
let on_msg = Closure::wrap(Box::new(move |msg_evt: MessageEvent| {
@@ -133,30 +138,39 @@ impl WebSocketOnMessageRead {
#[cfg(target_arch = "wasm32")]
impl Readable for WebSocketOnMessageRead {
async fn read_buf(&mut self, buffer: &mut Buffer) -> Result<usize> {
- let mut queue = Vec::new();
- self.queue.recv_many(&mut queue, 10).await;
- let mut bytes = 0;
- for msg in queue {
- match msg {
- WsMessage::Text(s) => {
- let text = s.as_bytes();
- bytes += buffer.write(text)?;
- }
- WsMessage::Binary(v) => {
- bytes += buffer.write(&v)?;
- }
+ let msg = self.queue.recv().await;
+ let msg = match msg {
+ Some(msg) => msg,
+ None => return Err(Error::WebSocketClosed),
+ };
+ match msg {
+ WsMessage::Text(s) => {
+ let text = s.as_bytes();
+ Ok(buffer.write(text)?)
}
+ WsMessage::Binary(v) => Ok(buffer.write(&v)?),
}
- Ok(bytes)
}
}
+/// Trait for abstracting asynchronous read streams.
pub trait Readable {
fn read_buf(&mut self, buffer: &mut Buffer)
-> impl std::future::Future<Output = Result<usize>>;
}
+/// String wrapper which implements Readable, for string parsing.
+pub struct ReadableString(pub String);
+
+impl Readable for ReadableString {
+ async fn read_buf(&mut self, buffer: &mut Buffer) -> Result<usize> {
+ let string = self.0.split_off(0);
+ Ok(buffer.write(string.as_bytes())?)
+ }
+}
+
impl<R> Reader<R> {
+ /// Create a new `Reader` which is constrained to a single root element.
pub fn new(reader: R) -> Self {
let mut default_declarations = HashSet::new();
default_declarations.insert(NamespaceDeclaration {
@@ -178,6 +192,7 @@ impl<R> Reader<R> {
}
}
+ /// Create a new `Reader` which is not constrained to a single root element.
pub fn new_unendable(reader: R) -> Self {
let mut default_declarations = HashSet::new();
default_declarations.insert(NamespaceDeclaration {
@@ -199,6 +214,7 @@ impl<R> Reader<R> {
}
}
+ /// Extract the inner type from the `Reader`.
pub fn into_inner(self) -> R {
self.inner
}
@@ -214,6 +230,7 @@ where
}
impl<R: Readable> Reader<R> {
+ /// Attempt to read an XML prolog, which could include an XML declaration, miscellaneous items (e.g. comments, processing instructions), and/or a doctype declaration.
pub async fn read_prolog<'s>(&'s mut self) -> Result<Option<Declaration>> {
if !self.unendable && self.root_ended {
return Err(Error::RootElementEnded);
@@ -269,18 +286,21 @@ impl<R: Readable> Reader<R> {
}
}
+ /// Read a start tag, moving up in document depth, and convert it into a type which implements `FromElement`.
pub async fn read_start<'s, T: FromElement>(&'s mut self) -> Result<T> {
let element = self.read_start_tag().await?;
trace!("read element start: {:?}", element);
Ok(FromElement::from_element(element)?)
}
+ /// Read a full element (start tag + content + end tag, or empty tag) and convert it into a type which implements `FromElement`.
pub async fn read<'s, T: FromElement>(&'s mut self) -> Result<T> {
let element = self.read_element().await?;
trace!("read element: {:?}", element);
Ok(FromElement::from_element(element)?)
}
+ /// Read a start tag, moving up in document depth.
pub async fn read_start_tag<'s>(&'s mut self) -> Result<Element> {
if !self.unendable && self.root_ended {
return Err(Error::RootElementEnded);
@@ -316,6 +336,7 @@ impl<R: Readable> Reader<R> {
}
}
+ /// Read an end tag, moving down in document depth.
pub async fn read_end_tag<'s>(&'s mut self) -> Result<()> {
if !self.unendable && self.root_ended {
return Err(Error::RootElementEnded);
@@ -354,6 +375,7 @@ impl<R: Readable> Reader<R> {
}
}
+ /// Read a full element (start tag + content + end tag, or empty tag).
pub async fn read_element<'s>(&'s mut self) -> Result<Element> {
if !self.unendable && self.root_ended {
return Err(Error::RootElementEnded);
@@ -389,6 +411,7 @@ impl<R: Readable> Reader<R> {
}
}
+ /// Read element content (text, another full element, a comment, a PI).
pub async fn read_content<'s>(&'s mut self) -> Result<Content> {
if !self.unendable && self.root_ended {
return Err(Error::RootElementEnded);
@@ -546,6 +569,7 @@ impl<R: Readable> Reader<R> {
}
impl<R> Reader<R> {
+ /// Convert a start tag into an `Element` given a mutable document context.
fn start_tag_from_xml(
depth: &mut Vec<Name>,
namespace_declarations: &mut Vec<HashSet<NamespaceDeclaration>>,
@@ -667,6 +691,7 @@ impl<R> Reader<R> {
});
}
+ /// Ensure an end tag is acceptable given a document context.
fn end_tag_from_xml(
depth: &mut Vec<Name>,
namespace_declarations: &mut Vec<HashSet<NamespaceDeclaration>>,
@@ -714,6 +739,7 @@ impl<R> Reader<R> {
}
}
+ /// Convert an xml element (empty or not) into an `Element` given a mutable document context.
fn element_from_xml(
namespace_declarations: &mut Vec<HashSet<NamespaceDeclaration>>,
element: xml::Element,
@@ -888,6 +914,7 @@ impl<R> Reader<R> {
});
}
+ /// Convert xml content into a `VecDeque` of `Content` given a document context.
fn content_from_xml(
namespaces: &mut Vec<HashSet<NamespaceDeclaration>>,
xml_content: xml::Content,
diff --git a/src/writer.rs b/src/writer.rs
index 40a935b..5cd0d0e 100644
--- a/src/writer.rs
+++ b/src/writer.rs
@@ -1,3 +1,7 @@
+// SPDX-FileCopyrightText: 2025 cel <cel@bunny.garden>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
use std::collections::HashSet;
use async_recursion::async_recursion;
@@ -9,14 +13,17 @@ use web_sys::WebSocket;
use crate::{
declaration::{Declaration, VersionInfo},
element::{escape_str, Content, Element, IntoContent, IntoElement, Name, NamespaceDeclaration},
- endable::Endable,
error::Error,
- loggable::Loggable,
xml::{self, composers::Composer, parsers_complete::Parser},
Result, XMLNS_NS, XML_NS,
};
+use endable::Endable;
+pub use loggable::Loggable;
+
+mod endable;
+mod loggable;
-// pub struct Writer<W, C = Composer> {
+/// Writer that tracks depth and corresponding declared/available namespaces.
#[derive(Debug)]
pub struct Writer<W> {
inner: Endable<W>,
@@ -26,6 +33,7 @@ pub struct Writer<W> {
}
impl<W> Writer<Loggable<W>> {
+ /// Create a new `Writer` which is constrained to a single root element.
pub fn new(writer: W) -> Self {
let mut default_declarations = HashSet::new();
default_declarations.insert(NamespaceDeclaration {
@@ -44,6 +52,7 @@ impl<W> Writer<Loggable<W>> {
}
}
+ /// Create a new `Writer` which is not constrained to a single root element.
pub fn new_unendable(writer: W) -> Self {
let mut default_declarations = HashSet::new();
default_declarations.insert(NamespaceDeclaration {
@@ -62,6 +71,7 @@ impl<W> Writer<Loggable<W>> {
}
}
+ /// Extract the inner type from the `Writer`.
pub fn into_inner(self) -> W {
self.inner.into_inner().into_inner()
}
@@ -69,6 +79,7 @@ impl<W> Writer<Loggable<W>> {
#[cfg(target_arch = "wasm32")]
impl Writer<WebSocket> {
+ /// Create a new `Writer` which is constrained to a single root element.
pub fn new(websocket: WebSocket) -> Self {
let mut default_declarations = HashSet::new();
default_declarations.insert(NamespaceDeclaration {
@@ -87,10 +98,12 @@ impl Writer<WebSocket> {
}
}
+ /// Extract the inner `WebSocket` from the `Writer`.
pub fn into_inner(self) -> WebSocket {
self.inner.into_inner()
}
+ /// Create a new `Writer` which is not constrained to a single root element.
pub fn new_unendable(websocket: WebSocket) -> Self {
let mut default_declarations = HashSet::new();
default_declarations.insert(NamespaceDeclaration {
@@ -109,6 +122,7 @@ impl Writer<WebSocket> {
}
}
+ /// Write an XML declaration with the provided `VersionInfo`.
pub async fn write_declaration(&mut self, version: VersionInfo) -> Result<()> {
let declaration = Declaration::version(version);
let version_info;
@@ -132,6 +146,7 @@ impl Writer<WebSocket> {
Ok(())
}
+ /// Write a full element corresponding with the item implementing `IntoElement` (start tag + content + end tag).
pub async fn write_full(&mut self, into_element: &impl IntoElement) -> Result<()> {
let element = into_element.into_element();
let mut frame = String::new();
@@ -141,6 +156,7 @@ impl Writer<WebSocket> {
Ok(())
}
+ /// Write the start tag of an item that implements `IntoElement`. Navigates up the document.
pub async fn write_start(&mut self, into_element: &impl IntoElement) -> Result<()> {
let element = into_element.into_element();
let mut frame = String::new();
@@ -150,6 +166,7 @@ impl Writer<WebSocket> {
Ok(())
}
+ /// Write all the inner content (everything within the start and end tag of an xml element) of an item that implements `IntoElement`. In the case of an empty element, write nothing.
pub async fn write_all_content(&mut self, into_element: &impl IntoElement) -> Result<()> {
let mut frame = String::new();
for content in &into_element.get_content() {
@@ -160,6 +177,7 @@ impl Writer<WebSocket> {
Ok(())
}
+ /// Write an item that implements `IntoContent`. Could be an element, some text, a comment, etc. Anything that could be included in an element body.
pub async fn write(&mut self, into_content: &impl IntoContent) -> Result<()> {
let content = into_content.into_content();
let mut frame = String::new();
@@ -169,7 +187,7 @@ impl Writer<WebSocket> {
Ok(())
}
- // pub async fn write_end(&mut self)
+ /// Navigate down the document structure and write the end tag for the current element opened in the document context.
pub async fn write_end(&mut self) -> Result<()> {
let mut frame = String::new();
self.write_end_tag_to_frame(&mut frame)?;
@@ -178,7 +196,7 @@ impl Writer<WebSocket> {
Ok(())
}
- pub fn write_element_to_frame(&mut self, element: &Element, frame: &mut String) -> Result<()> {
+ fn write_element_to_frame(&mut self, element: &Element, frame: &mut String) -> Result<()> {
if element.content.is_empty() {
self.write_empty_to_frame(element, frame)?;
} else {
@@ -191,8 +209,8 @@ impl Writer<WebSocket> {
Ok(())
}
- pub fn write_empty_to_frame(&mut self, element: &Element, frame: &mut String) -> Result<()> {
- let writer = if self.unendable {
+ fn write_empty_to_frame(&mut self, element: &Element, frame: &mut String) -> Result<()> {
+ let _writer = if self.unendable {
self.inner.ignore_end()
} else {
self.inner.try_as_mut()?
@@ -306,12 +324,12 @@ impl Writer<WebSocket> {
Ok(())
}
- pub fn write_element_start_to_frame(
+ fn write_element_start_to_frame(
&mut self,
element: &Element,
frame: &mut String,
) -> Result<()> {
- let writer = if self.unendable {
+ let _writer = if self.unendable {
self.inner.ignore_end()
} else {
self.inner.try_as_mut()?
@@ -424,11 +442,11 @@ impl Writer<WebSocket> {
Ok(())
}
- pub fn write_content_to_frame(&mut self, content: &Content, frame: &mut String) -> Result<()> {
+ fn write_content_to_frame(&mut self, content: &Content, frame: &mut String) -> Result<()> {
match content {
Content::Element(element) => self.write_element_to_frame(element, frame)?,
Content::Text(text) => {
- let writer = if self.unendable {
+ let _writer = if self.unendable {
self.inner.ignore_end()
} else {
self.inner.try_as_mut()?
@@ -442,8 +460,8 @@ impl Writer<WebSocket> {
Ok(())
}
- pub fn write_end_tag_to_frame(&mut self, frame: &mut String) -> Result<()> {
- let writer = if self.unendable {
+ fn write_end_tag_to_frame(&mut self, frame: &mut String) -> Result<()> {
+ let _writer = if self.unendable {
self.inner.ignore_end()
} else {
self.inner.try_as_mut()?
@@ -491,8 +509,8 @@ impl Writer<WebSocket> {
}
}
-#[cfg(not(target_arch = "wasm32"))]
impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
+ /// Write an XML declaration with the provided `VersionInfo`.
pub async fn write_declaration(&mut self, version: VersionInfo) -> Result<()> {
let writer = if self.unendable {
self.inner.ignore_end()
@@ -516,53 +534,68 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
Ok(())
}
+ /// Write a full element corresponding with the item implementing `IntoElement` (start tag + content + end tag).
pub async fn write_full(&mut self, into_element: &impl IntoElement) -> Result<()> {
let element = into_element.into_element();
self.write_element(&element).await?;
- let bytes = &self.inner.ignore_end().take_log();
- let log = str::from_utf8(bytes).unwrap_or("failed to convert bytes written to str");
- info!("wrote element: {}", log);
+
+ let bytes = self.inner.ignore_end().take_log();
+ let log = String::from_utf8(bytes)
+ .map_err(|err| format!("failed to convert bytes written to str: {err}"));
+ info!("wrote element: {log:?}");
Ok(())
}
+ /// Write the start tag of an item that implements `IntoElement`. Navigates up the document.
pub async fn write_start(&mut self, into_element: &impl IntoElement) -> Result<()> {
let element = into_element.into_element();
self.write_element_start(&element).await?;
- let bytes = &self.inner.ignore_end().take_log();
- let log = str::from_utf8(bytes).unwrap_or("failed to convert bytes written to str");
- info!("wrote element start: {}", log);
+
+ let bytes = self.inner.ignore_end().take_log();
+ let log = String::from_utf8(bytes)
+ .map_err(|err| format!("failed to convert bytes written to str: {err}"));
+ info!("wrote element start: {log:?}");
Ok(())
}
+ /// Write all the inner content (everything within the start and end tag of an xml element) of an item that implements `IntoElement`. In the case of an empty element, write nothing.
pub async fn write_all_content(&mut self, into_element: &impl IntoElement) -> Result<()> {
for content in &into_element.get_content() {
self.write_content(content).await?;
}
- let bytes = &self.inner.ignore_end().take_log();
- let log = str::from_utf8(bytes).unwrap_or("failed to convert bytes written to str");
- info!("wrote element content: {}", log);
+
+ let bytes = self.inner.ignore_end().take_log();
+ let log = String::from_utf8(bytes)
+ .map_err(|err| format!("failed to convert bytes written to str: {err}"));
+ info!("wrote element content: {log:?}");
Ok(())
}
+ /// Write an item that implements `IntoContent`. Could be an element, some text, a comment, etc. Anything that could be included in an element body.
pub async fn write(&mut self, into_content: &impl IntoContent) -> Result<()> {
let content = into_content.into_content();
self.write_content(&content).await?;
- let bytes = &self.inner.ignore_end().take_log();
- let log = str::from_utf8(bytes).unwrap_or("failed to convert bytes written to str");
- info!("wrote element: {}", log);
+
+ let bytes = self.inner.ignore_end().take_log();
+ let log = String::from_utf8(bytes)
+ .map_err(|err| format!("failed to convert bytes written to str: {err}"));
+ info!("wrote element: {log:?}");
Ok(())
}
- // pub async fn write_end(&mut self)
+ /// Navigate down the document structure and write the end tag for the current element opened in the document context.
pub async fn write_end(&mut self) -> Result<()> {
self.write_end_tag().await?;
- let bytes = &self.inner.ignore_end().take_log();
- let log = str::from_utf8(bytes).unwrap_or("failed to convert bytes written to str");
- info!("wrote element end: {}", log);
+
+ let bytes = self.inner.ignore_end().take_log();
+ let log = String::from_utf8(bytes)
+ .map_err(|err| format!("failed to convert bytes written to str: {err}"));
+ info!("wrote element end: {log:?}");
Ok(())
}
#[async_recursion]
+ /// Write an `Element`.
pub async fn write_element(&mut self, element: &Element) -> Result<()> {
if element.content.is_empty() {
self.write_empty(element).await?;
@@ -576,6 +609,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
Ok(())
}
+ /// Write an empty element tag from an `Element` (ignoring any content).
pub async fn write_empty(&mut self, element: &Element) -> Result<()> {
let writer = if self.unendable {
self.inner.ignore_end()
@@ -690,6 +724,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
Ok(())
}
+ /// Write an element start tag from an `Element`, navigating up in document depth.
pub async fn write_element_start(&mut self, element: &Element) -> Result<()> {
let writer = if self.unendable {
self.inner.ignore_end()
@@ -803,6 +838,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
Ok(())
}
+ /// Write some `Content`.
pub async fn write_content(&mut self, content: &Content) -> Result<()> {
match content {
Content::Element(element) => self.write_element(element).await?,
@@ -821,6 +857,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
Ok(())
}
+ /// Write an end tag (depending on the current document context), moving back down in the document.
pub async fn write_end_tag(&mut self) -> Result<()> {
let writer = if self.unendable {
self.inner.ignore_end()
diff --git a/src/endable.rs b/src/writer/endable.rs
index 6d842f3..aede0cc 100644
--- a/src/endable.rs
+++ b/src/writer/endable.rs
@@ -1,3 +1,7 @@
+// SPDX-FileCopyrightText: 2025 cel <cel@bunny.garden>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
use crate::Error;
#[derive(Debug)]
diff --git a/src/loggable.rs b/src/writer/loggable.rs
index dd69668..894e173 100644
--- a/src/loggable.rs
+++ b/src/writer/loggable.rs
@@ -1,3 +1,7 @@
+// SPDX-FileCopyrightText: 2025 cel <cel@bunny.garden>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
use std::{fmt::Display, mem, pin::pin, task::Poll};
use futures::ready;
@@ -5,6 +9,7 @@ use pin_project::pin_project;
pub use tokio::io::AsyncWrite;
#[pin_project]
+/// Wrapper struct for logging writes to `AsyncWrite` implementors.
#[derive(Debug)]
pub struct Loggable<W> {
log_buffer: Vec<u8>,
@@ -32,8 +37,8 @@ impl<W> Loggable<W> {
impl<W: AsyncWrite + Unpin + Send> Display for Loggable<W> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
- let str = str::from_utf8(&self.log_buffer).unwrap_or("buffer to string conversion failed");
- f.write_str(str)
+ let str = String::from_utf8_lossy(&self.log_buffer);
+ write!(f, "{str}")
}
}
diff --git a/src/xml/composers.rs b/src/xml/composers.rs
index a47f007..160811f 100644
--- a/src/xml/composers.rs
+++ b/src/xml/composers.rs
@@ -1,3 +1,7 @@
+// SPDX-FileCopyrightText: 2025 cel <cel@bunny.garden>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
use std::{
fmt::{self, Display, Formatter, Write},
io,
diff --git a/src/xml/mod.rs b/src/xml/mod.rs
index 005a122..2bf960e 100644
--- a/src/xml/mod.rs
+++ b/src/xml/mod.rs
@@ -1,3 +1,7 @@
+// SPDX-FileCopyrightText: 2025 cel <cel@bunny.garden>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
use std::{char, ops::Deref};
use parsers_complete::Parser;
diff --git a/src/xml/parsers.rs b/src/xml/parsers.rs
index 79d72b4..b98d68a 100644
--- a/src/xml/parsers.rs
+++ b/src/xml/parsers.rs
@@ -1,3 +1,7 @@
+// SPDX-FileCopyrightText: 2025 cel <cel@bunny.garden>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
use nom::{
branch::alt,
bytes::streaming::{is_a, is_not, tag, take, take_while},
diff --git a/src/xml/parsers_complete.rs b/src/xml/parsers_complete.rs
index 1e2ac31..ae97d9e 100644
--- a/src/xml/parsers_complete.rs
+++ b/src/xml/parsers_complete.rs
@@ -1,3 +1,7 @@
+// SPDX-FileCopyrightText: 2025 cel <cel@bunny.garden>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
use nom::{
branch::alt,
bytes::complete::{is_a, is_not, tag, take, take_while},
generated by cgit (git 2.34.1) at 2025-12-25 20:08:10 +0000