Etcetera

This is a Ruby port of a Rust library that allows you to determine the locations of configuration, data, cache & other files for your application. Existing Rust 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.

Minimum Ruby version: 4.0.0

Note: Ruby 4.0.0 is required because Pathname became a core class & fiddle became a bundled gem in that version.

Etcetera supports the following conventions:

• the XDG base directory
• Apple's Standard Directories
• Window's Known Folder Locations
• the "Unix Single-folder Convention" i.e. everything in ~/.myapp

Etcetera has 2 modes of operation: BaseStrategy & AppStrategy:

• With BaseStrategy, you just get the location of the respective directory. For eg. for config_dir:
  • XDG: ~/.config
  • Apple: ~/Library/Preferences
  • Windows: ~\AppData\Roaming
• With AppStrategy, you provide additional information to get the location of your app directory. For eg. if you provide the following details: top_level_domain: "org", author: "Acme Corp", app_name: "Frobnicator Plus", you'll get:
  • XDG: ~/.config/frobnicator-plus
  • Unix: ~/.frobnicator-plus
  • Apple: ~/Library/Preferences/org.acme-corp.Frobnicator-Plus
  • Windows: ~\AppData\Roaming\Acme Corp\Frobnicator Plus

Note: the location of the home (~) is determined by Dir.home.

Etcetera also provides convenience functions for selecting the appropriate strategy on each platform:

• BaseStrategy.choose_base_strategy & AppStrategy.choose_app_strategy: Uses Windows on Windows & XDG everywhere else. This is used by most CLI tools & some GUI tools on each platform.
• BaseStrategy.choose_native_strategy & AppStrategy.choose_native_strategy: Uses Windows on Windows, Apple on macOS/iOS, & XDG everywhere else. This is used by most GUI applications on each platform.

See the documentation for examples.

This is a port of the Rust crate of the same name, version 0.12.0. Like the crate, it leans on its language's standard library, so it differs from the crate wherever Ruby's standard library differs from Rust's:

• Directories are Pathnames rather than PathBufs, & missing directories are nil rather than None.
• Pathname#== compares paths as strings, so Pathname.new("/foo/") != Pathname.new("/foo"), unlike Path's component-wise comparison.
• Dir.home & std::env::home_dir don't always agree on the home directory, for eg. when HOME is unset or empty, or on Windows when HOME & USERPROFILE differ.
• On Windows, Pathname#absolute? accepts paths such as /foo & C:foo that Path::is_absolute rejects, so the Xdg strategy honours an XDG_CONFIG_HOME of /foo there.
• Strategies & AppStrategyArgs are Data value objects.
• Ruby can't tell macOS & iOS apart, so choose_native_strategy picks Apple on any darwin platform.
• The Known Folder bindings in Etcetera::WindowsSys are derived from windows-sys, which the crate depends on; see LICENSE-WINDOWS-SYS.