From 9a3df3975790c47cb945275043fce1da9b64852f Mon Sep 17 00:00:00 2001 From: asonix Date: Sat, 16 May 2020 13:28:59 -0500 Subject: [PATCH] More Object docs --- src/link.rs | 6 +- src/object.rs | 334 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 337 insertions(+), 3 deletions(-) diff --git a/src/link.rs b/src/link.rs index a83f57e..73874d6 100644 --- a/src/link.rs +++ b/src/link.rs @@ -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: markers::Link { - /// Immutable borrow of Link + /// Immutable borrow of `Link` fn link_ref(&self) -> &Link; - /// Mutable borrow of Link + /// Mutable borrow of `Link` fn link_mut(&mut self) -> &mut Link; } diff --git a/src/object.rs b/src/object.rs index 9516feb..076906e 100644 --- a/src/object.rs +++ b/src/object.rs @@ -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::()?) +//! .set_attributed_to("https://example.com/actor".parse::()?) +//! .set_generator("https://example.com/image-generator".parse::()?) +//! .set_icon("https://example.com/icon.png".parse::()?); +//! # +//! # 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: markers::Object { + /// Immutable borrow of `Object` fn object_ref(&self) -> &Object; + + /// Mutable borrow of `Object` fn object_mut(&mut self) -> &mut Object; } +/// Implementation trait for deriving ActivityPub Object methods for a type +/// +/// Any type implementing AsApObject will automatically gain methods provided by ApObjectExt pub trait AsApObject: markers::Object { + /// Immutable borrow of `ApObject` fn ap_object_ref(&self) -> &ApObject; + + /// Mutable borrow of `ApObject` fn ap_object_mut(&mut self) -> &mut ApObject; } +/// 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: AsObject { /// Fetch the attachment for the current object /// @@ -2706,6 +2774,11 @@ pub trait ObjectExt: AsObject { } } +/// 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: AsApObject { 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> { 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::()?); + /// # Ok(()) + /// # } + /// ``` fn set_object(&mut self, object: T) -> &mut Self where T: Into, @@ -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::()?, + /// "https://example.com/two".parse()?, + /// ]); + /// # Ok(()) + /// # } + /// ``` fn set_many_objects(&mut self, items: I) -> &mut Self where I: IntoIterator, @@ -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::()?) + /// .add_object("https://example.com/two".parse::()?); + /// # Ok(()) + /// # } + /// ``` fn add_object(&mut self, object: T) -> &mut Self where T: Into, @@ -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> { 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::()?); + /// # + /// 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> { 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::()?); + /// # Ok(()) + /// # } + /// ``` fn set_relationship(&mut self, relationship: T) -> &mut Self where T: Into, @@ -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::()?, + /// "https://example.com/two".parse()?, + /// ]); + /// # Ok(()) + /// # } + /// ``` fn set_many_relationships(&mut self, items: I) -> &mut Self where I: IntoIterator, @@ -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::()?) + /// .add_relationship("https://example.com/two".parse::()?); + /// # Ok(()) + /// # } + /// ``` fn add_relationship(&mut self, relationship: T) -> &mut Self where T: Into, @@ -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> { 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::()?); + /// # + /// 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> { 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::()?); + /// # Ok(()) + /// # } + /// ``` fn set_former_type(&mut self, former_type: T) -> &mut Self where T: Into, @@ -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::()?, + /// "https://example.com/two".parse()?, + /// ]); + /// # Ok(()) + /// # } + /// ``` fn set_many_former_types(&mut self, items: I) -> &mut Self where I: IntoIterator, @@ -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::()?) + /// .add_former_type("https://example.com/two".parse::()?); + /// # Ok(()) + /// # } + /// ``` fn add_former_type(&mut self, former_type: T) -> &mut Self where T: Into, @@ -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> { 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::()?); + /// # + /// 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