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