From e225d7344cef05f03676f6579415999478328ead Mon Sep 17 00:00:00 2001
From: HampusM <hampus@hampusmat.com>
Date: Sat, 25 Feb 2023 20:36:06 +0100
Subject: feat: add variable list support

---
 src/description.rs | 89 +++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 72 insertions(+), 17 deletions(-)

(limited to 'src/description.rs')

diff --git a/src/description.rs b/src/description.rs
index adc5324..dfa521b 100644
--- a/src/description.rs
+++ b/src/description.rs
@@ -1,11 +1,12 @@
 //! Reference entry description.
+use crate::variable_list::{Error as VariableListError, VariableList};
 use crate::xml::element::{Elements, FromElements, Tagged};
 
 /// Reference entry description.
-#[derive(Debug)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Description
 {
-    paragraphs: Vec<Paragraph>,
+    parts: Vec<Part>,
 }
 
 impl Description
@@ -14,16 +15,14 @@ impl Description
     #[must_use]
     pub fn new() -> Self
     {
-        Self {
-            paragraphs: Vec::new(),
-        }
+        Self { parts: Vec::new() }
     }
 
-    /// Returns the reference description's paragraphs.
+    /// Returns the description's parts.
     #[must_use]
-    pub fn paragraphs(&self) -> &[Paragraph]
+    pub fn parts(&self) -> &[Part]
     {
-        &self.paragraphs
+        &self.parts
     }
 }
 
@@ -41,15 +40,27 @@ impl FromElements for Description
 
     fn from_elements(elements: &Elements) -> Result<Self, Self::Error>
     {
-        let paragraphs = elements
-            .get_all_tagged_elements_with_name("para")
+        let parts = elements
+            .get_all_tagged_elements()
             .into_iter()
-            .map(|paragraph_element| {
-                Paragraph::from_elements(paragraph_element.child_elements())
+            .filter_map(|part_elem| match part_elem.name() {
+                "para" => Some(
+                    Paragraph::from_elements(part_elem.child_elements())
+                        .map(Part::Paragraph)
+                        .map_err(Self::Error::InvalidParagraph),
+                ),
+
+                "variablelist" => Some(
+                    VariableList::from_elements(part_elem.child_elements())
+                        .map(Part::VariableList)
+                        .map_err(Self::Error::InvalidVariableList),
+                ),
+                "title" => None,
+                name => Some(Err(Self::Error::UnknownPartFound(name.to_string()))),
             })
-            .collect::<Result<Vec<_>, _>>()?;
+            .collect::<Result<Vec<_>, Self::Error>>()?;
 
-        Ok(Description { paragraphs })
+        Ok(Description { parts })
     }
 }
 
@@ -57,13 +68,32 @@ impl FromElements for Description
 #[derive(Debug, thiserror::Error)]
 pub enum Error
 {
+    /// Unknown part element found.
+    #[error("Unknown part element with name '{0}' found")]
+    UnknownPartFound(String),
+
     /// Invalid paragraph.
     #[error("Invalid paragraph")]
-    InvalidParagraph(#[from] ParagraphError),
+    InvalidParagraph(#[source] ParagraphError),
+
+    /// Invalid variable list.
+    #[error("Invalid variable list")]
+    InvalidVariableList(#[source] VariableListError),
+}
+
+/// Description part.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Part
+{
+    /// Paragraph.
+    Paragraph(Paragraph),
+
+    /// Variable list.
+    VariableList(VariableList),
 }
 
 /// Reference entry description paragraph.
-#[derive(Debug)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Paragraph
 {
     parts: Vec<ParagraphPart>,
@@ -71,6 +101,14 @@ pub struct Paragraph
 
 impl Paragraph
 {
+    /// Returns a new `Paragraph`.
+    pub fn new(parts: impl IntoIterator<Item = ParagraphPart>) -> Self
+    {
+        Self {
+            parts: parts.into_iter().collect(),
+        }
+    }
+
     /// Returns the parts of the paragraph.
     #[must_use]
     pub fn parts(&self) -> &[ParagraphPart]
@@ -106,7 +144,7 @@ pub enum ParagraphError
 }
 
 /// Reference entry description paragraph part.
-#[derive(Debug)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ParagraphPart
 {
     /// Text part.
@@ -123,6 +161,9 @@ pub enum ParagraphPart
 
     /// Reference entry citation part.
     Entry(String),
+
+    /// Variable list part.
+    VariableList(VariableList),
 }
 
 impl FromElements for ParagraphPart
@@ -154,6 +195,9 @@ impl ParagraphPart
             "function" => Self::Function,
             "parameter" => Self::Parameter,
             "citerefentry" => Self::Entry,
+            "variablelist" => |_| {
+                unreachable!();
+            },
             _ => {
                 return Err(<Self as FromElements>::Error::UnknownPart(
                     tagged_element.name().to_string(),
@@ -175,6 +219,13 @@ impl ParagraphPart
             return Ok(Self::Entry(title.clone()));
         }
 
+        if tagged_element.name() == "variablelist" {
+            let variable_list =
+                VariableList::from_elements(tagged_element.child_elements())?;
+
+            return Ok(Self::VariableList(variable_list));
+        }
+
         let text_element = tagged_element
             .child_elements()
             .get_first_text_element()
@@ -203,4 +254,8 @@ pub enum ParagraphPartError
     /// No entry title found.
     #[error("No entry title found")]
     NoEntryTitleFound,
+
+    /// Invalid variable list.
+    #[error("Invalid variable list")]
+    InvalidVariableList(#[from] VariableListError),
 }
-- 
cgit v1.2.3-18-g5258