Mirrors/gallery-dl
1
0
Fork 0
mirror of https://github.com/mikf/gallery-dl.git synced 2024-11-22 10:42:34 +01:00
Code Issues Releases Wiki Activity

use HTML tables in docs/formatting.md

Browse Source
This commit is contained in:
Mike Fährmann 2021-07-05 23:29:03 +02:00
parent 5f1b13d1a5
commit 317ecc8180
No known key found for this signature in database
GPG Key ID: 5680CA389D365A88
3 changed files with 138 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -1,5 +1,7 @@
# Changelog
## Unreleased
## 1.18.1 - 2021-07-04
### Additions
- [mangafox] add `manga` extractor ([#1633](https://github.com/mikf/gallery-dl/issues/1633))

166
docs/formatting.md
View File

@ -11,52 +11,156 @@ 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.
| | Example | Result |
| --- | --- | --- |
| Name | `{title}` | `Hello World` |
| Element Index | `{title[6]}` | `W` |
| Slicing | `{title[3:8]}` | `lo Wo` |
| Alternatives | `{empty\|title}` | `Hello World` |
| Element Access | `{user[name]}` | `John Doe` |
| | Example | Result |
| ---------------- | ----------------- | ---------------------- |
| Name | `{title}` | `Hello World` |
| Element Index | `{title[6]}` | `W` |
| Slicing | `{title[3:8]}` | `lo Wo` |
| Alternatives | `{empty\|title}` | `Hello World` |
| Element Access | `{user[name]}` | `John Doe` |
| Attribute Access | `{extractor.url}` | `https://example.org/` |
All of these methods can be combined as needed. For example `{title[24]|empty|extractor.url[15:-1]}` would result in `.org`.
All of these methods can be combined as needed.
For example `{title[24]|empty|extractor.url[15:-1]}` would result in `.org`.
## Conversions
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:
| Conversion | Description | Example | Result |
|:---:| --- | --- | --- |
| `l` | Convert a string to lowercase | `{foo!l}` | `foo bar`
| `u` | Convert a string to uppercase | `{foo!u}` | `FOO BAR`
| `c` | Capitalize a string, i.e. convert the first character to uppercase and all others to lowercase | `{foo!c}` | `Foo bar`
| `C` | Capitalize each word in a string | `{foo!C}` | `Foo Bar`
| `t` | Trim a string, i.e. remove leading and trailing whitespace characters | `{bar!t}` | `FooBar`
| `T` | Convert a `datetime` object to a unix timestamp | `{date!T}` | `1262304000`
| `d` | Convert a unix timestamp to a `datetime` object | `{created!d}` | `2010-01-01 00:00:00`
| `s` | Convert value to [`str`](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str) | `{tags!s}` | `['sun', 'tree', 'water']`
| `S` | Convert value to `str` and provide a human-readable representation for lists | `{tags!S}` | `sun, tree, water`
| `r` | Convert value to `str` using [`repr()`](https://docs.python.org/3/library/functions.html#repr) |
| `a` | Convert value to `str` using [`ascii()`](https://docs.python.org/3/library/functions.html#ascii) |
<table>
<thead>
<tr>
<th>Conversion</th>
<th>Description</th>
<th>Example</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr>
<td align="center"><code>l</code></td>
<td>Convert a string to lowercase</td>
<td><code>{foo!l}</code></td>
<td><code>foo bar</code></td>
</tr>
<tr>
<td align="center"><code>u</code></td>
<td>Convert a string to uppercase</td>
<td><code>{foo!u}</code></td>
<td><code>FOO BAR</code></td>
</tr>
<tr>
<td align="center"><code>c</code></td>
<td>Capitalize a string, i.e. convert the first character to uppercase and all others to lowercase</td>
<td><code>{foo!c}</code></td>
<td><code>Foo bar</code></td>
</tr>
<tr>
<td align="center"><code>C</code></td>
<td>Capitalize each word in a string</td>
<td><code>{foo!C}</code></td>
<td><code>Foo Bar</code></td>
</tr>
<tr>
<td align="center"><code>t</code></td>
<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>
<td align="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>
<td align="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>
<td align="center"><code>s</code></td>
<td>Convert value to <a href="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>
<td align="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>
<td align="center"><code>r</code></td>
<td>Convert value to <code>str</code> using <a href="https://docs.python.org/3/library/functions.html#repr" rel="nofollow"><code>repr()</code></a></td>
<td></td>
<td></td>
</tr>
<tr>
<td align="center"><code>a</code></td>
<td>Convert value to <code>str</code> using <a href="https://docs.python.org/3/library/functions.html#ascii" rel="nofollow"><code>ascii()</code></a></td>
<td></td>
<td></td>
</tr>
</tbody>
</table>
## Format Specifiers
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:
| Format Specifier | Description | Example | Result |
| --- | --- | --- | --- |
| `?<before>/<after>/` | Adds `<before>` and `<after>` to the actual value if it evaluates to `True`. Otherwise the whole replacement field becomes an empty string. | `{foo:?[/]/}` <br /> `{empty:?[/]/}` | `[Foo Bar]` <br /> ` `
| `L<maxlen>/<repl>/` | Replaces the entire output with `<repl>` if its length exceeds `<maxlen>` | `{foo:L15/long/}` <br /> `{foo:L3/long/}` | `Foo Bar` <br /> `long`|
| `J<separator>/` | Concatenates elements of a list with `<separator>` using [`str.join()`](https://docs.python.org/3/library/stdtypes.html#str.join) | `{tags:J - /}` | `sun - tree - water` |
| `R<old>/<new>/` | Replaces all occurrences of `<old>` with `<new>` using [`str.replace()`](https://docs.python.org/3/library/stdtypes.html#str.replace) | `{foo:Ro/()/}` | `F()() Bar` |
<table>
<thead>
<tr>
<th>Format Specifier</th>
<th>Description</th>
<th>Example</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan="2"><code>?&lt;before&gt;/&lt;after&gt;/</code></td>
<td rowspan="2">Adds <code>&lt;before&gt;</code> and <code>&lt;after&gt;</code> to the actual value if it evaluates to <code>True</code>. Otherwise the whole replacement field becomes an empty string.</td>
<td><code>{foo:?[/]/}</code></td>
<td><code>[Foo&nbsp;Bar]</code></td>
</tr>
<tr>
<td><code>{empty:?[/]/}</code></td>
<td><code></code></td>
</tr>
<tr>
<td rowspan="2"><code>L&lt;maxlen&gt;/&lt;repl&gt;/</code></td>
<td rowspan="2">Replaces the entire output with <code>&lt;repl&gt;</code> if its length exceeds <code>&lt;maxlen&gt;</code></td>
<td><code>{foo:L15/long/}</code></td>
<td><code>Foo&nbsp;Bar</code></td>
</tr>
<tr>
<td><code>{foo:L3/long/}</code></td>
<td><code>long</code></td>
</tr>
<tr>
<td><code>J&lt;separator&gt;/</code></td>
<td>Concatenates elements of a list with <code>&lt;separator&gt;</code> using <a href="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&lt;old&gt;/&lt;new&gt;/</code></td>
<td>Replaces all occurrences of <code>&lt;old&gt;</code> with <code>&lt;new&gt;</code> using <a href="https://docs.python.org/3/library/stdtypes.html#str.replace" rel="nofollow"><code>str.replace()</code></a></td>
<td><code>{foo:Ro/()/}</code></td>
<td><code>F()()&nbsp;Bar</code></td>
</tr>
</tbody>
</table>
All special format specifiers (`?`, `L`, `J`, `R`) can be chained and combined with one another, but must always come before any standard format specifiers:
For example `{foo:?//RF/B/Ro/e/> 10}` -> `   Bee Bar`
- `?//` - Test if `foo` has a value
- `RF/B/` - Replace `F` with `B`
- `Ro/e/` - Replace `o` with `e`
- `> 10` - Left-fill the string with spaces until it is 10 characters long
- `?//` - Tests if `foo` has a value
- `RF/B/` - Replaces `F` with `B`
- `Ro/e/` - Replaces `o` with `e`
- `> 10` - Left-fills the string with spaces until it is 10 characters long

2
gallery_dl/version.py
View File

@ -6,4 +6,4 @@
# it under the terms of the GNU General Public License version 2 as
# published by the Free Software Foundation.
__version__ = "1.18.1"
__version__ = "1.18.2-dev"