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

stellar_xdr/
lib.rs
