Class: Toys::Utils::XDG
- Inherits:
-
Object
- Object
- Toys::Utils::XDG
- Defined in:
- lib/toys/utils/xdg.rb
Overview
A class that provides tools for working with the XDG Base Directory Specification.
This class provides utility methods that locate base directories and search paths for application state, configuration, caches, and other data, according to the XDG Base Directory Spec version 0.8.
Tools can use the :xdg
mixin for convenient access to this class.
Example
require "toys/utils/xdg"
xdg = Toys::Utils::XDG.new
# Get config file paths, in order from most to least inportant
config_files = xdg.lookup_config("my-config.toml")
config_files.each { |path| read_my_config(path) }
Windows operation
The Spec assumes a unix-like environment, and cannot be applied directly to Windows without modification. In general, this class will function on Windows, but with the following caveats:
- All file paths must use Windows-style absolute paths, beginning with the drive letter.
- Environment variables that can contain multiple paths (
XDG_*_DIRS
) use the Windows path delimiter (;
) rather than the unix path delimiter (:
). - Defaults for home directories (
XDG_*_HOME
) will follow unix conventions, using subdirectories under the user's profile directory rather than the Windows known folder paths. - Defaults for search paths (
XDG_*_DIRS
) will be empty and will not use the Windows known folder paths.
Instance Method Summary collapse
-
#cache_home ⇒ String
Returns the absolute path to the single base directory relative to which user-specific non-essential (cached) data should be written.
-
#config_dirs ⇒ Array<String>
Returns the set of preference ordered base directories relative to which configuration files should be searched, as an array of absolute paths.
-
#config_home ⇒ String
Returns the absolute path to the single base directory relative to which user-specific configuration files should be written.
-
#data_dirs ⇒ Array<String>
Returns the set of preference ordered base directories relative to which data files should be searched, as an array of absolute paths.
-
#data_home ⇒ String
Returns the absolute path to the single base directory relative to which user-specific data files should be written.
-
#ensure_cache_subdir(path) ⇒ String
Returns the absolute path to a directory under #cache_home, creating it if it doesn't already exist.
-
#ensure_config_subdir(path) ⇒ String
Returns the absolute path to a directory under #config_home, creating it if it doesn't already exist.
-
#ensure_data_subdir(path) ⇒ String
Returns the absolute path to a directory under #data_home, creating it if it doesn't already exist.
-
#ensure_state_subdir(path) ⇒ String
Returns the absolute path to a directory under #state_home, creating it if it doesn't already exist.
-
#executable_home ⇒ String
Returns the absolute path to the single base directory relative to which user-specific executable files may be written.
-
#home_dir ⇒ String
Returns the absolute path to the current user's home directory.
-
#initialize(env: ::ENV) ⇒ XDG
constructor
Create an instance of XDG.
-
#lookup_config(path, type: :file) ⇒ Array<String>
Searches the config directories for an object with the given relative path, and returns an array of absolute paths to all objects found in the config directories (i.e. in #config_dirs or #config_home), in order from most to least important.
-
#lookup_data(path, type: :file) ⇒ Array<String>
Searches the data directories for an object with the given relative path, and returns an array of absolute paths to all objects found in the data directories (i.e. in #data_dirs or #data_home), in order from most to least important.
-
#runtime_dir ⇒ String?
Returns the absolute path to the single base directory relative to which user-specific runtime files and other file objects should be placed.
-
#state_home ⇒ String
Returns the absolute path to the single base directory relative to which user-specific state files should be written.
Constructor Details
#initialize(env: ::ENV) ⇒ XDG
Create an instance of XDG.
50 51 52 53 54 |
# File 'lib/toys/utils/xdg.rb', line 50 def initialize(env: ::ENV) require "fileutils" require "toys/compat" @env = env end |
Instance Method Details
#cache_home ⇒ String
Returns the absolute path to the single base directory relative to
which user-specific non-essential (cached) data should be written.
Corresponds to the value of the $XDG_CACHE_HOME
environment variable
and its defaults according to the XDG Base Directory Spec.
111 112 113 |
# File 'lib/toys/utils/xdg.rb', line 111 def cache_home @cache_home ||= validate_dir_env("XDG_CACHE_HOME") || ::File.join(home_dir, ".cache") end |
#config_dirs ⇒ Array<String>
Returns the set of preference ordered base directories relative to
which configuration files should be searched, as an array of absolute
paths. The array is ordered from most to least important, and does
not include the config home directory.
Corresponds to the value of the $XDG_CONFIG_DIRS
environment variable
and its defaults according to the XDG Base Directory Spec.
152 153 154 155 |
# File 'lib/toys/utils/xdg.rb', line 152 def config_dirs @config_dirs ||= validate_dirs_env("XDG_CONFIG_DIRS") || validate_dirs(["/etc/xdg"]) || [] end |
#config_home ⇒ String
Returns the absolute path to the single base directory relative to
which user-specific configuration files should be written.
Corresponds to the value of the $XDG_CONFIG_HOME
environment variable
and its defaults according to the XDG Base Directory Spec.
86 87 88 |
# File 'lib/toys/utils/xdg.rb', line 86 def config_home @config_home ||= validate_dir_env("XDG_CONFIG_HOME") || ::File.join(home_dir, ".config") end |
#data_dirs ⇒ Array<String>
Returns the set of preference ordered base directories relative to
which data files should be searched, as an array of absolute paths.
The array is ordered from most to least important, and does not
include the data home directory.
Corresponds to the value of the $XDG_DATA_DIRS
environment variable
and its defaults according to the XDG Base Directory Spec.
137 138 139 140 |
# File 'lib/toys/utils/xdg.rb', line 137 def data_dirs @data_dirs ||= validate_dirs_env("XDG_DATA_DIRS") || validate_dirs(["/usr/local/share", "/usr/share"]) || [] end |
#data_home ⇒ String
Returns the absolute path to the single base directory relative to
which user-specific data files should be written.
Corresponds to the value of the $XDG_DATA_HOME
environment variable
and its defaults according to the XDG Base Directory Spec.
73 74 75 76 |
# File 'lib/toys/utils/xdg.rb', line 73 def data_home @data_home ||= validate_dir_env("XDG_DATA_HOME") || ::File.join(home_dir, ".local", "share") end |
#ensure_cache_subdir(path) ⇒ String
Returns the absolute path to a directory under #cache_home, creating it if it doesn't already exist.
255 256 257 |
# File 'lib/toys/utils/xdg.rb', line 255 def ensure_cache_subdir(path) ensure_subdir_internal(cache_home, path) end |
#ensure_config_subdir(path) ⇒ String
Returns the absolute path to a directory under #config_home, creating it if it doesn't already exist.
229 230 231 |
# File 'lib/toys/utils/xdg.rb', line 229 def ensure_config_subdir(path) ensure_subdir_internal(config_home, path) end |
#ensure_data_subdir(path) ⇒ String
Returns the absolute path to a directory under #data_home, creating it if it doesn't already exist.
216 217 218 |
# File 'lib/toys/utils/xdg.rb', line 216 def ensure_data_subdir(path) ensure_subdir_internal(data_home, path) end |
#ensure_state_subdir(path) ⇒ String
Returns the absolute path to a directory under #state_home, creating it if it doesn't already exist.
242 243 244 |
# File 'lib/toys/utils/xdg.rb', line 242 def ensure_state_subdir(path) ensure_subdir_internal(state_home, path) end |
#executable_home ⇒ String
Returns the absolute path to the single base directory relative to
which user-specific executable files may be written.
Returns the value of $HOME/.local/bin
as specified by the XDG Base
Directory Spec.
123 124 125 |
# File 'lib/toys/utils/xdg.rb', line 123 def executable_home @executable_home ||= ::File.join(home_dir, ".local", "bin") end |
#home_dir ⇒ String
Returns the absolute path to the current user's home directory.
61 62 63 |
# File 'lib/toys/utils/xdg.rb', line 61 def home_dir @home_dir ||= validate_dir_env("HOME") || ::Dir.home end |
#lookup_config(path, type: :file) ⇒ Array<String>
Searches the config directories for an object with the given relative path, and returns an array of absolute paths to all objects found in the config directories (i.e. in #config_dirs or #config_home), in order from most to least important.
203 204 205 |
# File 'lib/toys/utils/xdg.rb', line 203 def lookup_config(path, type: :file) lookup_internal([config_home] + config_dirs, path, type) end |
#lookup_data(path, type: :file) ⇒ Array<String>
Searches the data directories for an object with the given relative path, and returns an array of absolute paths to all objects found in the data directories (i.e. in #data_dirs or #data_home), in order from most to least important.
184 185 186 |
# File 'lib/toys/utils/xdg.rb', line 184 def lookup_data(path, type: :file) lookup_internal([data_home] + data_dirs, path, type) end |
#runtime_dir ⇒ String?
Returns the absolute path to the single base directory relative to
which user-specific runtime files and other file objects should be
placed. May return nil
if no such directory could be determined.
164 165 166 167 |
# File 'lib/toys/utils/xdg.rb', line 164 def runtime_dir @runtime_dir = validate_dir_env("XDG_RUNTIME_DIR") unless defined? @runtime_dir @runtime_dir end |
#state_home ⇒ String
Returns the absolute path to the single base directory relative to
which user-specific state files should be written.
Corresponds to the value of the $XDG_STATE_HOME
environment variable
and its defaults according to the XDG Base Directory Spec.
98 99 100 101 |
# File 'lib/toys/utils/xdg.rb', line 98 def state_home @state_home ||= validate_dir_env("XDG_STATE_HOME") || ::File.join(home_dir, ".local", "state") end |