babbel_bencode 0.1.1

Fast, binary-safe BitTorrent Bencode parser, serializer, and DOM in pure Rust
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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

//! A Rust library for encoding and decoding data in the Bencode format, commonly used in BitTorrent files.
//! This library provides functionality to parse, create, modify and serialize bencode data structures
//! with support for various formats including JSON, YAML and XML conversion.
//!
//! # Features
//!
//! - `std` (default): Enable standard library support
//! - Without `std`: Core bencode functionality works in `no_std` environments

#![cfg_attr(not(feature = "std"), no_std)]

#[cfg(not(feature = "std"))]
extern crate alloc;

#[cfg(not(feature = "std"))]
pub(crate) use alloc::collections::BTreeMap as HashMap;

#[cfg(feature = "std")]
pub(crate) use std::collections::HashMap;

/// Centralized bencode protocol character and byte constants
pub(crate) mod constants;
/// Module defining custom error types and error handling functionality
pub mod error;
/// Module providing input/output operations for reading and writing bencode data
pub mod io;
/// Module containing utility functions and helper methods
pub mod misc;

/// Module containing configuration options for parsing and encoding
pub mod config;
/// Module providing memory management utilities for embedded systems
pub mod memory;
/// Module defining the core data structures for representing bencode nodes
pub mod nodes;
/// Module containing the parsing logic to decode bencode format into data structures
pub mod parser;
/// Module implementing serialization of data structures back to bencode format
pub mod stringify;

/// Integration tests module
mod integration_tests;

///
/// babbel_bencode API
///

/// Returns the current version of the bencode library
pub use misc::get_version as version;

/// Reads and parses a bencode-encoded file from disc (requires `std` feature)
#[cfg(feature = "std")]
pub use misc::read_bencode_file as read_file;

/// Writes bencode-encoded data to a file on disk (requires `std` feature)
#[cfg(feature = "std")]
pub use misc::write_bencode_file as write_file;

/// Destination implementation for writing bencode data to a memory buffer
pub use io::destinations::buffer::Buffer as BufferDestination;

/// Destination implementation for writing bencode data to a file (requires `std` feature)
#[cfg(feature = "std")]
pub use io::destinations::file::File as FileDestination;

/// Source implementation for reading bencode data from a memory buffer
pub use io::sources::buffer::Buffer as BufferSource;

/// Source implementation for reading bencode data from a file (requires `std` feature)
#[cfg(feature = "std")]
pub use io::sources::file::File as FileSource;

/// Core data structure representing a bencode node in the parsed tree
pub use nodes::node::Node;
pub use nodes::node::make_node;

/// Zero-copy borrowed node for embedded systems (no allocation)
pub use nodes::borrowed::BorrowedNode;

/// Type alias for fixed-size stack buffers with const generics
pub use nodes::fixed::FixedSizeBuffer;
/// Memory bounds calculator using const generics
pub use nodes::fixed::MemoryBounds;

/// Parses bencode data into a Node tree structure
pub use parser::default::parse;
/// Parses bencode data from a byte slice into a Node tree structure
pub use parser::default::parse_bytes;
/// Parses bencode data from a string into a Node tree structure
pub use parser::default::parse_str;

/// Parses bencode data from a string slice. Canonical alias for [`parse_str`].
pub use parser::default::parse_str as from_str;
/// Parses bencode data from a byte slice. Canonical alias for [`parse_bytes`].
pub use parser::default::parse_bytes as from_bytes;
/// Parses bencode data from any streaming source. Canonical alias for [`parse`].
pub use parser::default::parse as from_source;

/// Zero-copy parser that returns borrowed nodes (no allocation)
pub use parser::borrowed::parse_borrowed;
/// Validates bencode data without building a node tree (minimal allocation)
pub use parser::borrowed::validate_bencode;

/// Parses bencode data from a byte slice using iterative parser
pub use parser::iterative::parse_bytes_iterative;
/// Iterative parser that avoids recursion (for deeply nested structures)
pub use parser::iterative::parse_iterative;
/// Parses bencode data from a string using iterative parser
pub use parser::iterative::parse_str_iterative;

/// Arena allocator for bump allocation from fixed buffers
pub use memory::Arena;
/// Memory usage tracker for embedded systems
pub use memory::MemoryTracker;
/// Stack-based fixed-size buffer
pub use memory::StackBuffer;

/// Lightweight error type for embedded systems (no heap allocation)
pub use error::embedded::BencodeError;

/// Encoder configuration options
pub use config::EncoderConfig;
/// Parser configuration options
pub use config::ParserConfig;

/// Converts a Node tree back to bencode format
pub use stringify::default::stringify;
/// Converts a Node tree to bencode format as bytes
pub use stringify::default::stringify_to_bytes;
/// Converts a Node tree to bencode format as a String
pub use stringify::default::stringify_to_string;

/// Converts a Node tree to bencode format as a String. Canonical alias for [`stringify_to_string`].
pub use stringify::default::stringify_to_string as to_string;
/// Converts a Node tree to bencode format as bytes. Canonical alias for [`stringify_to_bytes`].
pub use stringify::default::stringify_to_bytes as to_vec;

/// Core SOLID I/O abstractions
pub use io::traits::{BencodeRead, BencodeWrite, BufferedWrite, RewindableRead};

/// Schema validation and typed dictionary query extension trait
pub use nodes::query::NodeQueryExt;

/// Visitor pattern traits for format serialization
pub use stringify::visitor::{BencodeVisitable, BencodeVisitor};

/// Converts a Node tree to JSON format (requires "json" feature)
#[cfg(feature = "json")]
pub use stringify::json::stringify as to_json;

/// Converts a Node tree to TOML format (requires "toml" feature)
#[cfg(feature = "toml")]
pub use stringify::toml::stringify as to_toml;

/// Converts a Node tree to XML format (requires "xml" feature)
#[cfg(feature = "xml")]
pub use stringify::xml::stringify as to_xml;

/// Converts a Node tree to YAML format (requires "yaml" feature)
#[cfg(feature = "yaml")]
pub use stringify::yaml::stringify as to_yaml;