Crate json_feed_model

Expand description

§JSON Feed Model

JSON Feed Model provides types which can be used to manipulate JSON Feed data.

The crate is basically a newtype wrapper around Serde JSON’s Map type and provides methods to JSON Feed properties.

For example, a library user can have a slice of bytes and create a Feed by calling from_slice. If the slice of bytes is a JSON object, then a Feed instance is returned. The only guarantee which Feed and other model types make is that the JSON data is a JSON object.

The library user can call is_valid(Version::Version1_1) on the Feed instance to determine if the JSON object is a valid Version 1.1 JSON Feed.

§Documentation

Latest API Docs

§Alloc Only

If the host environment has an allocator but does not have access to the Rust std library:

[dependencies]
json-feed-model = { version = "0.2.0", default-features = false, features = ["alloc"]}

§Accessor Methods

If the library user wants to read or write data, then methods like title(), set_title(...), and remove_title() exist on Feed.

For “getter” methods, the return type is a Result<Option<type>, ...>. The “getter” may fail due to expecting the wrong JSON type. For instance, if a field is expected to be a JSON string but the value is a JSON number, then an Error::UnexpectedType will be returned. The field value may or may not be present so the Option type is used to indicate if a value exists.

For “setter” and “remove” methods, any existing value in the JSON object is returned.

§Owned, Borrowed, and Borrowed Mutable Types

There are 3 variants of every model type, the “owned” data type (e.g. Feed), the borrowed data type (e.g. FeedRef), and the borrowed mutable data type (e.g. FeedMut). In most cases, the “owned” data type will be the primary kind explicitly used. The borrowed and borrowed mutable variants may be returned from “getter” methods for performance reasons.

A few standard traits are implemented like From<Map<String,Value>> and Serialize as well as a few helper methods like as_map() and as_map_mut() for the model types.

§Examples

The following example shows how to read properties.

use json_feed_model::{Feed, ItemRef, Version};

let json = serde_json::json!({
    "version": "https://jsonfeed.org/version/1.1",
    "title": "Lorem ipsum dolor sit amet.",
    "home_page_url": "https://example.org/",
    "feed_url": "https://example.org/feed.json",
    "items": [
        {
            "id": "cd7f0673-8e81-4e13-b273-4bd1b83967d0",
            "content_text": "Aenean tristique dictum mauris, et.",
            "url": "https://example.org/aenean-tristique"
        },
        {
            "id": "2bcb497d-c40b-4493-b5ae-bc63c74b48fa",
            "content_html": "Vestibulum non magna vitae tortor.",
            "url": "https://example.org/vestibulum-non"
        }
    ]
});

let feed = json_feed_model::from_value(json)?;

assert!(feed.is_valid(&Version::Version1_1));

assert_eq!(feed.version()?, Some(json_feed_model::VERSION_1_1));
assert_eq!(feed.title()?, Some("Lorem ipsum dolor sit amet."));
assert_eq!(feed.home_page_url()?, Some("https://example.org/"));
assert_eq!(feed.feed_url()?, Some("https://example.org/feed.json"));

let items: Option<Vec<ItemRef>> = feed.items()?;
assert!(items.is_some());
let items: Vec<ItemRef> = items.unwrap();
assert_eq!(items.len(), 2);

assert_eq!(items[0].id()?, Some("cd7f0673-8e81-4e13-b273-4bd1b83967d0"));
assert_eq!(
    items[0].content_text()?,
    Some("Aenean tristique dictum mauris, et.")
);
assert_eq!(
    items[0].url()?,
    Some("https://example.org/aenean-tristique")
);

assert_eq!(items[1].id()?, Some("2bcb497d-c40b-4493-b5ae-bc63c74b48fa"));
assert_eq!(
    items[1].content_html()?,
    Some("Vestibulum non magna vitae tortor.")
);
assert_eq!(items[1].url()?, Some("https://example.org/vestibulum-non"));

§Custom Extension

The following example uses a custom trait to write and then read a custom extension. It also shows a simple way to use serde_json to write the JSON Feed. See serde_json for other serialization methods.

use json_feed_model::{Feed, Item, Version};
use serde_json::Value;

trait ExampleExtension {
    fn example(&self) -> Result<Option<&str>, json_feed_model::Error>;

    fn set_example<T>(&mut self, value: T) -> Option<Value>
    where
        T: ToString;
}

impl ExampleExtension for Feed {
    fn example(&self) -> Result<Option<&str>, json_feed_model::Error> {
        self.as_map().get("_example").map_or_else(
            || Ok(None),
            |value| match value {
                Value::String(s) => Ok(Some(s.as_str())),
                _ => Err(json_feed_model::Error::UnexpectedType),
            },
        )
    }

    fn set_example<T>(&mut self, value: T) -> Option<Value>
    where
        T: ToString,
    {
        self.as_map_mut()
            .insert(String::from("_example"), Value::String(value.to_string()))
    }
}

let mut feed = Feed::new();
feed.set_version(Version::Version1_1);
feed.set_title("Lorem ipsum dolor sit amet.");

feed.set_example("123456");

let mut item = Item::new();
item.set_id("2bcb497d-c40b-4493-b5ae-bc63c74b48fa");
item.set_content_text("Vestibulum non magna vitae tortor.");
item.set_url("https://example.org/vestibulum-non");

feed.set_items(vec![item]);

assert!(feed.is_valid(&Version::Version1_1));

let expected_json = serde_json::json!({
    "version": "https://jsonfeed.org/version/1.1",
    "title": "Lorem ipsum dolor sit amet.",
    "_example": "123456",
    "items": [
        {
            "id": "2bcb497d-c40b-4493-b5ae-bc63c74b48fa",
            "content_text": "Vestibulum non magna vitae tortor.",
            "url": "https://example.org/vestibulum-non",
        }
    ]
});
assert_eq!(feed, json_feed_model::from_value(expected_json)?);

assert_eq!(feed.example()?, Some("123456"));

let output = serde_json::to_string(&feed);
assert!(output.is_ok());

§License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.

§Contributions

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Structs§

Attachment: A relevant resource for an Item.
AttachmentMut: An Attachment implemented with a borrowed mutable reference to a JSON object.
AttachmentRef: An Attachment implemented with a borrowed reference to a JSON object.
Author: An author of a feed or an item in the feed.
AuthorMut: An Author implemented with a borrowed mutable reference to a JSON object.
AuthorRef: An Author implemented with a borrowed reference to a JSON object.
Feed: A list of items with associated metadata.
FeedMut: A Feed implemented with a borrowed mutable reference to a JSON object.
FeedRef: A Feed implemented with a borrowed reference to a JSON object.
Hub: A subscription endpoint which can be used to receive feed update notifications.
HubMut: A Hub implemented with a borrowed mutable reference to a JSON object.
HubRef: A Hub implemented with a borrowed reference to a JSON object.
Item: An item is a single object (blog post, story, etc.) in the feed list.
ItemMut: An Item implemented with a borrowed mutable reference to a JSON object.
ItemRef: An Item implemented with a borrowed reference to a JSON object.

Enums§

Error: All of the possible crate errors.
Version: A JSON Feed spec version identifier

Constants§

VERSION_1: Version 1 identifier (for 1.0 feeds)
VERSION_1_1: Version 1.1 identifier

Functions§

from_readerstd: Attempts to JSON decode a std::io::Read and return a Feed.
from_slice: Attempts to JSON decode a byte slice and return a Feed.
from_str: Attempts to JSON decode a str and return a Feed.
from_value: Attempts to return a Feed from a JSON Value.