stellar_xdr/
lib.rs

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

stellar_xdr/
lib.rs
