Merge 748f327 into 67af572

EXAMPLES.md

@@ -1,10 +1,10 @@
 ## Examples
- - [Detect MIME type](#detect)
- - [Check against MIME type](#check)
+ - [Detect MIME type](#detect-mime-type)
+ - [Check against a MIME type](#check-against-a-mime-type)
  - [Parent](#parent)
  - [Binary file vs text file](#binary-file-vs-text-file)
 
-### Detect
+### Detect MIME type [<kbd>playground</kbd>](http://play.golang.org/p/rhRN3RdQyd)
 Get the MIME type from a path to a file.
 ```go
 file := "testdata/pdf.pdf"
@@ -28,18 +28,23 @@ fmt.Println(mime.String(), mime.Extension())
 // Output: application/pdf .pdf
 ```
 
-### Check
-Test if a file has a specific MIME type. Also accepts MIME type aliases.
+### Check against a MIME type [<kbd>playground</kbd>](http://play.golang.org/p/rhRN3RdQyd)
+Test if a file has a specific MIME type. Different from the string comparison,
+e.g.: `mime.String() == "application/zip"`, `mime.Is("application/zip")` method
+has the following advantages:
+ - handles MIME aliases,
+ - is case insensitive,
+ - ignores optional MIME parameters,
+ - ignores any leading and trailing whitespace.
 ```go
 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>
 ```
 
-### Parent
+### Parent [<kbd>playground</kbd>](http://play.golang.org/p/rhRN3RdQyd)
 Upon detection, it may happen that the returned MIME type is more accurate than
 needed.
 
@@ -65,11 +70,10 @@ for mime := detectedMIME; mime != nil; mime = mime.Parent() {
 
 // isText is true, even if the detected MIME was text/html.
 fmt.Println(isText, detectedMIME, err)
-
 // Output: true text/html <nil>
 ```
 
-### Binary file vs text file
+### Binary file vs text file [<kbd>playground</kbd>](http://play.golang.org/p/rhRN3RdQyd)
 Considering the definition of a binary file as "a computer file that is not
 a text file", they can be differentiated by searching for the `text/plain` MIME
 in it's MIME hierarchy.
@@ -84,6 +88,5 @@ for mime := detectedMIME; mime != nil; mime = mime.Parent() {
 }
 
 fmt.Println(isBinary, detectedMIME, err)
-
 // Output: false text/xml; charset=utf-8 <nil>
 ```

README.md

@@ -36,17 +36,6 @@ go get github.com/gabriel-vasile/mimetype
 There are quick [examples](EXAMPLES.md) and
 [GoDoc](https://godoc.org/github.com/gabriel-vasile/mimetype) 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](https://godoc.org/github.com/gabriel-vasile/mimetype#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](supported_mimes.md) for the list of detected MIME types.
 If support is needed for a specific file format, please open an [issue](https://github.com/gabriel-vasile/mimetype/issues/new/choose).

example_mimetype_test.go

@@ -40,7 +40,11 @@ func Example_detect() {
 // 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.
+// Different from the string comparison,
+// e.g.: mime.String() == "application/zip", mime.Is("application/zip") method
+// has the following advantages: it handles MIME aliases, is case insensitive,
+// ignores optional MIME parameters, and ignores any leading and trailing
+// whitespace.
 func Example_check() {
 	mime, err := mimetype.DetectFile("testdata/zip.zip")
 	// application/x-zip is an alias of application/zip,

mime.go

@@ -4,9 +4,6 @@ import "mime"
 
 // MIME struct holds information about a file format: the string representation
 // of the MIME type, the extension and the parent file format.
-//
-// This struct should not be instantiated by clients. It is exposed purely for
-// documentation purposes.
 type MIME struct {
 	mime      string
 	aliases   []string

mimetype.go

@@ -56,7 +56,7 @@ func DetectReader(r io.Reader) (mime *MIME, err error) {
 // Any error returned is related to the opening and reading from the input file.
 //
 // To prevent loading entire files into memory, DetectFile reads at most
-// matchers.ReadLimit bytes from the reader.
+// matchers.ReadLimit bytes from the input file.
 func DetectFile(file string) (mime *MIME, err error) {
 	f, err := os.Open(file)
 	if err != nil {