xdg 0.1.0 → 0.3.0

data/HISTORY

@@ -0,0 +1,5 @@
+### 0.3.0 / 2008-09-11
+
+* Renamed module level methods without 'xdg_' prefix.
+* The xdg_ versions still exist for backward compatibility.
+

data/MANIFEST

@@ -1,14 +1,22 @@
-doc
-doc/book
-doc/book/basedir-spec-0.6.html
 test
+test/fakeroot
+test/fakeroot/home
+test/fakeroot/usr
+test/fakeroot/usr/share
+test/fakeroot/usr/share/bar.dat
+test/fakeroot/etc
+test/fakeroot/etc/xdg
+test/fakeroot/etc/xdg/bar.config
+test/test_xdg.rb
 RELEASE
 README
+HISTORY
 meta
 meta/homepage
 meta/summary
 meta/abstract
 meta/releases
+meta/title
 meta/authors
 meta/contact
 lib

data/README

@@ -1,29 +1,51 @@
-= XDG
+= XDG Base Directory Standards for Ruby
+
+  http://xdg.rubyforge.org
+
+== Introduction
 
 XDG provides an easy to use interface for utilizing
-the XDG Base Base Directory Standards.
+the XDG Base Directory Standards.
+
+See: http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html
+
+== Release Notes
+
+Please see the RELEASE file.
 
 == Usage
 
-XDG is a module with a small set of easy to understand
-module methods, so it very easy to use.
+XDG is a module with a small set of easy to use methods:
 
-See RDOC's for more information.
+  XDG.config_home
+  XDG.config_dirs
+  XDG.data_home
+  XDG.data_dirs
+  XDG.cache_home
+
+  XDG.data_file(file)
+  XDG.config_file(file)
+  XDG.cache_file(file)
+
+  XDG.config_work
+  XDG.data_work
+  XDG.cache_work
+
+If you know XDG these are pretty much self-explanitory.
+But see the RDocs for specifics.
 
 == Installation
 
-=== RubyGems
+Using 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
+  $ tar -xvzf xdg-0.4.1
+  $ cd xdg-0.4.1
+  $ sudo setup.rb all
 
 == Development
 

data/RELEASE

@@ -1,5 +1,10 @@
-This is the initial release of XDG.
+This release removes the xdg_ prefix from the module-level
+method names. The instance methods retain the xdg_ prefix.
+I will consider if they should also be removed for the
+next release.
 
-XDG provides a straight-forward interface for supporting
-the XDG Base Directory Standard.
+### 0.3.0 / 2008-09-11
+
+* Renamed module level methods without 'xdg_' prefix.
+* The xdg_ versions still exist for backward compatibility.
 

data/VERSION

@@ -1 +1 @@
-xdg 0.1.0 beta (2008-09-27)
+xdg 0.3.0 beta (2008-09-30)

data/lib/xdg.rb

@@ -32,81 +32,82 @@
 
 module XDG
 
-  ###############
-  module_function
-  ###############
-
-  def xdg_home
+  def self.home
     ENV['HOME'] || File.expand_path('~')
   end
 
   # Location of user's personal config directory.
-  def xdg_config_home
+  def self.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(/[:;]/)
+  def self.config_dirs
+    dirs = ENV['XDG_CONFIG_DIRS'].to_s.split(/[:;]/)
     if dirs.empty?
       dirs = %w{/etc/xdg}
     end
-    dir.collect{ |d| File.expand_path(d) }
+    dirs.collect{ |d| File.expand_path(d) }
   end
 
   # Location of user's personal data directory.
-  def xdg_data_home
+  def self.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
+  def self.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) }
+    dirs.collect{ |d| File.expand_path(d) }
   end
 
   # Location of user's personal cache directory.
-  def xdg_cache_home
+  def self.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|
+  def self.data_file(file)
+    find = nil
+    [xdg_data_home, *xdg_data_dirs].each do |dir|
       path = File.join(dir,file)
-      break path if File.exist?(path)
+      break find = path if File.exist?(path)
     end
+    find
   end
 
   # Find a file or directory in config dirs.
-  def xdg_config_file(file)
-    [config_home, *config_dirs].each do |dir|
+  def self.config_file(file)
+    find = nil
+    [xdg_config_home, *xdg_config_dirs].each do |dir|
       path = File.join(dir,file)
-      break path if File.exist?(path)
+      break find = path if File.exist?(path)
     end
+    find
   end
 
   # Find a file or directory in the user cache.
-  def xdg_cache_file(file)
-    File.join(cache_home,file)
+  def self.cache_file(file)
+    path = File.join(xdg_cache_home,file)
+    File.exist?(path) ? path : nil
   end
 
-  ############################################
-  # The following are not strictly XDG spec, #
-  # but are useful in the same respect.      #
-  ############################################
+  #--
+  # The following are not strictly XDG spec,
+  # but are useful in the same respect.
+  #++
 
   # Location of working config directory.
-  def xdg_config_work
+  def self.config_work
     File.expand_path(
       #ENV['XDG_CONFIG_WORK'] || File.join(Dir.pwd, '.config')
       File.join(Dir.pwd, '.config')
@@ -114,7 +115,7 @@ module XDG
   end
 
   # Location of working data directory.
-  def xdg_data_work
+  def self.data_work
     File.expand_path(
       #ENV['XDG_DATA_WORK'] || File.join(Dir.pwd, '.share')
       File.join(Dir.pwd, '.share')
@@ -122,12 +123,31 @@ module XDG
   end
 
   # Location of working cache directory.
-  def xdg_cache_work
+  def self.cache_work
     File.expand_path(
       #ENV['XDG_CACHE_WORK'] || File.join(Dir.pwd, '.cache')
       File.join(Dir.pwd, '.cache')
     )
   end
 
+  ###############
+  module_function
+  ###############
+
+  def xdg_home        ; XDG.home        ; end
+  def xdg_config_home ; XDG.config_home ; end
+  def xdg_config_dirs ; XDG.config_dirs ; end
+  def xdg_data_home   ; XDG.data_home   ; end
+  def xdg_data_dirs   ; XDG.data_dirs   ; end
+  def xdg_cache_home  ; XDG.cache_home  ; end
+
+  def xdg_data_file(file)   ; XDG.data_file(file)   ; end
+  def xdg_config_file(file) ; XDG.config_file(file) ; end
+  def xdg_cache_file(file)  ; XDG.cache_file(file)  ; end
+
+  def xdg_config_work ; XDG.config_work ; end
+  def xdg_data_work   ; XDG.data_work   ; end
+  def xdg_cache_work  ; XDG.cache_work  ; end
+
 end # module XDG
 

data/meta/abstract

@@ -1 +1,3 @@
-XDG provides and interface for using the XDG directory standard.
+XDG provides a module for supporting the XDG Base Directory Standard.
+See: http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html
+

data/meta/title

@@ -0,0 +1 @@
+XDG

data/test/fakeroot/etc/xdg/bar.config

@@ -0,0 +1 @@
+BAR.CONFIG

data/test/fakeroot/usr/share/bar.dat

@@ -0,0 +1 @@
+BAR.DAT

data/test/test_xdg.rb

@@ -0,0 +1,76 @@
+require 'test/unit'
+$: << 'lib'
+require 'xdg'
+
+# run test from fakeroot directory.
+Dir.chdir(File.join(File.dirname(__FILE__), 'fakeroot'))
+
+ENV['HOME']            = File.join(Dir.pwd, 'home')
+ENV['XDG_DATA_DIRS']   = File.join(Dir.pwd, 'usr/share')
+ENV['XDG_CONFIG_DIRS'] = File.join(Dir.pwd, 'etc/xdg')
+
+class TestXDG < Test::Unit::TestCase
+
+  # Test the standard paths.
+
+  def test_xdg_home
+    assert_equal(File.join(Dir.pwd,'home'), XDG.xdg_home)
+  end
+
+  def test_xdg_config_home
+    assert_equal(File.join(Dir.pwd,'home/.config'), XDG.xdg_config_home)
+  end
+
+  def test_xdg_config_dirs
+    assert_equal([File.join(Dir.pwd,"etc/xdg")], XDG.xdg_config_dirs)
+  end
+
+  def test_xdg_data_home
+    assert_equal(File.join(Dir.pwd,'home/.local/share'), XDG.xdg_data_home)
+  end
+
+  def test_xdg_data_dirs
+    assert_equal([File.join(Dir.pwd,'usr/share')], XDG.xdg_data_dirs)
+  end
+
+  def test_xdg_cache_home
+    assert_equal(File.join(Dir.pwd,'home/.cache'), XDG.xdg_cache_home)
+  end
+
+  # Test the file lookups.
+
+  def test_xdg_data_file
+    file = 'foo.dat'
+    assert_equal(File.join(Dir.pwd,'home/.local/share', file), XDG.xdg_data_file(file))
+    file = 'bar.dat'
+    assert_equal(File.join(Dir.pwd,'usr/share', file), XDG.xdg_data_file(file))
+  end
+
+  def test_xdg_config_file
+    file = 'foo.config'
+    assert_equal(File.join(Dir.pwd,'home/.config', file), XDG.xdg_config_file(file))
+    file = 'bar.config'
+    assert_equal(File.join(Dir.pwd,'etc/xdg', file), XDG.xdg_config_file(file))
+  end
+
+  def test_xdg_cache_file
+    file = 'foo.cache'
+    assert_equal(File.join(Dir.pwd,'home/.cache', file), XDG.xdg_cache_file(file))
+  end
+
+  # Test the working directory variations.
+
+  def test_xdg_config_work
+    assert_equal(File.join(Dir.pwd,'.config'), XDG.xdg_config_work)
+  end
+
+  def test_xdg_data_work
+    assert_equal(File.join(Dir.pwd,'.share'), XDG.xdg_data_work)
+  end
+
+  def test_xdg_cache_work
+    assert_equal(File.join(Dir.pwd,'.cache'), XDG.xdg_cache_work)
+  end
+
+end
+

metadata

@@ -1,22 +1,20 @@
 --- !ruby/object:Gem::Specification 
 name: xdg
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors: 
-- |
-  tigerops-community@rubyforge.org
-
+- tigerops-community@rubyforge.org
 - 7rans <transfire@gmail.com>
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2008-09-27 00:00:00 -04:00
+date: 2008-10-11 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
-description: XDG provides and interface for using the 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"
 email: 
 executables: []
 
@@ -26,21 +24,30 @@ extra_rdoc_files:
 - README
 - MANIFEST
 - RELEASE
+- HISTORY
 - VERSION
 - COPYING
 files: 
-- doc
-- doc/book
-- doc/book/basedir-spec-0.6.html
 - MANIFEST
 - test
+- test/fakeroot
+- test/fakeroot/home
+- test/fakeroot/usr
+- test/fakeroot/usr/share
+- test/fakeroot/usr/share/bar.dat
+- test/fakeroot/etc
+- test/fakeroot/etc/xdg
+- test/fakeroot/etc/xdg/bar.config
+- test/test_xdg.rb
 - RELEASE
 - README
+- HISTORY
 - meta
 - meta/homepage
 - meta/summary
 - meta/abstract
 - meta/releases
+- meta/title
 - meta/authors
 - meta/contact
 - lib
@@ -48,9 +55,7 @@ files:
 - VERSION
 - COPYING
 has_rdoc: true
-homepage: |
-  http://xdg.rubyforge.org
-
+homepage: http://xdg.rubyforge.org
 post_install_message: 
 rdoc_options: 
 - --inline-source
@@ -78,6 +83,14 @@ 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: []
-
+summary: XDG provides a module for supporting the XDG Base Directory Standard.
+test_files: 
+- test/fakeroot
+- test/fakeroot/home
+- test/fakeroot/usr
+- test/fakeroot/usr/share
+- test/fakeroot/usr/share/bar.dat
+- test/fakeroot/etc
+- test/fakeroot/etc/xdg
+- test/fakeroot/etc/xdg/bar.config
+- test/test_xdg.rb

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

@@ -1,138 +0,0 @@
-<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>