README
¶
The XDG Base Directory Specification implemented in Go.
The XDG Base Directory Specification allows you specify directories where runtime files, configurations, data and caches are kept. The file discovery process is automatic and adheres to the XDG standard.
This package supports most Unix-based operating systems. It should work fine on MacOS. I wrote this package for my personal needs: to deduplicate this kind of functionality from my other programs, but it is very much a self-contained implementation.
See Usage section below for examples. Package documentation is available here: https://pkg.go.dev/github.com/mdm-code/xdg.
Installation
go get github.com/mdm-code/xdg
Default locations
The table shows default values for XDG environmental variables for Unix-like systems:
Unix-like |
|
|---|---|
| XDG_DATA_HOME | $HOME/.local/share |
| XDG_CONFIG_HOME | $HOME/.config |
| XDG_STATE_HOME | $HOME/.local/state |
| XDG_DATA_DIRS | /usr/local/share/:/usr/share/ |
| XDG_CONFIG_DIRS | /etc/xdg |
| XDG_CACHE_HOME | $HOME/.cache |
| XDG_RUNTIME_DIR | $TMPDIR |
Usage
Here is an example of how to use the public API of the xdg package.
package main
import (
"fmt"
"github.com/mdm-code/xdg"
)
func main() {
// XDG base directory paths.
dirs := []struct {
msg string
pth string
}{
{"Home data directory: ", xdg.DataHomeDir()},
{"Config home directory: ", xdg.CacheHomeDir()},
{"State home directory: ", xdg.StateHomeDir()},
{"Data directories: ", xdg.DataDirs()},
{"Config directories: ", xdg.ConfigDirs()},
{"Cache home directory: ", xdg.CacheHomeDir()},
{"Runtime home directory: ", xdg.RuntimeDir()},
}
for _, d := range dirs {
fmt.Println(d.msg, d.pth)
}
// Search for file in data XDG directories.
fpath := "/prog/file"
if f, ok := xdg.Find(xdg.Data, fpath); ok {
fmt.Println(f)
} else {
fmt.Printf("ERROR: couldn't find %s\n", fpath)
}
}
Development
Consult Makefile to see how to format, examine code with go vet,
run unit test, run code linter with golint get test coverage and check if the
package builds all right.
Remember to install golint before you try to run tests and test the build:
go install golang.org/x/lint/golint@latest
License
Copyright (c) 2023 Michał Adamczyk.
This project is licensed under the MIT license. See LICENSE for more details.
Documentation
¶
Overview ¶
Package xdg implements the XDG Base Directory Specification in Go. The specification states where specification files should be searched. It does so by defining base directories relative to which files are located. The details of the specification are laid out here: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
This package supports most Unix-based operating systems. It should work fine on MacOS.
Usage
package main
import (
"fmt"
"github.com/mdm-code/xdg"
)
func main() {
// XDG base directory paths.
dirs := []struct {
msg string
f func() string
}{
{"Home data directory: ", xdg.DataHomeDir},
{"Config home directory: ", xdg.CacheHomeDir},
{"State home directory: ", xdg.StateHomeDir},
{"Data directories: ", xdg.DataDirs},
{"Config directories: ", xdg.ConfigDirs},
{"Cache home directory: ", xdg.CacheHomeDir},
{"Runtime home directory: ", xdg.RuntimeDir},
}
for _, d := range dirs {
fmt.Println(d.msg, d.f())
}
// Search for file in data XDG directories.
fpath := "program/file.data"
if f, ok := xdg.Find(xdg.Data, fpath); ok {
fmt.Println(f)
} else {
fmt.Printf("ERROR: couldn't find %s\n", fpath)
}
}
Index ¶
Examples ¶
Constants ¶
const ( // Data XDG base directory type. Data dir = iota // Config XDG base directory type. Config // State XDG base directory type. State // Cache XDG base directory type. Cache // Runtime XDG base directory type. Runtime )
Variables ¶
This section is empty.
Functions ¶
func CacheHomeDir ¶
func CacheHomeDir() string
CacheHomeDir returns a single base directory relative to which user-specific, non-essential (cached) data should be written. Default: $HOME/.cache.
Example ¶
package main
import (
"fmt"
"github.com/mdm-code/xdg"
)
func main() {
dir := xdg.CacheHomeDir()
fmt.Println("Cache home directory: ", dir)
}
Output:
func ConfigDirs ¶
func ConfigDirs() string
ConfigDirs returns a set of preference-ordered base directories relative to which configuration files should be searched. Default: /etc/xdg.
Example ¶
package main
import (
"fmt"
"github.com/mdm-code/xdg"
)
func main() {
dir := xdg.ConfigDirs()
fmt.Println("Config directories: ", dir)
}
Output:
func ConfigHomeDir ¶
func ConfigHomeDir() string
ConfigHomeDir returns a single base directory relative to which user-specific configuration files should be written. Default: $HOME/.config.
Example ¶
package main
import (
"fmt"
"github.com/mdm-code/xdg"
)
func main() {
dir := xdg.ConfigHomeDir()
fmt.Println("Config home directory: ", dir)
}
Output:
func DataDirs ¶
func DataDirs() string
DataDirs returns a set of preference-ordered base directories relative to which data files should be searched. Default: /usr/local/share/:/usr/share/.
Example ¶
package main
import (
"fmt"
"github.com/mdm-code/xdg"
)
func main() {
dir := xdg.DataDirs()
fmt.Println("Data directories: ", dir)
}
Output:
func DataHomeDir ¶
func DataHomeDir() string
DataHomeDir returns a single base directory relative to which user-specific files should be written. Default: $HOME/.local/share.
Example ¶
package main
import (
"fmt"
"github.com/mdm-code/xdg"
)
func main() {
dir := xdg.DataHomeDir()
fmt.Println("Home data directory: ", dir)
}
Output:
func Find ¶
Find searches for a given path in specified XDG directories. It returns an empty string and false if the path is not found.
Example ¶
package main
import (
"fmt"
"github.com/mdm-code/xdg"
)
func main() {
fpath := "program/file.data"
if f, ok := xdg.Find(xdg.Data, fpath); ok {
fmt.Printf("Data file for %s was found at %s\n", fpath, f)
} else {
fmt.Printf("ERROR: couldn't find %s\n", fpath)
}
}
Output:
func RuntimeDir ¶
func RuntimeDir() string
RuntimeDir returns a single base directory relative to which user-specific, runtime files and other file objects should be placed. It defaults to $TMPDIR on Unix if non-empty else /tmp.
Example ¶
package main
import (
"fmt"
"github.com/mdm-code/xdg"
)
func main() {
dir := xdg.RuntimeDir()
fmt.Println("Runtime home directory: ", dir)
}
Output:
func StateHomeDir ¶
func StateHomeDir() string
StateHomeDir returns a single base directory relative to which user-specific state data should be written. Default: $HOME/.local/state.
Example ¶
package main
import (
"fmt"
"github.com/mdm-code/xdg"
)
func main() {
dir := xdg.StateHomeDir()
fmt.Println("State home directory: ", dir)
}
Output:
Types ¶
This section is empty.
Source Files