From 4b1c7dd8be8cf2454739af9b4999f9bc3b50df80 Mon Sep 17 00:00:00 2001 From: Maxr1998 Date: Wed, 13 Dec 2023 11:25:27 +0100 Subject: [PATCH] Specify new advancedrewrite configuration in docs --- docs/plugins/advancedrewrite.rst | 45 +++++++++++++++++++++++++------- 1 file changed, 36 insertions(+), 9 deletions(-) diff --git a/docs/plugins/advancedrewrite.rst b/docs/plugins/advancedrewrite.rst index 8ac0e277e..27d434cac 100644 --- a/docs/plugins/advancedrewrite.rst +++ b/docs/plugins/advancedrewrite.rst @@ -3,28 +3,53 @@ Advanced Rewrite Plugin The ``advancedrewrite`` plugin lets you easily substitute values in your templates and path formats, similarly to the :doc:`/plugins/rewrite`. -Please make sure to read the documentation of that plugin first. +It's recommended to read the documentation of that plugin first. -The *advanced* rewrite plugin doesn't match the rewritten field itself, +The *advanced* rewrite plugin does not only support the simple rule format +of the ``rewrite`` plugin, but also an advanced format: +there, the plugin doesn't consider the value of the rewritten field, but instead checks if the given item matches a :doc:`query `. Only then, the field is replaced with the given value. +It's also possible to replace multiple fields at once, +and even supports multi-valued fields. To use advanced field rewriting, first enable the ``advancedrewrite`` plugin (see :ref:`using-plugins`). Then, make a ``advancedrewrite:`` section in your config file to contain your rewrite rules. -In contrast to the normal ``rewrite`` plugin, you need to provide a list -of replacement rule objects, each consisting of a query, a field name, -and the replacement value. +In contrast to the normal ``rewrite`` plugin, you need to provide a list of +replacement rule objects, which can have a different syntax depending on +the rule complexity. +The simple syntax is the same as the one of the rewrite plugin and allows +to replace a single field:: + + advancedrewrite: + - artist ODD EYE CIRCLE: 이달의 소녀 오드아이써클 + +The advanced syntax consists of a query to match against, as well as a map +of replacements to apply. For example, to credit all songs of ODD EYE CIRCLE before 2023 to their original group name, you can use the following rule:: advancedrewrite: - match: "mb_artistid:dec0f331-cb08-4c8e-9c9f-aeb1f0f6d88c year:..2022" - field: artist - replacement: "이달의 소녀 오드아이써클" + replacements: + artist: 이달의 소녀 오드아이써클 + artist_sort: LOONA / ODD EYE CIRCLE + +Note how the sort name is also rewritten within the same rule. +You can specify as many fields as you'd like in the replacements map. + +If you need to work with multi-valued fields, you can use the following syntax:: + + advancedrewrite: + - match: "artist:배유빈 feat. 김미현" + replacements: + artists: + - 유빈 + - 미미 As a convenience, the plugin applies patterns for the ``artist`` field to the ``albumartist`` field as well. (Otherwise, you would probably want to duplicate @@ -35,5 +60,7 @@ formats; it initially does not modify files' metadata tags or the values tracked by beets' library database, but since it *rewrites all field lookups*, it modifies the file's metadata anyway. See comments in issue :bug:`2786`. -As an alternative to this plugin the simpler :doc:`/plugins/rewrite` or -similar :doc:`/plugins/substitute` can be used. +As an alternative to this plugin the simpler but less powerful +:doc:`/plugins/rewrite` can be used. +If you don't want to modify the item's metadata and only replace values +in file paths, you can check out the :doc:`/plugins/substitute`.