xdg_basedir

This is a simple crystal interface to the XDG Base Directories. It is based on the XDG Base Directory Specification, the latest version of which (0.7) can be found here.

The XDG Base Directories Specification is a definition of the directories where things like a program's configuration files and stored data ought to be written to and read from, along with the order of precedence to be used when searching for those kinds of files. If you've ever seen a program that stores its configurations in the .config directory, that program is, at least in part, following this specification.

This crystal interface to the specification provides methods for simply listing the base directories, as well as a helper method for easily building file paths relative to them.

installation

First, add the dependency to your project's shard.yml file:

dependencies:
  xdg_basedir:
    github: shmibs/xdg_basedir

and then run shards install.

usage

Suppose you're writing a program called program_name, and you want to read one of its configuration files, file_name.conf. After reading, you want to perform some operation on the contents of the file, and then write the new contents back to file_name.conf. Using this module, that might look something like the following:

require "xdg_basedir"

# Note: for simplicity's sake, exception handling has been ignored for the
# calls to File.read and File.write

# typically, files in the XDG Base Directories will be first sorted into
# directories, based on the program that uses them. This isn't always the case
# however, and so it is not enforced
read_path = XDGBasedir.full_path("program_name/file_name.conf", :config, :read)

# the specification dictates that base directory locations be determined using
# both the state of the filesystem and the state of certain environment
# variables. it's thus possible that an appropriate base directory won't be
# found, so a nil check is required
if read_path
  contents = File.read(read_path)

  # ...do something with the contents here...

  # write_path here is not necessarily the same as read_path above. full_path
  # above will check through the hierarchy of fallback base directories and, if
  # it finds the target, return the path into the directory where it was found.
  # there is only one base directory for writing, however, and so it is always
  # returned here. this means that the first time program_name is run, it might
  # read in some system-wide config, write back a user-specific config, and
  # then read the user-specific version thereafter
  write_path = XDGBasedir.full_path("program_name/file_name.conf", :config,
                                    :write)

  # again, nil check necessary...
  if write_path
    File.write(write_path, contents)
  end
end

The full_path method takes an argument type, which was set above to :config. This argument indicates the type of files that are stored in the base directory that should be selected. There are four possible types:

• :data directories are used for storing and retrieving persistent files across multiple runs of a program.
• :config directories are used for storing and retrieving a program's configuration files.
• :cache directories are used for storing non-essential data which may or may not be retained
• :runtime directories are used for storing runtime files (e.g. lock files or sockets)

Every method defined under XDGBasedir takes one of these types as an argument.

In addition to full_path, two lower-level methods are also provided:

• write_dir, which returns the single directory where files of a given type should be written
• read_dirs, which returns a hierarchical list of base directories from which files of a given type should be read

However, these two methods will probably be less useful.

license

This library is licensed under The MIT License.