Add `bareasc` command to display entries with the unidecode transformation

applied.

Signed-off-by: Graham R. Cobb <g+beets@cobb.uk.net>

beetsplug/bareasc.py

@@ -21,6 +21,8 @@
 
 from __future__ import division, absolute_import, print_function
 
+from beets import ui
+from beets.ui import print_, decargs
 from beets.plugins import BeetsPlugin
 from beets.dbcore.query import StringFieldQuery
 from unidecode import unidecode
@@ -53,6 +55,29 @@ class BareascPlugin(BeetsPlugin):
         })
 
     def queries(self):
-        """Reguster bare-ASCII matching."""
+        """Register bare-ASCII matching."""
         prefix = self.config['prefix'].as_str()
         return {prefix: BareascQuery}
+
+    def commands(self):
+        """Add bareasc command as unidecode version of 'list'."""
+        cmd = ui.Subcommand('bareasc',
+                            help='unidecode version of beet list command')
+        cmd.parser.usage += u"\n" \
+            u'Example: %prog -f \'$album: $title\' artist:beatles'
+        cmd.parser.add_all_common_options()
+        cmd.func = self.unidecode_list
+        return [cmd]
+
+    def unidecode_list(self, lib, opts, args):
+        """Emulate normal 'list' command but with unidecode output."""
+        query = decargs(args)
+        album = opts.album
+        fmt = u''
+        # Copied from commands.py - list_items
+        if album:
+            for album in lib.albums(query):
+                print_(unidecode(format(album, fmt)))
+        else:
+            for item in lib.items(query):
+                print_(unidecode(format(item, fmt)))

docs/plugins/bareasc.rst

@@ -14,6 +14,23 @@ You'll then be able to use the ``#`` prefix to use bare-ASCII matching::
     $ beet ls '#dvorak'
     István Kertész - REQUIEM - Dvořàk: Requiem, op.89 - Confutatis maledictis
 
+Command
+-------
+
+In addition to the query prefix, the plugin provides a utility ``bareasc`` command.
+This command is **exactly** the same as the ``beet list`` command except that
+the output is passed through the bare-ASCII transformation before being printed.
+This allows you to easily check what the library data looks like in bare ASCII,
+which can be useful if you are trying to work out why a query is not matching.
+
+Using the same example track as above::
+
+    $ beet bareasc 'Dvořàk'
+    Istvan Kertesz - REQUIEM - Dvorak: Requiem, op.89 - Confutatis maledictis
+
+Note: the ``bareasc`` command does NOT automatically use bare-ASCII queries.
+If you want a bare-ASCII query you still need to specify the ``#`` prefix.
+
 Notes
 -----
 
@@ -23,9 +40,16 @@ accents.
 The default ``bareasc`` prefix (``#``) is used as a comment character in some shells
 so may need to be protected (for example in quotes) when typed into the command line.
 
-The bare ASCII transformation is quite simple. It may not work perfectly for all
-languages and does not handle transformations which change the number of letters.
-For example, German u-umlaut ``ü`` is transformed into ASCII ``u``, not into ``ue``.
+The bare ASCII transformation is quite simple. It may not give the expected output
+for all languages. For example, German u-umlaut ``ü`` is transformed into ASCII ``u``,
+not into ``ue``.
+
+The bare ASCII transformation also changes Unicode punctuation like double quotes,
+apostrophes and even some hyphens. It is often best to leave out punctuation
+in the queries. Note that the punctuation changes are often not even visible
+with normal terminal fonts. You can always use the ``bareasc`` command to print the
+transformed entries and use a command like ``diff`` to compare with the output
+from the ``list`` command.
 
 Configuration
 -------------

test/test_bareasc.py

@@ -8,7 +8,7 @@ from __future__ import division, absolute_import, print_function
 
 import unittest
 
-from test.helper import TestHelper
+from test.helper import capture_stdout, TestHelper
 
 from beets import logging
 
@@ -27,9 +27,9 @@ class BareascPluginTest(unittest.TestCase, TestHelper):
         # and assigns the next free id number.
         self.add_item(title=u'with accents',
                       album_id=2,
-                      artist=u'Antonín dvořák')
+                      artist=u'Antonín Dvořák')
         self.add_item(title=u'without accents',
-                      artist=u'Antonín dvorak')
+                      artist=u'Antonín Dvorak')
         self.add_item(title=u'with umlaut',
                       album_id=2,
                       artist=u'Brüggen')
@@ -129,6 +129,13 @@ class BareascPluginTest(unittest.TestCase, TestHelper):
             {u'without umlaut or e', u'with umlaut'}
         )
 
+    def test_bareasc_list_output(self):
+        """Bare-ASCII version of list command - check output."""
+        with capture_stdout() as output:
+            self.run_command('bareasc', 'with accents')
+
+        self.assertIn('Antonin Dvorak', output.getvalue())
+
 
 def suite():
     """loader."""