phmongeau committed 1f15d9c

document how extend the query syntax in plugins using PluginQuery

update the fuzzy documentation

  • Participants
  • Parent commits 5466791

Comments (0)

Files changed (2)

File docs/plugins/fuzzy.rst

 Fuzzy Search Plugin
-The ``fuzzy`` plugin provides a command that search your library using
-fuzzy pattern matching. This can be useful if you want to find a track with complicated characters in the title.
+The ``fuzzy`` plugin provides a query prefix that search you library using fuzzy
+pattern matching. This can be useful if you want to find a track with
+complicated characters in the title.
 First, enable the plugin named ``fuzzy`` (see :doc:`/plugins/index`).
-You'll then be able to use the ``beet fuzzy`` command::
+You'll then be able to use the ``~`` prefix to use fuzzy matching::
-    $ beet fuzzy Vareoldur
+    $ beet ls '~Vareoldur'
     Sigur Rós - Valtari - Varðeldur
-The command has several options that resemble those for the ``beet list``
-command (see :doc:`/reference/cli`). To choose an album instead of a single
-track, use ``-a``; to print paths to items instead of metadata, use ``-p``; and
-to use a custom format for printing, use ``-f FORMAT``.
-The ``-t NUMBER`` option lets you specify how precise the fuzzy match has to be
-(default is 0.7). To make a fuzzier search, try ``beet fuzzy -t 0.5 Varoeldur``.
-A value of ``1`` will show only perfect matches and a value of ``0`` will match everything.
-The default threshold can also be set in the config file::
+The plugin provides to config option to let you choose the prefix and the
         threshold: 0.8
+        prefix: '@'
+A threshold value of ``1`` will show only perfect matches and a value of ``0``
+will match everything.
+The default prefix ``~`` needs to be escaped or quoted in most shells. If this
+bothers you, you can change the prefix in your config file.

File docs/plugins/writing.rst

             self.import_stages = [self.stage]
         def stage(self, config, task):
             print('Importing something!')
+Extend the Query Syntax
+Beets already support searching using regular expressions by prepending search
+terms with the colon prefix. It is possible to add new prefix by extending the
+``PluginQuery`` class.
+The plugin then need to declare its new queries by returning a ``dict`` of
+``{prefix: PluginQuery}`` insied the ``queries`` method.
+The following example plugins declares a query using the ``@`` prefix. So the
+plugin will be call if we issue a command like ``beet ls @something`` or
+``beet ls artist:@something``.::
+    from beets.plugins import BeetsPlugin
+    from beets.Library import PluginQuery
+    class ExampleQuery(PluginQuery):
+        def match(self, pattern, val):
+            return True # this will simply match everything
+    class ExamplePlugin(BeetsPlugin):
+        def queries():
+            # plugins need to declare theire queries by
+            # returning a dict of {prefix: PluginQuery}
+            # from the queries() function
+            return {
+                '@': ExampleQuery
+            }