bt_bencode/
lib.rs

1//! # BtBencode
2//!
3//! `BtBencode` is a library which can help with [Bencode][wikipedia_bencode]
4//! encoding/decoding.  Bencode is primarily used in [BitTorrent][bep_0003] related
5//! applications.
6//!
7//! It uses the [Serde][serde] library to serialize and deserialize Bencode data.
8//! It is similar to [Serde JSON][serde_json] in terms of functionality and
9//! implementation.
10//!
11//! ## Documentation
12//!
13//! * [Latest API Docs][docs_rs_bt_bencode]
14//!
15//! ## Examples
16//!
17//! An example serializing a standard Rust collection type and then deserializing
18//! into a custom type:
19//!
20//! ```rust
21//! use std::collections::BTreeMap;
22//! use serde_derive::Deserialize;
23//!
24//! let mut dict: BTreeMap<String, String> = BTreeMap::new();
25//! dict.insert(String::from("url"), String::from("https://example.com/"));
26//!
27//! let serialized_bytes = bt_bencode::to_vec(&dict)?;
28//!
29//! #[derive(Deserialize)]
30//! struct Info<'a> {
31//!     url: &'a str,
32//! }
33//!
34//! let info: Info = bt_bencode::from_slice(&serialized_bytes)?;
35//! assert_eq!(info.url, "https://example.com/");
36//! # Ok::<(), bt_bencode::Error>(())
37//! ```
38//!
39//! An example deserializing from a slice of bytes into a general `Value`
40//! representation and then from the `Value` instance into a more strongly typed
41//! data structure.
42//!
43//! ```rust
44//! use serde_derive::{Serialize, Deserialize};
45//!
46//! use bt_bencode::Value;
47//!
48//! #[derive(Serialize, Deserialize)]
49//! struct Info {
50//!     t: String,
51//!     url: String,
52//! }
53//!
54//! let serialized_bytes = bt_bencode::to_vec(&Info {
55//!     t: String::from("query"),
56//!     url: String::from("https://example.com/"),
57//! })?;
58//!
59//! let value: Value = bt_bencode::from_slice(&serialized_bytes)?;
60//! assert_eq!(value["t"].as_str().unwrap(), "query");
61//! assert_eq!(
62//!     value.get("url").and_then(|url| url.as_str()).unwrap(),
63//!     "https://example.com/"
64//! );
65//!
66//! let info: Info = bt_bencode::from_value(value)?;
67//! assert_eq!(info.t, "query");
68//! assert_eq!(info.url, "https://example.com/");
69//! # Ok::<(), bt_bencode::Error>(())
70//! ```
71//!
72//! ## License
73//!
74//! Licensed under either of [Apache License, Version 2.0][LICENSE_APACHE] or [MIT
75//! License][LICENSE_MIT] at your option.
76//!
77//! ### Contributions
78//!
79//! Unless you explicitly state otherwise, any contribution intentionally submitted
80//! for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
81//! dual licensed as above, without any additional terms or conditions.
82//!
83//! [LICENSE_APACHE]: LICENSE-APACHE
84//! [LICENSE_MIT]: LICENSE-MIT
85//! [wikipedia_bencode]: https://en.wikipedia.org/wiki/Bencode
86//! [bep_0003]: http://www.bittorrent.org/beps/bep_0003.html
87//! [serde]: https://serde.rs
88//! [serde_json]: https://github.com/serde-rs/json
89//! [docs_rs_bt_bencode]: https://docs.rs/bt_bencode/latest/bt_bencode/
90
91#![cfg_attr(not(feature = "std"), no_std)]
92#![cfg_attr(docsrs, feature(doc_cfg))]
93#![warn(
94    missing_copy_implementations,
95    missing_debug_implementations,
96    missing_docs,
97    rust_2018_idioms,
98    unused_lifetimes,
99    unused_qualifications
100)]
101
102#[cfg(all(feature = "alloc", not(feature = "std")))]
103extern crate alloc;
104
105#[macro_use]
106extern crate serde;
107
108mod bstring;
109mod de;
110mod error;
111
112pub mod read;
113pub mod write;
114
115mod ser;
116pub mod value;
117
118#[doc(inline)]
119pub use bstring::ByteString;
120#[doc(inline)]
121pub use de::{from_slice, Deserializer};
122#[doc(inline)]
123pub use error::{Error, ErrorKind, Result};
124#[doc(inline)]
125pub use value::{from_value, to_value, Value};
126
127#[doc(inline)]
128#[cfg(feature = "std")]
129pub use ser::to_writer;
130
131#[doc(inline)]
132pub use ser::{to_vec, Serializer};
133
134#[doc(inline)]
135#[cfg(feature = "std")]
136pub use de::from_reader;
bt_bencode/lib.rs

bt_bencode/
lib.rs
