asonix/activitystreams-new
2
1
Fork 0
Code Issues Pull requests Releases Wiki Activity

More Object docs

Browse source
This commit is contained in:
asonix 2020-05-16 13:28:59 -05:00
parent 6318b771d2
commit 9a3df39757
2 changed files with 337 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
src/link.rs
View file

@ -30,7 +30,7 @@ use std::convert::TryFrom;
use typed_builder::TypedBuilder;
pub mod kind {
//! kinds of links defined by the spec
//! Kinds of links defined by the spec
//!
//! These types exist only to be statically-typed versions of the associated string. e.g.
//! `MentionType` -> `"Mention"`
@ -44,10 +44,10 @@ use self::kind::MentionType;
///
/// Any type implementing AsLink will automatically gain methods provided by LinkExt
pub trait AsLink<Kind>: markers::Link {
/// Immutable borrow of Link<Kind>
/// Immutable borrow of `Link<Kind>`
fn link_ref(&self) -> &Link<Kind>;
/// Mutable borrow of Link<Kind>
/// Mutable borrow of `Link<Kind>`
fn link_mut(&mut self) -> &mut Link<Kind>;
}

334
src/object.rs
View file

@ -1,3 +1,24 @@
//! Types and traits for dealing with Object attributes
//!
//! ```rust
//! # fn main() -> Result<(), anyhow::Error> {
//! use activitystreams_new::{
//! object::Image,
//! prelude::*,
//! primitives::XsdAnyUri,
//! };
//!
//! let mut image = Image::default();
//!
//! image
//! .set_url("https://example.com/image.png".parse::<XsdAnyUri>()?)
//! .set_attributed_to("https://example.com/actor".parse::<XsdAnyUri>()?)
//! .set_generator("https://example.com/image-generator".parse::<XsdAnyUri>()?)
//! .set_icon("https://example.com/icon.png".parse::<XsdAnyUri>()?);
//! #
//! # Ok(())
//! # }
//! ```
use crate::{
base::{AnyBase, AsBase, Base, Extends},
markers,
@ -8,41 +29,88 @@ use std::convert::TryFrom;
use typed_builder::TypedBuilder;
pub mod kind {
//! Kinds of objects defined by the spec
//!
//! These types exist only to be statically-typed versions of the associated string. e.g.
//! `PlaceType` -> `"Place"`
pub use activitystreams::object::kind::*;
}
use self::kind::*;
/// Implementation trait for deriving Object methods for a type
///
/// Any type implementing AsObject will automatically gain methods provided by ObjectExt
pub trait AsObject<Kind>: markers::Object {
/// Immutable borrow of `Object<Kind>`
fn object_ref(&self) -> &Object<Kind>;
/// Mutable borrow of `Object<Kind>`
fn object_mut(&mut self) -> &mut Object<Kind>;
}
/// Implementation trait for deriving ActivityPub Object methods for a type
///
/// Any type implementing AsApObject will automatically gain methods provided by ApObjectExt
pub trait AsApObject<Inner>: markers::Object {
/// Immutable borrow of `ApObject<Inner>`
fn ap_object_ref(&self) -> &ApObject<Inner>;
/// Mutable borrow of `ApObject<Inner>`
fn ap_object_mut(&mut self) -> &mut ApObject<Inner>;
}
/// Implementation trait for deriving Place methods for a type
///
/// Any type implementing AsPlace will automatically gain methods provided by PlaceExt
pub trait AsPlace: markers::Object {
/// Immutable borrow of `Place`
fn place_ref(&self) -> &Place;
/// Mutable borrow of `Place`
fn place_mut(&mut self) -> &mut Place;
}
/// Implementation trait for deriving Profile methods for a type
///
/// Any type implementing AsProfile will automatically gain methods provided by ProfileExt
pub trait AsProfile: markers::Object {
/// Immutable borrow of `Profile`
fn profile_ref(&self) -> &Profile;
/// Mutable borrow of `Profile`
fn profile_mut(&mut self) -> &mut Profile;
}
/// Implementation trait for deriving Relationship methods for a type
///
/// Any type implementing AsRelationship will automatically gain methods provided by
/// RelationshipExt
pub trait AsRelationship: markers::Object {
/// Immutable borrow of `Relationship`
fn relationship_ref(&self) -> &Relationship;
/// Mutable borrow of `Relationship`
fn relationship_mut(&mut self) -> &mut Relationship;
}
/// Implementation trait for deriving Tombstone methods for a type
///
/// Any type implementing AsTombstone will automatically gain methods provided by TombstoneExt
pub trait AsTombstone: markers::Object {
/// Immutable borrow of `Tombstone`
fn tombstone_ref(&self) -> &Tombstone;
/// Mutable borrow of `Tombstone`
fn tombstone_mut(&mut self) -> &mut Tombstone;
}
/// Helper methods for interacting with Object types
///
/// This trait represents methods valid for any ActivityStreams Object.
///
/// Documentation for the fields related to these methods can be found on the `Object` struct
pub trait ObjectExt<Kind>: AsObject<Kind> {
/// Fetch the attachment for the current object
///
@ -2706,6 +2774,11 @@ pub trait ObjectExt<Kind>: AsObject<Kind> {
}
}
/// Helper methods for interacting with ActivityPub Object types
///
/// This trait represents methods valid for any ActivityPub Object.
///
/// Documentation for the fields related to these methods can be found on the `ApObject` struct
pub trait ApObjectExt<Inner>: AsApObject<Inner> {
fn shares<'a>(&'a self) -> Option<&'a XsdAnyUri>
where
@ -2989,10 +3062,36 @@ pub trait RelationshipExt: AsRelationship {
self
}
/// Fetch the object for the current object
///
/// ```rust
/// # use activitystreams_new::object::Relationship;
/// # let mut video = Relationship::default();
/// #
/// use activitystreams_new::prelude::*;
///
/// if let Some(object) = video.object() {
/// println!("{:?}", object);
/// }
/// ```
fn object(&self) -> Option<&OneOrMany<AnyBase>> {
self.relationship_ref().object.as_ref()
}
/// Set the object for the current object
///
/// This overwrites the contents of object
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// use activitystreams_new::prelude::*;
/// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
/// # let mut video = Relationship::default();
///
/// video.set_object("https://example.com".parse::<XsdAnyUri>()?);
/// # Ok(())
/// # }
/// ```
fn set_object<T>(&mut self, object: T) -> &mut Self
where
T: Into<AnyBase>,
@ -3001,6 +3100,23 @@ pub trait RelationshipExt: AsRelationship {
self
}
/// Set many objects for the current object
///
/// This overwrites the contents of object
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// use activitystreams_new::prelude::*;
/// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
/// # let mut video = Relationship::default();
///
/// video.set_many_objects(vec![
/// "https://example.com/one".parse::<XsdAnyUri>()?,
/// "https://example.com/two".parse()?,
/// ]);
/// # Ok(())
/// # }
/// ```
fn set_many_objects<I, T>(&mut self, items: I) -> &mut Self
where
I: IntoIterator<Item = T>,
@ -3011,6 +3127,22 @@ pub trait RelationshipExt: AsRelationship {
self
}
/// Add a object to the current object
///
/// This does not overwrite the contents of object, only appends an item
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// use activitystreams_new::prelude::*;
/// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
/// # let mut video = Relationship::default();
///
/// video
/// .add_object("https://example.com/one".parse::<XsdAnyUri>()?)
/// .add_object("https://example.com/two".parse::<XsdAnyUri>()?);
/// # Ok(())
/// # }
/// ```
fn add_object<T>(&mut self, object: T) -> &mut Self
where
T: Into<AnyBase>,
@ -3026,19 +3158,73 @@ pub trait RelationshipExt: AsRelationship {
self
}
/// Take the object from the current object, leaving nothing
///
/// ```rust
/// # use activitystreams_new::object::Relationship;
/// # let mut video = Relationship::default();
/// #
/// use activitystreams_new::prelude::*;
///
/// if let Some(object) = video.take_object() {
/// println!("{:?}", object);
/// }
/// ```
fn take_object(&mut self) -> Option<OneOrMany<AnyBase>> {
self.relationship_mut().object.take()
}
/// Delete the object from the current object
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
/// # let mut video = Relationship::default();
/// # video.set_object("https://example.com".parse::<XsdAnyUri>()?);
/// #
/// use activitystreams_new::prelude::*;
///
/// assert!(video.object().is_some());
/// video.delete_object();
/// assert!(video.object().is_none());
/// # Ok(())
/// # }
/// ```
fn delete_object(&mut self) -> &mut Self {
self.relationship_mut().object = None;
self
}
/// Fetch the relationship for the current object
///
/// ```rust
/// # use activitystreams_new::object::Relationship;
/// # let mut video = Relationship::default();
/// #
/// use activitystreams_new::prelude::*;
///
/// if let Some(relationship) = video.relationship() {
/// println!("{:?}", relationship);
/// }
/// ```
fn relationship(&self) -> Option<&OneOrMany<AnyBase>> {
self.relationship_ref().relationship.as_ref()
}
/// Set the relationship for the current object
///
/// This overwrites the contents of relationship
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// use activitystreams_new::prelude::*;
/// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
/// # let mut video = Relationship::default();
///
/// video.set_relationship("https://example.com".parse::<XsdAnyUri>()?);
/// # Ok(())
/// # }
/// ```
fn set_relationship<T>(&mut self, relationship: T) -> &mut Self
where
T: Into<AnyBase>,
@ -3047,6 +3233,23 @@ pub trait RelationshipExt: AsRelationship {
self
}
/// Set many relationships for the current object
///
/// This overwrites the contents of relationship
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// use activitystreams_new::prelude::*;
/// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
/// # let mut video = Relationship::default();
///
/// video.set_many_relationships(vec![
/// "https://example.com/one".parse::<XsdAnyUri>()?,
/// "https://example.com/two".parse()?,
/// ]);
/// # Ok(())
/// # }
/// ```
fn set_many_relationships<I, T>(&mut self, items: I) -> &mut Self
where
I: IntoIterator<Item = T>,
@ -3057,6 +3260,22 @@ pub trait RelationshipExt: AsRelationship {
self
}
/// Add a relationship to the current object
///
/// This does not overwrite the contents of relationship, only appends an item
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// use activitystreams_new::prelude::*;
/// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
/// # let mut video = Relationship::default();
///
/// video
/// .add_relationship("https://example.com/one".parse::<XsdAnyUri>()?)
/// .add_relationship("https://example.com/two".parse::<XsdAnyUri>()?);
/// # Ok(())
/// # }
/// ```
fn add_relationship<T>(&mut self, relationship: T) -> &mut Self
where
T: Into<AnyBase>,
@ -3072,10 +3291,38 @@ pub trait RelationshipExt: AsRelationship {
self
}
/// Take the relationship from the current object, leaving nothing
///
/// ```rust
/// # use activitystreams_new::object::Relationship;
/// # let mut video = Relationship::default();
/// #
/// use activitystreams_new::prelude::*;
///
/// if let Some(relationship) = video.take_relationship() {
/// println!("{:?}", relationship);
/// }
/// ```
fn take_relationship(&mut self) -> Option<OneOrMany<AnyBase>> {
self.relationship_mut().relationship.take()
}
/// Delete the relationship from the current object
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
/// # let mut video = Relationship::default();
/// # video.set_relationship("https://example.com".parse::<XsdAnyUri>()?);
/// #
/// use activitystreams_new::prelude::*;
///
/// assert!(video.relationship().is_some());
/// video.delete_relationship();
/// assert!(video.relationship().is_none());
/// # Ok(())
/// # }
/// ```
fn delete_relationship(&mut self) -> &mut Self {
self.relationship_mut().relationship = None;
self
@ -3083,10 +3330,36 @@ pub trait RelationshipExt: AsRelationship {
}
pub trait TombstoneExt: AsTombstone {
/// Fetch the former_type for the current object
///
/// ```rust
/// # use activitystreams_new::object::Tombstone;
/// # let mut video = Tombstone::default();
/// #
/// use activitystreams_new::prelude::*;
///
/// if let Some(former_type) = video.former_type() {
/// println!("{:?}", former_type);
/// }
/// ```
fn former_type(&self) -> Option<&OneOrMany<AnyBase>> {
self.tombstone_ref().former_type.as_ref()
}
/// Set the former_type for the current object
///
/// This overwrites the contents of former_type
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// use activitystreams_new::prelude::*;
/// # use activitystreams_new::{object::Tombstone, primitives::XsdAnyUri};
/// # let mut video = Tombstone::default();
///
/// video.set_former_type("https://example.com".parse::<XsdAnyUri>()?);
/// # Ok(())
/// # }
/// ```
fn set_former_type<T>(&mut self, former_type: T) -> &mut Self
where
T: Into<AnyBase>,
@ -3095,6 +3368,23 @@ pub trait TombstoneExt: AsTombstone {
self
}
/// Set many former_types for the current object
///
/// This overwrites the contents of former_type
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// use activitystreams_new::prelude::*;
/// # use activitystreams_new::{object::Tombstone, primitives::XsdAnyUri};
/// # let mut video = Tombstone::default();
///
/// video.set_many_former_types(vec![
/// "https://example.com/one".parse::<XsdAnyUri>()?,
/// "https://example.com/two".parse()?,
/// ]);
/// # Ok(())
/// # }
/// ```
fn set_many_former_types<I, T>(&mut self, items: I) -> &mut Self
where
I: IntoIterator<Item = T>,
@ -3105,6 +3395,22 @@ pub trait TombstoneExt: AsTombstone {
self
}
/// Add a former_type to the current object
///
/// This does not overwrite the contents of former_type, only appends an item
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// use activitystreams_new::prelude::*;
/// # use activitystreams_new::{object::Tombstone, primitives::XsdAnyUri};
/// # let mut video = Tombstone::default();
///
/// video
/// .add_former_type("https://example.com/one".parse::<XsdAnyUri>()?)
/// .add_former_type("https://example.com/two".parse::<XsdAnyUri>()?);
/// # Ok(())
/// # }
/// ```
fn add_former_type<T>(&mut self, former_type: T) -> &mut Self
where
T: Into<AnyBase>,
@ -3120,10 +3426,38 @@ pub trait TombstoneExt: AsTombstone {
self
}
/// Take the former_type from the current object, leaving nothing
///
/// ```rust
/// # use activitystreams_new::object::Tombstone;
/// # let mut video = Tombstone::default();
/// #
/// use activitystreams_new::prelude::*;
///
/// if let Some(former_type) = video.take_former_type() {
/// println!("{:?}", former_type);
/// }
/// ```
fn take_former_type(&mut self) -> Option<OneOrMany<AnyBase>> {
self.tombstone_mut().former_type.take()
}
/// Delete the former_type from the current object
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::{object::Tombstone, primitives::XsdAnyUri};
/// # let mut video = Tombstone::default();
/// # video.set_former_type("https://example.com".parse::<XsdAnyUri>()?);
/// #
/// use activitystreams_new::prelude::*;
///
/// assert!(video.former_type().is_some());
/// video.delete_former_type();
/// assert!(video.former_type().is_none());
/// # Ok(())
/// # }
/// ```
fn delete_former_type(&mut self) -> &mut Self {
self.tombstone_mut().former_type = None;
self