From 4a90832ad9b1436dce84e3ac0d8cb67a8fb33102 Mon Sep 17 00:00:00 2001 From: dakkar Date: Tue, 7 Feb 2017 19:59:04 +0000 Subject: use more Pod::Weaver --- lib/Sietima.pm | 60 +++++++++-------------------- lib/Sietima/CmdLine.pm | 16 +++----- lib/Sietima/MailStore.pm | 14 +++---- lib/Sietima/MailStore/FS.pm | 10 ++--- lib/Sietima/Message.pm | 10 ++--- lib/Sietima/Role/AvoidDups.pm | 4 +- lib/Sietima/Role/Debounce.pm | 4 +- lib/Sietima/Role/Headers.pm | 8 +--- lib/Sietima/Role/NoMail.pm | 4 +- lib/Sietima/Role/ReplyTo.pm | 8 +--- lib/Sietima/Role/SubjectTag.pm | 8 +--- lib/Sietima/Role/SubscriberOnly.pm | 12 ++---- lib/Sietima/Role/SubscriberOnly/Drop.pm | 4 +- lib/Sietima/Role/SubscriberOnly/Moderate.pm | 16 +++----- lib/Sietima/Role/WithMailStore.pm | 4 +- lib/Sietima/Role/WithOwner.pm | 4 +- lib/Sietima/Role/WithPostAddress.pm | 4 +- lib/Sietima/Runner.pm | 2 + lib/Sietima/Subscriber.pm | 16 ++++---- lib/Sietima/Types.pm | 18 ++++----- weaver.ini | 9 +++++ 21 files changed, 88 insertions(+), 147 deletions(-) diff --git a/lib/Sietima.pm b/lib/Sietima.pm index b40e9fc..e317147 100644 --- a/lib/Sietima.pm +++ b/lib/Sietima.pm @@ -44,54 +44,34 @@ consumes L<< C >> to simplify composing roles: These are the traits provided with the default distribution: -=over - -=item L<< C|Sietima::Role::AvoidDups >> - +=for :list += L<< C|Sietima::Role::AvoidDups >> prevents the sender from receiving copies of their own messages - -=item L<< C|Sietima::Role::Debounce >> - += L<< C|Sietima::Role::Debounce >> avoids mail-loops using a C header - -=item L<< C|Sietima::Role::Headers >> - += L<< C|Sietima::Role::Headers >> adds C headers to all outgoing messages - -=item L<< C|Sietima::Role::NoMail >> - += L<< C|Sietima::Role::NoMail >> avoids sending messages to subscribers who don't want them - -=item L<< C|Sietima::Role::ReplyTo >> - += L<< C|Sietima::Role::ReplyTo >> optionally sets the C header to the mailing list address - -=item L<< C|Sietima::Role::SubjectTag >> - += L<< C|Sietima::Role::SubjectTag >> prepends a C<[tag]> to the subject header of outgoing messages that aren't already tagged - -=item L<< C|Sietima::Role::SubscriberOnly::Drop >> - += L<< C|Sietima::Role::SubscriberOnly::Drop >> silently drops all messages coming from addresses not subscribed to the list - -=item L<< C|Sietima::Role::SubscriberOnly::Moderate >> - += L<< C|Sietima::Role::SubscriberOnly::Moderate >> holds messages coming from addresses not subscribed to the list for moderation, and provides commands to manage the moderation queue -=back - The only "configuration mechanism" currently supported is to initialise a C object in your driver script, passing all the needed values to the constructor. L<< C >> is the recommended way of doing that: it adds command-line parsing capability to Sietima. -=head1 ATTRIBUTES - -=head2 C +=attr C A L<< C >> instance, coerced from string if necessary. This is the address that Sietima will send messages @@ -106,7 +86,7 @@ has return_path => ( coerce => AddressFromStr, ); -=head2 C +=attr C An array-ref of L<< C >> objects, defaults to the empty array. @@ -138,7 +118,7 @@ has subscribers => ( ); sub _build_subscribers { +[] } -=head2 C +=attr C A L<< C >> instance, which will be used to send messages. If not passed in, Sietima uses L<< @@ -153,9 +133,7 @@ has transport => ( ); sub _build_transport { Email::Sender::Simple->default_transport } -=head1 METHODS - -=head2 C +=method C $sietima->handle_mail_from_stdin(); @@ -173,7 +151,7 @@ sub handle_mail_from_stdin($self,@) { return $self->handle_mail($incoming_mail); } -=head2 C +=method C $sietima->handle_mail($email_mime); @@ -193,7 +171,7 @@ sub handle_mail($self,$incoming_mail) { return; } -=head2 C +=method C my $subscribers_aref = $sietima->subscribers_to_send_to($email_mime); @@ -213,7 +191,7 @@ sub subscribers_to_send_to($self,$incoming_mail) { return $self->subscribers; } -=head2 C +=method C my @messages = $sietima->munge_mail($email_mime); @@ -239,7 +217,7 @@ sub munge_mail($self,$incoming_mail) { }); } -=head2 C +=method C $sietima->send_message($sietima_message); @@ -265,7 +243,7 @@ sub send_message($self,$outgoing_message) { sub _trait_namespace { 'Sietima::Role' } ## no critic(ProhibitUnusedPrivateSubroutines) -=head2 C +=method C my $addresses_href = $sietima->list_addresses; @@ -286,7 +264,7 @@ sub list_addresses($self) { }; } -=head2 C +=method C my $app_spec_data = $sietima->command_line_spec; diff --git a/lib/Sietima/CmdLine.pm b/lib/Sietima/CmdLine.pm index 98805f9..6c24834 100644 --- a/lib/Sietima/CmdLine.pm +++ b/lib/Sietima/CmdLine.pm @@ -28,9 +28,7 @@ use namespace::clean; This class simplifies the creation of a L<< C >> object, and uses L<< C >> to provide a command-line interface to it. -=head1 ATTRIBUTES - -=head2 C +=attr C Required, an instance of L<< C >>. You can either construct it yourself, or use the L ( isa => SietimaObj, ); -=head2 C +=attr C Optional hashref. Used inside L<< /C >>. If you're not familiar with L<< C >>, you probably don't want to touch @@ -58,9 +56,7 @@ has extra_spec => ( default => sub { +{} }, ); -=head1 METHODS - -=head2 C +=method C my $cmdline = Sietima::CmdLine->new({ sietima => Sietima->with_traits(qw(SubjectTag))->new({ @@ -96,7 +92,7 @@ sub BUILDARGS($class,@args) { return $args; } -=head2 C +=method C Returns an instance of L<< C >>, built from the specification returned by calling L<< @@ -121,12 +117,12 @@ sub _build_app_spec($self) { }); } -=head2 C +=method C Returns an instance of L<< C >>, built from the L<< /C >>. -=head2 C +=method C Delegates to the L<< /C >>'s L<< C|App::Spec::Run/run >> method. diff --git a/lib/Sietima/MailStore.pm b/lib/Sietima/MailStore.pm index c529e3e..5e6fc7f 100644 --- a/lib/Sietima/MailStore.pm +++ b/lib/Sietima/MailStore.pm @@ -11,9 +11,7 @@ use namespace::clean; This role defines the interface that all mail stores must adhere to. It does not provide any implementation. -=head1 REQUIRED METHODS - -=head2 C +=require C my $id = $ms->store($email_mime_object,@tags); @@ -23,7 +21,7 @@ tags (which must be strings). Must return a unique identifier for the stored message. It is acceptable if identical messages are indistinguishable by the storage. -=head2 C +=require C my $email_mime_object = $ms->retrieve_by_id($id); @@ -34,7 +32,7 @@ C >> object). If the message has been deleted, or the identifier is not recognised, this method must return C in scalar context. -=head2 C +=require C my @ids = $ms->retrieve_ids_by_tags(@tags)->@*; @@ -57,7 +55,7 @@ For example: $ms->retrieve_ids_by_tags('t1','t2') ==> [ $id3 ] $ms->retrieve_ids_by_tags('t3') ==> [ ] -=head2 C +=require C my @email_mime_objects = $ms->retrieve_by_tags(@tags)->@*; @@ -73,7 +71,7 @@ return an arrayref of hashrefs. For example: { id => $id1, mail => $msg1 }, ] -=head2 C +=require C $ms->remove($id); @@ -81,7 +79,7 @@ This method must remove the message corresponding to the given identifier from the persistent storage. Removing a non-existent message must succeed, and do nothing. -=head2 C +=require C $ms->clear(); diff --git a/lib/Sietima/MailStore/FS.pm b/lib/Sietima/MailStore/FS.pm index d34b388..fe41de4 100644 --- a/lib/Sietima/MailStore/FS.pm +++ b/lib/Sietima/MailStore/FS.pm @@ -59,7 +59,7 @@ sub BUILD($self,@) { return; } -=head2 C +=method C my $id = $store->store($email_mime_object,@tags); @@ -85,7 +85,7 @@ sub store($self,$mail,@tags) { return $id; } -=head2 C +=method C my $email_mime_object = $store->retrieve_by_id($id); @@ -106,7 +106,7 @@ sub retrieve_by_id($self,$id) { return Email::MIME->new($msg_path->slurp_raw); } -=head2 C +=method C my @ids = $store->retrieve_ids_by_tags(@tags)->@*; @@ -150,7 +150,7 @@ sub retrieve_ids_by_tags($self,@tags) { return \@ret; } -=head2 C +=method C my @email_mime_objects = $store->retrieve_by_tags(@tags)->@*; @@ -178,7 +178,7 @@ sub retrieve_by_tags($self,@tags) { return \@ret; } -=head2 C +=method C $store->remove($id); diff --git a/lib/Sietima/Message.pm b/lib/Sietima/Message.pm index 30befdb..b0d82e6 100644 --- a/lib/Sietima/Message.pm +++ b/lib/Sietima/Message.pm @@ -34,7 +34,7 @@ C|Sietima/send_message >>. All attributes are read-only and required. -=head2 C +=attr C An L<< C >> object, representing the message. @@ -46,7 +46,7 @@ has mail => ( required => 1, ); -=head2 C +=attr C An L<< C >> object, coercible from a string, representing the sender. @@ -60,7 +60,7 @@ has from => ( required => 1, ); -=head2 C +=attr C An arrayref of L<< C >> objects, each coercible from a string or an L<< C >> object, representing the @@ -81,9 +81,7 @@ has to => ( required => 1, ); -=head1 METHODS - -=head2 C +=method C my %envelope = $message->envelope->%*; diff --git a/lib/Sietima/Role/AvoidDups.pm b/lib/Sietima/Role/AvoidDups.pm index c6a5cdd..e0a5bae 100644 --- a/lib/Sietima/Role/AvoidDups.pm +++ b/lib/Sietima/Role/AvoidDups.pm @@ -18,9 +18,7 @@ message to a subscriber, if that subscriber is already mentioned in the C or C header fields, because they can be assumed to be already receiving the message directly from the sender. -=head1 MODIFIED METHODS - -=head2 C +=modif C Filters out subscribers that L the addresses in the C or C headers of the incoming email. diff --git a/lib/Sietima/Role/Debounce.pm b/lib/Sietima/Role/Debounce.pm index b128422..e6bd087 100644 --- a/lib/Sietima/Role/Debounce.pm +++ b/lib/Sietima/Role/Debounce.pm @@ -18,9 +18,7 @@ have that same header. This prevents messages bounced by other services from being looped between the mailing list and those other services. -=head1 MODIFIED METHODS - -=head2 C +=modif C If the incoming email contains our C header, this method will return an empty list (essentially dropping the message). diff --git a/lib/Sietima/Role/Headers.pm b/lib/Sietima/Role/Headers.pm index 320ab93..92a24f7 100644 --- a/lib/Sietima/Role/Headers.pm +++ b/lib/Sietima/Role/Headers.pm @@ -34,9 +34,7 @@ C >> objects (in which case the header will have a C URI as value) or strings (which will be used literally for the value of the header). -=head1 ATTRIBUTES - -=head2 C +=attr C Optional string, the name of the mailing list. If this attribute is set, a C header will be added, with a value built out of the @@ -88,9 +86,7 @@ sub _add_headers_to($self,$message) { return; } -=head1 MODIFIED METHODS - -=head2 C +=modif C This method adds list-management headers to each message returned by the original method. diff --git a/lib/Sietima/Role/NoMail.pm b/lib/Sietima/Role/NoMail.pm index 2d129a8..10071d6 100644 --- a/lib/Sietima/Role/NoMail.pm +++ b/lib/Sietima/Role/NoMail.pm @@ -22,9 +22,7 @@ A L<< C >> list with this role applied will not send messages to subscribers that have the C preference set to a false value. -=head1 MODIFIED METHODS - -=head2 C +=modif C Filters out subscribers that have the C preference set to a false value. diff --git a/lib/Sietima/Role/ReplyTo.pm b/lib/Sietima/Role/ReplyTo.pm index 1e10420..6b21f20 100644 --- a/lib/Sietima/Role/ReplyTo.pm +++ b/lib/Sietima/Role/ReplyTo.pm @@ -40,9 +40,7 @@ C|Sietima::Role::WithPostAddress >>. with 'Sietima::Role::WithPostAddress'; -=head1 ATTRIBUTES - -=head2 C +=attr C Optional boolean, defaults to false. If set to a true value, all messages will have their C header set to the value of the @@ -57,9 +55,7 @@ has munge_reply_to => ( default => 0, ); -=head1 MODIFIED METHODS - -=head2 C +=modif C For each message returned by the original method, this method partitions the subscribers, who are recipients of the message, diff --git a/lib/Sietima/Role/SubjectTag.pm b/lib/Sietima/Role/SubjectTag.pm index dd72562..7602405 100644 --- a/lib/Sietima/Role/SubjectTag.pm +++ b/lib/Sietima/Role/SubjectTag.pm @@ -19,9 +19,7 @@ use namespace::clean; A L<< C >> list with this role applied will prepend the given tag to every outgoing message's C header. -=head1 ATTRIBUTES - -=head2 C +=attr C Required string. This string, enclosed by square brackets, will be prepended to the C header of outgoing messages. For example, @@ -40,9 +38,7 @@ has subject_tag => ( required => 1, ); -=head1 MODIFIED METHODS - -=head2 C +=modif C The subject of the incoming email is modified to add the tag (unless it's already there). The email is then processed normally. diff --git a/lib/Sietima/Role/SubscriberOnly.pm b/lib/Sietima/Role/SubscriberOnly.pm index d2edf6b..6524d39 100644 --- a/lib/Sietima/Role/SubscriberOnly.pm +++ b/lib/Sietima/Role/SubscriberOnly.pm @@ -29,9 +29,7 @@ with messages from non-subscribers. See L<< C >> and L<< C >> for useable roles. -=head1 REQUIRED METHODS - -=head2 C +=require C sub munge_mail_from_non_subscriber($self,$mail) { ... } @@ -48,9 +46,7 @@ requires 'munge_mail_from_non_subscriber'; our $let_it_pass=0; ## no critic(ProhibitPackageVars) -=head1 MODIFIED METHODS - -=head2 C +=modif C If the incoming email's C header contains an address that L any of the subscribers, the email @@ -70,9 +66,7 @@ around munge_mail => sub ($orig,$self,$mail) { } }; -=head1 METHODS - -=head2 C +=method C $sietima->ignoring_subscriberonly(sub($s) { $s->handle_mail($mail); diff --git a/lib/Sietima/Role/SubscriberOnly/Drop.pm b/lib/Sietima/Role/SubscriberOnly/Drop.pm index dea742b..d9de94e 100644 --- a/lib/Sietima/Role/SubscriberOnly/Drop.pm +++ b/lib/Sietima/Role/SubscriberOnly/Drop.pm @@ -25,9 +25,7 @@ C|Sietima::Role::SubscriberOnly >>. with 'Sietima::Role::SubscriberOnly'; -=head1 METHODS - -=head2 C +=method C Does nothing, returns an empty list. diff --git a/lib/Sietima/Role/SubscriberOnly/Moderate.pm b/lib/Sietima/Role/SubscriberOnly/Moderate.pm index 13bc541..c4d62c9 100644 --- a/lib/Sietima/Role/SubscriberOnly/Moderate.pm +++ b/lib/Sietima/Role/SubscriberOnly/Moderate.pm @@ -38,9 +38,7 @@ with 'Sietima::Role::SubscriberOnly', 'Sietima::Role::WithMailStore', 'Sietima::Role::WithOwner'; -=head1 METHODS - -=head2 C +=method C L the email with the C tag, and forwards it to the L +=method C $sietima->resume($mail_id); @@ -89,7 +87,7 @@ sub resume ($self,$mail_id) { $self->mail_store->remove($mail_id); } -=head2 C +=method C $sietima->drop($mail_id); @@ -102,7 +100,7 @@ sub drop ($self,$mail_id) { $self->mail_store->remove($mail_id); } -=head2 C +=method C $sietima->list_mails_in_moderation_queue($sietima_runner); @@ -129,7 +127,7 @@ sub list_mails_in_moderation_queue ($self,$runner,@) { } } -=head2 C +=method C $sietima->show_mail_from_moderation_queue($sietima_runner); @@ -149,9 +147,7 @@ sub show_mail_from_moderation_queue ($self,$runner,@) { $runner->out($mail->as_string =~ s{\r\n}{\n}gr); } -=head1 MODIFIED METHODS - -=head2 C +=modif C This method adds the following sub-commands for the command line: diff --git a/lib/Sietima/Role/WithMailStore.pm b/lib/Sietima/Role/WithMailStore.pm index e139965..7ca4b4e 100644 --- a/lib/Sietima/Role/WithMailStore.pm +++ b/lib/Sietima/Role/WithMailStore.pm @@ -25,9 +25,7 @@ On its own, this role is not very useful, but other roles (like L<< C|Sietima::Role::SubscriberOnly::Moderate >>) can have uses for an object that can persistently store messages. -=head1 ATTRIBUTES - -=head2 C +=attr C Required instance of an object that consumes the L<< C >> role. Instead of passing an instance, you can diff --git a/lib/Sietima/Role/WithOwner.pm b/lib/Sietima/Role/WithOwner.pm index 0677f90..5a11d05 100644 --- a/lib/Sietima/Role/WithOwner.pm +++ b/lib/Sietima/Role/WithOwner.pm @@ -23,9 +23,7 @@ On its own, this role is not very useful, but other roles (like L<< C|Sietima::Role::SubscriberOnly::Moderate >>) can have uses for an owner address. -=head1 ATTRIBUTES - -=head2 C +=attr C Required instance of L<< C >>, coercible from a string. This is the address of the owner of the list. diff --git a/lib/Sietima/Role/WithPostAddress.pm b/lib/Sietima/Role/WithPostAddress.pm index daa483a..333c5e3 100644 --- a/lib/Sietima/Role/WithPostAddress.pm +++ b/lib/Sietima/Role/WithPostAddress.pm @@ -24,9 +24,7 @@ On its own, this role is not very useful, but other roles (like L<< C|Sietima::Role::ReplyTo >>) can have uses for a post address. -=head1 ATTRIBUTES - -=head2 C +=attr C An L<< C >> object, defaults to the value of the L<< C|Sietima/return_path >> attribute. This is the address diff --git a/lib/Sietima/Runner.pm b/lib/Sietima/Runner.pm index d18f936..ca64348 100644 --- a/lib/Sietima/Runner.pm +++ b/lib/Sietima/Runner.pm @@ -16,6 +16,8 @@ itself to execute the built-in commands, instead of delegating to the C object (in our case, a C instance) which would delegate back via L<< C >>. +=for Pod::Coverage run_op + =cut extends 'App::Spec::Run'; diff --git a/lib/Sietima/Subscriber.pm b/lib/Sietima/Subscriber.pm index 4782e85..b62e44f 100644 --- a/lib/Sietima/Subscriber.pm +++ b/lib/Sietima/Subscriber.pm @@ -20,7 +20,7 @@ subscriber, together with possible aliases and preferences. All attributes are read-only. -=head2 C +=attr C Required L<< C >> object, coercible from a string. @@ -37,7 +37,7 @@ has primary => ( handles => [qw(address name original)], ); -=head2 C +=attr C Arrayref of L<< C >> objects, each coercible from a string. Defaults to an empty arrayref. @@ -61,7 +61,7 @@ has aliases => ( ); sub _build_aliases { +[] } -=head2 C +=attr C A hashref. Various preferences that may be interpreted by Sietima roles. Defaults to an empty hashref. @@ -74,9 +74,7 @@ has prefs => ( default => sub { +{} }, ); -=head1 METHODS - -=head2 C +=method C if ($subscriber->match($address)) { ... } @@ -99,11 +97,11 @@ sub match { $self->primary, $self->aliases->@*; } -=head2 C
+=method C
-=head2 C +=method C -=head2 C +=method C These methods delegate to L<< C >>'s methods of the same name, invoked on the L. diff --git a/lib/Sietima/Types.pm b/lib/Sietima/Types.pm index e7a576d..9f052e3 100644 --- a/lib/Sietima/Types.pm +++ b/lib/Sietima/Types.pm @@ -20,9 +20,7 @@ use Type::Library This module is a L<< C >>. It declares a few type constraints nad coercions. -=head1 TYPES - -=head2 C +=type C An instance of L<< C >>. @@ -30,7 +28,7 @@ An instance of L<< C >>. class_type SietimaObj, { class => 'Sietima' }; -=head2 C +=type C An instance of L<< C >>. @@ -38,7 +36,7 @@ An instance of L<< C >>. class_type EmailMIME, { class => 'Email::MIME' }; -=head2 C +=type C An object that consumes the role L<< C >>. @@ -46,7 +44,7 @@ An object that consumes the role L<< C >>. role_type Transport, { role => 'Email::Sender::Transport' }; -=head2 C +=type C An object that consumes the role L<< C >>. @@ -79,7 +77,7 @@ declare_coercion MailStoreFromHashRef, q{ require Module::Runtime; } . q{ Module::Runtime::use_module(delete $_->{class})->new($_); }; -=head2 C
+=type C
An instance of L<< C >>. @@ -104,7 +102,7 @@ declare_coercion AddressFromStr, to_type Address, from Str, q{ (Email::Address->parse($_))[0] }; -=head2 C +=type C A string composed exclusively of "word" (C) characters. Used by L to tag messages. @@ -118,7 +116,7 @@ declare TagName, as Str, .qq{ && ($varname =~/\\A\\w+\\z/) }; }; -=head2 C +=type C An instance of L<< C >>. @@ -126,7 +124,7 @@ An instance of L<< C >>. class_type Message, { class => 'Sietima::Message' }; -=head2 C +=type C An instance of L<< C >>. diff --git a/weaver.ini b/weaver.ini index 4cf1cae..f4c9077 100644 --- a/weaver.ini +++ b/weaver.ini @@ -14,12 +14,21 @@ [Collect / ATTRIBUTES] command = attr +[Collect / REQUIRED METHODS] +command = require + [Collect / METHODS] command = method +[Collect / MODIFIED METHODS] +command = modif + [Collect / FUNCTIONS] command = func +[Collect / TYPES] +command = type + [Leftovers] [Region / postlude] -- cgit v1.2.3