## Usage

Add the following line of code to your [Node.js](https://nodejs.org/) application:

```js
const xdg = require('{%= name %}');
```

The main export is a function that may be called with an options object:

```js
const dirs = xdg(/* options */);
console.log(dirs);

/* This output is on MacOS, see examples for Linux and Windows below */
console.log(dirs.config); // => '/Users/jonschlinkert/Library/Preferences'
console.log(dirs.cache); // => '/Users/jonschlinkert/Library/Caches'
console.log(dirs.data); // => '/Users/jonschlinkert/Library/Application Support'
```

See [example output](#examples) by platform.

## Options

<details>
<summary><strong>Click to see all available options</strong></summary>
<br>
The following options are available for customizing behavior and/or testing behavior.

| Option | Type | Description | Default Value |
| --- | --- | --- | --- |
| `cachedir`   | `string`   | Override the default `cachedir` | Platform specific, see [below](#examples) |
| `configdir`  | `string`   | Override the default `configdir` |  |
| `datadir`    | `string`   | Override the default `datadir` |  |
| `env`        | `object`   | The `env` object to use for getting paths. | `process.env` |
| `expanded`   | `boolean`  | Expand paths into an object. See the [Expanded Paths](#expanded-paths) example for more details. | undefined |
| `homedir`    | `string`   | The user's home directory. | `os.homedir()` |
| `platform`   | `string`   | The platform to use: `darwin`, `linux`, `win32` | `process.platform` |
| `resolve`    | `function` | Custom function for resolving paths to each directory. The default function attempts to respect casing in the user's existing directories. | undefined |
| `runtimedir` | `string`   | Override the default `runtimedir` |  |
| `subdir`     | `string`   | A sub-directory to join to the path, typically the name of your application. This path is joined differently on each platform. See [examples](#examples). | `xdg` |
| `tempdir`    | `string`   | The temp directory to use. | `os.tmpdir()` |

See [examples](#xamples) below.

</details>

## Examples

<details>
<summary><strong>Click to see example for platform-specific paths</strong></summary>
<br>
Get paths for a specific platform.
<br>

```js
console.log(xdg.darwin());
console.log(xdg.linux());
console.log(xdg.win32());
// or, if you want "expanded" paths (see the "expanded paths" example)
console.log(xdg({ expanded: true, platform: 'darwin' }));
console.log(xdg({ expanded: true, platform: 'linux' }));
console.log(xdg({ expanded: true, platform: 'win32' }));
```

</details>

<details>
<summary><strong>Click to see example with no options</strong></summary>
<br>
The following examples show what the paths look like when no options are passed.
<br>

```js
console.log(xdg());
```

### MacOS (darwin)

```js
{
  cache: '/Users/jonschlinkert/Library/Caches/xdg',
  config: '/Users/jonschlinkert/Library/Preferences/xdg',
  configdirs: [ '/Users/jonschlinkert/Library/Preferences/xdg', '/etc/xdg' ],
  data: '/Users/jonschlinkert/Library/Application Support/xdg',
  datadirs: [
    '/Users/jonschlinkert/Library/Application Support/xdg',
    '/usr/local/share/',
    '/usr/share/'
  ],
  runtime: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/xdg'
}
```

### Linux

```js
{
  cache: '/Users/jonschlinkert/.cache/xdg',
  config: '/Users/jonschlinkert/.config/xdg',
  configdirs: [ '/Users/jonschlinkert/.config/xdg', '/etc/xdg' ],
  data: '/Users/jonschlinkert/.local/share/xdg',
  datadirs: [
    '/Users/jonschlinkert/.local/share/xdg',
    '/usr/local/share/',
    '/usr/share/'
  ],
  runtime: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/xdg'
}
```

### Windows (win32)

```js
{
  cache: '/Users/jonschlinkert/AppData/Local/xdg/Cache',
  config: '/Users/jonschlinkert/AppData/Roaming/xdg/Config',
  configdirs: [ '/Users/jonschlinkert/AppData/Roaming/xdg/Config' ],
  data: '/Users/jonschlinkert/AppData/Local/xdg/Data',
  datadirs: [ '/Users/jonschlinkert/AppData/Local/xdg/Data' ],
  runtime: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/xdg'
}
```

</details>

<details>
<summary><strong>Click to see "expanded" paths example</strong></summary>
<br>
Running the following example returns an object with "expanded" paths, where `config` and `configdirs` are converted to `config.home` and `config.dirs`, etc. Additionally, `cwd`, `home` and `temp` paths are added for convenience.
<br>

```js
console.log(xdg({ expanded: true, subdir: 'FooBar' }));
```

**Extra directories**

Note that the `expanded` object includes four additional path properties for convenience:

- `cwd` - set via `options.cwd` or `process.cwd()`
- `home` - set via `options.homedir` or `os.homedir()`
- `temp` - set via `options.tempdir` or `os.tmpdir()`
- `cache.logs` - set at `path.join(cachedir, 'logs')`

### MacOS (darwin)

```js
{
  cwd: '/Users/jonschlinkert/dev/@folder/xdg',
  home: '/Users/jonschlinkert',
  temp: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T',
  cache: { 
    home: '/Users/jonschlinkert/Library/Caches/FooBar',
    logs: '/Users/jonschlinkert/Library/Caches/FooBar/Logs' 
  },
  config: {
    home: '/Users/jonschlinkert/Library/Preferences/FooBar',
    dirs: [ '/Users/jonschlinkert/Library/Preferences/FooBar', '/etc/FooBar' ]
  },
  data: {
    home: '/Users/jonschlinkert/Library/Application Support/FooBar',
    dirs: [
      '/Users/jonschlinkert/Library/Application Support/FooBar',
      '/usr/local/share/',
      '/usr/share/'
    ]
  },
  runtime: { home: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/FooBar' }
}
```

### Linux

```js
{
  cwd: '/Users/jonschlinkert/dev/@folder/xdg',
  home: '/Users/jonschlinkert',
  temp: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T',
  cache: { 
    home: '/Users/jonschlinkert/.cache/FooBar',
    logs: '/Users/jonschlinkert/.cache/FooBar/Logs'
  },
  config: {
    home: '/Users/jonschlinkert/.config/FooBar',
    dirs: [ '/Users/jonschlinkert/.config/FooBar', '/etc/FooBar' ]
  },
  data: {
    home: '/Users/jonschlinkert/.local/share/FooBar',
    dirs: [
      '/Users/jonschlinkert/.local/share/FooBar',
      '/usr/local/share/',
      '/usr/share/'
    ]
  },
  runtime: { home: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/FooBar' }
}
```

### Windows (win32)

```js
{
  cwd: '/Users/jonschlinkert/dev/@folder/xdg',
  home: '/Users/jonschlinkert',
  temp: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T',
  cache: { 
    home: '/Users/jonschlinkert/AppData/Local/FooBar/Cache',
    logs: '/Users/jonschlinkert/AppData/Local/FooBar/Cache/Logs'
  },
  config: {
    home: '/Users/jonschlinkert/AppData/Roaming/FooBar/Config',
    dirs: [ '/Users/jonschlinkert/AppData/Roaming/FooBar/Config' ]
  },
  data: {
    home: '/Users/jonschlinkert/AppData/Local/FooBar/Data',
    dirs: [ '/Users/jonschlinkert/AppData/Local/FooBar/Data' ]
  },
  runtime: { home: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/FooBar' }
}
```

</details>

# API

Aside from the main export, `xdg()`, several platform-specific methods are exposed to simplify getting paths for specific platforms. Note that you can accomplish the same thing by passing the platform on the options to the main export, e.g. `{ platform: 'linux' }`.

The main export, and each method, returns an object with the following properties (see the [XDG Base Directories](#xdg-base-directory) docs below for more details on how each property is set):

- `cache`
- `config`
- `configdirs`
- `data`
- `datadirs`
- `runtime`

## Main Export

{%= apidocs('index.js') %}
{%= apidocs('lib/userdirs.js') %}

## XDG Base Directories

This documentation is from the Arch Linux [XDG Base Directory](https://wiki.archlinux.org/index.php/XDG_Base_Directory) docs.

### User directories

- `XDG_CONFIG_HOME`
  * Where user-specific configurations should be written (analogous to `/etc`).
  * Should default to `$HOME/.config`.

- `XDG_CACHE_HOME`
  * Where user-specific non-essential (cached) data should be written (analogous to `/var/cache`).
  * Should default to `$HOME/.cache`.

- `XDG_DATA_HOME`
  * Where user-specific data files should be written (analogous to `/usr/share`).
  * Should default to `$HOME/.local/share`.

- `XDG_RUNTIME_DIR`
  * Used for non-essential, user-specific data files such as sockets, named pipes, etc.
  * Not required to have a default value; warnings should be issued if not set or equivalents provided.
  * Must be owned by the user with an access mode of `0700`.
  * Filesystem fully featured by standards of OS.
  * Must be on the local filesystem.
  * May be subject to periodic cleanup.
  * Modified every 6 hours or set sticky bit if persistence is desired.
  * Can only exist for the duration of the user's login.
  * Should not store large files as it may be mounted as a tmpfs.

### System directories

- `XDG_DATA_DIRS`
  * List of directories seperated by `:` (analogous to `PATH`).
  * Should default to `/usr/local/share:/usr/share`.

- `XDG_CONFIG_DIRS`
  * List of directories seperated by `:` (analogous to `PATH`).
  * Should default to `/etc/xdg`.