niffler_temp/lib.rs
1//! # niffler
2//! Simple and transparent support for compressed files.
3//!
4//! This library provides two main features:
5//! - sniffs out compression formats from input files and return a
6//! Read trait object ready for consumption.
7//! - Create a Writer initialized with compression ready for writing.
8//!
9//! The goal is to lower the barrier to open and use a file, especially in
10//! bioinformatics workflows.
11//!
12//! # Example
13//!
14//! ```rust
15//! use niffler_temp::{Error, compression};
16//! # fn main() -> Result<(), Error> {
17//! # #[cfg(feature = "gz")] {
18//! let mut buffer = Vec::new();
19//!
20//! {
21//! let mut writer = niffler_temp::get_writer(Box::new(&mut buffer), compression::Format::Gzip, niffler_temp::Level::Nine)?;
22//! writer.write_all(b"hello")?;
23//! }
24//!
25//! # assert_eq!(&buffer, &[0x1f, 0x8b, 8, 0, 0, 0, 0, 0, 2, 255, 203, 72, 205, 201, 201, 7, 0, 134, 166, 16, 54, 5, 0, 0, 0]);
26//!
27//! let (mut reader, compression) = niffler_temp::get_reader(Box::new(&buffer[..]))?;
28//!
29//! let mut contents = String::new();
30//! reader.read_to_string(&mut contents)?;
31//!
32//! assert_eq!(compression, niffler_temp::compression::Format::Gzip);
33//! assert_eq!(contents, "hello");
34//! # }
35//! # Ok(())
36//! # }
37//! ```
38//!
39//! ## Selecting compression formats
40//!
41//! By default all supported compression formats are enabled.
42//! If you're working on systems that don't support them you can disable default
43//! features and select the ones you want.
44//! For example,
45//! currently only `gz` is supported in Webassembly environments
46//! (because `niffler` depends on crates that have system dependencies for `bz2` and `lzma` compression),
47//! so you can use this in your `Cargo.toml` to select only the `gz` support:
48//! ```toml
49//! niffler = { version = "2.2.0", default-features = false, features = ["gz"] }
50//! ```
51//!
52//! You can still use `niffler_temp::sniff()` to find what is the compression format,
53//! even if any feature is disabled.
54//! But if you try to use `niffler_temp::get_reader` for a disabled feature,
55//! it will throw a runtime error.
56//!
57//! ## Backends features
58//!
59//! The libraries that are used for decompression provide a number of features that can have a significant impact on performance.
60//! Here is the list of features available with corresponding backend crates and features name in backend crates:
61//! - bz2_tokio -> bzip2 tokio
62//! - bz2_static -> bzip2 static
63//! - lzma_tokio -> lzma tokio
64//! - gz_zlib -> flate2 zlib
65//! - gz_zlib-ng-compat -> flate2 zlib-ng-compat
66//! - gz_cloudflare_zlib -> flate2 cloudflare_zlib
67//! - gz_rust_backend -> flate2 rust_backend
68//! - xz_tokio -> xz2 tokio
69
70/* declare mod */
71pub mod basic;
72pub mod error;
73pub mod level;
74pub mod seek;
75pub mod seeksend;
76pub mod send;
77pub(crate) mod utils;
78
79/* reexport for convinent usage of niffler */
80pub use crate::basic::compression::Format;
81pub use crate::basic::*;
82pub use crate::error::Error;
83pub use crate::level::Level;