aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordakkar <dakkar@thenautilus.net>2017-02-03 20:28:40 +0000
committerdakkar <dakkar@thenautilus.net>2017-02-03 20:28:40 +0000
commit564c0667e00820734fd2667911862dbc72ef72a6 (patch)
treec763f3163ca342f0a7e57458de6694c3a554da9a
parentPOD for ::Policy (diff)
downloadSietima-564c0667e00820734fd2667911862dbc72ef72a6.tar.gz
Sietima-564c0667e00820734fd2667911862dbc72ef72a6.tar.bz2
Sietima-564c0667e00820734fd2667911862dbc72ef72a6.zip
POD for ::Subscriber
-rw-r--r--lib/Sietima/Subscriber.pm67
1 files changed, 67 insertions, 0 deletions
diff --git a/lib/Sietima/Subscriber.pm b/lib/Sietima/Subscriber.pm
index 68f119b..649b2e5 100644
--- a/lib/Sietima/Subscriber.pm
+++ b/lib/Sietima/Subscriber.pm
@@ -8,6 +8,28 @@ use Email::Address;
use List::AllUtils qw(any);
use namespace::clean;
+=head1 NAME
+
+Sietima::Subscriber - a subscriber to a mailing list
+
+=head1 DESCRIPTION
+
+This class holds the primary email address for a mailing list
+subscriber, together with possible aliases and preferences.
+
+=head1 ATTRIBUTES
+
+All attributes are read-only.
+
+=head2 C<raw_address>
+
+Required L<< C<Email::Address> >> object, coercible from a string.
+
+This is the primary address for the subscriber, the one where they
+will receive messages from the mailing list.
+
+=cut
+
has raw_address => (
isa => Address,
is => 'ro',
@@ -16,6 +38,18 @@ has raw_address => (
handles => [qw(address name original)],
);
+=head2 C<aliases>
+
+Arrayref of L<< C<Email::Address> >> objects, each coercible from a
+string. Defaults to an empty arrayref.
+
+These are secondary addresses that the subscriber may write
+from. Subscriber-only mailing lists should accept messages from any of
+these addresses as if they were from the primary. The L<< /C<match> >>
+simplifies that task.
+
+=cut
+
my $address_array = ArrayRef[
Address->plus_coercions(
AddressFromStr
@@ -28,12 +62,34 @@ has aliases => (
);
sub _build_aliases { +[] }
+=head2 C<prefs>
+
+A hashref. Various preferences that may be interpreted by Sietima
+roles. Defaults to an empty hashref.
+
+=cut
+
has prefs => (
isa => HashRef,
is => 'ro',
default => sub { +{} },
);
+=head1 METHODS
+
+=head2 C<match>
+
+ if ($subscriber->match($address)) { ... }
+
+Given a L<< C<Email::Address> >> object (or a string), this method
+returns true if the address is equivalent to the
+L<primary|/raw_address> or any of the L</aliases>.
+
+This method should be used to determine whether an address belongs to
+a subscriber.
+
+=cut
+
sub match {
# we can't use the sub signature here, because we need the
# coercion
@@ -44,4 +100,15 @@ sub match {
$self->raw_address, $self->aliases->@*;
}
+=head2 C<address>
+
+=head2 C<name>
+
+=head2 C<original>
+
+These methods delegate to L<< C<Email::Address> >>'s methods of the
+same name, invoked on the L<primary address|/raw_address>.
+
+=cut
+
1;