root/bin/pl-subscribe

#!/usr/bin/perl

=head1 NAME

pl-subscribe - Add addresses to a Lancelot list's subscriber database

=head1 SYNOPSIS

  pl-subscribe [-dwv?] [--[no]digest] [--[no]mail] [--[no]moderated]
             [--[no]welcome] [--verbose] list@domain [address ...]

=head1 OVERVIEW

The B<pl-subscribe> command allows a list owner to add addresses to a
list's subscriber database manually. Addresses may be listed on the command
line or fed to the command on its standard input.

=head1 DESCRIPTION

The B<pl-subscribe> command takes addresses from the command line or,
alternatively, standard input (if none are specified on the command
line) and adds them to the given list's subscriber database. Various
parameters may be used to control the subscribers' delivery options.

Addresses on the command line may take either of the forms

  alfred@example.com
  Alfred Newman <alfred@example.com>
  "Alfred E. Newman" <alfred@example.com>

(note that address specifications containing blanks, like the last
two, must be quoted on the command line).

If a name is given with the address, it is also stored in the
database.

Addresses passed on standard input may take the same forms. In addition,
blank lines and lines starting with the comment symbol, "#", are ignored.

For newly added addresses, the B<digest>, B<nomail>, and B<moderated>
options in the subscriber database take their default from the list
configuration parameters B<subscribe.digestdefault>,
B<subscribe.nomaildefault>, and B<subscribe.moderateddefault>,
respectively, if they are not set explicity (one way or the other) on
the command line.

Similarly, if neither B<--welcome> nor B<--nowelcome> is given, the
value of the B<subscribe.welcomedefault> list configuration parameter
determines whether the "welcome message" will be sent.

=head1 OPTIONS

=over 4

=item B<--digest>, B<-d>

The new addresses are added as "digest" subscribers; they will receive
aggregated copies of all messages submitted over a period of
time. (Digests are planned for Lancelot 0.3; until then, this option
is effectively equivalent to B<--nomail>, and digest subscribers will
not receive anything at all.)

=item B<--help>, B<-?>

Causes the program to output a brief usage explanation and exit.

=item B<--mail>

The new addresses are added as "receiving" subscribers; they will receive
either individual copies of all messages or digests depending on the
value of their B<digest> option.

=item B<--moderated>

The new addresses are added as "moderated" subscribers; anything they
submit will be placed before a moderator for approval before it is actually
posted to the list subscribers at large. (Message moderation is planned
for Lancelot 0.4; until then, this option is effectively ignored.)

=item B<--nodigest>

The new addresses are added as "regular" subscribers; they will receive
individual copies of all messages as they come in.

=item B<--nomail>

The new addresses are added as "non-receiving" subscribers; they will
receive no messages but messages sent from them will be accepted for
distribution.

=item B<--nomoderated>

The new addresses are added as "non-moderated" subscribers; anything they
submit will be posted to the list subscribers immediately without
message moderation.

=item B<--nowelcome>

No "welcome message" will be sent to the new addresses.

=item B<--verbose>, B<-v>

Causes the program to output messages about its progress to the
standard error channel.

=item B<--welcome>, B<-w>

A copy of the list's "welcome message" is sent to the new addresses
after they have been subscribed. 

=back

=head1 SEE ALSO

pl-conf(1), pl-init(1),  pl-list(1), pl-subchange(1), pl-unsubscribe(1)

=head1 AUTHOR

Anselm Lingnau <anselm@anselms.net>

=head1 COPYRIGHT AND LICENSE

Copyright 2004 by Anselm Lingnau. This program is free software; you
may redistribute it and/or modify it under the terms of the GNU
General Public License as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, refer to
<URL:http://www.gnu.org/copyleft/gpl.html>. You may also obtain it by
writing to the Free Software Foundation, Inc., 59 Temple Place - Suite
330, Boston, MA 02111-1307, USA.

=cut

use strict;

# Make Binary find it's libraries for non standard installations ...
use Config;
use File::Basename;
use vars qw($g_base_dir);
BEGIN {
    use FindBin qw($Bin);
    $g_base_dir = dirname ($Bin);
}
use lib "$g_base_dir/lib";
use lib "$g_base_dir/lib/perl5/$Config{version}";
use lib "$g_base_dir/lib/perl5/site_perl/$Config{version}";

use Lancelot::GetOpt qw/GetOptions/;

use Lancelot::DB;
use Lancelot::Send;
use Lancelot::Module::subscribe_user; # for the welcome message
use Lancelot::Log qw/log/;

my %opts = ( welcome => -1 );

GetOptions(\%opts, -defaults => 1, -argvmin => 1, "no list address specified",
           "digest|d!", "mail!", "moderated!", "welcome|w!");

my $listaddr = shift;

my $db = new Lancelot::DB $listaddr
    or die "$0: error accessing list $listaddr\n";

sub opt_or_conf {
    my ($option, $conf, $default) = @_;
    $default ||= 0;
    my ($cvalue) = $db->get_config($conf);
    return $opts{$option} != -1
        ? $opts{$option} : (defined $cvalue ? $cvalue : $default);
}

$opts{welcome} = opt_or_conf("welcome", "subscribe.welcome", 1);

my (%option) = (
    moderator => 0,
    digest => opt_or_conf("digest", "subscribe.digestdefault"),
    nomail => $opts{mail} != -1 ? !$opts{mail}
                : $db->get_config("subscribe.nomaildefault"),
    moderated => opt_or_conf("moderated", "subscribe.moderateddefault"),
);

my (@addrs) = @ARGV;
if (@ARGV == 0) {
    @addrs = grep { chomp; !/^\s*$/ && !/^\#/ } <STDIN>;
}

foreach my $k (sort keys %option) {
    log "debug", "$k => $option{$k}";
}
foreach my $a (@addrs) {
    if ($db->add_address($a, \%option)) {
        &send_welcome($a) if $opts{welcome};
        log "info", "$a subscribed\n";
    } else {
        warn "$0: error subscribing $a\n";
    }
}

sub send_welcome {
    my ($address) = @_;
    log "debug", "Sending welcome message to $address";
    Lancelot::Send::sendtemplate("welcome-message", $db, undef,
                                 { "new-subscriber" => $address });
}