appdirs

README

appdirs

This is a port of the excellent python module named the same, which can be found here appdirs.

The README and documentation in the original should be a good starting point. Documentation is currently lacking on the port itself, but the API is very similar to the python version.

Credits go to Wesley Bitter for the original implementation. The purposes of this fork currently is to attached the appdirs go package to a Go module. This allows the package to be versioned as needed as part of Go module's dependency management.

License

See LICENSE.

Documentation

Overview

A port of the excellent python module `appdirs`. See https://github.com/ActiveState/appdirs for the python version.

This is a port of a python module used for finding what directory you 'should' be using for saving your application data such as configuration, cache files or other files.

The location of these directories is often hard to get right. The original python module set out to change this into a simple API that returns you the exact directory you need. This is a port of it to Go.

Depending on platform, this package exports you at the least 6 functions that return various system directories. And one helper struct type that combines the functions into methods for less arguments in your code.

Each function defined accepts a number of arguments, each argument is optional and can be left to the types default value if omitted. Often the function will ignore arguments if the name given is empty.

Passing in all default values into any of the functions will return you the base directory without any of the arguments appended to it.

Index

• func ExpandUser(path string) string
• func SiteConfigDir(name, author, version string) string
• func SiteConfigDirs(name, author, version string) (paths []string)
• func SiteDataDir(name, author, version string) string
• func SiteDataDirs(name, author, version string) (paths []string)
• func UserCacheDir(name, author, version string, opinion bool) string
• func UserConfigDir(name, author, version string, roaming bool) string
• func UserDataDir(name, author, version string, roaming bool) string
• func UserLogDir(name, author, version string, opinion bool) string
• type App
  • func New(name, author, version string) *App
  • func (app *App) SiteConfig() string
  • func (app *App) SiteData() string
  • func (app *App) UserCache() string
  • func (app *App) UserConfig() string
  • func (app *App) UserData() string
  • func (app *App) UserLog() string

Functions

func ExpandUser

func ExpandUser(path string) string

ExpandUser is a helper function that expands the first '~' it finds in the passed path with the home directory of the current user.

Note: This only works on environments similar to bash.

func SiteConfigDir

func SiteConfigDir(name, author, version string) string

SiteConfigDir returns the full path to the user-shared data directory.

This function uses XDG_CONFIG_DIRS[0] as by the XDG spec on *nix like systems.

Examples of return values:

Mac OS X: same as SiteDataDir
Unix: /etc/xdg/<AppName> or $XDG_CONFIG_DIRS[i]/<AppName> for each value in $XDG_CONFIG_DIRS
Win *: same as SiteDataDir
Vista: (Fail! "C:\ProgramData" is a hidden *system* directory on Vista.)

WARNING: Do not use this on Windows Vista, see the note above.

func SiteConfigDirs

func SiteConfigDirs(name, author, version string) (paths []string)

func SiteDataDir

func SiteDataDir(name, author, version string) string

SiteDataDir returns the full path to the user-shared data directory.

This function uses XDG_DATA_DIRS[0] as by the XDG spec on *nix like systems.

Examples of return values:

Mac OS X: /Library/Application Support/<AppName>
Unix: /usr/local/share/<AppName> or /usr/share/<AppName>
Win XP: C:\Documents and Settings\All Users\Application Data\<AppAuthor>\<AppName>
Vista: (Fail! "C:\ProgramData" is a hidden *system* directory on Vista.)
Win 7: C:\ProgramData\<AppAuthor>\<AppName> # Hidden, but writeable on Win 7.

WARNING: Do not use this on Windows Vista, See the note above.

func SiteDataDirs

func SiteDataDirs(name, author, version string) (paths []string)

func UserCacheDir

func UserCacheDir(name, author, version string, opinion bool) string

UserCacheDir returns the full path to the user-specific cache directory.

The opinion argument will append 'Cache' to the base directory if set to true.

Examples of return values:

Mac OS X: ~/Library/Caches/<AppName>
Unix: ~/.cache/<AppName> (XDG default)
Win XP: C:\Documents and Settings\<username>\Local Settings\Application Data\<AppAuthor>\<AppName>\Cache
Vista: C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>\Cache

func UserConfigDir

func UserConfigDir(name, author, version string, roaming bool) string

UserConfigDir returns the full path to the user-specific configuration directory

This function uses XDG_CONFIG_HOME as by the XDG spec on *nix like systems.

Examples of return values:

Mac OS X: same as UserDataDir
Unix: ~/.config/<AppName> # or in $XDG_CONFIG_HOME, if defined
Win *: same as UserDataDir

func UserDataDir

func UserDataDir(name, author, version string, roaming bool) string

UserDataDir returns the full path to the user-specific data directory.

This function uses XDG_DATA_HOME as defined by the XDG spec on *nix like systems.

Examples of return values:

Mac OS X: ~/Library/Application Support/<AppName>
Unix: ~/.local/share/<AppName> # or in $XDG_DATA_HOME, if defined
Win XP (not roaming): C:\Documents and Settings\<username>\Application Data\<AppAuthor>\<AppName>
Win XP (roaming): C:\Documents and Settings\<username>\Local Settings\Application Data\<AppAuthor>\<AppName>
Win 7 (not roaming): C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>
Win 7 (roaming): C:\Users\<username>\AppData\Roaming\<AppAuthor>\<AppName>

func UserLogDir

func UserLogDir(name, author, version string, opinion bool) string

UserLogDir returns the full path to the user-specific log directory.

The opinion argument will append either 'Logs' (windows) or 'log' (unix) to the base directory when set to true.

Examples of return values:

Mac OS X: ~/Library/Logs/<AppName>
Unix: ~/.cache/<AppName>/log # or under $XDG_CACHE_HOME if defined
Win XP: C:\Documents and Settings\<username>\Local Settings\Application Data\<AppAuthor>\<AppName>\Logs
Vista: C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>\Logs

Types

type App

type App struct {
	Name    string
	Author  string
	Version string
	Roaming bool
	Opinion bool
}

App is a helper type to create easy access across your program to the appdirs functions.

The *App type has 6 methods that map to the 6 functions exported by `appdirs`. All methods take no arguments, and supply the function it wraps with arguments pre-set in the struct on creation.

func New

func New(name, author, version string) *App

New returns a new App helper that has various methods for receiving relevant directories for your application.

The following defaults are used for the two fields not settable by New: Roaming: false, Opinion: true

If you want to set these, create your own App struct by the usual means.

func (*App) SiteConfig

func (app *App) SiteConfig() string

SiteConfig returns the full path to the user-shared configuration directory

func (*App) SiteData

func (app *App) SiteData() string

SiteData returns the full path to the user-shared data directory

func (*App) UserCache

func (app *App) UserCache() string

UserCache returns the full path to the user-specific cache directory

func (*App) UserConfig

func (app *App) UserConfig() string

UserConfig returns the full path to the user-specific configuration directory

func (*App) UserData

func (app *App) UserData() string

UserData returns the full path to the user-specific data directory

func (*App) UserLog

func (app *App) UserLog() string

UserLog returns the full path to the user-specific log directory