magical_rs

A zero-dependency, no_std-friendly Rust crate that detects file types with surgical precision by matching magic bytes at exact offsets — including deep-offset formats like ISO and TAR. Built for speed, safety, and extensibility.

Table of Contents:

• magical_rs
  • Table of Contents:
  • Level of use
  • Supported File Types
  • License

Level of use

Level 1, uses built-in file detection via signature:

• At this level, you will use the magical_rs built-in API, which supports detecting ~50 file types via signatures.

• List of currently supported file types here

• By the way, you can contribute new file signatures here

• Examples:

•   let max_byte_read = with_bytes_read();
  
    let bytes = read_file_header("img/2.iso", max_byte_read).unwrap();
  
    match FileKind::match_types(&bytes) {
        Some(k) => println!("{k:?}"),
        None => println!("Could not detect ISO file."),
    }
  

• More examples of level 1 can be found here

Level 2, untilimited compiler-time customization with infinite function pointers:

• At this level, you can customize file signatures, offsets, and more.

• Here, you can also use function pointers for complex logic. In theory, you can do almost anything at compiler-time. And thanks to that, you can detect any file type you want.

• Also, supports the use of infinite function pointers at once. And function pointers have macros with syntax-sugar supports at well.

• Examples:

• #[derive(Clone, Copy, PartialEq, Eq, Debug)]
  enum FileKind {
    Shoujo,
    UnknownFallback,
  }
  
  fn is_shoujo(bytes: &[u8]) -> bool {
      bytes.starts_with(b"Magic!")
  }
  
  fn is_not_shoujo(bytes: &[u8]) -> bool {
      !bytes.starts_with(b"Magic!")
  }
  
  
  pub fn magic_custom_any() {
      let rule = magic_custom! (
          signatures: [b""],
          offsets: [0],
          max_bytes_read: 2451,
          kind: FileKind::Shoujo,
          rules: any_matches!(is_shoujo, is_not_shoujo)
      );
  
      let result = match_custom! (
          bytes: b"Magic!",
          rules: [rule],
          fallback: FileKind::UnknownFallback
      );
  
      assert_eq!(result, FileKind::Shoujo);
      assert_ne!(result, FileKind::UnknownFallback);
  }
  

• There are many ways to implement it, and you can find them here

Level 1 & 2 both support no_std.

Level 3, custom run-time file detection with infinite logic

• At this level, you can customize the runtime logic. You can do anything. You can detect any type of file, even if it changes at run-time. You can emit AI, send requests to the Open-AI API, even spawn processes. The only limit is your imagination.

• So, you need to unlock this feature by:

• cargo add magical_rs --features magical_dyn
  

• Examples:

• fn my_detect_rule() -> impl Fn(&[u8]) -> bool {
      let require_bytes = b"MagicalGirl";
  
      |bytes: &[u8]| bytes.starts_with(require_bytes) && bytes.len() == require_bytes.len()
  }
  
  fn detect_custom_file(file_bytes: &'static [u8]) -> bool {
  
      let detect_fn = my_detect_rule();
      let rule = DynMagicCustom::new(detect_fn, String::from("Is Mahou Shoujo Detect."), 32);
  
      let kind = rule.kind_downcast_ref::<String>();
      
      match kind {
          Some(k) => println!("{k}"), /* Is Mahou Shoujo Detect. */
          None => println!("Kind not found."),
      }
      rule.matches(file_bytes)
  }
  
  

• Many examples of use can be found here

• Warning: Use only if you really know what you are doing.

Supported File Types

License

• magical_rs is licensed under the GNU General Public License v3.0. See here