xdg

README

Go, XDG, go!

This is go-xdg, a little library to help you use the XDG base directory spec.

(There are other XDG specs, that might get included in time. Patches welcome.)

Sample usage

Let's say you are writing an app called “frobz”. It has a config file and a sqlite database. You'd do something like this:

configFileName, err := xdg.Config.Find("frobz/config.txt")
if err == nil {
    // a config file exists! load it...
}
dbFileName, err := xdg.Data.Ensure("frobz/frobz.db")
// now the file and all its directories exist; it's up to you to
// determine if it's empty, etc.

Resources

Both Find and Ensure take a resource to construct the path they return.

A resource is usually an application name (or a well-known shared resource pool name, such as icons), followed by a filename. However nothing in the standard nor in this library limits you to that; you may store e.g. your application's configuration in just $XDG_CONFIG_HOME/application.conf (in which case the "resource" here would be just application.conf), or in a sub-directory of an application-specific directory.

License, etc.

BSD simplified, © John R. Lenton, blah blah.

Documentation

Overview

xdg implements helpers for you to use the XDG spec in your apps.

For now, that's just the base directory spec, http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

Index

• type XDGDir
  • func (x *XDGDir) Dirs() []string
  • func (x *XDGDir) Ensure(suffix string) (absPath string, err error)
  • func (x *XDGDir) Find(suffix string) (absPath string, err error)
  • func (x *XDGDir) Home() string

Types

type XDGDir

type XDGDir struct {
	// contains filtered or unexported fields
}

An XDGDir holds configuration for and can be used to access the XDG-specified base directories relative to which user-specific files of a given type should be stored.

Typically you wouldn't use XDGDir directly, but one of the predefined ones which implement the spec: Data, Config and Cache.

var (
	Data   *XDGDir // for data files.
	Config *XDGDir // for configuration files.
	Cache  *XDGDir // for non-essential data files.
)

func (*XDGDir) Dirs

func (x *XDGDir) Dirs() []string

Dirs returns the preference-ordered set of base directories to search for files of the given type, starting with the user-specific one, as specified (or not) by the user's environment.

func (*XDGDir) Ensure

func (x *XDGDir) Ensure(suffix string) (absPath string, err error)

Ensure takes the path suffix given, and ensures that a matching file exists in the home XDG directory. If it doesn't exist it is created. If it can't be created, or exists but is unreadable, an error is returned.

func (*XDGDir) Find

func (x *XDGDir) Find(suffix string) (absPath string, err error)

Find attempts to find the path suffix in all of the known XDG directories. If not found, an error is returned.

func (*XDGDir) Home

func (x *XDGDir) Home() string

Home gets the path to the given user-specific XDG directory, as specified (or not) by the user's environment.