xdg 0.5.2 → 1.0.0

data/HISTORY

@@ -1,65 +1,81 @@
 = RELEASE HISTORY
 
+== 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
-hardcoded FHS locations.
+some hardcoded FHS locations.
 
 Changes:
 
-* 1 Enhancement
-
-    * replaced hardcoded system directories with rbconfig entries.
+* Replaced hardcoded system directories with rbconfig entries.
 
 
 == 0.5.1 / 2008-11-17
 
 Changes:
 
-* 4 Enhancements
-
-    * data work directory is '.local', not '.share'
-    * data_work is deprecated
-    * updated website
+* Fixed data work directory is '.local', not '.share'
+* Deprecated #data_work
 
 
 == 0.5.0 / 2008-10-28
 
 Changes:
 
-* 1 Enhancement
-
-    * changed _glob to _select
+* Changed _glob to _select
 
 
 == 0.4.0 / 2008-10-26
 
-Changes:
+This release removes the xdg_ prefix from the instance-level
+method names. Now module and instance levels are the same.
 
-* 9 Enhancements
+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.
 
-    * removed xdg_ prefixes and replaced _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
+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:
 
-* 5 Enhancements
-
-    * 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
+* 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

data/MANIFEST

@@ -1,33 +1,22 @@
-#!mast bin lib meta test [A-Z]*
-lib
+#!mast bin lib meta script test [A-Z]*
+lib/xdg/compat.rb
+lib/xdg/extended.rb
 lib/xdg.rb
-meta
-meta/abstract
 meta/authors
+meta/collection
 meta/contact
+meta/description
 meta/homepage
-meta/package
+meta/name
+meta/repository
 meta/summary
 meta/title
 meta/version
-test
-test/fakeroot
-test/fakeroot/.cache
-test/fakeroot/.config
-test/fakeroot/.share
-test/fakeroot/etc
-test/fakeroot/etc/xdg
+script/test
 test/fakeroot/etc/xdg/bar.config
-test/fakeroot/home
-test/fakeroot/home/.cache
 test/fakeroot/home/.cache/foo.cache
-test/fakeroot/home/.config
 test/fakeroot/home/.config/foo.config
-test/fakeroot/home/.local
-test/fakeroot/home/.local/share
 test/fakeroot/home/.local/share/foo.dat
-test/fakeroot/usr
-test/fakeroot/usr/share
 test/fakeroot/usr/share/bar.dat
 test/test_xdg.rb
 README

data/README

@@ -1,6 +1,7 @@
 = XDG Base Directory Standard for Ruby
 
-  http://xdg.rubyforge.org
+* http://rubyworks.github.com/xdg
+* http://github.com/rubyworks/xdg
 
 == Introduction
 
@@ -11,62 +12,86 @@ If your program utilizes user or system-wide support files
 (eg. configuration files), you owe it to yourself to checkout
 the XDG standard.
 
-What's next? The API should be stable now. I do not forsee
-and reasons for it to change. In the future, I may add some
-additional ruby-esque features, perhaps for other parts of
-the XDG utilities, but that should be purely in addition to
-what is already here. If all this holds true for a while a
-1.0 release will be forth-coming.
-
 [1]http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html 
 
-== Release Notes
 
-Please see the RELEASE file.
+== HOW TO USE
+
+XDG consists of a small set of modules, one for each XDG directory. Each of
+these has a small base set of easy to use methods.
+
+    XDG::Config.home
+    XDG::Config.dirs
+    XDG::Config.find(pattern){ |path| ... }
+    XDG::Config.search(pattern){ |path| ... }
 
-== Usage
+    XDG::Data.home
+    XDG::Data.dirs
+    XDG::Data.find(pattern){ |path| ... }
+    XDG::Data.search(pattern){ |path| ... }
 
-XDG is a module with a small set of easy to use methods:
+    XDG::Cache.home
+    XDG::Cache.find(pattern){ |path| ... }
+    XDG::Cache.search(pattern){ |path| ... }
 
-  XDG.config_home
-  XDG.config_dirs
-  XDG.config_find(pattern){ |path| ... }
-  XDG.config_select(pattern){ |path| ... }
+XDG can also access these modules via methods.
 
-  XDG.data_home
-  XDG.data_dirs
-  XDG.data_find(pattern){ |path| ... }
-  XDG.data_select(pattern){ |path| ... }
+    XDG.config.home
+    XDG.config.dirs
+    XDG.config.find(pattern){ |path| ... }
+    XDG.config.search(pattern){ |path| ... }
 
-  XDG.cache_home
-  XDG.cache_find(pattern){ |path| ... }
-  XDG.cache_select(pattern){ |path| ... }
+    XDG.data.home
+    XDG.data.dirs
+    XDG.data.find(pattern){ |path| ... }
+    XDG.data.search(pattern){ |path| ... }
 
-  XDG.config_work
-  XDG.cache_work
+    XDG.cache.home
+    XDG.cache.find(pattern){ |path| ... }
+    XDG.cache.search(pattern){ |path| ... }
 
 If you know XDG these are pretty much self-explanitory.
 But see the RDocs for specifics.
 
-== Installation
+=== Extended Functionality
+
+The Ruby XDG module also provides extended functionality
+not part of the standard specification. These extensions are
+simply add-on funcitonality deemed useful, or implementations
+of  proposals being discussed for a possible future version of
+the standard.
+
+    require 'xdg/extended'
+
+    XDG.config.work
+    XDG.cache.work
+
+See the API for the extended.rb, to learn more. Note that
+the extended modules are subject to great change of change
+as they are still being designed.
+
+
+== HOW TO INSTALL
 
 Using RubyGems:
 
   $ sudo gem install xdg
 
-Installing the tarball requires Ruby Setup
-(see http://setup.rubyforge.org).
+Installing the tarball requires Ruby Setup (see http://proutils.github.com/setup).
 
   $ tar -xvzf xdg-0.5.2
   $ cd xdg-0.5.2
   $ sudo setup.rb all
 
-== Development
 
-Visit http://rubyforge.org/projects/xdg
+== DEVELOPMENT
+
+Visit http://github.com/proutils/xdg
+
 
-== Copyright
+== COPYRIGHT
 
-Copyright (c) 2008 Tiger Ops / 7rans
+Copyright (c) 2008, 2009 Thomas Sawyer
 Distributed under the terms of the LGPL v3 license.
+See COPYING file for details.
 

data/lib/xdg.rb

@@ -7,12 +7,11 @@ require 'rbconfig'
 #
 #   http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
 #
-# Some important clarifications, not made clear by the
-# above specification. 
+# 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 mangers should
+# 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,
@@ -21,217 +20,239 @@ require 'rbconfig'
 # not just root and sudo admin scripts.
 #
 # The cache locations stores files that could just as well be deleted
-# and everyihtng would still work fine. This is for variable and
-# temporary files. much like var/ in FHS.
+# 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
 
-  extend self    #module_function
+  #module_function
+  extend self
 
   # Returns user's home directory.
+  #
   def home
     File.expand_path('~') # ENV['HOME']
   end
 
-  # Location of user's personal config directory.
-  def config_home
-    File.expand_path(
-      ENV['XDG_CONFIG_HOME'] || File.join(home, '.config')
-    )
-  end
-
-  # List of user's shared config directories.
-  def config_dirs
-    dirs = ENV['XDG_CONFIG_DIRS'].to_s.split(/[:;]/)
-    if dirs.empty?
-      dirs = File.join(Config::CONFIG['sysconfdir'], 'xdg') #%w{/etc/xdg}
+  # Access to data resource locations.
+  #
+  #   XDG.data.each{ |dir| ... }
+  #
+  def data(*glob_and_flags, &block)
+    if !glob_and_flags.empty? or block_given?
+      Data.select(*glob_and_flags, &block)
+    else
+      Data
     end
-    dirs.collect{ |d| File.expand_path(d) }
-  end
-
-  # Location of user's personal data directory.
-  def data_home
-    File.expand_path(
-      ENV['XDG_DATA_HOME'] || File.join(home, '.local', 'share')
-    )
   end
 
-  # List of user's shared data directores.
-  def data_dirs
-    dirs = ENV['XDG_DATA_DIRS'].split(/[:;]/)
-    if dirs.empty?
-      dirs = [ Config::CONFIG['localdatadir'], Config::CONFIG['datadir'] ] #%w{/usr/local/share/ /usr/share/}
+  # Access to configuration locations.
+  #
+  #   XDG.config.each{ |dir| ... }
+  #
+  def config(*glob_and_flags, &block)
+    if !glob_and_flags.empty? or block_given?
+      Config.select(*glob_and_flags, &block)
+    else
+      Config
     end
-    dirs.collect{ |d| File.expand_path(d) }
   end
 
-  # Location of user's personal cache directory.
-  def cache_home
-    File.expand_path(
-      ENV['XDG_CACHE_HOME'] || File.join(home, '.cache')
-    )
-  end
-
-  # Find a file or directory in data dirs.
+  # Access to cache locations.
   #
-  # See: +data_select+.
+  #   XDG.cache.each{ |dir| ... }
   #
-  def data_find(*glob_and_flags, &block)
-    data_select(*glob_and_flags, &block).first
+  def cache(*glob_and_flags, &block)
+    if !glob_and_flags.empty? or block_given?
+      Cache.select(*glob_and_flags, &block)
+    else
+      Cache
+    end
   end
 
-  # Return array of matching files or directories
-  # in any of the data locations.
+  # Each directory set shares these common methods.
   #
-  # This starts with the user's home directory
-  # and then searches system directories.
-  #
-  # String parameters are joined into a pathname
-  # while Integers and Symbols treated as flags.
-  #
-  # For example, the following are equivalent:
-  #
-  #   XDG.data_select('stick/units', File::FNM_CASEFOLD)
-  #
-  #   XDG.data_select('stick', 'uits', :casefold)
-  #
-  def data_select(*glob_and_flags, &block)
-    glob, flags = *glob_and_flags.partition{ |e| String===e }
-    glob = ['**/*'] if glob.empty?
-    flag = flags.inject(0) do |m, f|
-      if Symbol === f
-        m + File::const_get("FNM_#{f.to_s.upcase}")
-      else
-        m + f.to_i
-      end
+  module Common
+
+    # Returns a complete list of directories, starting
+    # with the home location and moving outward.
+    def list
+      [home, *dirs]
     end
-    find = []
-    [data_home, *data_dirs].each do |dir|
-      path = File.join(dir, *glob)
-      if block_given?
-        find.concat(Dir.glob(path, flag).select(&block))
-      else
-        find.concat(Dir.glob(path, flag))
+
+    # Return array of matching files or directories
+    # in any of the resource locations, starting with
+    # the home directory and searching outward into
+    # system directories.
+    #
+    # Unlike #select, this doesn't take a block and each
+    # additional glob argument is treated as a logical-or.
+    #
+    #   XDG::Data.glob("stick/*.rb", "stick/*.yaml")
+    #
+    def glob(*glob_and_flags)
+      glob, flags = *parse_arguments(*glob_and_flags)
+      find = []
+      list.each do |dir|
+        glob.each do |pattern|
+          find.concat(Dir.glob(File.join(dir, pattern), flags))
+        end
       end
+      find.uniq
     end
-    find
-  end
 
-  # Return the fist matching file or directory
-  # from the config locations.
-  #
-  # See: +config_select+.
-  #
-  def config_find(*glob_and_flags, &block)
-    config_select(*glob_and_flags, &block).first
-  end
+    # Return array of matching files or directories
+    # in any of the resource locations, starting with
+    # the home directory and searching outward into
+    # system directories.
+    #
+    # String parameters are joined into a pathname
+    # while Integers and Symbols treated as flags.
+    #
+    # For example, the following are equivalent:
+    #
+    #   XDG.data.select('stick/units', File::FNM_CASEFOLD)
+    #
+    #   XDG.data.select('stick', 'units', :casefold)
+    #
+    def select(*glob_and_flags, &block)
+      glob, flag = *parse_arguments(*glob_and_flags)
+      find = []
+      list.each do |dir|
+        path = File.join(dir, *glob)
+        hits = Dir.glob(path, flag)
+        hits = hits.select(&block) if block_given?
+        find.concat(hits)
+      end
+      find.uniq
+    end
 
-  # Return array of matching files or directories
-  # in any of the config locations.
-  #
-  # This starts with the user's home directory
-  # and then searches system directories.
-  #
-  # String parameters are joined into a pathname
-  # while Integers and Symbols treated as flags.
-  #
-  # For example, the following are equivalent:
-  #
-  #   XDG.config_select('sow/plugins', File::FNM_CASEFOLD)
-  #
-  #   XDG.config_select('sow', 'plugins', :casefold)
-  #
-  def config_select(*glob_and_flags)
-    glob, flags = *glob_and_flags.partition{ |e| String===e }
-    glob = ['**/*'] if glob.empty?
-    flag = flags.inject(0) do |m, f|
-      if Symbol === f
-        m + File::const_get("FNM_#{f.to_s.upcase}")
-      else
-        m + f.to_i
+    # Find a file or directory. This works just like #select
+    # except that it returns the first match found.
+    #
+    # TODO: It would be more efficient to traverse the dirs and use #fnmatch.
+    #
+    def find(*glob_and_flags, &block)
+      glob, flag = *parse_arguments(*glob_and_flags)
+      find = nil
+      list.each do |dir|
+        path = File.join(dir, *glob)
+        hits = Dir.glob(path, flag)
+        hits = hits.select(&block) if block_given?
+        find = hits.first
+        break if find
       end
+      find
     end
-    find = []
-    [config_home, *config_dirs].each do |dir|
-      path = File.join(dir, *glob)
-      if block_given?
-        find.concat(Dir.glob(path, flag).select(&block))
-      else
-        find.concat(Dir.glob(path, flag))
+
+  private
+
+    def parse_arguments(*glob_and_flags)
+      glob, flags = *glob_and_flags.partition{ |e| String===e }
+      glob = ['**/*'] if glob.empty?
+      flag = flags.inject(0) do |m, f|
+        if Symbol === f
+          m + File::const_get("FNM_#{f.to_s.upcase}")
+        else
+          m + f.to_i
+        end
       end
+      return glob, flag
     end
-    find
+
   end
 
-  # Return the fist matching file or directory
-  # in the cache directory.
-  #
-  # See: +cache_select+.
+  # = DATA LOCATIONS
   #
-  def cache_find(*glob_and_flags, &block)
-    cache_select(*glob_and_flags, &block).first
+  module Data
+    include Common
+
+    # Location of personal data directory.
+    def home
+      @home ||= (
+        File.expand_path(
+          ENV['XDG_DATA_HOME'] || File.join(XDG.home, '.local', 'share')
+        )
+      )
+    end
+
+    # List of shared data directores.
+    def dirs
+      @dirs ||= (
+        dirs = ENV['XDG_DATA_DIRS'].split(/[:;]/)
+        if dirs.empty?
+          #dirs = [ Config::CONFIG['localdatadir'], Config::CONFIG['datadir'] ]
+          dirs = Resource.dirs.map{ |d| File.join(d, 'share') }
+        end
+        dirs = dirs.map{ |d| File.expand_path(d) }.uniq
+        dirs = dirs.select{ |d| File.directory?(d) }
+        dirs
+      )
+    end
+
+    extend self
   end
 
-  # Return array of matching files or directories
-  # from the cache directory.
+  # = CONFIGUTATION LOCATIONS
   #
-  # String parameters are joined into a pathname
-  # while Integers and Symbols treated as flags.
-  #
-  # For example, the following are equivalent:
-  #
-  #   XDG.cache_select('sow/tmp', File::FNM_CASEFOLD)
-  #
-  #   XDG.cache_select('sow', 'tmp', :casefold)
-  #
-  def cache_select(*glob_and_flags)
-    glob, flags = *glob_and_flags.partition{ |e| String===e }
-    glob = ['**/*'] if glob.empty?
-    flag = flags.inject(0) do |m, f|
-      if Symbol === f
-        m + File::const_get("FNM_#{f.to_s.upcase}")
-      else
-        m + f.to_i
-      end
+  module Config
+    include Common
+    extend self
+
+    # Location of personal config directory.
+    def home
+      @home ||= (
+        File.expand_path(
+          ENV['XDG_CONFIG_HOME'] || File.join(XDG.home, '.config')
+        )
+      )
     end
-    path = File.join(cache_home,*glob)
-    if block_given?
-      Dir.glob(path, flag).select(&block)
-    else
-      Dir.glob(path, flag)
+
+    # List of shared config directories.
+    def dirs
+      @dirs ||= (
+        dirs = ENV['XDG_CONFIG_DIRS'].to_s.split(/[:;]/)
+        if dirs.empty?
+          #dirs = ['etc/xdg', 'etc']
+          sysconfdir = ::Config::CONFIG['sysconfdir']
+          dirs = [ File.join(sysconfdir, 'xdg'), sysconfdir ]
+        end
+        dirs = dirs.map{ |d| File.expand_path(d) }.uniq
+        dirs = dirs.select{ |d| File.directory?(d) }
+        dirs
+      )
     end
+
+    extend self
   end
 
-  #--
-  # The following are not strictly XDG spec,
-  # but are useful in an analogous respect.
-  #++
+  # = CACHE LOCATIONS
+  #
+  module Cache
+    include Common
 
-  # Location of working config directory.
-  def config_work
-    File.expand_path(
-      File.join(Dir.pwd, '.config')
-    )
-  end
+    # Location of user's personal cache directory.
+    def home
+      @home ||= (
+        File.expand_path(
+          ENV['XDG_CACHE_HOME'] || File.join(XDG.home, '.cache')
+        )
+      )
+    end
+
+    # Serves as a no-op, since there are no common cache directories
+    # defined by the XDG standard. (Though one might argue that 
+    # <tt>tmp/</tt> is one.)
+    def dirs
+      @dirs ||= []
+    end
 
-  # DEPRECATED -- Does not make sense to have this.
-  # Location of working data directory.
-  #def data_work
-  #  File.expand_path(
-  #    File.join(Dir.pwd, '.local')
-  #  )
-  #end
-
-  # Location of working cache directory.
-  def cache_work
-    File.expand_path(
-      File.join(Dir.pwd, '.cache')
-    )
+    extend self
   end
 
 end # module XDG
 
-# Copyright (c)2008 Tiger Ops / Trans
-# Distributed under the terms of the GPL v3.
+# Copyright (c) 2008,2009 Thomas Sawyer
+# Distributed under the terms of the LGPL v3.