mimetype

README

mimetype

A package for detecting MIME types and extensions based on magic numbers

No bindings, thread safe and completely written in go

Install

go get github.com/gabriel-vasile/mimetype

Usage

There are quick examples and GoDoc for full reference.

Upgrade from v0.3.x to v1.x

In v1.x the detect functions no longer return the MIME type and extension as strings. Instead they return a MIME struct. To get the string value of the MIME and the extension, call the String() and the Extension() methods.

In order to play better with the stdlib mime package, v1.x file extensions include the leading dot, as in ".html".

In v1.x the text/plain MIME type is text/plain; charset=utf-8.

Supported MIME types

See supported mimes for the list of detected MIME types. If support is needed for a specific file format, please open an issue.

Structure

mimetype uses an hierarchical structure to keep the MIME type detection logic. This reduces the number of calls needed for detecting the file type. The reason behind this choice is that there are file formats used as containers for other file formats. For example, Microsoft Office files are just zip archives, containing specific metadata files. Once a file a file has been identified as a zip, there is no need to check if it is a text file, but it is worth checking if it is an Microsoft Office file.

Contributing

See CONTRIBUTING.md.

Documentation

Overview

Package mimetype uses magic number signatures to detect the MIME type of a file.

mimetype stores the list of MIME types in a tree structure with "application/octet-stream" at the root of the hierarchy. The hierarchy approach minimizes the number of checks that need to be done on the input and allows for more precise results once the base type of file has been identified.

Example (Check)

To check if some bytes/reader/file has a specific MIME type, first perform a detect on the input and then test against the MIME.

Is method can also be called with MIME aliases.

package main

import (
	"fmt"

	"github.com/gabriel-vasile/mimetype"
)

func main() {
	mime, err := mimetype.DetectFile("testdata/zip.zip")
	// application/x-zip is an alias of application/zip,
	// therefore Is returns true both times.
	fmt.Println(mime.Is("application/zip"), mime.Is("application/x-zip"), err)

}

Output:
true true <nil>

Example (Detect)

To find the MIME type of some input, perform a detect. In addition to the basic Detect,

mimetype.Detect([]byte) *MIME

there are shortcuts for detecting from a reader:

mimetype.DetectReader(io.Reader) (*MIME, error)

or from a file:

mimetype.DetectFile(string) (*MIME, error)

package main

import (
	"fmt"
	"io/ioutil"
	"os"

	"github.com/gabriel-vasile/mimetype"
)

func main() {
	file := "testdata/pdf.pdf"
	reader, _ := os.Open(file)       // ignoring error for brevity's sake
	data, _ := ioutil.ReadFile(file) // ignoring error for brevity's sake

	dmime := mimetype.Detect(data)
	rmime, rerr := mimetype.DetectReader(reader)
	fmime, ferr := mimetype.DetectFile(file)

	fmt.Println(dmime, rmime, fmime)
	fmt.Println(rerr, ferr)

}

Output:
application/pdf application/pdf application/pdf
<nil> <nil>

Example (Parent)

To check if some bytes/reader/file has a base MIME type, first perform a detect on the input and then navigate the parents until the base MIME type is found.

Considering JAR files are just ZIPs containing some metadata files, if, for example, you need to tell if the input can be unzipped, go up the hierarchy until zip is found or the root is reached.

package main

import (
	"fmt"

	"github.com/gabriel-vasile/mimetype"
)

func main() {
	detectedMIME, err := mimetype.DetectFile("testdata/jar.jar")

	zip := false
	for mime := detectedMIME; mime != nil; mime = mime.Parent() {
		if mime.Is("application/zip") {
			zip = true
		}
	}

	// zip is true, even if the detected MIME was application/jar.
	fmt.Println(zip, detectedMIME, err)

}

Output:
true application/jar <nil>

Example (TextVsBinary)

Considering the definition of a binary file as "a computer file that is not a text file", they can differentiated by searching for the text/plain MIME in it's MIME hierarchy.

package main

import (
	"fmt"

	"github.com/gabriel-vasile/mimetype"
)

func main() {
	detectedMIME, err := mimetype.DetectFile("testdata/xml.xml")

	isBinary := true
	for mime := detectedMIME; mime != nil; mime = mime.Parent() {
		if mime.Is("text/plain") {
			isBinary = false
		}
	}

	fmt.Println(isBinary, detectedMIME, err)

}

Output:
false text/xml; charset=utf-8 <nil>

Index

• type MIME
  • func Detect(in []byte) (mime *MIME)
  • func DetectFile(file string) (mime *MIME, err error)
  • func DetectReader(r io.Reader) (mime *MIME, err error)
  • func (n *MIME) Extension() string
  • func (n *MIME) Is(expectedMIME string) bool
  • func (n *MIME) Parent() *MIME
  • func (n *MIME) String() string

Examples

• Package (Check)
• Package (Detect)
• Package (Parent)
• Package (TextVsBinary)
• Detect
• DetectFile
• DetectReader
• MIME.Is

Types

type MIME

type MIME struct {
	// contains filtered or unexported fields
}

MIME represents a file format in the tree structure of formats.

func Detect

func Detect(in []byte) (mime *MIME)

Detect returns the MIME type found from the provided byte slice.

Failure to identify the format results in application/octet-stream being returned.

Example

package main

import (
	"fmt"
	"io/ioutil"

	"github.com/gabriel-vasile/mimetype"
)

func main() {
	data, err := ioutil.ReadFile("testdata/zip.zip")
	mime := mimetype.Detect(data)

	fmt.Println(mime, err)

}

Output:
application/zip <nil>

func DetectFile

func DetectFile(file string) (mime *MIME, err error)

DetectFile returns the MIME type of the provided file.

The result is always a valid MIME type, with application/octet-stream returned when identification failed with or without an error. Any error returned is related to the opening and reading from the input file.

Example

package main

import (
	"fmt"

	"github.com/gabriel-vasile/mimetype"
)

func main() {
	mime, err := mimetype.DetectFile("testdata/zip.zip")

	fmt.Println(mime, err)

}

Output:
application/zip <nil>

func DetectReader

func DetectReader(r io.Reader) (mime *MIME, err error)

DetectReader returns the MIME type of the provided reader.

The result is always a valid MIME type, with application/octet-stream returned when identification failed with or without an error. Any error returned is related to the reading from the input reader.

DetectReader assumes the reader offset is at the start. If the input is a ReadSeeker you read from before, it should be rewinded before detection:

reader.Seek(0, io.SeekStart)

Example

package main

import (
	"fmt"
	"os"

	"github.com/gabriel-vasile/mimetype"
)

func main() {
	data, oerr := os.Open("testdata/zip.zip")
	mime, merr := mimetype.DetectReader(data)

	fmt.Println(mime, oerr, merr)

}

Output:
application/zip <nil> <nil>

func (*MIME) Extension

func (n *MIME) Extension() string

Extension returns the file extension associated with the MIME type. It includes the leading dot, as in ".html". When the file format does not have an extension, the empty string is returned.

func (*MIME) Is

func (n *MIME) Is(expectedMIME string) bool

Is checks whether this MIME type, or any of its aliases, is equal to the expected MIME type. MIME type equality test is done on the "type/subtype" sections, ignores any optional MIME parameters, ignores any leading and trailing whitespace, and is case insensitive.

Example

package main

import (
	"fmt"

	"github.com/gabriel-vasile/mimetype"
)

func main() {
	mime, err := mimetype.DetectFile("testdata/pdf.pdf")

	pdf := mime.Is("application/pdf")
	xpdf := mime.Is("application/x-pdf")
	txt := mime.Is("text/plain")
	fmt.Println(pdf, xpdf, txt, err)

}

Output:
true true false <nil>

func (*MIME) Parent

func (n *MIME) Parent() *MIME

Parent returns the parent MIME type from the tree structure. Each MIME type has a non-nil parent, except for the root MIME type.

func (*MIME) String

func (n *MIME) String() string

String returns the string representation of the MIME type, e.g., "application/zip".