initial commit! ヽ(^o^)丿

1 files changed, 299 insertions, 0 deletions

diff --git a/src/xdg_basedir.cr b/src/xdg_basedir.cr
new file mode 100644
index 0000000..b406841
--- /dev/null
+++ b/src/xdg_basedir.cr
@@ -0,0 +1,299 @@
+# This module implements an interface to the XDG Base Directories, compliant
+# with version 0.7 of the XDG Base Directory Specification.
+#
+# Provided are methods for locating XDG Base Directories at runtime, as well as
+# a helper method for easily building full file paths relative to them.
+#
+# Each of the operations below can be performed on one of four categories of
+# directories, designated via an argument *type* of value `:data`, `:config`,
+# `:cache`, or `:runtime`.
+#
+# - `:data` directories are used for storing and retrieving persistent files
+# across multiple runs of a program.
+# - `:config` directories are used for storing and retrieving a program's
+# configuration files.
+# - `:cache` directories are used for storing non-essential data which may or
+# may not be retained
+# - `:runtime` directories are used for storing runtime files (e.g. lock files
+# or sockets)
+#
+# For more details, please refer to the specification, which is available
+# online [here](https://specifications.freedesktop.org/basedir-spec/0.7/).
+module XDGBasedir
+  VERSION = "1.0.0"
+
+  # get the base directory into which files of a given *type* should be written
+  #
+  # Given a *type* of `:data`, `:config`, `:cache`, or `:runtime`, this method
+  # returns a single directory into which data of that type should be written,
+  # or else `nil`, if no appropriate candidate is found.
+  #
+  # If a directory is returned, it is guaranteed to always have a terminating
+  # '/' character, meaning that, when trying to write a file, it is safe to
+  # directly concatenate the directory and the file path that is to be written
+  # to within it.
+  #
+  # ### Example
+  #
+  #     dir = XDGBasedir.write_dir :config
+  #     if dir
+  #       File.write "#{dir}created/file.conf", "contents"
+  #     end
+  #
+  def self.write_dir(type = :config) : String?
+    case type
+    when :data
+      if ENV["XDG_DATA_HOME"]? && ENV["XDG_DATA_HOME"] != ""
+        s = "#{ENV["XDG_DATA_HOME"]}/"
+      else
+        if ENV["HOME"]?
+          s = "#{ENV["HOME"]}/.local/share/"
+        else
+          return nil
+        end
+      end
+
+    when :config
+      if ENV["XDG_CONFIG_HOME"]? && ENV["XDG_CONFIG_HOME"] != ""
+        s = "#{ENV["XDG_CONFIG_HOME"]}/"
+      else
+        if ENV["HOME"]?
+          s = "#{ENV["HOME"]}/.config/"
+        else
+          return nil
+        end
+      end
+
+    when :cache
+      if ENV["XDG_CACHE_HOME"]? && ENV["XDG_CACHE_HOME"] != ""
+        s = "#{ENV["XDG_CACHE_HOME"]}/"
+      else
+        if ENV["HOME"]?
+          s = "#{ENV["HOME"]}/.cache/"
+        else
+          return nil
+        end
+      end
+
+    when :runtime
+      if ENV["XDG_RUNTIME_DIR"]? && ENV["XDG_RUNTIME_DIR"] != ""
+        s = "#{ENV["XDG_RUNTIME_DIR"]}/"
+      else
+        # runtime dir has no fallback
+        return nil
+      end
+
+      # runtime dir must necessarily have certain permissions
+      unless File.directory?(s) && File.info(s).permissions.value == 0o0700
+        return nil
+      end
+
+    else
+      raise ArgumentError.new(
+        "type must be one of: :data, :config, :cache, :runtime"
+      )
+    end
+
+    # return result with slashes deduplicated. nil check required because the
+    # compiler can't work out that s will have a value here...
+    s ? s.gsub(/\/+/, "/") : nil
+
+  end
+
+  # get a list of base directories from which files of a given *type* can be
+  # read
+  #
+  # Given a type of `:data`, `:config`, `:cache`, or `:runtime`, this method
+  # returns a string array of directories from which data of that type should
+  # be read. If no appropriate candidates are found, it instead returns `nil`.
+  #
+  # The returned list will be ordered according to precedence. That is, given a
+  # returned list `l`, accessing a file should first be attempted from within
+  # `l[0]`, if that fails, be attempted from within `l[1]`, and so on.
+  #
+  # If a directory list is returned, those directories are guaranteed to always
+  # have a terminating '/' character, meaning that, when trying to access a
+  # file, it is safe to directly concatenate the directory and the file path
+  # that is to be accessed within it.
+  #
+  # ### Example
+  #
+  #     contents = nil
+  #     dir_list = XDGBasedir.read_dirs :config
+  #     
+  #     if dir_list
+  #       dir_list.each { |dir|
+  #         if File.file? "#{dir}target/file.conf"
+  #           contents = File.read "#{dir}target/file.conf"
+  #           break
+  #         end
+  #       }
+  #     end
+  #
+  def self.read_dirs(type = :config) : Array(String)?
+    case type
+    when :data
+      # first entry is the write dir, if it exists
+      if s = self.write_dir(:data)
+        l = [s]
+      else
+        l = [] of String
+      end
+
+      if ENV["XDG_DATA_DIRS"]? && !/^:*$/.match(ENV["XDG_DATA_DIRS"])
+        ENV["XDG_DATA_DIRS"].split(":").reject{|s| s == ""}.each{|s| l << s}
+      else
+        l << "/usr/local/share/"
+        l << "/usr/share/"
+      end
+
+    when :config
+      # first entry is the write dir, if it exists
+      if s = self.write_dir(:config)
+        l = [s]
+      else
+        l = [] of String
+      end
+
+      if ENV["XDG_CONFIG_DIRS"]? && !/^:*$/.match(ENV["XDG_CONFIG_DIRS"])
+        ENV["XDG_CONFIG_DIRS"].split(":").reject{|d| d == ""}.each{|s| l << s}
+      else
+        l << "/etc/xdg/"
+      end
+
+    when :cache
+      if ENV["XDG_CACHE_HOME"]? && ENV["XDG_CACHE_HOME"] != ""
+        l = ["#{ENV["XDG_CACHE_HOME"]}/"]
+      else
+        if ENV["HOME"]?
+          l = ["#{ENV["HOME"]}/.cache/"]
+        else
+          return nil
+        end
+      end
+
+    when :runtime
+      if ENV["XDG_RUNTIME_DIR"]? && ENV["XDG_RUNTIME_DIR"] != ""
+        s = "#{ENV["XDG_RUNTIME_DIR"]}/"
+      else
+        # runtime dir has no fallback
+        return nil
+      end
+
+      # runtime dir must necessarily have certain permissions
+      unless File.directory?(s) && File.info(s).permissions.value == 0o0700
+        return nil
+      else
+        l = [s]
+      end
+
+    else
+      raise ArgumentError.new(
+        "type must be one of: :data, :config, :cache, :runtime"
+      )
+    end
+
+    # return result with slashes deduplicated and a trailing slash present.
+    l ? l.map { |s| s.gsub(/\/+/, "/").sub(/[^\/]$/, "\\0/") } : nil
+
+  end
+
+  # for a given *relative_path*, get a full file path built against an
+  # appropriate base directory
+  # 
+  # This method takes a *relative_path*, the *type* of that path, and the
+  # *action* you intend to perform on it, and returns a full path, constructed
+  # by concatenating the *relative_path* to the most appropriate base
+  # directory. If an appropriate directory cannot be found, `nil` is returned.
+  #
+  # The *type* argument indicates what sort of file you intend to access at the
+  # full path (`:config`, `:data` ...), and the *action* argument indicates
+  # what you intend to to do with it (either `:read` or `:write`). Note that
+  # `:write` takes precedence over `:read`, so that if you intend to both read
+  # and write, choose `:write`
+  #
+  # ### Example
+  #
+  #     data = nil
+  #     path = XDGBasedir.full_path "relative/path.dat", :data, :read
+  #     
+  #     if path
+  #       data = File.read path
+  #     end
+  #
+  def self.full_path(relative_path, type = :config,
+                     action : Symbol = :read) : String?
+    unless action == :read || action == :write
+      raise ArgumentError.new(
+        "action must be one of: :read, :write"
+      )
+    end
+
+    case type
+    when :data, :config, :cache, :runtime
+      if action == :read
+        unless l = self.read_dirs(type)
+          return nil
+        end
+
+        # search the read dirs until relative_path is found
+        l.each { |d|
+          if File.exists?(d + relative_path)
+            return d + relative_path
+          end
+        }
+
+        # or else just return against the first read dir
+        l[0] + relative_path
+      else
+        d = self.write_dir(type)
+        d ? d + relative_path : nil
+      end
+    else
+      raise ArgumentError.new(
+        "type must be one of: :data, :config, :cache, :runtime"
+      )
+    end
+  end
+
+  # for a given *relative_path*, get a full file path built against an
+  # appropriate base directory
+  # 
+  # This method takes a *relative_path*, the *type* of that path, and the
+  # access *mode* with which that file is to be opened, and returns a full
+  # path, constructed by concatenating the *relative_path* to the most
+  # appropriate base directory. If an appropriate directory cannot be found,
+  # `nil` is returned.
+  #
+  # The *type* indicates what sort of file you intend to access at the full
+  # path (`:config`, `:data` ...), and the *mode* argument is a string, in the
+  # common format used by both C's `fopen` and Crystal's `File.open`. For more
+  # information, refer to `man fopen` or the Crystal standard library
+  # documentation for [File](https://crystal-lang.org/api/latest/File.html).
+  #
+  # This overloaded version of `full_path` is added for convenience, as, if you
+  # intend to call `File.open` on the produced full path, it might be easier to
+  # use the same *mode* argument for both methods.
+  #
+  # ### Example
+  #
+  #     data = nil
+  #     mode = "r"
+  #     path = XDGBasedir.full_path "relative/path.dat", :data, mode
+  #     
+  #     if path
+  #       data = File.open(path, mode) do |file|
+  #         file.gets_to_end
+  #       end
+  #     end
+  #
+  def self.full_path(relative_path, type = :config,
+                     mode : String = "r") : String?
+    if /^r[^+]*$/.match(mode)
+      self.full_path(relative_path, type, :read)
+    else
+      self.full_path(relative_path, type, :write)
+    end
+  end
+
+end