ripunzel/README.md

# reddit-post-dump

## Installation
reddit-post-dump requires a arbitrarily recent version of Node.js. Before use, dependencies must be installed as follows:

`npm install`

## Usage
`node app.js --user={username}`

### Optional parameters
* `--users={user1,user2}`: You may fetch posts from multiple users by either supplying a comma-separated list of usernames (no spaces) with `--users`, or by using multiple individual `--user` arguments
* `--limit={number}`: Maximum amount posts per user to fetch content from
* `--sort={method}`: How posts should be sorted while fetched. This affects the `$postIndex` variable, and in combination with a `--limit` decides what posts will be included.

### Examples
* `node app.js --user=ThePendulum`
* `node app.js --user=ThePendulum --limit=10 --sort=top`

## Configuration
The default configuration aims to be sensible, and the application may be used without any further tweaking. However, a multitude of options make this utility particularly powerful.

To change the configuration, please refer to `config/default.js`. I recommend not editing this file directly, but instead making a copy `config/local.js`, as the default configuration might be overwritten in updates and can be a useful reference for restoring any detrimental configuration errors. The structure of `config/local.js` must match the structure of the default configuration, but does not necessarily need to contain any properties you do not wish to override. If preferred, you may instead use JSON in `config/local.json`.

### Patterns
Path patterns dictate where and how a file will be saved. Various variables and options are available, and you may use subdirectories divided by `/`.

#### Variables
##### Post
* `$postId`: The ID of the reddit post
* `$postTitle`: The title of the reddit post
* `$postUser`: The user that submitted the post, almost always equivalent to the `--user` command line argument
* `$postDate`: The submission date of the reddit post, formatted by the `dateformat` configuration described below
* `$postIndex`: The index of the post according to the sort method
* `$host`: Name of the source the content was hosted on

##### Album
* `$albumId`: The ID of the media host album
* `$albumTitle`: The title of the media host album
* `$albumDescription`: The description of the media host album
* `$albumDate`: The submission date of the media host album, formatted by the `dateformat` configuration described below

##### Item (individual image, video or text)
* `$itemId`: The ID of the individual image or video
* `$itemTitle`: The title of the individual image or video
* `$itemDescription`: The description of the individual image or video
* `$itemDate`: The submission date of the individual image or video, formatted by the `dateformat` configuration described below
* `$itemIndex`: The index of the individual image or video in an album, offset by the `indexOffset` configuration described below
* `$extracted`: When extracting single album items is enabled and the item has been extracted, this variable will display the value of `extractedLabel` as described below in case the item was the only item in an album
* `$ext`: The extension of the medium. Must typically be included, but may be omitted for self (text) posts on Unix systems

##### `dateFormat`
Affects the representation of `$postDate`, `$albumDate` and `$itemDate` and defaults to `YYYYMMDD`. See [this documentation](https://date-fns.org/v1.29.0/docs/format) for an overview of all available tokens.

##### `titleLength`
Titles can sometimes be longer than you prefer your filenames to be, or even overflow the operating system's limit (255 bytes for Linux). This property cuts off titles at a fixed number of characters.

##### `indexOffset`
Arrays start at 0, but as to not tire myself out debating the matter, you may offset it my any numerical value you like. Affects the `$itemIndex` variable for album items.

##### `slashSubstitute`
The patterns represent Unix file paths, and a `/` therefore indicates a new directory. You may freely use directories in your paths, but titles or descriptions may contain a `/` that is not supposed to create a new directory. All instances of `/` in a variable value will be replaced with the configured slash substitute.

##### `album.extractSingleItem` and `extractedLabel`
Some albums contain only one image or video. By setting `album.extractSingleItem` to `true` (default), the item will be saved in accordance to the individual item patterns rather than the album patterns. An extracted item will inherit the title and description of the album if it has none of its own. Extracted items can be marked with the `$extracted` boolean variable, of which the display value is set with `extractedLabel`.