From 06af52f31065f21dda2e8c22602c08fac389d070 Mon Sep 17 00:00:00 2001 From: dakkar Date: Tue, 7 Feb 2017 18:51:12 +0000 Subject: POD for ::Moderate --- lib/Sietima.pm | 15 +++- lib/Sietima/Role/SubscriberOnly/Moderate.pm | 113 +++++++++++++++++++++++++++- 2 files changed, 122 insertions(+), 6 deletions(-) diff --git a/lib/Sietima.pm b/lib/Sietima.pm index f22e408..6cdf404 100644 --- a/lib/Sietima.pm +++ b/lib/Sietima.pm @@ -296,8 +296,19 @@ Returns a hashref describing the command line processing for L<< C >>. L<< C >> uses this to build the command line parser. -This base class declares a single sub-command, C, that invokes -the L<< /C >> method. +This base class declares a single sub-command: + +=over + +=item C + +Invokes the L<< /C >> method. + +For example, in a C<.qmail> file: + + |/path/to/sietima send + +=back Roles can extend this to provide additional sub-commands and options. diff --git a/lib/Sietima/Role/SubscriberOnly/Moderate.pm b/lib/Sietima/Role/SubscriberOnly/Moderate.pm index c0e4a01..750e4be 100644 --- a/lib/Sietima/Role/SubscriberOnly/Moderate.pm +++ b/lib/Sietima/Role/SubscriberOnly/Moderate.pm @@ -39,6 +39,16 @@ with 'Sietima::Role::SubscriberOnly', 'Sietima::Role::WithMailStore', 'Sietima::Role::WithOwner'; +=head1 METHODS + +=head2 C + +L the email with the C +tag, and forwards it to the L. + +=cut + sub munge_mail_from_non_subscriber ($self,$mail) { my $id = $self->mail_store->store($mail,'moderation'); my $notice = Email::Stuffer @@ -49,6 +59,8 @@ sub munge_mail_from_non_subscriber ($self,$mail) { ->attach( $mail->as_string, content_type => 'message/rfc822', + # some clients, most notably Claws-Mail, seem to have + # problems with encodings other than this encoding => '7bit', ); $self->transport->send($notice->email,{ @@ -58,6 +70,18 @@ sub munge_mail_from_non_subscriber ($self,$mail) { return; } +=head2 C + + $sietima->resume($mail_id); + +Given an identifier returned when L +an email, this method retrieves the email and re-processes it via L<< +C|Sietima::Role::SubscriberOnly/ignoring_subscriberonly +>>. This will make sure that the email is not caught again by the +subscriber-only filter. + +=cut + sub resume ($self,$mail_id) { my $mail = $self->mail_store->retrieve_by_id($mail_id); $self->ignoring_subscriberonly( @@ -66,10 +90,33 @@ sub resume ($self,$mail_id) { $self->mail_store->remove($mail_id); } +=head2 C + + $sietima->drop($mail_id); + +Given an identifier returned when L +an email, this method deletes the email from the store. + +=cut + sub drop ($self,$mail_id) { $self->mail_store->remove($mail_id); } +=head2 C + + $sietima->list_mails_in_moderation_queue($sietima_runner); + +This method L of messages tagged +C, and L via the +L<< C >> object. + +This method is usually invoked from the command line, see L<< +/C >>. + +=cut + sub list_mails_in_moderation_queue ($self,$runner,@) { my $mails = $self->mail_store->retrieve_by_tags('moderation'); $runner->out(sprintf 'There are %d messages held for moderation:',scalar($mails->@*)); @@ -83,6 +130,19 @@ sub list_mails_in_moderation_queue ($self,$runner,@) { } } +=head2 C + + $sietima->show_mail_from_moderation_queue($sietima_runner); + +This method L +of the message requested from the command line, and L via the L<< C >> object. + +This method is usually invoked from the command line, see L<< +/C >>. + +=cut + sub show_mail_from_moderation_queue ($self,$runner,@) { my $id = $runner->parameters->{'mail-id'}; my $mail = $self->mail_store->retrieve_by_id($id); @@ -90,12 +150,57 @@ sub show_mail_from_moderation_queue ($self,$runner,@) { $runner->out($mail->as_string =~ s{\r\n}{\n}gr); } +=head1 MODIFIED METHODS + +=head2 C + +This method adds the following sub-commands for the command line: + +=over + +=item C + + $ sietima list-held + +Invokes the L<< /C >> method, printing +the identifiers of all messages held for moderation. + +=item C + + $ sietima show-held 32946p6eu7867 + +Invokes the L<< /C >> method, +printing one message held for moderation; the identifier is expected +as a positional parameter. + +=item C + + $ sietima resume-held 32946p6eu7867 + +Invokes the L<< /C >> method, causing the held message to be +processed normally; the identifier is expected as a positional +parameter. + +=item C + + $ sietima drop-held 32946p6eu7867 + +Invokes the L<< /C >> method, removing the held message; the +identifier is expected as a positional parameter. + +=back + +=cut + around command_line_spec => sub ($orig,$self) { my $spec = $self->$orig(); + # this allows us to tab-complete identifiers from the shell! my $list_mail_ids = sub ($self,$runner,$args) { $self->mail_store->retrieve_ids_by_tags('moderation'); }; + # a little factoring: $etc->($command_name) generates the spec for + # sub-commands that require a mail id my $etc = sub($cmd) { return ( summary => "$cmd the given mail, currently held for moderation", @@ -110,6 +215,10 @@ around command_line_spec => sub ($orig,$self) { ); }; + $spec->{subcommands}{'list-held'} = { + op => 'list_mails_in_moderation_queue', + summary => 'list all mails currently held for moderation', + }; $spec->{subcommands}{'show-held'} = { op => 'show_mail_from_moderation_queue', $etc->('show'), @@ -126,10 +235,6 @@ around command_line_spec => sub ($orig,$self) { }, $etc->('drop'), }; - $spec->{subcommands}{'list-held'} = { - op => 'list_mails_in_moderation_queue', - summary => 'list all mails currently held for moderation', - }; return $spec; }; -- cgit v1.2.3