========================
The command queue runner
========================

This queue runner's purpose is to process and respond to email commands.
Commands are extensible using the Mailman plugin system, but Mailman comes
with a number of email commands out of the box.  These are processed when a
message is sent to the list's -request address.

    >>> mlist = create_list('test@example.com')


A command in the Subject
========================

For example, the 'echo' command simply echoes the original command back to the
sender.  The command can be in the Subject header.

    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ... To: test-request@example.com
    ... Subject: echo hello
    ... Message-ID: <aardvark>
    ...
    ... """)

    >>> from mailman.inject import inject_message
    >>> inject_message(mlist, msg, switchboard='command')
    >>> from mailman.queue.command import CommandRunner
    >>> from mailman.testing.helpers import make_testable_runner
    >>> command = make_testable_runner(CommandRunner)
    >>> command.run()

And now the response is in the virgin queue.

    >>> from mailman.queue import Switchboard
    >>> virgin_queue = config.switchboards['virgin']
    >>> len(virgin_queue.files)
    1
    >>> from mailman.testing.helpers import get_queue_messages
    >>> item = get_queue_messages('virgin')[0]
    >>> print item.msg.as_string()
    Subject: The results of your email commands
    From: test-bounces@example.com
    To: aperson@example.com
    ...
    <BLANKLINE>
    The results of your email command are provided below.
    <BLANKLINE>
    - Original message details:
        From: aperson@example.com
        Subject: echo hello
        Date: ...
        Message-ID: <aardvark>
    <BLANKLINE>
    - Results:
    echo hello
    <BLANKLINE>
    - Done.
    <BLANKLINE>
    >>> sorted(item.msgdata.items())
    [..., ('listname', u'test@example.com'), ...,
     ('recipients', [u'aperson@example.com']),
     ...]


A command in the body
=====================

The command can also be found in the body of the message, as long as the
message is plain text.

    >>> msg = message_from_string("""\
    ... From: bperson@example.com
    ... To: test-request@example.com
    ... Message-ID: <bobcat>
    ...
    ... echo foo bar
    ... """)

    >>> inject_message(mlist, msg, switchboard='command')
    >>> command.run()
    >>> len(virgin_queue.files)
    1
    >>> item = get_queue_messages('virgin')[0]
    >>> print item.msg.as_string()
    Subject: The results of your email commands
    From: test-bounces@example.com
    To: bperson@example.com
    ...
    Precedence: bulk
    <BLANKLINE>
    The results of your email command are provided below.
    <BLANKLINE>
    - Original message details:
        From: bperson@example.com
        Subject: n/a
        Date: ...
        Message-ID: <bobcat>
    <BLANKLINE>
    - Results:
    echo foo bar
    <BLANKLINE>
    - Done.
    <BLANKLINE>


Stopping command processing
===========================

The 'end' command stops email processing, so that nothing following is looked
at by the command queue.

    >>> msg = message_from_string("""\
    ... From: cperson@example.com
    ... To: test-request@example.com
    ... Message-ID: <caribou>
    ...
    ... echo foo bar
    ... end ignored
    ... echo baz qux
    ... """)

    >>> inject_message(mlist, msg, switchboard='command')
    >>> command.run()
    >>> len(virgin_queue.files)
    1
    >>> item = get_queue_messages('virgin')[0]
    >>> print item.msg.as_string()
    Subject: The results of your email commands
    ...
    <BLANKLINE>
    - Results:
    echo foo bar
    <BLANKLINE>
    - Unprocessed:
    echo baz qux
    <BLANKLINE>
    - Done.
    <BLANKLINE>

The 'stop' command is an alias for 'end'.

    >>> msg = message_from_string("""\
    ... From: cperson@example.com
    ... To: test-request@example.com
    ... Message-ID: <caribou>
    ...
    ... echo foo bar
    ... stop ignored
    ... echo baz qux
    ... """)

    >>> inject_message(mlist, msg, switchboard='command')
    >>> command.run()
    >>> len(virgin_queue.files)
    1
    >>> item = get_queue_messages('virgin')[0]
    >>> print item.msg.as_string()
    Subject: The results of your email commands
    ...
    <BLANKLINE>
    - Results:
    echo foo bar
    <BLANKLINE>
    - Unprocessed:
    echo baz qux
    <BLANKLINE>
    - Done.
    <BLANKLINE>