spam-db 0.2.2

Parser and query library for SPAM databases
Documentation 
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

//! Parser and query library for [spam](https://github.com/feel-co/spam) databases.
//!
//! spam indexes Nix package closures and `nixosOptionsDoc` output into
//! compressed, bucket-indexed databases. Use this crate to open those
//! databases and run substring queries against them.
//!
//! ## Database kinds
//!
//! - [`OptionsDb`]: NixOS module options, keyed by option name.
//! - [`PackagesDb`]: Nix store file paths, keyed by path. Opens both
//!   `packages` databases from `spam db build` and `index` databases from
//!   `spam index`.
//!
//! ## File format
//!
//! ```text
//! # spam-db-v2\t{options|packages|index}\n
//! [256 x 16-byte index entries: (offset: u64le, length: u64le)]
//! [concatenated zstd-compressed bucket blobs]
//! ```
//!
//! Each line is placed in every bucket for each unique byte in its search key.
//! Queries decompress only the bucket for `query[0]`.
//!
//! ## Usage
//!
//! ```rust,no_run
//! use spam_db::SpamDb;
//!
//! match SpamDb::open("files.db").unwrap() {
//!     SpamDb::Options(db) => {
//!         for rec in db.query("services.nginx").unwrap() {
//!             println!("{}: {:?}", rec.name, rec.summary);
//!         }
//!     }
//!     SpamDb::Packages(db) => {
//!         for rec in db.query("/bin/").unwrap() {
//!             println!("{} -> {}", rec.path, rec.packages.join(", "));
//!         }
//!     }
//!     SpamDb::Index(db) => {
//!         for rec in db.query("/bin/").unwrap() {
//!             println!("{} -> {}", rec.path, rec.packages.join(", "));
//!         }
//!     }
//! }
//! ```
//!
//! ```rust,no_run
//! use spam_db::OptionsDb;
//!
//! let db = OptionsDb::open("options.db").unwrap();
//! let results = db.query("networking.firewall").unwrap();
//! ```

mod format;

pub mod error;
pub mod options;
pub mod packages;

pub use error::Error;
pub use format::DbKind;
pub use options::{OptionRecord, OptionsDb};
pub use packages::{FileKind, FileRecord, PackagesDb};

/// Convenience alias for `Result<T, spam_db::Error>`.
pub type Result<T> = std::result::Result<T, Error>;

/// A spam database returned by [`SpamDb::open`] when the kind is not known at
/// compile time.
#[derive(Debug)]
pub enum SpamDb {
  /// An options database (NixOS module options).
  Options(OptionsDb),
  /// A package-manifest database from `spam db build`.
  Packages(PackagesDb),
  /// An autonomous package index from `spam index`.
  Index(PackagesDb),
}

impl SpamDb {
  /// Open a spam database, detecting the kind from the file header.
  pub fn open(path: impl AsRef<std::path::Path>) -> Result<Self> {
    let db = format::DbFile::open(path)?;
    match db.kind {
      DbKind::Options => Ok(SpamDb::Options(OptionsDb::from_file(db))),
      DbKind::Packages => Ok(SpamDb::Packages(PackagesDb::from_file(db))),
      DbKind::Index => Ok(SpamDb::Index(PackagesDb::from_file(db))),
    }
  }

  /// The kind of this database.
  pub fn kind(&self) -> DbKind {
    match self {
      SpamDb::Options(_) => DbKind::Options,
      SpamDb::Packages(_) => DbKind::Packages,
      SpamDb::Index(_) => DbKind::Index,
    }
  }
}