Update readme

This commit is contained in:
asonix 2020-03-10 15:26:08 -05:00
parent 8ff9ab9a1e
commit bfd5b3e9d4

146
README.md
View file

@ -17,32 +17,91 @@ activitystreams = "0.4"
And then use it in your project And then use it in your project
```rust ```rust
use activitystreams::{context, Object, Actor, object::Profile}; use activitystreams::object::Video;
use serde_derive::{Serialize, Deserialize};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut v = Video::default();
v.as_mut()
.set_context_xsd_any_uri("https://www.w3.org/ns/activitystreams")?
.set_id("https://example.com/@example/lions")?
.set_url_xsd_any_uri("https://example.com/@example/lions/video.webm")?
.set_name_xsd_string("My Cool Video")?
.set_summary_xsd_string("A video about some cool lions")?
.set_media_type("video/webm")?
.set_duration("PT4M20S")?;
println!("Video, {:#?}", v);
let s = serde_json::to_string(&v)?;
println!("json, {}", s);
let v: Video = serde_json::from_str(&s)?;
println!("Video again, {:#?}", v);
Ok(())
}
```
### Intermediate Usage
```rust
use activitystreams::{
context,
object::{
properties::{
ObjectProperties,
ProfileProperties
},
Profile,
},
primitives::XsdAnyUri,
Actor,
Object,
};
use serde::{Deserialize, Serialize};
use std::any::Any;
#[derive(Clone, Debug, Default, Deserialize, Serialize)] #[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")] #[serde(rename_all = "camelCase")]
pub struct Persona { pub struct Persona {
#[serde(rename = "@context")] #[serde(rename = "@context")]
context: serde_json::Value, context: XsdAnyUri,
#[serde(rename = "type")] #[serde(rename = "type")]
kind: String, kind: String,
} }
impl Object for Persona {} #[typetag::serde]
impl Object for Persona {
fn as_any(&self) -> &(dyn Any + 'static) {
self
}
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static) {
self
}
fn duplicate(&self) -> Box<dyn Object + 'static> {
Box::new(self.clone())
}
}
impl Actor for Persona {} impl Actor for Persona {}
fn run() -> Result<(), anyhow::Error> { fn main() -> Result<(), anyhow::Error> {
let mut profile = Profile::default(); let mut profile = Profile::default();
profile.profile.set_describes_object(Persona { let pprops: &mut ProfileProperties = profile.as_mut();
context: serde_json::to_value(context())?,
pprops.set_describes_object_box(Persona {
context: context(),
kind: "Persona".to_owned(), kind: "Persona".to_owned(),
})?; })?;
profile.object_props.set_context_object(context())?; let oprops: &mut ObjectProperties = profile.as_mut();
oprops.set_context_xsd_any_uri(context())?;
let profile_string = serde_json::to_string(&profile)?; let profile_string = serde_json::to_string(&profile)?;
@ -57,62 +116,77 @@ Add the required crates to your `Cargo.toml`
```toml ```toml
# Cargo.toml # Cargo.toml
activitystreams-derive = "0.2" activitystreams = "0.4"
activitystreams-traits = "0.2" serde = { version = "1.0", features = ["derive"] }
activtystreams-types = "0.3"
serde = "1.0"
serde_derive = "1.0"
serde_json = "1.0" serde_json = "1.0"
``` ```
And then in your project And then in your project
```rust ```rust
use activitystreams_derive::{Properties, UnitString}; use activitystreams::{
use activitystreams_traits::{Link, Object}; context,
use activitystreams_types::{CustomLink, link::Mention}; link::{
use serde_derive::{Deserialize, Serialize}; properties::LinkProperties,
LinkExt,
},
Link,
Object,
PropRefs,
UnitString
};
/// Using the UnitString derive macro /// Using the UnitString derive macro
/// ///
/// This macro implements Serialize and Deserialize for the given type, making this type /// This macro implements Serialize and Deserialize for the given type, making this type
/// represent the string "SomeKind" in JSON. /// represent the string "SomeKind" in JSON.
#[derive(Clone, Debug, Default, UnitString)] #[derive(Clone, Debug, Default, UnitString)]
#[activitystreams(SomeKind)] #[activitystreams(MyLink)]
pub struct MyKind; pub struct MyKind;
properties! {
MyLink {
docs [ "Document MyLinkProperties" ],
required_key {
docs [ "Document the required key" ],
types [ String ],
functional,
required,
}
}
}
/// Using the Properties derive macro /// Using the Properties derive macro
/// ///
/// This macro generates getters and setters for the associated fields. /// This macro generates getters and setters for the associated fields.
#[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)] #[derive(Clone, Debug, Default, serde::Deserialize, serde::Serialize, PropRefs)]
#[serde(rename_all = "camelCase")] #[serde(rename_all = "camelCase")]
pub struct MyProperties { pub struct MyLink {
/// Derive getters and setters for @context with Link and Object traits.
#[serde(rename = "@context")]
#[activitystreams(ab(Object, Link))]
pub context: Option<serde_json::Value>,
/// Use the UnitString MyKind to enforce the type of the object by "SomeKind" /// Use the UnitString MyKind to enforce the type of the object by "SomeKind"
pub kind: MyKind, pub kind: MyKind,
/// Derive getters and setters for required_key with String type. #[activitystreams(Link)]
/// pub link_props: LinkProperties,
/// In the Activity Streams spec, 'functional' means there can only be one item for this
/// key. This means all fields not labeled 'functional' can also be serialized/deserialized #[activitystreams(None)]
/// as Vec<T>. pub my_link_props: MyLinkProperties,
#[activitystreams(concrete(String), functional)]
pub required_key: serde_json::Value,
} }
fn run() -> Result<(), anyhow::Error> { fn run() -> Result<(), anyhow::Error> {
let mut props = MyProperties::default(); let mut my_link = MyLink::default();
props.set_required_key_string("Hey".to_owned())?; let mprops: &mut MyLinkProperties = my_link.as_mut();
mprops.set_required_key("hey")?;
let my_link = CustomLink::new(Mention::default(), props); let lprops: &mut LinkProperties = my_link.as_mut();
lprops.set_context_xsd_any_uri(context)?;
let my_link_string = serde_json::to_string(&my_link)?; let my_link_string = serde_json::to_string(&my_link)?;
let my_link: CustomLink<Mention, MyProperties> = serde_json::from_str(&my_link_string)?; let my_link: MyLink = serde_json::from_str(&my_link_string)?;
let mprops: &MyLinkProperties = my_link.as_ref();
println!("{}", mprops.get_required_key());
Ok(()) Ok(())
} }