Merge pull request #2 from bi-zone/fix_readme

Update README.md. Add package doc. Fix examples a bit

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 BI.ZONE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,94 +1,86 @@
-# go-fileversion
-
-[![GoDoc](https://godoc.org/github.com/bi-zone/go-fileversion?status.svg)](https://godoc.org/github.com/bi-zone/go-fileversion/)
-
-Package `fileversion` provides wrapper for windows version-information resource.
-
-Using the package you can extract the following info:
-
-![](https://github.com/bi-zone/go-fileversion/assets/explorer_properties.png)
-
-
-
-## Examples
-
-Print version info from input file
-```golang
-package main
-
-import (
-	"fmt"
-	"log"
-	"os"
-
-	"github.com/bi-zone/go-fileversion"
-)
-
-func main() {
-	if len(os.Args) < 2 {
-		log.Fatal("Usage: ./file_info.exe <image-path>")
-	}
-	f, err := fileversion.New(os.Args[1])
-	if err != nil {
-		log.Fatal(err)
-	}
-	fmt.Println("CompanyName:", f.CompanyName())
-	fmt.Println("FileDescription:", f.FileDescription())
-	fmt.Println("FileVersion:", f.FileVersion())
-	fmt.Println("InternalName:", f.InternalName())
-	fmt.Println("LegalCopyright:", f.LegalCopyright())
-	fmt.Println("OriginalFilename:", f.OriginalFilename())
-	fmt.Println("ProductName:", f.ProductName())
-	fmt.Println("ProductVersion:", f.ProductVersion())
-	fmt.Println("Comments:", f.Comments())
-	fmt.Println("FileVeLegalTrademarksrsion:", f.FileVeLegalTrademarksrsion())
-	fmt.Println("PrivateBuild:", f.PrivateBuild())
-	fmt.Println("SpecialBuild:", f.SpecialBuild())
-
-	fmt.Printf("\n%+#v\n", f.FixedInfo())
-
-	fmt.Printf("%+#v\n", f.Locales)
-}
-```
-
-You can choose the locale for getting property.
-
-Choose locale from object:
-
-```golang
-f, err := fileversion.New(os.Args[1])
-if err != nil {
-    log.Fatal(err)
-}
-if len(f.Locales) > 1 {
-    fmt.Println(f.GetPropertyWithLocale("PropertyName", f.Locales[len(f.Locales) - 1]))
-}
-```
-
-Also you can get property with owen-defined locale:
-```golang
-f, err := fileversion.New(os.Args[1])
-if err != nil {
-    log.Fatal(err)
-}
-germanLocale := fileversion.Locale{
-		LangID: 0x0407,
-		CharsetID: fileversion.CSUnicode,
-	}
-fmt.Println(f.GetPropertyWithLocale("PropertyName", germanLocale))
-```
-But we don't recommend to do this :) If object doesn't have locale, 
-you will get an error.
-
- `f.GetProperty` method tries to get property with different locales given 
- windows features.
-The idea of locales handling was copied from 
-[.NET Framework 4.8](https://referencesource.microsoft.com/#System/services/monitoring/system/diagnosticts/FileVersionInfo.cs,036c54a4aa10d39f,references)
-
-```golang
-f, err := fileversion.New(os.Args[1])
-if err != nil {
-    log.Fatal(err)
-}
-f.GetProperty("PropertyName")
-```
+# go-fileversion
+
+[![GoDoc](https://godoc.org/github.com/bi-zone/go-fileversion?status.svg)](https://godoc.org/github.com/bi-zone/go-fileversion/)
+[![Go Report Card](https://goreportcard.com/badge/github.com/bi-zone/wmi)](https://goreportcard.com/report/github.com/bi-zone/go-fileversion)
+
+Package `fileversion` provides wrapper for querying properties from windows version-information resource.
+
+Using the package you can extract the following info:
+
+![properties example](./assets/explorer_properties.png)
+
+If you are looking how to add this info to your go binary - look at [josephspurrier/goversioninfo](https://github.com/josephspurrier/goversioninfo).
+
+## Examples
+
+Print version info from input file
+```golang
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/bi-zone/go-fileversion"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		log.Fatalf("Usage: %s <image-path>", os.Args[0])
+	}
+	f, err := fileversion.New(os.Args[1])
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println("ProductName:", f.ProductName())
+	fmt.Println("LegalCopyright:", f.LegalCopyright())
+	fmt.Println("Version:", f.FixedInfo().FileVersion)
+}
+```
+
+All string properties in file version-information resource by-design has multiple translations. 
+`go-fileversion` allows you to query that translations in a 2 ways. 
+
+You can create an `Info` object with "preferred" locale:
+
+```golang
+germanLocale := fileversion.Locale{
+    LangID: 0x0407, // langID German
+    CharsetID: fileversion.CSUnicode,
+}
+f, err := fileversion.NewWithLocale(os.Args[1], germanLocale)
+if err != nil {
+    log.Fatal(err)
+}
+fmt.Println("ProductName:", f.ProductName())
+```
+
+Here "German-Unicode" locale will be used to query string properties (like `ProductName`), 
+**but if the german translation will be missing - `go-fileversion` would try to fetch a 
+property with default translation**. (The idea of locales handling was copied from 
+[.NET Framework 4.8](https://referencesource.microsoft.com/#System/services/monitoring/system/diagnosticts/FileVersionInfo.cs,036c54a4aa10d39f,references))
+
+The only way to get necessary translation without any heuristics is to use `GetPropertyWithLocale` manualy:
+```golang
+f, err := fileversion.New(os.Args[1])
+if err != nil {
+    log.Fatal(err)
+}
+germanLocale := fileversion.Locale{
+    LangID: 0x0407, // langID German
+    CharsetID: fileversion.CSUnicode,
+}
+fmt.Println(f.GetPropertyWithLocale("ProductName", germanLocale))
+```
+
+## Versioning
+
+Project uses [semantic versioning](http://semver.org) for version numbers, which
+is similar to the version contract of the Go language. Which means that the major
+version will always maintain backwards compatibility with minor versions. Minor 
+versions will only add new additions and changes. Fixes will always be in patch. 
+
+This contract should allow you to upgrade to new minor and patch versions without
+breakage or modifications to your existing code. Leave a ticket, if there is breakage,
+so that it could be fixed.

examples/file_info/main.go

@@ -10,7 +10,7 @@ import (
 
 func main() {
 	if len(os.Args) < 2 {
-		log.Fatal("Usage: ./file_info.exe <image-path>")
+		log.Fatalf("Usage: %s <image-path>", os.Args[0])
 	}
 	f, err := fileversion.New(os.Args[1])
 	if err != nil {
@@ -41,5 +41,5 @@ func main() {
 		LangID:    0x0407, // langID German
 		CharsetID: fileversion.CSUnicode,
 	}
-	fmt.Println(f.GetPropertyWithLocale("PropertyName", germanLocale))
+	fmt.Println(f.GetPropertyWithLocale("ProductName", germanLocale))
 }

version_info.go

@@ -1,3 +1,14 @@
+// Package fileversion provides wrapper for querying properties from windows
+// version-information resource.
+//
+// fileversion API is aimed to the easiest way of getting file properties so
+// it ignore most of errors querying properties. We suppose most of the time
+// it will be used as "create with New and just access properties". If you
+// need some guaranties - access the properties manually using GetProperty and
+// GetPropertyWithLocale.
+//
+// For more info about version-information resource look at
+// https://docs.microsoft.com/en-us/windows/win32/menurc/versioninfo-resource
 package fileversion
 
 import (
@@ -42,7 +53,7 @@ type FixedFileInfo struct {
 // https://docs.microsoft.com/en-us/windows/win32/menurc/versioninfo-resource
 type LangID uint16
 
-// CharsetId is character-set identifier. Could be one of the codes listed in
+// CharsetID is character-set identifier. Could be one of the codes listed in
 // `charsetID` section of
 // https://docs.microsoft.com/en-us/windows/win32/menurc/versioninfo-resource
 type CharsetID uint16