xdg 1.0.0 → 2.0.0

data/lib/xdg/base_dir.rb

@@ -0,0 +1,220 @@
+module XDG
+
+  # Base Directory Standard
+  class BaseDir
+
+    # Try to get information from Ruby's install configuration.
+    require 'rbconfig'
+
+    sysconfdir = ::Config::CONFIG['sysconfdir'] || '/etc'
+    datadir    = ::Config::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']
+    }
+
+    # BaseDir iterates over directory paths.
+    include Enumerable
+
+    # Shortcut for `BaseDir.new`.
+    def self.[](*env)
+      new(*env)
+    end
+
+    # Initialize new instance of BaseDir class.
+    def initialize(*env)
+      @environment_variables = []
+      env.each do |v|
+        v = v.to_s.upcase
+        if v !~ /_/
+          @environment_variables << 'XDG_' + v + '_HOME'
+          @environment_variables << 'XDG_' + v + '_DIRS'
+        else
+          @environment_variables << 'XDG_' + v
+        end
+      end
+    end
+
+    # The environment variables being referenced.
+    #
+    # @return [Array] list of XDG environment variable names
+    def environment_variables
+      @environment_variables
+    end
+
+    # Returns a complete list of directories.
+    def to_a
+      environment_variables.map do |v|
+        if paths = ENV[v]
+          dirs = paths.split(/[:;]/)
+        else
+          dirs = DEFAULTS[v]
+        end
+        dirs.map{ |path| expand(path) }
+      end.flatten
+    end
+
+    # BaseDir is essentially an array.
+    alias_method :to_ary, :to_a
+
+    # Number of directory paths.
+    def size
+      to_a.size
+    end
+
+    # Iterate of each directory.
+    def each(&block)
+      to_a.each(&block)
+    end
+
+    # Returns a complete list of directories.
+    def list
+      to_a
+    end
+
+    # List of directories as Pathanme objects.
+    #
+    # @return [Array<Pathname>] list of directories as Pathname objects
+    def paths
+      map{ |dir| Pathname.new(dir) }
+    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.
+    #
+    # 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
+
+    # 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::BaseDir[:DATA,:HOME].select('stick/units', File::FNM_CASEFOLD)
+    #
+    #   XDG::BaseDir[:DATA,:HOME].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
+
+    # 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
+
+    # @return [String] envinronment values.
+    def to_s
+      environment_variables.map{ |v| ENV[v] || DEFAULTS[v] }.join(':')
+    end
+
+    # @return [Pathname] pathname of first directory
+    def to_path
+      Pathname.new(to_s)
+    end
+
+    #
+    def env
+      environment_variables.map{ |v| ENV[v] }.join(':')
+    end
+
+    #
+    attr :subdirectory
+
+    #
+    def subdirectory=(path)
+      @subdirectory = path.to_s
+    end
+
+    #
+    def with_subdirectory(path)
+      @subdirectory = path if path
+      self
+    end
+
+  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
+
+    #
+    def expand(path)
+      if subdirectory
+        File.expand_path(File.join(path, subdirectory))
+      else
+        File.expand_path(path)
+      end
+    end
+
+    # If Pathname is referenced the library is automatically loaded.
+    def self.const_missing(const)
+      if const == :Pathname
+        require 'pathname'
+        ::Pathname
+      else
+        super(const)
+      end
+    end
+
+  end
+
+end
+
+# Copyright (c) 2008,2011 Thomas Sawyer
+# Distributed under the terms of the APACHE 2.0 license.

data/lib/xdg/base_dir/extended.rb

@@ -0,0 +1,20 @@
+module XDG
+
+  # Base directory interface class.
+  class BaseDir
+
+    #
+    DEFAULTS['XDG_RESOURCE_HOME'] = ['~/.local']
+    DEFAULTS['XDG_RESOURCE_DIRS'] = ['/usr/local','/usr']
+
+    # Working directory
+    # TODO: Not sure about these defaults
+    DEFAULTS['XDG_CONFIG_WORK']   = ['.config','config']
+    DEFAULTS['XDG_CACHE_WORK']    = ['.tmp','tmp']
+    DEFAULTS['XDG_RESOURCE_WORK'] = ['.local']
+  end
+
+end
+
+# Copyright (c) 2008,2011 Thomas Sawyer
+# Distributed under the terms of the APACHE 2.0 license.

data/lib/xdg/base_dir/global_variables.rb

@@ -0,0 +1,18 @@
+if RUBY_VERSION > '1.9'
+  require_relative 'base_dir'
+else
+  require 'xdg/base_dir'
+end
+
+$XDG_DATA        = XDG::BaseDir.new('DATA')
+$XDG_DATA_HOME   = XDG::BaseDir.new('DATA', 'HOME')
+$XDG_DATA_DIRS   = XDG::BaseDir.new('DATA', 'DIRS')
+
+$XDG_CONFIG      = XDG::BaseDir.new('CONFIG')
+$XDG_CONFIG_HOME = XDG::BaseDir.new('CONFIG', 'HOME')
+$XDG_CONFIG_DIRS = XDG::BaseDir.new('CONFIG', 'DIRS')
+
+$XDG_CACHE       = XDG::BaseDir.new('CACHE')
+$XDG_CACHE_HOME  = XDG::BaseDir.new('CACHE', 'HOME')
+$XDG_CACHE_DIRS  = XDG::BaseDir.new('CACHE', 'DIRS')
+

data/lib/xdg/base_dir/legacy.rb

@@ -0,0 +1,72 @@
+module XDG
+  class BaseDir
+    # Legacy API can serve as a stop gap until a developer
+    # has time to update an program already using XDG.
+    #
+    # Do NOT use this module for future development!!!
+    module Legacy
+      #
+      require 'xdg'
+      require 'xdg/base_dir/extended'
+
+      #
+      extend self
+
+      #
+      def home
+        File.expand_path('~')
+      end
+
+      #
+      def data
+        obj = XDG['DATA']
+        class << obj
+          def home
+            XDG['DATA_HOME'].to_a.first
+          end
+          def dirs
+            XDG['DATA_DIRS'].to_a
+          end
+        end
+        return obj
+      end
+
+      #
+      def config
+        obj = XDG['CONFIG']
+        class << obj
+          def home
+            XDG['CONFIG_HOME'].to_a.first
+          end
+          def dirs
+            XDG['CONFIG_DIRS'].to_a
+          end
+          def work
+            XDG['CONFIG_WORK'].to_a
+          end
+        end
+        return obj
+      end
+
+      #
+      def cache
+        obj = XDG['CACHE']
+        class << obj
+          def home
+            XDG['CACHE_HOME'].to_a.first
+          end
+          def dirs
+            XDG['CACHE_DIRS'].to_a
+          end
+          def work
+            XDG['CACHE_WORK'].to_a
+          end
+        end
+        return obj
+      end
+
+    end
+  end
+
+  extend BaseDir::Legacy
+end

data/lib/xdg/base_dir/mixin.rb

@@ -0,0 +1,84 @@
+module XDG
+  class BaseDir
+    #
+    # The BaseDir::Mixin module can be used to add XDG base directory
+    # methods to your own classes.
+    #
+    #     class MyAppConfig
+    #       include XDG::BaseDir::Mixin
+    #
+    #       def subdirectory
+    #         'myapp'
+    #       end
+    #     end
+    #
+    #     c = MyAppConfig.new
+    #
+    #     c.config.home.to_s  #=> '~/.config/myapp'
+    #
+    module Mixin
+
+      # @todo do we need this?
+      extend self
+
+      # Override this method to change the subdirectory of the mixin.
+      def subdirectory
+        nil
+      end
+
+      #
+      def home
+        File.expand_path('~')
+      end
+
+      #
+      def data
+        obj = XDG['DATA'].with_subdirectory(subdirectory)
+        class << obj
+          def home
+            XDG['DATA_HOME'].with_subdirectory(subdirectory)
+          end
+          def dirs
+            XDG['DATA_DIRS'].with_subdirectory(subdirectory)
+          end
+        end
+        return obj
+      end
+
+      #
+      def config
+        obj = XDG['CONFIG'].with_subdirectory(subdirectory)
+        class << obj
+          def home
+            XDG['CONFIG_HOME'].with_subdirectory(subdirectory)
+          end
+          def dirs
+            XDG['CONFIG_DIRS'].with_subdirectory(subdirectory)
+          end
+          def work
+            XDG['CONFIG_WORK'].with_subdirectory(subdirectory)
+          end
+        end
+        return obj
+      end
+
+      #
+      def cache
+        obj = XDG['CACHE'].with_subdirectory(subdirectory)
+        class << obj
+          def home
+            XDG['CACHE_HOME'].with_subdirectory(subdirectory)
+          end
+          def dirs
+            XDG['CACHE_DIRS'].with_subdirectory(subdirectory)
+          end
+          def work
+            XDG['CACHE_WORK'].with_subdirectory(subdirectory)
+          end
+        end
+        return obj
+      end
+
+    end
+  end
+end

data/lib/xdg/version.rb

@@ -0,0 +1,3 @@
+module XDG
+  VERSION = '1.0.0'
+end

data/qed/01_base_dir.rdoc

@@ -0,0 +1,77 @@
+= 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'].env.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'].env.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'].env.assert == ENV['XDG_CONFIG_HOME'].to_s
+    XDG['CONFIG_HOME'].to_a.assert == [$froot + 'home/joe/.config']
+
+=== Dirs
+
+    XDG['CONFIG_DIRS'].env.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'].env.assert == ENV['XDG_CACHE_HOME'].to_s
+    XDG['CACHE_HOME'].to_a.assert == [$froot + 'home/joe/.cache']
+
+=== Dirs
+
+    XDG['CACHE_DIRS'].env.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']
+