diff --git a/src/attributes.rs b/src/attributes.rs index aed500c..36455ed 100644 --- a/src/attributes.rs +++ b/src/attributes.rs @@ -1,39 +1,65 @@ +//! Global attributes of MathML elements. + use std::fmt::Display; /// Direction for [`Attribute::Dir`]. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum Dir { + /// `rtl` direction. RightToLeft, + /// `ltr` direction. LeftToRight, } /// ScriptLevel for [`Attribute::ScriptLevel`]. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum ScriptLevel { + /// A positive number. Add(usize), + /// A negative number. Sub(usize), + /// A (positive) number. Num(usize), } +/// MathVariant for [`Attribute::MathVariant`]. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum MathVariant { + /// Normal variant. Normal, + /// Bold variant. Bold, + /// Italic variant. Italic, + /// Bold italic variant. BoldItalic, + /// Double struck variant. DoubleStruck, + /// Bold fraktur variant. BoldFraktur, + /// Script variant. Script, + /// Bold script variant. BoldScript, + /// Fraktur variant. Fraktur, + /// Sans serif variant. SansSerif, + /// Bold sans serif variant. BoldSansSerif, + /// Sans serif italic variant. SansSerifItalic, + /// Sans serif bold italic variant. SansSerifBoldItalic, + /// Monospace variant. Monospace, + /// Initial variant. Initial, + /// Tailed variant. Tailed, + /// Looped variant. Looped, + /// Stretched variant. Stretched, } @@ -121,6 +147,22 @@ pub enum Attribute { /// The `tabindex` attribute, same as in HTML. TabIndex(i16), + /// Event handler function, e.g. `onclick="..."`. + /// + /// # Example + /// ```rust + /// use alemat::{Attribute, BufMathMlWriter, Writer}; + /// + /// let handler = Attribute::OnHandler { + /// name: "click".to_string(), + /// handler: "console.log('Clicked!')".to_string(), + /// }; + /// + /// let mut writer = BufMathMlWriter::default(); + /// writer.write_attr(&handler); + /// let output = writer.finish(); + /// + /// assert_eq!(output, "onclick=\"console.log('Clicked!')\""); OnHandler { /// Name of the event. name: String, diff --git a/src/buf_writer.rs b/src/buf_writer.rs index cbf75d4..1c594ca 100644 --- a/src/buf_writer.rs +++ b/src/buf_writer.rs @@ -9,9 +9,10 @@ use crate::{ AnnotationAttr, AnnotationContent, FracAttr, Num, OperatorAttr, PaddedAttr, SpaceAttr, TableAttr, TableCellAttr, }, - Element, MathMlAttr, Renderer, Writer, + DisplayAttr, Element, MathMlAttr, Renderer, Writer, }; +/// Default implementation of MathMl [`Writer`]. #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct BufMathMlWriter { buf: String, @@ -580,7 +581,13 @@ impl Writer for BufMathMlWriter { self.write_str(" ")?; match attr { - MathMlAttr::Display(d) => write!(self, r#"display="{d}""#)?, + MathMlAttr::Display(d) => { + write!(self, r#"display=""#)?; + match d { + DisplayAttr::Block => write!(self, r#"block""#)?, + DisplayAttr::Inline => write!(self, r#"inline""#)?, + } + } MathMlAttr::AltText(alt_t) => write!(self, r#"alttext="{alt_t}""#)?, MathMlAttr::Global(a) => self.write_attr(a)?, } @@ -600,6 +607,10 @@ impl Writer for BufMathMlWriter { fn into_inner(self) -> Self::Buffer { self.buf } + + fn finish(&mut self) -> Self::Buffer { + std::mem::take(&mut self.buf) + } } impl Renderer for BufMathMlWriter { diff --git a/src/default_renderer.rs b/src/default_renderer.rs index d5e4a52..4061ffa 100644 --- a/src/default_renderer.rs +++ b/src/default_renderer.rs @@ -8,9 +8,10 @@ use crate::{ AnnotationAttr, AnnotationContent, FracAttr, Num, OperatorAttr, PaddedAttr, SpaceAttr, TableAttr, TableCellAttr, }, - Element, MathMlAttr, Renderer, + DisplayAttr, Element, MathMlAttr, Renderer, }; +/// Default MathMl [`Renderer`] implementation. #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct MathMlFormatter; @@ -521,7 +522,10 @@ impl Renderer for MathMlFormatter { .attr .iter() .map(|a| match a { - MathMlAttr::Display(d) => Ok(format!(r#"display="{d}""#)), + MathMlAttr::Display(d) => match d { + DisplayAttr::Block => Ok(String::from(r#"display="block""#)), + DisplayAttr::Inline => Ok(String::from(r#"display="inline""#)), + }, MathMlAttr::AltText(alt_t) => Ok(format!(r#"alttext="{alt_t}""#)), MathMlAttr::Global(a) => self.render_attr(a), }) diff --git a/src/elements.rs b/src/elements.rs index 4f98ace..efe19e7 100644 --- a/src/elements.rs +++ b/src/elements.rs @@ -2,16 +2,16 @@ //! elements. mod maction; -mod math; mod merror; mod mmultiscripts; mod mphantom; mod mrow; mod mstyle; +/// The grouping elements are `maction`, `math`, `merror`, `mphantom`, `mprescripts`, `mrow`, +/// `mstyle`, `semantics` and unknown MathML elements. pub mod grouping { pub use super::maction::*; - pub use super::math::*; pub use super::merror::*; pub use super::mmultiscripts::Prescripts; pub use super::mphantom::*; @@ -21,6 +21,8 @@ pub mod grouping { mod mroot; +/// The radical elements are `mroot` and `msqrt`. In this implementation both are constructed using +/// the [`Radical`] struct. pub mod radicals { pub use super::mroot::*; } @@ -28,6 +30,8 @@ pub mod radicals { mod msubsup; mod munderover; +/// The scripted elements are `mmultiscripts`, `mover`, `msub`, `msubsup`, `msup`, `munder` and +/// `munderover`. pub mod scripted { pub use super::mmultiscripts::Multiscripts; pub use super::msubsup::*; @@ -66,31 +70,74 @@ use self::{ scripted::UnderOver, }; +/// The MathML elements. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum Element { + /// `maction` element. Action(Action), + + /// `annotation` and `annotation-xml` elements. Annotation(Annotation), + + /// `merror` element. Error(Error), + + /// `mfrac` element. Frac(Frac), + + /// `mi` element. Ident(Ident), + + /// `mmultiscripts` element. Multiscripts(Multiscripts), + + /// `mprescripts` element. Prescripts(Prescripts), + + /// `mn` element. Num(Num), + + /// `mo` element. Operator(Operator), + + /// `mpadded` element. Padded(Padded), + + /// `mphantom` element. Phantom(Phantom), + + /// `mroot` and `msqrt` elements. Radical(Radical), + + /// `mrow` element. Row(Row), + + /// `msemantics` element. Semantics(Semantics), + + /// `mspace` element. Space(Space), + + /// `ms` element. StrLiteral(StrLiteral), + + /// `mstyle` Style(Style), + + /// `msub`, `msup` and `msubsup` elements. SubSup(SubSup), + + /// `mtable` element. Table(Table), + + /// `mtext` element. Text(Text), + + /// `munder`, `mover` and `munderover` elements. UnderOver(UnderOver), } +/// A list of [`Element`]s. #[repr(transparent)] #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct Elements(pub(crate) Vec); @@ -109,6 +156,7 @@ impl DerefMut for Elements { } impl Elements { + /// Consumes the [`Elements`] and returns a [`Vec`] of [`Element`]s. pub fn into_inner(self) -> Vec { self.0 } @@ -130,6 +178,7 @@ macro_rules! children { } } +/// Trait for conversion into [`Elements`]. pub trait IntoElements { /// Converts the type into elements. fn into_elements(self) -> Elements; diff --git a/src/elements/annotation.rs b/src/elements/annotation.rs index 4a64e96..918408c 100644 --- a/src/elements/annotation.rs +++ b/src/elements/annotation.rs @@ -11,7 +11,9 @@ use super::IntoElements; /// The content of `annotation` element, either text or MathML. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum AnnotationContent { + /// Text content of the `annotation` element. Implies the `annotation` variant. Text(String), + /// MathML content of the `annotation` element. Implies the `annotation-xml` variant. Nested(Elements), } @@ -42,6 +44,7 @@ impl From for AnnotationContent { /// [`Attribute`]: crate::attributes::Attribute #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum AnnotationAttr { + /// One of the global [`Attribute`]s. Global(Attribute), /// NOTE: Authors can use the encoding attribute to distinguish annotations for HTML @@ -78,19 +81,23 @@ pub struct Annotation { crate::element_from_type!(Annotation => Annotation); impl Annotation { + /// Create a builder for [`Annotation`] element. pub fn builder() -> AnnotationBuilder { AnnotationBuilder::default() } + /// Get a reference to the inner content of the [`Annotation`] element. pub fn content(&self) -> &AnnotationContent { &self.content } + /// Get a reference to all attributes of the [`Annotation`] element. pub fn attributes(&self) -> &[AnnotationAttr] { &self.attributes } } +/// Builder of the [`Annotation`] element. #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct AnnotationBuilder { content: Option, @@ -100,6 +107,7 @@ pub struct AnnotationBuilder { } impl AnnotationBuilder { + /// Set the content of the [`Annotation`] element. pub fn content(self, content: impl Into) -> AnnotationBuilder { AnnotationBuilder { content: Some(content.into()), @@ -108,6 +116,7 @@ impl AnnotationBuilder { } } + /// Add attributes. pub fn attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -119,6 +128,7 @@ impl AnnotationBuilder { } impl AnnotationBuilder { + /// Build the [`Annotation`] element. pub fn build(self) -> Annotation { Annotation { content: self @@ -143,14 +153,17 @@ pub struct Semantics { } impl Semantics { + /// Create a builder for [`Semantics`] element. pub fn builder() -> SemanticsBuilder { SemanticsBuilder::default() } + /// Get a reference to the inner content of the [`Semantics`] element. pub fn children(&self) -> &[Element] { &self.children } + /// Get a reference to all attributes of the [`Semantics`] element. pub fn attributes(&self) -> &[Attribute] { &self.attr } @@ -158,6 +171,7 @@ impl Semantics { crate::element_from_type!(Semantics => Semantics); +/// Builder of the [`Semantics`] element. #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct SemanticsBuilder { content: Option, @@ -167,6 +181,7 @@ pub struct SemanticsBuilder { } impl SemanticsBuilder { + /// Set the content of the [`Semantics`] element. pub fn content(self, content: impl IntoElements) -> SemanticsBuilder { SemanticsBuilder { content: Some(content.into_elements()), @@ -175,6 +190,7 @@ impl SemanticsBuilder { } } + /// Add attributes. pub fn attr(mut self, attr: A) -> Self where A: IntoIterator, @@ -185,6 +201,7 @@ impl SemanticsBuilder { } impl SemanticsBuilder { + /// Build the [`Semantics`] element. pub fn build(self) -> Semantics { Semantics { children: self diff --git a/src/elements/maction.rs b/src/elements/maction.rs index 41c91c4..4a3dbec 100644 --- a/src/elements/maction.rs +++ b/src/elements/maction.rs @@ -14,6 +14,7 @@ use super::IntoElements; /// [`Attribute`]: crate::attributes::Attribute #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum ActionAttr { + /// The of the global [`Attribute`]s. Global(Attribute), /// The child element currently visible, only taken into account for `actiontype="toggle"` or @@ -72,10 +73,12 @@ impl Action { ActionBuilder::default() } + /// Get a reference to the inner content of the [`Action`] element. pub fn content(&self) -> &[Element] { &self.content } + /// Get a reference to all attributes of the [`Action`] element. pub fn attributes(&self) -> &[ActionAttr] { &self.attributes } @@ -83,6 +86,7 @@ impl Action { crate::element_from_type!(Action => Action); +/// Builder of the [`Action`] element. #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct ActionBuilder { content: Option, @@ -92,6 +96,7 @@ pub struct ActionBuilder { } impl ActionBuilder { + /// Set the content of the [`Action`] element. pub fn content(self, content: impl IntoElements) -> ActionBuilder { ActionBuilder { content: Some(content.into_elements()), @@ -100,6 +105,7 @@ impl ActionBuilder { } } + /// Add attributes. pub fn attr(mut self, attributes: I) -> Self where I: IntoIterator, @@ -113,6 +119,7 @@ impl ActionBuilder { } impl ActionBuilder { + /// Build the [`Action`] element. pub fn build(self) -> Action { Action { content: self.content.expect("Content is guaranteed to be init."), diff --git a/src/elements/math.rs b/src/elements/math.rs deleted file mode 100644 index 59ccad4..0000000 --- a/src/elements/math.rs +++ /dev/null @@ -1,102 +0,0 @@ -use std::marker::PhantomData; - -use crate::{ - attributes::Attribute, - markers::{Init, Uninit}, - MathMl, -}; - -/// The display attribute, if present, must be an ASCII case-insensitive match to `block` or -/// `inline`. -#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] -pub enum DisplayAttr { - /// `block` display attribute. - Block, - - /// `inline` display attribute. - Inline, -} - -/// An attribute of `math` element. Either one of the global [`Attribute`]s, `display` or `alttext` -/// attribute. -/// -/// [`Attribute`]: crate::attributes::Attribute -#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] -pub enum MathAttr { - Global(Attribute), - Display(DisplayAttr), - AltText(String), -} - -// TODO: figure out if this element is actually needed. -/// MathML specifies a single top-level or root math element, which encapsulates each instance of -/// MathML markup within a document. All other MathML content must be contained in a `` -/// element. -#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] -pub struct Math { - content: MathMl, - attributes: Vec, -} - -impl Math { - /// Create new `math` element. - pub fn with_mathml(math: impl Into) -> Self { - Self { - content: math.into(), - attributes: Default::default(), - } - } - - pub fn builder() -> MathBuilder { - MathBuilder::default() - } -} - -impl From for Math -where - T: Into, -{ - fn from(value: T) -> Self { - Self { - content: value.into(), - attributes: Default::default(), - } - } -} - -#[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] -pub struct MathBuilder { - content: Option, - attributes: Vec, - - _marker: PhantomData<(T,)>, -} - -impl MathBuilder { - pub fn content(self, content: impl Into) -> MathBuilder { - MathBuilder { - content: Some(content.into()), - attributes: self.attributes, - - _marker: PhantomData, - } - } - - pub fn attr(mut self, attr: I) -> Self - where - I: IntoIterator, - A: Into, - { - self.attributes.extend(attr.into_iter().map(Into::into)); - self - } -} - -impl MathBuilder { - pub fn build(self) -> Math { - Math { - content: self.content.expect("Content is guaranteed to be init."), - attributes: self.attributes, - } - } -} diff --git a/src/elements/merror.rs b/src/elements/merror.rs index e26930b..0f05c76 100644 --- a/src/elements/merror.rs +++ b/src/elements/merror.rs @@ -26,14 +26,17 @@ impl Error { } } + /// Create a builder for [`Error`] element. pub fn builder() -> ErrorBuilder { ErrorBuilder::default() } + /// Get a reference to the inner content of the [`Error`] element. pub fn content(&self) -> &[Element] { &self.content } + /// Get a reference to all attributes of the [`Error`] element. pub fn attributes(&self) -> &[Attribute] { &self.attributes } @@ -59,6 +62,7 @@ impl From for Error { crate::element_from_type!(Error => Error); +/// Builder of the [`Error`] element. #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct ErrorBuilder { content: Option, @@ -68,6 +72,7 @@ pub struct ErrorBuilder { } impl ErrorBuilder { + /// Set the content of the [`Error`] element. pub fn content(self, content: impl IntoElements) -> ErrorBuilder { ErrorBuilder { content: Some(content.into_elements()), @@ -77,6 +82,7 @@ impl ErrorBuilder { } } + /// Add attributes. pub fn attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -88,6 +94,7 @@ impl ErrorBuilder { } impl ErrorBuilder { + /// Build [`Error`] element. pub fn build(self) -> Error { Error { content: self.content.expect("Content is guaranteed to be init."), diff --git a/src/elements/mfrac.rs b/src/elements/mfrac.rs index 2b60c93..40495ac 100644 --- a/src/elements/mfrac.rs +++ b/src/elements/mfrac.rs @@ -34,18 +34,22 @@ pub struct Frac { } impl Frac { + /// Create the builder for [`Frac`] element. pub fn builder() -> FracBuilder { FracBuilder::default() } + /// Get a reference to the content of the numerator. pub fn num(&self) -> &[Element] { &self.num } + /// Get a reference to the content of the denominator. pub fn denom(&self) -> &[Element] { &self.denom } + /// Get a reference to all attributes of the [`Frac`] element. pub fn attributes(&self) -> &[FracAttr] { &self.attributes } @@ -127,6 +131,7 @@ impl FracBuilder { } impl FracBuilder { + /// Build the [`Frac`] element. pub fn build(self) -> Frac { let num = self .num diff --git a/src/elements/mi/dict.rs b/src/elements/mi/dict.rs index 5f2c90a..dd21c16 100644 --- a/src/elements/mi/dict.rs +++ b/src/elements/mi/dict.rs @@ -1,5 +1,6 @@ use super::Ident; +#[allow(missing_docs)] impl Ident { pub fn empty_set() -> Self { Self::from("\u{2205}") diff --git a/src/elements/mi/mod.rs b/src/elements/mi/mod.rs index 628a918..6d180d5 100644 --- a/src/elements/mi/mod.rs +++ b/src/elements/mi/mod.rs @@ -16,14 +16,17 @@ pub struct Ident { } impl Ident { + /// Create a builder for [`Ident`] element. pub fn builder() -> IdentBuilder { IdentBuilder::default() } + /// Get a reference to the inner content of the [`Ident`] element. pub fn ident(&self) -> &str { &self.ident } + /// Get a reference to all attributes of the [`Ident`] element. pub fn attributes(&self) -> &[Attribute] { &self.attributes } @@ -43,6 +46,7 @@ where crate::element_from_type!(Ident => Ident); +/// Builder of the [`Ident`] element. #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct IdentBuilder { ident: Option, @@ -51,6 +55,7 @@ pub struct IdentBuilder { } impl IdentBuilder { + /// Set the identifier string for the [`Ident`] element. pub fn ident(self, ident: impl Into) -> IdentBuilder { IdentBuilder { ident: Some(ident.into()), @@ -59,6 +64,7 @@ impl IdentBuilder { } } + /// Add a attributes. pub fn attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -70,6 +76,7 @@ impl IdentBuilder { } impl IdentBuilder { + /// Build the [`Ident`] element. pub fn build(self) -> Ident { Ident { ident: self.ident.expect("Content is guaranteed to be init."), diff --git a/src/elements/mmultiscripts.rs b/src/elements/mmultiscripts.rs index aaabf6c..a1ade90 100644 --- a/src/elements/mmultiscripts.rs +++ b/src/elements/mmultiscripts.rs @@ -17,10 +17,12 @@ pub struct Multiscripts { } impl Multiscripts { + /// Get a reference to the inner content of the [`Multiscripts`] element. pub fn content(&self) -> &[Element] { &self.content } + /// Get a reference to all attributes of the [`Multiscripts`] element. pub fn attributes(&self) -> &[Attribute] { &self.attributes } @@ -36,6 +38,7 @@ impl From for Multiscripts { } impl Multiscripts { + /// Create a builder for [`Multiscripts`] element. pub fn builder() -> MultiscriptsBuilder { MultiscriptsBuilder::default() } @@ -88,6 +91,7 @@ pub struct Prescripts { } impl Prescripts { + /// Create a [`Prescripts`] element with the given attributes. pub fn with_attr(attr: I) -> Self where I: IntoIterator, @@ -98,6 +102,7 @@ impl Prescripts { } } + /// Get a reference to all attributes of the [`Prescripts`] element. pub fn attributes(&self) -> &[Attribute] { &self.attr } diff --git a/src/elements/mn.rs b/src/elements/mn.rs index c26c115..b67ad82 100644 --- a/src/elements/mn.rs +++ b/src/elements/mn.rs @@ -22,6 +22,7 @@ crate::from_types!(u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isiz |val| Num { num: format!("{}", val), attributes: Default::default() }); impl Num { + /// Add attributes to this instance of [`Num`]. pub fn add_attr(&mut self, attr: I) where I: IntoIterator, @@ -30,6 +31,7 @@ impl Num { self.attributes.extend(attr.into_iter().map(Into::into)); } + /// Create new instance of [`Num`] with additional attributes. pub fn with_attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -39,10 +41,12 @@ impl Num { self } + /// Get a reference to the inner content of the [`Num`] element. pub fn num(&self) -> &str { &self.num } + /// Get a reference to all attributes of the [`Num`] element. pub fn attributes(&self) -> &[Attribute] { &self.attributes } diff --git a/src/elements/mo/dict.rs b/src/elements/mo/dict.rs index 6c6b2b6..d601dde 100644 --- a/src/elements/mo/dict.rs +++ b/src/elements/mo/dict.rs @@ -1,5 +1,6 @@ use super::Operator; +#[allow(missing_docs)] impl Operator { pub fn plus() -> Self { Self::from("\u{002B}") diff --git a/src/elements/mo/mod.rs b/src/elements/mo/mod.rs index f15c5f6..82d956f 100644 --- a/src/elements/mo/mod.rs +++ b/src/elements/mo/mod.rs @@ -7,10 +7,14 @@ use crate::{ markers::{Init, Uninit}, }; +/// The possible values for `form` attribute of `mo` element. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum OpForm { + /// `infix` form. Default for operators like `Operator::plus()`. Infix, + /// `prefix` form. Default for operators like `Operator::lparens()`. Prefix, + /// `postfix` form. Default for operators like `Operator::rparens()`. Postfix, } @@ -108,14 +112,17 @@ where } impl Operator { + /// Create a builder for [`Operator`] element. pub fn builder() -> OperatorBuilder { OperatorBuilder::default() } + /// Get a reference to the inner content of the [`Operator`] element. pub fn op(&self) -> &str { &self.op } + /// Get a reference to all attributes of the [`Operator`] element. pub fn attributes(&self) -> &[OperatorAttr] { &self.attributes } @@ -123,6 +130,7 @@ impl Operator { crate::element_from_type!(Operator => Operator); +/// Builder of the [`Operator`] element. #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct OperatorBuilder { op: Option, @@ -131,6 +139,7 @@ pub struct OperatorBuilder { } impl OperatorBuilder { + /// Set the operator string for the [`Operator`] element. pub fn op(self, op: impl Into) -> OperatorBuilder { OperatorBuilder { op: Some(op.into()), @@ -139,6 +148,7 @@ impl OperatorBuilder { } } + /// Add a attributes to this [`Operator`] element. pub fn attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -150,6 +160,7 @@ impl OperatorBuilder { } impl OperatorBuilder { + /// Build the [`Operator`] element. pub fn build(self) -> Operator { Operator { op: self.op.expect("Op is guaranteed to be init."), diff --git a/src/elements/mpadded.rs b/src/elements/mpadded.rs index 1324885..50da847 100644 --- a/src/elements/mpadded.rs +++ b/src/elements/mpadded.rs @@ -9,12 +9,26 @@ use super::IntoElements; /// valid [``](https://www.w3.org/TR/css-values-4/#typedef-length-percentage). #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum PaddedAttr { + /// A `` indicating the desired horizontal length of the `mpadded` element. Width(String), + + /// A `` indicating the desired height (above the baseline) of the `mpadded` + /// element. Height(String), + + /// A `` indicating the desired depth (below the baseline) of the `mpadded` + /// element. Depth(String), + + /// A `` indicating the horizontal location of the positioning point of the + /// child content with respect to the positioning point of the `mpadded` element. LeftSpace(String), + + /// A `` indicating the vertical location of the positioning point of the + /// child content with respect to the positioning point of the `mpadded` element. VerticalOffset(String), + /// One of the global [`Attribute`]s. Global(Attribute), } @@ -54,6 +68,7 @@ where } impl Padded { + /// Add attributes. pub fn add_attr(&mut self, attr: I) where I: IntoIterator, @@ -62,6 +77,7 @@ impl Padded { self.attributes.extend(attr.into_iter().map(Into::into)); } + /// Create new instance of [`Padded`] with additional attributes. pub fn with_attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -71,10 +87,12 @@ impl Padded { self } + /// Get a reference to the children of the [`Padded`] element. pub fn children(&self) -> &[Element] { &self.children } + /// Get a reference to all attributes of the [`Padded`] element. pub fn attributes(&self) -> &[PaddedAttr] { &self.attributes } diff --git a/src/elements/mphantom.rs b/src/elements/mphantom.rs index 44cf327..645765f 100644 --- a/src/elements/mphantom.rs +++ b/src/elements/mphantom.rs @@ -38,6 +38,7 @@ impl> From<[I; N]> for Phantom { } impl Phantom { + /// Add attributes. pub fn add_attr(&mut self, attr: I) where I: IntoIterator, @@ -46,6 +47,7 @@ impl Phantom { self.attributes.extend(attr.into_iter().map(Into::into)); } + /// Create a new instance of [`Phantom`] with additional attributes. pub fn with_attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -55,10 +57,12 @@ impl Phantom { self } + /// Get a reference to the children of the [`Phantom`] element. pub fn children(&self) -> &[Element] { &self.children } + /// Get a reference to all attributes of the [`Phantom`] element. pub fn attributes(&self) -> &[Attribute] { &self.attributes } diff --git a/src/elements/mroot.rs b/src/elements/mroot.rs index 997576d..cf26b04 100644 --- a/src/elements/mroot.rs +++ b/src/elements/mroot.rs @@ -36,22 +36,27 @@ pub struct Radical { } impl Radical { + /// Create a builder for the [`Radical`] element. pub fn builder() -> RadicalsBuilder { RadicalsBuilder::default() } + /// Get a reference to the index of the radical. e.g. "2" for the square root. pub fn index(&self) -> &str { &self.index } + /// Check if the radical is a square root. pub fn is_square(&self) -> bool { self.index.parse::().map_or(false, |num| num == 2) } + /// Get a reference to the inner content of the [`Radical`] element. pub fn content(&self) -> &[Element] { &self.content } + /// Get a reference to all attributes of the [`Radical`] element. pub fn attributes(&self) -> &[Attribute] { &self.attributes } @@ -59,6 +64,7 @@ impl Radical { crate::element_from_type!(Radical => Radical); +/// Builder of the [`Radical`] element. #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct RadicalsBuilder { index: Option, @@ -69,6 +75,7 @@ pub struct RadicalsBuilder { } impl RadicalsBuilder { + /// Set the index of the radical. e.g. "2" for the square root. pub fn index(self, index: impl Into) -> RadicalsBuilder { RadicalsBuilder { index: Some(index.into()), @@ -99,6 +106,7 @@ impl RadicalsBuilder { } } + /// Add attributes. pub fn attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -110,6 +118,7 @@ impl RadicalsBuilder { } impl RadicalsBuilder { + /// Build the [`Radical`] element. pub fn build(self) -> Radical { let mut radical = Radical { index: self.index.expect("Index is guaranteed to be init."), diff --git a/src/elements/mrow.rs b/src/elements/mrow.rs index dbf3a6d..198834b 100644 --- a/src/elements/mrow.rs +++ b/src/elements/mrow.rs @@ -30,6 +30,7 @@ impl> From<[I; N]> for Row { } impl Row { + /// Add attributes. pub fn add_attr(&mut self, attr: I) where I: IntoIterator, @@ -38,6 +39,7 @@ impl Row { self.attr.extend(attr.into_iter().map(Into::into)); } + /// Create a new instance of [`Row`] with additional attributes. pub fn with_attr(mut self, attr: I) -> Self where I: Iterator, @@ -47,10 +49,12 @@ impl Row { self } + /// Get a reference to the children of the [`Row`] element. pub fn children(&self) -> &[Element] { &self.children } + /// Get a reference to all attributes of the [`Row`] element. pub fn attributes(&self) -> &[Attribute] { &self.attr } diff --git a/src/elements/ms.rs b/src/elements/ms.rs index 9109496..2da1951 100644 --- a/src/elements/ms.rs +++ b/src/elements/ms.rs @@ -21,6 +21,7 @@ where } impl StrLiteral { + /// Add attributes. pub fn add_attr(&mut self, attr: I) where I: IntoIterator, @@ -29,6 +30,7 @@ impl StrLiteral { self.attr.extend(attr.into_iter().map(Into::into)); } + /// Create a new instance of [`StrLiteral`] with additional attributes. pub fn with_attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -38,10 +40,12 @@ impl StrLiteral { self } + /// Get a reference to the literal content of the [`StrLiteral`] element. pub fn content(&self) -> &str { &self.literal } + /// Get a reference to all attributes of the [`StrLiteral`] element. pub fn attributes(&self) -> &[Attribute] { &self.attr } diff --git a/src/elements/mspace.rs b/src/elements/mspace.rs index 16c9235..4512bf2 100644 --- a/src/elements/mspace.rs +++ b/src/elements/mspace.rs @@ -43,6 +43,7 @@ pub struct Space { } impl Space { + /// Add attributes. pub fn add_attr(&mut self, attr: I) where I: IntoIterator, @@ -51,6 +52,7 @@ impl Space { self.attr.extend(attr.into_iter().map(Into::into)); } + /// Create a new instance of [`Space`] with additional attributes. pub fn with_attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -60,6 +62,7 @@ impl Space { self } + /// Get a reference to all attributes of the [`Space`] element. pub fn attributes(&self) -> &[SpaceAttr] { &self.attr } diff --git a/src/elements/mstyle.rs b/src/elements/mstyle.rs index d6ec533..afcd728 100644 --- a/src/elements/mstyle.rs +++ b/src/elements/mstyle.rs @@ -31,6 +31,7 @@ impl> From<[I; N]> for Style { } impl Style { + /// Add attributes. pub fn add_attr(&mut self, attr: I) where I: IntoIterator, @@ -39,6 +40,7 @@ impl Style { self.attr.extend(attr.into_iter().map(Into::into)); } + /// Create a new instance of [`Style`] with additional attributes. pub fn with_attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -48,10 +50,12 @@ impl Style { self } + /// Get a reference to the children of the [`Style`] element. pub fn children(&self) -> &[Element] { &self.children } + /// Get a reference to all attributes of the [`Style`] element. pub fn attributes(&self) -> &[Attribute] { &self.attr } diff --git a/src/elements/msubsup.rs b/src/elements/msubsup.rs index f237e4d..e29f124 100644 --- a/src/elements/msubsup.rs +++ b/src/elements/msubsup.rs @@ -27,10 +27,12 @@ pub struct SubSup { crate::element_from_type!(SubSup => SubSup); impl SubSup { + /// Create a builder for [`SubSup`] element. pub fn builder() -> SubSupBuilder { SubSupBuilder::default() } + /// Get a reference to the subscript content of the [`SubSup`] element if present. pub fn sub(&self) -> Option<&[Element]> { match self.inner { SubSupInner::Sub(ref sub) | SubSupInner::SubSup { ref sub, .. } => Some(sub), @@ -38,6 +40,7 @@ impl SubSup { } } + /// Get a reference to the superscript content of the [`SubSup`] element if present. pub fn sup(&self) -> Option<&[Element]> { match self.inner { SubSupInner::Sup(ref sup) | SubSupInner::SubSup { ref sup, .. } => Some(sup), @@ -45,15 +48,18 @@ impl SubSup { } } + /// Get a reference to the base content of the [`SubSup`] element. pub fn base(&self) -> &[Element] { &self.base } + /// Get a reference to all attributes of the [`SubSup`] element. pub fn attributes(&self) -> &[Attribute] { &self.attributes } } +/// Builder of the [`SubSup`] element. #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct SubSupBuilder { base: Option, @@ -64,6 +70,7 @@ pub struct SubSupBuilder { } impl SubSupBuilder { + /// Set the base of the [`SubSup`] element. pub fn base(self, base: impl IntoElements) -> SubSupBuilder { SubSupBuilder { base: Some(base.into_elements()), @@ -74,6 +81,7 @@ impl SubSupBuilder { } } + /// Set the subscript of the [`SubSup`] element. pub fn subscript(self, sub: impl IntoElements) -> SubSupBuilder { SubSupBuilder { base: self.base, @@ -84,6 +92,7 @@ impl SubSupBuilder { } } + /// Set the superscript of the [`SubSup`] element. pub fn supscript(self, sup: impl IntoElements) -> SubSupBuilder { SubSupBuilder { base: self.base, @@ -94,6 +103,7 @@ impl SubSupBuilder { } } + /// Add attributes. pub fn attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -105,6 +115,7 @@ impl SubSupBuilder { } impl SubSupBuilder { + /// Build the [`SubSup`] element. pub fn build(self) -> SubSup { debug_assert!( self.sub.is_some() || self.sup.is_some(), diff --git a/src/elements/mtable.rs b/src/elements/mtable.rs index df89968..d697b57 100644 --- a/src/elements/mtable.rs +++ b/src/elements/mtable.rs @@ -1,5 +1,6 @@ use crate::{attributes::Attribute, Element, Elements}; +/// One of the values for `columnlines` attribute. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum ColumnLine { /// No line is drawn. @@ -45,14 +46,17 @@ pub struct Table { } impl Table { + /// Get a reference to the [`Table`]s rows. pub fn rows(&self) -> &[TableRow] { &self.rows } + /// Add a [`TableRow`] to the [`Table`]. pub fn add_row(&mut self, row: TableRow) { self.rows.push(row); } + /// Add multiple [`TableRow`]s to the [`Table`]. pub fn add_rows(&mut self, rows: I) where I: IntoIterator, @@ -61,11 +65,13 @@ impl Table { self.rows.extend(rows.into_iter().map(Into::into)); } + /// Create a new instance of [`Table`] extended with the given [`TableRow`]. pub fn with_row(mut self, row: TableRow) -> Self { self.rows.push(row); self } + /// Create a new instance of [`Table`] extended with given [`TableRow`]s. pub fn with_rows(mut self, rows: I) -> Self where I: IntoIterator, @@ -75,9 +81,29 @@ impl Table { self } + /// Get a reference to the attributes of the [`Table`] element. pub fn attributes(&self) -> &[TableAttr] { &self.attributes } + + /// Add attributes. + pub fn add_attr(&mut self, attr: I) + where + I: IntoIterator, + A: Into, + { + self.attributes.extend(attr.into_iter().map(Into::into)); + } + + /// Create a new instance of [`Table`] with additional attributes. + pub fn with_attr(mut self, attr: I) -> Self + where + I: IntoIterator, + A: Into, + { + self.attributes.extend(attr.into_iter().map(Into::into)); + self + } } crate::element_from_type!(Table => Table); @@ -104,25 +130,6 @@ where } } -impl Table { - pub fn add_attr(&mut self, attr: I) - where - I: IntoIterator, - A: Into, - { - self.attributes.extend(attr.into_iter().map(Into::into)); - } - - pub fn with_attr(mut self, attr: I) -> Self - where - I: IntoIterator, - A: Into, - { - self.attributes.extend(attr.into_iter().map(Into::into)); - self - } -} - /// Create a [`Table`] easily using this macro. /// /// # Example @@ -176,6 +183,7 @@ where } impl TableRow { + /// Add attributes. pub fn add_attr(&mut self, attr: I) where I: IntoIterator, @@ -184,10 +192,12 @@ impl TableRow { self.attr.extend(attr.into_iter().map(Into::into)); } + /// Add a [`TableCell`] to this instance of [`TableRow`]. pub fn add_cell(&mut self, cell: TableCell) { self.cells.push(cell); } + /// Add multiple [`TableCell`]s to this instance of [`TableRow`]. pub fn add_cells(&mut self, cells: I) where I: IntoIterator, @@ -196,11 +206,13 @@ impl TableRow { self.cells.extend(cells.into_iter().map(Into::into)); } + /// Create a new instance of [`TableRow`] extended with the given [`TableCell`]. pub fn with_cell(mut self, cell: TableCell) -> Self { self.cells.push(cell); self } + /// Create a new instance of [`TableRow`] extended with given [`TableCell`]s. pub fn with_cells(mut self, cells: I) -> Self where I: IntoIterator, @@ -210,10 +222,12 @@ impl TableRow { self } + /// Get a reference to the cells of the [`TableRow`] element. pub fn cells(&self) -> &[TableCell] { &self.cells } + /// Get a reference to all attributes of the [`TableRow`] element. pub fn attributes(&self) -> &[Attribute] { &self.attr } @@ -331,14 +345,17 @@ impl> From<[I; N]> for TableCell { } impl TableCell { + /// Get a reference to the children of the [`TableCell`] element. pub fn children(&self) -> &[Element] { &self.children } + /// Get a reference to all attributes of the [`TableCell`] element. pub fn attributes(&self) -> &[TableCellAttr] { &self.attr } + /// Create a [`TableCell`] with the given content. pub fn with_content(content: impl IntoElements) -> Self { Self { children: content.into_elements(), @@ -346,6 +363,7 @@ impl TableCell { } } + /// Add attributes. pub fn add_attr(&mut self, attr: I) where I: IntoIterator, @@ -354,6 +372,7 @@ impl TableCell { self.attr.extend(attr.into_iter().map(Into::into)); } + /// Create a new instance of [`TableCell`] with additional attributes. pub fn with_attr(mut self, attr: I) -> Self where I: IntoIterator, diff --git a/src/elements/mtext.rs b/src/elements/mtext.rs index d6ece8c..80bc77e 100644 --- a/src/elements/mtext.rs +++ b/src/elements/mtext.rs @@ -24,6 +24,7 @@ where } impl Text { + /// Add attributes. pub fn add_attr(&mut self, attr: I) where I: IntoIterator, @@ -32,6 +33,7 @@ impl Text { self.attr.extend(attr.into_iter().map(Into::into)); } + /// Create a new instance of [`Text`] with additional attributes. pub fn with_attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -41,10 +43,12 @@ impl Text { self } + /// Get a reference to the text content of the [`Text`] element. pub fn text(&self) -> &str { &self.text } + /// Get a reference to all attributes of the [`Text`] element. pub fn attributes(&self) -> &[Attribute] { &self.attr } diff --git a/src/elements/munderover.rs b/src/elements/munderover.rs index 60ef85a..3730d5f 100644 --- a/src/elements/munderover.rs +++ b/src/elements/munderover.rs @@ -18,8 +18,15 @@ use super::IntoElements; /// attributes are absent or invalid, they are treated as equal to false. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum UnderOverAttr { + /// Indicates whether the under script should be treated as an accent (i.e. drawn bigger and + /// closer to the base expression). AccentUnder, + + /// Indicates whether the over script should be treated as an accent (i.e. drawn bigger and + /// closer to the base expression). AccentOver, + + /// One of the global [`Attribute`]s. Global(Attribute), } @@ -40,14 +47,17 @@ pub struct UnderOver { } impl UnderOver { + /// Create a builder for [`UnderOver`] element. pub fn builder() -> UnderOverBuilder { UnderOverBuilder::default() } + /// Get a reference to the base content of the [`UnderOver`] element. pub fn expr(&self) -> &[Element] { &self.expr } + /// Get a reference to the under script content of the [`UnderOver`] element if present. pub fn under(&self) -> Option<&[Element]> { match self.inner { UnderOverInner::Under(ref under) | UnderOverInner::UnderOver { ref under, .. } => { @@ -57,6 +67,7 @@ impl UnderOver { } } + /// Get a reference to the over script content of the [`UnderOver`] element if present. pub fn over(&self) -> Option<&[Element]> { match self.inner { UnderOverInner::Over(ref over) | UnderOverInner::UnderOver { ref over, .. } => { @@ -66,6 +77,7 @@ impl UnderOver { } } + /// Get a reference to all attributes of the [`UnderOver`] element. pub fn attributes(&self) -> &[UnderOverAttr] { &self.attributes } @@ -73,6 +85,7 @@ impl UnderOver { crate::element_from_type!(UnderOver => UnderOver); +/// Builder of the [`UnderOver`] element. #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct UnderOverBuilder { expr: Option, @@ -84,6 +97,7 @@ pub struct UnderOverBuilder { } impl UnderOverBuilder { + /// Set the base expression of the [`UnderOver`] element. pub fn expr(self, expr: impl IntoElements) -> UnderOverBuilder { UnderOverBuilder { expr: Some(expr.into_elements()), @@ -95,6 +109,7 @@ impl UnderOverBuilder { } } + /// Set the under script of the [`UnderOver`] element. pub fn over(self, over: impl IntoElements) -> UnderOverBuilder { UnderOverBuilder { expr: self.expr, @@ -105,6 +120,7 @@ impl UnderOverBuilder { } } + /// Set the over script of the [`UnderOver`] element. pub fn under(self, under: impl IntoElements) -> UnderOverBuilder { UnderOverBuilder { expr: self.expr, @@ -115,6 +131,7 @@ impl UnderOverBuilder { } } + /// Add attributes. pub fn attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -126,6 +143,7 @@ impl UnderOverBuilder { } impl UnderOverBuilder { + /// Build the [`UnderOver`] element. pub fn build(self) -> UnderOver { debug_assert!( self.over.is_some() || self.under.is_some(), diff --git a/src/lib.rs b/src/lib.rs index a473df4..3bf8ce6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,4 +1,5 @@ -//! Library for type-safe building of MathML. +#![warn(missing_docs)] +//! Library for type-safe building of MathML (core) markup. pub mod attributes; mod buf_writer; @@ -7,37 +8,71 @@ pub mod elements; pub mod markers; mod to_mathml; -use attributes::Attribute; -use buf_writer::BufMathMlWriter; +pub use attributes::Attribute; +pub use buf_writer::BufMathMlWriter; pub use default_renderer::MathMlFormatter; pub(crate) use elements::element_from_type; use elements::IntoElements; pub use elements::{Element, Elements}; pub use to_mathml::*; +/// Specifies how the enclosed MathML markup should be rendered. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] +pub enum DisplayAttr { + /// `block` display attribute. The element will be displayed in its own block outside the + /// current span of text and with math-style set to normal. + Block, + + /// `inline` display attribute. The element will be displayed inside the current span of text + /// and with math-style set to compact. + Inline, +} + +/// Attributes of the `math` ([`MathMl`]) element. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum MathMlAttr { - Display(String), + /// This enumerated attribute specifies how the enclosed MathML markup should be rendered. It + /// can have one of the following values: + /// + /// * `block`, which means that this element will be displayed in its own block outside the + /// current span of text and with math-style set to normal. + /// * `inline`, which means that this element will be displayed inside the current span of + /// text and with math-style set to compact. + /// + /// If not present, its default value is `inline`. + Display(DisplayAttr), + + /// The alttext attribute may be used as alternative text by some legacy systems that do not + /// implement math layout. AltText(String), + /// One of the global [`Attribute`]s. Global(Attribute), } +/// The `MathMl` is the `math` - the top-level MathML element, used to write a single mathematical +/// formula. It can be placed in HTML content where flow content is permitted. #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct MathMl { + /// Inner content of the `math` element. content: Elements, + + /// Attributes of the `math` element. attr: Vec, } impl MathMl { + /// Get a reference to the inner content of the `math` element. pub fn content(&self) -> &Elements { &self.content } + /// Get a reference to all attributes of the `math` element. pub fn attributes(&self) -> &[MathMlAttr] { &self.attr } + /// Create a new `math` element with the given content. pub fn with_content(content: impl IntoElements) -> Self { Self { content: content.into_elements(), @@ -45,14 +80,17 @@ impl MathMl { } } + /// Append more content to this `math` element. pub fn append_content(&mut self, content: impl IntoElements) { self.content.append(&mut content.into_elements()); } + /// Add a single attribute to this `math` element. pub fn add_attr(&mut self, attr: impl Into) { self.attr.push(attr.into()); } + /// Create new instance of `MathMl` with additional attributes. pub fn with_attr(mut self, attr: I) -> Self where I: IntoIterator, @@ -62,6 +100,7 @@ impl MathMl { self } + /// Extend the attributes of this `math` element. pub fn extend_attr(&mut self, attr: I) where I: IntoIterator, @@ -70,23 +109,32 @@ impl MathMl { self.attr.extend(attr.into_iter().map(Into::into)) } + /// Return the number of elements this `math` element contains. pub fn len(&self) -> usize { self.content.len() } + /// Check whether this `math` element contains no elements. pub fn is_empty(&self) -> bool { self.content.is_empty() } + /// Render this `math` element and its children using the given renderer. pub fn render_with(&self, renderer: &mut R) -> Result { renderer.render_mathml(self) } - pub fn render(&self) -> Result::Error> { - let mut buf_writer = BufMathMlWriter::default(); - buf_writer.write_mathml(self)?; + /// Write this `math` element and its children using the given writer. + pub fn write(&self, writer: &mut W) -> Result { + writer.write_mathml(self)?; + Ok(writer.finish()) + } - Ok(buf_writer.into_inner()) + /// Render this `math` element and its children using the default renderer. + /// + /// In this implementation, [`BufMathMlWriter`] is used. + pub fn render(&self) -> Result::Error> { + self.write(&mut BufMathMlWriter::default()) } } diff --git a/src/markers.rs b/src/markers.rs index c5c2283..9579153 100644 --- a/src/markers.rs +++ b/src/markers.rs @@ -1,7 +1,13 @@ +//! Marker types used in builders. + #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] #[doc(hidden)] +/// Marker type used in builders to indicate that a particular value has been initialized. +/// This is not intended to be used dirctly. pub struct Init; #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] #[doc(hidden)] +/// Marker type used in builders to indicate that a particular value has not been initialized. +/// This is not intended to be used dirctly. pub struct Uninit; diff --git a/src/to_mathml.rs b/src/to_mathml.rs index 8358b62..9f85331 100644 --- a/src/to_mathml.rs +++ b/src/to_mathml.rs @@ -1,3 +1,5 @@ +//! This module provides traits for rendering MathML elements. + use std::borrow::Borrow; use crate::{ @@ -11,30 +13,48 @@ use crate::{ Element, MathMl, }; +/// Trait for rendering MathML elements. Each method in this trait has a default implementation +/// that returns [`Result::Ok`] with an empty [`String`]. +/// This makes it possible to potentially introduce new elements without breaking existing +/// renderers. +/// This means that any new elements introduced will be omitted in the final render, if the +/// corresponding methods are not implemented. pub trait Renderer { + /// The `Output` type of the renderer that will be returned by `render_*` methods. type Output; + + /// The `Error` type of the renderer that will be returned by `render_*` methods in cases where + /// rendering can fail. Use [`Infallible`] for renderers that cannot fail. + /// + /// [`Infallible`]: std::convert::Infallible type Error; + /// Render an [`Action`] element. fn render_action(&mut self, action: &Action) -> Result { unimplemented!("Rendering of {:?} not implemented", action); } + /// Render an [`Annotation`] element. fn render_annotation(&mut self, annotation: &Annotation) -> Result { unimplemented!("Rendering of {:?} not implemented", annotation); } + /// Render an [`Error`] element. fn render_error(&mut self, error: &Error) -> Result { unimplemented!("Rendering of {:?} not implemented", error); } + /// Render a [`Frac`] element. fn render_frac(&mut self, frac: &Frac) -> Result { unimplemented!("Rendering of {:?} not implemented", frac); } + /// Render an [`Ident`] element. fn render_ident(&mut self, ident: &Ident) -> Result { unimplemented!("Rendering of {:?} not implemented", ident); } + /// Render a [`Multiscripts`] element. fn render_multiscripts( &mut self, multiscripts: &Multiscripts, @@ -42,42 +62,52 @@ pub trait Renderer { unimplemented!("Rendering of {:?} not implemented", multiscripts); } + /// Render a [`Prescripts`] element. fn render_prescripts(&mut self, prescripts: &Prescripts) -> Result { unimplemented!("Rendering of {:?} not implemented", prescripts); } + /// Render a [`Num`] element. fn render_num(&mut self, num: &Num) -> Result { unimplemented!("Rendering of {:?} not implemented", num); } + /// Render an [`Operator`] element. fn render_operator(&mut self, operator: &Operator) -> Result { unimplemented!("Rendering of {:?} not implemented", operator); } + /// Render a [`Padded`] element. fn render_padded(&mut self, padded: &Padded) -> Result { unimplemented!("Rendering of {:?} not implemented", padded); } + /// Render a [`Phantom`] element. fn render_phantom(&mut self, phantom: &Phantom) -> Result { unimplemented!("Rendering of {:?} not implemented", phantom); } + /// Render a [`Radical`] element. fn render_radical(&mut self, radical: &Radical) -> Result { unimplemented!("Rendering of {:?} not implemented", radical); } + /// Render a [`Row`] element. fn render_row(&mut self, row: &Row) -> Result { unimplemented!("Rendering of {:?} not implemented", row); } + /// Render a [`Semantics`] element. fn render_semantics(&mut self, semantics: &Semantics) -> Result { unimplemented!("Rendering of {:?} not implemented", semantics); } + /// Render a [`Space`] element. fn render_space(&mut self, space: &Space) -> Result { unimplemented!("Rendering of {:?} not implemented", space); } + /// Render a [`StrLiteral`] element. fn render_str_literal( &mut self, str_literal: &StrLiteral, @@ -85,30 +115,37 @@ pub trait Renderer { unimplemented!("Rendering of {:?} not implemented", str_literal); } + /// Render a [`Style`] element. fn render_style(&mut self, style: &Style) -> Result { unimplemented!("Rendering of {:?} not implemented", style); } + /// Render a [`SubSup`] element. fn render_subsup(&mut self, sub_sup: &SubSup) -> Result { unimplemented!("Rendering of {:?} not implemented", sub_sup); } + /// Render a [`Table`] element. fn render_table(&mut self, table: &Table) -> Result { unimplemented!("Rendering of {:?} not implemented", table); } + /// Render a [`Text`] element. fn render_text(&mut self, text: &Text) -> Result { unimplemented!("Rendering of {:?} not implemented", text); } + /// Render an [`UnderOver`] element. fn render_underover(&mut self, under_over: &UnderOver) -> Result { unimplemented!("Rendering of {:?} not implemented", under_over); } + /// Render an [`Attribute`] element. fn render_attr(&mut self, attr: &Attribute) -> Result { unimplemented!("Rendering of {:?} not implemented", attr); } + /// Render an [`Element`] element. fn render_element(&mut self, element: &Element) -> Result { match element { Element::Action(action) => self.render_action(action), @@ -135,103 +172,146 @@ pub trait Renderer { } } + /// Render a [`MathMl`] element. fn render_mathml(&mut self, mathml: &MathMl) -> Result { unimplemented!("Rendering of {:?} not implemented", mathml) } } +/// Trait for writing MathML elements. Each method in this trait has a default implementation that +/// does nothing. +/// +/// In contrast with [`Renderer`] trait, implementors of this trait are meant to write the rendered +/// representation into a buffer instead of returning the rendered output from each function. +/// This enables buffered rendering, where instead of allocating many [`String`]s (for example), +/// one [`String`] is allocated and written into. +/// +/// Each method in this trait has a default implementation that corresponds to a no-op. +/// This makes it possible to potentially introduce new elements without breaking existing +/// renderers. +/// This also means that any new elements introduced will be omitted in the final render, as long +/// as the corresponding methods are not implemented. pub trait Writer { + /// The type of the buffer that this writer writes into. type Buffer; + + /// The `Error` type of the writer that will be returned by `write_*` methods in cases where + /// writing can fail. Use [`Infallible`] for writers that cannot fail. + /// + /// [`Infallible`]: std::convert::Infallible type Error; - fn write_action(&mut self, action: &Action) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", action); + /// Write an [`Action`] element. + fn write_action(&mut self, _action: &Action) -> Result<(), Self::Error> { + Ok(()) } - fn write_annotation(&mut self, annotation: &Annotation) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", annotation); + /// Write an [`Annotation`] element. + fn write_annotation(&mut self, _annotation: &Annotation) -> Result<(), Self::Error> { + Ok(()) } - fn write_error(&mut self, error: &Error) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", error); + /// Write an [`Error`] element. + fn write_error(&mut self, _error: &Error) -> Result<(), Self::Error> { + Ok(()) } - fn write_frac(&mut self, frac: &Frac) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", frac); + /// Write a [`Frac`] element. + fn write_frac(&mut self, _frac: &Frac) -> Result<(), Self::Error> { + Ok(()) } - fn write_ident(&mut self, ident: &Ident) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", ident); + /// Write an [`Ident`] element. + fn write_ident(&mut self, _ident: &Ident) -> Result<(), Self::Error> { + Ok(()) } - fn write_multiscripts(&mut self, multiscripts: &Multiscripts) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", multiscripts); + /// Write a [`Multiscripts`] element. + fn write_multiscripts(&mut self, _multiscripts: &Multiscripts) -> Result<(), Self::Error> { + Ok(()) } - fn write_prescripts(&mut self, prescripts: &Prescripts) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", prescripts); + /// Write a [`Prescripts`] element. + fn write_prescripts(&mut self, _prescripts: &Prescripts) -> Result<(), Self::Error> { + Ok(()) } - fn write_num(&mut self, num: &Num) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", num); + /// Write a [`Num`] element. + fn write_num(&mut self, _num: &Num) -> Result<(), Self::Error> { + Ok(()) } - fn write_operator(&mut self, operator: &Operator) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", operator); + /// Write an [`Operator`] element. + fn write_operator(&mut self, _operator: &Operator) -> Result<(), Self::Error> { + Ok(()) } - fn write_padded(&mut self, padded: &Padded) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", padded); + /// Write a [`Padded`] element. + fn write_padded(&mut self, _padded: &Padded) -> Result<(), Self::Error> { + Ok(()) } - fn write_phantom(&mut self, phantom: &Phantom) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", phantom); + /// Write a [`Phantom`] element. + fn write_phantom(&mut self, _phantom: &Phantom) -> Result<(), Self::Error> { + Ok(()) } - fn write_radical(&mut self, radical: &Radical) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", radical); + /// Write a [`Radical`] element. + fn write_radical(&mut self, _radical: &Radical) -> Result<(), Self::Error> { + Ok(()) } - fn write_row(&mut self, row: &Row) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", row); + /// Write a [`Row`] element. + fn write_row(&mut self, _row: &Row) -> Result<(), Self::Error> { + Ok(()) } - fn write_semantics(&mut self, semantics: &Semantics) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", semantics); + /// Write a [`Semantics`] element. + fn write_semantics(&mut self, _semantics: &Semantics) -> Result<(), Self::Error> { + Ok(()) } - fn write_space(&mut self, space: &Space) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", space); + /// Write a [`Space`] element. + fn write_space(&mut self, _space: &Space) -> Result<(), Self::Error> { + Ok(()) } - fn write_str_literal(&mut self, str_literal: &StrLiteral) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", str_literal); + /// Write a [`StrLiteral`] element. + fn write_str_literal(&mut self, _str_literal: &StrLiteral) -> Result<(), Self::Error> { + Ok(()) } - fn write_style(&mut self, style: &Style) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", style); + /// Write a [`Style`] element. + fn write_style(&mut self, _style: &Style) -> Result<(), Self::Error> { + Ok(()) } - fn write_subsup(&mut self, sub_sup: &SubSup) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", sub_sup); + /// Write a [`SubSup`] element. + fn write_subsup(&mut self, _sub_sup: &SubSup) -> Result<(), Self::Error> { + Ok(()) } - fn write_table(&mut self, table: &Table) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", table); + /// Write a [`Table`] element. + fn write_table(&mut self, _table: &Table) -> Result<(), Self::Error> { + Ok(()) } - fn write_text(&mut self, text: &Text) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", text); + /// Write a [`Text`] element. + fn write_text(&mut self, _text: &Text) -> Result<(), Self::Error> { + Ok(()) } - fn write_underover(&mut self, under_over: &UnderOver) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", under_over); + /// Write an [`UnderOver`] element. + fn write_underover(&mut self, _under_over: &UnderOver) -> Result<(), Self::Error> { + Ok(()) } - fn write_attr(&mut self, attr: &Attribute) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", attr); + /// Write an [`Attribute`] element. + fn write_attr(&mut self, _attr: &Attribute) -> Result<(), Self::Error> { + Ok(()) } + /// Write an [`Element`] into the `Self::Buffer`. fn write_element(&mut self, tag: &Element) -> Result<(), Self::Error> { match tag { Element::Action(action) => self.write_action(action), @@ -258,13 +338,23 @@ pub trait Writer { } } + /// Write a [`MathMl`] element. fn write_mathml(&mut self, mathml: &MathMl) -> Result<(), Self::Error> { - unimplemented!("Rendering of {:?} not implemented", mathml) + for element in mathml.content().iter() { + self.write_element(element)?; + } + + Ok(()) } + /// Return a reference to the buffer. fn buffer(&self) -> &T where Self::Buffer: Borrow; + /// Produce a rendered representation of the [`MathMl`] content written into the [`Writer`]. + fn finish(&mut self) -> Self::Buffer; + + /// Consume the [`Writer`] and return the inner buffer. fn into_inner(self) -> Self::Buffer; } diff --git a/tests/scripted/mod.rs b/tests/scripted/mod.rs index 8a2d286..8608d0d 100644 --- a/tests/scripted/mod.rs +++ b/tests/scripted/mod.rs @@ -1,6 +1,6 @@ use alemat::elements::scripted::{SubSup, UnderOver}; use alemat::elements::{Ident, Num, Operator, Text}; -use alemat::{MathMl, MathMlAttr}; +use alemat::{DisplayAttr, MathMl, MathMlAttr}; #[test] fn subsup() { @@ -27,7 +27,7 @@ fn subsup_integral() { Ident::from("x"), Ident::from("dx"), ]) - .with_attr([MathMlAttr::Display(String::from("block"))]) + .with_attr([MathMlAttr::Display(DisplayAttr::Block)]) .render(); crate::snap_test!(out, name: "subsup_integral"); @@ -46,7 +46,7 @@ fn subsup_summation() { .supscript(Ident::from("i")) .build() ]) - .with_attr([MathMlAttr::Display(String::from("block"))]) + .with_attr([MathMlAttr::Display(DisplayAttr::Block)]) .render(); crate::snap_test!(out, name: "subsup_summation"); @@ -77,7 +77,7 @@ fn underover_integral() { Ident::from("x"), Ident::from("dx"), ]) - .with_attr([MathMlAttr::Display(String::from("block"))]) + .with_attr([MathMlAttr::Display(DisplayAttr::Block)]) .render(); crate::snap_test!(out, name: "underover_integral"); @@ -96,7 +96,7 @@ fn underover_summation() { .supscript(Ident::from("i")) .build() ]) - .with_attr([MathMlAttr::Display(String::from("block"))]) + .with_attr([MathMlAttr::Display(DisplayAttr::Block)]) .render(); crate::snap_test!(out, name: "underover_summation");