gap

README

go-app-paths

Lets you retrieve platform-specific paths (like directories for app-data, cache, config, and logs). Follows the XDG Base Directory Specification on Unix, but also provides implementations for macOS and Windows systems.

Installation

Make sure you have a working Go environment (Go 1.2 or higher is required). See the install instructions.

To install go-app-paths, simply run:

go get github.com/muesli/go-app-paths

To compile it from source:

cd $GOPATH/src/github.com/muesli/go-app-paths
go get -u -v
go build && go test -v

Platform Support

Unix	User Scope	System Scope
Data Dir	${XDG_DATA_HOME}/appname	/usr/share/appname
Cache Dir	${XDG_CACHE_HOME}/appname	/var/cache/appname
Config Path	${XDG_CONFIG_HOME}/appname/filename	/etc/appname/filename
Log Path	${XDG_DATA_HOME}/appname/filename	/var/log/appname/filename

macOS	User Scope	System Scope
Data Dir	~/Library/Application Support/appname	/Library/Application Support/appname
Cache Dir	~/Library/Caches/appname	/Library/Caches/appname
Config Path	~/Library/Preferences/appname/filename	/Library/Preferences/appname/filename
Log Path	~/Library/Logs/appname/filename	/Library/Logs/appname/filename

Windows	User Scope	System Scope
Data Dir	%LOCALAPPDATA%/appname	%PROGRAMDATA%/appname
Cache Dir	%LOCALAPPDATA%/appname/Cache	%PROGRAMDATA%/appname/Cache
Config Path	%LOCALAPPDATA%/appname/Config/filename	%PROGRAMDATA%/appname/Config/filename
Log Path	%LOCALAPPDATA%/appname/Logs/filename	%PROGRAMDATA%/appname/Logs/filename

Example

package main

import (
	gap "github.com/muesli/go-app-paths"
)

func main() {
	userScope := gap.NewScope(gap.User, "vendorname", "appname")
	userScope.DataDir()                   // => ~/.local/share/appname
	userScope.CacheDir()                  // => ~/.cache/appname
	userScope.ConfigPath("filename.conf") // => ~/.config/appname/filename.conf
	userScope.LogPath("filename.log")     // => ~/.local/share/appname/filename.log

	systemScope := gap.NewScope(gap.System, "vendorname", "appname")
	systemScope.DataDir()                   // => /usr/share/appname
	systemScope.CacheDir()                  // => /var/cache/appname
	systemScope.ConfigPath("filename.conf") // => /etc/appname/filename.conf
	systemScope.LogPath("filename.log")     // => /var/log/appname/filename.log
}

Documentation

Index

• Variables
• type Scope
  • func NewCustomHomeScope(path, vendor, app string) *Scope
  • func NewScope(t ScopeType, vendor, app string) *Scope
  • func (s *Scope) CacheDir() (string, error)
  • func (s *Scope) ConfigPath(filename string) (string, error)
  • func (s *Scope) DataDir() (string, error)
  • func (s *Scope) LogPath(filename string) (string, error)
• type ScopeType

Variables

var (
	// ErrInvalidScope gets returned when an invalid scope type has been set.
	ErrInvalidScope = errors.New("Invalid scope type")
	// ErrRetrievingPath gets returned when the path could not be resolved.
	ErrRetrievingPath = errors.New("Could not retrieve path")
)

Types

type Scope

type Scope struct {
	Type       ScopeType
	CustomHome string
	Vendor     string
	App        string
}

Scope holds scope & app-specific information.

func NewCustomHomeScope

func NewCustomHomeScope(path, vendor, app string) *Scope

NewCustomHomeScope returns a new Scope that lets you operate on a custom path prefix.

func NewScope

func NewScope(t ScopeType, vendor, app string) *Scope

NewScope returns a new Scope that lets you query app- & platform-specific paths.

func (*Scope) CacheDir

func (s *Scope) CacheDir() (string, error)

CacheDir returns the full path to the application's cache dir.

func (*Scope) ConfigPath

func (s *Scope) ConfigPath(filename string) (string, error)

ConfigPath returns the full path to the application's config file.

func (*Scope) DataDir

func (s *Scope) DataDir() (string, error)

DataDir returns the full path to the application's data dir.

func (*Scope) LogPath

func (s *Scope) LogPath(filename string) (string, error)

LogPath returns the full path to the application's log file.

type ScopeType

type ScopeType int

ScopeType specifies whether returned paths are user-specific or system-wide.

const (
	// System is the system-wide scope.
	System ScopeType = iota
	// User is the user-specific scope.
	User
	// CustomHome uses a custom user home as scope.
	CustomHome
)