From fd2cacbc25ecd1dec5a60c1e3995ea7b031c3614 Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Fri, 20 Nov 2015 10:07:29 -0800 Subject: [PATCH] Minor docs refinements for #1728 - Use a marginally more realistic example in the changelog. - The -- convention is actually not the purview of shells; it's just a de facto standard for command-line parsers. Fortunately, argparse supports it out of the box. --- docs/changelog.rst | 8 ++++---- docs/reference/query.rst | 16 +++++++--------- 2 files changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 81dcdd2b7..474e4c4a7 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -20,10 +20,10 @@ New: :doc:`/plugins/discogs` also adopts the same setting. * :doc:`/plugins/embyupdate`: A plugin to trigger a library refresh on a `Emby Server`_ if database changed. -* Queries can now use "not" logic: if you prepend a query term with "-" or - "^", items or albums matching that term will be excluded from the results. - For example, ``beet ls foo ^artist:bar`` will get all the items matching - `foo` but whose artist do not match `bar`. See :ref:`not_query`. :bug:`819` +* Queries can now use "not" logic. Type a ``^`` before part of a query to + *exclude* matching music from the results. For example, ``beet list -a + beatles ^album:1`` will find all your albums by the Beatles except for their + singles compilation, "1." See :ref:`not_query`. :bug:`819` :bug:`1728` For developers: diff --git a/docs/reference/query.rst b/docs/reference/query.rst index 6d83537d1..2cb3aec87 100644 --- a/docs/reference/query.rst +++ b/docs/reference/query.rst @@ -186,7 +186,7 @@ Find all items with a file modification time between 2008-12-01 and Query Term Negation ------------------- -Query terms can also be negated, acting like a Boolean "not", by prepending +Query terms can also be negated, acting like a Boolean "not," by prefixing them with ``-`` or ``^``. This has the effect of returning all the items that do **not** match the query term. For example, this command:: @@ -195,19 +195,17 @@ do **not** match the query term. For example, this command:: matches all the songs in the library that do not have "love" in any of their fields. -Negation can be combined with the rest of the query mechanisms, allowing to +Negation can be combined with the rest of the query mechanisms, so you can negate specific fields, regular expressions, etc. For example, this command:: - $ beet list -a artist:dylan ^year:1980..1990 "^album::the(y)?" + $ beet list -a artist:dylan ^year:1980..1989 "^album::the(y)?" matches all the albums with an artist containing "dylan", but excluding those -released on the eighties and those that have "the" or "they" on the title. +released in the eighties and those that have "the" or "they" on the title. -Note that the ``-`` character is treated by most shells as a reserved character -for passing arguments, and as such needs to be escaped if using it for query -negation. In most UNIX derivatives shells, using a double dash ``--`` -(indicating that everything after that point should not be treated as -arguments) before the query terms should prevent conflicts, such as:: +The syntax supports both ``^`` and ``-`` as synonyms because the latter +indicates flags on the command line. To use a minus sign in a command-line +query, use a double dash ``--`` to separate the options from the query:: $ beet list -a -- artist:dylan -year:1980..1990 "-album::the(y)?"