README
¶
dotconfig
Package dotconfig provides utilities for finding application configuration directories and files following standard conventions across different operating systems.
While Go's standard library offers os.UserConfigDir to find the user's configuration directory, this package extends that functionality by searching multiple potential locations and considering traditional dot-directory patterns. This approach provides more flexibility and better compatibility with existing applications and different environment configurations, including Plan9.
It implements the XDG Base Directory Specification (when XDG_CONFIG_HOME is set) and falls back to traditional home directory locations. The package's primary functions are Dir, which locates the appropriate configuration directory for an application, and File, which locates specific configuration files.
The search order for configuration directories is:
$XDG_CONFIG_HOME/<app>(if XDG_CONFIG_HOME is set)$HOME/.config/<app>(if XDG_CONFIG_HOME is not set)$HOME/lib/<app>(for Plan9 compatibility)$HOME/.<app>(if os.UserHomeDir returns no error).<app>(in current directory, as last resort)
For files, similar locations are searched but with the file name appended to directories or with the file extension appended to dot-prefixed application names.
$XDG_CONFIG_HOME/<app>/<name>(if XDG_CONFIG_HOME is set)$HOME/.config/<app>/<name>(if XDG_CONFIG_HOME is not set)$HOME/lib/<app>/<name>(for Plan9 compatibility)$HOME/.<app>/<name>(if os.UserHomeDir returns no error)$HOME/.<app><ext>(where<ext>is the file extension of<name>).<app>/<name>(in current directory).<app><ext>(in current directory, as last resort)
Unlike os.UserConfigDir which only returns a single directory recommendation, this package actively searches for existing configuration directories and files, providing a recommended path even when no directory or file exists yet, making it easier to handle both reading from existing configurations and creating new configuration files.
Usage Example
Dir
dir, exists := dotconfig.Dir("myapp")
if !exists {
if err := os.MkdirAll(dir, 0755); err != nil {
panic(err)
}
}
File
file, status := dotconfig.File("myapp", "config.yaml")
if status == dotconfig.NotExists {
if err := os.MkdirAll(filepath.Dir(file), 0755); err != nil {
return err
}
}
Documentation
¶
Overview ¶
Package dotconfig provides utilities for finding application configuration directories and files following standard conventions across different operating systems.
While Go's standard library offers os.UserConfigDir to find the user's configuration directory, this package extends that functionality by searching multiple potential locations and considering traditional dot-directory patterns. This approach provides more flexibility and better compatibility with existing applications and different environment configurations, including Plan9.
It implements the XDG Base Directory Specification (when XDG_CONFIG_HOME is set) and falls back to traditional home directory locations. The package's primary functions are Dir, which locates the appropriate configuration directory for an application, and File, which locates specific configuration files.
The search order for configuration directories is:
- $XDG_CONFIG_HOME/<app> (if XDG_CONFIG_HOME is set)
- $HOME/.config/<app> (if XDG_CONFIG_HOME is not set)
- $HOME/lib/<app> (for Plan9 compatibility)
- $HOME/.<app> (if os.UserHomeDir returns no error)
- .<app> (in current directory, as last resort)
For files, similar locations are searched but with the file name appended to directories or with the file extension appended to dot-prefixed application names.
- $XDG_CONFIG_HOME/<app>/<name> (if XDG_CONFIG_HOME is set)
- $HOME/.config/<app>/<name> (if XDG_CONFIG_HOME is not set)
- $HOME/lib/<app>/<name> (for Plan9 compatibility)
- $HOME/.<app>/<name> (if os.UserHomeDir returns no error)
- $HOME/.<app><ext> (where <ext> is the file extension of <name>)
- .<app>/<name> (in current directory)
- .<app><ext> (in current directory, as last resort)
Unlike os.UserConfigDir which only returns a single directory recommendation, this package actively searches for existing configuration directories and files, providing a recommended path even when no directory or file exists yet, making it easier to handle both reading from existing configurations and creating new configuration files.
Index ¶
Examples ¶
Constants ¶
const ( // NotExists indicates that neither the file nor its base directory exists NotExists fileExists = iota // BaseExists indicates that the file's base directory exists but the file itself does not BaseExists // FileExists indicates that the file exists FileExists )
Variables ¶
This section is empty.
Functions ¶
func Dir ¶
Dir searches for a configuration directory for the specified application. It searches multiple potential locations following standard conventions across different operating systems.
The function tries the following locations in order:
- $XDG_CONFIG_HOME/<app> (if XDG_CONFIG_HOME is set)
- $HOME/.config/<app> (if XDG_CONFIG_HOME is not set)
- $HOME/lib/<app> (for Plan9 compatibility)
- $HOME/.<app> (if os.UserHomeDir returns no error)
- .<app> (in current directory, as last resort)
If an existing directory is found, it returns the directory path and true. If no existing directory is found but potential locations were checked, it returns the first potential location and false. If no locations could be determined, it returns ".<app>" and whether it exists.
Parameters:
- app: The application name to search configurations for
Returns:
- dir: The configuration directory path
- exist: Boolean indicating whether the directory exists on the filesystem
Example ¶
package main
import (
"fmt"
"os"
"github.com/goaux/dotconfig"
)
func main() {
dir, exists := dotconfig.Dir("myapp")
if !exists {
if err := os.MkdirAll(dir, 0755); err != nil {
panic(err)
}
}
fmt.Println(dir)
}
func File ¶
File searches for a configuration file for the specified application. It follows similar conventions to Dir but locates specific files rather than directories.
The function tries the following locations in order:
- $XDG_CONFIG_HOME/<app>/<name> (if XDG_CONFIG_HOME is set)
- $HOME/.config/<app>/<name> (if XDG_CONFIG_HOME is not set)
- $HOME/lib/<app>/<name> (for Plan9 compatibility)
- $HOME/.<app>/<name> (if os.UserHomeDir returns no error)
- $HOME/.<app><ext> (where <ext> is the file extension of <name>, if os.UserHomeDir returns no error)
- .<app>/<name> (in current directory)
- .<app><ext> (in current directory, as last resort)
If the file name parameter is "." or "/", the application name is used as the file name.
Parameters:
- app: The application name to search configurations for
- name: The name of the configuration file to find
Returns:
- path: The configuration file path
- status: A fileExists constant indicating whether the file exists, only its base directory exists, or neither exists
Example ¶
package main
import (
"fmt"
"os"
"path/filepath"
"github.com/goaux/dotconfig"
)
func main() {
file, status := dotconfig.File("myapp", "config.yaml")
if status == dotconfig.NotExists {
if err := os.MkdirAll(filepath.Dir(file), 0755); err != nil {
panic(err)
}
}
var config []byte
if err := os.WriteFile(file, config, 0644); err != nil {
panic(err)
}
fmt.Println(file)
}
Types ¶
This section is empty.
Source Files