Merge pull request #42 from mmalecot/dev

v0.23.0

CHANGELOG.md

@@ -1,3 +1,24 @@
+# Version 0.23.0 (2023-12-11)
+
+## Fixes
+
+- Fix Neo Geo Pocket ROM (NGP) extension
+
+## Improvements
+
+- Add precision to the JSON Feed signature
+
+## Internal changes
+
+- Improve performance and precision of all readers
+
+## New formats support
+
+- Empty
+- Microsoft Write (WRI)
+- Neo Geo Pocket Color ROM (NGC)
+- Picture Exchange (PCX)
+
 # Version 0.22.0 (2023-11-04)
 
 ## Internal changes

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "file-format"
-version = "0.22.0"
+version = "0.23.0"
 authors = ["Mickaël Malécot <[email protected]>"]
 edition = "2021"
 description = "Crate for determining the file format of a given file or stream."

README.md

@@ -9,10 +9,11 @@
 Crate for determining the file format of a given file or stream.
 
 It provides a variety of functions for identifying a wide range of file formats, including ZIP,
-Compound File Binary (CFB), Extensible Markup Language (XML) and more.
+Compound File Binary (CFB), Extensible Markup Language (XML) and much more.
 
-It checks the signature of the file to determine its format. If it is not recognized by its
-signature, it returns the default file format which is Arbitrary Binary Data (BIN).
+It checks the signature of the file to determine its format and intelligently employs specific
+readers when available for accurate identification. If the signature is not recognized, the crate
+falls back to the default file format, which is Arbitrary Binary Data (BIN).
 
 ## Examples
 
@@ -50,9 +51,36 @@ Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-file-format = "0.22"
+file-format = "0.23"
 ```
 
+## Crate features
+
+All features below are disabled by default.
+
+### Ecosystem features
+
+- `serde` - Adds the ability to serialize and deserialize a `FileFormat` and `Kind` using serde.
+
+### Reader features
+
+These features enable the detection of file formats that require a specific reader for
+identification.
+
+- `reader` - Enables all reader features.
+- `reader-asf` - Enables Advanced Systems Format (ASF) based file formats detection.
+- `reader-cfb` - Enables Compound File Binary (CFB) based file formats detection.
+- `reader-ebml` - Enables Extensible Binary Meta Language (EBML) based file formats detection.
+- `reader-exe` - Enables MS-DOS Executable (EXE) based file formats detection.
+- `reader-mp4` - Enables MPEG-4 Part 14 (MP4) based file formats detection.
+- `reader-pdf` - Enables Portable Document Format (PDF) based file formats detection.
+- `reader-rm` - Enables RealMedia (RM) based file formats detection.
+- `reader-txt` - Enables Plain Text (TXT) detection when the file format is not recognized by its
+  signature. Please note that this feature only detects files containing ASCII/UTF-8-encoded text.
+- `reader-xml` - Enables Extensible Markup Language (XML) based file formats detection. Please note
+  that these file formats may be detected without the feature in certain cases.
+- `reader-zip` - Enables ZIP-based file formats detection.
+
 ## Supported file formats
 
 ### Application
@@ -69,6 +97,7 @@ file-format = "0.22"
 - CD Audio (CDA)
 - Compound File Binary (CFB)
 - Digital Imaging and Communications in Medicine (DICOM)
+- Empty
 - Encapsulated PostScript (EPS)
 - Extensible Binary Meta Language (EBML)
 - Extensible Stylesheet Language Transformations (XSLT)
@@ -237,6 +266,7 @@ file-format = "0.22"
 - Microsoft Works 6 Spreadsheet (XLR)
 - Microsoft Works Spreadsheet (WKS)
 - Microsoft Works Word Processor (WPS)
+- Microsoft Write (WRI)
 - Office Open XML Document (DOCX)
 - Office Open XML Drawing (VSDX)
 - Office Open XML Presentation (PPTX)
@@ -359,6 +389,7 @@ file-format = "0.22"
 - OpenEXR (EXR)
 - OpenRaster (ORA)
 - Panasonic Raw (RW2)
+- Picture Exchange (PCX)
 - Portable Arbitrary Map (PAM)
 - Portable BitMap (PBM)
 - Portable FloatMap (PFM)
@@ -463,6 +494,7 @@ file-format = "0.22"
 - Game Boy ROM (GB)
 - Game Gear ROM (GG)
 - Mega Drive ROM (MD)
+- Neo Geo Pocket Color ROM (NGC)
 - Neo Geo Pocket ROM (NGP)
 - Nintendo 64 ROM (Z64)
 - Nintendo DS ROM (NDS)

src/formats.rs

@@ -646,6 +646,12 @@ formats! {
     extension = "eot"
     kind = Font
 
+    format = Empty
+    name = "Empty"
+    media_type = "application/x-empty"
+    extension = "empty"
+    kind = Application
+
     format = EncapsulatedPostscript
     name = "Encapsulated PostScript"
     short_name = "EPS"
@@ -1436,6 +1442,13 @@ formats! {
     extension = "wps"
     kind = Document
 
+    format = MicrosoftWrite
+    name = "Microsoft Write"
+    short_name = "WRI"
+    media_type = "application/x-mswrite"
+    extension = "wri"
+    kind = Document
+
     format = Mobipocket
     name = "Mobipocket"
     short_name = "MOBI"
@@ -1529,7 +1542,7 @@ formats! {
 
     format = MpegDashManifest
     name = "MPEG-DASH Manifest"
-    short_name= "MPD"
+    short_name = "MPD"
     media_type = "application/dash+xml"
     extension = "mpd"
     kind = Playlist
@@ -1588,11 +1601,18 @@ formats! {
     extension = "mxl"
     kind = Application
 
+    format = NeoGeoPocketColorRom
+    name = "Neo Geo Pocket Color ROM"
+    short_name = "NGC"
+    media_type = "application/x-neo-geo-pocket-rom"
+    extension = "ngc"
+    kind = Rom
+
     format = NeoGeoPocketRom
     name = "Neo Geo Pocket ROM"
     short_name = "NGP"
     media_type = "application/x-neo-geo-pocket-rom"
-    extension = "npg"
+    extension = "ngp"
     kind = Rom
 
     format = NewExecutable
@@ -1958,6 +1978,13 @@ formats! {
     extension = "asc"
     kind = Application
 
+    format = PictureExchange
+    name = "Picture Exchange"
+    short_name = "PCX"
+    media_type = "image/x-pcx"
+    extension = "pcx"
+    kind = Image
+
     format = PlainText
     name = "Plain Text"
     short_name = "TXT"

src/lib.rs

@@ -3,10 +3,12 @@ Crate for determining the file format of a [given file](`FileFormat::from_file`)
 
 It provides a variety of functions for identifying a wide range of file formats, including
 [ZIP](`FileFormat::Zip`), [Compound File Binary (CFB)](`FileFormat::CompoundFileBinary`),
-[Extensible Markup Language (XML)](`FileFormat::ExtensibleMarkupLanguage`) and [more](`FileFormat`).
+[Extensible Markup Language (XML)](`FileFormat::ExtensibleMarkupLanguage`) and
+[much more](`FileFormat`).
 
-It checks the signature of the file to determine its format. If it is not recognized by its
-signature, it returns the default file format which is
+It checks the signature of the file to determine its format and intelligently employs specific
+readers when available for accurate identification. If the signature is not recognized, the crate
+falls back to the default file format, which is
 [Arbitrary Binary Data (BIN)](`FileFormat::ArbitraryBinaryData`).
 
 # Examples
@@ -50,8 +52,8 @@ All features below are disabled by default.
 
 ## Reader features
 
-These features enable the detection of file formats that need a specific reader in order to be
-detected.
+These features enable the detection of file formats that require a specific reader for
+identification.
 
 - `reader` - Enables all reader features.
 - `reader-asf` - Enables [Advanced Systems Format (ASF)](`FileFormat::AdvancedSystemsFormat`) based
@@ -62,7 +64,6 @@ detected.
 - `reader-cfb` - Enables [Compound File Binary (CFB)](`FileFormat::CompoundFileBinary`) based file
   formats detection.
   * [3D Studio Max (MAX)](`FileFormat::ThreeDimensionalStudioMax`)
-  * [Autodesk 123D (123DX)](`FileFormat::Autodesk123d`)
   * [Autodesk Inventor Assembly (IAM)](`FileFormat::AutodeskInventorAssembly`)
   * [Autodesk Inventor Drawing (IDW)](`FileFormat::AutodeskInventorDrawing`)
   * [Autodesk Inventor Part (IPT)](`FileFormat::AutodeskInventorPart`)
@@ -76,7 +77,6 @@ detected.
   * [Microsoft Word Document (DOC)](`FileFormat::MicrosoftWordDocument`)
   * [Microsoft Works 6 Spreadsheet (XLR)](`FileFormat::MicrosoftWorks6Spreadsheet`)
   * [Microsoft Works Database (WDB)](`FileFormat::MicrosoftWorksDatabase`)
-  * [Microsoft Works Spreadsheet (WKS)](`FileFormat::MicrosoftWorksSpreadsheet`)
   * [Microsoft Works Word Processor (WPS)](`FileFormat::MicrosoftWorksWordProcessor`)
   * [SolidWorks Assembly (SLDASM)](`FileFormat::SolidworksAssembly`)
   * [SolidWorks Drawing (SLDDRW)](`FileFormat::SolidworksDrawing`)
@@ -114,11 +114,11 @@ detected.
   * [RealAudio (RA)](`FileFormat::Realaudio`)
   * [RealVideo (RV)](`FileFormat::Realvideo`)
 - `reader-txt` - Enables [Plain Text (TXT)](`FileFormat::PlainText`) detection when the file format
-  is not recognized by its signature. Please note that this option only detects files that contain
+  is not recognized by its signature. Please note that this feature only detects files containing
   ASCII/UTF-8-encoded text.
 - `reader-xml` - Enables [Extensible Markup Language (XML)](`FileFormat::ExtensibleMarkupLanguage`)
   based file formats detection. Please note that these file formats may be detected without the
-  feature in some cases.
+  feature in certain cases.
   * [AbiWord (ABW)](`FileFormat::Abiword`)
   * [AbiWord Template (AWT)](`FileFormat::AbiwordTemplate`)
   * [Additive Manufacturing Format (AMF)](`FileFormat::AdditiveManufacturingFormat`)
@@ -149,6 +149,7 @@ detected.
   * [3D Manufacturing Format (3MF)](`FileFormat::ThreeDimensionalManufacturingFormat`)
   * [Adobe Integrated Runtime (AIR)](`FileFormat::AdobeIntegratedRuntime`)
   * [Android Package (APK)](`FileFormat::AndroidPackage`)
+  * [Autodesk 123D (123DX)](`FileFormat::Autodesk123d`)
   * [Circuit Diagram Document (CDDX)](`FileFormat::CircuitDiagramDocument`)
   * [Design Web Format XPS (DWFX)](`FileFormat::DesignWebFormatXps`)
   * [Electronic Publication (EPUB)](`FileFormat::ElectronicPublication`)
@@ -198,6 +199,7 @@ detected.
 */
 
 #![deny(missing_docs)]
+#![forbid(unsafe_code)]
 
 #[macro_use]
 mod macros;
@@ -209,7 +211,7 @@ mod signatures;
 use std::{
     fmt::{self, Display, Formatter},
     fs::File,
-    io::{BufRead, BufReader, Cursor, Read, Result, Seek},
+    io::{Cursor, Read, Result, Seek},
     path::Path,
 };
 
@@ -269,20 +271,18 @@ impl FileFormat {
     /// use file_format::FileFormat;
     ///
     /// let format = FileFormat::from_reader(std::io::empty())?;
-    /// assert_eq!(format, FileFormat::default());
+    /// assert_eq!(format, FileFormat::Empty);
     /// # Ok::<(), std::io::Error>(())
     ///```
-    pub fn from_reader<R: Read + Seek>(reader: R) -> Result<Self> {
-        // Maximum required size to read and detect the file format from its signature.
-        const BUFFER_SIZE: usize = 36870;
-
-        // Creates a buffered reader with the specified size.
-        let mut reader = BufReader::with_capacity(BUFFER_SIZE, reader);
+    pub fn from_reader<R: Read + Seek>(mut reader: R) -> Result<Self> {
+        // Creates and fills a buffer.
+        let mut buffer = [0; 36870];
+        let bytes_read = reader.read(&mut buffer)?;
 
-        // Attempts to detect the file format.
-        Ok(if reader.fill_buf()?.is_empty() {
-            Self::default()
-        } else if let Some(format) = Self::from_signature(reader.buffer()) {
+        // Determines file format.
+        Ok(if bytes_read == 0 {
+            Self::Empty
+        } else if let Some(format) = Self::from_signature(&buffer[..bytes_read]) {
             Self::from_format_reader(format, &mut reader)
                 .unwrap_or_else(|_| Self::from_generic_reader(&mut reader))
         } else {
@@ -321,7 +321,7 @@ pub enum Kind {
     /// Data which do not fit in any of the other kinds, and particularly for data to be processed
     /// by some type of application program.
     Application,
-    /// Stored files and directories into a single file, possibly compressed.
+    /// Files and directories stored in a single, possibly compressed, archive.
     Archive,
     /// Musics, sound effects, and spoken audio recordings.
     Audio,
@@ -335,10 +335,10 @@ pub enum Kind {
     Database,
     /// Floppy disk images, optical disc images and virtual machine disks.
     Disk,
-    /// Word processing documents, spreadsheets, presentations, documents templates, diagrams,
+    /// Word processing documents, spreadsheets, presentations, document templates, diagrams,
     /// charts, and other formatted documents.
     Document,
-    /// Machine executable codes, virtual machine codes and shared libraries.
+    /// Machine-executable codes, virtual machine codes and shared libraries.
     Executable,
     /// Typefaces used for displaying text on screen or in print.
     Font,
@@ -348,21 +348,21 @@ pub enum Kind {
     Image,
     /// 3D models, CAD drawings, and other types of files used for creating or displaying 3D images.
     Model,
-    /// Archives or other containers that bundles programs and resources that can be run on target
+    /// Archives or other containers that bundle programs and resources that can be run on target
     /// environments.
     Package,
     /// Lists of audio or video files that are played in a specific order.
     Playlist,
-    /// Copies of a read-only memory chip of computers, cartridges or other electronic devices.
+    /// Copies of a read-only memory chip of computers, cartridges, or other electronic devices.
     Rom,
     /// Subtitles and captions.
     Subtitle,
     /// Web feeds and syndication.
     Syndication,
-    /// Plain text, source codes, markup languages, and other types of files that contain written
+    /// Plain text, source codes, markup languages, and other types of files containing written
     /// text.
     Text,
-    /// Movies, animations, and other types of files that contain moving images, possibly with color
+    /// Movies, animations, and other types of files containing moving images, possibly with color
     /// and coordinated sound.
     Video,
 }