rewrite plugin

--HG--
rename : docs/plugins/inline.rst => docs/plugins/rewrite.rst

beetsplug/rewrite.py

@@ -0,0 +1,62 @@
+# This file is part of beets.
+# Copyright 2012, Adrian Sampson.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+
+"""Uses user-specified rewriting rules to canonicalize names for path
+formats.
+"""
+import re
+import logging
+
+from beets.plugins import BeetsPlugin
+from beets import ui
+from beets import library
+
+log = logging.getLogger('beets')
+
+def rewriter(fieldname, pattern, replacement):
+    def fieldfunc(item):
+        value = getattr(item, fieldname)
+        if pattern.match(value):
+            # Rewrite activated.
+            return replacement
+        else:
+            # Not activated; return original value.
+            return value
+    return fieldfunc
+
+class RewritePlugin(BeetsPlugin):
+    template_fields = {}
+
+    def configure(self, config):
+        cls = type(self)
+
+        for key, value in config.items('rewrite', True):
+            try:
+                fieldname, pattern = key.split(None, 1)
+            except ValueError:
+                raise ui.UserError("invalid rewrite specification")
+            if fieldname not in library.ITEM_KEYS:
+                raise ui.UserError("invalid field name (%s) in rewriter" %
+                                   fieldname)
+            log.debug(u'adding template field %s' % key)
+            pattern = re.compile(pattern, re.I)
+
+            # Replace the template field with the new function.
+            cls.template_fields[fieldname] = rewriter(fieldname, pattern,
+                                                      value)
+            if fieldname == 'artist':
+                # Special case for the artist field: apply the same rewrite for
+                # "albumartist" as well.
+                cls.template_fields['albumartist'] = rewriter('albumartist',
+                                                              pattern, value)

docs/changelog.rst

@@ -25,8 +25,9 @@ This release focuses on making beets' path formatting vastly more powerful.
   directory and music file names.  See :doc:`/reference/config`.
 * Beets now ensures that files have **unique filenames** by appending a number
   to any filename that would otherwise conflict with an existing file.
-* The new :doc:`/plugins/scrub/` can remove extraneous metadata either manually
+* The new :doc:`/plugins/scrub` can remove extraneous metadata either manually
   or automatically.
+* The new :doc:`/plugins/rewrite` can canonicalize names for path formats.
 * The autotagging heuristics have been tweaked in situations where the
   MusicBrainz database did not contain track lengths. Previously, beets
   penalized matches where this was the case, leading to situations where

docs/plugins/index.rst

@@ -44,6 +44,7 @@ disabled by default, but you can turn them on as described above:
    replaygain
    inline
    scrub
+   rewrite
 
 .. _other-plugins:
 

docs/plugins/rewrite.rst

@@ -0,0 +1,38 @@
+Rewrite Plugin
+==============
+
+The ``rewrite`` plugin lets you easily substitute values in your path formats.
+Specifically, it is intended to let you *canonicalize* names such as artists:
+for example, perhaps you want albums from The Jimi Hendrix Experience to be
+sorted into the same folder as solo Hendrix albums.
+
+To use field rewriting, first enable the plugin by putting ``rewrite``
+on your ``plugins`` line::
+
+    [beets]
+    plugins: rewrite
+
+Then, make a ``[rewrite]`` section in your config file to contain your rewrite
+rules. Each rule consists of a field name, a regular expression pattern, and a
+replacement value. Rules are written ``fieldname regex: replacement``. For
+example, this line implements the Jimi Hendrix example above::
+
+    [rewrite]
+    artist The Jimi Hendrix Experience: Jimi Hendrix
+
+This will make ``$artist`` in your path formats expand to "Jimi Henrix" where it
+would otherwise be "The Jimi Hendrix Experience".
+
+The pattern is a case-insensitive regular expression. This means you can use
+ordinary regular expression syntax to match multiple artists. For example, you
+might use::
+
+    [rewrite]
+    artist .*jimi hendrix.*: Jimi Hendrix
+
+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``.)
+
+Note that this plugin only applies to path templating; it does not modify files'
+metadata tags or the values tracked by beets' library database.