stellar_xdr/
lib.rs

1#![forbid(unsafe_code)]
2#![cfg_attr(not(feature = "std"), no_std)]
3#![cfg_attr(docs, feature(doc_cfg))]
4// TODO: Remove these clippy doc comment allows after improving the
5// auto-generated docs.
6#![allow(clippy::tabs_in_doc_comments)]
7#![allow(clippy::doc_markdown)]
8#![allow(clippy::doc_lazy_continuation)]
9#![allow(unused_attributes)]
10
11//! Library and CLI containing types and functionality for working with Stellar
12//! XDR.
13//!
14//! Types are generated from XDR definitions hosted at [stellar/stellar-xdr]
15//! using the Rust XDR generator in `xdr-generator-rust/`.
16//!
17//! [stellar/stellar-xdr]: https://github.com/stellar/stellar-xdr
18//!
19//! ## Usage
20//!
21//! ### Library
22//! To use the library, include in your toml:
23//!
24//! ```toml
25//! stellar-xdr = { version = "...", default-features = true, features = [] }
26//! ```
27//!
28//! #### Features
29//!
30//! The crate has several features, tiers of functionality, ancillary
31//! functionality, and channels of XDR.
32//!
33//! Default features: `std`, `curr`.
34//!
35//! Tiers of functionality:
36//!
37//! 1. `std` – The std feature provides all functionality (types, encode,
38//! decode), and is the default feature set.
39//! 2. `alloc` – The alloc feature uses `Box` and `Vec` types for recursive
40//! references and arrays, and is automatically enabled if the std feature is
41//! enabled. The default global allocator is used. Support for a custom
42//! allocator will be added in [#39]. No encode or decode capability exists,
43//! only types. Encode and decode capability will be added in [#46].
44//! 3. If std or alloc are not enabled recursive and array types requires static
45//! lifetime values. No encode or decode capability exists. Encode and decode
46//! capability will be added in [#47].
47//!
48//! [#39]: https://github.com/stellar/rs-stellar-xdr/issues/39
49//! [#46]: https://github.com/stellar/rs-stellar-xdr/issues/46
50//! [#47]: https://github.com/stellar/rs-stellar-xdr/issues/47
51//!
52//! Ancillary functionality:
53//!
54//! 1. `base64` – Enables support for base64 encoding and decoding.
55//! 2. `serde` – Enables support for serializing and deserializing types with
56//! the serde crate.
57//! 3. `serde_json` – Enables support for built-in functionality specifically
58//! for serde_json. Often not required to use the types with serde_json, and
59//! only necessary to use utility functions that depend on serde_json.
60//! 4. `arbitrary` – Enables support for interop with the arbitrary crate.
61//! 5. `hex` – Enables support for hex in string representations of some types.
62//! Automatically enabled when serde is enabled.
63//! 6. `schemars` – Enables support for JSON Schema generation. (Experimental)
64//!
65//! Features marked experimental may disappear at anytime, see breaking changes
66//! at anytime, or and may be minimal implementations instead of complete.
67//!
68//! Channels of XDR:
69//!
70//! - `curr` – XDR types built from the `stellar/stellar-xdr` `curr` branch.
71//! - `next` – XDR types built from the `stellar/stellar-xdr` `next` branch.
72//!
73//! If a single channel is enabled the types are available at the root of the
74//! crate. If multiple channels are enabled they are available in modules at
75//! the root of the crate.
76//!
77//! ### CLI
78//!
79//! To use the CLI:
80//!
81//! ```console
82//! cargo install --locked stellar-xdr --version ... --features cli
83//! ```
84//!
85//! #### Examples
86//!
87//! Parse a `TransactionEnvelope`:
88//! ```console
89//! stellar-xdr decode --type TransactionEnvelope << -
90//! AAAAA...
91//! -
92//! ```
93//!
94//! Parse a `ScSpecEntry` stream from a contract:
95//! ```console
96//! stellar-xdr +next decode --type ScSpecEntry --input stream-base64 --output json-formatted << -
97//! AAAAA...
98//! -
99//! ```
100//!
101//! Parse a `BucketEntry` framed stream from a bucket file:
102//! ```console
103//! stellar-xdr decode --type BucketEntry --input stream-framed --output json-formatted bucket.xdr
104//! ```
105
106#[derive(Clone, Debug, Eq, PartialEq, PartialOrd, Ord, Hash)]
107#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
108pub struct Version<'a> {
109    pub pkg: &'a str,
110    pub rev: &'a str,
111    pub xdr: &'a str,
112    pub xdr_curr: &'a str,
113    pub xdr_next: &'a str,
114}
115pub const VERSION: Version = Version {
116    pkg: env!("CARGO_PKG_VERSION"),
117    rev: env!("GIT_REVISION"),
118    xdr: if cfg!(all(feature = "curr", feature = "next")) {
119        "curr,next"
120    } else if cfg!(feature = "curr") {
121        "curr"
122    } else if cfg!(feature = "next") {
123        "next"
124    } else {
125        ""
126    },
127    xdr_curr: include_str!("../xdr/curr-version"),
128    xdr_next: include_str!("../xdr/next-version"),
129};
130
131#[cfg(feature = "schemars")]
132pub mod schemars;
133
134#[cfg(feature = "curr")]
135pub mod curr;
136
137#[cfg(feature = "next")]
138pub mod next;
139
140#[cfg(feature = "cli")]
141pub mod cli;
142
143#[cfg(all(any(feature = "curr", feature = "next"), feature = "alloc"))]
144pub(crate) mod num256;
145
146#[cfg(all(any(feature = "curr", feature = "next"), feature = "alloc"))]
147pub(crate) mod num128;
stellar_xdr/lib.rs

stellar_xdr/
lib.rs
