Skip to content

Commit

Permalink
Update README.md. Add package doc. Fix examples a bit
Browse files Browse the repository at this point in the history
  • Loading branch information
@yalegko
yalegko committed Aug 27, 2019
1 parent 8535cf6 commit 03bdb86
Show file tree
Hide file tree
Showing 3 changed files with 100 additions and 97 deletions.
180 changes: 86 additions & 94 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
4 changes: 2 additions & 2 deletions examples/file_info/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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))
}
13 changes: 12 additions & 1 deletion version_info.go
View file
Original file line number Diff line number Diff line change
@@ -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 (
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 03bdb86

Please sign in to comment.