opml/opml_api/source/lib.rs

//! This crate provides an API to parse and create [OPML documents].
//!
//! [OPML documents]: http://opml.org/spec2.opml
//!
//! ## Parsing
//!
//! To parse an OPML document use [`OPML::from_str`] or [`OPML::from_reader`].
//!
//! Parsing will result in an error if:
//! * the XML is malformed,
//! * the included OPML version is not supported (currently all OPML versions
//!   (1.0, 1.1 and 2.0) are supported) or,
//! * if the [`Body`] element contains no child [`Outline`] elements,
//!   [as per the spec].
//!
//! [as per the spec]: http://opml.org/spec2.opml#1629042198000
//!
//! ```rust
//! use opml::OPML;
//!
//! let xml = r#"<opml version="2.0"><head/><body><outline text="Outline"/></body></opml>"#;
//! let document = OPML::from_str(xml).unwrap();
//!
//! assert_eq!(document.version, "2.0");
//! ```
//!
//! ## Creating
//!
//! To create an OPML document from scratch, use [`OPML::default()`] or the good
//! old `OPML { /* ... */ }` syntax.

#![forbid(unsafe_code)]
#![warn(missing_docs, clippy::missing_docs_in_private_items)]

use hard_xml::{XmlRead, XmlWrite};
use serde::{Deserialize, Serialize};
use thiserror::Error;

/// All possible errors.
#[derive(Debug, Error)]
pub enum Error {
  /// [From the spec], "a `<body>` contains one or more `<outline>` elements".
  ///
  /// [From the spec]: http://opml.org/spec2.opml#1629042198000
  #[error("OPML body has no <outline> elements")]
  BodyHasNoOutlines,

  /// Wrapper for [`std::io::Error`].
  #[error("Failed to read file")]
  IoError(#[from] std::io::Error),

  /// The version string in the XML is not supported.
  #[error("Unsupported OPML version: {0:?}")]
  UnsupportedVersion(String),

  /// The input string is not valid XML.
  #[error("Failed to process XML file")]
  XmlError(#[from] hard_xml::XmlError),
}

/// The top-level [`OPML`] element.
#[derive(
  XmlWrite, XmlRead, PartialEq, Eq, Debug, Clone, Serialize, Deserialize,
)]
#[xml(tag = "opml")]
pub struct OPML {
  /// The version attribute from the element, valid values are `1.0`, `1.1` and
  /// `2.0`.
  #[xml(attr = "version")]
  pub version: String,

  /// The [`Head`] child element. Contains the metadata of the OPML document.
  #[xml(child = "head")]
  pub head: Option<Head>,

  /// The [`Body`] child element. Contains all the [`Outline`] elements.
  #[xml(child = "body")]
  pub body: Body,
}

impl OPML {
  /// Deprecated, use [`OPML::from_str`] instead.
  #[deprecated(note = "Use from_str instead", since = "1.1.0")]
  pub fn new(xml: &str) -> Result<Self, Error> {
    Self::from_str(xml).map_err(Into::into)
  }

  /// Parses an OPML document.
  ///
  /// # Example
  ///
  /// ```rust
  /// use opml::{OPML, Outline};
  ///
  /// let xml = r#"<opml version="2.0"><head/><body><outline text="Outline"/></body></opml>"#;
  /// let document = OPML::from_str(xml).unwrap();
  ///
  /// let mut expected = OPML::default();
  /// expected.body.outlines.push(Outline {
  ///   text: "Outline".to_string(),
  ///   ..Outline::default()
  /// });
  ///
  /// assert_eq!(document, expected);
  /// ```
  #[allow(clippy::should_implement_trait)]
  pub fn from_str(xml: &str) -> Result<Self, Error> {
    let opml = <OPML as XmlRead>::from_str(xml)?;

    // SPEC: The version attribute is a version string, of the form, x.y, where
    // x and y are both numeric strings.
    let valid_versions = ["1.0", "1.1", "2.0"];

    if !valid_versions.contains(&opml.version.as_str()) {
      return Err(Error::UnsupportedVersion(opml.version));
    }

    // SPEC: A `<body>` contains one or more `<outline>` elements.
    if opml.body.outlines.is_empty() {
      return Err(Error::BodyHasNoOutlines);
    }

    Ok(opml)
  }

  /// Parses an OPML document from a reader.
  ///
  /// # Example
  ///
  /// ```rust,no_run
  /// use opml::OPML;
  ///
  /// let mut file = std::fs::File::open("file.opml").unwrap();
  /// let document = OPML::from_reader(&mut file).unwrap();
  /// ```
  pub fn from_reader<R>(reader: &mut R) -> Result<Self, Error>
  where
    R: std::io::Read,
  {
    let mut s = String::new();
    reader.read_to_string(&mut s)?;
    Self::from_str(&s).map_err(Into::into)
  }

  /// Helper function to add an [`Outline`] element with `text` and `xml_url`
  /// attributes to the [`Body`]. Useful for creating feed lists quickly.
  /// This function also exists as [`Outline::add_feed`] for grouped lists.
  ///
  /// # Example
  ///
  /// ```rust
  /// use opml::{OPML, Outline};
  ///
  /// let mut opml = OPML::default();
  /// opml.add_feed("Feed Name", "https://example.com/");
  /// let added_feed = opml.body.outlines.first().unwrap();
  ///
  /// let expected_feed = &Outline {
  ///   text: "Feed Name".to_string(),
  ///   xml_url: Some("https://example.com/".to_string()),
  ///   ..Outline::default()
  /// };
  ///
  /// assert_eq!(added_feed, expected_feed);
  /// ```
  pub fn add_feed(&mut self, text: &str, url: &str) -> &mut Self {
    self.body.outlines.push(Outline {
      text: text.to_string(),
      xml_url: Some(url.to_string()),
      ..Outline::default()
    });

    self
  }

  /// Deprecated, use [`OPML::to_string`] instead.
  #[deprecated(note = "Use to_string instead", since = "1.1.0")]
  pub fn to_xml(&self) -> Result<String, Error> {
    self.to_string()
  }

  /// Converts the struct to an XML document.
  ///
  /// # Example
  ///
  /// ```rust
  /// use opml::OPML;
  ///
  /// let opml = OPML::default();
  /// let xml = opml.to_string().unwrap();
  ///
  /// let expected = r#"<opml version="2.0"><head/><body/></opml>"#;
  /// assert_eq!(xml, expected);
  /// ```
  pub fn to_string(&self) -> Result<String, Error> {
    Ok(XmlWrite::to_string(self)?)
  }

  /// Converts the struct to an XML document and writes it using the writer.
  ///
  /// # Example
  ///
  /// ```rust,no_run
  /// use opml::OPML;
  ///
  /// let opml = OPML::default();
  /// let mut file = std::fs::File::create("file.opml").unwrap();
  /// let xml = opml.to_writer(&mut file).unwrap();
  /// ```
  pub fn to_writer<W>(&self, writer: &mut W) -> Result<(), Error>
  where
    W: std::io::Write,
  {
    let xml_string = self.to_string()?;
    writer.write_all(xml_string.as_bytes())?;
    Ok(())
  }
}

impl Default for OPML {
  fn default() -> Self {
    OPML {
      version: "2.0".to_string(),
      head: Some(Head::default()),
      body: Body::default(),
    }
  }
}

/// The [`Head`] child element of [`OPML`]. Contains the metadata of the OPML
/// document.
#[derive(
  XmlWrite,
  XmlRead,
  PartialEq,
  Eq,
  Debug,
  Clone,
  Default,
  Serialize,
  Deserialize,
)]
#[xml(tag = "head")]
pub struct Head {
  /// The title of the document.
  #[xml(flatten_text = "title")]
  pub title: Option<String>,

  /// A date-time (RFC822) indicating when the document was created.
  #[xml(flatten_text = "dateCreated")]
  pub date_created: Option<String>,

  /// A date-time (RFC822) indicating when the document was last modified.
  #[xml(flatten_text = "dateModified")]
  pub date_modified: Option<String>,

  /// The name of the document owner.
  #[xml(flatten_text = "ownerName")]
  pub owner_name: Option<String>,

  /// The email address of the document owner.
  #[xml(flatten_text = "ownerEmail")]
  pub owner_email: Option<String>,

  /// A link to the website of the document owner.
  #[xml(flatten_text = "ownerId")]
  pub owner_id: Option<String>,

  /// A link to the documentation of the OPML format used for this document.
  #[xml(flatten_text = "docs")]
  pub docs: Option<String>,

  /// A comma-separated list of line numbers that are expanded. The line numbers
  /// in the list tell you which headlines to expand. The order is important.
  /// For each element in the list, X, starting at the first summit, navigate
  /// flatdown X times and expand. Repeat for each element in the list.
  #[xml(flatten_text = "expansionState")]
  pub expansion_state: Option<String>,

  /// A number indicating which line of the outline is displayed on the top line
  /// of the window. This number is calculated with the expansion state already
  /// applied.
  #[xml(flatten_text = "vertScrollState")]
  pub vert_scroll_state: Option<i32>,

  /// The pixel location of the top edge of the window.
  #[xml(flatten_text = "windowTop")]
  pub window_top: Option<i32>,

  /// The pixel location of the left edge of the window.
  #[xml(flatten_text = "windowLeft")]
  pub window_left: Option<i32>,

  /// The pixel location of the bottom edge of the window.
  #[xml(flatten_text = "windowBottom")]
  pub window_bottom: Option<i32>,

  /// The pixel location of the right edge of the window.
  #[xml(flatten_text = "windowRight")]
  pub window_right: Option<i32>,
}

/// The [`Body`] child element of [`OPML`]. Contains all the [`Outline`]
/// elements.
#[derive(
  XmlWrite,
  XmlRead,
  PartialEq,
  Eq,
  Debug,
  Clone,
  Default,
  Serialize,
  Deserialize,
)]
#[xml(tag = "body")]
pub struct Body {
  /// All the top-level [`Outline`] elements.
  #[xml(child = "outline")]
  pub outlines: Vec<Outline>,
}

/// The [`Outline`] element.
#[derive(
  XmlWrite,
  XmlRead,
  PartialEq,
  Eq,
  Debug,
  Clone,
  Default,
  Serialize,
  Deserialize,
)]
#[xml(tag = "outline")]
pub struct Outline {
  /// Every outline element must have at least a text attribute, which is what
  /// is displayed when an outliner opens the OPML document.
  ///
  /// Version 1.0 OPML documents may omit this attribute, so for compatibility
  /// and strictness this attribute is "technically optional" as it will be
  /// replaced by an empty String if it is omitted.
  ///
  /// Text attributes may contain encoded HTML markup.
  #[xml(default, attr = "text")]
  pub text: String,

  /// A string that indicates how the other attributes of the [`Outline`]
  /// should be interpreted.
  #[xml(attr = "type")]
  pub r#type: Option<String>,

  /// Indicating whether the outline is commented or not. By convention if an
  /// outline is commented, all subordinate outlines are considered to also be
  /// commented.
  #[xml(attr = "isComment")]
  pub is_comment: Option<bool>,

  /// Indicating whether a breakpoint is set on this outline. This attribute is
  /// mainly necessary for outlines used to edit scripts.
  #[xml(attr = "isBreakpoint")]
  pub is_breakpoint: Option<bool>,

  /// The date-time (RFC822) that this [`Outline`] element was created.
  #[xml(attr = "created")]
  pub created: Option<String>,

  /// A string of comma-separated slash-delimited category strings, in the
  /// format defined by the [RSS 2.0 category] element. To represent a "tag",
  /// the category string should contain no slashes.
  ///
  /// [RSS 2.0 category]: https://cyber.law.harvard.edu/rss/rss.html#ltcategorygtSubelementOfLtitemgt
  #[xml(attr = "category")]
  pub category: Option<String>,

  /// Child [`Outline`] elements of the current one.
  #[xml(child = "outline")]
  pub outlines: Vec<Outline>,

  /// The HTTP address of the feed.
  #[xml(attr = "xmlUrl")]
  pub xml_url: Option<String>,

  /// The top-level description element from the feed.
  #[xml(attr = "description")]
  pub description: Option<String>,

  /// The top-level link element from the feed.
  #[xml(attr = "htmlUrl")]
  pub html_url: Option<String>,

  /// The top-level language element from the feed.
  #[xml(attr = "language")]
  pub language: Option<String>,

  /// The top-level title element from the feed.
  #[xml(attr = "title")]
  pub title: Option<String>,

  /// The version of the feed's format (such as RSS 0.91, 2.0, ...).
  #[xml(attr = "version")]
  pub version: Option<String>,

  /// A link that can point to another OPML document or to something that can
  /// be displayed in a web browser.
  #[xml(attr = "url")]
  pub url: Option<String>,
}

impl Outline {
  /// Helper function to add an [`Outline`] element with `text` and `xml_url`
  /// attributes as a child element, useful for creating grouped lists. This
  /// function also exists as [`OPML::add_feed`] for non-grouped lists.
  ///
  /// # Example
  ///
  /// ```rust
  /// use opml::Outline;
  ///
  /// let mut group = Outline::default();
  /// group.add_feed("Feed Name", "https://example.com/");
  /// let added_feed = group.outlines.first().unwrap();
  ///
  /// let expected_feed = &Outline {
  ///   text: "Feed Name".to_string(),
  ///   xml_url: Some("https://example.com/".to_string()),
  ///   ..Outline::default()
  /// };
  ///
  /// assert_eq!(added_feed, expected_feed);
  /// ```
  pub fn add_feed(&mut self, name: &str, url: &str) -> &mut Self {
    self.outlines.push(Outline {
      text: name.to_string(),
      xml_url: Some(url.to_string()),
      ..Outline::default()
    });

    self
  }
}