module

Logarithm::PathResolver

Cross-platform path resolution following XDG and FHS standards.

This module provides intelligent path resolution that works across different operating systems and installation scenarios. It follows the XDG Base Directory specification for user directories and FHS for system directories.

Supported Standards

  • XDG Base Directory: For user-specific data/config/cache
  • Filesystem Hierarchy Standard (FHS): For system-wide installation
  • Environment variable overrides: For custom installations

Directory Types

  • Data Directory: Model files, training data (~/.local/share/logarithm)
  • Config Directory: Configuration files (~/.config/logarithm)
  • Cache Directory: Temporary files, logs (~/.cache/logarithm)

Environment Variables

Override defaults with:

  • LOGARITHM_DATA_DIR: Custom data directory
  • LOGARITHM_CONFIG_DIR: Custom config directory
  • LOGARITHM_CACHE_DIR: Custom cache directory

Example Usage

# Get standard directories
data_dir = PathResolver.data_dir     # ~/.local/share/logarithm
config_dir = PathResolver.config_dir # ~/.config/logarithm
cache_dir = PathResolver.cache_dir   # ~/.cache/logarithm

# Ensure directories exist
full_path = PathResolver.ensure_directory(data_dir)

# Get config file path
config_file = PathResolver.default_config_path # ~/.config/logarithm/config.yml

Installation Scenarios

  • User installation: Uses XDG directories in home folder
  • System installation: Uses FHS directories (/var/lib, /etc, /var/cache)
  • Custom installation: Override with environment variables
  • Portable installation: Set all paths explicitly

Constants

APP_NAME = "logarithm"

Application name for XDG subdirectories

DEFAULT_XDG_CACHE_HOME = "~/.cache"
DEFAULT_XDG_CONFIG_HOME = "~/.config"
DEFAULT_XDG_DATA_HOME = "~/.local/share"

Default XDG paths

FHS_CACHE_DIR = "/var/cache/logarithm"
FHS_CONFIG_DIR = "/etc/logarithm"
FHS_DATA_DIR = "/var/lib/logarithm"

FHS paths for system installation

Log = ::Logarithm::Log.for("path_resolver")
LOGARITHM_CACHE_DIR = "LOGARITHM_CACHE_DIR"
LOGARITHM_CONFIG_DIR = "LOGARITHM_CONFIG_DIR"
LOGARITHM_DATA_DIR = "LOGARITHM_DATA_DIR"

Logarithm-specific environment variables

XDG_CACHE_HOME = "XDG_CACHE_HOME"
XDG_CONFIG_HOME = "XDG_CONFIG_HOME"
XDG_DATA_HOME = "XDG_DATA_HOME"

XDG Base Directory environment variables

Class methods

cache_dir

Gets the appropriate cache directory for temporary files.

Determines the best cache directory based on:

  1. LOGARITHM_CACHE_DIR environment variable (highest priority)
  2. FHS system directory if running as root (/var/cache/logarithm)
  3. XDG user directory (~/.cache/logarithm)

Returns: Absolute path to cache directory

Source
config_dir

Gets the appropriate config directory for configuration files.

Determines the best config directory based on:

  1. LOGARITHM_CONFIG_DIR environment variable (highest priority)
  2. FHS system directory if running as root (/etc/logarithm)
  3. XDG user directory (~/.config/logarithm)

Returns: Absolute path to config directory

Source
data_dir

Gets the appropriate data directory for model storage.

Determines the best data directory based on:

  1. LOGARITHM_DATA_DIR environment variable (highest priority)
  2. FHS system directory if running as root (/var/lib/logarithm)
  3. XDG user directory (~/.local/share/logarithm)

Returns: Absolute path to data directory

Source
default_config_path

Gets the default path for the configuration file.

Returns the standard location for logarithm's configuration file based on the resolved config directory.

Returns: Absolute path to config.yaml in the config directory

Source
ensure_directory(dir : String) : String

Ensures a directory exists and is writable.

Creates the directory (and parent directories) if they don't exist, then verifies the directory is writable. Raises an exception if the directory cannot be created or is not writable.

Parameters:

  • dir: Directory path to ensure (supports ~ expansion)

Returns: Absolute path to the ensured directory

Raises: Exception if directory cannot be created or is not writable

Source
expand_path(path : String) : String

Expand path with tilde expansion and absolute path resolution

Source