xdg

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 4, 2020 License: MIT Imports: 5 Imported by: 3

README

goulash/xdg

GoDoc

Package xdg provides an implementation of the XDG Base Directory Specification.

On initialization, the following package variables are set to their recommended values, by reading the corresponding environment variables and falling back to specification defaults if necessary.

ConfigHome      // user configuration base directory, e.g. ~/.config
DataHome        // user data files base directory, e.g. ~/.local/share
CacheHome       // user cache files base directory, e.g. ~/.cache
RuntimeDir      // user runtime files base directory, e.g. /run/user/1000
ConfigDirs      // global configuration directories, e.g. /etc/xdg
DataDirs        // global data files directories, e.g. /usr/local/share
AllConfigDirs   // user and global configuration directories
AllDataDirs     // user and global data directories

Initialization happens automatically, but can also be explicitely started with the Init function. If no valid path can be constructed, the variable is left blank or empty. If one of the required paths is blank or empty, the program should fail. These variables should be treated as read-only; change them only if you know what you are doing.

The package has four classes of functions, which should suffice for most needs:

User*           // construct a valid path for user (config|data|...) files
Find*           // find existing (config|data|...) files
Merge*          // execute a function on each found (config|data) file
Open*           // open or create a user (config|data|...) file

Only the Open* functions may alter the filesystem in any way: this is restricted to creating XDG user base directories and files therein. Directories in ConfigDirs and DataDirs are not modified.

The XDG Base Directory Specification, henceforth “the specification”, defines several types of files: configuration, data, cache, and runtime files. The specification can be found at:

http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

Configuration files

Configuration files are read from ConfigHome and from ConfigDirs; they are only written in ConfigHome.

ConfigHome is a single base directory relative to which user-specific data files should be written. This directory is defined by the environment variable $XDG_DATA_HOME. If $XDG_CONFIG_HOME is not set, the default $HOME/.config is used.

ConfigDirs is a set of preference ordered base directories relative to which configuration files should be searched. This set of directories is defined by the environment variable $XDG_CONFIG_DIRS. The directories in $XDG_CONFIG_DIRS should be seperated with a colon :. If $XDG_CONFIG_DIRS is not set, the default /etc/xdg is used.

ConfigHomeDirs combines ConfigHome and ConfigDirs into one preference ordered set of directories.

Data files

Data files are read from DataHome and from DataDirs; they are only written in DataHome.

DataHome is a single base directory relative to which user-specific data files should be written. This directory is defined by the environment variable $XDG_DATA_HOME. If $XDG_DATA_HOME is not set, the default $HOME/.local/share is used.

DataDirs is a set of preference ordered base directories relative to which data files should be searched. This set of directories is defined by the environment variable $XDG_DATA_DIRS. If $XDG_CONFIG_DIRS is not set, the default /usr/local/share:/usr/share is used.

Cache files

CacheHome is a single base directory relative to which user-specific non-essential (cached) data should be written. This directory is defined by the environment variable $XDG_CACHE_HOME. If $XDG_CACHE_HOME is not set, the default $HOME/.cache is used.

Runtime files

RuntimeDir is a single base directory relative to which user-specific runtime files and other file objects should be placed. This directory is defined by the environment variable $XDG_RUNTIME_DIR. If $XDG_RUNTIME_DIR is not set, the following method is used to find an appropriate directory:

path.Join(os.TempDir(), fmt.Sprintf("xdg-%d", os.Getuid()))

This usually results in paths such as /tmp/xdg-1000. Normally, we expect something along the lines of /run/user/1000.

In this implementation, we assume that the system takes care of removing the XDG runtime directory at shutdown.

For more information, see the documentation! :-) This package is licensed under the MIT license. This package takes much inspiration from adrg/xdg. Many Thanks.

Documentation

Overview

Package xdg provides an implementation of the XDG Base Directory Specification.

On initialization, the following package variables are set to their recommended values, by reading the corresponding environment variables and falling back to specification defaults if necessary. 

ConfigHome      // user configuration base directory, e.g. ~/.config
DataHome        // user data files base directory, e.g. ~/.local/share
CacheHome       // user cache files base directory, e.g. ~/.cache
RuntimeDir      // user runtime files base directory, e.g. /run/user/1000
ConfigDirs      // global configuration directories, e.g. /etc/xdg
DataDirs        // global data files directories, e.g. /usr/local/share
AllConfigDirs   // user and global configuration directories
AllDataDirs     // user and global data directories

Initialization happens automatically, but can also be explicitely started with the Init function. If no valid path can be constructed, the variable is left blank or empty. If one of the required paths is blank or empty, the program should fail. These variables should be treated as read-only; change them only if you know what you are doing.

The package has four classes of functions, which should suffice for most needs: 

User*           // construct a valid path for user (config|data|...) files
Find*           // find existing (config|data|...) files
Merge*          // execute a function on each found (config|data) file
Open*           // open or create a user (config|data|...) file

Only the Open* functions may alter the filesystem in any way: this is restricted to creating XDG user base directories and files therein. Directories in ConfigDirs and DataDirs are not modified.

The XDG Base Directory Specification, henceforth “the specification”, defines several types of files: configuration, data, cache, and runtime files. The specification can be found at: 

http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

Configuration files

Configuration files are read from ConfigHome and from ConfigDirs; they are only written in ConfigHome.

ConfigHome is a single base directory relative to which user-specific data files should be written. This directory is defined by the environment variable $XDG_DATA_HOME. If $XDG_CONFIG_HOME is not set, the default "$HOME/.config" is used.

ConfigDirs is a set of preference ordered base directories relative to which configuration files should be searched. This set of directories is defined by the environment variable $XDG_CONFIG_DIRS. The directories in $XDG_CONFIG_DIRS should be seperated with a colon ':'. If $XDG_CONFIG_DIRS is not set, the default "/etc/xdg" is used.

ConfigHomeDirs combines ConfigHome and ConfigDirs into one preference ordered set of directories.

Data files

Data files are read from DataHome and from DataDirs; they are only written in DataHome.

DataHome is a single base directory relative to which user-specific data files should be written. This directory is defined by the environment variable $XDG_DATA_HOME. If $XDG_DATA_HOME is not set, the default "$HOME/.local/share" is used.

DataDirs is a set of preference ordered base directories relative to which data files should be searched. This set of directories is defined by the environment variable $XDG_DATA_DIRS. If $XDG_CONFIG_DIRS is not set, the default "/usr/local/share:/usr/share" is used.

Cache files

CacheHome is a single base directory relative to which user-specific non-essential (cached) data should be written. This directory is defined by the environment variable $XDG_CACHE_HOME. If $XDG_CACHE_HOME is not set, the default "$HOME/.cache" is used.

Runtime files

RuntimeDir is a single base directory relative to which user-specific runtime files and other file objects should be placed. This directory is defined by the environment variable $XDG_RUNTIME_DIR. If $XDG_RUNTIME_DIR is not set, the following method is used to find an appropriate directory: 

path.Join(os.TempDir(), fmt.Sprintf("xdg-%d", os.Getuid()))

This usually results in paths such as "/tmp/xdg-1000". Normally, we expect something along the lines of "/run/user/1000".

In this implementation, we assume that the system takes care of removing the XDG runtime directory at shutdown.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Errors contains all errors that occurred during initialization.
	Errors []error

	// ErrInvalidHome is found in the Errors slice if the HOME environment variable
	// is not set or it is not an absolute path.
	ErrInvalidHome = errors.New("environment variable HOME is invalid or not set")

	// ErrInvalidPath is returned when attempting to create or open an invalid path.
	// This means that some XDG variable could not be correctly set.
	ErrInvalidPath = errors.New("invalid XDG path used")
)
View Source 
var (
	// ConfigHome is a single base directory relative to which user-specific
	// configuration files should be written.
	ConfigHome string

	// DataHome is a single base directory relative to which user-specific data
	// files should be written.
	DataHome string

	// CacheHome is a single base directory relative to which user-specific
	// non-essential (cached) data should be written.
	CacheHome string

	// RuntimeDir is a single base directory relative to which user-specific
	// runtime files and other file objects should be placed.
	RuntimeDir string

	// ConfigDirs is a set of preference ordered base directories relative to
	// which configuration files should be searched.
	ConfigDirs []string

	// DataDirs is a set of preference ordered base directories relative to
	// which data files should be searched.
	DataDirs []string

	// ConfigHomeDirs is the same as ConfigDirs, with ConfigHome at first place.
	ConfigHomeDirs []string

	// DataHomeDirs is the same as DataDirs, with DataHome at first place.
	DataHomeDirs []string
)
View Source 
var Getenv func(string) string = os.Getenv

Getenv reads several environment variables. You can provide your own implementation if you have special needs (e.g. mock testing). If you change Getenv, you need to call Init() again. The following variables are read: 

HOME
XDG_CONFIG_HOME
XDG_DATA_HOME
XDG_CACHE_HOME
XDG_RUNTIME_DIR
XDG_CONFIG_DIRS
XDG_DATA_DIRS
View Source 
var Skip = errors.New("skip the rest of the files to be merged")

Skip can be returned by a MergeFunc which causes the Merge* functions to skip the rest of the files to be merged.

Functions

func FindAllConfig 

func FindAllConfig(file string) []string

func FindAllData 

func FindAllData(file string) []string

func FindCache 

func FindCache(file string) string

func FindConfig 

func FindConfig(file string) string

func FindData 

func FindData(file string) string

func FindRuntime 

func FindRuntime(file string) string

func Init 

func Init()

Init initializes this package, reading several environment variables (using Getenv, which you can override if you need to), and setting several package variables.

It is normally not necessary to call Init; you only need to do so if you would like to reset the package (e.g. because you changed Getenv).

func MergeConfig 

func MergeConfig(file string, f MergeFunc) error

func MergeConfigR 

func MergeConfigR(file string, f MergeFunc) error

func MergeData 

func MergeData(file string, f MergeFunc) error

func MergeDataR 

func MergeDataR(file string, f MergeFunc) error

func MkdirAll 

func MkdirAll(dirpath string) error

MkdirAll creates dirpath if it does not already exist.

Example: 

xdg.MkdirAll(xdg.UserData("dromi"))
db, err := OpenDatabase(xdg.UserData("dromi/datbase.db"))

func OpenCache 

func OpenCache(file string, flag int) (*os.File, error)

func OpenConfig 

func OpenConfig(file string, flag int) (*os.File, error)

func OpenData 

func OpenData(file string, flag int) (*os.File, error)

func OpenRuntime 

func OpenRuntime(file string, flag int) (*os.File, error)

func UserCache 

func UserCache(file string) string

func UserConfig 

func UserConfig(file string) string

func UserData 

func UserData(file string) string

func UserRuntime 

func UserRuntime(file string) string

Types

type MergeFunc 

type MergeFunc func(filepath string) error

MergeFunc is given to the Merge* functions to handle the files that it finds. It receives an absolute path to a file, which MergeFunc can then try to open. When MergeFunc is done with the file (for example, it couldn't read the file, or it was empty) then it can return nil. If an error is returned, then the Merge* function aborts and returns this error. If an error hasn't occurred, but no files need be further inspected, Skip can be returned.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.