Format strings in gallery-dl follow the general rules of [`str.format()`](https://docs.python.org/3/library/string.html#format-string-syntax) ([PEP 3101](https://www.python.org/dev/peps/pep-3101/)) plus several extras.
The syntax for replacement fields is `{<field-name>!<conversion>:<format-specifiers>}`, where `!<conversion>` and `:<format-specifiers>` are both optional and can be used to specify how the value selected by `<field-name>` should be transformed.
## Field Names
Field names select the metadata value to use in a replacement field.
While simple names are usually enough, more complex forms like accessing values by attribute, element index, or slicing are also supported.
Conversion specifiers allow to *convert* the value to a different form or type. Such a specifier must only consist of 1 character. gallery-dl supports the default three (`s`, `r`, `a`) as well as several others:
<td>Trim a string, i.e. remove leading and trailing whitespace characters</td>
<td><code>{bar!t}</code></td>
<td><code>FooBar</code></td>
</tr>
<tr>
<tdalign="center"><code>T</code></td>
<td>Convert a <code>datetime</code> object to a unix timestamp</td>
<td><code>{date!T}</code></td>
<td><code>1262304000</code></td>
</tr>
<tr>
<tdalign="center"><code>d</code></td>
<td>Convert a unix timestamp to a <code>datetime</code> object</td>
<td><code>{created!d}</code></td>
<td><code>2010-01-01 00:00:00</code></td>
</tr>
<tr>
<tdalign="center"><code>s</code></td>
<td>Convert value to <ahref="https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str"rel="nofollow"><code>str</code></a></td>
<td><code>{tags!s}</code></td>
<td><code>['sun', 'tree', 'water']</code></td>
</tr>
<tr>
<tdalign="center"><code>S</code></td>
<td>Convert value to <code>str</code> while providing a human-readable representation for lists</td>
<td><code>{tags!S}</code></td>
<td><code>sun, tree, water</code></td>
</tr>
<tr>
<tdalign="center"><code>r</code></td>
<td>Convert value to <code>str</code> using <ahref="https://docs.python.org/3/library/functions.html#repr"rel="nofollow"><code>repr()</code></a></td>
<td></td>
<td></td>
</tr>
<tr>
<tdalign="center"><code>a</code></td>
<td>Convert value to <code>str</code> using <ahref="https://docs.python.org/3/library/functions.html#ascii"rel="nofollow"><code>ascii()</code></a></td>
Format specifiers can be used for advanced formatting by using the options provided by Python (see [Format Specification Mini-Language](https://docs.python.org/3/library/string.html#format-specification-mini-language)) like zero-filling a number (`{num:>03}`) or formatting a [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) object (`{date:%Y%m%d}`), or with gallery-dl's extra formatting specifiers:
<tdrowspan="2">Adds <code><start></code> and <code><end></code> to the actual value if it evaluates to <code>True</code>. Otherwise the whole replacement field becomes an empty string.</td>
<tdrowspan="2">Replaces the entire output with <code><repl></code> if its length exceeds <code><maxlen></code></td>
<td><code>{foo:L15/long/}</code></td>
<td><code>Foo Bar</code></td>
</tr>
<tr>
<td><code>{foo:L3/long/}</code></td>
<td><code>long</code></td>
</tr>
<tr>
<td><code>J<separator>/</code></td>
<td>Concatenates elements of a list with <code><separator></code> using <ahref="https://docs.python.org/3/library/stdtypes.html#str.join"rel="nofollow"><code>str.join()</code></a></td>
<td><code>{tags:J - /}</code></td>
<td><code>sun - tree - water</code></td>
</tr>
<tr>
<td><code>R<old>/<new>/</code></td>
<td>Replaces all occurrences of <code><old></code> with <code><new></code> using <ahref="https://docs.python.org/3/library/stdtypes.html#str.replace"rel="nofollow"><code>str.replace()</code></a></td>
<td>Parse a string value to a <code>datetime</code> object according to <ahref="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes"><code><format></code></a></td>
All special format specifiers (`?`, `L`, `J`, `R`, `D`) can be chained and combined with one another, but must always come before any standard format specifiers:
