From 497bdbe3dda8f9f060eba55104ae427a3abe7435 Mon Sep 17 00:00:00 2001 From: Charles Chege Date: Thu, 28 Oct 2021 15:46:38 +0300 Subject: [PATCH] Document the macros. Add code examples for the macros --- sea-orm-macros/src/attributes.rs | 2 + sea-orm-macros/src/derives/active_model.rs | 1 + .../src/derives/active_model_behavior.rs | 1 + sea-orm-macros/src/derives/column.rs | 4 + sea-orm-macros/src/derives/entity_model.rs | 1 + .../src/derives/from_query_result.rs | 1 + .../src/derives/into_active_model.rs | 2 + sea-orm-macros/src/derives/model.rs | 1 + sea-orm-macros/src/derives/primary_key.rs | 1 + sea-orm-macros/src/derives/relation.rs | 1 + sea-orm-macros/src/lib.rs | 123 ++++++++++++++++++ 11 files changed, 138 insertions(+) diff --git a/sea-orm-macros/src/attributes.rs b/sea-orm-macros/src/attributes.rs index fbfa0778..3f479bb9 100644 --- a/sea-orm-macros/src/attributes.rs +++ b/sea-orm-macros/src/attributes.rs @@ -1,6 +1,7 @@ pub mod derive_attr { use bae::FromAttributes; + /// Attributes for Models and ActiveModels #[derive(Default, FromAttributes)] pub struct SeaOrm { pub column: Option, @@ -16,6 +17,7 @@ pub mod derive_attr { pub mod field_attr { use bae::FromAttributes; + /// Operations for Models and ActiveModels #[derive(Default, FromAttributes)] pub struct SeaOrm { pub belongs_to: Option, diff --git a/sea-orm-macros/src/derives/active_model.rs b/sea-orm-macros/src/derives/active_model.rs index add31f20..d691a724 100644 --- a/sea-orm-macros/src/derives/active_model.rs +++ b/sea-orm-macros/src/derives/active_model.rs @@ -4,6 +4,7 @@ use proc_macro2::{Ident, TokenStream}; use quote::{format_ident, quote, quote_spanned}; use syn::{punctuated::Punctuated, token::Comma, Data, DataStruct, Field, Fields, Lit, Meta, Type}; +/// Method to derive an [ActiveModel](sea_orm::ActiveModel) pub fn expand_derive_active_model(ident: Ident, data: Data) -> syn::Result { let fields = match data { Data::Struct(DataStruct { diff --git a/sea-orm-macros/src/derives/active_model_behavior.rs b/sea-orm-macros/src/derives/active_model_behavior.rs index 7ae9d375..0ff02f34 100644 --- a/sea-orm-macros/src/derives/active_model_behavior.rs +++ b/sea-orm-macros/src/derives/active_model_behavior.rs @@ -2,6 +2,7 @@ use proc_macro2::{Ident, TokenStream}; use quote::quote; use syn::Data; +/// Method to derive an implementation of [ActiveModelBehavior](sea_orm::ActiveModelBehavior) pub fn expand_derive_active_model_behavior(_ident: Ident, _data: Data) -> syn::Result { Ok(quote!( #[automatically_derived] diff --git a/sea-orm-macros/src/derives/column.rs b/sea-orm-macros/src/derives/column.rs index 7446340e..ed035e0b 100644 --- a/sea-orm-macros/src/derives/column.rs +++ b/sea-orm-macros/src/derives/column.rs @@ -3,6 +3,8 @@ use proc_macro2::{Ident, TokenStream}; use quote::{quote, quote_spanned}; use syn::{punctuated::Punctuated, token::Comma, Data, DataEnum, Fields, Lit, Meta, Variant}; +/// FIXME +/// Method to derive default column names from a &str pub fn impl_default_as_str(ident: &Ident, data: &Data) -> syn::Result { let variants = match data { syn::Data::Enum(DataEnum { variants, .. }) => variants, @@ -65,6 +67,7 @@ pub fn impl_default_as_str(ident: &Ident, data: &Data) -> syn::Result syn::Result { let data_enum = match data { Data::Enum(data_enum) => data_enum, @@ -114,6 +117,7 @@ pub fn expand_derive_column(ident: &Ident, data: &Data) -> syn::Result syn::Result { let impl_default_as_str = impl_default_as_str(ident, data)?; let impl_col_from_str = impl_col_from_str(ident, data)?; diff --git a/sea-orm-macros/src/derives/entity_model.rs b/sea-orm-macros/src/derives/entity_model.rs index 3329731a..9b649922 100644 --- a/sea-orm-macros/src/derives/entity_model.rs +++ b/sea-orm-macros/src/derives/entity_model.rs @@ -7,6 +7,7 @@ use syn::{ Lit, Meta, }; +/// Method to derive an Model pub fn expand_derive_entity_model(data: Data, attrs: Vec) -> syn::Result { // if #[sea_orm(table_name = "foo", schema_name = "bar")] specified, create Entity struct let mut table_name = None; diff --git a/sea-orm-macros/src/derives/from_query_result.rs b/sea-orm-macros/src/derives/from_query_result.rs index fcef9da3..dc6bbc44 100644 --- a/sea-orm-macros/src/derives/from_query_result.rs +++ b/sea-orm-macros/src/derives/from_query_result.rs @@ -2,6 +2,7 @@ use proc_macro2::{Ident, TokenStream}; use quote::{format_ident, quote, quote_spanned}; use syn::{Data, DataStruct, Field, Fields}; +/// Method to derive a [QueryResult](sea_orm::QueryResult) pub fn expand_derive_from_query_result(ident: Ident, data: Data) -> syn::Result { let fields = match data { Data::Struct(DataStruct { diff --git a/sea-orm-macros/src/derives/into_active_model.rs b/sea-orm-macros/src/derives/into_active_model.rs index 3d95e927..2f7dc3f2 100644 --- a/sea-orm-macros/src/derives/into_active_model.rs +++ b/sea-orm-macros/src/derives/into_active_model.rs @@ -2,6 +2,7 @@ use bae::FromAttributes; use proc_macro2::{Span, TokenStream}; use quote::{quote, quote_spanned}; +/// Attributes to derive an ActiveModel #[derive(Default, FromAttributes)] pub struct SeaOrm { pub active_model: Option, @@ -89,6 +90,7 @@ impl IntoActiveModel { } } +/// Method to derive the ActiveModel from the [ActiveModelTrait](sea_orm::ActiveModelTrait) pub fn expand_into_active_model(input: syn::DeriveInput) -> syn::Result { let ident_span = input.ident.span(); diff --git a/sea-orm-macros/src/derives/model.rs b/sea-orm-macros/src/derives/model.rs index 85d690f2..97ca66a8 100644 --- a/sea-orm-macros/src/derives/model.rs +++ b/sea-orm-macros/src/derives/model.rs @@ -183,6 +183,7 @@ impl DeriveModel { } } +/// Method to derive an ActiveModel pub fn expand_derive_model(input: syn::DeriveInput) -> syn::Result { let ident_span = input.ident.span(); diff --git a/sea-orm-macros/src/derives/primary_key.rs b/sea-orm-macros/src/derives/primary_key.rs index f699749f..13c7b5ab 100644 --- a/sea-orm-macros/src/derives/primary_key.rs +++ b/sea-orm-macros/src/derives/primary_key.rs @@ -3,6 +3,7 @@ use proc_macro2::{Ident, TokenStream}; use quote::{quote, quote_spanned}; use syn::{Data, DataEnum, Fields, Variant}; +/// Method to derive a Primary Key for a Model using the [PrimaryKeyTrait](sea_orm::PrimaryKeyTrait) pub fn expand_derive_primary_key(ident: Ident, data: Data) -> syn::Result { let variants = match data { syn::Data::Enum(DataEnum { variants, .. }) => variants, diff --git a/sea-orm-macros/src/derives/relation.rs b/sea-orm-macros/src/derives/relation.rs index 4304ab21..ee4f332c 100644 --- a/sea-orm-macros/src/derives/relation.rs +++ b/sea-orm-macros/src/derives/relation.rs @@ -166,6 +166,7 @@ impl DeriveRelation { } } +/// Method to derive a Relation pub fn expand_derive_relation(input: syn::DeriveInput) -> syn::Result { let ident_span = input.ident.span(); diff --git a/sea-orm-macros/src/lib.rs b/sea-orm-macros/src/lib.rs index cf8c2f3c..bdc52f0f 100644 --- a/sea-orm-macros/src/lib.rs +++ b/sea-orm-macros/src/lib.rs @@ -7,6 +7,14 @@ mod attributes; mod derives; mod util; +/// Create an Entity +/// ### Usage +/// ``` +/// use sea_orm::entity::prelude::*; +/// +///#[derive(Copy, Clone, Default, Debug, DeriveEntity)] +///pub struct Entity; +/// ``` #[proc_macro_derive(DeriveEntity, attributes(sea_orm))] pub fn derive_entity(input: TokenStream) -> TokenStream { let input = parse_macro_input!(input as DeriveInput); @@ -15,6 +23,21 @@ pub fn derive_entity(input: TokenStream) -> TokenStream { .into() } +/// This derive macro is the 'almighty' macro which automatically generates +/// Entity, Column, and PrimaryKey from a given Model. +/// ### Usage +/// use sea_orm::entity::prelude::*; +/// +/// #[derive(Clone, Debug, PartialEq, DeriveEntityModel, Deserialize, Serialize, FromForm)] +/// #[sea_orm(table_name = "posts")] +/// pub struct Model { +/// #[sea_orm(primary_key)] +/// pub id: i32, +/// pub title: String, +/// #[sea_orm(column_type = "Text")] +/// pub text: String, +/// } +/// ``` #[proc_macro_derive(DeriveEntityModel, attributes(sea_orm))] pub fn derive_entity_model(input: TokenStream) -> TokenStream { let input_ts = input.clone(); @@ -36,6 +59,19 @@ pub fn derive_entity_model(input: TokenStream) -> TokenStream { ts } +/// The DerivePrimaryKey derive macro will implement [PrimaryKeyToColumn] +/// for PrimaryKey which defines tedious mappings between primary keys and columns. +/// The [EnumIter] is also derived, allowing iteration over all enum variants. +/// ### Usage +/// ``` +/// use sea_orm::entity::prelude::*; +/// +/// #[derive(Copy, Clone, Debug, EnumIter, DerivePrimaryKey)] +/// pub enum PrimaryKey { +/// CakeId, +/// FillingId, +/// } +/// ``` #[proc_macro_derive(DerivePrimaryKey)] pub fn derive_primary_key(input: TokenStream) -> TokenStream { let DeriveInput { ident, data, .. } = parse_macro_input!(input); @@ -46,6 +82,19 @@ pub fn derive_primary_key(input: TokenStream) -> TokenStream { } } +/// The DeriveColumn derive macro will implement [ColumnTrait] for Columns. +/// It defines the identifier of each column by implementing Iden and IdenStatic. +/// The EnumIter is also derived, allowing iteration over all enum variants. +/// ### Usage +/// ``` +/// use sea_orm::entity::prelude::*; +/// +/// #[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)] +/// pub enum Column { +/// CakeId, +/// FillingId, +/// } +/// ``` #[proc_macro_derive(DeriveColumn, attributes(sea_orm))] pub fn derive_column(input: TokenStream) -> TokenStream { let DeriveInput { ident, data, .. } = parse_macro_input!(input); @@ -56,6 +105,13 @@ pub fn derive_column(input: TokenStream) -> TokenStream { } } +/// Derive a column if column names are not in snake-case +/// #[derive(Copy, Clone, Debug, EnumIter, DeriveCustomColumn)] +/// pub enum Column { +/// Id, +/// Name, +/// VendorId, +/// } #[proc_macro_derive(DeriveCustomColumn)] pub fn derive_custom_column(input: TokenStream) -> TokenStream { let DeriveInput { ident, data, .. } = parse_macro_input!(input); @@ -66,6 +122,18 @@ pub fn derive_custom_column(input: TokenStream) -> TokenStream { } } +/// The DeriveModel derive macro will implement ModelTrait for Model, +/// which provides setters and getters for all attributes in the mod +/// It also implements FromQueryResult to convert a query result into the corresponding Model. +/// ### Usage +/// +/// ``` +/// #[derive(Clone, Debug, PartialEq, DeriveModel, DeriveActiveModel)] +/// pub struct Model { +/// pub id: i32, +/// pub name: String, +/// } +/// ``` #[proc_macro_derive(DeriveModel, attributes(sea_orm))] pub fn derive_model(input: TokenStream) -> TokenStream { let input = parse_macro_input!(input as DeriveInput); @@ -74,6 +142,19 @@ pub fn derive_model(input: TokenStream) -> TokenStream { .into() } +/// The DeriveActiveModel derive macro will implement ActiveModelTrait for ActiveModel +/// which provides setters and getters for all active values in the active model. +/// ### Usage +/// +/// ``` +/// +/// #[derive(Clone, Debug, PartialEq, DeriveModel, DeriveActiveModel)] +/// pub struct Model { +/// pub id: i32, +/// pub name: String, +/// } +/// +/// ``` #[proc_macro_derive(DeriveActiveModel, attributes(sea_orm))] pub fn derive_active_model(input: TokenStream) -> TokenStream { let DeriveInput { ident, data, .. } = parse_macro_input!(input); @@ -84,6 +165,7 @@ pub fn derive_active_model(input: TokenStream) -> TokenStream { } } +/// FIXME Derive into an active model #[proc_macro_derive(DeriveIntoActiveModel, attributes(sea_orm))] pub fn derive_into_active_model(input: TokenStream) -> TokenStream { let input = parse_macro_input!(input as DeriveInput); @@ -92,6 +174,18 @@ pub fn derive_into_active_model(input: TokenStream) -> TokenStream { .into() } +/// Models that a user can override +/// ### Usage +/// +/// ``` +/// use sea_orm::entity::prelude::*; +/// +/// #[derive(Clone, Debug, PartialEq, DeriveModel, DeriveActiveModel, DeriveActiveModelBehavior,)] +/// pub struct Model { +/// pub id: i32, +/// pub name: String, +/// } +/// ``` #[proc_macro_derive(DeriveActiveModelBehavior)] pub fn derive_active_model_behavior(input: TokenStream) -> TokenStream { let DeriveInput { ident, data, .. } = parse_macro_input!(input); @@ -102,6 +196,16 @@ pub fn derive_active_model_behavior(input: TokenStream) -> TokenStream { } } +/// Convert a query result into the corresponding Model. +/// ### Usage +/// +/// ``` +/// #[derive(Debug, FromQueryResult)] +/// struct SelectResult { +/// name: String, +/// num_of_fruits: i32, +/// } +/// ``` #[proc_macro_derive(FromQueryResult)] pub fn derive_from_query_result(input: TokenStream) -> TokenStream { let DeriveInput { ident, data, .. } = parse_macro_input!(input); @@ -112,6 +216,25 @@ pub fn derive_from_query_result(input: TokenStream) -> TokenStream { } } +/// The DeriveRelation derive macro will implement RelationTrait for Relation. +/// ### Usage +/// ``` +/// #[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)] +/// pub enum Relation { +/// #[sea_orm( +/// belongs_to = "super::cake::Entity", +/// from = "Column::CakeId", +/// to = "super::cake::Column::Id" +/// )] +/// Cake, +/// #[sea_orm( +/// belongs_to = "super::cake_expanded::Entity", +/// from = "Column::CakeId", +/// to = "super::cake_expanded::Column::Id" +/// )] +/// CakeExpanded, +/// } +/// ``` #[proc_macro_derive(DeriveRelation, attributes(sea_orm))] pub fn derive_relation(input: TokenStream) -> TokenStream { let input = parse_macro_input!(input as DeriveInput);