Advanced Rewrite Plugin
***********************

The "advancedrewrite" plugin lets you easily substitute values in your
templates and path formats, similarly to the Rewrite Plugin. It's
recommended to read the documentation of that plugin first.

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 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 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, 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"
       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 every rule for "artist" and "albumartist".)

Make sure to properly quote your query strings if they contain spaces,
otherwise they might not do what you expect, or even cause beets to
crash.

Take the following example:

   advancedrewrite:
     # BAD, DON'T DO THIS!
     - match: album:THE ALBUM
       replacements:
         artist: New artist

On the first sight, this might look sane, and replace the artist of
the album *THE ALBUM* with *New artist*. However, due to the space and
missing quotes, this query will evaluate to "album:THE" and match
"ALBUM" on any field, including "artist". As "artist" is the field
being replaced, this query will result in infinite recursion and
ultimately crash beets.

Instead, you should use the following rule:

   advancedrewrite:
     # Note the quotes around the query string!
     - match: album:"THE ALBUM"
       replacements:
         artist: New artist

A word of warning: This plugin theoretically only applies to templates
and path 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 #2786.

As an alternative to this plugin the simpler but less powerful Rewrite
Plugin 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
Substitute Plugin.
