mirrors/activitystreams
1
0
Fork 0
mirror of https://git.asonix.dog/asonix/activitystreams.git synced 2024-11-14 14:21:12 +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
```toml
activitystreams = "0.4.0"
activitystreams = "0.5.0-alpha.0"
```
### Types
@ -102,7 +102,7 @@ With multiple values
It may seem like interacting with these types might get unweildy, so the `properties` macro
also generates methods for interacting with each field.
```ignore
```rust
fn set_summary_xsd_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<...>;
@ -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
these will leave out the type name from the function name.
```ignore
```rust
fn set_id<T>(&mut self, T) -> Result<...>;
fn delete_id(&mut self) -> &mut Self;
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
bound the function like so:
```ignore
```rust
fn my_manipulator<T>(some_activity: T) -> Result<&mut ObjectProperties, SomeErrorType>
where
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.
To build your own Person struct, for example, you could write
```ignore
```rust
use activitystreams::actor::kind::PersonType;
#[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.
```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 |
@ -235,22 +235,25 @@ fn main() -> Result<(), Error> {
```rust
use activitystreams::{
context,
actor::{Actor, ActorBox},
object::{
properties::{
ObjectProperties,
ProfileProperties
},
apub::Profile,
Object, ObjectBox,
},
primitives::XsdAnyUri,
Actor,
Object,
PropRefs,
};
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")]
#[prop_refs(Object)]
#[prop_refs(Actor)]
pub struct Persona {
#[serde(rename = "@context")]
context: XsdAnyUri,
@ -259,22 +262,6 @@ pub struct Persona {
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> {
let mut profile = Profile::default();
@ -303,11 +290,9 @@ use activitystreams::{
properties,
link::{
properties::LinkProperties,
Mention,
Link, LinkBox, Mention,
},
Link,
PropRefs,
UnitString,
PropRefs, UnitString,
};
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
/// represent the string "MyLink" in JSON.
#[derive(Clone, Debug, Default, UnitString)]
#[activitystreams(MyLink)]
#[unit_string(MyLink)]
pub struct MyKind;
properties! {
@ -344,16 +329,17 @@ properties! {
/// This macro generates getters and setters for the associated fields.
#[derive(Clone, Debug, Default, Deserialize, Serialize, PropRefs)]
#[serde(rename_all = "camelCase")]
#[prop_refs(Link)]
pub struct My {
/// Use the UnitString MyKind to enforce the type of the object by "MyLink"
pub kind: MyKind,
/// Derive AsRef/AsMut for My -> MyProperties
#[activitystreams(None)]
#[prop_refs]
pub my_properties: MyProperties,
/// Derive AsRef/AsMut/Link for My -> LinkProperties
#[activitystreams(Link)]
#[prop_refs]
pub link_properties: LinkProperties,
}

2
activitystreams-derive/README.md
View file

@ -10,7 +10,7 @@ Add the required crates to your `Cargo.toml`
```toml
# Cargo.toml
activitystreams = "0.4.0"
activitystreams = "0.5.0-alpha.0"
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
//! ```toml
//! activitystreams-derive = "0.4.0"
//! # or activitystreams = "0.4.0"
//! activitystreams-derive = "0.5.0-alpha.0"
//! # or activitystreams = "0.5.0-alpha.0"
//! 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 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! {
#input
#doc_line
#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
#[serde(transparent)]
pub struct #type_name(pub serde_json::Value);
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>
where
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
///
/// 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>
where
T: #trait_name + serde::de::DeserializeOwned,

18
src/activity/properties.rs
View file

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

20
src/actor/properties.rs
View file

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

18
src/collection/properties.rs
View file

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

41
src/lib.rs
View file

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

9
src/link/properties.rs
View file

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

9
src/object/properties.rs
View file

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