ion_binary_rs/lib.rs
1//! # Ion Binary parser/encoder & Ion Hash in Rust
2//!
3//! Ion binary is a production-ready library written in safe rust for parsing, encoding and hashing Amazon's Ion binary format.
4//!
5//! [](https://coveralls.io/github/Couragium/ion-binary-rs?branch=master)
6//! [](https://github.com/Couragium/ion-binary-rs/actions)
7//! [](https://docs.rs/ion-binary-rs)
8//! [](https://crates.io/crates/ion-binary-rs)
9//!
10//! It **parses**, **encodes** and **hashes** anything you throw at it. Any failure to do so
11//! is a bug that we will fix and we will be very happy if you report them.
12//!
13//! The code is mature and way more tested than Amazon's alternatives, including their js
14//! library. Amazon, when implementing the "good tests" only check that it parses. We check
15//! that the value is the correct one too. Additionally, we seem to be implementing way
16//! more of the ion protocol than Amazon's libraries, as we don't have huge skip lists in
17//! the tests files. We test all their test suite, not only a few test.
18//!
19//! ## How to use the library
20//!
21//! First of all, you need to be aware of the trade offs that we took for this library:
22//!
23//! - The API returns strings instead of Symbols. If needed we can add symbol, but we
24//! think string is the the most ergonomic way.
25//! - When parsing/decoding you can add shared tables for binary blobs that doesn't have
26//! all the required symbols.
27//!
28//! We have implemented the whole amazon ion test-suite for parsing.
29//! Encoding and Hashing fully tested. We are working in expading the coverage.
30//! We would appreciate any bug you can report. You can check all the test for examples.
31//!
32//! ## Example
33//!
34//! ### Parsing
35//!
36//! ```rust,no_run
37//!
38//! use ion_binary_rs::IonParser;
39//!
40//! // This is the response from Amazon's QLDB introduction example using Rusoto
41//! let ion_test = b"\xe0\x01\0\xea\xee\xa6\x81\x83\xde\xa2\x87\xbe\x9f\x83VIN\x84Type\x84Year\x84Make\x85Model\x85Color\xde\xb9\x8a\x8e\x911C4RJFAG0FC625797\x8b\x85Sedan\x8c\"\x07\xe3\x8d\x88Mercedes\x8e\x87CLK 350\x8f\x85White";
42//!
43//! let mut parser = IonParser::new(&ion_test[..]);
44//!
45//! println!("Decoded Ion: {:?}", parser.consume_all().unwrap())
46//! // Decoded Ion: [Struct({"Color": String("White"), "Year": Integer(2019), "VIN": String("1C4RJFAG0FC625797"), "Make": String("Mercedes"), "Model": String("CLK 350"), "Type": String("Sedan")})]
47//!
48//! ```
49//!
50//! ### Encoding
51//!
52//! ```rust,no_run
53//!
54//! use ion_binary_rs::{IonEncoder, IonParser, IonValue};
55//! use std::collections::HashMap;
56//!
57//! let mut ion_struct = HashMap::new();
58//!
59//! ion_struct.insert("Model".to_string(), IonValue::String("CLK 350".to_string()));
60//! ion_struct.insert("Type".to_string(), IonValue::String("Sedan".to_string()));
61//! ion_struct.insert("Color".to_string(), IonValue::String("White".to_string()));
62//! ion_struct.insert(
63//! "VIN".to_string(),
64//! IonValue::String("1C4RJFAG0FC625797".to_string()),
65//! );
66//! ion_struct.insert("Make".to_string(), IonValue::String("Mercedes".to_string()));
67//! ion_struct.insert("Year".to_string(), IonValue::Integer(2019));
68//!
69//! let ion_value = IonValue::Struct(ion_struct);
70//!
71//! let mut encoder = IonEncoder::new();
72//!
73//! encoder.add(ion_value.clone());
74//! let bytes = encoder.encode();
75//!
76//! let resulting_ion_value = IonParser::new(&bytes[..]).consume_value().unwrap().0;
77//!
78//! assert_eq!(ion_value, resulting_ion_value);
79//! ```
80//!
81//! ### Hashing
82//!
83//! ```rust,no_run
84//! use sha2::Sha256;
85//! use ion_binary_rs::{IonHash, IonValue};
86//! use std::collections::HashMap;
87//!
88//! let mut ion_struct = HashMap::new();
89//!
90//! ion_struct.insert("Model".to_string(), IonValue::String("CLK 350".to_string()));
91//! ion_struct.insert("Type".to_string(), IonValue::String("Sedan".to_string()));
92//! ion_struct.insert("Color".to_string(), IonValue::String("White".to_string()));
93//! ion_struct.insert(
94//! "VIN".to_string(),
95//! IonValue::String("1C4RJFAG0FC625797".to_string()),
96//! );
97//! ion_struct.insert("Make".to_string(), IonValue::String("Mercedes".to_string()));
98//! ion_struct.insert("Year".to_string(), IonValue::Integer(2019));
99//!
100//! let ion_value = IonValue::Struct(ion_struct);
101//!
102//! let hash = IonHash::digest::<Sha256>(&ion_value);
103//!
104//! println!("{:X?}", hash);
105//! ```
106//!
107//! ## Safety
108//!
109//! In order to speed up the encoding of data, we use Uninit vector buffers, as otherwise
110//! it would require for the buffer to be set to zeroes and then to the correct values.
111//!
112//! ## Contributing
113//!
114//! We would be thrilled if you decide to check the library and/or contribute to it!
115//! Just open an issue or pull request and we can check what you would like to implement.
116//! Bug hunting and proposals are always welcomed. And of course, feel free to ask anything.
117//!
118//! ## License
119//!
120//! <sup>
121//! Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
122//! 2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
123//! </sup>
124//!
125//! <br/>
126//!
127//! <sub>
128//! Unless you explicitly state otherwise, any contribution intentionally submitted
129//! for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
130//! be dual licensed as above, without any additional terms or conditions.
131//! </sub>
132//!
133
134pub(crate) mod binary_encoder;
135pub(crate) mod binary_parser;
136pub(crate) mod binary_parser_types;
137pub(crate) mod ion_encoder;
138pub(crate) mod ion_hash;
139pub(crate) mod ion_hash_encoder;
140pub(crate) mod ion_parser;
141pub(crate) mod ion_parser_types;
142pub(crate) mod ion_value_impl;
143pub(crate) mod symbol_table;
144
145#[cfg(test)]
146mod tests;
147
148pub use binary_parser_types::ParsingError;
149pub use ion_encoder::IonEncoder;
150pub use ion_hash::IonHash;
151pub use ion_parser::IonParser;
152pub use ion_parser_types::{
153 IonExtractionError, IonParserError, IonValue, NullIonValue, SerdeJsonParseError,
154};
155pub use symbol_table::{Symbol, SymbolContextError};