diff --git a/CHANGELOG.md b/CHANGELOG.md index b2d86ae0..988f78b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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)) diff --git a/docs/formatting.md b/docs/formatting.md index 66948c12..dbcdb6ee 100644 --- a/docs/formatting.md +++ b/docs/formatting.md @@ -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) | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConversionDescriptionExampleResult
lConvert a string to lowercase{foo!l}foo bar
uConvert a string to uppercase{foo!u}FOO BAR
cCapitalize a string, i.e. convert the first character to uppercase and all others to lowercase{foo!c}Foo bar
CCapitalize each word in a string{foo!C}Foo Bar
tTrim a string, i.e. remove leading and trailing whitespace characters{bar!t}FooBar
TConvert a datetime object to a unix timestamp{date!T}1262304000
dConvert a unix timestamp to a datetime object{created!d}2010-01-01 00:00:00
sConvert value to str{tags!s}['sun', 'tree', 'water']
SConvert value to str while providing a human-readable representation for lists{tags!S}sun, tree, water
rConvert value to str using repr()
aConvert value to str using ascii()
## 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 | -| --- | --- | --- | --- | -| `?//` | Adds `` and `` to the actual value if it evaluates to `True`. Otherwise the whole replacement field becomes an empty string. | `{foo:?[/]/}`
`{empty:?[/]/}` | `[Foo Bar]`
` ` -| `L//` | Replaces the entire output with `` if its length exceeds `` | `{foo:L15/long/}`
`{foo:L3/long/}` | `Foo Bar`
`long`| -| `J/` | Concatenates elements of a list with `` using [`str.join()`](https://docs.python.org/3/library/stdtypes.html#str.join) | `{tags:J - /}` | `sun - tree - water` | -| `R//` | Replaces all occurrences of `` with `` using [`str.replace()`](https://docs.python.org/3/library/stdtypes.html#str.replace) | `{foo:Ro/()/}` | `F()() Bar` | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Format SpecifierDescriptionExampleResult
?<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:?[/]/}[Foo Bar]
{empty:?[/]/}
L<maxlen>/<repl>/Replaces the entire output with <repl> if its length exceeds <maxlen>{foo:L15/long/}Foo Bar
{foo:L3/long/}long
J<separator>/Concatenates elements of a list with <separator> using str.join(){tags:J - /}sun - tree - water
R<old>/<new>/Replaces all occurrences of <old> with <new> using str.replace(){foo:Ro/()/}F()() Bar
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 diff --git a/gallery_dl/version.py b/gallery_dl/version.py index 376735b8..0838e16b 100644 --- a/gallery_dl/version.py +++ b/gallery_dl/version.py @@ -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"