|katherine 262bf71320 revise documentation for clarity||10 months ago|
|spec||11 months ago|
|src||10 months ago|
|.gitignore||11 months ago|
|LICENSE||11 months ago|
|README.md||10 months ago|
|shard.yml||10 months ago|
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 two low-level methods, which simply list the base directories of a certain type, as well as a helper method for easily building file paths relative to them.
First, add the dependency to your project’s
dependencies: xdg_basedir: github: shmibs/xdg_basedir
and then run
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 you want to 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 # files within the XDG Base Directories will typically be further sorted into # subdirectories, with those subdirectories named for the program or # application which "owns" them. This is not always the case however, and so it # isn't enforced read_path = XDGBasedir.full_path("program_name/file_name.conf", :config, :read) # the specification dictates that the locations of base directories should 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, and 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. the above # call to full_path will check through a hierarchy of fallback base # directories and, if it finds the target file in one of them, will return a # path into the directory where it was found. there is only one base # directory for writing config files, however, and so it is always returned # here. in practice, this means that the first time program_name is run, it # might read in some system-wide config file and then write back a # user-specific one 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
full_path method takes an argument type (set to
:config in the
example above). This argument indicates that only base directories containing
files of that type should be selected. There are four possible types:
:datadirectories are used for storing and retrieving persistent files across multiple runs of a program.
:configdirectories are used for storing and retrieving a program’s configuration files.
:cachedirectories are used for storing non-essential data which may or may not be retained
:runtimedirectories are used for storing runtime files (e.g. lock files or sockets)
Every method defined under
XDGBasedir takes one of these types as an
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.
This library is licensed under The MIT License.