From 9511acbce2bb97526098047ed75fd9de5046bdc8 Mon Sep 17 00:00:00 2001 From: katherine Date: Mon, 19 Nov 2018 19:45:08 -0700 Subject: =?UTF-8?q?initial=20commit!=20=E3=83=BD(^o^)=E4=B8=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..a72a85b --- /dev/null +++ b/README.md @@ -0,0 +1,110 @@ +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](https://specifications.freedesktop.org/basedir-spec/0.7/). + +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: + +```yaml +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: + +```crystal +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](https://opensource.org/licenses/MIT). -- cgit v1.2.3