maid-xdg 2.2.1.1 → 2.2.1.2

data/Rakefile

@@ -0,0 +1,40 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+#
+def command?(command)
+  system("type #{command} > /dev/null 2>&1")
+end
+
+#
+# Tests
+#
+
+task :default => [:qed, :test]
+
+if command? :turn
+  desc "Run tests"
+  task :test do
+    suffix = "-n #{ENV['TEST']}" if ENV['TEST']
+    sh "turn -Ilib:. test/*.rb #{suffix}"
+  end
+else
+  Rake::TestTask.new do |t|
+    t.libs << 'lib'
+    t.libs << '.'
+    t.pattern = 'test/test_*.rb'
+    t.verbose = false
+  end
+end
+
+if command? :qed
+  desc "run qed tests"
+  task :qed do
+    sh "qed -Ilib qed/"
+  end
+else
+  task :qed do
+    $stderr.puts "WARNING: install qed gem to run qed tests"
+  end
+end
+

data/demo/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'].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']
+

data/demo/02_base_dir_extended.rdoc

@@ -0,0 +1,47 @@
+= 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']
+

data/demo/03_base_dir_mixin.rdoc

@@ -0,0 +1,17 @@
+= 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']
+

data/demo/applique/ae.rb

@@ -0,0 +1 @@
+AE.ansi = false

data/demo/applique/fakeroot.rb

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

data/demo/applique/xdg.rb

@@ -0,0 +1 @@
+require 'xdg'

data/demo/fixtures/fakeroot/.cache/DUMMY.txt

@@ -0,0 +1 @@
+Just here to provide a file for github to keep this directory.

data/demo/fixtures/fakeroot/etc/xdg/bar.config

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

data/demo/fixtures/fakeroot/home/.cache/foo.cache

@@ -0,0 +1 @@
+FOO.CACHE

data/demo/fixtures/fakeroot/home/.local/share/foo.dat

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

data/demo/fixtures/fakeroot/home/joe/foo.txt

@@ -0,0 +1 @@
+FOO TEXT

data/demo/fixtures/fakeroot/usr/share/bar.dat

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

data/lib/xdg.rb

@@ -0,0 +1,46 @@
+# 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,2011 Thomas Sawyer
+# Distributed under the terms of the APACHE 2.0 license.

data/lib/xdg/base_dir.rb

@@ -0,0 +1,256 @@
+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']
+    }
+
+    # 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
+
+    # The environment setting, or it's equivalent when the BaseDir
+    # is a combination of environment variables.
+    #
+    # @return [String] evnironment vsetting
+    def environment
+      environment_variables.map{ |v| ENV[v] }.join(':')
+    end
+
+    # This is same as #environment, but also includes default values.
+    #
+    # @return [String] envinronment value.
+    def environment_with_defaults
+      environment_variables.map{ |v| ENV[v] || DEFAULTS[v] }.join(':')
+    end
+
+    # Shortcut for #environment_with_defaults.
+    alias_method :env, :environment_with_defaults
+
+    # Returns a complete list of expanded directories.
+    #
+    # @return [Array<String>] expanded directory list
+    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 an *unexpanded* list of directories.
+    #
+    # @return [Array<String>] unexpanded directory list
+    def list
+      environment_variables.map do |v|
+        if paths = ENV[v]
+          dirs = paths.split(/[:;]/)
+        else
+          dirs = DEFAULTS[v]
+        end
+        if subdirectory
+          dirs.map{ |path| File.join(path, subdirectory) }
+        else
+          dirs
+        end
+      end.flatten
+    end
+
+    # List of directories as Pathanme objects.
+    #
+    # @return [Array<Pathname>] list of directories as Pathname objects
+    def paths
+      map{ |dir| Pathname.new(dir) }
+    end
+
+    # Returns the first directory expanded. Since a environment settings
+    # like `*_HOME` will only have one directory entry, this definition
+    # of #to_s makes utilizing those more convenient.
+    #
+    # @return [String] directory
+    def to_s
+      to_a.first
+    end
+
+    # The first directory converted to a Pathname object.
+    #
+    # @return [Pathname] pathname of first directory
+    def to_path
+      Pathname.new(to_a.first)
+    end
+
+    # The common subdirectory.
+    attr :subdirectory
+
+    # Set subdirectory to be applied to all paths.
+    def subdirectory=(path)
+      @subdirectory = path.to_s
+    end
+
+    # Set subdirectory to be applied to all paths and return `self`.
+    #
+    # @return [BaseDir] self
+    def with_subdirectory(path)
+      @subdirectory = path if path
+      self
+    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 = []
+      to_a.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 = []
+      to_a.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
+      to_a.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
+
+  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.