etcetera 0.12.0

data/lib/etcetera/app_strategy/xdg.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Etcetera
+  module AppStrategy
+    # This strategy implements the {XDG Base Directories Specification}[https://specifications.freedesktop.org/basedir/latest/]. It is the most common on Linux, but is increasingly being adopted elsewhere.
+    #
+    # This initial example removes all the XDG environment variables to show the strategy’s use of the XDG default directories.
+    #
+    #   require "etcetera"
+    #
+    #   # Remove the environment variables that the strategy reads from.
+    #   ENV.delete("XDG_CONFIG_HOME")
+    #   ENV.delete("XDG_DATA_HOME")
+    #   ENV.delete("XDG_CACHE_HOME")
+    #   ENV.delete("XDG_STATE_HOME")
+    #   ENV.delete("XDG_RUNTIME_DIR")
+    #
+    #   app_strategy = Etcetera::AppStrategy::Xdg.new(Etcetera::AppStrategy::AppStrategyArgs.new(
+    #     top_level_domain: "org",
+    #     author: "Acme Corp",
+    #     app_name: "Frobnicator Plus"
+    #   ))
+    #
+    #   home_dir = Etcetera.home_dir
+    #
+    #   app_strategy.home_dir == home_dir # => true
+    #   app_strategy.config_dir.relative_path_from(home_dir) # => #<Pathname:.config/frobnicator-plus>
+    #   app_strategy.data_dir.relative_path_from(home_dir) # => #<Pathname:.local/share/frobnicator-plus>
+    #   app_strategy.cache_dir.relative_path_from(home_dir) # => #<Pathname:.cache/frobnicator-plus>
+    #   app_strategy.state_dir.relative_path_from(home_dir) # => #<Pathname:.local/state/frobnicator-plus>
+    #   app_strategy.runtime_dir # => nil
+    #
+    # This next example gives the environment variables values:
+    #
+    #   require "etcetera"
+    #
+    #   # We need to conditionally set these to ensure that they are absolute paths both on Windows and other systems.
+    #   windows = Gem.win_platform?
+    #   config_path = windows ? "C:\\my_config_location\\" : "/my_config_location/"
+    #   data_path = windows ? "C:\\my_data_location\\" : "/my_data_location/"
+    #   cache_path = windows ? "C:\\my_cache_location\\" : "/my_cache_location/"
+    #   state_path = windows ? "C:\\my_state_location\\" : "/my_state_location/"
+    #   runtime_path = windows ? "C:\\my_runtime_location\\" : "/my_runtime_location/"
+    #
+    #   ENV["XDG_CONFIG_HOME"] = config_path
+    #   ENV["XDG_DATA_HOME"] = data_path
+    #   ENV["XDG_CACHE_HOME"] = cache_path
+    #   ENV["XDG_STATE_HOME"] = state_path
+    #   ENV["XDG_RUNTIME_DIR"] = runtime_path
+    #
+    #   app_strategy = Etcetera::AppStrategy::Xdg.new(Etcetera::AppStrategy::AppStrategyArgs.new(
+    #     top_level_domain: "org",
+    #     author: "Acme Corp",
+    #     app_name: "Frobnicator Plus"
+    #   ))
+    #
+    #   app_strategy.config_dir == Pathname.new(config_path).join("frobnicator-plus") # => true
+    #   app_strategy.data_dir == Pathname.new(data_path).join("frobnicator-plus") # => true
+    #   app_strategy.cache_dir == Pathname.new(cache_path).join("frobnicator-plus") # => true
+    #   app_strategy.state_dir == Pathname.new(state_path).join("frobnicator-plus") # => true
+    #   app_strategy.runtime_dir == Pathname.new(runtime_path).join("frobnicator-plus") # => true
+    #
+    # The XDG spec requires that when the environment variables’ values are not absolute paths, their values should be ignored. This example exemplifies this behaviour:
+    #
+    #   require "etcetera"
+    #
+    #   # Remove the environment variables that the strategy reads from.
+    #   ENV["XDG_CONFIG_HOME"] = "relative_path/"
+    #   ENV["XDG_DATA_HOME"] = "./another_one/"
+    #   ENV["XDG_CACHE_HOME"] = "yet_another/"
+    #   ENV["XDG_STATE_HOME"] = "./and_another"
+    #   ENV["XDG_RUNTIME_DIR"] = "relative_path/"
+    #
+    #   app_strategy = Etcetera::AppStrategy::Xdg.new(Etcetera::AppStrategy::AppStrategyArgs.new(
+    #     top_level_domain: "org",
+    #     author: "Acme Corp",
+    #     app_name: "Frobnicator Plus"
+    #   ))
+    #
+    #   home_dir = Etcetera.home_dir
+    #
+    #   # We still get the default values.
+    #   app_strategy.config_dir.relative_path_from(home_dir) # => #<Pathname:.config/frobnicator-plus>
+    #   app_strategy.data_dir.relative_path_from(home_dir) # => #<Pathname:.local/share/frobnicator-plus>
+    #   app_strategy.cache_dir.relative_path_from(home_dir) # => #<Pathname:.cache/frobnicator-plus>
+    #   app_strategy.state_dir.relative_path_from(home_dir) # => #<Pathname:.local/state/frobnicator-plus>
+    #   app_strategy.runtime_dir # => nil
+    class Xdg < Data.define(:base_strategy, :unixy_name)
+      include AppStrategy
+
+      # Create a new \Xdg \AppStrategy
+      def self.new(args) = super(base_strategy: BaseStrategy::Xdg.new, unixy_name: args.unixy_name)
+
+      private :base_strategy, :unixy_name
+
+      def home_dir = base_strategy.home_dir
+
+      def config_dir = base_strategy.config_dir.join(unixy_name)
+
+      def data_dir = base_strategy.data_dir.join(unixy_name)
+
+      def cache_dir = base_strategy.cache_dir.join(unixy_name)
+
+      def state_dir = base_strategy.state_dir.join(unixy_name)
+
+      def runtime_dir = base_strategy.runtime_dir&.join(unixy_name)
+    end
+  end
+end

data/lib/etcetera/app_strategy.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Etcetera
+  # These strategies require you to provide some information on your application, and they will in turn locate the configuration/data/cache directory specifically for your application.
+  #
+  # Allows applications to retrieve the paths of configuration, data, and cache directories specifically for them.
+  module AppStrategy
+    # The arguments to the creator method of an AppStrategy.
+    #
+    # +top_level_domain+:: The top level domain of the application, e.g. +com+, +org+, or <tt>io.github</tt>.
+    # +author+:: The name of the author of the application.
+    # +app_name+:: The application’s name. This should be capitalised if appropriate.
+    class AppStrategyArgs < Data.define(:top_level_domain, :author, :app_name)
+      def initialize(top_level_domain: "", author: "", app_name: "") = super
+
+      # Constructs a bunde identifier from an +AppStrategyArgs+.
+      #
+      #   require "etcetera"
+      #
+      #   strategy_args = Etcetera::AppStrategy::AppStrategyArgs.new(
+      #     top_level_domain: "org",
+      #     author: "Acme Corp",
+      #     app_name: "Frobnicator Plus"
+      #   )
+      #
+      #   strategy_args.bundle_id # => "org.acme-corp.Frobnicator-Plus"
+      def bundle_id
+        author = self.author.downcase.tr(" ", "-")
+        app_name = self.app_name.tr(" ", "-")
+        [top_level_domain, author, app_name].reject(&:empty?).join(".")
+      end
+
+      # Returns a ‘unixy’ version of the application’s name, akin to what would usually be used as a binary name.
+      #
+      #   require "etcetera"
+      #
+      #   strategy_args = Etcetera::AppStrategy::AppStrategyArgs.new(
+      #     top_level_domain: "org",
+      #     author: "Acme Corp",
+      #     app_name: "Frobnicator Plus"
+      #   )
+      #
+      #   strategy_args.unixy_name # => "frobnicator-plus"
+      def unixy_name = app_name.downcase.tr(" ", "-")
+    end
+
+    ##
+    # :method: home_dir
+    # :call-seq:
+    #   home_dir -> Pathname
+    #
+    # Gets the home directory of the current user.
+
+    # @!method home_dir
+    #   Gets the home directory of the current user.
+    #   @return [Pathname]
+
+    ##
+    # :method: config_dir
+    # :call-seq:
+    #   config_dir -> Pathname
+    #
+    # Gets the configuration directory for your application.
+
+    # @!method config_dir
+    #   Gets the configuration directory for your application.
+    #   @return [Pathname]
+
+    ##
+    # :method: data_dir
+    # :call-seq:
+    #   data_dir -> Pathname
+    #
+    # Gets the data directory for your application.
+
+    # @!method data_dir
+    #   Gets the data directory for your application.
+    #   @return [Pathname]
+
+    ##
+    # :method: cache_dir
+    # :call-seq:
+    #   cache_dir -> Pathname
+    #
+    # Gets the cache directory for your application.
+
+    # @!method cache_dir
+    #   Gets the cache directory for your application.
+    #   @return [Pathname]
+
+    ##
+    # :method: state_dir
+    # :call-seq:
+    #   state_dir -> Pathname or nil
+    #
+    # Gets the state directory for your application.
+    # Currently, only the Xdg & Unix strategies support
+    # this.
+
+    # @!method state_dir
+    #   Gets the state directory for your application.
+    #   Currently, only the {Etcetera::AppStrategy::Xdg Xdg} & {Etcetera::AppStrategy::Unix Unix} strategies support
+    #   this.
+    #   @return [Pathname, nil]
+
+    ##
+    # :method: runtime_dir
+    # :call-seq:
+    #   runtime_dir -> Pathname or nil
+    #
+    # Gets the runtime directory for your application.
+    # Currently, only the Xdg & Unix strategies support
+    # this.
+    #
+    # Note: The {XDG Base Directory Specification}[https://specifications.freedesktop.org/basedir/latest/] places additional requirements on this
+    # directory related to ownership, permissions, and persistence. This library does not check
+    # these requirements.
+
+    # @!method runtime_dir
+    #   Gets the runtime directory for your application.
+    #   Currently, only the {Etcetera::AppStrategy::Xdg Xdg} & {Etcetera::AppStrategy::Unix Unix} strategies support
+    #   this.
+    #
+    #   Note: The {XDG Base Directory Specification}[https://specifications.freedesktop.org/basedir/latest/] places additional requirements on this
+    #   directory related to ownership, permissions, and persistence. This library does not check
+    #   these requirements.
+    #   @return [Pathname, nil]
+
+    # Constructs a path inside your application’s configuration directory to which a path of your choice has been appended.
+    def in_config_dir(path) = config_dir.join(path)
+
+    # Constructs a path inside your application’s data directory to which a path of your choice has been appended.
+    def in_data_dir(path) = data_dir.join(path)
+
+    # Constructs a path inside your application’s cache directory to which a path of your choice has been appended.
+    def in_cache_dir(path) = cache_dir.join(path)
+
+    # Constructs a path inside your application’s state directory to which a path of your choice has been appended.
+    #
+    # Currently, this is only implemented for the Xdg strategy.
+    def in_state_dir(path) = state_dir&.join(path)
+
+    # Constructs a path inside your application’s runtime directory to which a path of your choice has been appended.
+    # Currently, only the Xdg & Unix strategies support
+    # this.
+    #
+    # See the note in #runtime_dir for more information.
+    def in_runtime_dir(path) = runtime_dir&.join(path)
+
+    # Returns the current OS’s native AppStrategy.
+    # This uses the Windows strategy on \Windows, Apple on macOS & iOS, and Xdg everywhere else.
+    # This is the convention used by most GUI applications.
+    def self.choose_native_strategy(args)
+      if Gem.win_platform? then Windows.new(args)
+      elsif RUBY_PLATFORM.include?("darwin") then Apple.new(args)
+      else Xdg.new(args)
+      end
+    end
+
+    # Returns the current OS’s default AppStrategy.
+    # This uses the Windows strategy on \Windows, and Xdg everywhere else.
+    # This is the convention used by most CLI applications.
+    def self.choose_app_strategy(args)
+      Gem.win_platform? ? Windows.new(args) : Xdg.new(args)
+    end
+  end
+end

data/lib/etcetera/base_strategy/apple.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Etcetera
+  module BaseStrategy
+    # This is the strategy created by \Apple for use on macOS and iOS devices. It is always used by GUI apps on macOS, and is sometimes used by command-line applications there too. iOS only has GUIs, so all iOS applications follow this strategy. The specification is available {here}[https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW1].
+    #
+    #   require "etcetera"
+    #
+    #   base_strategy = Etcetera::BaseStrategy::Apple.new
+    #
+    #   home_dir = Etcetera.home_dir
+    #
+    #   base_strategy.home_dir == home_dir # => true
+    #   base_strategy.config_dir.relative_path_from(home_dir) # => #<Pathname:Library/Preferences>
+    #   base_strategy.data_dir.relative_path_from(home_dir) # => #<Pathname:Library/Application Support>
+    #   base_strategy.cache_dir.relative_path_from(home_dir) # => #<Pathname:Library/Caches>
+    #   base_strategy.state_dir # => nil
+    #   base_strategy.runtime_dir # => nil
+    class Apple < Data.define(:home_dir)
+      # Create a new \Apple \BaseStrategy
+      def initialize(home_dir: Etcetera.home_dir) = super
+
+      def config_dir = home_dir.join("Library/Preferences/")
+
+      def data_dir = home_dir.join("Library/Application Support/")
+
+      def cache_dir = home_dir.join("Library/Caches/")
+
+      def state_dir = nil
+
+      def runtime_dir = nil
+    end
+  end
+end

data/lib/etcetera/base_strategy/windows.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Etcetera
+  module BaseStrategy # rubocop:disable Style/Documentation -- documented in base_strategy.rb
+    if Gem.win_platform?
+      require_relative "../windows_sys"
+
+      # The C runtime function the crate declares in an `extern "C"` block.
+      module CRT # :nodoc: all
+        extend Fiddle::Importer
+
+        dlload "ucrtbase.dll"
+        extern "size_t wcslen(void* buf)"
+      end
+      private_constant :CRT
+    end
+
+    # This strategy follows Windows’ conventions. It seems that all \Windows GUI apps, and some command-line ones follow this pattern. The specification is available {here}[https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid].
+    #
+    # This initial example removes all the relevant environment variables to show the strategy’s use of the:
+    # - (on \Windows) SHGetKnownFolderPath API.
+    # - (on non-Windows) \Windows default directories.
+    #
+    #   require "etcetera"
+    #
+    #   # Remove the environment variables that the strategy reads from.
+    #   ENV.delete("HOME")
+    #   ENV.delete("APPDATA")
+    #   ENV.delete("LOCALAPPDATA")
+    #
+    #   base_strategy = Etcetera::BaseStrategy::Windows.new
+    #
+    #   home_dir = Etcetera.home_dir
+    #
+    #   base_strategy.home_dir == home_dir # => true
+    #   base_strategy.config_dir.relative_path_from(home_dir) # => #<Pathname:AppData/Roaming>
+    #   base_strategy.data_dir.relative_path_from(home_dir) # => #<Pathname:AppData/Roaming>
+    #   base_strategy.cache_dir.relative_path_from(home_dir) # => #<Pathname:AppData/Local>
+    #   base_strategy.state_dir # => nil
+    #   base_strategy.runtime_dir # => nil
+    #
+    # This next example gives the environment variables values:
+    #
+    #   require "etcetera"
+    #
+    #   windows = Gem.win_platform?
+    #   home_path = windows ? "C:/foo/" : Etcetera.home_dir.to_s
+    #   data_path = windows ? "C:\\bar\\" : "/bar/"
+    #   cache_path = windows ? "C:\\baz\\" : "/baz/"
+    #
+    #   ENV["HOME"] = home_path
+    #   ENV["APPDATA"] = data_path
+    #   ENV["LOCALAPPDATA"] = cache_path
+    #
+    #   base_strategy = Etcetera::BaseStrategy::Windows.new
+    #
+    #   base_strategy.home_dir == Pathname.new(home_path) # => true
+    #   base_strategy.config_dir == Pathname.new(data_path) # => true
+    #   base_strategy.data_dir == Pathname.new(data_path) # => true
+    #   base_strategy.cache_dir == Pathname.new(cache_path) # => true
+    #   base_strategy.state_dir # => nil
+    #   base_strategy.runtime_dir # => nil
+    class Windows < Data.define(:home_dir)
+      # Create a new \Windows \BaseStrategy
+      def initialize(home_dir: Etcetera.home_dir) = super
+
+      def config_dir = data_dir
+
+      def data_dir = dir_inner("APPDATA") || home_dir.join("AppData").join("Roaming")
+
+      def cache_dir = dir_inner("LOCALAPPDATA") || home_dir.join("AppData").join("Local")
+
+      def state_dir = nil
+
+      def runtime_dir = nil
+
+      private
+
+      def dir_inner(env)
+        value = ENV.fetch(env, "")
+        value.empty? ? dir_crt(env) : Pathname.new(value)
+      end
+
+      if Gem.win_platform?
+        # Ref: https://github.com/rust-lang/cargo/blob/home-0.5.11/crates/home/src/windows.rs
+        # We should keep this code in sync with the above.
+        def dir_crt(env)
+          folder_id = case env
+                      when "APPDATA" then WindowsSys::FOLDERID_RoamingAppData
+                      when "LOCALAPPDATA" then WindowsSys::FOLDERID_LocalAppData
+                      else return nil
+                      end
+
+          path = Fiddle::Pointer.new(0)
+          case WindowsSys.SHGetKnownFolderPath(folder_id.to_ptr, WindowsSys::KF_FLAG_DONT_VERIFY, nil, path.ref)
+          when WindowsSys::S_OK
+            path_slice = path[0, CRT.wcslen(path) * 2]
+            s = path_slice.force_encoding(Encoding::UTF_16LE).encode(Encoding::UTF_8, invalid: :replace)
+            WindowsSys.CoTaskMemFree(path)
+            Pathname.new(s)
+          else
+            # Free any allocated memory even on failure. A null ptr is a no-op for `CoTaskMemFree`.
+            WindowsSys.CoTaskMemFree(path)
+            nil
+          end
+        end
+      else
+        def dir_crt(_env) = nil
+      end
+    end
+  end
+end

data/lib/etcetera/base_strategy/xdg.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Etcetera
+  module BaseStrategy
+    # This strategy implements the {XDG Base Directories Specification}[https://specifications.freedesktop.org/basedir/latest/]. It is the most common on Linux, but is increasingly being adopted elsewhere.
+    #
+    # This initial example removes all the XDG environment variables to show the strategy’s use of the XDG default directories.
+    #
+    #   require "etcetera"
+    #
+    #   # Remove the environment variables that the strategy reads from.
+    #   ENV.delete("XDG_CONFIG_HOME")
+    #   ENV.delete("XDG_DATA_HOME")
+    #   ENV.delete("XDG_CACHE_HOME")
+    #   ENV.delete("XDG_STATE_HOME")
+    #   ENV.delete("XDG_RUNTIME_DIR")
+    #
+    #   base_strategy = Etcetera::BaseStrategy::Xdg.new
+    #
+    #   home_dir = Etcetera.home_dir
+    #
+    #   base_strategy.home_dir == home_dir # => true
+    #   base_strategy.config_dir.relative_path_from(home_dir) # => #<Pathname:.config>
+    #   base_strategy.data_dir.relative_path_from(home_dir) # => #<Pathname:.local/share>
+    #   base_strategy.cache_dir.relative_path_from(home_dir) # => #<Pathname:.cache>
+    #   base_strategy.state_dir.relative_path_from(home_dir) # => #<Pathname:.local/state>
+    #   base_strategy.runtime_dir # => nil
+    #
+    # This next example gives the environment variables values:
+    #
+    #   require "etcetera"
+    #
+    #   # We need to conditionally set these to ensure that they are absolute paths both on Windows and other systems.
+    #   windows = Gem.win_platform?
+    #   config_path = windows ? "C:\\foo\\" : "/foo/"
+    #   data_path = windows ? "C:\\bar\\" : "/bar/"
+    #   cache_path = windows ? "C:\\baz\\" : "/baz/"
+    #   state_path = windows ? "C:\\foobar\\" : "/foobar/"
+    #   runtime_path = windows ? "C:\\qux\\" : "/qux/"
+    #
+    #   ENV["XDG_CONFIG_HOME"] = config_path
+    #   ENV["XDG_DATA_HOME"] = data_path
+    #   ENV["XDG_CACHE_HOME"] = cache_path
+    #   ENV["XDG_STATE_HOME"] = state_path
+    #   ENV["XDG_RUNTIME_DIR"] = runtime_path
+    #
+    #   base_strategy = Etcetera::BaseStrategy::Xdg.new
+    #
+    #   base_strategy.config_dir == Pathname.new(config_path) # => true
+    #   base_strategy.data_dir == Pathname.new(data_path) # => true
+    #   base_strategy.cache_dir == Pathname.new(cache_path) # => true
+    #   base_strategy.state_dir == Pathname.new(state_path) # => true
+    #   base_strategy.runtime_dir == Pathname.new(runtime_path) # => true
+    #
+    # The XDG spec requires that when the environment variables’ values are not absolute paths, their values should be ignored. This example exemplifies this behaviour:
+    #
+    #   require "etcetera"
+    #
+    #   # Remove the environment variables that the strategy reads from.
+    #   ENV["XDG_CONFIG_HOME"] = "foo/"
+    #   ENV["XDG_DATA_HOME"] = "bar/"
+    #   ENV["XDG_CACHE_HOME"] = "baz/"
+    #   ENV["XDG_STATE_HOME"] = "foobar/"
+    #   ENV["XDG_RUNTIME_DIR"] = "qux/"
+    #
+    #   base_strategy = Etcetera::BaseStrategy::Xdg.new
+    #
+    #   home_dir = Etcetera.home_dir
+    #
+    #   # We still get the default values.
+    #   base_strategy.config_dir.relative_path_from(home_dir) # => #<Pathname:.config>
+    #   base_strategy.data_dir.relative_path_from(home_dir) # => #<Pathname:.local/share>
+    #   base_strategy.cache_dir.relative_path_from(home_dir) # => #<Pathname:.cache>
+    #   base_strategy.state_dir.relative_path_from(home_dir) # => #<Pathname:.local/state>
+    #   base_strategy.runtime_dir # => nil
+    class Xdg < Data.define(:home_dir)
+      # Create a new \Xdg \BaseStrategy
+      def initialize(home_dir: Etcetera.home_dir) = super
+
+      def config_dir = env_var_or_default("XDG_CONFIG_HOME", ".config/")
+
+      def data_dir = env_var_or_default("XDG_DATA_HOME", ".local/share/")
+
+      def cache_dir = env_var_or_default("XDG_CACHE_HOME", ".cache/")
+
+      def state_dir = env_var_or_default("XDG_STATE_HOME", ".local/state/")
+
+      def runtime_dir = env_var_or_none("XDG_RUNTIME_DIR")
+
+      private
+
+      def env_var_or_none(env_var)
+        path = ENV[env_var]&.then { Pathname.new(it) }
+
+        # Return nil if the path obtained from the environment variable isn’t absolute.
+        path if path&.absolute?
+      end
+
+      def env_var_or_default(env_var, default) = env_var_or_none(env_var) || home_dir.join(default)
+    end
+  end
+end

data/lib/etcetera/base_strategy.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Etcetera
+  # These strategies simply provide the user’s configuration, data, and cache directories, without knowing about the application specifically.
+  #
+  # Provides configuration, data, and cache directories of the current user.
+  module BaseStrategy
+    ##
+    # :method: home_dir
+    # :call-seq:
+    #   home_dir -> Pathname
+    #
+    # Gets the home directory of the current user.
+
+    # @!method home_dir
+    #   Gets the home directory of the current user.
+    #   @return [Pathname]
+
+    ##
+    # :method: config_dir
+    # :call-seq:
+    #   config_dir -> Pathname
+    #
+    # Gets the user’s configuration directory.
+
+    # @!method config_dir
+    #   Gets the user’s configuration directory.
+    #   @return [Pathname]
+
+    ##
+    # :method: data_dir
+    # :call-seq:
+    #   data_dir -> Pathname
+    #
+    # Gets the user’s data directory.
+
+    # @!method data_dir
+    #   Gets the user’s data directory.
+    #   @return [Pathname]
+
+    ##
+    # :method: cache_dir
+    # :call-seq:
+    #   cache_dir -> Pathname
+    #
+    # Gets the user’s cache directory.
+
+    # @!method cache_dir
+    #   Gets the user’s cache directory.
+    #   @return [Pathname]
+
+    ##
+    # :method: state_dir
+    # :call-seq:
+    #   state_dir -> Pathname or nil
+    #
+    # Gets the user’s state directory.
+    # Currently, only the Xdg strategy supports this.
+
+    # @!method state_dir
+    #   Gets the user’s state directory.
+    #   Currently, only the {Etcetera::BaseStrategy::Xdg Xdg} strategy supports this.
+    #   @return [Pathname, nil]
+
+    ##
+    # :method: runtime_dir
+    # :call-seq:
+    #   runtime_dir -> Pathname or nil
+    #
+    # Gets the user’s runtime directory.
+    # Currently, only the Xdg strategy supports this.
+    #
+    # Note: The {XDG Base Directory Specification}[https://specifications.freedesktop.org/basedir/latest/] places additional requirements on this
+    # directory related to ownership, permissions, and persistence. This library does not check
+    # these requirements.
+
+    # @!method runtime_dir
+    #   Gets the user’s runtime directory.
+    #   Currently, only the {Etcetera::BaseStrategy::Xdg Xdg} strategy supports this.
+    #
+    #   Note: The {XDG Base Directory Specification}[https://specifications.freedesktop.org/basedir/latest/] places additional requirements on this
+    #   directory related to ownership, permissions, and persistence. This library does not check
+    #   these requirements.
+    #   @return [Pathname, nil]
+
+    # Returns the current OS’s native BaseStrategy.
+    # This uses the Windows strategy on \Windows, Apple on macOS & iOS, and Xdg everywhere else.
+    # This is the convention used by most GUI applications.
+    def self.choose_native_strategy
+      if Gem.win_platform? then Windows.new
+      elsif RUBY_PLATFORM.include?("darwin") then Apple.new
+      else Xdg.new
+      end
+    end
+
+    # Returns the current OS’s default BaseStrategy.
+    # This uses the Windows strategy on \Windows, and Xdg everywhere else.
+    # This is the convention used by most CLI applications.
+    def self.choose_base_strategy
+      Gem.win_platform? ? Windows.new : Xdg.new
+    end
+  end
+end

data/lib/etcetera/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Etcetera
+  # Version of the gem, mirroring the version of the Rust crate it ports.
+  VERSION = "0.12.0"
+end

data/lib/etcetera/windows_sys.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "fiddle/import"
+
+module Etcetera
+  # The parts of the windows-sys crate that the crate uses, bound with Fiddle.
+  # Only Windows loads this, as only Windows builds of the crate depend on it.
+  #
+  # Derived from windows-sys 0.61.2 (https://github.com/microsoft/windows-rs),
+  # Copyright (c) Microsoft Corporation, used under the MIT License; see
+  # LICENSE-WINDOWS-SYS.
+  module WindowsSys # :nodoc: all
+    # :stopdoc:
+
+    extend Fiddle::Importer
+
+    dlload "shell32.dll", "combase.dll"
+
+    GUID = struct(["uint32_t data1", "uint16_t data2", "uint16_t data3", "uint8_t data4[8]"])
+
+    def GUID.from_u128(uuid)
+      malloc(Fiddle::RUBY_FREE).tap do |guid|
+        guid.data1 = uuid >> 96
+        guid.data2 = uuid >> 80 & 0xffff
+        guid.data3 = uuid >> 64 & 0xffff
+        guid.data4 = [uuid & 0xffff_ffff_ffff_ffff].pack("Q>").bytes
+      end
+    end
+
+    S_OK = 0
+    KF_FLAG_DONT_VERIFY = 16_384
+    FOLDERID_LocalAppData = GUID.from_u128(0xf1b32785_6fba_4fcf_9d55_7b8e7f157091)
+    FOLDERID_RoamingAppData = GUID.from_u128(0x3eb685db_65f9_4cf6_a03a_e3ef65729f3d)
+
+    extern "int32_t SHGetKnownFolderPath(void* rfid, uint32_t dwflags, void* htoken, void* ppszpath)"
+    extern "void CoTaskMemFree(void* pv)"
+  end
+  private_constant :WindowsSys
+end