mirrors/activitystreams
1
0
Fork 0
mirror of https://git.asonix.dog/asonix/activitystreams.git synced 2024-11-22 11:51:00 +00:00
Code Issues Projects Releases Packages Wiki Activity

Update docs

Browse source
This commit is contained in:
asonix 2020-03-13 16:22:08 -05:00
parent aa8c4f9c1d
commit 9593d79bee
9 changed files with 93 additions and 87 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
README.md
View file

@ -9,7 +9,7 @@ __A set of Traits and Types that make up the ActivityStreams and ActivityPub spe
First, add ActivityStreams to your dependencies First, add ActivityStreams to your dependencies
```toml ```toml
activitystreams = "0.4.0" activitystreams = "0.5.0-alpha.0"
``` ```
### Types ### Types
@ -102,7 +102,7 @@ With multiple values
It may seem like interacting with these types might get unweildy, so the `properties` macro It may seem like interacting with these types might get unweildy, so the `properties` macro
also generates methods for interacting with each field. also generates methods for interacting with each field.
```ignore ```rust
fn set_summary_xsd_string<T>(&mut self, T) -> Result<...>; fn set_summary_xsd_string<T>(&mut self, T) -> Result<...>;
fn set_summary_rdf_lang_string<T>(&mut self, T) -> Result<...>; fn set_summary_rdf_lang_string<T>(&mut self, T) -> Result<...>;
fn set_many_summary_xsd_strings<T>(&mut self, Vec<T>) -> Result<...>; fn set_many_summary_xsd_strings<T>(&mut self, Vec<T>) -> Result<...>;
@ -129,7 +129,7 @@ implement `FromStr` for parsing and `Display` to convert back to strings, as wel
For some fields, like `id`, there is only one valid type. methods generated for fields like For some fields, like `id`, there is only one valid type. methods generated for fields like
these will leave out the type name from the function name. these will leave out the type name from the function name.
```ignore ```rust
fn set_id<T>(&mut self, T) -> Result<...>; fn set_id<T>(&mut self, T) -> Result<...>;
fn delete_id(&mut self) -> &mut Self; fn delete_id(&mut self) -> &mut Self;
fn get_id(&self) -> Option<XsdAnyUri>; fn get_id(&self) -> Option<XsdAnyUri>;
@ -144,7 +144,7 @@ compiletime.
If you want to make a function that manipulates an Activity, but not a normal object, you could If you want to make a function that manipulates an Activity, but not a normal object, you could
bound the function like so: bound the function like so:
```ignore ```rust
fn my_manipulator<T>(some_activity: T) -> Result<&mut ObjectProperties, SomeErrorType> fn my_manipulator<T>(some_activity: T) -> Result<&mut ObjectProperties, SomeErrorType>
where where
T: Activity + AsMut<ObjectProperties>, T: Activity + AsMut<ObjectProperties>,
@ -160,7 +160,7 @@ enable different ActivityPub Object types to be deserialized into different Name
These can be found in `activitystreams::objects::kind`, and similar paths. These can be found in `activitystreams::objects::kind`, and similar paths.
To build your own Person struct, for example, you could write To build your own Person struct, for example, you could write
```ignore ```rust
use activitystreams::actor::kind::PersonType; use activitystreams::actor::kind::PersonType;
#[derive(serde::Deserialize, serde::Serialize)] #[derive(serde::Deserialize, serde::Serialize)]
@ -177,7 +177,7 @@ There are a number of features that can be disabled in this crate. By default, e
enabled. enabled.
```toml ```toml
activitystreams = { version = "0.4.0", default-features = "false", features = ["derive"] } activitystreams = { version = "0.5.0-alpha.0", default-features = "false", features = ["derive"] }
``` ```
| feature | what you get | | feature | what you get |
@ -235,22 +235,25 @@ fn main() -> Result<(), Error> {
```rust ```rust
use activitystreams::{ use activitystreams::{
context, context,
actor::{Actor, ActorBox},
object::{ object::{
properties::{ properties::{
ObjectProperties, ObjectProperties,
ProfileProperties ProfileProperties
}, },
apub::Profile, apub::Profile,
Object, ObjectBox,
}, },
primitives::XsdAnyUri, primitives::XsdAnyUri,
Actor, PropRefs,
Object,
}; };
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use std::any::Any; use std::any::Any;
#[derive(Clone, Debug, Default, Deserialize, Serialize)] #[derive(Clone, Debug, Default, Deserialize, Serialize, PropRefs)]
#[serde(rename_all = "camelCase")] #[serde(rename_all = "camelCase")]
#[prop_refs(Object)]
#[prop_refs(Actor)]
pub struct Persona { pub struct Persona {
#[serde(rename = "@context")] #[serde(rename = "@context")]
context: XsdAnyUri, context: XsdAnyUri,
@ -259,22 +262,6 @@ pub struct Persona {
kind: String, kind: String,
} }
#[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 {}
fn main() -> Result<(), anyhow::Error> { fn main() -> Result<(), anyhow::Error> {
let mut profile = Profile::default(); let mut profile = Profile::default();
@ -303,11 +290,9 @@ use activitystreams::{
properties, properties,
link::{ link::{
properties::LinkProperties, properties::LinkProperties,
Mention, Link, LinkBox, Mention,
}, },
Link, PropRefs, UnitString,
PropRefs,
UnitString,
}; };
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
@ -316,7 +301,7 @@ use serde::{Deserialize, Serialize};
/// 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 "MyLink" in JSON. /// represent the string "MyLink" in JSON.
#[derive(Clone, Debug, Default, UnitString)] #[derive(Clone, Debug, Default, UnitString)]
#[activitystreams(MyLink)] #[unit_string(MyLink)]
pub struct MyKind; pub struct MyKind;
properties! { properties! {
@ -344,16 +329,17 @@ properties! {
/// 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, PropRefs)] #[derive(Clone, Debug, Default, Deserialize, Serialize, PropRefs)]
#[serde(rename_all = "camelCase")] #[serde(rename_all = "camelCase")]
#[prop_refs(Link)]
pub struct My { pub struct My {
/// Use the UnitString MyKind to enforce the type of the object by "MyLink" /// Use the UnitString MyKind to enforce the type of the object by "MyLink"
pub kind: MyKind, pub kind: MyKind,
/// Derive AsRef/AsMut for My -> MyProperties /// Derive AsRef/AsMut for My -> MyProperties
#[activitystreams(None)] #[prop_refs]
pub my_properties: MyProperties, pub my_properties: MyProperties,
/// Derive AsRef/AsMut/Link for My -> LinkProperties /// Derive AsRef/AsMut/Link for My -> LinkProperties
#[activitystreams(Link)] #[prop_refs]
pub link_properties: LinkProperties, pub link_properties: LinkProperties,
} }

2
activitystreams-derive/README.md
View file

@ -10,7 +10,7 @@ Add the required crates to your `Cargo.toml`
```toml ```toml
# Cargo.toml # Cargo.toml
activitystreams = "0.4.0" activitystreams = "0.5.0-alpha.0"
serde = { version = "1.0", features = ["derive"] } serde = { version = "1.0", features = ["derive"] }
``` ```

13
activitystreams-derive/src/lib.rs
View file

@ -23,8 +23,8 @@
//! //!
//! First, add `serde` and `activitystreams-derive` to your Cargo.toml //! First, add `serde` and `activitystreams-derive` to your Cargo.toml
//! ```toml //! ```toml
//! activitystreams-derive = "0.4.0" //! activitystreams-derive = "0.5.0-alpha.0"
//! # or activitystreams = "0.4.0" //! # or activitystreams = "0.5.0-alpha.0"
//! serde = { version = "1.0", features = ["derive"] } //! serde = { version = "1.0", features = ["derive"] }
//! ``` //! ```
//! //!
@ -251,15 +251,19 @@ pub fn wrapper_type(_: TokenStream, input: TokenStream) -> TokenStream {
let trait_name = input.ident.clone(); let trait_name = input.ident.clone();
let type_name = Ident::new(&format!("{}Box", trait_name), trait_name.span()); let type_name = Ident::new(&format!("{}Box", trait_name), trait_name.span());
let doc_line = to_doc(&format!("A wrapper type around a generic `{}`", trait_name));
let tokens = quote! { let tokens = quote! {
#input #input
#doc_line
#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)] #[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
#[serde(transparent)] #[serde(transparent)]
pub struct #type_name(pub serde_json::Value); pub struct #type_name(pub serde_json::Value);
impl #type_name { impl #type_name {
/// Create the wrapper type from a concrete type /// Coerce a concrete type into this wrapper type
///
/// This is done automatically via TryFrom in proprties setter methods
pub fn from_concrete<T>(t: T) -> Result<Self, serde_json::Error> pub fn from_concrete<T>(t: T) -> Result<Self, serde_json::Error>
where where
T: #trait_name + serde::ser::Serialize, T: #trait_name + serde::ser::Serialize,
@ -268,6 +272,9 @@ pub fn wrapper_type(_: TokenStream, input: TokenStream) -> TokenStream {
} }
/// Attempt to deserialize the wrapper type to a concrete type /// Attempt to deserialize the wrapper type to a concrete type
///
/// Before this method is called, the type should be verified via the `kind` or
/// `is_kind` methods
pub fn to_concrete<T>(self) -> Result<T, serde_json::Error> pub fn to_concrete<T>(self) -> Result<T, serde_json::Error>
where where
T: #trait_name + serde::de::DeserializeOwned, T: #trait_name + serde::de::DeserializeOwned,

18
src/activity/properties.rs
View file

@ -22,16 +22,22 @@
//! //!
//! ```rust //! ```rust
//! use activitystreams::{ //! use activitystreams::{
//! activity::properties::ActivityProperties, //! activity::{
//! object::properties::ObjectProperties, //! properties::ActivityProperties,
//! Activity, //! Activity, ActivityBox,
//! Object, //! },
//! object::{
//! properties::ObjectProperties,
//! Object, ObjectBox,
//! },
//! PropRefs, //! PropRefs,
//! }; //! };
//! use serde::{Deserialize, Serialize}; //! use serde::{Deserialize, Serialize};
//! //!
//! #[derive(Clone, Debug, Serialize, Deserialize, PropRefs)] //! #[derive(Clone, Debug, Serialize, Deserialize, PropRefs)]
//! #[serde(rename_all = "camelCase")] //! #[serde(rename_all = "camelCase")]
//! #[prop_refs(Object)]
//! #[prop_refs(Activity)]
//! pub struct MyActivity { //! pub struct MyActivity {
//! #[serde(rename = "type")] //! #[serde(rename = "type")]
//! #[serde(alias = "objectType")] //! #[serde(alias = "objectType")]
@ -42,11 +48,11 @@
//! pub my_property: String, //! pub my_property: String,
//! //!
//! #[serde(flatten)] //! #[serde(flatten)]
//! #[activitystreams(Object)] //! #[prop_refs]
//! pub object_properties: ObjectProperties, //! pub object_properties: ObjectProperties,
//! //!
//! #[serde(flatten)] //! #[serde(flatten)]
//! #[activitystreams(Activity)] //! #[prop_refs]
//! pub activity_properties: ActivityProperties, //! pub activity_properties: ActivityProperties,
//! } //! }
//! # //! #

20
src/actor/properties.rs
View file

@ -23,14 +23,22 @@
//! //!
//! ```rust //! ```rust
//! use activitystreams::{ //! use activitystreams::{
//! actor::properties::ApActorProperties, //! actor::{
//! object::properties::{ApObjectProperties, ObjectProperties}, //! properties::ApActorProperties,
//! Actor, Object, PropRefs //! Actor, ActorBox,
//! },
//! object::{
//! properties::{ApObjectProperties, ObjectProperties},
//! Object, ObjectBox,
//! },
//! PropRefs,
//! }; //! };
//! use serde::{Deserialize, Serialize}; //! use serde::{Deserialize, Serialize};
//! //!
//! #[derive(Clone, Debug, Serialize, Deserialize, PropRefs)] //! #[derive(Clone, Debug, Serialize, Deserialize, PropRefs)]
//! #[serde(rename_all = "camelCase")] //! #[serde(rename_all = "camelCase")]
//! #[prop_refs(Object)]
//! #[prop_refs(Actor)]
//! pub struct MyActor { //! pub struct MyActor {
//! #[serde(rename = "type")] //! #[serde(rename = "type")]
//! pub kind: String, //! pub kind: String,
@ -39,15 +47,15 @@
//! pub my_property: String, //! pub my_property: String,
//! //!
//! #[serde(flatten)] //! #[serde(flatten)]
//! #[activitystreams(Object)] //! #[prop_refs]
//! pub object_props: ObjectProperties, //! pub object_props: ObjectProperties,
//! //!
//! #[serde(flatten)] //! #[serde(flatten)]
//! #[activitystreams(None)] //! #[prop_refs]
//! pub ap_object_props: ApObjectProperties, //! pub ap_object_props: ApObjectProperties,
//! //!
//! #[serde(flatten)] //! #[serde(flatten)]
//! #[activitystreams(Actor)] //! #[prop_refs]
//! pub actor_props: ApActorProperties, //! pub actor_props: ApActorProperties,
//! } //! }
//! # //! #

18
src/collection/properties.rs
View file

@ -23,10 +23,14 @@
//! //!
//! ```rust //! ```rust
//! use activitystreams::{ //! use activitystreams::{
//! collection::properties::CollectionProperties, //! collection::{
//! object::properties::ObjectProperties, //! properties::CollectionProperties,
//! Collection, //! Collection, CollectionBox,
//! Object, //! },
//! object::{
//! properties::ObjectProperties,
//! Object, ObjectBox,
//! },
//! PropRefs, //! PropRefs,
//! }; //! };
//! use serde::{Deserialize, Serialize}; //! use serde::{Deserialize, Serialize};
@ -34,6 +38,8 @@
//! //!
//! #[derive(Clone, Debug, Serialize, Deserialize, PropRefs)] //! #[derive(Clone, Debug, Serialize, Deserialize, PropRefs)]
//! #[serde(rename_all = "camelCase")] //! #[serde(rename_all = "camelCase")]
//! #[prop_refs(Object)]
//! #[prop_refs(Collection)]
//! pub struct MyCollection { //! pub struct MyCollection {
//! #[serde(rename = "type")] //! #[serde(rename = "type")]
//! pub kind: String, //! pub kind: String,
@ -42,11 +48,11 @@
//! pub my_property: String, //! pub my_property: String,
//! //!
//! #[serde(flatten)] //! #[serde(flatten)]
//! #[activitystreams(Object)] //! #[prop_refs]
//! pub object_properties: ObjectProperties, //! pub object_properties: ObjectProperties,
//! //!
//! #[serde(flatten)] //! #[serde(flatten)]
//! #[activitystreams(Collection)] //! #[prop_refs]
//! pub collection_properties: CollectionProperties, //! pub collection_properties: CollectionProperties,
//! } //! }
//! # //! #

41
src/lib.rs
View file

@ -25,7 +25,7 @@
//! //!
//! First, add ActivityStreams to your dependencies //! First, add ActivityStreams to your dependencies
//! ```toml //! ```toml
//! activitystreams = "0.4.0" //! activitystreams = "0.5.0-alpha.0"
//! ``` //! ```
//! //!
//! ### Types //! ### Types
@ -193,7 +193,7 @@
//! enabled. //! enabled.
//! //!
//! ```toml //! ```toml
//! activitystreams = { version = "0.4.0", default-features = "false", features = ["derive"] } //! activitystreams = { version = "0.5.0-alpha.0", default-features = "false", features = ["derive"] }
//! ``` //! ```
//! //!
//! | feature | what you get | //! | feature | what you get |
@ -257,16 +257,19 @@
//! ProfileProperties //! ProfileProperties
//! }, //! },
//! apub::Profile, //! apub::Profile,
//! Object,
//! ObjectBox,
//! }, //! },
//! actor::{Actor, ActorBox},
//! primitives::XsdAnyUri, //! primitives::XsdAnyUri,
//! Actor, //! PropRefs,
//! Object,
//! }; //! };
//! use serde::{Deserialize, Serialize}; //! use serde::{Deserialize, Serialize};
//! use std::any::Any;
//! //!
//! #[derive(Clone, Debug, Default, Deserialize, Serialize)] //! #[derive(Clone, Debug, Default, Deserialize, Serialize, PropRefs)]
//! #[serde(rename_all = "camelCase")] //! #[serde(rename_all = "camelCase")]
//! #[prop_refs(Object)]
//! #[prop_refs(Actor)]
//! pub struct Persona { //! pub struct Persona {
//! #[serde(rename = "@context")] //! #[serde(rename = "@context")]
//! context: XsdAnyUri, //! context: XsdAnyUri,
@ -275,22 +278,6 @@
//! kind: String, //! kind: String,
//! } //! }
//! //!
//! #[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 {}
//!
//! fn main() -> Result<(), anyhow::Error> { //! fn main() -> Result<(), anyhow::Error> {
//! let mut profile = Profile::default(); //! let mut profile = Profile::default();
//! //!
@ -319,9 +306,8 @@
//! properties, //! properties,
//! link::{ //! link::{
//! properties::LinkProperties, //! properties::LinkProperties,
//! Mention, //! Link, LinkBox, Mention,
//! }, //! },
//! Link,
//! PropRefs, //! PropRefs,
//! UnitString, //! UnitString,
//! }; //! };
@ -332,7 +318,7 @@
//! /// 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 "MyLink" in JSON. //! /// represent the string "MyLink" in JSON.
//! #[derive(Clone, Debug, Default, UnitString)] //! #[derive(Clone, Debug, Default, UnitString)]
//! #[activitystreams(MyLink)] //! #[unit_string(MyLink)]
//! pub struct MyKind; //! pub struct MyKind;
//! //!
//! properties! { //! properties! {
@ -360,16 +346,17 @@
//! /// 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, PropRefs)] //! #[derive(Clone, Debug, Default, Deserialize, Serialize, PropRefs)]
//! #[serde(rename_all = "camelCase")] //! #[serde(rename_all = "camelCase")]
//! #[prop_refs(Link)]
//! pub struct My { //! pub struct My {
//! /// Use the UnitString MyKind to enforce the type of the object by "MyLink" //! /// Use the UnitString MyKind to enforce the type of the object by "MyLink"
//! pub kind: MyKind, //! pub kind: MyKind,
//! //!
//! /// Derive AsRef/AsMut for My -> MyProperties //! /// Derive AsRef/AsMut for My -> MyProperties
//! #[activitystreams(None)] //! #[prop_refs]
//! pub my_properties: MyProperties, //! pub my_properties: MyProperties,
//! //!
//! /// Derive AsRef/AsMut/Link for My -> LinkProperties //! /// Derive AsRef/AsMut/Link for My -> LinkProperties
//! #[activitystreams(Link)] //! #[prop_refs]
//! pub link_properties: LinkProperties, //! pub link_properties: LinkProperties,
//! } //! }
//! //!

9
src/link/properties.rs
View file

@ -23,8 +23,10 @@
//! //!
//! ```rust //! ```rust
//! use activitystreams::{ //! use activitystreams::{
//! link::properties::LinkProperties, //! link::{
//! Link, //! properties::LinkProperties,
//! Link, LinkBox,
//! },
//! PropRefs, //! PropRefs,
//! }; //! };
//! use serde::{Deserialize, Serialize}; //! use serde::{Deserialize, Serialize};
@ -32,6 +34,7 @@
//! //!
//! #[derive(Clone, Debug, Serialize, Deserialize, PropRefs)] //! #[derive(Clone, Debug, Serialize, Deserialize, PropRefs)]
//! #[serde(rename_all = "camelCase")] //! #[serde(rename_all = "camelCase")]
//! #[prop_refs(Link)]
//! pub struct MyLink { //! pub struct MyLink {
//! #[serde(rename = "type")] //! #[serde(rename = "type")]
//! pub kind: String, //! pub kind: String,
@ -40,7 +43,7 @@
//! pub my_property: String, //! pub my_property: String,
//! //!
//! #[serde(flatten)] //! #[serde(flatten)]
//! #[activitystreams(Link)] //! #[prop_refs]
//! pub link_properties: LinkProperties, //! pub link_properties: LinkProperties,
//! } //! }
//! # //! #

9
src/object/properties.rs
View file

@ -23,8 +23,10 @@
//! //!
//! ```rust //! ```rust
//! use activitystreams::{ //! use activitystreams::{
//! object::properties::ObjectProperties, //! object::{
//! Object, //! properties::ObjectProperties,
//! Object, ObjectBox,
//! },
//! PropRefs, //! PropRefs,
//! }; //! };
//! use serde::{Deserialize, Serialize}; //! use serde::{Deserialize, Serialize};
@ -32,6 +34,7 @@
//! //!
//! #[derive(Clone, Debug, Serialize, Deserialize, PropRefs)] //! #[derive(Clone, Debug, Serialize, Deserialize, PropRefs)]
//! #[serde(rename_all = "camelCase")] //! #[serde(rename_all = "camelCase")]
//! #[prop_refs(Object)]
//! pub struct MyObject { //! pub struct MyObject {
//! #[serde(rename = "type")] //! #[serde(rename = "type")]
//! pub kind: String, //! pub kind: String,
@ -40,7 +43,7 @@
//! pub my_property: String, //! pub my_property: String,
//! //!
//! #[serde(flatten)] //! #[serde(flatten)]
//! #[activitystreams(Object)] //! #[prop_refs]
//! pub object_properties: ObjectProperties, //! pub object_properties: ObjectProperties,
//! } //! }
//! # //! #