babbel_bencode/lib.rs
1//! A Rust library for encoding and decoding data in the Bencode format, commonly used in BitTorrent files.
2//! This library provides functionality to parse, create, modify and serialize bencode data structures
3//! with support for various formats including JSON, YAML and XML conversion.
4//!
5//! # Features
6//!
7//! - `std` (default): Enable standard library support
8//! - Without `std`: Core bencode functionality works in `no_std` environments
9
10#![cfg_attr(not(feature = "std"), no_std)]
11
12#[cfg(not(feature = "std"))]
13extern crate alloc;
14
15#[cfg(not(feature = "std"))]
16pub(crate) use alloc::collections::BTreeMap as HashMap;
17
18#[cfg(feature = "std")]
19pub(crate) use std::collections::HashMap;
20
21/// Centralized bencode protocol character and byte constants
22pub(crate) mod constants;
23/// Module defining custom error types and error handling functionality
24pub mod error;
25/// Module providing input/output operations for reading and writing bencode data
26pub mod io;
27/// Module containing utility functions and helper methods
28pub mod misc;
29
30/// Module containing configuration options for parsing and encoding
31pub mod config;
32/// Module providing memory management utilities for embedded systems
33pub mod memory;
34/// Module defining the core data structures for representing bencode nodes
35pub mod nodes;
36/// Module containing the parsing logic to decode bencode format into data structures
37pub mod parser;
38/// Module implementing serialization of data structures back to bencode format
39pub mod stringify;
40
41/// Integration tests module
42mod integration_tests;
43
44///
45/// babbel_bencode API
46///
47
48/// Returns the current version of the bencode library
49pub use misc::get_version as version;
50
51/// Reads and parses a bencode-encoded file from disc (requires `std` feature)
52#[cfg(feature = "std")]
53pub use misc::read_bencode_file as read_file;
54
55/// Writes bencode-encoded data to a file on disk (requires `std` feature)
56#[cfg(feature = "std")]
57pub use misc::write_bencode_file as write_file;
58
59/// Destination implementation for writing bencode data to a memory buffer
60pub use io::destinations::buffer::Buffer as BufferDestination;
61
62/// Destination implementation for writing bencode data to a file (requires `std` feature)
63#[cfg(feature = "std")]
64pub use io::destinations::file::File as FileDestination;
65
66/// Source implementation for reading bencode data from a memory buffer
67pub use io::sources::buffer::Buffer as BufferSource;
68
69/// Source implementation for reading bencode data from a file (requires `std` feature)
70#[cfg(feature = "std")]
71pub use io::sources::file::File as FileSource;
72
73/// Core data structure representing a bencode node in the parsed tree
74pub use nodes::node::Node;
75pub use nodes::node::make_node;
76
77/// Zero-copy borrowed node for embedded systems (no allocation)
78pub use nodes::borrowed::BorrowedNode;
79
80/// Type alias for fixed-size stack buffers with const generics
81pub use nodes::fixed::FixedSizeBuffer;
82/// Memory bounds calculator using const generics
83pub use nodes::fixed::MemoryBounds;
84
85/// Parses bencode data into a Node tree structure
86pub use parser::default::parse;
87/// Parses bencode data from a byte slice into a Node tree structure
88pub use parser::default::parse_bytes;
89/// Parses bencode data from a string into a Node tree structure
90pub use parser::default::parse_str;
91
92/// Parses bencode data from any streaming source. Canonical alias for [`parse`].
93pub use parser::default::parse as from_source;
94/// Parses bencode data from a byte slice. Canonical alias for [`parse_bytes`].
95pub use parser::default::parse_bytes as from_bytes;
96/// Parses bencode data from a string slice. Canonical alias for [`parse_str`].
97pub use parser::default::parse_str as from_str;
98
99/// Zero-copy parser that returns borrowed nodes (no allocation)
100pub use parser::borrowed::parse_borrowed;
101/// Validates bencode data without building a node tree (minimal allocation)
102pub use parser::borrowed::validate_bencode;
103
104/// Parses bencode data from a byte slice using iterative parser
105pub use parser::iterative::parse_bytes_iterative;
106/// Iterative parser that avoids recursion (for deeply nested structures)
107pub use parser::iterative::parse_iterative;
108/// Parses bencode data from a string using iterative parser
109pub use parser::iterative::parse_str_iterative;
110
111/// Arena allocator for bump allocation from fixed buffers
112pub use memory::Arena;
113/// Memory usage tracker for embedded systems
114pub use memory::MemoryTracker;
115/// Stack-based fixed-size buffer
116pub use memory::StackBuffer;
117
118/// Lightweight error type for embedded systems (no heap allocation)
119pub use error::embedded::BencodeError;
120
121/// Encoder configuration options
122pub use config::EncoderConfig;
123/// Parser configuration options
124pub use config::ParserConfig;
125
126/// Converts a Node tree back to bencode format
127pub use stringify::default::stringify;
128/// Converts a Node tree to bencode format as bytes
129pub use stringify::default::stringify_to_bytes;
130/// Converts a Node tree to bencode format as a String
131pub use stringify::default::stringify_to_string;
132
133/// Converts a Node tree to bencode format as bytes. Canonical alias for [`stringify_to_bytes`].
134pub use stringify::default::stringify_to_bytes as to_vec;
135/// Converts a Node tree to bencode format as a String. Canonical alias for [`stringify_to_string`].
136pub use stringify::default::stringify_to_string as to_string;
137
138/// Core SOLID I/O abstractions
139pub use io::traits::{BencodeRead, BencodeWrite, BufferedWrite, RewindableRead};
140
141/// Schema validation and typed dictionary query extension trait
142pub use nodes::query::NodeQueryExt;
143
144/// Visitor pattern traits for format serialization
145pub use stringify::visitor::{BencodeVisitable, BencodeVisitor};
146
147/// Converts a Node tree to JSON format (requires "json" feature)
148#[cfg(feature = "json")]
149pub use stringify::json::stringify as to_json;
150
151/// Converts a Node tree to TOML format (requires "toml" feature)
152#[cfg(feature = "toml")]
153pub use stringify::toml::stringify as to_toml;
154
155/// Converts a Node tree to XML format (requires "xml" feature)
156#[cfg(feature = "xml")]
157pub use stringify::xml::stringify as to_xml;
158
159/// Converts a Node tree to YAML format (requires "yaml" feature)
160#[cfg(feature = "yaml")]
161pub use stringify::yaml::stringify as to_yaml;
162
163/// Format engine implementation adhering to OCP and DIP
164pub mod engine;
165pub use engine::BencodeEngine;