hcnet_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 Hcnet
10//! XDR.
11//!
12//! Types are generated from XDR definitions hosted at [hcnet/hcnet-xdr]
13//! using [xdrgen].
14//!
15//! [hcnet/hcnet-xdr]: https://github.com/hcnet/hcnet-xdr
16//! [xdrgen]: https://github.com/hcnet/xdrgen
17//!
18//! ## Usage
19//!
20//! ### Library
21//! To use the library, include in your toml:
22//!
23//! ```toml
24//! hcnet-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/hcnet/rs-hcnet-xdr/issues/39
48//! [#46]: https://github.com/hcnet/rs-hcnet-xdr/issues/46
49//! [#47]: https://github.com/hcnet/rs-hcnet-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. `arbitrary` – Enables support for interop with the arbitrary crate.
57//!
58//! Channels of XDR:
59//!
60//! - `curr` – XDR types built from the `hcnet/hcnet-xdr` `curr` branch.
61//! - `next` – XDR types built from the `hcnet/hcnet-xdr` `next` branch.
62//!
63//! If a single channel is enabled the types are available at the root of the
64//! crate. If multiple channels are enabled they are available in modules at
65//! the root of the crate.
66//!
67//! ### CLI
68//!
69//! To use the CLI:
70//!
71//! ```console
72//! cargo install --locked hcnet-xdr --version ... --features cli
73//! ```
74//!
75//! #### Examples
76//!
77//! Parse a `TransactionEnvelope`:
78//! ```console
79//! hcnet-xdr decode --type TransactionEnvelope << -
80//! AAAAA...
81//! -
82//! ```
83//!
84//! Parse a `ScSpecEntry` stream from a contract:
85//! ```console
86//! hcnet-xdr +next decode --type ScSpecEntry --input stream-base64 --output json-formatted << -
87//! AAAAA...
88//! -
89//! ```
90//!
91//! Parse a `BucketEntry` framed stream from a bucket file:
92//! ```console
93//! hcnet-xdr decode --type BucketEntry --input stream-framed --output json-formatted bucket.xdr
94//! ```
95
96#[derive(Clone, Debug, Eq, PartialEq, PartialOrd, Ord, Hash)]
97#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
98pub struct Version<'a> {
99    pub pkg: &'a str,
100    pub rev: &'a str,
101    pub xdr: &'a str,
102    pub xdr_curr: &'a str,
103    pub xdr_next: &'a str,
104}
105pub const VERSION: Version = Version {
106    pkg: env!("CARGO_PKG_VERSION"),
107    rev: env!("GIT_REVISION"),
108    xdr: if cfg!(all(feature = "curr", feature = "next")) {
109        "curr,next"
110    } else if cfg!(feature = "curr") {
111        "curr"
112    } else if cfg!(feature = "next") {
113        "next"
114    } else {
115        ""
116    },
117    xdr_curr: include_str!("../xdr/curr-version"),
118    xdr_next: include_str!("../xdr/next-version"),
119};
120
121#[cfg(feature = "curr")]
122pub mod curr;
123
124#[cfg(feature = "next")]
125pub mod next;
126
127#[cfg(feature = "cli")]
128pub mod cli;
hcnet_xdr/lib.rs

hcnet_xdr/
lib.rs
