From 03bdb8627382f43268781b14c44836998401488c Mon Sep 17 00:00:00 2001 From: Oleg Broslavsky Date: Tue, 27 Aug 2019 17:01:44 +0700 Subject: [PATCH 1/2] Update README.md. Add package doc. Fix examples a bit --- README.md | 180 ++++++++++++++++++------------------- examples/file_info/main.go | 4 +- version_info.go | 13 ++- 3 files changed, 100 insertions(+), 97 deletions(-) diff --git a/README.md b/README.md index 92fa04d..2e039b0 100644 --- a/README.md +++ b/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 ") - } - 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 ", 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. \ No newline at end of file diff --git a/examples/file_info/main.go b/examples/file_info/main.go index 7bfb3bc..8b0a1ca 100644 --- a/examples/file_info/main.go +++ b/examples/file_info/main.go @@ -10,7 +10,7 @@ import ( func main() { if len(os.Args) < 2 { - log.Fatal("Usage: ./file_info.exe ") + log.Fatalf("Usage: %s ", 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)) } diff --git a/version_info.go b/version_info.go index 9b5c934..b3d08c8 100644 --- a/version_info.go +++ b/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 From d6a9b16a62f9ec33c76002d8b52a43b3282214a6 Mon Sep 17 00:00:00 2001 From: Oleg Broslavsky Date: Tue, 27 Aug 2019 17:25:54 +0700 Subject: [PATCH 2/2] Create LICENSE --- LICENSE | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..5622e84 --- /dev/null +++ b/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.