gappdirs

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Mar 1, 2026 License: MIT Imports: 8 Imported by: 0

README

gappdirs

Go Reference Go Report Card

gappdirs allows you to retrieve platform-specifc directories and files for application data, configuration, logs, and cache. This module handles platform-specific directory conventions and provides a consistent API for applications to manage their files across different operating systems.

Currently supports Linux, macOS and Windows. On Linux, the directory and file lookup honors the XDG Base Directory Specification v0.8 behavior.

Application files can be classified into four categories based on their purpose:

  • Data - application data files that should be preserved across sessions.
  • Config - configuration files that are typically looked up at the startup of the application.
  • Log - files that record the state of application's execution and can be used for debugging, monitoring, or auditing purposes.
  • Cache - temporary files used by the application.

Directory and file lookup of the files and directories is organized by scope:

  • System - for system files that are relevant for all users. A system scope lookup will resolve to system directories only.
  • User - for files that are relevant to the current user. A user scope lookup resolves to user directories first, then system directories. This is the default scope most applications might want to use.
  • Local - for files that are in specific folders like the current directory, or a project-specific directories. Local scope resolves to local directories first, then user directories, then system directories.

Prerequisites

  • Go 1.24 or newer

Install

go get github.com/andrerfcsantos/gappdirs

Usage

Global functions

Use the global functions of the module to retrieve directories and files. This is the easiest way to interact with the library.

package main

import (
	"fmt"
	appdirs "github.com/andrerfcsantos/gappdirs"
)

func main() {
	// User data directories
	fmt.Println(appdirs.UserDataDirs("myapp")) // returns the user data directories for "myapp" in precedence order
	fmt.Println(appdirs.UserDataDir("myapp")) // returns the user data directory with most precedence for "myapp"

	// System log directories
	fmt.Println(appdirs.SystemLogDirs("myapp")) // returns the system log directories for "myapp" in precedence order
	fmt.Println(appdirs.SystemLogDir("myapp")) // returns the system log directory with most precedence for "myapp"

	// Create a config file in the directory with the most precedence for the user scope
	created, configPath, err := appdirs.CreateUserConfigFile("myapp", "settings.yaml")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("config file path:", configPath, "created:", created)

	// Find all existing config files names matching "settings.yaml" in the config dirs for user scope
	configFiles, err := appdirs.FindUserConfigFiles("myapp", "settings.yaml")
	if err != nil {
		fmt.Println("error finding config files:", err)
	}
	fmt.Println("config files:", configFiles)
}
Resolver for multiple scoped operations

If you do operations on a scope for a single app name often, you can create a Resolver for that app name and scope, and re-use it for several operations in files and directories:

package main

import (
	"fmt"
	appdirs "github.com/andrerfcsantos/gappdirs"
)

func main() {
	// The same example as above, but using a Resolver
	// Create a resolver for the user scope for the app "myapp"
	resolver := appdirs.NewUserResolver("myapp")

	// User data directories
	fmt.Println(resolver.DataDirs()) // returns the user data directories for "myapp" in precedence order
	fmt.Println(resolver.DataDir()) // returns the user data directory with most precedence for "myapp"

	// User log directories
	fmt.Println(resolver.LogDirs()) // returns the user log directories for "myapp" in precedence order
	fmt.Println(resolver.LogDir()) // returns the user log directory with most precedence for "myapp"

	// Create a config file in the directory with the most precedence for the user scope
	created, configPath, err := resolver.CreateConfigFile("settings.yaml")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("config file path:", configPath, "created:", created)

	// Find all existing config files names matching "settings.yaml" in the config dirs for user scope
	configFiles, err := resolver.FindConfigFiles("settings.yaml")
	if err != nil {
		fmt.Println("error finding config files:", err)
	}
	fmt.Println("config files:", configFiles)
}
Local Scope

Local scope allows you to configure lookup on directories that might not be user or system-related. For instance, before looking up user's and system's folder, you might want to check the user's local directory, or a config folder inside the local directory:

r := appdirs.NewLocalResolver("myapp",
	appdirs.WithLocalDirs(".", "./config"),
)

Directory Resolution Matrix

Each cell shows lookup precedence in order: Local -> User -> System.

Operating System Data Config Log Cache
Linux 1. Local: <cwd>/.<appName>/data
2. User: $XDG_DATA_HOME/<appName> (default: ~/.local/share/<appName>)
3. System: /var/lib/<appName>, then each entry in $XDG_DATA_DIRS/<appName> (default: /usr/local/share/<appName>, /usr/share/<appName>)		 1. Local: <cwd>/.<appName>/config
2. User: $XDG_CONFIG_HOME/<appName> (default: ~/.config/<appName>)
3. System: each entry in $XDG_CONFIG_DIRS/<appName> (default: /etc/xdg/<appName>)		 1. Local: <cwd>/.<appName>/log
2. User: $XDG_STATE_HOME/<appName>/log (default: ~/.local/state/<appName>/log)
3. System: /var/log/<appName>		 1. Local: <cwd>/.<appName>/cache
2. User: $XDG_CACHE_HOME/<appName> (default: ~/.cache/<appName>)
3. System: /var/cache/<appName>
macOS 1. Local: <cwd>/.<appName>/data
2. User: ~/Library/Application Support/<appName>/data
3. System: /Library/Application Support/<appName>/data		 1. Local: <cwd>/.<appName>/config
2. User: ~/Library/Application Support/<appName>/config
3. System: /Library/Application Support/<appName>/config		 1. Local: <cwd>/.<appName>/log
2. User: ~/Library/Logs/<appName>
3. System: /Library/Logs/<appName>		 1. Local: <cwd>/.<appName>/cache
2. User: ~/Library/Caches/<appName>
3. System: /Library/Caches/<appName>
Windows 1. Local: <cwd>\\.<appName>\\data (normalized form: <cwd>/.<appName>/data)
2. User: %LOCALAPPDATA%\\<appName>\\Data, %APPDATA%\\<appName>\\Data
3. System: %ProgramData%\\<appName>\\Data		 1. Local: <cwd>\\.<appName>\\config (normalized form: <cwd>/.<appName>/config)
2. User: %APPDATA%\\<appName>\\Config, %LOCALAPPDATA%\\<appName>\\Config
3. System: %ProgramData%\\<appName>\\Config		 1. Local: <cwd>\\.<appName>\\log (normalized form: <cwd>/.<appName>/log)
2. User: %LOCALAPPDATA%\\<appName>\\Logs
3. System: %ProgramData%\\<appName>\\Logs		 1. Local: <cwd>\\.<appName>\\cache (normalized form: <cwd>/.<appName>/cache)
2. User: %LOCALAPPDATA%\\<appName>\\Cache
3. System: %ProgramData%\\<appName>\\Cache

Documentation

Overview

Package gappdirs allows you to retrieve platform-specifc directories and files for application data, configuration, logs, and cache. This module handles platform-specific directory conventions and provides a consistent API for applications to manage their files across different operating systems. On Linux, the directory and file lookup honors the XDG Base Directory Specification v0.8 behavior.

Application files can be classified into four categories based on their purpose:

  • Data - application data files that should be preserved across sessions.
  • Config - configuration files that are typically looked up at the startup of the application.
  • Log - files that record the state of application's execution and can be used for debugging, monitoring, or auditing purposes.
  • Cache - temporary files used by the application.

Directory and file lookup of the files and directories is organized by scope:

  • System - for system files that are relevant for all users. A system scope lookup will resolve to system directories only.
  • User - for files that are relevant to the current user. A user scope lookup resolves to user directories first, then system directories.
  • Local - for files that are in specific folders like the current directory, or a project-specific directories. Local scope resolves to local directories first, then user directories, then system directories.

Use the global functions of the module to retrieve directories and files: 

package main

import (
	"fmt"
	appdirs "github.com/andrerfcsantos/gappdirs"
)

func main() {
	// User data directories
	fmt.Println(appdirs.UserDataDirs("myapp")) // returns the user data directories for "myapp" in precedence order
	fmt.Println(appdirs.UserDataDir("myapp")) // returns the user data directory with most precedence for "myapp"

	// System log directories
	fmt.Println(appdirs.SystemLogDirs("myapp")) // returns the system log directories for "myapp" in precedence order
	fmt.Println(appdirs.SystemLogDir("myapp")) // returns the system log directory with most precedence for "myapp"

	// Create a config file in the directory with the most precedence for the user scope
	created, configPath, err := appdirs.CreateUserConfigFile("myapp", "settings.yaml")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("config file path:", configPath, "created:", created)

	// Find all existing config files names matching "settings.yaml" in the config dirs for user scope
	configFiles, err := appdirs.FindUserConfigFiles("myapp", "settings.yaml")
	if err != nil {
		fmt.Println("error finding config files:", err)
	}
	fmt.Println("config files:", configFiles)
}

If you do operations on a scope for a single app name often, you can create a Resolver for that app name and scope, and use it for operations in files and directories: 

package main

import (
	"fmt"
	appdirs "github.com/andrerfcsantos/gappdirs"
)

func main() {
	// The same example as above, but using a Resolver

	// Create a resolver for the user scope for the app "myapp"
	resolver := appdirs.NewUserResolver("myapp")

	// User data directories
	fmt.Println(resolver.DataDirs()) // returns the user data directories for "myapp" in precedence order
	fmt.Println(resolver.DataDir()) // returns the user data directory with most precedence for "myapp"

	// User log directories
	fmt.Println(resolver.LogDirs()) // returns the user log directories for "myapp" in precedence order
	fmt.Println(resolver.LogDir()) // returns the user log directory with most precedence for "myapp"

	// Create a config file in the directory with the most precedence for the user scope
	created, configPath, err := resolver.CreateConfigFile("settings.yaml")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("config file path:", configPath, "created:", created)

	// Find all existing config files names matching "settings.yaml" in the config dirs for user scope
	configFiles, err := resolver.FindConfigFiles("settings.yaml")
	if err != nil {
		fmt.Println("error finding config files:", err)
	}
	fmt.Println("config files:", configFiles)
}

Index

Constants

View Source 
const DefaultCreateFilePerm fs.FileMode = 0o644

DefaultCreateFilePerm is the default file permission used for file creation operations.

View Source 
const DefaultDirPerm fs.FileMode = 0o755

DefaultDirPerm is the default directory permission used for directory creation operations.

Variables

View Source 
var ErrNotFound = errors.New("gappdirs: no matching path found")

ErrNotFound indicates that a requested file was not found in any of the searched directories.

It is returned by all Find*File methods to allow callers to handle missing files—like falling back to defaults or creating new files—without performing string matching on errors.

Functions

func CreateLocalCacheFile 

func CreateLocalCacheFile(appName string, filename string, opts ...CreateFileOption) (bool, string, error)

CreateLocalCacheFile creates a new file in the highest-precedence cache directory for appName.

It returns the absolute path to the file, and any error encountered.

func CreateLocalConfigFile 

func CreateLocalConfigFile(appName string, filename string, opts ...CreateFileOption) (bool, string, error)

CreateLocalConfigFile creates a new file in the highest-precedence config directory for appName.

It returns the absolute path to the file, and any error encountered.

func CreateLocalDataFile 

func CreateLocalDataFile(appName string, filename string, opts ...CreateFileOption) (bool, string, error)

CreateLocalDataFile creates a new file in the highest-precedence data directory for appName.

It returns the absolute path to the file, and any error encountered.

func CreateLocalLogFile 

func CreateLocalLogFile(appName string, filename string, opts ...CreateFileOption) (bool, string, error)

CreateLocalLogFile creates a new file in the highest-precedence log directory for appName.

It returns the absolute path to the file, and any error encountered.

func CreateSystemCacheFile 

func CreateSystemCacheFile(appName string, filename string, opts ...CreateFileOption) (bool, string, error)

CreateSystemCacheFile creates a new file in the highest-precedence cache directory for appName.

It returns the absolute path to the file, and any error encountered.

func CreateSystemConfigFile 

func CreateSystemConfigFile(appName string, filename string, opts ...CreateFileOption) (bool, string, error)

CreateSystemConfigFile creates a new file in the highest-precedence config directory for appName.

It returns the absolute path to the file, and any error encountered.

func CreateSystemDataFile 

func CreateSystemDataFile(appName string, filename string, opts ...CreateFileOption) (bool, string, error)

CreateSystemDataFile creates a new file in the highest-precedence data directory for appName.

It returns the absolute path to the file, and any error encountered.

func CreateSystemLogFile 

func CreateSystemLogFile(appName string, filename string, opts ...CreateFileOption) (bool, string, error)

CreateSystemLogFile creates a new file in the highest-precedence log directory for appName.

It returns the absolute path to the file, and any error encountered.

func CreateUserCacheFile 

func CreateUserCacheFile(appName string, filename string, opts ...CreateFileOption) (bool, string, error)

CreateUserCacheFile creates a new file in the highest-precedence cache directory for appName.

It returns the absolute path to the file, and any error encountered.

func CreateUserConfigFile 

func CreateUserConfigFile(appName string, filename string, opts ...CreateFileOption) (bool, string, error)

CreateUserConfigFile creates a new file in the highest-precedence config directory for appName.

It returns the absolute path to the file, and any error encountered.

func CreateUserDataFile 

func CreateUserDataFile(appName string, filename string, opts ...CreateFileOption) (bool, string, error)

CreateUserDataFile creates a new file in the highest-precedence data directory for appName.

It returns the absolute path to the file, and any error encountered.

func CreateUserLogFile 

func CreateUserLogFile(appName string, filename string, opts ...CreateFileOption) (bool, string, error)

CreateUserLogFile creates a new file in the highest-precedence log directory for appName.

It returns the absolute path to the file, and any error encountered.

func EnsureLocalCacheDir 

func EnsureLocalCacheDir(appName string, opts ...EnsureOption) (string, error)

EnsureLocalCacheDir ensures the existence of the highest-precedence cache directory for appName and returns its path.

It returns the absolute path to the directory, and any error encountered.

func EnsureLocalConfigDir 

func EnsureLocalConfigDir(appName string, opts ...EnsureOption) (string, error)

EnsureLocalConfigDir ensures the existence of the highest-precedence config directory for appName and returns its path.

It returns the absolute path to the directory, and any error encountered.

func EnsureLocalDataDir 

func EnsureLocalDataDir(appName string, opts ...EnsureOption) (string, error)

EnsureLocalDataDir ensures the highest-precedence data directory for appName and returns its path.

It returns the absolute path to the directory, and any error encountered.

func EnsureLocalLogDir 

func EnsureLocalLogDir(appName string, opts ...EnsureOption) (string, error)

EnsureLocalLogDir ensures the existence of the highest-precedence log directory for appName and returns its path.

It returns the absolute path to the directory, and any error encountered.

func EnsureSystemCacheDir 

func EnsureSystemCacheDir(appName string, opts ...EnsureOption) (string, error)

EnsureSystemCacheDir ensures the existence of the highest-precedence cache directory for appName and returns its path.

It returns the absolute path to the directory, and any error encountered.

func EnsureSystemConfigDir 

func EnsureSystemConfigDir(appName string, opts ...EnsureOption) (string, error)

EnsureSystemConfigDir ensures the existence of the highest-precedence config directory for appName and returns its path.

It returns the absolute path to the directory, and any error encountered.

func EnsureSystemDataDir 

func EnsureSystemDataDir(appName string, opts ...EnsureOption) (string, error)

EnsureSystemDataDir ensures the existence of the highest-precedence data directory for appName and returns its path.

It returns the absolute path to the directory, and any error encountered.

func EnsureSystemLogDir 

func EnsureSystemLogDir(appName string, opts ...EnsureOption) (string, error)

EnsureSystemLogDir ensures the existence of the highest-precedence log directory for appName and returns its path.

It returns the absolute path to the directory, and any error encountered.

func EnsureUserCacheDir 

func EnsureUserCacheDir(appName string, opts ...EnsureOption) (string, error)

EnsureUserCacheDir ensures the existence of the highest-precedence cache directory for appName and returns its path.

It returns the absolute path to the directory, and any error encountered.

func EnsureUserConfigDir 

func EnsureUserConfigDir(appName string, opts ...EnsureOption) (string, error)

EnsureUserConfigDir ensures the existence of the highest-precedence config directory for appName and returns its path.

It returns the absolute path to the directory, and any error encountered.

func EnsureUserDataDir 

func EnsureUserDataDir(appName string, opts ...EnsureOption) (string, error)

EnsureUserDataDir ensures the existence of the highest-precedence data directory for appName and returns its path.

It returns the absolute path to the directory, and any error encountered.

func EnsureUserLogDir 

func EnsureUserLogDir(appName string, opts ...EnsureOption) (string, error)

EnsureUserLogDir ensures the existence of the highest-precedence log directory for appName and returns its path.

It returns the absolute path to the directory, and any error encountered.

func FindLocalCacheFile 

func FindLocalCacheFile(appName string, filename string) (string, error)

FindLocalCacheFile returns the first existing match for filename in cache directories for appName selected by local, user, then system precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, it returns ErrNotFound.

func FindLocalCacheFiles 

func FindLocalCacheFiles(appName string, filename string) ([]string, error)

FindLocalCacheFiles returns all existing matches for filename in cache directories for appName in local, user, then system precedence order.

It returns the paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func FindLocalConfigFile 

func FindLocalConfigFile(appName string, filename string) (string, error)

FindLocalConfigFile returns the first existing match for filename in config directories for appName selected by local, user, then system precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, it returns ErrNotFound.

func FindLocalConfigFiles 

func FindLocalConfigFiles(appName string, filename string) ([]string, error)

FindLocalConfigFiles returns all existing matches for filename in config directories for appName in local, user, then system precedence order.

It returns the paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func FindLocalDataFile 

func FindLocalDataFile(appName string, filename string) (string, error)

FindLocalDataFile returns the first existing match for filename in data directories for appName selected by local, user, then system precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, it returns ErrNotFound.

func FindLocalDataFiles 

func FindLocalDataFiles(appName string, filename string) ([]string, error)

FindLocalDataFiles returns all existing matches for filename in data directories for appName selected by local, user, then system precedence order.

It returns the paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func FindLocalLogFile 

func FindLocalLogFile(appName string, filename string) (string, error)

FindLocalLogFile returns the first existing match for filename in log directories for appName selected by local, user, then system precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, it returns ErrNotFound.

func FindLocalLogFiles 

func FindLocalLogFiles(appName string, filename string) ([]string, error)

FindLocalLogFiles returns all existing matches for filename in log directories for appName in local, user, then system precedence order.

It returns the paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func FindSystemCacheFile 

func FindSystemCacheFile(appName string, filename string) (string, error)

FindSystemCacheFile returns the first existing match for filename in cache directories for appName selected by system precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, it returns ErrNotFound.

func FindSystemCacheFiles 

func FindSystemCacheFiles(appName string, filename string) ([]string, error)

FindSystemCacheFiles returns all existing matches for filename in cache directories for appName selected by system precedence order.

It returns the paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func FindSystemConfigFile 

func FindSystemConfigFile(appName string, filename string) (string, error)

FindSystemConfigFile returns the first existing match for filename in config directories for appName selected by system precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, it returns ErrNotFound.

func FindSystemConfigFiles 

func FindSystemConfigFiles(appName string, filename string) ([]string, error)

FindSystemConfigFiles returns all existing matches for filename in config directories for appName selected by system precedence order.

It returns the paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func FindSystemDataFile 

func FindSystemDataFile(appName string, filename string) (string, error)

FindSystemDataFile returns the first existing match for filename in data directories for appName selected by system precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, it returns ErrNotFound.

func FindSystemDataFiles 

func FindSystemDataFiles(appName string, filename string) ([]string, error)

FindSystemDataFiles returns all existing matches for filename in data directories for appName selected by system precedence order.

It returns the paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func FindSystemLogFile 

func FindSystemLogFile(appName string, filename string) (string, error)

FindSystemLogFile returns the first existing match for filename in log directories for appName selected by system precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, it returns ErrNotFound.

func FindSystemLogFiles 

func FindSystemLogFiles(appName string, filename string) ([]string, error)

FindSystemLogFiles returns all existing matches for filename in log directories for appName selected by system precedence order.

It returns the paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func FindUserCacheFile 

func FindUserCacheFile(appName string, filename string) (string, error)

FindUserCacheFile returns the first existing match for filename in cache directories for appName selected by user, then system precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, it returns ErrNotFound.

func FindUserCacheFiles 

func FindUserCacheFiles(appName string, filename string) ([]string, error)

FindUserCacheFiles returns all existing matches for filename in cache directories for appName selected by user, then system precedence order.

It returns the paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func FindUserConfigFile 

func FindUserConfigFile(appName string, filename string) (string, error)

FindUserConfigFile returns the first existing match for filename in config directories for appName selected by user, then system precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, it returns ErrNotFound.

func FindUserConfigFiles 

func FindUserConfigFiles(appName string, filename string) ([]string, error)

FindUserConfigFiles returns all existing matches for filename in config directories for appName selected by user, then system precedence order.

It returns the paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func FindUserDataFile 

func FindUserDataFile(appName string, filename string) (string, error)

FindUserDataFile returns the first existing match for filename in data directories for appName selected by user, then system precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, it returns ErrNotFound.

func FindUserDataFiles 

func FindUserDataFiles(appName string, filename string) ([]string, error)

FindUserDataFiles returns all existing matches for filename in data directories for appName in user, then system precedence order.

It returns the paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func FindUserLogFile 

func FindUserLogFile(appName string, filename string) (string, error)

FindUserLogFile returns the first existing match for filename in log directories for appName selected by user, then system precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, it returns ErrNotFound.

func FindUserLogFiles 

func FindUserLogFiles(appName string, filename string) ([]string, error)

FindUserLogFiles returns all existing matches for filename in log directories for appName selected by user, then system precedence order.

It returns the paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func LocalCacheDir 

func LocalCacheDir(appName string) string

LocalCacheDir returns the single highest-precedence cache directory path for appName selected by local, user, then system precedence.

The path returned is not guaranteed to exist on the filesystem. Use EnsureLocalCacheDir to ensure the highest-precedence cache directory exists and get its path.

func LocalCacheDirs 

func LocalCacheDirs(appName string) []string

LocalCacheDirs returns all candidate cache directories paths, in precedence order for appName selected by local, user, then system precedence.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureLocalCacheDir to ensure the highest-precedence cache directory exists and get its path.

func LocalCacheFilePath added in v0.2.0 

func LocalCacheFilePath(appName string, filename string) string

LocalCacheFilePath returns the single highest-precedence cache file path for filename for appName selected by local, user, then system precedence.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func LocalCacheFilePaths added in v0.2.0 

func LocalCacheFilePaths(appName string, filename string) []string

LocalCacheFilePaths returns all candidate cache file paths for filename, in precedence order for appName selected by local, user, then system precedence.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func LocalConfigDir 

func LocalConfigDir(appName string) string

LocalConfigDir returns the single highest-precedence config directory path for appName selected by local, user, then system precedence.

The path returned is not guaranteed to exist on the filesystem. Use EnsureLocalConfigDir to ensure the highest-precedence config directory exists and get its path.

func LocalConfigDirs 

func LocalConfigDirs(appName string) []string

LocalConfigDirs returns all candidate config directories paths, in precedence order for appName selected by local, user, then system precedence.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureLocalConfigDir to ensure the highest-precedence config directory exists and get its path.

func LocalConfigFilePath added in v0.2.0 

func LocalConfigFilePath(appName string, filename string) string

LocalConfigFilePath returns the single highest-precedence config file path for filename for appName selected by local, user, then system precedence.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func LocalConfigFilePaths added in v0.2.0 

func LocalConfigFilePaths(appName string, filename string) []string

LocalConfigFilePaths returns all candidate config file paths for filename, in precedence order for appName selected by local, user, then system precedence.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func LocalDataDir 

func LocalDataDir(appName string) string

LocalDataDir returns the single highest-precedence data directory path for appName selected by local, user, then system precedence.

The path returned is not guaranteed to exist on the filesystem. Use EnsureLocalDataDir to ensure the highest-precedence data directory exists and get its path.

func LocalDataDirs 

func LocalDataDirs(appName string) []string

LocalDataDirs returns all candidate data directories paths, in precedence order for appName selected by local, user, then system precedence.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureLocalDataDir to ensure the highest-precedence data directory exists and get its path.

func LocalDataFilePath added in v0.2.0 

func LocalDataFilePath(appName string, filename string) string

LocalDataFilePath returns the single highest-precedence data file path for filename for appName selected by local, user, then system precedence.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func LocalDataFilePaths added in v0.2.0 

func LocalDataFilePaths(appName string, filename string) []string

LocalDataFilePaths returns all candidate data file paths for filename, in precedence order for appName selected by local, user, then system precedence.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func LocalLogDir 

func LocalLogDir(appName string) string

LocalLogDir returns the single highest-precedence log directory path for appName selected by local, user, then system precedence.

The path returned is not guaranteed to exist on the filesystem. Use EnsureLocalLogDir to ensure the highest-precedence log directory exists and get its path.

func LocalLogDirs 

func LocalLogDirs(appName string) []string

LocalLogDirs returns all candidate log directories paths, in precedence order for appName selected by local, user, then system precedence.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureLocalLogDir to ensure the highest-precedence log directory exists and get its path.

func LocalLogFilePath added in v0.2.0 

func LocalLogFilePath(appName string, filename string) string

LocalLogFilePath returns the single highest-precedence log file path for filename for appName selected by local, user, then system precedence.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func LocalLogFilePaths added in v0.2.0 

func LocalLogFilePaths(appName string, filename string) []string

LocalLogFilePaths returns all candidate log file paths for filename, in precedence order for appName selected by local, user, then system precedence.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func SystemCacheDir 

func SystemCacheDir(appName string) string

SystemCacheDir returns the single highest-precedence cache directory path for appName selected by system precedence.

The path returned is not guaranteed to exist on the filesystem. Use EnsureSystemCacheDir to ensure the highest-precedence cache directory exists and get its path.

func SystemCacheDirs 

func SystemCacheDirs(appName string) []string

SystemCacheDirs returns all candidate cache directories paths, in precedence order for appName selected by system precedence.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureSystemCacheDir to ensure the highest-precedence cache directory exists and get its path.

func SystemCacheFilePath added in v0.2.0 

func SystemCacheFilePath(appName string, filename string) string

SystemCacheFilePath returns the single highest-precedence cache file path for filename for appName selected by system precedence.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func SystemCacheFilePaths added in v0.2.0 

func SystemCacheFilePaths(appName string, filename string) []string

SystemCacheFilePaths returns all candidate cache file paths for filename, in precedence order for appName selected by system precedence.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func SystemConfigDir 

func SystemConfigDir(appName string) string

SystemConfigDir returns the single highest-precedence config directory path for appName selected by system precedence.

The path returned is not guaranteed to exist on the filesystem. Use EnsureSystemConfigDir to ensure the highest-precedence config directory exists and get its path.

func SystemConfigDirs 

func SystemConfigDirs(appName string) []string

SystemConfigDirs returns all candidate config directories paths, in precedence order for appName selected by system precedence.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureSystemConfigDir to ensure the highest-precedence config directory exists and get its path.

func SystemConfigFilePath added in v0.2.0 

func SystemConfigFilePath(appName string, filename string) string

SystemConfigFilePath returns the single highest-precedence config file path for filename for appName selected by system precedence.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func SystemConfigFilePaths added in v0.2.0 

func SystemConfigFilePaths(appName string, filename string) []string

SystemConfigFilePaths returns all candidate config file paths for filename, in precedence order for appName selected by system precedence.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func SystemDataDir 

func SystemDataDir(appName string) string

SystemDataDir returns the single highest-precedence data directory path for appName selected by system precedence.

The path returned is not guaranteed to exist on the filesystem. Use EnsureSystemDataDir to ensure the highest-precedence data directory exists and get its path.

func SystemDataDirs 

func SystemDataDirs(appName string) []string

SystemDataDirs returns all candidate data directories paths, in precedence order for appName selected by system precedence.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureSystemDataDir to ensure the highest-precedence data directory exists and get its path.

func SystemDataFilePath added in v0.2.0 

func SystemDataFilePath(appName string, filename string) string

SystemDataFilePath returns the single highest-precedence data file path for filename for appName selected by system precedence.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func SystemDataFilePaths added in v0.2.0 

func SystemDataFilePaths(appName string, filename string) []string

SystemDataFilePaths returns all candidate data file paths for filename, in precedence order for appName selected by system precedence.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func SystemLogDir 

func SystemLogDir(appName string) string

SystemLogDir returns the single highest-precedence log directory path for appName selected by system precedence.

The path returned is not guaranteed to exist on the filesystem. Use EnsureSystemLogDir to ensure the highest-precedence log directory exists and get its path.

func SystemLogDirs 

func SystemLogDirs(appName string) []string

SystemLogDirs returns all candidate log directories paths, in precedence order for appName selected by system precedence.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureSystemLogDir to ensure the highest-precedence log directory exists and get its path.

func SystemLogFilePath added in v0.2.0 

func SystemLogFilePath(appName string, filename string) string

SystemLogFilePath returns the single highest-precedence log file path for filename for appName selected by system precedence.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func SystemLogFilePaths added in v0.2.0 

func SystemLogFilePaths(appName string, filename string) []string

SystemLogFilePaths returns all candidate log file paths for filename, in precedence order for appName selected by system precedence.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func UserCacheDir 

func UserCacheDir(appName string) string

UserCacheDir returns the single highest-precedence cache directory path for appName selected by user, then system precedence.

The path returned is not guaranteed to exist on the filesystem. Use EnsureUserCacheDir to ensure the highest-precedence cache directory exists and get its path.

func UserCacheDirs 

func UserCacheDirs(appName string) []string

UserCacheDirs returns all candidate cache directories paths, in precedence order for appName selected by user, then system precedence.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureUserCacheDir to ensure the highest-precedence cache directory exists and get its path.

func UserCacheFilePath added in v0.2.0 

func UserCacheFilePath(appName string, filename string) string

UserCacheFilePath returns the single highest-precedence cache file path for filename for appName selected by user, then system precedence.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func UserCacheFilePaths added in v0.2.0 

func UserCacheFilePaths(appName string, filename string) []string

UserCacheFilePaths returns all candidate cache file paths for filename, in precedence order for appName selected by user, then system precedence.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func UserConfigDir 

func UserConfigDir(appName string) string

UserConfigDir returns the single highest-precedence config directory path for appName selected by user, then system precedence.

The path returned is not guaranteed to exist on the filesystem. Use EnsureUserConfigDir to ensure the highest-precedence config directory exists and get its path.

func UserConfigDirs 

func UserConfigDirs(appName string) []string

UserConfigDirs returns all candidate config directories paths, in precedence order for appName selected by user, then system precedence.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureUserConfigDir to ensure the highest-precedence config directory exists and get its path.

func UserConfigFilePath added in v0.2.0 

func UserConfigFilePath(appName string, filename string) string

UserConfigFilePath returns the single highest-precedence config file path for filename for appName selected by user, then system precedence.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func UserConfigFilePaths added in v0.2.0 

func UserConfigFilePaths(appName string, filename string) []string

UserConfigFilePaths returns all candidate config file paths for filename, in precedence order for appName selected by user, then system precedence.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func UserDataDir 

func UserDataDir(appName string) string

UserDataDir returns the single highest-precedence data directory path for appName selected by user, then system precedence.

The path returned is not guaranteed to exist on the filesystem. Use EnsureUserDataDir to ensure the highest-precedence data directory exists and get its path.

func UserDataDirs 

func UserDataDirs(appName string) []string

UserDataDirs returns all candidate data directories paths, in precedence order for appName selected by user, then system precedence.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureUserDataDir to ensure the highest-precedence data directory exists and get its path.

func UserDataFilePath added in v0.2.0 

func UserDataFilePath(appName string, filename string) string

UserDataFilePath returns the single highest-precedence data file path for filename for appName selected by user, then system precedence.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func UserDataFilePaths added in v0.2.0 

func UserDataFilePaths(appName string, filename string) []string

UserDataFilePaths returns all candidate data file paths for filename, in precedence order for appName selected by user, then system precedence.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func UserLogDir 

func UserLogDir(appName string) string

UserLogDir returns the single highest-precedence log directory path for appName selected by user, then system precedence.

The path returned is not guaranteed to exist on the filesystem. Use EnsureUserLogDir to ensure the highest-precedence log directory exists and get its path.

func UserLogDirs 

func UserLogDirs(appName string) []string

UserLogDirs returns all candidate log directories paths, in precedence order for appName selected by user, then system precedence.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureUserLogDir to ensure the highest-precedence log directory exists and get its path.

func UserLogFilePath added in v0.2.0 

func UserLogFilePath(appName string, filename string) string

UserLogFilePath returns the single highest-precedence log file path for filename for appName selected by user, then system precedence.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func UserLogFilePaths added in v0.2.0 

func UserLogFilePaths(appName string, filename string) []string

UserLogFilePaths returns all candidate log file paths for filename, in precedence order for appName selected by user, then system precedence.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

Types

type CreateFileOption 

type CreateFileOption func(*CreateFileOptions)

CreateFileOption allows setting one option on file creation operations.

func WithContentsFromReader 

func WithContentsFromReader(reader io.Reader) CreateFileOption

WithContentsFromReader sets the contents of the new file being created to the contents of the reader.

If this option is not set a new file will be created with no content.

func WithFilePerm 

func WithFilePerm(perm fs.FileMode) CreateFileOption

WithFilePerm sets the file permission used when creating new files.

If this option is not set a default permission of 0o644 is used. Invalid permissions are ignored and the default is used instead.

func WithOverwriteExisting 

func WithOverwriteExisting() CreateFileOption

WithOverwriteExisting allows overwriting existing files in file creation operations.

If the option WithContentsFromReader is also used, the contents of the reader will be written to the file, overwriting the existing contents.

type CreateFileOptions 

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

CreateFileOptions contains the options passed on file creation operations.

type EnsureOption 

type EnsureOption func(*ensureConfig)

EnsureOption configures options for directory operations. It allows adjusting directory creation details for a single directory operation.

func WithEnsureDirPerm 

func WithEnsureDirPerm(perm fs.FileMode) EnsureOption

WithEnsureDirPerm sets the directory permission when creating a directory.

Invalid permissions are ignored and the default is used instead.

type Resolver 

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

Resolver resolves application directories for the current platform. It can be used for several operations of lookup and creation of application files and directories for the same scope and app name. If you just need a single operation, you might want to use the global functions of the module instead.

func NewLocalResolver 

func NewLocalResolver(appName string, opts ...ResolverOption) *Resolver

NewLocalResolver creates a Resolver configured to search local directories first, followed by user and then system directories.

It is typically used for development tools or applications that support project-local configuration overrides while keeping standard fallback behavior. Use the WithLocalDir or WithLocalDirs options to set the local directories.

func NewSystemResolver 

func NewSystemResolver(appName string, opts ...ResolverOption) *Resolver

NewSystemResolver creates a Resolver configured to search only machine-wide system directories.

It is useful for system services, daemons, or tools that manage shared assets and must intentionally ignore any user-specific or local overrides.

func NewUserResolver 

func NewUserResolver(appName string, opts ...ResolverOption) *Resolver

NewUserResolver creates a Resolver configured to search user directories first, followed by system directories.

It is the standard choice for most applications that store per-user configuration, data, and caches, while optionally reading machine-wide system defaults as a fallback.

func (*Resolver) CacheDir 

func (r *Resolver) CacheDir() string

CacheDir returns the single highest-precedence cache directory path for the resolver's scope and app name.

The path returned is not guaranteed to exist on the filesystem. Use EnsureCacheDir to ensure the highest-precedence cache directory exists and get its path.

func (*Resolver) CacheDirs 

func (r *Resolver) CacheDirs() []string

CacheDirs returns all candidate cache directories paths, in precedence order for the resolver's scope and app name.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureCacheDir to ensure the highest-precedence cache directory exists and get its path.

func (*Resolver) CacheFilePath added in v0.2.0 

func (r *Resolver) CacheFilePath(filename string) string

CacheFilePath returns the single highest-precedence cache file path for filename for the resolver's scope and app name.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func (*Resolver) CacheFilePaths added in v0.2.0 

func (r *Resolver) CacheFilePaths(filename string) []string

CacheFilePaths returns all candidate cache file paths for filename, in precedence order for the resolver's scope and app name.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func (*Resolver) ConfigDir 

func (r *Resolver) ConfigDir() string

ConfigDir returns the single highest-precedence config directory path for the resolver's scope and app name.

The path returned is not guaranteed to exist on the filesystem. Use EnsureConfigDir to ensure the highest-precedence config directory exists and get its path.

func (*Resolver) ConfigDirs 

func (r *Resolver) ConfigDirs() []string

ConfigDirs returns all candidate config directories paths, in precedence order for the resolver's scope and app name.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureConfigDir to ensure the highest-precedence config directory exists and get its path.

func (*Resolver) ConfigFilePath added in v0.2.0 

func (r *Resolver) ConfigFilePath(filename string) string

ConfigFilePath returns the single highest-precedence config file path for filename for the resolver's scope and app name.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func (*Resolver) ConfigFilePaths added in v0.2.0 

func (r *Resolver) ConfigFilePaths(filename string) []string

ConfigFilePaths returns all candidate config file paths for filename, in precedence order for the resolver's scope and app name.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func (*Resolver) CreateCacheFile 

func (r *Resolver) CreateCacheFile(filename string, opts ...CreateFileOption) (created bool, path string, err error)

CreateCacheFile creates a file with the given name in the highest-precedence cache directory for the Resolver scope.

If the file already exists, it will not be modified, unless the WithOverwriteExisting option is used. If the file does not exist, it will be created with the specified permissions and contents (if provided).

It returns a boolean indicating whether a new file was created and didn't exist before, the absolute path to the file, and any error encountered.

func (*Resolver) CreateConfigFile 

func (r *Resolver) CreateConfigFile(filename string, opts ...CreateFileOption) (created bool, path string, err error)

CreateConfigFile creates a file with the given name in the highest-precedence config directory for the Resolver scope.

If the file already exists, it will not be modified, unless the WithOverwriteExisting option is used. If the file does not exist, it will be created with the specified permissions and contents (if provided).

It returns a boolean indicating whether a new file was created and didn't exist before, the absolute path to the file, and any error encountered.

func (*Resolver) CreateDataFile 

func (r *Resolver) CreateDataFile(filename string, opts ...CreateFileOption) (created bool, path string, err error)

CreateDataFile creates a file with the given name in the highest-precedence data directory for the Resolver scope.

If the file already exists, it will not be modified, unless the WithOverwriteExisting option is used. If the file does not exist, it will be created with the specified permissions and contents (if provided).

It returns a boolean indicating whether a new file was created and didn't exist before, the absolute path to the file, and any error encountered.

func (*Resolver) CreateLogFile 

func (r *Resolver) CreateLogFile(filename string, opts ...CreateFileOption) (created bool, path string, err error)

CreateLogFile creates a file with the given name in the highest-precedence log directory for the Resolver scope.

If the file already exists, it will not be modified, unless the WithOverwriteExisting option is used. If the file does not exist, it will be created with the specified permissions and contents (if provided).

It returns a boolean indicating whether a new file was created and didn't exist before, the absolute path to the file, and any error encountered.

func (*Resolver) DataDir 

func (r *Resolver) DataDir() string

DataDir returns the single highest-precedence data directory path for the resolver's scope and app name.

The path returned is not guaranteed to exist on the filesystem. Use EnsureDataDir to ensure the highest-precedence data directory exists and get its path.

func (*Resolver) DataDirs 

func (r *Resolver) DataDirs() []string

DataDirs returns all candidate data directories paths, in precedence order for the resolver's scope and app name.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureDataDir to ensure the highest-precedence data directory exists and get its path.

func (*Resolver) DataFilePath added in v0.2.0 

func (r *Resolver) DataFilePath(filename string) string

DataFilePath returns the single highest-precedence data file path for filename for the resolver's scope and app name.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func (*Resolver) DataFilePaths added in v0.2.0 

func (r *Resolver) DataFilePaths(filename string) []string

DataFilePaths returns all candidate data file paths for filename, in precedence order for the resolver's scope and app name.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func (*Resolver) EnsureCacheDir 

func (r *Resolver) EnsureCacheDir(opts ...EnsureOption) (string, error)

EnsureCacheDir ensures the existence of the highest-precedence cache directory for the Resolver scope by creating it if it doesn't exist.

It returns the absolute path to the directory, and any error encountered.

func (*Resolver) EnsureConfigDir 

func (r *Resolver) EnsureConfigDir(opts ...EnsureOption) (string, error)

EnsureConfigDir ensures the existence of the highest-precedence config directory for the Resolver scope by creating it if it doesn't exist.

It returns the absolute path to the directory, and any error encountered.

func (*Resolver) EnsureDataDir 

func (r *Resolver) EnsureDataDir(opts ...EnsureOption) (string, error)

EnsureDataDir ensures the existence of the highest-precedence data directory for the Resolver scope by creating it if it doesn't exist.

It returns the absolute path to the directory, and any error encountered.

func (*Resolver) EnsureLogDir 

func (r *Resolver) EnsureLogDir(opts ...EnsureOption) (string, error)

EnsureLogDir ensures the existence of the highest-precedence log directory for the Resolver scope by creating it if it doesn't exist.

It returns the absolute path to the directory, and any error encountered.

func (*Resolver) FindCacheFile 

func (r *Resolver) FindCacheFile(filename string) (string, error)

FindCacheFile returns the first existing match for filename in cache directories by precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, an error of type ErrNotFound is returned.

func (*Resolver) FindCacheFiles 

func (r *Resolver) FindCacheFiles(filename string) ([]string, error)

FindCacheFiles returns all existing matches for filename in cache directories by precedence order.

It returns thr paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func (*Resolver) FindConfigFile 

func (r *Resolver) FindConfigFile(filename string) (string, error)

FindConfigFile returns the first existing match for filename in config directories by precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, an error of type ErrNotFound is returned.

func (*Resolver) FindConfigFiles 

func (r *Resolver) FindConfigFiles(filename string) ([]string, error)

FindConfigFiles returns all existing matches for filename in config directories by precedence order.

It returns thr paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func (*Resolver) FindDataFile 

func (r *Resolver) FindDataFile(filename string) (string, error)

FindDataFile returns the first existing match for filename in data directories by precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, an error of type ErrNotFound is returned.

func (*Resolver) FindDataFiles 

func (r *Resolver) FindDataFiles(filename string) ([]string, error)

FindDataFiles returns all existing matches for filename in data directories by precedence order.

It returns thr paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func (*Resolver) FindLogFile 

func (r *Resolver) FindLogFile(filename string) (string, error)

FindLogFile returns the first existing match for filename in log directories by precedence.

It returns the path to the existing file and any error encountered during the lookup. If no matching file is found, an error of type ErrNotFound is returned.

func (*Resolver) FindLogFiles 

func (r *Resolver) FindLogFiles(filename string) ([]string, error)

FindLogFiles returns all existing matches for filename in log directories by precedence order.

It returns thr paths to the existing files and any error encountered during the lookup. If no matching files are found, it returns an empty slice and nil error.

func (*Resolver) LogDir 

func (r *Resolver) LogDir() string

LogDir returns the single highest-precedence log directory path for the resolver's scope and app name.

The path returned is not guaranteed to exist on the filesystem. Use EnsureLogDir to ensure the highest-precedence log directory exists and get its path.

func (*Resolver) LogDirs 

func (r *Resolver) LogDirs() []string

LogDirs returns all candidate log directories paths, in precedence order for the resolver's scope and app name.

The paths returned are not guaranteed to exist on the filesystem. Use EnsureLogDir to ensure the highest-precedence log directory exists and get its path.

func (*Resolver) LogFilePath added in v0.2.0 

func (r *Resolver) LogFilePath(filename string) string

LogFilePath returns the single highest-precedence log file path for filename for the resolver's scope and app name.

The path returned is a computed candidate and is not guaranteed to exist on the filesystem.

func (*Resolver) LogFilePaths added in v0.2.0 

func (r *Resolver) LogFilePaths(filename string) []string

LogFilePaths returns all candidate log file paths for filename, in precedence order for the resolver's scope and app name.

The paths returned are computed candidates and are not guaranteed to exist on the filesystem.

func (*Resolver) ScopeForPath added in v0.3.0 

func (r *Resolver) ScopeForPath(path string) (scope Scope, found bool)

ScopeForPath returns the matching scope for path for the Resolver app name and scope.

It checks only the scope layers available for the resolver:

  • local resolvers check local, user, then system
  • user resolvers check user then system
  • system resolvers check system only

The path does not need to exist on disk.

type ResolverOption 

type ResolverOption func(*newResolverConfig)

ResolverOption sets an option when creating a resolver. It allows adjusting the local directories and the default directory permissions of a resolver.

func WithDefaultDirPerm 

func WithDefaultDirPerm(perm fs.FileMode) ResolverOption

WithDefaultDirPerm sets the default permission used when creating a directory.

Invalid permissions are ignored and the default is used instead.

func WithLocalDir 

func WithLocalDir(dir string) ResolverOption

WithLocalDir sets a local working directory root used for local scope.

This option can be used multiple times to set multiple local directories. Directories given first have highest precedence. Duplicate directories are ignored and only the first occurrence is used.

func WithLocalDirs 

func WithLocalDirs(dirs ...string) ResolverOption

WithLocalDirs sets one or multiple local working directory roots used for local scope.

Directories given first have highest precedence. Duplicate directories are ignored and only the first occurrence is used.

type Scope 

type Scope int

Scope determines which directory layers are searched for each lookup.

It allows callers to control the level of visibility and persistence for their files, choosing between project-local, per-user, or machine-wide system directories. 

const (
	// ScopeLocal includes the current working directory as the highest priority,
	// falling back to user directories, and then system directories.
	ScopeLocal Scope = iota
	// ScopeUser includes user-specific directories as the highest priority,
	// falling back to system directories.
	ScopeUser
	// ScopeSystem includes only machine-wide system directories, ignoring user
	// and local paths.
	ScopeSystem
)

func ScopeForPath added in v0.3.0 

func ScopeForPath(appName string, path string) (scope Scope, found bool)

ScopeForPath returns the matching scope for path for app name and a bool indicating if a match was found.

Directory comparison and lookup checks path candidates in local, then user, then system precedence. In other words, it assumes local scope for directory comparison.

The path does not need to exist on disk.

func (Scope) String 

func (s Scope) String() string

String returns a lowercase string representation of the scope.

It returns "local", "user", or "system" for known scopes, and formats unknown scopes as "scope(N)".

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.