aboutsummaryrefslogtreecommitdiffstats
path: root/src/writer.rs
diff options
context:
space:
mode:
Diffstat (limited to 'src/writer.rs')
-rw-r--r--src/writer.rs53
1 files changed, 38 insertions, 15 deletions
diff --git a/src/writer.rs b/src/writer.rs
index 40a935b..c30f03e 100644
--- a/src/writer.rs
+++ b/src/writer.rs
@@ -9,14 +9,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;
+use loggable::Loggable;
-// pub struct Writer<W, C = Composer> {
+mod endable;
+mod loggable;
+
+/// Writer that tracks depth and corresponding declared/available namespaces.
#[derive(Debug)]
pub struct Writer<W> {
inner: Endable<W>,
@@ -26,6 +29,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 +48,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 +67,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 +75,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 +94,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 +118,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 +142,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 +152,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 +162,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 +173,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 +183,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 +192,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 +205,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 +320,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 +438,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 +456,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 +505,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,6 +530,7 @@ 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?;
@@ -525,6 +540,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
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?;
@@ -534,6 +550,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
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?;
@@ -544,6 +561,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
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?;
@@ -553,7 +571,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
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();
@@ -563,6 +581,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
}
#[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 +595,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 +710,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 +824,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 +843,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()
generated by cgit (git 2.34.1) at 2025-06-07 15:28:31 +0000