Skip to content

M
mpd
Commit 2de98b65 authored by Max Kellermann's avatar Max Kellermann
Browse files
Options

doc/protocol.xml: move filter syntax to separate section

parent 361ad92d
Show whitespace changes
Inline Side-by-side
Showing with 104 additions and 88 deletions
doc/protocol.xml
View file @ 2de98b65
...@@ -195,6 +195,78 @@ ...@@ -195,6 +195,78 @@
</para> </para>
</section> </section>
<section id="filter_syntax">
<title>Filters</title>
<para>
All commands which search for songs (e.g. <link
linkend="command_find"><command>find</command></link> and
<link
linkend="command_searchadd"><command>searchadd</command></link>)
share a common filter syntax:
</para>
<cmdsynopsis>
<command>find</command>
<arg choice="req" rep="repeat">
<arg choice="req"><replaceable>TYPE</replaceable></arg>
<arg choice="req"><replaceable>VALUE</replaceable></arg>
</arg>
</cmdsynopsis>
<para>
<varname>TYPE</varname> can
be any tag supported by <application>MPD</application>, or one of the special
parameters:
</para>
<itemizedlist>
<listitem>
<para>
<parameter>any</parameter> checks all tag values
</para>
</listitem>
<listitem>
<para>
<parameter>file</parameter> checks the full path
(relative to the music directory)
</para>
</listitem>
<listitem>
<para>
<parameter>base</parameter> restricts the search to
songs in the given directory (also relative to the
music directory)
</para>
</listitem>
<listitem>
<para>
<parameter>modified-since</parameter> compares the
file's time stamp with the given value (ISO 8601 or
UNIX time stamp)
</para>
</listitem>
<listitem>
<para>
<parameter>albumartist</parameter> looks for
<varname>VALUE</varname> in AlbumArtist and falls back to
Artist tags if AlbumArtist does not exist.
</para>
</listitem>
</itemizedlist>
<para>
<varname>VALUE</varname> is what to find. The
<command>find</command> commands specify an exact value and
are case-sensitive; the <command>search</command> commands
specify a sub string and ignore case.
</para>
</section>
<section id="tags"> <section id="tags">
<title>Tags</title> <title>Tags</title>
...@@ -1685,17 +1757,16 @@ OK ...@@ -1685,17 +1757,16 @@ OK
<term> <term>
<cmdsynopsis> <cmdsynopsis>
<command>count</command> <command>count</command>
<arg choice="req"><replaceable>TAG</replaceable></arg> <arg choice="req" rep="repeat"><replaceable>FILTER</replaceable></arg>
<arg choice="req"><replaceable>NEEDLE</replaceable></arg>
<arg choice="opt"><replaceable>...</replaceable></arg>
<arg choice="opt">group</arg> <arg choice="opt">group</arg>
<arg choice="opt"><replaceable>GROUPTYPE</replaceable></arg> <arg choice="opt"><replaceable>GROUPTYPE</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</term> </term>
<listitem> <listitem>
<para> <para>
Counts the number of songs and their total playtime in Count the number of songs and their total playtime in
the db matching <varname>TAG</varname> exactly. The the database matching <varname>FILTER</varname> (see
<link linkend="filter_syntax">Filters</link>). The
following prints the number of songs whose title matches following prints the number of songs whose title matches
"Echoes": "Echoes":
</para> </para>
...@@ -1716,65 +1787,16 @@ OK ...@@ -1716,65 +1787,16 @@ OK
<term> <term>
<cmdsynopsis> <cmdsynopsis>
<command>find</command> <command>find</command>
<arg choice="req"><replaceable>TYPE</replaceable></arg> <arg choice="req" rep="repeat"><replaceable>FILTER</replaceable></arg>
<arg choice="req"><replaceable>WHAT</replaceable></arg>
<arg choice="opt"><replaceable>...</replaceable></arg>
<arg choice="opt">sort <replaceable>TYPE</replaceable></arg> <arg choice="opt">sort <replaceable>TYPE</replaceable></arg>
<arg choice="opt">window <replaceable>START</replaceable>:<replaceable>END</replaceable></arg> <arg choice="opt">window <replaceable>START</replaceable>:<replaceable>END</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</term> </term>
<listitem> <listitem>
<para> <para>
Finds songs in the db that are exactly Search the database for songs matching
<varname>WHAT</varname>. <varname>FILTER</varname> (see <link
</para> linkend="filter_syntax">Filters</link>).
<para>
<varname>TYPE</varname> can
be any tag supported by <application>MPD</application>, or one of the special
parameters:
</para>
<itemizedlist>
<listitem>
<para>
<parameter>any</parameter> checks all tag values
</para>
</listitem>
<listitem>
<para>
<parameter>file</parameter> checks the full path
(relative to the music directory)
</para>
</listitem>
<listitem>
<para>
<parameter>base</parameter> restricts the search to
songs in the given directory (also relative to the
music directory)
</para>
</listitem>
<listitem>
<para>
<parameter>modified-since</parameter> compares the
file's time stamp with the given value (ISO 8601 or
UNIX time stamp)
</para>
</listitem>
<listitem>
<para>
<parameter>albumartist</parameter> looks for
<varname>WHAT</varname> in AlbumArtist and falls back to
Artist tags if AlbumArtist does not exist.
</para>
</listitem>
</itemizedlist>
<para>
<varname>WHAT</varname> is what to find.
</para> </para>
<para> <para>
...@@ -1804,16 +1826,16 @@ OK ...@@ -1804,16 +1826,16 @@ OK
<term> <term>
<cmdsynopsis> <cmdsynopsis>
<command>findadd</command> <command>findadd</command>
<arg choice="req"><replaceable>TYPE</replaceable></arg> <arg choice="req" rep="repeat"><replaceable>FILTER</replaceable></arg>
<arg choice="req"><replaceable>WHAT</replaceable></arg>
<arg choice="opt"><replaceable>...</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</term> </term>
<listitem> <listitem>
<para> <para>
Finds songs in the db that are exactly Search the database for songs matching
<varname>WHAT</varname> and adds them to current <varname>FILTER</varname> (see <link
playlist. Parameters have the same meaning as for <link linkend="filter_syntax">Filters</link>) and add them to
the queue. Parameters have the same meaning as for
<link
linkend="command_find"><command>find</command></link>. linkend="command_find"><command>find</command></link>.
</para> </para>
</listitem> </listitem>
...@@ -1824,9 +1846,7 @@ OK ...@@ -1824,9 +1846,7 @@ OK
<cmdsynopsis> <cmdsynopsis>
<command>list</command> <command>list</command>
<arg choice="req"><replaceable>TYPE</replaceable></arg> <arg choice="req"><replaceable>TYPE</replaceable></arg>
<arg choice="opt"><replaceable>FILTERTYPE</replaceable></arg> <arg choice="opt" rep="repeat"><replaceable>FILTER</replaceable></arg>
<arg choice="opt"><replaceable>FILTERWHAT</replaceable></arg>
<arg choice="opt"><replaceable>...</replaceable></arg>
<arg choice="opt">group</arg> <arg choice="opt">group</arg>
<arg choice="opt"><replaceable>GROUPTYPE</replaceable></arg> <arg choice="opt"><replaceable>GROUPTYPE</replaceable></arg>
<arg choice="opt"><replaceable>...</replaceable></arg> <arg choice="opt"><replaceable>...</replaceable></arg>
...@@ -1840,10 +1860,8 @@ OK ...@@ -1840,10 +1860,8 @@ OK
<parameter>file</parameter>. <parameter>file</parameter>.
</para> </para>
<para> <para>
Additional arguments may specify a filter like the one Additional arguments may specify a <link
in the <link linkend="filter_syntax">filter</link>.
linkend="command_find"><command>find</command>
command</link>.
</para> </para>
<para> <para>
The <parameter>group</parameter> keyword may be used The <parameter>group</parameter> keyword may be used
...@@ -1994,18 +2012,17 @@ OK ...@@ -1994,18 +2012,17 @@ OK
<term> <term>
<cmdsynopsis> <cmdsynopsis>
<command>search</command> <command>search</command>
<arg choice="req"><replaceable>TYPE</replaceable></arg> <arg choice="req" rep="repeat"><replaceable>FILTER</replaceable></arg>
<arg choice="req"><replaceable>WHAT</replaceable></arg>
<arg choice="opt"><replaceable>...</replaceable></arg>
<arg choice="opt">sort <replaceable>TYPE</replaceable></arg> <arg choice="opt">sort <replaceable>TYPE</replaceable></arg>
<arg choice="opt">window <replaceable>START</replaceable>:<replaceable>END</replaceable></arg> <arg choice="opt">window <replaceable>START</replaceable>:<replaceable>END</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</term> </term>
<listitem> <listitem>
<para> <para>
Searches for any song that contains Search the database for songs matching
<varname>WHAT</varname>. Parameters have the same <varname>FILTER</varname> (see <link
meaning as for <link linkend="filter_syntax">Filters</link>). Parameters
have the same meaning as for <link
linkend="command_find"><command>find</command></link>, linkend="command_find"><command>find</command></link>,
except that search is not case sensitive. except that search is not case sensitive.
</para> </para>
...@@ -2015,15 +2032,15 @@ OK ...@@ -2015,15 +2032,15 @@ OK
<term> <term>
<cmdsynopsis> <cmdsynopsis>
<command>searchadd</command> <command>searchadd</command>
<arg choice="req"><replaceable>TYPE</replaceable></arg> <arg choice="req" rep="repeat"><replaceable>FILTER</replaceable></arg>
<arg choice="req"><replaceable>WHAT</replaceable></arg>
<arg choice="opt"><replaceable>...</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</term> </term>
<listitem> <listitem>
<para> <para>
Searches for any song that contains <varname>WHAT</varname> Search the database for songs matching
in tag <varname>TYPE</varname> and adds them to current playlist. <varname>FILTER</varname> (see <link
linkend="filter_syntax">Filters</link>) and add them to
the queue.
</para> </para>
<para> <para>
Parameters have the same meaning as for <link Parameters have the same meaning as for <link
...@@ -2036,16 +2053,15 @@ OK ...@@ -2036,16 +2053,15 @@ OK
<cmdsynopsis> <cmdsynopsis>
<command>searchaddpl</command> <command>searchaddpl</command>
<arg choice="req"><replaceable>NAME</replaceable></arg> <arg choice="req"><replaceable>NAME</replaceable></arg>
<arg choice="req"><replaceable>TYPE</replaceable></arg> <arg choice="req" rep="repeat"><replaceable>FILTER</replaceable></arg>
<arg choice="req"><replaceable>WHAT</replaceable></arg>
<arg choice="opt"><replaceable>...</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</term> </term>
<listitem> <listitem>
<para> <para>
Searches for any song that contains <varname>WHAT</varname> Search the database for songs matching
in tag <varname>TYPE</varname> and adds them to the playlist <varname>FILTER</varname> (see <link
named <varname>NAME</varname>. linkend="filter_syntax">Filters</link>) and add them to
the playlist named <varname>NAME</varname>.
</para> </para>
<para> <para>
If a playlist by that name doesn't exist it is created. If a playlist by that name doesn't exist it is created.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment