IF Commons GitHub

dirs

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-system FR-008

Where a program keeps its files on each system, by the conventions the system and the tools we depend on already have, never by one of ours (commons 0031-install-locations): the XDG Base Directory Specification on Linux and macOS (as git and gh do on both), and Windows' known folders on Windows (as gh does), with the XDG_* variables honored on every system where they are set. Every function takes the environment and the system as values, so that a test on one system proves the paths of another; nothing here reads the host.

Config is $XDG_CONFIG_HOME/<app> (else ~/.config/<app>) and %APPDATA%\<app>; data is $XDG_DATA_HOME/<app> (else ~/.local/share/<app>) and %LOCALAPPDATA%\<app>; state, which is what a program remembers between runs and a person would not want to back up, is $XDG_STATE_HOME/<app> (else ~/.local/state/<app>) and %LOCALAPPDATA%\<app>\state; cache is $XDG_CACHE_HOME/<app> (else ~/.cache/<app>) and %LOCALAPPDATA%\<app>\cache; the runtime folder (locks and sockets) is $XDG_RUNTIME_DIR/<app> where the variable is set and there is none otherwise, and the caller uses its state folder; user programs go in ~/.local/bin, which the XDG specification names for them, and Windows has no such folder (WinGet links the programs it installs into its own, which is already on the path, and a runtime's global install has its own). A value of an XDG_* variable that is not an absolute path is ignored, as the specification says.

import { dirsOf } from "./dirs.ts";
const env = (n: string): string | undefined => ({ HOME: "/home/a" })[n];
dirsOf("ergonex", env, "linux").config; // "/home/a/.config/ergonex"

Source: commons/system/src/dirs.ts

2 of 10 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

dirsnamespace
namespace dirs
dirs.Ostypeno test imports it
type Os = "linux" | "darwin" | "windows";

An operating system, by the names proc.build.os gives.

dirs.Envtypeno test imports it
type Env = (name: string) => string | undefined;

A variable's value, or undefined.

dirs.Dirstypeno test imports it
type Dirs = { readonly config: string | undefined; readonly data: string | undefined; readonly state: string | und… (440 characters)
type Dirs = {
  readonly config: string | undefined;
  readonly data: string | undefined;
  readonly state: string | undefined;
  readonly cache: string | undefined;
  /** For locks and sockets: undefined where `XDG_RUNTIME_DIR` is not set, and the caller uses `state`. */
  readonly runtime: string | undefined;
  /** Where a program a person installs is put: `~/.local/bin`; undefined on Windows. */
  readonly bin: string | undefined;
};

The folders a program keeps its files in; each is undefined where it cannot be found.

dirs.homeOffunctionno test imports it
function homeOf(env: Env, os: Os): string | undefined

The home folder: HOME, and on Windows USERPROFILE first.

dirs.dirsOffunctionno test imports it
function dirsOf(app: string, env: Env, os: Os): Dirs

The folders of the program app on the system os, from the variables env gives.

Ostypeno test imports it
type Os = "linux" | "darwin" | "windows";

An operating system, by the names proc.build.os gives.

Envtypeno test imports it
type Env = (name: string) => string | undefined;

A variable's value, or undefined.

Dirstypeno test imports it
type Dirs = { readonly config: string | undefined; readonly data: string | undefined; readonly state: string | und… (440 characters)
type Dirs = {
  readonly config: string | undefined;
  readonly data: string | undefined;
  readonly state: string | undefined;
  readonly cache: string | undefined;
  /** For locks and sockets: undefined where `XDG_RUNTIME_DIR` is not set, and the caller uses `state`. */
  readonly runtime: string | undefined;
  /** Where a program a person installs is put: `~/.local/bin`; undefined on Windows. */
  readonly bin: string | undefined;
};

The folders a program keeps its files in; each is undefined where it cannot be found.

homeOffunction
function homeOf(env: Env, os: Os): string | undefined

The home folder: HOME, and on Windows USERPROFILE first.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

dirsOffunction
function dirsOf(app: string, env: Env, os: Os): Dirs

The folders of the program app on the system os, from the variables env gives.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.