Skip to content

Commit

Permalink
Fix doc tests
Browse files Browse the repository at this point in the history
  • Loading branch information
@jbearer
jbearer committed Mar 15, 2024
1 parent 3d8fa72 commit c0d1765
Show file tree
Hide file tree
Showing 4 changed files with 86 additions and 77 deletions.
12 changes: 12 additions & 0 deletions Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,15 @@ members = [
"tagged-base64",
"tagged-base64-macros",
]

[workspace.dependencies]
ark-bls12-381 = "0.4"
ark-serialize = { version = "0.4", default-features = false }
ark-std = { version = "0.4", default-features = false }
rand_chacha = "0.3"
serde = "1.0"

[profile.release]
# Tell `rustc` to optimize for small code size.
opt-level = "s"
debug = true
69 changes: 0 additions & 69 deletions tagged-base64-macros/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,75 +7,6 @@ use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, AttributeArgs, Item, Meta, NestedMeta};

/// Derive serdes for a type which serializes as a binary blob.
///
/// This macro can be used to easily derive friendly serde implementations for a binary type which
/// implements [CanonicalSerialize](ark_serialize::CanonicalSerialize) and
/// [CanonicalDeserialize](ark_serialize::CanonicalDeserialize). This is useful for cryptographic
/// primitives and other types which do not have a human-readable serialization, but which may be
/// embedded in structs with a human-readable serialization. The serde implementations derived by
/// this macro will serialize the type as bytes for binary encodings and as base 64 for human
/// readable encodings.
///
/// This macro takes at least one arguments:
/// * The first argument should be the tag, as a string literal or expression.
/// * By default, the derived implementation invokes `CanonicalSerialize` and `CanonicalDeserialize`
/// with `uncompressed` and `unchecked` flags.
/// * If `compressed` and/or `checked` flags are presented, the derived implementation will behave
/// accordingly.
///
/// Specifically, this macro does 4 things when applied to a type definition:
/// * It adds `#[derive(Serialize, Deserialize)]` to the type definition, along with serde
/// attributes to serialize using [TaggedBase64].
/// * It creates an implementation of [Tagged] for the type using the specified tag. This tag will
/// be used to identify base 64 strings which represent this type in human-readable encodings.
/// * It creates an implementation of `TryFrom<TaggedBase64>` for the type `T`, which is needed to
/// make the `serde(try_from)` attribute work.
/// * It creates implementations of [Display](ark_std::fmt::Display) and
/// [FromStr](ark_std::str::FromStr) using tagged base 64 as a display format. This allows tagged
/// blob types to be conveniently displayed and read to and from user interfaces in a manner
/// consistent with how they are serialized.
///
/// Usage example:
///
/// ```
/// #[macro_use] extern crate tagged_base64_macros;
/// use ark_serialize::*;
///
/// #[tagged("PRIM")]
/// #[derive(Clone, CanonicalSerialize, CanonicalDeserialize, /* any other derives */)]
/// pub struct CryptoPrim(
/// // This type can only be serialied as an opaque, binary blob using ark_serialize.
/// pub(crate) ark_bls12_381::Fr,
/// );
/// ```
///
/// The type `CryptoPrim` can now be serialized as binary:
/// ```
/// # use ark_serialize::*;
/// # use ark_std::UniformRand;
/// # use tagged_base64_macros::tagged;
/// # use rand_chacha::{ChaChaRng, rand_core::SeedableRng};
/// # #[tagged("PRIM", compressed)]
/// # #[derive(Clone, CanonicalSerialize, CanonicalDeserialize, /* any other derives */)]
/// # struct CryptoPrim(ark_bls12_381::Fr);
/// # let crypto_prim = CryptoPrim(ark_bls12_381::Fr::rand(&mut ChaChaRng::from_seed([42; 32])));
/// bincode::serialize(&crypto_prim).unwrap();
/// ```
/// or as base64:
/// ```
/// # use ark_serialize::*;
/// # use ark_std::UniformRand;
/// # use tagged_base64_macros::tagged;
/// # use rand_chacha::{ChaChaRng, rand_core::SeedableRng};
/// # #[tagged("PRIM", compressed, checked)]
/// # #[derive(Clone, CanonicalSerialize, CanonicalDeserialize, /* any other derives */)]
/// # struct CryptoPrim(ark_bls12_381::Fr);
/// # let crypto_prim = CryptoPrim(ark_bls12_381::Fr::rand(&mut ChaChaRng::from_seed([42; 32])));
/// serde_json::to_string(&crypto_prim).unwrap();
/// ```
/// which will produce a tagged base64 string like
/// "PRIM~8oaujwbov8h4eEq7HFpqW6mIXhVbtJGxLUgiKrGpMCoJ".
#[proc_macro_attribute]
pub fn tagged(args: TokenStream, input: TokenStream) -> TokenStream {
let args = parse_macro_input!(args as AttributeArgs);
Expand Down
13 changes: 5 additions & 8 deletions tagged-base64/Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,11 @@ wasm-debug = ["dep:console_error_panic_hook"]
build-cli = ["dep:clap"]

[dependencies]
ark-serialize = { version = "0.4.0", optional = true, default-features = false, features = ["derive"] }
ark-std = { version = "0.4.0", default-features = false }
ark-serialize = { workspace = true, optional = true, features = ["derive"] }
ark-std = { workspace = true }
base64 = "0.21"
crc-any = { version = "2.4.1", default-features = false }
serde = { version = "1.0", optional = true, features = ["derive"] }
serde = { workspace = true, optional = true, features = ["derive"] }
snafu = { version = "0.7", features = ["backtraces"] }
tagged-base64-macros = { version = "0.4.0", path = "../tagged-base64-macros", default-features = false }

Expand All @@ -46,18 +46,15 @@ web-sys = { version = "0.3.49", optional = true, features = ["console", "Headers
console_error_panic_hook = { version = "0.1.7", optional = true }

[dev-dependencies]
ark-bls12-381 = { workspace = true }
bincode = "1.3"
getrandom = { version = "0.2", features = ["js"] }
quickcheck = "1.0"
quickcheck_macros = "1.0"
rand_chacha = "0.3"
serde_json = "1.0"
wasm-bindgen-test = { version = "0.3.28" }

[profile.release]
# Tell `rustc` to optimize for small code size.
opt-level = "s"
debug = true

# https://github.com/rustwasm/wasm-bindgen/issues/2279
[package.metadata.wasm-pack.profile.release]
wasm-opt = ["-Os", "--enable-mutable-globals"]
69 changes: 69 additions & 0 deletions tagged-base64/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,75 @@ use ark_std::{
#[cfg(all(target_arch = "wasm32", feature = "wasm-bindgen"))]
use wasm_bindgen::prelude::*;

/// Derive serdes for a type which serializes as a binary blob.
///
/// This macro can be used to easily derive friendly serde implementations for a binary type which
/// implements [CanonicalSerialize](ark_serialize::CanonicalSerialize) and
/// [CanonicalDeserialize](ark_serialize::CanonicalDeserialize). This is useful for cryptographic
/// primitives and other types which do not have a human-readable serialization, but which may be
/// embedded in structs with a human-readable serialization. The serde implementations derived by
/// this macro will serialize the type as bytes for binary encodings and as base 64 for human
/// readable encodings.
///
/// This macro takes at least one arguments:
/// * The first argument should be the tag, as a string literal or expression.
/// * By default, the derived implementation invokes `CanonicalSerialize` and `CanonicalDeserialize`
/// with `uncompressed` and `unchecked` flags.
/// * If `compressed` and/or `checked` flags are presented, the derived implementation will behave
/// accordingly.
///
/// Specifically, this macro does 4 things when applied to a type definition:
/// * It adds `#[derive(Serialize, Deserialize)]` to the type definition, along with serde
/// attributes to serialize using [TaggedBase64].
/// * It creates an implementation of [Tagged] for the type using the specified tag. This tag will
/// be used to identify base 64 strings which represent this type in human-readable encodings.
/// * It creates an implementation of `TryFrom<TaggedBase64>` for the type `T`, which is needed to
/// make the `serde(try_from)` attribute work.
/// * It creates implementations of [Display](ark_std::fmt::Display) and
/// [FromStr](ark_std::str::FromStr) using tagged base 64 as a display format. This allows tagged
/// blob types to be conveniently displayed and read to and from user interfaces in a manner
/// consistent with how they are serialized.
///
/// Usage example:
///
/// ```
/// use ark_serialize::*;
/// use tagged_base64_macros::tagged;
///
/// #[tagged("PRIM")]
/// #[derive(Clone, CanonicalSerialize, CanonicalDeserialize, /* any other derives */)]
/// pub struct CryptoPrim(
/// // This type can only be serialied as an opaque, binary blob using ark_serialize.
/// pub(crate) ark_bls12_381::Fr,
/// );
/// ```
///
/// The type `CryptoPrim` can now be serialized as binary:
/// ```
/// # use ark_serialize::*;
/// # use ark_std::UniformRand;
/// # use tagged_base64_macros::tagged;
/// # use rand_chacha::{ChaChaRng, rand_core::SeedableRng};
/// # #[tagged("PRIM", compressed)]
/// # #[derive(Clone, CanonicalSerialize, CanonicalDeserialize, /* any other derives */)]
/// # struct CryptoPrim(ark_bls12_381::Fr);
/// # let crypto_prim = CryptoPrim(ark_bls12_381::Fr::rand(&mut ChaChaRng::from_seed([42; 32])));
/// bincode::serialize(&crypto_prim).unwrap();
/// ```
/// or as base64:
/// ```
/// # use ark_serialize::*;
/// # use ark_std::UniformRand;
/// # use tagged_base64_macros::tagged;
/// # use rand_chacha::{ChaChaRng, rand_core::SeedableRng};
/// # #[tagged("PRIM", compressed, checked)]
/// # #[derive(Clone, CanonicalSerialize, CanonicalDeserialize, /* any other derives */)]
/// # struct CryptoPrim(ark_bls12_381::Fr);
/// # let crypto_prim = CryptoPrim(ark_bls12_381::Fr::rand(&mut ChaChaRng::from_seed([42; 32])));
/// serde_json::to_string(&crypto_prim).unwrap();
/// ```
/// which will produce a tagged base64 string like
/// "PRIM~8oaujwbov8h4eEq7HFpqW6mIXhVbtJGxLUgiKrGpMCoJ".
pub use tagged_base64_macros::tagged;

/// Separator that does not appear in URL-safe base64 encoding and can
Expand Down

0 comments on commit c0d1765

Please sign in to comment.