for a given relative_path, get a full file path built against an appropriate base directory

This method takes a relative_path, the type of that path, and the action you intend to perform on it, and returns a full path, constructed by concatenating the relative_path to the most appropriate base directory. If an appropriate directory cannot be found, nil is returned.

The type argument indicates what sort of file you intend to access at the full path (:config, :data ...), and the action argument indicates what you intend to to do with it (either :read or :write). Note that :write takes precedence over :read, so that if you intend to both read and write, choose :write

Example

data = nil
path = XDGBasedir.full_path "relative/path.dat", :data, :read

if path
  data = File.read path
end

for a given relative_path, get a full file path built against an appropriate base directory

This method takes a relative_path, the type of that path, and the access mode with which that file is to be opened, and returns a full path, constructed by concatenating the relative_path to the most appropriate base directory. If an appropriate directory cannot be found, nil is returned.

The type indicates what sort of file you intend to access at the full path (:config, :data ...), and the mode argument is a string, in the common format used by both C's fopen and Crystal's File.open. For more information, refer to man fopen or the Crystal standard library documentation for File.

This overloaded version of .full_path is added for convenience, as, if you intend to call File.open on the produced full path, it might be easier to use the same mode argument for both methods.

Example

data = nil
mode = "r"
path = XDGBasedir.full_path "relative/path.dat", :data, mode

if path
  data = File.open(path, mode) do |file|
    file.gets_to_end
  end
end

get a list of base directories from which files of a given type can be read

Given a type of :data, :config, :cache, or :runtime, this method returns a string array of directories from which data of that type should be read. If no appropriate candidates are found, it instead returns nil.

The returned list will be ordered according to precedence. That is, given a returned list l, accessing a file should first be attempted from within l[0], if that fails, be attempted from within l[1], and so on.

If a directory list is returned, those directories are guaranteed to always have a terminating '/' character, meaning that, when trying to access a file, it is safe to directly concatenate the directory and the file path that is to be accessed within it.

Example

contents = nil
dir_list = XDGBasedir.read_dirs :config

if dir_list
  dir_list.each { |dir|
    if File.file? "#{dir}target/file.conf"
      contents = File.read "#{dir}target/file.conf"
      break
    end
  }
end

get the base directory into which files of a given type should be written

Given a type of :data, :config, :cache, or :runtime, this method returns a single directory into which data of that type should be written, or else nil, if no appropriate candidate is found.

If a directory is returned, it is guaranteed to always have a terminating '/' character, meaning that, when trying to write a file, it is safe to directly concatenate the directory and the file path that is to be written to within it.

Example

dir = XDGBasedir.write_dir :config
if dir
  File.write "#{dir}created/file.conf", "contents"
end