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
//! Decodes a bencoded struct
//!
//! # Basic decoding
//! For any decoding process, first we need to create a decoder:
//!
//! ```
//! # use bendy::decoding::{Decoder};
//! #
//! # let buf: &[u8] = b"d3:fooi1ee";
//! let _decoder = Decoder::new(buf);
//! ```
//!
//! Decoders have a depth limit to prevent resource exhaustion from hostile inputs. By default, it's
//! set high enough for most structures that you'd encounter when prototyping, but for production
//! use, not only may it not be enough, but the higher the depth limit, the more stack space an
//! attacker can cause your program to use, so we recommend setting the bounds tightly:
//!
//! ```
//! # use bendy::decoding::{Decoder};
//! #
//! # let buf: &[u8] = b"d3:fooi1ee";
//! let _decoder = Decoder::new(buf).with_max_depth(3);
//! ```
//!
//! Atoms (integers and strings) have depth zero, and lists and dicts have a depth equal to the
//! depth of their deepest member plus one. As an special case, an empty list or dict has depth 1.
//!
//! Now, you can start reading objects:
//!
//! ```
//! # use bendy::decoding::{Decoder,Object};
//! #
//! # fn decode_list(_: bendy::decoding::ListDecoder) {}
//! # fn decode_dict(_: bendy::decoding::DictDecoder) {}
//! #
//! # let buf: &[u8] = b"d3:fooi1ee";
//! # let mut decoder = Decoder::new(buf);
//! #
//! match decoder.next_object().unwrap() {
//! None => (), // EOF
//! Some(Object::List(d)) => decode_list(d),
//! Some(Object::Dict(d)) => decode_dict(d),
//! Some(Object::Integer(_)) => (), // integer, as a string
//! Some(Object::Bytes(_)) => (), // A raw bytestring
//! };
//! ```
//!
//! # Error handling
//!
//! Once an error is encountered, the decoder won't try to muddle through it; instead, every future
//! call to the decoder will return the same error. This behaviour can be used to check the syntax
//! of an input object without fully decoding it:
//!
//! ```
//! # use bendy::decoding::Decoder;
//! #
//! fn syntax_check(buf: &[u8]) -> bool {
//! let mut decoder = Decoder::new(buf);
//! decoder.next_object().ok(); // ignore the return value of this
//! return decoder.next_object().is_ok();
//! }
//! #
//! # assert!(syntax_check(b"i18e"));
//! ```
pub use ;