1 files changed, 110 insertions, 0 deletions
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).