XDG
Constants
Default paths according to XDG Base Directory Specification https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
Note: These are parsed into Array(Path) by config_dirs/data_dirs methods Note: Default runtime dir needs UID, handled in default_runtime_dir
Constants for platform-specific paths (macOS, Windows)
Class methods
Returns an application-specific cache file path within XDG_CACHE_HOME.
@param file_name Relative path of the file within the cache home. Must not contain '..' or start with '/'.
@param create If true, ensures the parent directory exists.
@return Full path to the potential cache file.
@raise XDG::DirectoryError if creation fails when create is true.
@raise ArgumentError if file_name is invalid.
Returns an application-specific configuration path within XDG_CONFIG_HOME.
Does not create the directory. Use app_config_path or ensure_directories! for creation.
@param app The application name.
@param version Optional version string, creating a subdirectory.
@param vendor Optional vendor name, creating a vendor subdirectory.
@return The constructed Path object.
@example Standard path
XDG.app_config("myapp") # => /home/user/.config/myapp
@example Path with version
XDG.app_config("myapp", "2.0") # => /home/user/.config/myapp/2.0
@example Path with vendor
XDG.app_config("cli", vendor: "acme") # => /home/user/.config/acme/cli
@example Path with vendor and version
XDG.app_config("cli", "1.1", vendor: "acme") # => /home/user/.config/acme/cli/1.1
@raise ArgumentError if app, version, or vendor contain invalid characters like '..' or '/'.
Returns a path for a config file within the primary config directory.
Optionally creates the parent directory.
@param file_name Relative path of the file within the config home.
@param create If true, ensures the parent directory exists.
@return The full path to the potential config file.
@raise XDG::DirectoryError if creation fails when create is true.
@raise ArgumentError if file_name is invalid.
Returns an application-specific data file path within XDG_DATA_HOME.
@param file_name Relative path of the file within the data home (e.g., "settings.json", "cache/images.db"). Must not contain '..' or start with '/'.
@param create If true, ensures the parent directory exists.
@return Full path to the potential data file.
@raise XDG::DirectoryError if creation fails when create is true.
@raise ArgumentError if file_name is invalid.
Returns an application-specific state path within XDG_STATE_HOME.
Does not create the directory. Use ensure_directories! for creation.
@param app The application name.
@param version Optional version string, creating a subdirectory.
@return The constructed Path object.
@example Standard path
XDG.app_state("myapp") # => /home/user/.local/state/myapp
@example Path with version
XDG.app_state("myapp", "2.0") # => /home/user/.local/state/myapp/2.0
@raise ArgumentError if app or version contain invalid characters like '..' or '/'.
Returns an application-specific state file path within XDG_STATE_HOME.
@param file_name Relative path of the file within the state home. Must not contain '..' or start with '/'.
@param create If true, ensures the parent directory exists.
@return Full path to the potential state file.
@raise XDG::DirectoryError if creation fails when create is true.
@raise ArgumentError if file_name is invalid.
Ensures base directories exist by creating them if missing with given mode (default 0700). Existing directories are left unchanged - no permission validation is performed. @param mode Permissions for newly created directories (has no effect on existing dirs) @raise XDG::DirectoryError if directory creation fails
Searches for a configuration file according to XDG Base Directory Spec. Looks in $XDG_CONFIG_HOME, then $XDG_CONFIG_DIRS. @param name The relative path or filename to search for. @return The full path to the first found file, or nil if not found. @example XDG.find_config_file("myapp/settings.ini")
Returns the XDG_RUNTIME_DIR directory path, creating it if necessary, or raises an error. Ensures the directory exists with 0o700 permissions. @raise RuntimeError if XDG_RUNTIME_DIR is not set and no valid default exists. @raise XDG::DirectoryError if creation fails or path disappears. @raise XDG::SecurityError if the path exists but is not a directory, or if the directory cannot be secured.
Validates directory security with detailed checks (ownership, permissions).
Logs detailed issues if validation fails.
@param path The directory path to validate.
@param expected_mode_max The maximum allowed permission bits (e.g., 0o700 for runtime, 0o777 for general).
@return true if the directory is valid, false otherwise.
Validates if a runtime directory meets XDG security requirements