Holllo/opml
Holllo
/
opml
1
Fork 0
Code Issues Releases 17 Activity

Add more and clean up documentation.

This commit is contained in:
Bauke 2020-05-28 16:47:03 +02:00
parent 3e90b069a5
commit b429da1362
Signed by: Bauke
GPG Key ID: C1C0F29952BCF558
4 changed files with 119 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Cargo.toml
View File

@ -3,9 +3,9 @@
[package] [package]
name = "opml" name = "opml"
authors = ["Holllo <helllo@holllo.cc>"] authors = ["Holllo <helllo@holllo.cc>"]
version = "0.2.0" version = "0.2.1"
license = "MIT/Apache-2.0" license = "MIT/Apache-2.0"
description = "An OPML 2.0 parser for Rust." description = "An OPML parser for Rust."
repository = "https://gitlab.com/holllo/opml-rs" repository = "https://gitlab.com/holllo/opml-rs"
readme = "ReadMe.md" readme = "ReadMe.md"
edition = "2018" edition = "2018"

6
ReadMe.md
View File

@ -5,10 +5,10 @@
## Contents ## Contents
* [Examples](examples/) * [Examples](examples/)
* [Expertise Wanted](#expertise-wanted) * [Expertise Welcome](#expertise-welcome)
* [License](#license) * [License](#license)
## Expertise Wanted ## Expertise Welcome
This is the first crate I'm publishing to crates.io and the first proper library I've made for Rust. Any help or tips with how to improve the API, documentation, usability, testing or anything else is very welcome. Feel free to create [an issue](https://gitlab.com/holllo/opml-rs/issues/) or contact me via email at helllo@holllo.cc. This is the first crate I'm publishing to crates.io and the first proper library I've made for Rust. Any help or tips with how to improve the API, documentation, usability, testing or anything else is very welcome. Feel free to create [an issue](https://gitlab.com/holllo/opml-rs/issues/) or contact me via email at helllo@holllo.cc.
@ -23,6 +23,8 @@ let parsed = OPML::new(xml).unwrap();
println!("{:#?}", parsed); println!("{:#?}", parsed);
``` ```
Check out [the documentation](https://docs.rs/opml/) for further details.
## License ## License
Open-sourced with either the Open-sourced with either the

148
source/lib.rs
View File

@ -1,48 +1,51 @@
//! This crate provides an API to parse and construct [OPML files](https://dev.opml.org/spec2.html) to and from regular Rust structs. //! This crate provides an API to parse and construct [OPML documents](http://dev.opml.org/spec2.html) to and from regular Rust structs.
//! //!
//! ## Getting Started //! ## Getting Started
//! //!
//! ### Parsing //! ### Parsing
//! //!
//! ```rust //! Parsing XML into [an OPML struct](struct.OPML.html) can be done with [`OPML::new()`](struct.OPML.html#method.new). Resulting in an error if the XML can't be parsed, if the included OPML version is not supported (currently all OPML versions (1.0, 1.1 and 2.0) are supported) or if the [Body](struct.Body.html) element contains no child [Outline](struct.Outline.html) elements, [as per the spec](http://dev.opml.org/spec2.html#whatIsALtbodygt).
//! use opml::OPML;
//! //!
//! let xml = r#"<opml version="2.0"><body><outline text="Outline"/></body></opml>"#; //! ```rust
//! use opml::{OPML, Outline};
//!
//! let xml = r#"<opml version="2.0"><head/><body><outline text="Outline"/></body></opml>"#;
//! let parsed = OPML::new(xml).unwrap(); //! let parsed = OPML::new(xml).unwrap();
//! //!
//! let mut expected = OPML::default();
//! expected.body.outlines.push(Outline {
//! text: "Outline".to_string(),
//! ..Outline::default()
//! });
//!
//! println!("{:#?}", parsed); //! println!("{:#?}", parsed);
//! assert_eq!(parsed, expected);
//! ``` //! ```
//! //!
//! ### Constructing //! ### Constructing
//! //!
//! Constructing OPMLs is very easy as all you have to do is instantiate the [OPML struct](struct.OPML.html) with [`OPML::default()`](struct.OPML.html#method.default), add anything wanted and then call [`OPML::to_xml()`](struct.OPML.html#method.to_xml) to return the XML as a string.
//!
//! ```rust //! ```rust
//! use opml::{Head, OPML}; //! use opml::{Head, OPML};
//! //!
//! let mut opml = OPML::default(); //! let mut opml = OPML::default();
//! opml.head = Some(Head {
//! title: Some("Rust Feeds".to_string()),
//! ..Head::default()
//! });
//! opml //! opml
//! .add_feed("Rust Blog", "https://blog.rust-lang.org/feed.xml") //! .add_feed("Rust Blog", "https://blog.rust-lang.org/feed.xml")
//! .add_feed( //! .add_feed(
//! "Inside Rust", //! "Inside Rust",
//! "https://blog.rust-lang.org/inside-rust/feed.xml", //! "https://blog.rust-lang.org/inside-rust/feed.xml",
//! ) //! );
//! .set_head(Head {
//! title: Some("Rust Feeds".to_string()),
//! ..Head::default()
//! });
//! //!
//! let xml = opml.to_xml().unwrap(); //! let xml = opml.to_xml().unwrap();
//! let expected = r#"<opml version="2.0"><head><title>Rust Feeds</title></head><body><outline text="Rust Blog" xmlUrl="https://blog.rust-lang.org/feed.xml"/><outline text="Inside Rust" xmlUrl="https://blog.rust-lang.org/inside-rust/feed.xml"/></body></opml>"#;
//! println!("{}", xml); //! println!("{}", xml);
//! assert_eq!(xml, expected);
//! //!
//! // Outputs (without whitespace):
//! // <opml version="2.0">
//! // <head>
//! // <title>Rust Feeds</title>
//! // </head>
//! // <body>
//! // <outline text="Rust Blog" xmlUrl="https://blog.rust-lang.org/feed.xml"/>
//! // <outline text="Inside Rust" xmlUrl="https://blog.rust-lang.org/inside-rust/feed.xml"/>
//! // </body>
//! // </opml>
//! ``` //! ```
//! //!
//! ## License //! ## License
@ -61,25 +64,43 @@
use regex::Regex; use regex::Regex;
use strong_xml::{XmlError, XmlRead, XmlWrite}; use strong_xml::{XmlError, XmlRead, XmlWrite};
/// The top-level `<opml>` element. /// The top-level [OPML](struct.OPML.html) element.
#[derive(XmlWrite, XmlRead, PartialEq, Debug, Clone)] #[derive(XmlWrite, XmlRead, PartialEq, Debug, Clone)]
#[xml(tag = "opml")] #[xml(tag = "opml")]
pub struct OPML { pub struct OPML {
/// The version attribute from the element. /// The version attribute from the element, valid values are `1.0`, `1.1` and `2.0`.
#[xml(attr = "version")] #[xml(attr = "version")]
pub version: String, pub version: String,
/// The `<head>` child element. Contains the metadata of the OPML document. /// The [Head](struct.Head.html) child element. Contains the metadata of the OPML document.
#[xml(child = "head")] #[xml(child = "head")]
pub head: Option<Head>, pub head: Option<Head>,
/// The `<body>` child element. Contains all the `<outlines>`. /// The [Body](struct.Body.html) child element. Contains all the [Outlines](struct.Outline.html).
#[xml(child = "body")] #[xml(child = "body")]
pub body: Body, pub body: Body,
} }
impl OPML { impl OPML {
/// Parses an OPML file. /// 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 parsed = OPML::new(xml).unwrap();
///
/// let mut expected = OPML::default();
/// expected.body.outlines.push(Outline {
/// text: "Outline".to_string(),
/// ..Outline::default()
/// });
///
/// assert_eq!(parsed, expected);
/// ```
pub fn new(xml: &str) -> Result<Self, String> { pub fn new(xml: &str) -> Result<Self, String> {
let opml: Result<OPML, XmlError> = OPML::from_str(xml); let opml: Result<OPML, XmlError> = OPML::from_str(xml);
@ -111,9 +132,28 @@ impl OPML {
Ok(opml) Ok(opml)
} }
pub fn add_feed(&mut self, name: &str, url: &str) -> &mut Self { /// Helper function to add an [Outline](struct.Outline.html) element with `text` and `xml_url` attributes to the [Body](struct.Body.html). Useful for creating feed lists quickly. This function [also exists on the Outline struct](struct.Outline.html#method.add_feed) to create grouped lists easily.
///
/// # 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 { self.body.outlines.push(Outline {
text: name.to_string(), text: text.to_string(),
xml_url: Some(url.to_string()), xml_url: Some(url.to_string()),
..Outline::default() ..Outline::default()
}); });
@ -121,12 +161,19 @@ impl OPML {
self self
} }
pub fn set_head(&mut self, head: Head) -> &mut Self { /// Converts the struct to an XML document.
self.head = Some(head); ///
/// # Example
self ///
} /// ```rust
/// use opml::OPML;
///
/// let opml = OPML::default();
/// let xml = opml.to_xml().unwrap();
///
/// let expected = r#"<opml version="2.0"><head/><body/></opml>"#;
/// assert_eq!(xml, expected);
/// ```
pub fn to_xml(&self) -> Result<String, String> { pub fn to_xml(&self) -> Result<String, String> {
let result: Result<String, XmlError> = self.to_string(); let result: Result<String, XmlError> = self.to_string();
@ -147,7 +194,7 @@ impl Default for OPML {
} }
} }
/// The `<head>` child element of `<opml>`. /// The [Head](struct.Head.html) child element of [OPML](struct.OPML.html).
/// Contains the metadata of the OPML document. /// Contains the metadata of the OPML document.
#[derive(XmlWrite, XmlRead, PartialEq, Debug, Clone, Default)] #[derive(XmlWrite, XmlRead, PartialEq, Debug, Clone, Default)]
#[xml(tag = "head")] #[xml(tag = "head")]
@ -205,25 +252,25 @@ pub struct Head {
pub window_right: Option<i32>, pub window_right: Option<i32>,
} }
/// The `<body>` child element of `<opml>`. Contains all the `<outlines>`. /// The [Body](struct.Body.html) child element of [OPML](struct.OPML.html). Contains all the [Outlines](struct.Outline.html).
#[derive(XmlWrite, XmlRead, PartialEq, Debug, Clone, Default)] #[derive(XmlWrite, XmlRead, PartialEq, Debug, Clone, Default)]
#[xml(tag = "body")] #[xml(tag = "body")]
pub struct Body { pub struct Body {
/// `<outline>` elements. /// All the top-level [Outline](struct.Outline.html) elements.
#[xml(child = "outline")] #[xml(child = "outline")]
pub outlines: Vec<Outline>, pub outlines: Vec<Outline>,
} }
/// The `<outline>` element. /// The [Outline](struct.Outline.html) element.
#[derive(XmlWrite, XmlRead, PartialEq, Debug, Clone, Default)] #[derive(XmlWrite, XmlRead, PartialEq, Debug, Clone, Default)]
#[xml(tag = "outline")] #[xml(tag = "outline")]
pub struct 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 file. /// Every outline element must have at least a text attribute, which is what is displayed when an outliner opens the OPML document.
/// Text attributes may contain encoded HTML markup. /// Text attributes may contain encoded HTML markup.
#[xml(attr = "text")] #[xml(attr = "text")]
pub text: String, pub text: String,
/// A string that indicates how the other attributes of the `<outline>` should be interpreted. /// A string that indicates how the other attributes of the [Outline](struct.Outline.html) should be interpreted.
#[xml(attr = "type")] #[xml(attr = "type")]
pub r#type: Option<String>, pub r#type: Option<String>,
@ -235,7 +282,7 @@ pub struct Outline {
#[xml(attr = "isBreakpoint")] #[xml(attr = "isBreakpoint")]
pub is_breakpoint: Option<bool>, pub is_breakpoint: Option<bool>,
/// The date-time (RFC822) that this `<outline>` element was created. /// The date-time (RFC822) that this [Outline](struct.Outline.html) element was created.
#[xml(attr = "created")] #[xml(attr = "created")]
pub created: Option<String>, pub created: Option<String>,
@ -243,7 +290,7 @@ pub struct Outline {
#[xml(attr = "category")] #[xml(attr = "category")]
pub category: Option<String>, pub category: Option<String>,
/// Child `<outline>` elements of the current one. /// Child [Outline](struct.Outline.html) elements of the current one.
#[xml(child = "outline")] #[xml(child = "outline")]
pub outlines: Vec<Outline>, pub outlines: Vec<Outline>,
@ -271,12 +318,31 @@ pub struct Outline {
#[xml(attr = "version")] #[xml(attr = "version")]
pub version: Option<String>, pub version: Option<String>,
/// A link that can point to another OPML file or to something that can be displayed in a web browser. /// A link that can point to another OPML document or to something that can be displayed in a web browser.
#[xml(attr = "url")] #[xml(attr = "url")]
pub url: Option<String>, pub url: Option<String>,
} }
impl Outline { impl Outline {
/// Helper function to add an [Outline](struct.Outline.html) element with `text` and `xml_url` attributes as a child element. Useful for creating grouped lists. This function [also exists on the OPML struct](struct.OPML.html#method.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 { pub fn add_feed(&mut self, name: &str, url: &str) -> &mut Self {
self.outlines.push(Outline { self.outlines.push(Outline {
text: name.to_string(), text: name.to_string(),

12
tests/construction.rs
View File

@ -11,11 +11,11 @@ fn test_opml_construction_1() -> Result<(), Box<dyn Error>> {
.add_feed( .add_feed(
"Inside Rust", "Inside Rust",
"https://blog.rust-lang.org/inside-rust/feed.xml", "https://blog.rust-lang.org/inside-rust/feed.xml",
) );
.set_head(Head { opml.head = Some(Head {
title: Some("Rust Feeds".to_string()), title: Some("Rust Feeds".to_string()),
..Head::default() ..Head::default()
}); });
let actual = opml.to_xml().unwrap(); let actual = opml.to_xml().unwrap();
let expected = read("tests/samples/construction_1.opml")?; let expected = read("tests/samples/construction_1.opml")?;
@ -28,7 +28,7 @@ fn test_opml_construction_1() -> Result<(), Box<dyn Error>> {
#[test] #[test]
fn test_opml_construction_2() -> Result<(), Box<dyn Error>> { fn test_opml_construction_2() -> Result<(), Box<dyn Error>> {
let mut opml = OPML::default(); let mut opml = OPML::default();
opml.set_head(Head { opml.head = Some(Head {
title: Some("Rust Feeds".to_string()), title: Some("Rust Feeds".to_string()),
..Head::default() ..Head::default()
}); });