configdir

package
v0.6.8-ci.7 Latest Latest
Warning

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

Go to latest
Published: Feb 19, 2023 License: BSD-3-Clause, MIT Imports: 3 Imported by: 0

README

ConfigDir for Go

This library provides a cross platform means of detecting the system's configuration directories so that your Go app can store config files in a standard location. For Linux and other Unixes (BSD, etc.) this means using the Freedesktop.org XDG Base Directory Specification (0.8), and for Windows and macOS it uses their standard directories.

This is a simple no-nonsense module that just gives you the path names to do with as you please. You can either get the bare root config path, or get a path with any number of names suffixed onto it for vendor- or application-specific namespacing.

For the impatient, the directories this library can return tend to be like the following:

System-wide Configuration
Windows %PROGRAMDATA% or C:\ProgramData
Linux $XDG_CONFIG_DIRS or /etc/xdg
macOS /Library/Application Support
User-level Configuration
Windows %APPDATA% or C:\Users\%USER%\AppData\Roaming
Linux $XDG_CONFIG_HOME or $HOME/.config
macOS $HOME/Library/Application Support
User-level Cache Folder
Windows %LOCALAPPDATA% or C:\Users\%USER%\AppData\Local
Linux $XDG_CACHE_HOME or $HOME/.cache
macOS $HOME/Library/Caches

Quick Start

// A common use case is to get a private config folder for your app to
// place its settings files into, that are specific to the local user.
configPath := configdir.LocalConfig("my-app")
err := configdir.MakePath(configPath) // Ensure it exists.
if err != nil {
    panic(err)
}

// Deal with a JSON configuration file in that folder.
configFile := filepath.Join(configPath, "settings.json")
type AppSettings struct {
    Username string `json:"username"`
    Password string `json:"password"`
}
var settings AppSettings

// Does the file not exist?
if _, err = os.Stat(configFile); os.IsNotExist(err) {
    // Create the new config file.
    settings = AppSettings{"MyUser", "MyPassword"}
    fh, err := os.Create(configFile)
    if err != nil {
        panic(err)
    }
    defer fh.Close()

    encoder := json.NewEncoder(fh)
    encoder.Encode(&settings)
} else {
    // Load the existing file.
    fh, err := os.Open(configFile)
    if err != nil {
        panic(err)
    }
    defer fh.Close()

    decoder := json.NewDecoder(fh)
    decoder.Decode(&settings)
}

Documentation

Package documentation is available at https://godoc.org/github.com/kirsle/configdir

Author

Noah Petherbridge, @kirsle

License

MIT

Documentation

Overview

Package configdir provides a cross platform means of detecting the system's configuration directories.

This makes it easy to program your Go app to store its configuration files in a standard location relevant to the host operating system. For Linux and some other Unixes (like BSD) this means following the Freedesktop.org XDG Base Directory Specification 0.8, and for Windows and macOS it uses their standard directories.

This is a simple no-nonsense module that just gives you the paths, with optional components tacked on the end for vendor- or app-specific namespacing. It also provides a convenience function to call `os.MkdirAll()` on the paths to ensure they exist and are ready for you to read and write files in.

Standard Global Configuration Paths

  • Linux: $XDG_CONFIG_DIRS or "/etc/xdg"
  • Windows: %PROGRAMDATA% or "C:\\ProgramData"
  • macOS: /Library/Application Support

Standard User-Specific Configuration Paths

  • Linux: $XDG_CONFIG_HOME or "$HOME/.config"
  • Windows: %APPDATA% or "C:\\Users\\%USER%\\AppData\\Roaming"
  • macOS: $HOME/Library/Application Support

Standard User-Specific Cache Paths

  • Linux: $XDG_CACHE_HOME or "$HOME/.cache"
  • Windows: %LOCALAPPDATA% or "C:\\Users\\%USER%\\AppData\\Local"
  • macOS: $HOME/Library/Caches
Example

Quick start example for a common use case of this module.

Output:

Index

Examples

Constants

View Source
const VERSION = "0.1.0"

VERSION is the semantic version number of the configdir library.

Variables

View Source
var DefaultFileMode = os.FileMode(0755)

DefaultFileMode controls the default permissions on any paths created by using MakePath.

Functions

func LocalCache

func LocalCache(folder ...string) string

LocalCache returns the local user cache folder, with optional path components added to the end for vendor/application-specific settings.

Example

Example for getting a user-specific cache folder.

Output:

func LocalConfig

func LocalConfig(folder ...string) string

LocalConfig returns the local user configuration path, with optional path components added to the end for vendor/application-specific settings.

Example

Example for getting a user-specific configuration path.

Output:

func MakePath

func MakePath(paths ...string) error

MakePath ensures that the full path you wanted, including vendor or application-specific components, exists. You can give this the output of any of the config path functions (SystemConfig, LocalConfig or LocalCache).

In the event that the path function gives multiple answers, e.g. for SystemConfig, MakePath() will only attempt to create the sub-folders on the *first* path found. If this isn't what you want, you may want to just use the os.MkdirAll() functionality directly.

Example

Example for automatically creating config directories.

Output:

func Refresh

func Refresh()

Refresh will rediscover the config paths, checking current environment variables again.

This function is automatically called when the program initializes. If you change the environment variables at run-time, though, you may call the Refresh() function to reevaluate the config paths.

Example

Example for recalculating what the directories should be.

Output:

func SystemConfig

func SystemConfig(folder ...string) []string

SystemConfig returns the system-wide configuration paths, with optional path components added to the end for vendor/application-specific settings.

Example

Example for getting a global system configuration path.

Output:

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL