nix_nar/
lib.rs

1#![warn(clippy::pedantic)]
2
3//! # Summary
4//!
5//! Library to manipulate Nix Archive (nar) files.
6//!
7//! For the NAR specification, see ["The Purely Functional Deployment
8//! Model" by Eelco
9//! Dolstra](https://edolstra.github.io/pubs/phd-thesis.pdf), Figure
10//! 5.2 (page 93).
11//!
12//! ## Encoding
13//!
14//! To encode a directory as a NAR file, first create an [`Encoder`]
15//! with [`Encoder::new`], then treat it as a [`std::io::Read`]
16//! instance.  For instance, you can [`std::io::copy`] it to a file.
17//!
18//! ```no_run
19//! use nix_nar::Encoder;
20//! # use std::{io, fs::File};
21//! # fn main() -> io::Result<()> {
22//! let mut enc = Encoder::new("some/dir").unwrap();
23//! let mut nar = File::create("output.nar")?;
24//! io::copy(&mut enc, &mut nar)?;
25//! # Ok(())
26//! # }
27//! ```
28//!
29//! If you have very long filenames, use [`Encoder::builder()`] and
30//! then configure the internal buffer size to be at least 200 bytes
31//! larger than the longest filename.
32//!
33//! Alternatively, use the [`Encoder::pack`] helper.
34//!
35//! ## Decoding
36//!
37//! To decode a NAR file, first create a [`Decoder`] with
38//! [`Decoder::new`], and then call [`Decoder::entries`] to iterate
39//! through the files in the archive.
40//!
41//! ```
42//!   use nix_nar::Decoder;
43//!   # use nix_nar::NarError;
44//!   # fn main() -> Result<(), NarError> {
45//!   let input = include_bytes!("../test-data/02-empty-file.nar");
46//!   let dec = Decoder::new(&input[..])?;
47//!   for entry in dec.entries()? {
48//!     let entry = entry?;
49//!     println!("{:?} {:?}", entry.path, entry.content);
50//!   }
51//!   # Ok(())
52//!   # }
53//! ```
54//!
55//! Alternatively, use [`Decoder::unpack`] to extract a NAR file to a
56//! directory.
57
58mod coder;
59pub mod debug;
60mod dec;
61mod enc;
62mod error;
63mod parser;
64
65pub use crate::dec::{Content, Decoder, Entries, Entry};
66pub use crate::enc::{Encoder, EncoderBuilder};
67pub use crate::error::NarError;
nix_nar/lib.rs

nix_nar/
lib.rs
