Class: Toys::Utils::XDG

Inherits:
Object
  • Object
show all
Defined in:
core-docs/toys/utils/xdg.rb

Overview

Defined in the toys-core gem

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

Constructor Details

#initialize(env: ::ENV) ⇒ XDG

Create an instance of XDG.

Parameters:

  • env (Hash{String=>String}) (defaults to: ::ENV) —

    the environment variables. Normally, you can omit this argument, as it will default to ::ENV.



50
51
52
 
# File 'core-docs/toys/utils/xdg.rb', line 50

def initialize(env: ::ENV)
  # Source available in the toys-core gem
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.

Returns:

  • (String) 


107
108
109
 
# File 'core-docs/toys/utils/xdg.rb', line 107

def cache_home
  # Source available in the toys-core gem
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.

Returns:

  • (Array<String>) 


147
148
149
 
# File 'core-docs/toys/utils/xdg.rb', line 147

def config_dirs
  # Source available in the toys-core gem
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.

Returns:

  • (String) 


83
84
85
 
# File 'core-docs/toys/utils/xdg.rb', line 83

def config_home
  # Source available in the toys-core gem
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.

Returns:

  • (Array<String>) 


133
134
135
 
# File 'core-docs/toys/utils/xdg.rb', line 133

def data_dirs
  # Source available in the toys-core gem
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.

Returns:

  • (String) 


71
72
73
 
# File 'core-docs/toys/utils/xdg.rb', line 71

def data_home
  # Source available in the toys-core gem
end

#ensure_cache_subdir(path) ⇒ String

Returns the absolute path to a directory under #cache_home, creating it if it doesn't already exist.

Parameters:

  • path (String) —

    The relative path to the subdir within the base cache directory.

Returns:

  • (String) —

    The absolute path to the subdir.

Raises:

  • (Errno::EEXIST) —

    If a non-directory already exists there



248
249
250
 
# File 'core-docs/toys/utils/xdg.rb', line 248

def ensure_cache_subdir(path)
  # Source available in the toys-core gem
end

#ensure_config_subdir(path) ⇒ String

Returns the absolute path to a directory under #config_home, creating it if it doesn't already exist.

Parameters:

  • path (String) —

    The relative path to the subdir within the base config directory.

Returns:

  • (String) —

    The absolute path to the subdir.

Raises:

  • (Errno::EEXIST) —

    If a non-directory already exists there



222
223
224
 
# File 'core-docs/toys/utils/xdg.rb', line 222

def ensure_config_subdir(path)
  # Source available in the toys-core gem
end

#ensure_data_subdir(path) ⇒ String

Returns the absolute path to a directory under #data_home, creating it if it doesn't already exist.

Parameters:

  • path (String) —

    The relative path to the subdir within the base data directory.

Returns:

  • (String) —

    The absolute path to the subdir.

Raises:

  • (Errno::EEXIST) —

    If a non-directory already exists there



209
210
211
 
# File 'core-docs/toys/utils/xdg.rb', line 209

def ensure_data_subdir(path)
  # Source available in the toys-core gem
end

#ensure_state_subdir(path) ⇒ String

Returns the absolute path to a directory under #state_home, creating it if it doesn't already exist.

Parameters:

  • path (String) —

    The relative path to the subdir within the base state directory.

Returns:

  • (String) —

    The absolute path to the subdir.

Raises:

  • (Errno::EEXIST) —

    If a non-directory already exists there



235
236
237
 
# File 'core-docs/toys/utils/xdg.rb', line 235

def ensure_state_subdir(path)
  # Source available in the toys-core gem
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.

Returns:

  • (String) 


119
120
121
 
# File 'core-docs/toys/utils/xdg.rb', line 119

def executable_home
  # Source available in the toys-core gem
end

#home_dir ⇒ String

Returns the absolute path to the current user's home directory.

Returns:

  • (String) 


59
60
61
 
# File 'core-docs/toys/utils/xdg.rb', line 59

def home_dir
  # Source available in the toys-core gem
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.

Parameters:

  • path (String) —

    Relative path of the object to search for

  • type (String, Symbol, Array<String,Symbol>) (defaults to: :file) —

    The type(s) of objects to find. You can specify any of the types defined by File::Stat#ftype, such as file or directory, or the special type any. Types can be specified as strings or the corresponding symbols. If this argument is not provided, the default of file is used.

Returns:

  • (Array<String>) 


196
197
198
 
# File 'core-docs/toys/utils/xdg.rb', line 196

def lookup_config(path, type: :file)
  # Source available in the toys-core gem
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.

Parameters:

  • path (String) —

    Relative path of the object to search for

  • type (String, Symbol, Array<String,Symbol>) (defaults to: :file) —

    The type(s) of objects to find. You can specify any of the types defined by File::Stat#ftype, such as file or directory, or the special type any. Types can be specified as strings or the corresponding symbols. If this argument is not provided, the default of file is used.

Returns:

  • (Array<String>) 


177
178
179
 
# File 'core-docs/toys/utils/xdg.rb', line 177

def lookup_data(path, type: :file)
  # Source available in the toys-core gem
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.

Returns:

  • (String, nil) 


158
159
160
 
# File 'core-docs/toys/utils/xdg.rb', line 158

def runtime_dir
  # Source available in the toys-core gem
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.

Returns:

  • (String) 


95
96
97
 
# File 'core-docs/toys/utils/xdg.rb', line 95

def state_home
  # Source available in the toys-core gem
end