userdirs

Documentation

Overview

Package userdirs is a utility for building user-specific filesystem paths for applications to store configuration information, caches, etc.

It aims to conform to the conventions of the operating system where it is running, allowing applications using this package to follow the relevant conventions automatically.

Because the behavior of this library must be tailored for each operating system it supports, it supports only a subset of Go's own supported operating system targets. Others are intentionally not supported (rather than mapped on to some default OS) to avoid the situation where adding a new supported OS would change the behavior of existing applications built for that OS.

Currently this package supports Mac OS X ("darwin"), Linux and Windows first-class. It also maps AIX, Dragonfly, FreeBSD, NetBSD, and Solaris, following the same rules as for Linux.

On Mac OS X, we follow the Standard Directories guidelines from https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW6 .

On Linux and other Unix-like systems, we follow the XDG Base Directory specification version 0.8, from https://specifications.freedesktop.org/basedir-spec/basedir-spec-0.8.html .

On Windows, we use the Known Folder API and follow relevant platform conventions https://docs.microsoft.com/en-us/windows/desktop/shell/knownfolderid .

On all other systems, the directory-construction functions will panic. Use the SupportedOS function to determine whether this function's packages are available on the current operating system target, to avoid those panics. However, in practice it probably doesn't make much sense to use this package when building for an unsupported operating system anyway.

Additional operating systems may be supported in future releases. Once an operating system is supported, the constructed paths are frozen to ensure that applications can find their same files on future versions. Therefore the bar for adding support for a new operating system is there being a committed standard published by the operating system vendor.

Index

• func SupportedOS() bool
• type Dirs
  • func ForApp(name string, vendor string, bundleID string) Dirs
  • func (d Dirs) CachePath(parts ...string) string
  • func (d Dirs) ConfigHome() string
  • func (d Dirs) ConfigSearchPaths(parts ...string) []string
  • func (d Dirs) DataHome() string
  • func (d Dirs) DataSearchPaths(parts ...string) []string
  • func (d Dirs) FindConfigFiles(parts ...string) []string
  • func (d Dirs) FindDataFiles(parts ...string) []string
  • func (d Dirs) GlobConfigFiles(parts ...string) []string
  • func (d Dirs) GlobDataFiles(parts ...string) []string
  • func (d Dirs) NewConfigPath(parts ...string) string
  • func (d Dirs) NewDataPath(parts ...string) string

Functions

func SupportedOS

func SupportedOS() bool

SupportedOS returns true if the current operating system is supported by this package. If this function returns false, any call to ForApp will panic.

Types

type Dirs

type Dirs struct {
	// ConfigDirs is a list, in preference order, of directory paths to search
	// for configuration files.
	//
	// The list must always contain at least one element, and its first element
	// is the directory where any new configuration files should be written.
	//
	// On some systems, ConfigDirs and DataDirs may overlap, so applications
	// which scan the contents of the configuration directories should impose
	// some additional filtering to distinguish configuration files from data
	// files.
	//
	// Files placed in ConfigDirs should ideally be things that it would be
	// reasonable to share among multiple systems (possibly on different
	// platforms, possibly to check into a version control system, etc.
	ConfigDirs []string

	// DataDirs is a list, in preference order, of directory paths to search for
	// data files.
	//
	// The list must always contain at least one element, and its first element
	// is the directory where any new data files should be written.
	//
	// On some systems, ConfigDirs and DataDirs may overlap, so applications
	// which scan the contents of the data directories should impose some
	// additional filtering to distinguish data files from configuration files.
	DataDirs []string

	// CacheDir is the path of a single directory that can be used for temporary
	// cache data.
	//
	// The cache is suitable only for data that the calling application could
	// recreate if lost. Any file or directory under this prefix may be deleted
	// at any time by other software.
	//
	// This directory may, on some systems, match one of the directories
	// returned in ConfigDirs and/or DataDirs. For this reason applications
	// must ensure that they do not misinterpret config and data files as
	// cache files, and in particular should not naively purge a cache by
	// emptying this directory.
	CacheDir string
}

Dirs represents a set of directory paths with different purposes.

func ForApp

func ForApp(name string, vendor string, bundleID string) Dirs

ForApp returns a set of user-specific directories for a particular application.

The three arguments are used in different ways depending on the current host operating system, because each OS has different conventions.

• On Windows, the vendor and string are used to construct a two-level heirarchy, vendor/name, under each namespaced directory prefix. The bundleID is ignored.
• On Linux and other similar Unix systems, the name is converted to lowercase and any spaces changed to dashes and used as a subdirectory name. The vendor and bundleID are ignored.
• On Mac OS X, the bundleID is used and the name and vendor are ignored.

For best results, the name and vendor arguments should contain space-separated words using title case, like "Image Editor" and "Contoso", and the bundleID should be a reverse-DNS-style string, like "com.example.appname".

func (Dirs) CachePath

func (d Dirs) CachePath(parts ...string) string

CachePath joins the given path segments to the CacheHome to produce a path for a cache file or directory.

func (Dirs) ConfigHome

func (d Dirs) ConfigHome() string

ConfigHome returns the path for the directory where any new configuration files should be written.

func (Dirs) ConfigSearchPaths

func (d Dirs) ConfigSearchPaths(parts ...string) []string

ConfigSearchPaths joins the given path segments to each of the directories in in ConfigDirs to produce a more specific set of paths to be searched in preference order.

func (Dirs) DataHome

func (d Dirs) DataHome() string

DataHome returns the path for the directory where any new configuration files should be written.

func (Dirs) DataSearchPaths

func (d Dirs) DataSearchPaths(parts ...string) []string

DataSearchPaths joins the given path segments to each of the directories in in ConfigDirs to produce a more specific set of paths to be searched in preference order.

func (Dirs) FindConfigFiles

func (d Dirs) FindConfigFiles(parts ...string) []string

FindConfigFiles scans over all of the paths in ConfigDirs and tests whether a file of the given name is present in each, returning a slice of full paths that matched.

func (Dirs) FindDataFiles

func (d Dirs) FindDataFiles(parts ...string) []string

FindDataFiles scans over all of the paths in ConfigDirs and tests whether a file of the given name is present in each, returning a slice of full paths that matched.

func (Dirs) GlobConfigFiles

func (d Dirs) GlobConfigFiles(parts ...string) []string

GlobConfigFiles joins the given parts to create a glob pattern and then applies it relative to each of the paths in ConfigDirs, returning all of the matches in a single slice.

The order of the result preserves the directory preference order and sorts multiple files within the same directory lexicographically.

Remember that on some platforms the config dirs and data dirs overlap, so to be robust you should use distinct naming patterns for configuration and data files to avoid accidentally matching data files with this method.

func (Dirs) GlobDataFiles

func (d Dirs) GlobDataFiles(parts ...string) []string

GlobDataFiles joins the given parts to create a glob pattern and then applies it relative to each of the paths in DataDirs, returning all of the matches in a single slice.

The order of the result preserves the directory preference order and sorts multiple files within the same directory lexicographically.

Remember that on some platforms the config dirs and data dirs overlap, so to be robust you should use distinct naming patterns for configuration and data files to avoid accidentally matching configuration files with this method.

func (Dirs) NewConfigPath

func (d Dirs) NewConfigPath(parts ...string) string

NewConfigPath joins the given path segments to the ConfigHome to produce a path where a new configuration file might be written.

func (Dirs) NewDataPath

func (d Dirs) NewDataPath(parts ...string) string

NewDataPath joins the given path segments to the DataHome to produce a path where a new data file might be written.