gap

README

go-app-paths

Lets you retrieve platform-specific paths (like directories for app-data, cache, config, and logs). It is fully compliant with 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

Usage

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

Scopes

You can initialize gap with either the gap.User or gap.System scope to retrieve user- and/or system-specific base directories and paths:

scope := gap.NewScope(gap.User, "app")

Alternatively, you can initialize gap with an additional vendor name:

scope := gap.NewVendorScope(gap.User, "vendor", "app")

This will cause the app directory to be prefixed by a vendor directory in all the following tables.

Directories

DataDirs retrieves a priority-sorted list of data directories:

dirs, err := scope.DataDirs()

Platform	User Scope	System Scope
Unix	["~/.local/share/app", "/usr/local/share/app", "/usr/share/app"]	["/usr/local/share/app", "/usr/share/app"]
macOS	["~/Library/Application Support/app"]	["/Library/Application Support/app"]
Windows	["%LOCALAPPDATA%/app"]	["%PROGRAMDATA%/app"]

---

ConfigDirs retrieves a priority-sorted list of config directories:

dirs, err := scope.ConfigDirs()

Platform	User Scope	System Scope
Unix	["~/.config/app", "/etc/xdg/app", "/etc/app"]	["/etc/xdg/app", "/etc/app"]
macOS	["~/Library/Preferences/app"]	["/Library/Preferences/app"]
Windows	["%LOCALAPPDATA%/app/Config"]	["%PROGRAMDATA%/app/Config"]

---

CacheDir retrieves the app's cache directory:

dir, err := scope.CacheDir()

Platform	User Scope	System Scope
Unix	~/.cache/app	/var/cache/app
macOS	~/Library/Caches/app	/Library/Caches/app
Windows	%LOCALAPPDATA%/app/Cache	%PROGRAMDATA%/app/Cache

Default File Paths

DataPath retrieves the default path for a data file:

path, err := scope.DataPath("filename")

Platform	User Scope	System Scope
Unix	~/.local/share/app/filename	/usr/local/share/app/filename
macOS	~/Library/Application Support/app/filename	/Library/Application Support/app/filename
Windows	%LOCALAPPDATA%/app/filename	%PROGRAMDATA%/app/filename

---

ConfigPath retrieves the default path for a config file:

path, err := scope.ConfigPath("filename.conf")

Platform	User Scope	System Scope
Unix	~/.config/app/filename.conf	/etc/xdg/app/filename.conf
macOS	~/Library/Preferences/app/filename.conf	/Library/Preferences/app/filename.conf
Windows	%LOCALAPPDATA%/app/Config/filename.conf	%PROGRAMDATA%/app/Config/filename.conf

---

LogPath retrieves the default path for a log file:

path, err := scope.LogPath("filename.log")

Platform	User Scope	System Scope
Unix	~/.local/share/app/filename.log	/var/log/app/filename.log
macOS	~/Library/Logs/app/filename.log	/Library/Logs/app/filename.log
Windows	%LOCALAPPDATA%/app/Logs/filename.log	%PROGRAMDATA%/app/Logs/filename.log

Lookup Methods

LookupData retrieves a priority-sorted list of paths for existing data files with the name filename:

path, err := scope.LookupData("filename")

Platform	User Scope	System Scope
Unix	["~/.local/share/app/filename", "/usr/local/share/app/filename", "/usr/share/app/filename"]	["/usr/local/share/app/filename", "/usr/share/app/filename"]
macOS	["~/Library/Application Support/app/filename"]	["/Library/Application Support/app/filename"]
Windows	["%LOCALAPPDATA%/app/filename"]	["%PROGRAMDATA%/app/filename"]

---

LookupConfig retrieves a priority-sorted list of paths for existing config files with the name filename.conf:

path, err := scope.LookupConfig("filename.conf")

Platform	User Scope	System Scope
Unix	["~/.config/app/filename.conf", "/etc/xdg/app/filename.conf", "/etc/app/filename.conf"]	["/etc/xdg/app/filename.conf", "/etc/app/filename.conf"]
macOS	["~/Library/Preferences/app/filename.conf"]	["/Library/Preferences/app/filename.conf"]
Windows	["%LOCALAPPDATA%/app/Config/filename.conf"]	["%PROGRAMDATA%/app/Config/filename.conf"]

Documentation

Index

• Variables
• type Scope
  • func NewCustomHomeScope(path, vendor, app string) *Scope
  • func NewScope(t ScopeType, app string) *Scope
  • func NewVendorScope(t ScopeType, vendor, app string) *Scope
  • func (s *Scope) CacheDir() (string, error)
  • func (s *Scope) ConfigDirs() ([]string, error)
  • func (s *Scope) ConfigPath(filename string) (string, error)
  • func (s *Scope) DataDirs() ([]string, error)
  • func (s *Scope) DataPath(filename string) (string, error)
  • func (s *Scope) LogPath(filename string) (string, error)
  • func (s *Scope) LookupConfig(filename string) ([]string, error)
  • func (s *Scope) LookupDataFile(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, app string) *Scope

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

func NewVendorScope

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

NewVendorScope returns a new Scope with vendor information 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 default cache dir.

func (*Scope) ConfigDirs

func (s *Scope) ConfigDirs() ([]string, error)

ConfigDirs returns a priority-sorted slice of all of the application's config dirs.

func (*Scope) ConfigPath

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

ConfigPath returns the full path to a file in the application's default config directory.

func (*Scope) DataDirs

func (s *Scope) DataDirs() ([]string, error)

DataDirs returns a priority-sorted slice of all the application's data dirs.

func (*Scope) DataPath

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

DataPath returns the full path to a file in the application's default data directory.

func (*Scope) LogPath

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

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

func (*Scope) LookupConfig

func (s *Scope) LookupConfig(filename string) ([]string, error)

LookupConfig returns all existing configs with this filename.

func (*Scope) LookupDataFile

func (s *Scope) LookupDataFile(filename string) ([]string, error)

LookupDataFile returns all existing data files with this filename.

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
)