1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the License for the
// specific language governing permissions and limitations
// under the License.
//! Apache Fory's public Rust facade.
//!
//! Derive macros create serializers for local types:
//!
//! ```rust,ignore
//! use fory::{Fory, ForyStruct};
//!
//! #[derive(ForyStruct)]
//! struct User {
//! name: String,
//! age: u32,
//! }
//!
//! let mut fory = Fory::builder().xlang(false).build();
//! fory.register::<User>(100)?;
//! let bytes = fory.serialize(&User {
//! name: "Ada".to_owned(),
//! age: 37,
//! })?;
//! let user: User = fory.deserialize(&bytes)?;
//! # Ok::<(), fory::Error>(())
//! ```
//!
//! A local serializer can target a type owned by another crate. External structural
//! serializers use `#[fory(target = path::Type)]`; opaque or invariant-bearing targets use a
//! manual [`Serializer`]. The serializer is selected explicitly at a field with
//! `#[fory(with = UserSerializer)]` or at a root with the `*_with` API family:
//!
//! ```rust,ignore
//! let bytes = fory.serialize_with::<UserSerializer>(&external_user)?;
//! let user = fory.deserialize_with::<UserSerializer>(&bytes)?;
//!
//! let mut buffer = Vec::new();
//! fory.serialize_to_with::<UserSerializer>(&mut buffer, &external_user)?;
//! let mut reader = fory::Reader::new(&buffer);
//! let user = fory.deserialize_from_with::<UserSerializer>(&mut reader)?;
//! ```
//!
//! Fory-owned carrier serializers compose an external child at a root without changing the
//! carrier's standard wire representation:
//!
//! ```rust,ignore
//! use fory::{HashMapSerializer, VecSerializer};
//!
//! type Users = VecSerializer<UserSerializer>;
//! type Directory = HashMapSerializer<String, Users>;
//! let bytes = fory.serialize_with::<Directory>(&directory)?;
//! let decoded = fory.deserialize_with::<Directory>(&bytes)?;
//! ```
//!
//! Application traits extend [`ForyObject`], not [`Serializer`]. The concrete target list is
//! closed by [`register_trait_type!`], while each target's registered serializer determines its
//! serialization:
//!
//! ```rust,ignore
//! use fory::{register_trait_type, ForyObject};
//!
//! trait Animal: ForyObject {
//! fn name(&self) -> &str;
//! }
//!
//! register_trait_type!(Animal, Dog, third_party::Cat);
//! ```
//!
//! Use `register_trait_type!(sync Trait, Targets...)` for traits and targets that are
//! `Send + Sync`. The generated `TraitRcSerializer` and `TraitArcSerializer` types support
//! explicit `Rc<dyn Trait>` and `Arc<dyn Trait>` roots without wrapper values.
// Derive macros resolve the facade through `::fory::__private`, including doctests where
// `crate` is the doctest crate instead of this facade crate.
extern crate self as fory;
pub use ;
pub use ;