XDG Standards for Ruby¶ ↑

Homepage | Source Code | Report Issue | Mailing List | Chat Room

<img src=“http://travis-ci.org/rubyworks/xdg.png” />

Introduction¶ ↑

XDG provides an easy to use Ruby library for working with XDG standards.

Presently, it only supports the XDG Base Directory Standard.

If your program utilizes user or system-wide support files (e.g. configuration files), you owe it to yourself to checkout the XDG base directory standard.

You can learn more about the standard at: standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

How to Use¶ ↑

For working with XDG base directories, XDG provides a very simple yet flexible interface, ‘XDG[]`. Let’s say you want to work with the $XDG_CONFIG_HOME directory. Simply use:

XDG['CONFIG_HOME']

This will give you access to a number of useful methods all tied into the user’s personal configuration directory. Some examples:

XDG['CONFIG_HOME'].glob(pattern)
XDG['CONFIG_HOME'].select(pattern){ |path| ... }
XDG['CONFIG_HOME'].find(pattern){ |path| ... }

The same holds true for the other base directories.

XDG['DATA_HOME']
XDG['DATA_DIRS']

XDG['CACHE_HOME']
XDG['CACHE_DIRS']

By leaving out the last qualifier, XDG will provide an interface that ties into both the ‘HOME` and `DIRS` paths.

XDG['DATA']
XDG['CONFIG']
XDG['CACHE']

If you know XDG these are pretty much self-explanatory. But see the YARD-based API documentation for further specifics.

Extended Functionality¶ ↑

The Ruby XDG module also provides extended functionality not part of the standard specification. These extensions are simply add-on functionality deemed useful, or implementations of proposals being discussed for a possible future version of the standard.

XDG['CONFIG_WORK']
XDG['CACHE_WORK']

See the API documentation to learn more. Note that the extended modules are subject to greater potential for change as they are still being refined.

Base Directory Mixin¶ ↑

XDG provides a convenient base directory mixin that can provide handy a interface to a classes.

class MyAppConfig
  include XDG::BaseDir::Mixin

  def subdirectory
    'myapp'
  end
end

c = MyAppConfig.new

c.config.home.to_s  #=> '~/.config/myapp'

Legacy API¶ ↑

Version 2.0+ of library marks a major departure from the earlier “fluid” notation of previous releases. Where as one used to do:

XDG.data.home

With the new API one now does:

XDG['DATA_HOME']

This was done for a few reasons, but primarily because it reflects more closely Ruby’s interface to the environment variables themselves, e.g.

ENV['XDG_DATA_HOME']

If you prefer the older style, a compatibility layer is provided. You will need to load:

require 'xdg/base_dir/legacy'

However we STRONGLY RECOMMEND that you do not use the legacy API –use it only if you need to keep some old code working and don’t have time to update it at the moment. Sometime in the future the legacy API will be deprecated.

How to Install¶ ↑

Using RubyGems:

$ sudo gem install xdg

Installing the tarball requires Ruby Setup (see rubyworks.github.com/setup).

$ tar -xvzf xdg-0.5.2
$ cd xdg-0.5.2
$ sudo setup.rb all

Development¶ ↑

GitHub hosts our source code and issue ticket system.

To contribute to the project please fork the repository, ideally, create a new topic branch for your work, and submit a pull request.

Copyright & License¶ ↑

Copyright © 2008 Rubyworks

Distributed under the terms of the FreeBSD license.

See COPYING.rdoc file for details.