esexpr 0.2.5

ESExpr serialization format and related utilities.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

mod boxed;
mod btreemap;
#[cfg(feature = "std")]
mod hashmap;
mod option;
mod scalar;
mod vec;

use alloc::collections::{BTreeMap, VecDeque};
use alloc::vec::Vec;

use crate::cowstr::CowStr;
use crate::{DecodeError, ESExpr, ESExprTagSet};

/// Equality for the encoded ESExpr representation.
pub trait ESExprEncodedEq {
	/// Determines whether two values are equal when encoded as `ESExpr`.
	fn is_encoded_eq(&self, other: &Self) -> bool;
}

/// A codec that encodes and decodes `ESExpr` values.
pub trait ESExprCodec<'a>: ESExprEncodedEq + Sized + 'a {
	/// The tags of the encoded expressions that this type can produce.
	const TAGS: ESExprTagSet;

	/// Encode this value into an expression.
	fn encode_esexpr(&'a self) -> ESExpr<'a>;

	/// Decode an expression into a value.
	///
	/// # Errors
	/// Will return `Err` if decoding fails.
	fn decode_esexpr(expr: ESExpr<'a>) -> Result<Self, DecodeError>;
}

/// A field codec for optional fields.
pub trait ESExprOptionalFieldCodec<'a>: ESExprEncodedEq + Sized + 'a {
	/// The element type.
	type Element: ESExprCodec<'a> + 'a;

	/// Encode an optional field or None when the value should be excluded.
	fn encode_optional_field(&'a self) -> Option<ESExpr<'a>>;

	/// Decode an optional field value.
	///
	/// # Errors
	/// Will return `Err` if decoding fails.
	fn decode_optional_field(value: Option<ESExpr<'a>>) -> Result<Self, DecodeError>;
}

/// A field codec for variable arguments.
pub trait ESExprVarArgCodec<'a>: ESExprEncodedEq + Sized + 'a {
	/// The element type.
	type Element: ESExprCodec<'a> + 'a;

	/// Encode variable arguments
	fn encode_vararg_element(&'a self, args: &mut Vec<ESExpr<'a>>);

	/// Decode variable arguments.
	///
	/// # Errors
	/// Will return `Err` if decoding fails.
	fn decode_vararg_element(
		args: &mut VecDeque<ESExpr<'a>>,
		constructor_name: &str,
		start_index: &mut usize,
	) -> Result<Self, DecodeError>;
}

/// A field codec for dictionary arguments.
pub trait ESExprDictCodec<'a>
where
	Self: Sized + 'a,
{
	/// The element type.
	type Element: ESExprCodec<'a> + 'a;

	/// Encode dictionary arguments.
	fn encode_dict_element(&'a self, kwargs: &mut BTreeMap<CowStr<'a>, ESExpr<'a>>);

	/// Decode dictionary arguments.
	///
	/// # Errors
	/// Will return `Err` if decoding fails.
	fn decode_dict_element(
		kwargs: &mut BTreeMap<CowStr<'a>, ESExpr<'a>>,
		constructor_name: &str,
	) -> Result<Self, DecodeError>;
}