Commit 5d5c7f85 authored by Youhei SASAKI's avatar Youhei SASAKI

Import Upstream version 2.2.3

parents
---
type: ruby
revision: 2013
sources:
- Index.yml
authors:
- name: Trans
email: transfire@gmail.com
organizations:
- name: Rubyworks
requirements:
- groups:
- build
development: true
name: detroit
- groups:
- test
development: true
name: qed
- groups:
- test
development: true
name: ae
conflicts: []
alternatives: []
resources:
- type: home
uri: http://rubyworks.github.com/xdg
label: Homepage
- type: code
uri: http://github.com/rubyworks/xdg
label: Source Code
- type: mail
uri: http://groups.goole.com/rubyworks-mailinglist
label: Mailing List
repositories:
- name: upstream
scm: git
uri: git://github.com/rubyworks/xdg.git
categories: []
load_path:
- lib
copyrights:
- holder: Rubyworks
year: '2008'
license: BSD-2-Clause
name: xdg
title: XDG
version: 2.2.3
summary: XDG provides an interface for using XDG directory standard.
description: XDG provides a module for supporting the XDG Base Directory Standard.
See http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html
created: '2008-09-27'
date: '2012-12-12'
--title "YARD-Bird"
--readme README.md
--output-dir site/doc
--private
lib/**/*.rb -
*.md
*.txt
# XDG Base Directory Standard
The 2.0 API is much a great deal more concise than the original
0.0+ and 1.0+ APIs. It consists primarily of a single
interface method `XDG[]`. Yet all the functionality of the older
API remain and then some.
First we need to require the library.
require 'xdg'
In the applique we have setup a fake root directory with
coorepsonding environment settings to use as test fixtures.
## Data Paths
### Home
XDG['DATA_HOME'].environment.assert == ENV['XDG_DATA_HOME'].to_s
XDG['DATA_HOME'].environment_variables.assert == ['XDG_DATA_HOME']
Looking at the data home location by default it should be point to
our joe user's home directory under `.local/share`.
XDG['DATA_HOME'].to_a.assert == [$froot + 'home/joe/.local/share']
### Dirs
XDG['DATA_DIRS'].environment.assert == ENV['XDG_DATA_DIRS'].to_s
XDG['DATA_DIRS'].environment_variables.assert == ['XDG_DATA_DIRS']
Looking at the system data locations
XDG['DATA_DIRS'].to_a.assert == [$froot + 'usr/share']
### Combined
XDG['DATA'].environment_variables.assert == ['XDG_DATA_HOME', 'XDG_DATA_DIRS']
Lookking at both data location combined
XDG['DATA'].to_a.assert == [$froot + 'home/joe/.local/share', $froot + 'usr/share']
## Config Paths
### Home
XDG['CONFIG_HOME'].environment.assert == ENV['XDG_CONFIG_HOME'].to_s
XDG['CONFIG_HOME'].to_a.assert == [$froot + 'home/joe/.config']
### Dirs
XDG['CONFIG_DIRS'].environment.assert == ENV['XDG_CONFIG_DIRS'].to_s
XDG['CONFIG_DIRS'].to_a.assert == [$froot + 'etc/xdg', $froot + 'etc']
### Combined
XDG['CONFIG'].to_a.assert == [$froot + 'home/joe/.config', $froot + 'etc/xdg', $froot + 'etc']
## Cache Paths
### Home
XDG['CACHE_HOME'].environment.assert == ENV['XDG_CACHE_HOME'].to_s
XDG['CACHE_HOME'].to_a.assert == [$froot + 'home/joe/.cache']
### Dirs
XDG['CACHE_DIRS'].environment.assert == ENV['XDG_CACHE_DIRS'].to_s
XDG['CACHE_DIRS'].to_a.assert == [$froot + 'tmp']
### Combined
XDG['CACHE'].to_a.assert == [$froot + 'home/joe/.cache', $froot + 'tmp']
# Extended Base Directory Standard
The extended base directory standard provides additional locations
not apart the offical standard. These are somewhat experimental.
## Resource
XDG['RESOURCE_HOME'].environment.assert == ENV['XDG_RESOURCE_HOME'].to_s
XDG['RESOURCE_HOME'].environment_variables.assert == ['XDG_RESOURCE_HOME']
Looking at the data home location by default it should be pointing to
our joe users home directory under `.local`.
XDG['RESOURCE_HOME'].list.assert == ['~/.local']
XDG['RESOURCE_HOME'].to_a.assert == [$froot + 'home/joe/.local']
## Work
The working configuration directory
XDG['CONFIG_WORK'].environment.assert == ENV['XDG_CONFIG_WORK'].to_s
XDG['CONFIG_WORK'].environment_variables.assert == ['XDG_CONFIG_WORK']
Looking at the config work location, by default it should be pointing to
the current working directorys `.config` or `config` directory.
XDG['CONFIG_WORK'].list.assert == ['.config', 'config']
XDG['CONFIG_WORK'].to_a.assert == [Dir.pwd + '/.config', Dir.pwd + '/config']
The working cache directory
XDG['CACHE_WORK'].environment.assert == ENV['XDG_CACHE_WORK'].to_s
XDG['CACHE_WORK'].environment_variables.assert == ['XDG_CACHE_WORK']
Looking at the cache work location, by default it should be pointing to
the current working directorys `.tmp` or `tmp` directory.
XDG['CACHE_WORK'].list.assert == ['.tmp', 'tmp']
XDG['CACHE_WORK'].to_a.assert == [Dir.pwd + '/.tmp', Dir.pwd + '/tmp']
# Base Directory Mixin
The base directory mixin is used to easy augment a class for
access to a named subdirectory of the XDG directories.
class MyAppConfig
include XDG::BaseDir::Mixin
def subdirectory
'myapp'
end
end
c = MyAppConfig.new
c.config.home.to_a #=> [$froot + 'home/joe/.config/myapp']
# RELEASE HISTORY
## 2.2.3 / 2012-12-13
This release switches to RbConfig instead of Config, which Ruby
is deprecating.
Changes:
* Switch Config to RbConfig.
## 2.2.2 / 2011-10-30
Just a maintenance release to bring the build configuration
up to date. Also, change license to BSD-2-Clause.
Changes:
* Modernize build configuration
* Switch to BSD-2-Clause license.
## 2.2.1 / 2011-06-11
This release changes BaseDir#to_s to return the first directory
entry, and moves the old #to_s to #environment_with_defaults
with an alias of #env. The old #env now being called #environment.
Changes:
* Rename #env to #environment.
* Rename #to_s to #environment_with_defaults.
* Modify #to_s to return first directory.
## 2.1.0 / 2011-06-09
This release changes the BaseDir#list method, where as it used
to be an alias for #to_a, it now differs in that it does not
expand the paths. In addtion a few tests were fixed and version
number properly updated int hte version.rb file.
Changes:
* Change BaseDir#list to not expand paths.
* Properly assign VERSION constant.
* Fix broken qed tests.
## 2.0.0 / 2011-06-09
Major new release is full rewrite of the API, with an eye out for
support future XDG standards beyond the base directories. The
new API uses a single point of entry `XDG[]` (a shortcut for
`XDG::BaseDir[]`).
Changes:
* Complete rewrite of API.
* Utilize single point of entry interface.
* Structure project for future support of more of XDG.
## 1.0.0 / 2009-12-01
This is major reimplementation of the XDG API to be more flexiable
and object-oriented. Instead of a single module with every
needed method, the system is devided up into sub-modules, one for
each set of XDG locations. So, for example, instead of "XDG.data_dirs"
you use "XDG::Data.dirs" or "XDG.data.dirs".
Changes:
* Reworked API and underlying implementation to be more OOP-style.
* Began work on xdg/extended.rb, exploring future proposals.
* Provides xdg/compat.rb, for backward compatabilty (temporary).
## 0.5.2 / 2009-05-30
This release requires rbconfig.rb and uses system entries in place of
some hardcoded FHS locations.
Changes:
* Replaced hardcoded system directories with rbconfig entries.
## 0.5.1 / 2008-11-17
Changes:
* Fixed data work directory is '.local', not '.share'
* Deprecated #data_work
## 0.5.0 / 2008-10-28
Changes:
* Changed _glob to _select
## 0.4.0 / 2008-10-26
This release removes the xdg_ prefix from the instance-level
method names. Now module and instance levels are the same.
Also, data_file, config_file and cache_file have been replaced with
data_find, config_find, cache_find, data_glob, config_glob and
cache_glob.
What's next? Well, I can't say I'm fond of the term 'glob', so I
may rename that to 'map' or 'collect' (or 'select'?) and then
add the ability to use blocks for matching too.
Changes:
* Renamed instance level methods without 'xdg_' prefix.
* Replace _file methods with _find and _glob methods.
* Prepare for v0.4 release
* Remove some old commented-out code
* Fixed data_find and data_glob
* Update RELEASE file
* Updated documentation for 0.4 release
* Added MANIFEST to .gitignore
* Correction or RELEASE
* Fixed plural in RELEASE file
## 0.3.0 / 2008-10-11
Changes:
* Removed xdg_ prefix from module methods
* Moved web/index.html to doc directory
* Updated reap serives
* Prepare for next release
* Fixed issue of xdg_ prefix still being used internally
## 0.1.0 / 2008-09-27
Changes:
* Started project
BSD-2-Clause License
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
# XDG Standards for Ruby
[Homepage](http://rubyworks.github.com/xdg) |
[Source Code](http://github.com/rubyworks/xdg) |
[Report Issue](http://github.com/rubyworks/xdg/issues) |
[Mailing List](http://googlegroups.com/group.rubyworks-mailinglist) |
[Chat Room](irc://irc.freenode.net/rubyworks)
[![Build Status](https://secure.travis-ci.org/rubyworks/xdg.png)](http://travis-ci.org/rubyworks/xdg)
## 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:
http://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 http://rubyworks.github.com/setup).
$ tar -xvzf xdg-0.5.2
$ cd xdg-0.5.2
$ sudo setup.rb all
## Development
[GitHub](http://github.com) hosts our [source code](http://github.com/rubyworks/xdg)
and [issue ticket system](http://github.com/rubyworks/xdg/issues).
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 (c) 2008 Rubyworks
Distributed under the terms of the *FreeBSD* license.
See LICENSE.txt file for details.
# XDG Base Directory Standard
The 2.0 API is much a great deal more concise than the original
0.0+ and 1.0+ APIs. It consists primarily of a single
interface method `XDG[]`. Yet all the functionality of the older
API remain and then some.
First we need to require the library.
require 'xdg'
In the applique we have setup a fake root directory with
coorepsonding environment settings to use as test fixtures.
## Data Paths
### Home
XDG['DATA_HOME'].environment.assert == ENV['XDG_DATA_HOME'].to_s
XDG['DATA_HOME'].environment_variables.assert == ['XDG_DATA_HOME']
Looking at the data home location by default it should be point to
our joe user's home directory under `.local/share`.
XDG['DATA_HOME'].to_a.assert == [$froot + 'home/joe/.local/share']
### Dirs
XDG['DATA_DIRS'].environment.assert == ENV['XDG_DATA_DIRS'].to_s
XDG['DATA_DIRS'].environment_variables.assert == ['XDG_DATA_DIRS']
Looking at the system data locations
XDG['DATA_DIRS'].to_a.assert == [$froot + 'usr/share']
### Combined
XDG['DATA'].environment_variables.assert == ['XDG_DATA_HOME', 'XDG_DATA_DIRS']
Lookking at both data location combined
XDG['DATA'].to_a.assert == [$froot + 'home/joe/.local/share', $froot + 'usr/share']
## Config Paths
### Home
XDG['CONFIG_HOME'].environment.assert == ENV['XDG_CONFIG_HOME'].to_s
XDG['CONFIG_HOME'].to_a.assert == [$froot + 'home/joe/.config']
### Dirs
XDG['CONFIG_DIRS'].environment.assert == ENV['XDG_CONFIG_DIRS'].to_s
XDG['CONFIG_DIRS'].to_a.assert == [$froot + 'etc/xdg', $froot + 'etc']
### Combined
XDG['CONFIG'].to_a.assert == [$froot + 'home/joe/.config', $froot + 'etc/xdg', $froot + 'etc']
## Cache Paths
### Home
XDG['CACHE_HOME'].environment.assert == ENV['XDG_CACHE_HOME'].to_s
XDG['CACHE_HOME'].to_a.assert == [$froot + 'home/joe/.cache']
### Dirs
XDG['CACHE_DIRS'].environment.assert == ENV['XDG_CACHE_DIRS'].to_s
XDG['CACHE_DIRS'].to_a.assert == [$froot + 'tmp']
### Combined
XDG['CACHE'].to_a.assert == [$froot + 'home/joe/.cache', $froot + 'tmp']
# Extended Base Directory Standard
The extended base directory standard provides additional locations
not apart the offical standard. These are somewhat experimental.
## Resource
XDG['RESOURCE_HOME'].environment.assert == ENV['XDG_RESOURCE_HOME'].to_s
XDG['RESOURCE_HOME'].environment_variables.assert == ['XDG_RESOURCE_HOME']
Looking at the data home location by default it should be pointing to
our joe users home directory under `.local`.
XDG['RESOURCE_HOME'].list.assert == ['~/.local']
XDG['RESOURCE_HOME'].to_a.assert == [$froot + 'home/joe/.local']
## Work
The working configuration directory
XDG['CONFIG_WORK'].environment.assert == ENV['XDG_CONFIG_WORK'].to_s
XDG['CONFIG_WORK'].environment_variables.assert == ['XDG_CONFIG_WORK']
Looking at the config work location, by default it should be pointing to
the current working directorys `.config` or `config` directory.
XDG['CONFIG_WORK'].list.assert == ['.config', 'config']
XDG['CONFIG_WORK'].to_a.assert == [Dir.pwd + '/.config', Dir.pwd + '/config']
The working cache directory
XDG['CACHE_WORK'].environment.assert == ENV['XDG_CACHE_WORK'].to_s
XDG['CACHE_WORK'].environment_variables.assert == ['XDG_CACHE_WORK']
Looking at the cache work location, by default it should be pointing to
the current working directorys `.tmp` or `tmp` directory.
XDG['CACHE_WORK'].list.assert == ['.tmp', 'tmp']
XDG['CACHE_WORK'].to_a.assert == [Dir.pwd + '/.tmp', Dir.pwd + '/tmp']
# Base Directory Mixin
The base directory mixin is used to easy augment a class for
access to a named subdirectory of the XDG directories.
class MyAppConfig
include XDG::BaseDir::Mixin
def subdirectory
'myapp'
end
end
c = MyAppConfig.new
c.config.home.to_a #=> [$froot + 'home/joe/.config/myapp']
require 'ae'
AE.ansi = false
require 'fileutils'
dir = File.expand_path(File.dirname(File.dirname(__FILE__)))
$froot = File.join(dir, 'fixtures/fakeroot/')
puts "Fake root at: `#{$froot}'."
#
ENV['HOME'] = $froot + 'home/joe'
#ENV['XDG_DATA_HOME'] = $froot + '.local/share'
ENV['XDG_DATA_DIRS'] = $froot + 'usr/share'
#ENV['XDG_CONFIG_HOME'] = $froot + '.config'
ENV['XDG_CONFIG_DIRS'] = $froot + 'etc/xdg' + ':' + $froot + 'etc'
#ENV['XDG_CACHE_HOME'] = $froot + '.cache'
ENV['XDG_CACHE_DIRS'] = $froot + 'tmp'
Just here to provide a file for github to keep this directory.
# XDG Base Directory Standard
#
# This provides a conveient library for conforming to the
# XDG Base Directory Standard.
#
# http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
#
# Some important clarifications, not made clear by the above specification.
#
# The data directories are for "read-only" files. In other words once
# something is put there, it should only be read, and never written to
# by a program. (Generally speaking only users or package managers should
# be adding, changing or removing files from the data locations.)
#
# The config locations are where you store files that may change,
# and effect your applications depending on their content. This is like
# etc/ in the FHS, but alterable by end users and end user programs,
# not just root and sudo admin scripts.
#
# The cache locations stores files that could just as well be deleted
# and everything would still work fine. This is for variable and
# temporary files. Much like var/ and tmp/ in FHS.
#
# The module returns all paths as String.
#
module XDG
if RUBY_VERSION > '1.9'
require_relative 'xdg/version'
require_relative 'xdg/base_dir'
require_relative 'xdg/base_dir/extended'
require_relative 'xdg/base_dir/mixin'
else
require 'xdg/version'
require 'xdg/base_dir'
require 'xdg/base_dir/extended'
require 'xdg/base_dir/mixin'
end
#
def self.[](*env_path)
BaseDir.new(*env_path)
end
end
# Copyright (c) 2008 Rubyworks
module XDG
# Base Directory Standard
class BaseDir
# Try to get information from Ruby's install configuration.
require 'rbconfig'
sysconfdir = ::RbConfig::CONFIG['sysconfdir'] || '/etc'
datadir = ::RbConfig::CONFIG['datadir'] || '/usr/share'
# Standard defaults for locations.
DEFAULTS = {
'XDG_DATA_HOME' => ['~/.local/share'],
'XDG_DATA_DIRS' => ['/usr/local/share', datadir],
'XDG_CONFIG_HOME' => ['~/.config'],
'XDG_CONFIG_DIRS' => [File.join(sysconfdir,'xdg'), sysconfdir],
'XDG_CACHE_HOME' => ['~/.cache'],
'XDG_CACHE_DIRS' => ['/tmp']
}