xdg 0.1.0

data/COPYING

@@ -0,0 +1,168 @@
+.
+
+		            GNU LESSER GENERAL PUBLIC LICENSE
+                     Version 3, 29 June 2007
+
+   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+   Everyone is permitted to copy and distribute verbatim copies
+   of this license document, but changing it is not allowed.
+
+
+    This version of the GNU Lesser General Public License incorporates
+  the terms and conditions of version 3 of the GNU General Public
+  License, supplemented by the additional permissions listed below.
+
+    0. Additional Definitions. 
+
+    As used herein, "this License" refers to version 3 of the GNU Lesser
+  General Public License, and the "GNU GPL" refers to version 3 of the GNU
+  General Public License.
+
+    "The Library" refers to a covered work governed by this License,
+  other than an Application or a Combined Work as defined below.
+
+    An "Application" is any work that makes use of an interface provided
+  by the Library, but which is not otherwise based on the Library.
+  Defining a subclass of a class defined by the Library is deemed a mode
+  of using an interface provided by the Library.
+
+    A "Combined Work" is a work produced by combining or linking an
+  Application with the Library.  The particular version of the Library
+  with which the Combined Work was made is also called the "Linked
+  Version".
+
+    The "Minimal Corresponding Source" for a Combined Work means the
+  Corresponding Source for the Combined Work, excluding any source code
+  for portions of the Combined Work that, considered in isolation, are
+  based on the Application, and not on the Linked Version.
+
+    The "Corresponding Application Code" for a Combined Work means the
+  object code and/or source code for the Application, including any data
+  and utility programs needed for reproducing the Combined Work from the
+  Application, but excluding the System Libraries of the Combined Work.
+
+    1. Exception to Section 3 of the GNU GPL.
+
+    You may convey a covered work under sections 3 and 4 of this License
+  without being bound by section 3 of the GNU GPL.
+
+    2. Conveying Modified Versions.
+
+    If you modify a copy of the Library, and, in your modifications, a
+  facility refers to a function or data to be supplied by an Application
+  that uses the facility (other than as an argument passed when the
+  facility is invoked), then you may convey a copy of the modified
+  version:
+
+     a) under this License, provided that you make a good faith effort to
+     ensure that, in the event an Application does not supply the
+     function or data, the facility still operates, and performs
+     whatever part of its purpose remains meaningful, or
+
+     b) under the GNU GPL, with none of the additional permissions of
+     this License applicable to that copy.
+
+    3. Object Code Incorporating Material from Library Header Files.
+
+    The object code form of an Application may incorporate material from
+  a header file that is part of the Library.  You may convey such object
+  code under terms of your choice, provided that, if the incorporated
+  material is not limited to numerical parameters, data structure
+  layouts and accessors, or small macros, inline functions and templates
+  (ten or fewer lines in length), you do both of the following:
+
+     a) Give prominent notice with each copy of the object code that the
+     Library is used in it and that the Library and its use are
+     covered by this License.
+
+     b) Accompany the object code with a copy of the GNU GPL and this license
+     document.
+
+    4. Combined Works.
+
+    You may convey a Combined Work under terms of your choice that,
+  taken together, effectively do not restrict modification of the
+  portions of the Library contained in the Combined Work and reverse
+  engineering for debugging such modifications, if you also do each of
+  the following:
+
+     a) Give prominent notice with each copy of the Combined Work that
+     the Library is used in it and that the Library and its use are
+     covered by this License.
+
+     b) Accompany the Combined Work with a copy of the GNU GPL and this license
+     document.
+
+     c) For a Combined Work that displays copyright notices during
+     execution, include the copyright notice for the Library among
+     these notices, as well as a reference directing the user to the
+     copies of the GNU GPL and this license document.
+
+     d) Do one of the following:
+
+         0) Convey the Minimal Corresponding Source under the terms of this
+         License, and the Corresponding Application Code in a form
+         suitable for, and under terms that permit, the user to
+         recombine or relink the Application with a modified version of
+         the Linked Version to produce a modified Combined Work, in the
+         manner specified by section 6 of the GNU GPL for conveying
+         Corresponding Source.
+
+         1) Use a suitable shared library mechanism for linking with the
+         Library.  A suitable mechanism is one that (a) uses at run time
+         a copy of the Library already present on the user's computer
+         system, and (b) will operate properly with a modified version
+         of the Library that is interface-compatible with the Linked
+         Version. 
+
+     e) Provide Installation Information, but only if you would otherwise
+     be required to provide such information under section 6 of the
+     GNU GPL, and only to the extent that such information is
+     necessary to install and execute a modified version of the
+     Combined Work produced by recombining or relinking the
+     Application with a modified version of the Linked Version. (If
+     you use option 4d0, the Installation Information must accompany
+     the Minimal Corresponding Source and Corresponding Application
+     Code. If you use option 4d1, you must provide the Installation
+     Information in the manner specified by section 6 of the GNU GPL
+     for conveying Corresponding Source.)
+
+    5. Combined Libraries.
+
+    You may place library facilities that are a work based on the
+  Library side by side in a single library together with other library
+  facilities that are not Applications and are not covered by this
+  License, and convey such a combined library under terms of your
+  choice, if you do both of the following:
+
+     a) Accompany the combined library with a copy of the same work based
+     on the Library, uncombined with any other library facilities,
+     conveyed under the terms of this License.
+
+     b) Give prominent notice with the combined library that part of it
+     is a work based on the Library, and explaining where to find the
+     accompanying uncombined form of the same work.
+
+    6. Revised Versions of the GNU Lesser General Public License.
+
+    The Free Software Foundation may publish revised and/or new versions
+  of the GNU Lesser General Public License from time to time. Such new
+  versions will be similar in spirit to the present version, but may
+  differ in detail to address new problems or concerns.
+
+    Each version is given a distinguishing version number. If the
+  Library as you received it specifies that a certain numbered version
+  of the GNU Lesser General Public License "or any later version"
+  applies to it, you have the option of following the terms and
+  conditions either of that published version or of any later version
+  published by the Free Software Foundation. If the Library as you
+  received it does not specify a version number of the GNU Lesser
+  General Public License, you may choose any version of the GNU Lesser
+  General Public License ever published by the Free Software Foundation.
+
+    If the Library as you received it specifies that a proxy can decide
+  whether future versions of the GNU Lesser General Public License shall
+  apply, that proxy's public statement of acceptance of any version is
+  permanent authorization for you to choose that version for the
+  Library.
+

data/MANIFEST

@@ -0,0 +1,17 @@
+doc
+doc/book
+doc/book/basedir-spec-0.6.html
+test
+RELEASE
+README
+meta
+meta/homepage
+meta/summary
+meta/abstract
+meta/releases
+meta/authors
+meta/contact
+lib
+lib/xdg.rb
+VERSION
+COPYING

data/README

@@ -0,0 +1,36 @@
+= XDG
+
+XDG provides an easy to use interface for utilizing
+the XDG Base Base Directory Standards.
+
+== Usage
+
+XDG is a module with a small set of easy to understand
+module methods, so it very easy to use.
+
+See RDOC's for more information.
+
+== Installation
+
+=== RubyGems
+
+  $ gem install xdg
+
+=== Tarball
+
+Installing the tarball requires Ruby Setup
+(see http://setup.rubyforge.org).
+
+  $ tar -xvzf xdg-0.1.0
+  $ cd xdg-0.1.0
+  $ setup.rb all
+
+== Development
+
+Visit http://rubyforge.org/projects/xdg
+
+== Copyright
+
+Copyright (c) 2008 Tiger Ops / 7rans
+Distributed under the terms of the MIT license.
+

data/RELEASE

@@ -0,0 +1,5 @@
+This is the initial release of XDG.
+
+XDG provides a straight-forward interface for supporting
+the XDG Base Directory Standard.
+

data/VERSION

@@ -0,0 +1 @@
+xdg 0.1.0 beta (2008-09-27)

data/doc/book/basedir-spec-0.6.html

@@ -0,0 +1,138 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>XDG Base Directory Specification</title><meta name="generator" content="DocBook XSL Stylesheets V1.66.1"></head><body link="#0000ff" alink="#0000ff" bgcolor="white" text="black" vlink="#840084"><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="index"></a>XDG Base Directory Specification</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Waldo</span> <span class="surname">Bastian</span></h3><div class="affiliation"><div class="address"><p><br>
+	&nbsp;&nbsp;&nbsp;&nbsp;<tt class="email">&lt;<a href="mailto:bastian@kde.org">bastian@kde.org</a>&gt;</tt><br>
+	&nbsp;&nbsp;</p></div></div></div></div></div><div><p class="releaseinfo">Version 0.6</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#introduction">Introduction</a></span></dt><dt><span class="sect1"><a href="#basics">Basics</a></span></dt><dt><span class="sect1"><a href="#variables">Environment variables</a></span></dt><dt><span class="sect1"><a href="#referencing">Referencing this specification</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both;"><a name="introduction"></a>Introduction</h2></div></div></div><p>
+      Various specifications specify files and file formats. This 
+      specification defines where these files should be looked for by 
+      defining one or more base directories relative to which files 
+      should be located. 
+    </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both;"><a name="basics"></a>Basics</h2></div></div></div><p>
+      The XDG Base Directory Specification is based on the following concepts: 
+      </p><div class="itemizedlist"><ul type="disc"><li><p>
+            There is a single base directory relative to which user-specific
+            data files should be written. This directory is defined by the
+            environment variable <tt class="literal">$XDG_DATA_HOME</tt>.
+          </p></li><li><p>
+            There is a single base directory relative to which user-specific
+            configuration files should be written. This directory is defined by the
+            environment variable <tt class="literal">$XDG_CONFIG_HOME</tt>.
+          </p></li><li><p>
+            There is a set of preference ordered base directories relative to
+            which data files should be searched.  This set of directories is defined
+            by the environment variable <tt class="literal">$XDG_DATA_DIRS</tt>.
+          </p></li><li><p>
+            There is a set of preference ordered base directories relative to
+            which configuration files should be searched.  
+            This set of directories is defined
+            by the environment variable <tt class="literal">$XDG_CONFIG_DIRS</tt>.
+          </p></li><li><p>
+            There is a single base directory relative to which user-specific
+            non-essential (cached) data should be written. 
+            This directory is defined by the
+            environment variable <tt class="literal">$XDG_CACHE_HOME</tt>.
+          </p></li></ul></div><p>
+    </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both;"><a name="variables"></a>Environment variables</h2></div></div></div><p>
+      <tt class="literal">$XDG_DATA_HOME</tt> defines the base directory relative to
+      which user specific data files should be stored. If
+      <tt class="literal">$XDG_DATA_HOME</tt> is either not set or empty, a default equal to
+      <tt class="literal">$HOME</tt>/.local/share should be used.
+    </p><p>
+      <tt class="literal">$XDG_CONFIG_HOME</tt> defines the base directory relative to
+      which user specific configuration files should be stored. If
+      <tt class="literal">$XDG_CONFIG_HOME</tt> is either not set or empty, a default equal to
+      <tt class="literal">$HOME</tt>/.config should be used.
+    </p><p>
+      <tt class="literal">$XDG_DATA_DIRS</tt> defines the preference-ordered set of
+      base directories to search for data files in addition to the 
+      <tt class="literal">$XDG_DATA_HOME</tt> base directory.
+      The directories in <tt class="literal">$XDG_DATA_DIRS</tt> should be seperated 
+      with a colon ':'.
+    </p><p>
+      If <tt class="literal">$XDG_DATA_DIRS</tt> is either not set or empty, a value equal to
+      /usr/local/share/:/usr/share/ should be used. 
+    </p><p>
+      <tt class="literal">$XDG_CONFIG_DIRS</tt> defines the preference-ordered set of
+      base directories to search for configuration files in addition to the 
+      <tt class="literal">$XDG_CONFIG_HOME</tt> base directory.
+      The directories in <tt class="literal">$XDG_CONFIG_DIRS</tt> should be seperated 
+      with a colon ':'.
+    </p><p>
+      If <tt class="literal">$XDG_CONFIG_DIRS</tt> is either not set or empty, a value equal to
+      /etc/xdg should be used. 
+    </p><p>
+      The order of base directories denotes their importance; the first
+      directory listed is the most important. When the same information is
+      defined in multiple places the information defined relative to the more
+      important base directory takes precedent. The base directory defined
+      by <tt class="literal">$XDG_DATA_HOME</tt> is considered more important than 
+      any of the base directories defined by <tt class="literal">$XDG_DATA_DIRS</tt>.
+      The base directory defined
+      by <tt class="literal">$XDG_CONFIG_HOME</tt> is considered more important than
+      any of the base directories defined by <tt class="literal">$XDG_CONFIG_DIRS</tt>.
+    </p><p>
+      <tt class="literal">$XDG_CACHE_HOME</tt> defines the base directory relative to
+      which user specific non-essential data files should be stored. If
+      <tt class="literal">$XDG_CACHE_HOME</tt> is either not set or empty, a default equal to
+      <tt class="literal">$HOME</tt>/.cache should be used.
+    </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both;"><a name="referencing"></a>Referencing this specification</h2></div></div></div><p>
+      Other specifications may reference this specification by specifying the
+      location of a data file as
+      <tt class="literal">$XDG_DATA_DIRS</tt>/subdir/filename. This implies that:
+      </p><div class="itemizedlist"><ul type="disc"><li><p>
+            Such file should be installed to <tt class="literal">$datadir</tt>/subdir/filename
+            with <tt class="literal">$datadir</tt> defaulting to /usr/share.
+          </p></li><li><p>
+            A user specific version of the data file may be created in
+            <tt class="literal">$XDG_DATA_HOME</tt>/subdir/filename, taking into
+            account the default value for <tt class="literal">$XDG_DATA_HOME</tt> if
+            <tt class="literal">$XDG_DATA_HOME</tt> is not set.
+          </p></li><li><p>
+            Lookups of the data file should search for ./subdir/filename relative to
+            all base directories specified by <tt class="literal">$XDG_DATA_HOME</tt> and 
+            <tt class="literal">$XDG_DATA_DIRS</tt> . If an environment 
+            variable is either not set or empty, its default value as defined by this specification 
+            should be used instead.
+          </p></li></ul></div><p>
+    </p><p>
+      Specifications may reference this specification by specifying the
+      location of a configuration file as
+      <tt class="literal">$XDG_CONFIG_DIRS</tt>/subdir/filename. This implies that:
+      </p><div class="itemizedlist"><ul type="disc"><li><p>
+            Default configuration files should be installed to <tt class="literal">$sysconfdir</tt>/xdg/subdir/filename
+            with <tt class="literal">$sysconfdir</tt> defaulting to /etc.
+          </p></li><li><p>
+            A user specific version of the configuration file may be created in
+            <tt class="literal">$XDG_CONFIG_HOME</tt>/subdir/filename, taking into
+            account the default value for <tt class="literal">$XDG_CONFIG_HOME</tt> if
+            <tt class="literal">$XDG_CONFIG_HOME</tt> is not set.
+          </p></li><li><p>
+            Lookups of the configuration file should search for ./subdir/filename relative to
+            all base directories indicated by <tt class="literal">$XDG_CONFIG_HOME</tt> and 
+            <tt class="literal">$XDG_CONFIG_DIRS</tt> . If an environment 
+            variable is either not set or empty, its default value as defined by this specification 
+            should be used instead.
+          </p></li></ul></div><p>
+    </p><p>
+      If, when attempting to write a file, the destination 
+      directory is non-existant an attempt should be made to create it 
+      with permission <tt class="literal">0700</tt>. If the destination directory
+      exists already the permissions should not be changed.
+      The application should be prepared to handle the case where the file 
+      could not be written, either because the directory was non-existant 
+      and could not be created, or for any other reason. In such case it 
+      may chose to present an error message to the user.
+    </p><p>
+      When attempting to read a file, if for any reason a file in a certain
+      directory is unaccessible, e.g. because the directory is non-existant, 
+      the file is non-existant or the user is not authorized to open the file,
+      then the processing of the file in that directory should be skipped. 
+      If due to this a required file could not be found at all, the 
+      application may chose to present an error message to the user.
+    </p><p>
+      A specification that refers to <tt class="literal">$XDG_DATA_DIRS</tt> or 
+      <tt class="literal">$XDG_CONFIG_DIRS</tt> should define what the behaviour 
+      must be when a file is located under multiple base directories. 
+      It could, for example, define that only the file under the most 
+      important base directory should be used or, as another example,
+      it could define rules for merging the information from the different
+      files.
+    </p></div></div></body></html>

data/lib/xdg.rb

@@ -0,0 +1,133 @@
+# :Title: XDG
+# :Author: &trans;
+# :Copyright: (c)2008 Tiger Ops
+# :License: GPLv3
+
+
+# = 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, never written to
+# by a program. (Generally speaking only users or pacakge mangers should
+# be adding, changing or removing files from the data locations.
+#
+# The config locations are where you should store files that may change,
+# and effect operations depending one there content. This is like etc/
+# in the FHS, but alterable by end users and and end user programs,
+# not just root and sudo admin scripts.
+#
+# The cache location stores files that could judt as well be deleted
+# and everyihtng still works find. This is for variable and temporary
+# files. Like var/ in FHS.
+#
+# This module returns paths as strings.
+
+module XDG
+
+  ###############
+  module_function
+  ###############
+
+  def xdg_home
+    ENV['HOME'] || File.expand_path('~')
+  end
+
+  # Location of user's personal config directory.
+  def xdg_config_home
+    File.expand_path(
+      ENV['XDG_CONFIG_HOME'] || File.join(xdg_home, '.config')
+    )
+  end
+
+  # List of user's shared config directories.
+  def xdg_config_dirs
+    dirs = ENV['XDG_CONFIG_DIRS'].split(/[:;]/)
+    if dirs.empty?
+      dirs = %w{/etc/xdg}
+    end
+    dir.collect{ |d| File.expand_path(d) }
+  end
+
+  # Location of user's personal data directory.
+  def xdg_data_home
+    File.expand_path(
+      ENV['XDG_DATA_HOME'] || File.join(xdg_home, '.local', 'share')
+    )
+  end
+
+  # List of user's shared data directores.
+  def xdg_data_dirs
+    dirs = ENV['XDG_DATA_DIRS'].split(/[:;]/)
+    if dirs.empty?
+      dirs = %w{/usr/local/share/ /usr/share/}
+    end
+    dir.collect{ |d| File.expand_path(d) }
+  end
+
+  # Location of user's personal cache directory.
+  def xdg_cache_home
+    File.expand_path(
+      ENV['XDG_CACHE_HOME'] || File.join(xdg_home, '.cache')
+    )
+  end
+
+  # Find a file or directory in data dirs.
+  def xdg_data_file(file)
+    [data_home, *data_dirs].each do |dir|
+      path = File.join(dir,file)
+      break path if File.exist?(path)
+    end
+  end
+
+  # Find a file or directory in config dirs.
+  def xdg_config_file(file)
+    [config_home, *config_dirs].each do |dir|
+      path = File.join(dir,file)
+      break path if File.exist?(path)
+    end
+  end
+
+  # Find a file or directory in the user cache.
+  def xdg_cache_file(file)
+    File.join(cache_home,file)
+  end
+
+  ############################################
+  # The following are not strictly XDG spec, #
+  # but are useful in the same respect.      #
+  ############################################
+
+  # Location of working config directory.
+  def xdg_config_work
+    File.expand_path(
+      #ENV['XDG_CONFIG_WORK'] || File.join(Dir.pwd, '.config')
+      File.join(Dir.pwd, '.config')
+    )
+  end
+
+  # Location of working data directory.
+  def xdg_data_work
+    File.expand_path(
+      #ENV['XDG_DATA_WORK'] || File.join(Dir.pwd, '.share')
+      File.join(Dir.pwd, '.share')
+    )
+  end
+
+  # Location of working cache directory.
+  def xdg_cache_work
+    File.expand_path(
+      #ENV['XDG_CACHE_WORK'] || File.join(Dir.pwd, '.cache')
+      File.join(Dir.pwd, '.cache')
+    )
+  end
+
+end # module XDG
+

data/meta/abstract

@@ -0,0 +1 @@
+XDG provides and interface for using the XDG directory standard.

data/meta/authors

@@ -0,0 +1 @@
+7rans <transfire@gmail.com>

data/meta/contact

@@ -0,0 +1 @@
+tigerops-community@rubyforge.org

data/meta/homepage

@@ -0,0 +1 @@
+http://xdg.rubyforge.org

data/meta/releases

@@ -0,0 +1 @@
+

data/meta/summary

@@ -0,0 +1 @@
+XDG provides an interface for using XDG directory standard.

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification 
+name: xdg
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- |
+  tigerops-community@rubyforge.org
+
+- 7rans <transfire@gmail.com>
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-09-27 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: XDG provides and interface for using the XDG directory standard.
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- MANIFEST
+- RELEASE
+- VERSION
+- COPYING
+files: 
+- doc
+- doc/book
+- doc/book/basedir-spec-0.6.html
+- MANIFEST
+- test
+- RELEASE
+- README
+- meta
+- meta/homepage
+- meta/summary
+- meta/abstract
+- meta/releases
+- meta/authors
+- meta/contact
+- lib
+- lib/xdg.rb
+- VERSION
+- COPYING
+has_rdoc: true
+homepage: |
+  http://xdg.rubyforge.org
+
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --title
+- xdg api
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: xdg
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: XDG provides and interface for using the XDG directory standard.
+test_files: []
+