fory/
lib.rs

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

fory/
lib.rs
