magic_db/lib.rs
1#![forbid(unsafe_code)]
2#![deny(unused_imports)]
3#![deny(missing_docs)]
4//! # `magic-db`: Precompiled Magic Rules Database
5//!
6//! A precompiled database of file type detection rules based on the original `libmagic` project,
7//! optimized and adapted for use with [`pure-magic`](https://crates.io/crates/pure-magic).
8//! This crate provides ready-to-use file type detection capabilities without requiring external rule files.
9//!
10//! ## Features
11//!
12//! - **Precompiled Rules**: Optimized database embedded directly in your binary
13//! - **No External Dependencies**: All rules are included in the compiled crate
14//! - **Enhanced Rules**: Improved and extended versions of the original `libmagic` rules
15//! - **Easy Integration**: Simple one-line access to the compiled database
16//!
17//! ## Installation
18//!
19//! Add `magic-db` to your `Cargo.toml`:
20//!
21//! ```toml
22//! [dependencies]
23//! magic-db = "0.1" # Replace with the latest version
24//! pure-magic = "0.1" # Required peer dependency
25//! ```
26//!
27//! ## Usage
28//!
29//! ```rust
30//! use magic_db::CompiledDb;
31//! use std::fs::File;
32//! use std::env::current_exe;
33//!
34//! fn main() -> Result<(), pure_magic::Error> {
35//! // Open the precompiled database
36//! let db = CompiledDb::open()?;
37//!
38//! // Use it to detect file types
39//! let mut file = File::open(current_exe()?)?;
40//! let magic = db.first_magic(&mut file, None)?;
41//! assert!(!magic.is_default());
42//!
43//! println!("File type: {}", magic.message());
44//! println!("MIME type: {}", magic.mime_type());
45//! Ok(())
46//! }
47//! ```
48//!
49//! ## About the Rules
50//!
51//! This database contains slightly modified versions of the original `libmagic` rules that are available
52//! in the [`src/magdir`](https://github.com/qjerome/magic-rs/tree/main/magic-db/src/magdir) directory of this repository.
53//!
54//! Some of the rules have been:
55//! - **Adapted**: Modified to work with the [`pure-magic`](https://crates.io/crates/pure-magic) parser
56//! - **Optimized**: Performance improvements for common file types
57//! - **Extended**: Additional rules were created
58//! - **Fixed**: Corrections to inaccurate or problematic original rules
59//!
60//! ## Rule Exclusions
61//!
62//! The database intentionally excludes the `der` rules (ASN.1/DER encoding rules) because:
63//! - The [`pure-magic`](https://crates.io/crates/pure-magic) parser doesn't support (yet) the specific DER test types
64//! implemented in the original `libmagic`
65//!
66//! ## Source Rules
67//!
68//! The source magic rules are available in the repository at:
69//! [`src/magdir`](https://github.com/qjerome/magic-rs/tree/main/magic-db/src/magdir)
70//!
71//! You can:
72//! 1. Browse the rules to understand how file types are detected
73//! 2. Suggest improvements by opening issues or pull requests
74//! 3. Use these rules as a reference for creating your own custom rules
75//!
76//! ## License
77//!
78//! This project is licensed under the **GPL-3.0 License**.
79//!
80//! ## See Also
81//!
82//! - [`pure-magic`](https://crates.io/crates/pure-magic): The core file type detection library
83//! - [`magic-embed`](https://crates.io/crates/magic-embed): The macro used to create this database
84//! - [`magic`](https://www.man7.org/linux/man-pages/man4/magic.4.html): Expected magic rule format
85
86use magic_embed::magic_embed;
87
88#[magic_embed(include=["magdir"], exclude=["magdir/der"])]
89pub struct CompiledDb;
90
91#[cfg(test)]
92mod test {
93 use crate::CompiledDb;
94 use std::{env, fs::File};
95
96 #[test]
97 fn test_compiled_db() {
98 let db = CompiledDb::open().unwrap();
99 let mut exe = File::open(env::current_exe().unwrap()).unwrap();
100 let magic = db.first_magic(&mut exe, None).unwrap();
101 println!("{}", magic.message());
102 assert!(!magic.is_default())
103 }
104}