Add support for listing only local queues

Partially implements https://github.com/rabbitmq/rabbitmq-server/issues/851

- Made old `--online`/`--offline` options mutually exclusive between
  themselves and the new `--local` option
- Added documentation both for the old and the new option
- Fixed some ugly indentation in generated usage (only `set_policy`
  wrapped line remains unfixed)
- Added integration test suite for `rabbitmqctl list_queues`

2 files changed, 47 insertions, 5 deletions

diff --git a/docs/rabbitmqctl.1.xml b/docs/rabbitmqctl.1.xml
index ec864af6cf..7dd926eba8 100644
--- a/docs/rabbitmqctl.1.xml
+++ b/docs/rabbitmqctl.1.xml
@@ -749,9 +749,7 @@
 
         <varlistentry>
           <term>
-          <cmdsynopsis>
-            <command>authenticate_user</command> <arg choice="req"><replaceable>username</replaceable></arg> <arg choice="req"><replaceable>password</replaceable></arg>
-          </cmdsynopsis>
+          <cmdsynopsis><command>authenticate_user</command> <arg choice="req"><replaceable>username</replaceable></arg> <arg choice="req"><replaceable>password</replaceable></arg></cmdsynopsis>
           </term>
           <listitem>
             <variablelist>
@@ -1237,7 +1235,9 @@
 
       <variablelist>
         <varlistentry role="usage-has-option-list">
-          <term><cmdsynopsis><command>list_queues</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="opt" role="usage-option-list"><replaceable>queueinfoitem</replaceable> ...</arg></cmdsynopsis></term>
+          <term>
+            <cmdsynopsis><command>list_queues</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <group choice="opt"><arg>--offline</arg><arg>--online</arg><arg>--local</arg></group> <arg choice="opt" role="usage-option-list"><replaceable>queueinfoitem</replaceable> ...</arg></cmdsynopsis>
+          </term>
           <listitem>
             <para>
               Returns queue details. Queue details of the <command>/</command> virtual host
@@ -1245,6 +1245,40 @@
               override this default.
             </para>
             <para>
+              Displayed queues can be filtered by their status or
+              location using one of the following mutually exclusive
+              options:
+              <variablelist>
+                <varlistentry>
+                  <term><cmdsynopsis><arg choice="opt">--offline</arg></cmdsynopsis></term>
+                  <listitem>
+                    <para>
+                      List only those durable queues that are not
+                      currently running - i.e. they are located on
+                      inaccessible nodes.
+                    </para>
+                  </listitem>
+                </varlistentry>
+                <varlistentry>
+                  <term><cmdsynopsis><arg choice="opt">--online</arg></cmdsynopsis></term>
+                  <listitem>
+                    <para>
+                      List queues that are currently live.
+                    </para>
+                  </listitem>
+                </varlistentry>
+                <varlistentry>
+                  <term><cmdsynopsis><arg choice="opt">--local</arg></cmdsynopsis></term>
+                  <listitem>
+                    <para>
+                      List only those queues whose master process is
+                      located on the current node.
+                    </para>
+                  </listitem>
+                </varlistentry>
+              </variablelist>
+            </para>
+            <para>
               The <command>queueinfoitem</command> parameter is used to indicate which queue
               information items to include in the results. The column order in the
               results will match the order of the parameters.
diff --git a/docs/usage.xsl b/docs/usage.xsl
index 586f830327..0d3cb6f235 100644
--- a/docs/usage.xsl
+++ b/docs/usage.xsl
@@ -8,7 +8,7 @@
               encoding="UTF-8"
               indent="no"/>
 <xsl:strip-space elements="*"/>
-<xsl:preserve-space elements="cmdsynopsis arg" />
+<xsl:preserve-space elements="cmdsynopsis arg group" />
 
 <xsl:template match="/">
 <!-- Pull out cmdsynopsis to show the command usage line. -->%% Generated, do not edit!
@@ -68,6 +68,14 @@ usage() -> %QUOTE%Usage:
 <!-- Don't show anything else in command usage -->
 <xsl:template match="text()" mode="command-usage"/>
 
+<xsl:template match="group[@choice='opt']">
+  <xsl:text>[</xsl:text>
+  <xsl:for-each select="arg">
+    <xsl:apply-templates/>
+    <xsl:if test="not(position() = last())"><xsl:text>|</xsl:text></xsl:if>
+  </xsl:for-each>
+  <xsl:text>]</xsl:text>
+</xsl:template>
 <xsl:template match="arg[@choice='opt']">[<xsl:apply-templates/>]</xsl:template>
 <xsl:template match="replaceable">&lt;<xsl:value-of select="."/>&gt;</xsl:template>