etcetera 0.12.0

data/lib/etcetera.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "etcetera/version"
+require_relative "etcetera/base_strategy"
+require_relative "etcetera/base_strategy/apple"
+require_relative "etcetera/base_strategy/windows"
+require_relative "etcetera/base_strategy/xdg"
+require_relative "etcetera/app_strategy"
+require_relative "etcetera/app_strategy/apple"
+require_relative "etcetera/app_strategy/unix"
+require_relative "etcetera/app_strategy/windows"
+require_relative "etcetera/app_strategy/xdg"
+
+# This is a Ruby library that allows you to determine the locations of configuration, data, cache & other files for your application.
+# Existing Ruby libraries generally do not give you a choice in terms of which standards/conventions they follow.
+# Etcetera, on the other hand, gives you the choice.
+#
+# = Conventions
+# Etcetera supports the following conventions:
+# - the {XDG base directory}[https://standards.freedesktop.org/basedir/latest/]
+# - Apple’s {Standard Directories}[https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html]
+# - Window’s {Known Folder Locations}[https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid]
+# - the "Unix Single-folder Convention" i.e. everything in <tt>~/.myapp</tt>
+#
+# = Strategies
+# If you want to get started quickly, you can use the following convenience functions that use the default strategies (as determined arbitrarily by yours truly) or the native strategies for each OS.
+#
+# == BaseStrategy
+# If you just want to get the path to a configuration, data, cache or another directory, you can use the +choose_base_strategy+ function.
+#
+#   require "etcetera"
+#
+#   strategy = Etcetera.choose_base_strategy
+#
+#   config_dir = strategy.config_dir
+#   data_dir = strategy.data_dir
+#   cache_dir = strategy.cache_dir
+#   state_dir = strategy.state_dir
+#   runtime_dir = strategy.runtime_dir
+#
+# == AppStrategy
+# If you want to get the path to a configuration, data, cache or another directory, and you want to follow the naming conventions for your application, you can use the +choose_app_strategy+ function.
+#
+# Let’s take an application created by <tt>Acme Corp</tt> with the name <tt>Frobnicator Plus</tt> and the top-level domain of <tt>org</tt> as an example.
+# - XDG strategy would place these in <tt>~/.config/frobnicator-plus</tt>.
+# - Unix strategy would place these in <tt>~/.frobnicator-plus</tt>.
+# - Apple strategy would place these in <tt>~/Library/Preferences/org.acme-corp.Frobnicator-Plus</tt>.
+# - Windows strategy would place these in <tt>~\AppData\Roaming\Acme Corp\Frobnicator Plus</tt>.
+#
+#   require "etcetera"
+#
+#   strategy = Etcetera.choose_app_strategy(Etcetera::AppStrategyArgs.new(
+#     top_level_domain: "org",
+#     author: "Acme Corp",
+#     app_name: "Frobnicator Plus"
+#   ))
+#
+#   config_dir = strategy.config_dir
+#   data_dir = strategy.data_dir
+#   cache_dir = strategy.cache_dir
+#   state_dir = strategy.state_dir
+#   runtime_dir = strategy.runtime_dir
+#
+# == Native Strategy
+#
+# +choose_base_strategy+ and +choose_app_strategy+ will use the +XDG+ strategy on Linux & macOS, and the +Windows+ strategy on \Windows.
+# This is used by most CLI tools & some GUI tools on each platform.
+#
+# If you're developing a GUI application, you might want to use the "Standard directories" on macOS by using +choose_native_strategy+ instead.
+# Note that if your application expects the user to modify the configuration files, you should still prefer the +XDG+ strategy on macOS.
+#
+# == Custom Conventions
+#
+# You aren’t limited to the built-in conventions – you can implement the relevant modules yourself. Please consider contributing these back, as the more preset conventions there are, the better.
+#
+# = More Examples
+# Say you were a hardened Unix veteran, and didn’t want to have any of this XDG nonsense, clutter in the home directory be damned! Instead of using +choose_app_strategy+ or +choose_base_strategy+, you can pick a strategy yourself. Here’s an example using the AppStrategy::Unix strategy – see its documentation to see what kind of folder structures it produces:
+#
+#   require "etcetera"
+#
+#   strategy = Etcetera::AppStrategy::Unix.new(Etcetera::AppStrategyArgs.new(
+#     top_level_domain: "com",
+#     author: "Hardened Unix Veteran Who Likes Short Command Names",
+#     app_name: "wry"
+#   ))
+#
+#   config_dir = strategy.config_dir # produces ~/.wry/
+#   # et cetera.
+#
+# Oftentimes the location of a configuration, data or cache directory is needed solely to create a path that starts inside it. For this purpose, AppStrategy implements a couple of convenience methods for you:
+#
+#   require "etcetera"
+#
+#   strategy = Etcetera.choose_app_strategy(Etcetera::AppStrategyArgs.new(
+#     top_level_domain: "org",
+#     author: "Acme Corp",
+#     app_name: "Frobnicator"
+#   ))
+#
+#   # Path to configuration directory.
+#   config_dir = strategy.config_dir
+#
+#   # Path to config.toml inside the configuration directory.
+#   config_file = strategy.in_config_dir("config.toml")
+#
+#   config_dir.join("config.toml") == config_file # => true
+module Etcetera
+  AppStrategyArgs = AppStrategy::AppStrategyArgs
+
+  # A convenience function that wraps the {home}[https://docs.ruby-lang.org/en/master/Dir.html#method-c-home] function from the standard library.
+  def self.home_dir
+    Pathname.new(Dir.home)
+  rescue ArgumentError
+    raise HomeDirError
+  end
+
+  # This error occurs when the home directory cannot be located.
+  class HomeDirError < StandardError
+    def initialize(message = "could not locate home directory")
+      super
+    end
+  end
+
+  # Returns the current OS’s default BaseStrategy.
+  # This uses the BaseStrategy::Windows strategy on \Windows, and BaseStrategy::Xdg everywhere else.
+  # This is the convention used by most CLI applications.
+  def self.choose_base_strategy = BaseStrategy.choose_base_strategy
+
+  # Returns the current OS’s default AppStrategy.
+  # This uses the AppStrategy::Windows strategy on \Windows, and AppStrategy::Xdg everywhere else.
+  # This is the convention used by most CLI applications.
+  def self.choose_app_strategy(args) = AppStrategy.choose_app_strategy(args)
+end

data/sig/etcetera/app_strategy/apple.rbs

@@ -0,0 +1,15 @@
+module Etcetera
+  module AppStrategy
+    class Apple < Data
+      include AppStrategy
+      include _AppStrategy
+
+      def self.new: (AppStrategyArgs args) -> instance
+
+      private
+
+      attr_reader base_strategy: BaseStrategy::Apple
+      attr_reader bundle_id: String
+    end
+  end
+end

data/sig/etcetera/app_strategy/unix.rbs

@@ -0,0 +1,14 @@
+module Etcetera
+  module AppStrategy
+    class Unix < Data
+      include AppStrategy
+      include _AppStrategy
+
+      def self.new: (AppStrategyArgs args) -> instance
+
+      private
+
+      attr_reader unixy_name: String
+    end
+  end
+end

data/sig/etcetera/app_strategy/windows.rbs

@@ -0,0 +1,15 @@
+module Etcetera
+  module AppStrategy
+    class Windows < Data
+      include AppStrategy
+      include _AppStrategy
+
+      def self.new: (AppStrategyArgs args) -> instance
+
+      private
+
+      attr_reader base_strategy: BaseStrategy::Windows
+      attr_reader author_app_name_path: Pathname
+    end
+  end
+end

data/sig/etcetera/app_strategy/xdg.rbs

@@ -0,0 +1,15 @@
+module Etcetera
+  module AppStrategy
+    class Xdg < Data
+      include AppStrategy
+      include _AppStrategy
+
+      def self.new: (AppStrategyArgs args) -> instance
+
+      private
+
+      attr_reader base_strategy: BaseStrategy::Xdg
+      attr_reader unixy_name: String
+    end
+  end
+end

data/sig/etcetera/app_strategy.rbs

@@ -0,0 +1,36 @@
+module Etcetera
+  # Allows applications to retrieve the paths of configuration, data, and cache directories specifically for them.
+  interface _AppStrategy
+    def home_dir: () -> Pathname
+    def config_dir: () -> Pathname
+    def data_dir: () -> Pathname
+    def cache_dir: () -> Pathname
+    def state_dir: () -> Pathname?
+    def runtime_dir: () -> Pathname?
+  end
+
+  # 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.
+  module AppStrategy : _AppStrategy
+    # The arguments to the creator method of an AppStrategy.
+    class AppStrategyArgs < Data
+      attr_reader top_level_domain: String
+      attr_reader author: String
+      attr_reader app_name: String
+
+      def self.new: (?top_level_domain: String, ?author: String, ?app_name: String) -> instance
+      def initialize: (?top_level_domain: String, ?author: String, ?app_name: String) -> void
+
+      def bundle_id: () -> String
+      def unixy_name: () -> String
+    end
+
+    def self.choose_native_strategy: (AppStrategyArgs args) -> native_app_strategy
+    def self.choose_app_strategy: (AppStrategyArgs args) -> default_app_strategy
+
+    def in_config_dir: (Pathname | String path) -> Pathname
+    def in_data_dir: (Pathname | String path) -> Pathname
+    def in_cache_dir: (Pathname | String path) -> Pathname
+    def in_state_dir: (Pathname | String path) -> Pathname?
+    def in_runtime_dir: (Pathname | String path) -> Pathname?
+  end
+end

data/sig/etcetera/base_strategy/apple.rbs

@@ -0,0 +1,10 @@
+module Etcetera
+  module BaseStrategy
+    class Apple < Data
+      include _BaseStrategy
+
+      def self.new: (?home_dir: Pathname) -> instance
+      def initialize: (?home_dir: Pathname) -> void
+    end
+  end
+end

data/sig/etcetera/base_strategy/windows.rbs

@@ -0,0 +1,10 @@
+module Etcetera
+  module BaseStrategy
+    class Windows < Data
+      include _BaseStrategy
+
+      def self.new: (?home_dir: Pathname) -> instance
+      def initialize: (?home_dir: Pathname) -> void
+    end
+  end
+end

data/sig/etcetera/base_strategy/xdg.rbs

@@ -0,0 +1,10 @@
+module Etcetera
+  module BaseStrategy
+    class Xdg < Data
+      include _BaseStrategy
+
+      def self.new: (?home_dir: Pathname) -> instance
+      def initialize: (?home_dir: Pathname) -> void
+    end
+  end
+end

data/sig/etcetera/base_strategy.rbs

@@ -0,0 +1,17 @@
+module Etcetera
+  # Provides configuration, data, and cache directories of the current user.
+  interface _BaseStrategy
+    def home_dir: () -> Pathname
+    def config_dir: () -> Pathname
+    def data_dir: () -> Pathname
+    def cache_dir: () -> Pathname
+    def state_dir: () -> Pathname?
+    def runtime_dir: () -> Pathname?
+  end
+
+  # These strategies simply provide the user’s configuration, data, and cache directories, without knowing about the application specifically.
+  module BaseStrategy
+    def self.choose_native_strategy: () -> native_base_strategy
+    def self.choose_base_strategy: () -> default_base_strategy
+  end
+end

data/sig/etcetera.rbs

@@ -0,0 +1,32 @@
+module Etcetera
+  # Version of the gem, mirroring the version of the Rust crate it ports.
+  VERSION: String
+
+  # This error occurs when the home directory cannot be located.
+  class HomeDirError < StandardError
+    def initialize: (?String message) -> void
+  end
+
+  # The strategy Etcetera::BaseStrategy.choose_native_strategy returns.
+  type native_base_strategy = BaseStrategy::Apple | BaseStrategy::Windows | BaseStrategy::Xdg
+
+  # The strategy Etcetera::BaseStrategy.choose_base_strategy returns.
+  type default_base_strategy = BaseStrategy::Windows | BaseStrategy::Xdg
+
+  # The strategy Etcetera::AppStrategy.choose_native_strategy returns.
+  type native_app_strategy = AppStrategy::Apple | AppStrategy::Windows | AppStrategy::Xdg
+
+  # The strategy Etcetera::AppStrategy.choose_app_strategy returns.
+  type default_app_strategy = AppStrategy::Windows | AppStrategy::Xdg
+
+  AppStrategyArgs: singleton(AppStrategy::AppStrategyArgs)
+
+  # A convenience function that wraps the home function from the standard library.
+  def self.home_dir: () -> Pathname
+
+  # Returns the current OS's default Etcetera::BaseStrategy.
+  def self.choose_base_strategy: () -> default_base_strategy
+
+  # Returns the current OS's default Etcetera::AppStrategy.
+  def self.choose_app_strategy: (AppStrategy::AppStrategyArgs args) -> default_app_strategy
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: etcetera
+version: !ruby/object:Gem::Version
+  version: 0.12.0
+platform: ruby
+authors:
+- Kerrick Long
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: |
+  An unopinionated library for obtaining configuration, data, cache, & other
+  directories. Etcetera supports the XDG base directory specification, Apple's
+  Standard Directories, Windows' Known Folder Locations, and the Unix
+  single-folder convention, and lets you choose which to follow.
+email:
+- me@kerricklong.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yaml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE-APACHE
+- LICENSE-MIT
+- LICENSE-WINDOWS-SYS
+- README.md
+- Rakefile
+- lib/etcetera.rb
+- lib/etcetera/app_strategy.rb
+- lib/etcetera/app_strategy/apple.rb
+- lib/etcetera/app_strategy/unix.rb
+- lib/etcetera/app_strategy/windows.rb
+- lib/etcetera/app_strategy/xdg.rb
+- lib/etcetera/base_strategy.rb
+- lib/etcetera/base_strategy/apple.rb
+- lib/etcetera/base_strategy/windows.rb
+- lib/etcetera/base_strategy/xdg.rb
+- lib/etcetera/version.rb
+- lib/etcetera/windows_sys.rb
+- sig/etcetera.rbs
+- sig/etcetera/app_strategy.rbs
+- sig/etcetera/app_strategy/apple.rbs
+- sig/etcetera/app_strategy/unix.rbs
+- sig/etcetera/app_strategy/windows.rbs
+- sig/etcetera/app_strategy/xdg.rbs
+- sig/etcetera/base_strategy.rbs
+- sig/etcetera/base_strategy/apple.rbs
+- sig/etcetera/base_strategy/windows.rbs
+- sig/etcetera/base_strategy/xdg.rbs
+homepage: https://github.com/Kerrick/etcetera_rb
+licenses:
+- MIT
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/Kerrick/etcetera_rb
+  changelog_uri: https://github.com/Kerrick/etcetera_rb/blob/ruby/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/etcetera
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.22
+specification_version: 4
+summary: An unopinionated library for obtaining configuration, data, cache, & other
+  directories
+test_files: []