From 00bc74b1bfbc326c695949c5e2e6823642d6bbf7 Mon Sep 17 00:00:00 2001 From: asonix Date: Sat, 16 May 2020 10:58:12 -0500 Subject: [PATCH] Base docs --- src/base.rs | 705 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 679 insertions(+), 26 deletions(-) diff --git a/src/base.rs b/src/base.rs index ad075d8..60d5522 100644 --- a/src/base.rs +++ b/src/base.rs @@ -35,7 +35,7 @@ use crate::{ }; use typed_builder::TypedBuilder; -/// Implements conversion between Base and other ActivityStreams objects defined in this +/// Implements conversion between `Base` and other ActivityStreams objects defined in this /// crate pub trait Extends: Sized { /// The erro produced must be a StdError @@ -106,9 +106,12 @@ pub trait ExtendsExt: Extends { /// Implementation trait for deriving Base methods for a type /// -/// Any type Implementating AsBase will automatically gain methods provided by BaseExt +/// Any type implementating AsBase will automatically gain methods provided by BaseExt pub trait AsBase: markers::Base { + /// Immutable borrow of `Base` fn base_ref(&self) -> &Base; + + /// Mutable borrow of Base fn base_mut(&mut self) -> &mut Base; } @@ -242,6 +245,17 @@ pub trait BaseExt: AsBase { } /// Fetch the id for the current object + /// + /// ```rust + /// # use activitystreams_new::{object::Video, primitives::XsdString}; + /// # let mut video = Video::default(); + /// # + /// use activitystreams_new::prelude::*; + /// + /// if let Some(id) = video.id() { + /// println!("{:?}", id); + /// } + /// ``` fn id<'a>(&'a self) -> Option<&'a XsdAnyUri> where Kind: 'a, @@ -252,23 +266,69 @@ pub trait BaseExt: AsBase { /// Set the id for the current object /// /// This overwrites the contents of id + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::{object::Video, primitives::XsdString}; + /// # let mut video = Video::default(); + /// # + /// use activitystreams_new::prelude::*; + /// + /// video.set_id("https://example.com".parse()?); + /// # Ok(()) + /// # } + /// ``` fn set_id(&mut self, id: XsdAnyUri) -> &mut Self { self.base_mut().id = Some(id); self } /// Take the id from the current object, leaving nothing + /// + /// ```rust + /// # use activitystreams_new::{object::Video, primitives::XsdString}; + /// # let mut video = Video::default(); + /// # + /// use activitystreams_new::prelude::*; + /// + /// if let Some(id) = video.take_id() { + /// println!("{:?}", id); + /// } + /// ``` fn take_id(&mut self) -> Option { self.base_mut().id.take() } /// Delete the id from the current object + /// + /// ```rust + /// # use activitystreams_new::{context, object::Video}; + /// # let mut video = Video::default(); + /// # video.set_id(context()); + /// # + /// use activitystreams_new::prelude::*; + /// + /// assert!(video.id().is_some()); + /// video.delete_id(); + /// assert!(video.id().is_none()); + /// ``` fn delete_id(&mut self) -> &mut Self { self.base_mut().id = None; self } /// Fetch the kind for the current object + /// + /// ```rust + /// # use activitystreams_new::{object::Video, primitives::XsdString}; + /// # let mut video = Video::default(); + /// # + /// use activitystreams_new::prelude::*; + /// + /// if let Some(kind) = video.kind() { + /// println!("{:?}", kind); + /// } + /// ``` fn kind<'a>(&'a self) -> Option<&'a Kind> where Kind: 'a, @@ -279,23 +339,65 @@ pub trait BaseExt: AsBase { /// Set the kind for the current object /// /// This overwrites the contents of kind + /// + /// ```rust + /// # use activitystreams_new::object::{Video, kind::VideoType}; + /// # let mut video = Video::default(); + /// use activitystreams_new::prelude::*; + /// + /// video.set_kind(VideoType); + /// ``` fn set_kind(&mut self, kind: Kind) -> &mut Self { self.base_mut().kind = Some(kind); self } /// Take the kind from the current object, leaving nothing + /// + /// ```rust + /// # use activitystreams_new::{object::Video, primitives::XsdString}; + /// # let mut video = Video::default(); + /// # + /// use activitystreams_new::prelude::*; + /// + /// if let Some(kind) = video.take_kind() { + /// println!("{:?}", kind); + /// } + /// ``` fn take_kind(&mut self) -> Option { self.base_mut().kind.take() } /// Delete the kind from the current object + /// + /// ```rust + /// # use activitystreams_new::{object::{Video, kind::VideoType}}; + /// # let mut video = Video::default(); + /// # video.set_kind(VideoType); + /// # + /// use activitystreams_new::prelude::*; + /// + /// assert!(video.kind().is_some()); + /// video.delete_kind(); + /// assert!(video.kind().is_none()); + /// ``` fn delete_kind(&mut self) -> &mut Self { self.base_mut().kind = None; self } /// Fetch the name for the current object + /// + /// ``` + /// # use activitystreams_new::{object::Video, primitives::XsdString}; + /// # let mut video = Video::default(); + /// # + /// use activitystreams_new::prelude::*; + /// + /// if let Some(name) = video.name() { + /// println!("{:?}", name); + /// } + /// ``` fn name<'a>(&'a self) -> Option<&'a OneOrMany> where Kind: 'a, @@ -306,6 +408,14 @@ pub trait BaseExt: AsBase { /// Set the name for the current object /// /// This overwrites the contents of name + /// + /// ```rust + /// use activitystreams_new::prelude::*; + /// # use activitystreams_new::{object::Video, primitives::XsdString}; + /// # let mut video = Video::default(); + /// # + /// video.set_name(XsdString::from("hi")); + /// ``` fn set_name(&mut self, name: T) -> &mut Self where T: Into, @@ -317,6 +427,14 @@ pub trait BaseExt: AsBase { /// Set many names for the current object /// /// This overwrites the contents of name + /// + /// ```rust + /// use activitystreams_new::prelude::*; + /// # use activitystreams_new::{object::Video, primitives::XsdString}; + /// # let mut video = Video::default(); + /// # + /// video.set_many_names(vec![XsdString::from("hi"), XsdString::from("hey")]); + /// ``` fn set_many_names(&mut self, items: I) -> &mut Self where I: IntoIterator, @@ -330,6 +448,16 @@ pub trait BaseExt: AsBase { /// Add a name to the current object /// /// This does not overwrite the contents of name, only appends a new item + /// + /// ```rust + /// use activitystreams_new::prelude::*; + /// # use activitystreams_new::{object::Video, primitives::XsdString}; + /// # let mut video = Video::default(); + /// # + /// video + /// .add_name(XsdString::from("hi")) + /// .add_name(XsdString::from("hey")); + /// ``` fn add_name(&mut self, name: T) -> &mut Self where T: Into, @@ -346,17 +474,51 @@ pub trait BaseExt: AsBase { } /// Take the name from the current object, leaving nothing + /// + /// ```rust + /// # use activitystreams_new::object::Video; + /// # let mut video = Video::default(); + /// # + /// use activitystreams_new::prelude::*; + /// + /// if let Some(name) = video.take_name() { + /// println!("{:?}", name); + /// } + /// ``` fn take_name(&mut self) -> Option> { self.base_mut().name.take() } /// Delete the name from the current object + /// + /// ```rust + /// use activitystreams_new::prelude::*; + /// # use activitystreams_new::{object::Video, primitives::XsdString}; + /// # let mut video = Video::default(); + /// # video.set_name(XsdString::from("hi")); + /// # + /// + /// assert!(video.name().is_some()); + /// video.delete_name(); + /// assert!(video.name().is_none()); + /// ``` fn delete_name(&mut self) -> &mut Self { self.base_mut().name = None; self } /// Fetch the media type for the current object + /// + /// ```rust + /// # use activitystreams_new::object::Video; + /// # let mut video = Video::default(); + /// # + /// use activitystreams_new::prelude::*; + /// + /// if let Some(media_type) = video.media_type() { + /// println!("{:?}", media_type); + /// } + /// ``` fn media_type<'a>(&'a self) -> Option<&'a MimeMediaType> where Kind: 'a, @@ -367,23 +529,71 @@ pub trait BaseExt: AsBase { /// Set the media type for the current object /// /// This overwrites the contents of media_type + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// use activitystreams_new::prelude::*; + /// # use activitystreams_new::{object::Video, primitives::XsdAnyUri}; + /// # let mut video = Video::default(); + /// + /// video.set_media_type("video/webm".parse()?); + /// # Ok(()) + /// # } + /// ``` fn set_media_type(&mut self, media_type: MimeMediaType) -> &mut Self { self.base_mut().media_type = Some(media_type); self } /// Take the media type from the current object, leaving nothing + /// + /// ```rust + /// # use activitystreams_new::object::Video; + /// # let mut video = Video::default(); + /// # + /// use activitystreams_new::prelude::*; + /// + /// if let Some(media_type) = video.take_media_type() { + /// println!("{:?}", media_type); + /// } + /// ``` fn take_media_type(&mut self) -> Option { self.base_mut().media_type.take() } /// Delete the media type from the current object + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::{object::Video}; + /// # let mut video = Video::default(); + /// # video.set_media_type("video/webm".parse()?); + /// # + /// use activitystreams_new::prelude::*; + /// + /// assert!(video.media_type().is_some()); + /// video.delete_media_type(); + /// assert!(video.media_type().is_none()); + /// # Ok(()) + /// # } + /// ``` fn delete_media_type(&mut self) -> &mut Self { self.base_mut().media_type = None; self } /// Fetch the preview for the current object + /// + /// ```rust + /// # use activitystreams_new::object::Video; + /// # let mut video = Video::default(); + /// # + /// use activitystreams_new::prelude::*; + /// + /// if let Some(preview) = video.preview() { + /// println!("{:?}", preview); + /// } + /// ``` fn preview<'a>(&'a self) -> Option<&'a OneOrMany> where Kind: 'a, @@ -394,6 +604,17 @@ pub trait BaseExt: AsBase { /// Set the preview for the current object /// /// This overwrites the contents of preview + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// use activitystreams_new::prelude::*; + /// # use activitystreams_new::{object::Video, primitives::XsdAnyUri}; + /// # let mut video = Video::default(); + /// + /// video.set_preview("https://example.com".parse::()?); + /// # Ok(()) + /// # } + /// ``` fn set_preview(&mut self, preview: T) -> &mut Self where T: Into, @@ -405,6 +626,20 @@ pub trait BaseExt: AsBase { /// Set many previews for the current object /// /// This overwrites the contents of preview + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// use activitystreams_new::prelude::*; + /// # use activitystreams_new::{object::Video, primitives::XsdAnyUri}; + /// # let mut video = Video::default(); + /// + /// video.set_many_previews(vec![ + /// "https://example.com/one".parse::()?, + /// "https://example.com/two".parse()?, + /// ]); + /// # Ok(()) + /// # } + /// ``` fn set_many_previews(&mut self, items: I) -> &mut Self where I: IntoIterator, @@ -418,6 +653,19 @@ pub trait BaseExt: AsBase { /// Add a preview to the current object /// /// This does not overwrite the contents of preview, only appends an item + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// use activitystreams_new::prelude::*; + /// # use activitystreams_new::{object::Video, primitives::XsdAnyUri}; + /// # let mut video = Video::default(); + /// + /// video + /// .add_preview("https://example.com/one".parse::()?) + /// .add_preview("https://example.com/two".parse::()?); + /// # Ok(()) + /// # } + /// ``` fn add_preview(&mut self, preview: T) -> &mut Self where T: Into, @@ -434,11 +682,37 @@ pub trait BaseExt: AsBase { } /// Take the preview from the current object, leaving nothing + /// + /// ```rust + /// # use activitystreams_new::object::Video; + /// # let mut video = Video::default(); + /// # + /// use activitystreams_new::prelude::*; + /// + /// if let Some(preview) = video.take_preview() { + /// println!("{:?}", preview); + /// } + /// ``` fn take_preview(&mut self) -> Option> { self.base_mut().preview.take() } /// Delete the preview from the current object + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::{object::Video, primitives::XsdAnyUri}; + /// # let mut video = Video::default(); + /// # video.set_preview("https://example.com".parse::()?); + /// # + /// use activitystreams_new::prelude::*; + /// + /// assert!(video.preview().is_some()); + /// video.delete_preview(); + /// assert!(video.preview().is_none()); + /// # Ok(()) + /// # } + /// ``` fn delete_preview(&mut self) -> &mut Self { self.base_mut().preview = None; self @@ -565,7 +839,7 @@ pub struct Base { } impl Base { - /// Convert this Base into a Base + /// Convert this `Base` into a `Base` /// /// This is required before extending Base into the other types found in this crate pub fn solidify(self) -> Result, serde_json::Error> @@ -596,7 +870,7 @@ impl Base { T::extends(self) } - /// Retract any other ActivityStreams type into a Base + /// Retract any other ActivityStreams type into a `Base` /// /// ```rust /// # fn main() -> Result<(), anyhow::Error> { @@ -615,7 +889,7 @@ impl Base { t.retracts() } - /// Convert this Base into a Base + /// Convert this Base into a `Base` /// /// This is required before putting a Base into an AnyBase type pub fn into_generic(self) -> Result, serde_json::Error> @@ -625,7 +899,8 @@ impl Base { self.try_map_kind(serde_json::to_value) } - /// An inffalible conversion from Base to Base where there is a known path from T to U + /// An inffalible conversion from `Base` to `Base` where there is a known path from T to + /// U /// /// ```rust /// use activitystreams_new::{base::Base, prelude::*}; @@ -653,7 +928,22 @@ impl Base { } } - /// A fallible conversion from Base to Base + /// A fallible conversion from `Base to Base` + /// + /// ```rust + /// use activitystreams_new::{base::Base, prelude::*}; + /// + /// let mut base = Base::::default(); + /// base.set_kind("Hey".to_owned()); + /// + /// let new_base = base.try_map_kind(|kind| match kind.as_str() { + /// "Create" => Ok(1), + /// "Update" => Ok(5), + /// _ => Err(anyhow::Error::msg("invalid kind")), + /// }); + /// + /// assert!(new_base.is_err()); + /// ``` pub fn try_map_kind( self, f: impl Fn(Kind) -> Result, @@ -675,7 +965,16 @@ impl Base { } impl AnyBase { - /// Convert any type that is extended from Base into an AnyBase for storing + /// Convert any type that is extended from `Base` into an AnyBase for storing + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::{object::Video, base::AnyBase}; + /// # let video = Video::default(); + /// let any_base = AnyBase::from_extended(video)?; + /// # Ok(()) + /// # } + /// ``` pub fn from_extended(extended: T) -> Result where T: Extends, @@ -686,6 +985,15 @@ impl AnyBase { } /// Check if this object is an XsdAnyUri + /// + /// ```rust + /// # use activitystreams_new::base::AnyBase; + /// # fn main() -> Result<(), anyhow::Error> { + /// let any_base = AnyBase::from_xsd_any_uri("https://example.com".parse()?); + /// assert!(any_base.is_xsd_any_uri()); + /// # Ok(()) + /// # } + /// ``` pub fn is_xsd_any_uri(&self) -> bool { self.0 .as_ref() @@ -695,11 +1003,30 @@ impl AnyBase { } /// Check if this object is an XsdString + /// + /// ```rust + /// # use activitystreams_new::base::AnyBase; + /// # fn main() -> Result<(), anyhow::Error> { + /// let any_base = AnyBase::from_xsd_string("Profile".into()); + /// assert!(any_base.is_xsd_string()); + /// # Ok(()) + /// # } + /// ``` pub fn is_xsd_string(&self) -> bool { self.0.as_ref().right().is_some() } - /// Check if this object is a Base + /// Check if this object is a `Base` + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::{object::Video, base::AnyBase}; + /// # let video = Video::default(); + /// let any_base = AnyBase::from_extended(video)?; + /// assert!(any_base.is_base()); + /// # Ok(()) + /// # } + /// ``` pub fn is_base(&self) -> bool { self.0.as_ref().left().and_then(|l| l.as_base()).is_some() } @@ -708,6 +1035,35 @@ impl AnyBase { /// /// This method checks if the current object _is_ an ID, and then falls back on the `id` field /// within the `Base` if that exists + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::{ + /// # object::Video, base::AnyBase, prelude::*, primitives::XsdAnyUri + /// # }; + /// # let mut video = Video::default(); + /// let id = "https://example.com".parse::()?; + /// + /// video.set_id(id.clone()); + /// + /// let any_base = AnyBase::from_extended(video)?; + /// assert!(any_base.id().unwrap() == &id); + /// # Ok(()) + /// # } + /// ``` + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::{ + /// # base::AnyBase, prelude::*, primitives::XsdAnyUri + /// # }; + /// let id = "https://example.com".parse::()?; + /// + /// let any_base = AnyBase::from_xsd_any_uri(id.clone()); + /// assert!(any_base.id().unwrap() == &id); + /// # Ok(()) + /// # } + /// ``` pub fn id(&self) -> Option<&XsdAnyUri> { self.as_xsd_any_uri() .or_else(|| self.as_base().and_then(|base| base.id.as_ref())) @@ -716,69 +1072,222 @@ impl AnyBase { /// Get the kind from the current object /// /// This method only produces a value if the current object is a `Base` + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::{ + /// # object::{kind::VideoType, Video}, base::AnyBase, prelude::*, + /// # }; + /// # let mut video = Video::default(); + /// # + /// video.set_kind(VideoType); + /// + /// let any_base = AnyBase::from_extended(video)?; + /// + /// match any_base.kind().and_then(|k| k.as_str()) { + /// Some("Video") => println!("yay!"), + /// _ => return Err(anyhow::Error::msg("invalid type found")), + /// } + /// # Ok(()) + /// # } + /// ``` pub fn kind(&self) -> Option<&serde_json::Value> { self.as_base().and_then(|base| base.kind.as_ref()) } /// Get the object as an XsdAnyUri + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::base::AnyBase; + /// # + /// let any_base = AnyBase::from_xsd_any_uri("https://example.com".parse()?); + /// + /// assert!(any_base.as_xsd_any_uri().is_some()); + /// # + /// # Ok(()) + /// # } + /// ``` pub fn as_xsd_any_uri(&self) -> Option<&XsdAnyUri> { self.0.as_ref().left().and_then(|l| l.as_xsd_any_uri()) } /// Get the object as an XsdString + /// + /// ```rust + /// # use activitystreams_new::base::AnyBase; + /// # + /// let any_base = AnyBase::from_xsd_string("hi".into()); + /// + /// assert!(any_base.as_xsd_string().is_some()); + /// ``` pub fn as_xsd_string(&self) -> Option<&XsdString> { self.0.as_ref().right() } - /// Get the object as a Base + /// Get the object as a `Base` + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::{base::AnyBase, object::Video}; + /// # let video = Video::default(); + /// # + /// let any_base = AnyBase::from_extended(video)?; + /// + /// assert!(any_base.as_base().is_some()); + /// # + /// # Ok(()) + /// # } + /// ``` pub fn as_base(&self) -> Option<&Base> { self.0.as_ref().left().and_then(|l| l.as_base()) } /// Take the XsdAnyUri from the Object + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::base::AnyBase; + /// # + /// let any_base = AnyBase::from_xsd_any_uri("https://example.com".parse()?); + /// + /// assert!(any_base.take_xsd_any_uri().is_some()); + /// # + /// # Ok(()) + /// # } + /// ``` pub fn take_xsd_any_uri(self) -> Option { self.0.left().and_then(|l| l.id()) } /// Take the XsdString from the Object + /// + /// ```rust + /// # use activitystreams_new::base::AnyBase; + /// # + /// let any_base = AnyBase::from_xsd_string("hi".into()); + /// + /// assert!(any_base.take_xsd_string().is_some()); + /// ``` pub fn take_xsd_string(self) -> Option { self.0.right() } - /// Take the Base from the Object + /// Take the `Base` from the Object + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::{base::AnyBase, object::Video}; + /// # let video = Video::default(); + /// # + /// let any_base = AnyBase::from_extended(video)?; + /// + /// assert!(any_base.take_base().is_some()); + /// # + /// # Ok(()) + /// # } + /// ``` pub fn take_base(self) -> Option> { self.0.left().and_then(|l| l.base()) } /// Replace the object with the provided XsdAnyUri + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::base::AnyBase; + /// # + /// let mut any_base = AnyBase::from_xsd_string("hi".into()); + /// + /// any_base.set_xsd_any_uri("https://example.com".parse()?); + /// + /// assert!(any_base.take_xsd_any_uri().is_some()); + /// # + /// # Ok(()) + /// # } + /// ``` pub fn set_xsd_any_uri(&mut self, id: XsdAnyUri) { self.0 = Either::Left(IdOrBase::from_xsd_any_uri(id)); } - /// Replace the object with the provided Base - pub fn set_base(&mut self, base: Base) { - self.0 = Either::Left(IdOrBase::from_base(base)); - } - /// Replace the object with the provided XsdString + /// + /// ``` + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::base::AnyBase; + /// # + /// let mut any_base = AnyBase::from_xsd_any_uri("https://example.com".parse()?); + /// + /// any_base.set_xsd_string("hi".into()); + /// + /// assert!(any_base.take_xsd_string().is_some()); + /// # + /// # Ok(()) + /// # } + /// ``` pub fn set_xsd_string(&mut self, xsd_string: XsdString) { self.0 = Either::Right(xsd_string); } + /// Replace the object with the provided `Base` + /// + /// ``` + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::{base::{AnyBase, Base}, object::Video}; + /// # let video = Video::default(); + /// let mut any_base = AnyBase::from_xsd_string("hi".into()); + /// + /// let base = Base::retract(video)?.into_generic()?; + /// any_base.set_base(base); + /// + /// assert!(any_base.take_base().is_some()); + /// # + /// # Ok(()) + /// # } + /// ``` + pub fn set_base(&mut self, base: Base) { + self.0 = Either::Left(IdOrBase::from_base(base)); + } + /// Create an AnyBase from an XsdAnyUri + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// use activitystreams_new::base::AnyBase; + /// let any_base = AnyBase::from_xsd_any_uri("https://example.com".parse()?); + /// # Ok(()) + /// # } + /// ``` pub fn from_xsd_any_uri(id: XsdAnyUri) -> Self { AnyBase(Either::Left(IdOrBase::from_xsd_any_uri(id))) } - /// Create an AnyBase from a Base - pub fn from_base(base: Base) -> Self { - AnyBase(Either::Left(IdOrBase::from_base(base))) - } - /// Create an AnyBase from an XsdString + /// + /// ```rust + /// use activitystreams_new::base::AnyBase; + /// let any_base = AnyBase::from_xsd_string("hi".into()); + /// ``` pub fn from_xsd_string(xsd_string: XsdString) -> Self { AnyBase(Either::Right(xsd_string)) } + + /// Create an AnyBase from a `Base` + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::object::Video; + /// # let video = Video::default(); + /// use activitystreams_new::base::{AnyBase, Base}; + /// + /// let base = Base::retract(video)?.into_generic()?; + /// let any_base = AnyBase::from_base(base); + /// # Ok(()) + /// # } + /// ``` + pub fn from_base(base: Base) -> Self { + AnyBase(Either::Left(IdOrBase::from_base(base))) + } } impl IdOrBase { @@ -809,79 +1318,223 @@ impl IdOrBase { impl OneOrMany { /// Get a single XsdAnyUri from the object, if that is what is contained + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::primitives::OneOrMany; + /// # + /// let one = OneOrMany::from_xsd_any_uri("https://example.com".parse()?); + /// + /// assert!(one.as_single_xsd_any_uri().is_some()); + /// # + /// # Ok(()) + /// # } + /// ``` pub fn as_single_xsd_any_uri(&self) -> Option<&XsdAnyUri> { self.as_one().and_then(|inner| inner.as_xsd_any_uri()) } /// Get a single XsdString from the object, if that is what is contained + /// + /// ```rust + /// # use activitystreams_new::{base::AnyBase, primitives::OneOrMany}; + /// # + /// let one = OneOrMany::::from_xsd_string("hi".into()); + /// + /// assert!(one.as_single_xsd_string().is_some()); + /// ``` pub fn as_single_xsd_string(&self) -> Option<&XsdString> { self.as_one().and_then(|inner| inner.as_xsd_string()) } - /// Get a single Base from the object, if that is what is contained + /// Get a single `Base` from the object, if that is what is contained + /// + /// ```rust + /// # use activitystreams_new::{base::Base, primitives::OneOrMany}; + /// # let base = Base::default(); + /// # + /// let one = OneOrMany::from_base(base); + /// + /// assert!(one.as_single_base().is_some()); + /// ``` pub fn as_single_base(&self) -> Option<&Base> { self.as_one().and_then(|inner| inner.as_base()) } /// Take a single XsdAnyUri from the object, if that is what is contained + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// # use activitystreams_new::primitives::OneOrMany; + /// # + /// let one = OneOrMany::from_xsd_any_uri("https://example.com".parse()?); + /// + /// assert!(one.single_xsd_any_uri().is_some()); + /// # + /// # Ok(()) + /// # } + /// ``` pub fn single_xsd_any_uri(self) -> Option { self.one().and_then(|inner| inner.take_xsd_any_uri()) } /// Take a single XsdString from the object, if that is what is contained + /// + /// ```rust + /// # use activitystreams_new::{base::AnyBase, primitives::OneOrMany}; + /// # + /// let one = OneOrMany::::from_xsd_string("hi".into()); + /// + /// assert!(one.single_xsd_string().is_some()); + /// ``` pub fn single_xsd_string(self) -> Option { self.one().and_then(|inner| inner.take_xsd_string()) } - /// Take a single Base from the object, if that is what is contained + /// Take a single `Base` from the object, if that is what is contained + /// + /// ```rust + /// # use activitystreams_new::{base::Base, primitives::OneOrMany}; + /// # let base = Base::default(); + /// # + /// let one = OneOrMany::from_base(base); + /// + /// assert!(one.single_base().is_some()); + /// ``` pub fn single_base(self) -> Option> { self.one().and_then(|inner| inner.take_base()) } /// Create a OneOrMany from an XsdAnyUri + /// + /// ```rust + /// # fn main() -> Result<(), anyhow::Error> { + /// use activitystreams_new::primitives::OneOrMany; + /// + /// let one = OneOrMany::from_xsd_any_uri("https://example.com".parse()?); + /// # Ok(()) + /// # } + /// ``` pub fn from_xsd_any_uri(id: XsdAnyUri) -> Self { OneOrMany(Either::Left(AnyBase::from_xsd_any_uri(id))) } /// Create a OneOrMany from an XsdString + /// + /// ```rust + /// use activitystreams_new::{base::AnyBase, primitives::OneOrMany}; + /// + /// let one = OneOrMany::::from_xsd_string("hi".into()); + /// ``` pub fn from_xsd_string(xsd_string: XsdString) -> Self { OneOrMany(Either::Left(AnyBase::from_xsd_string(xsd_string))) } - /// Create a OneOrMany from a Base + /// Create a OneOrMany from a `Base` + /// + /// ```rust + /// # use activitystreams_new::base::Base; + /// # let base = Base::default(); + /// # + /// use activitystreams_new::primitives::OneOrMany; + /// + /// let one = OneOrMany::from_base(base); + /// ``` pub fn from_base(base: Base) -> Self { OneOrMany(Either::Left(AnyBase::from_base(base))) } /// Overwrite the current object with an XsdAnyUri + /// + /// ```rust + /// # use activitystreams_new::{base::Base, context, primitives::OneOrMany}; + /// # let base = Base::default(); + /// # + /// let mut one = OneOrMany::from_base(base); + /// + /// one.set_single_xsd_any_uri(context()); + /// + /// assert!(one.as_single_xsd_any_uri().is_some()); + /// ``` pub fn set_single_xsd_any_uri(&mut self, id: XsdAnyUri) -> &mut Self { self.0 = Either::Left(AnyBase::from_xsd_any_uri(id)); self } /// Overwrite the current object with an XsdString + /// + /// ```rust + /// # use activitystreams_new::{base::Base, primitives::OneOrMany}; + /// # let base = Base::default(); + /// # + /// let mut one = OneOrMany::from_base(base); + /// + /// one.set_single_xsd_string("hi".into()); + /// + /// assert!(one.as_single_xsd_string().is_some()); + /// ``` pub fn set_single_xsd_string(&mut self, xsd_string: XsdString) -> &mut Self { self.0 = Either::Left(AnyBase::from_xsd_string(xsd_string)); self } - /// Overwrite the current object with a Base + /// Overwrite the current object with a `Base` + /// + /// ``` + /// # use activitystreams_new::{base::Base, context, primitives::OneOrMany}; + /// # let base = Base::default(); + /// # + /// let mut one = OneOrMany::from_xsd_any_uri(context()); + /// + /// one.set_single_base(base); + /// + /// assert!(one.as_single_base().is_some()); + /// ``` pub fn set_single_base(&mut self, base: Base) -> &mut Self { self.0 = Either::Left(AnyBase::from_base(base)); self } /// Append an XsdAnyUri to the current object + /// + /// ```rust + /// use activitystreams_new::{base::AnyBase, context, primitives::OneOrMany, security}; + /// + /// let mut many = OneOrMany::::from_xsd_string("hi".into()); + /// + /// many.add_xsd_any_uri(security()) + /// .add_xsd_any_uri(context()); + /// ``` pub fn add_xsd_any_uri(&mut self, id: XsdAnyUri) -> &mut Self { self.add(AnyBase::from_xsd_any_uri(id)) } /// Append an XsdString to the current object + /// + /// ```rust + /// use activitystreams_new::{context, primitives::OneOrMany}; + /// + /// let mut many = OneOrMany::from_xsd_any_uri(context()); + /// + /// many.add_xsd_string("hi".into()) + /// .add_xsd_string("hello".into()); + /// ``` pub fn add_xsd_string(&mut self, xsd_string: XsdString) -> &mut Self { self.add(AnyBase::from_xsd_string(xsd_string)) } - /// Append a Base to the current object + /// Append a `Base` to the current object + /// + /// ```rust + /// # use activitystreams_new::base::Base; + /// # let base1 = Base::default(); + /// # let base2 = Base::default(); + /// use activitystreams_new::{context, primitives::OneOrMany}; + /// + /// let mut many = OneOrMany::from_xsd_any_uri(context()); + /// + /// many.add_base(base1).add_base(base2); + /// ``` pub fn add_base(&mut self, base: Base) -> &mut Self { self.add(AnyBase::from_base(base)) }