root/bin/pl-conf

#!/usr/bin/perl

=head1 NAME

pl-conf - Query or modify Project Lancelot list configuration parameters

=head1 SYNOPSIS

  pl-conf [--query|-q] [--all|-A] [--modified|-M] [--defaults|-D]
            [--valueonly|-h] list@domain [parameter ...]
  pl-conf [--set|-s] list@domain ["parameter = value" ...]
  pl-conf [--import|-i] [--onlynew|-n] list@domain [file ...]
  pl-conf [--delete|-d] list@domain [parameter ...]
  pl-conf [--merge|-m] --into=list@domain list@domain
  pl-conf [--unmerge|-u] list@domain
  pl-conf [--alias|-a] list@domain [alias]

=head1 OVERVIEW

The B<pl-conf> command allows a list owner to query, change, or
delete various configuration parameters of a Lancelot list.

=head1 DESCRIPTION

The B<pl-conf> command can be used for four different purposes:

=head2 QUERYING PARAMETERS

With the B<--query> (or B<-q>) option, B<pl-conf> will print either
all of the configuration parameters in the database (if no parameter
names are given) or the specified parameters to standard output, like

  list.address = test@example.com
  list.owneraddress = alfred@example.com
  ...

If there is a single argument which ends in .*, all configuration
parameters whose names start with the part preceding the * will be
considered.

The parameter name and equals sign can be suppressed using the
B<--valueonly> option but only for parameters listed on the command
line.  This is convenient if the parameter value is to be used, e.g.,
in a shell script.

With the B<--modified> (or B<-M>) option, B<--query> only lists those
parameters whose values differ from their built-in defaults. With the
B<--defaults> (or B<-D>) option, the built-in default values of
parameters are displayed instead of their actual values. With the
B<--all> (or B<-A>) option, all parameters known to Project Lancelot
are displayed, not just those that actually occur in the database of
the list being considered.

The output of B<pl-conf --query> is suitable as input for
B<pl-conf --import>, which is useful to clone, rename, or migrate Lancelot
lists.

=head2 SETTING PARAMETERS

With the B<--set> (or B<-s>) option, B<pl-conf> will take
configuration parameter assignments from the command line and enter
them into the configuration database. A parameter's new value consists
of everything to the right of the equals sign excluding leading or
trailing spaces; to set a value that begins or ends with whitespace
use quotes as in

  pl-conf --set 'mail.subjecttag = "[Test] "'

(Only double quotes are allowed; to include a double quote in a
double-quoted string, put a backslash in front of it.)

=head2 IMPORTING PARAMETERS WHOLESALE

With the B<--import> (or B<-i>) option, B<pl-conf> reads configuration
parameter assignments from files mentioned on the command line, or from
standard input. Blank lines and lines starting with the comment symbol,
"#", are ignored.

If the B<--onlynew> (or B<-n>) option is given, only those configuration
parameters from the input are taken into account that do not already
exist in the configuration database. This is handy if Lancelot acquires
new features with corresponding configuration parameters.

=head2 DELETING PARAMETERS

With the B<--delete> (or B<-d>) option, B<pl-conf> deletes the configuration
parameters listed on the command line from the database.

=head2 MERGING AND UNMERGING DATABASES

It is possible to combine the databases of several lists into one database
file, which allows them to be managed together using a web frontend such
as Project Guinevere. To do this, decide which of the databases is to be
the "master" database, and merge the other database(s) into it using the
B<--merge> option of B<pl-conf>, as in

  pl-conf --merge --into=master@example.com test@example.com

After this, all Project Lancelot commands can be used on
B<test@example.com> as before, except changes will now be made to the
appropriate parts of the B<master@example.com> database.

Unmerging databases using the B<--unmerge> option isn't implemented yet.

=head2 LIST ALIASES

Aliases for mailing list addresses can be introduced using the B<--alias>
(or B<-a>) option. These are strictly for convenience when using the
Project Lancelot command-line tools and have no bearing on mail delivery.

The command

  pl-conf --alias test@example.com test

introduces B<test> as an alias for the B<test@example.com> list. This
means that you may now use commands like

  pl-conf -q test

in addition to

  pl-conf -q test@example.com

A single list may have arbitrarily many aliases.

Invoking B<pl-conf --alias> with just the list address will display that
list's alias(es), if any. To find the list that an alias points to, use
a command like

  pl-conf -qh test list.address

Aliases are implemented by means of symbolic links in the F<$HOME/.pl>
directory. You can remove an alias by removing the corresponding symbolic
link from that directory.

Project Lancelot maintains an implicit alias, B<.>, to the mailing list
most recently used in a Project Lancelot command (except B<pl-incoming>).
This means that in

  pl-list -a test@example.com "hugo*"
  pl-subscribe . hugo@example.com

the second command will apply to the B<test@example.com> list.

=head1 OPTIONS

=over 4

=item B<--alias>, B<-a>

Introduces a command-line alias for a mailing list.

=item B<--all>, B<-A>

With B<--query>, outputs all configuration parameters known to Project
Lancelot, not just those that actually occur in the database of the
current list.

=item B<--defaults>, B<-D>

With B<--query>, causes the program to output the built-in default values
of parameters rather than their actual values.

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

Causes the program to delete the configuration parameters mentioned on
the command line from a list's database.

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

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

=item B<--import>, B<-i>

Causes the program to read configuration parameter assignments from
files mentioned on the command line, or standard input, and add them
to a list's database. Blank lines and comment lines are ignored.

=item B<--into>

When merging a list's database into another using the B<--merge> option,
this specifies the list that the given list's database should be merged
into.

=item B<--modified>, B<-M>

With B<--query>, outputs only those parameter whose values differ from
their built-in default values.

=item B<--onlynew>, B<-n>

When importing configuration parameters wholesale using B<--import>,
causes the program to ignore configuration parameters that already
exist in the database.

=item B<--query>, B<-q>

Causes the program to output the values of some or all of a list's
configuration parameters.

=item B<--set>, B<-s>

Causes the program to take configuration parameter assignments from
the command line and add them to a list's database.

=item B<--user>, B<-u>

Pretends to be the given user for the purposes of locating the list's
database. The database's file permissions must still allow access so this
probably works best if you are running as root or have group write
permission to the database.

=item B<--valueonly>, B<-h>

When used together with B<--query>, omits the parameter name and equals
sign from the output for explicitly named parameters.

When used together with B<--set> or B<--import>, this option is ignored.

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

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

=back

=head1 SEE ALSO

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

=head1 BUGS

There is no fixed set of valid configuration parameters; whatever is
passed to the command will be entered in the database.

=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 File::Spec;
use File::Basename;
use IO::Dir;

use Lancelot::GetOpt qw/GetOptions/;
use Pod::Usage;

use Lancelot::DB;
use Lancelot::Log qw/log/;

my %opts = ( all => 0 );

GetOptions(\%opts, -defaults, -argvmin => 1, "no list address specified",
           "query|q?", "set|s?", "import|i?", "delete|d?", "valueonly|h?",
           "merge|m?", "unmerge|u?", "alias|a?", "into=",
           "defaults|D?", "modified|M?", "all|A?",
           "onlynew|n?", "edit|e?", "user|u=");

pod2usage( -message => "$0: need one of --query, --set, --import, --delete, --merge, --unmerge, --alias",
           -exitvalue => 2 )
    if $opts{alias} + $opts{query} + $opts{set} + $opts{import}
           + $opts{delete} + $opts{edit} + $opts{merge} + $opts{unmerge} != 1
        || (($opts{valueonly} || $opts{defaults} || $opts{modified}
            || $opts{all}) && !$opts{query})
        || ($opts{onlynew} && !$opts{import})
        || ($opts{into} && !$opts{merge});

my $listaddr = shift;

my $db = new Lancelot::DB $listaddr, { user => $opts{user} }
    or die "$0: error accessing list $listaddr\n";

if ($opts{query}) {
    my @parameters = @ARGV;
    if (@ARGV == 0 || (@ARGV == 1 && $ARGV[0] =~ /\.\*$/)) {
        my ($pattern) = '.';
        if ($ARGV[0]) {
            ($pattern = $ARGV[0]) =~ s/\./\\./g; $pattern =~ s/\*/.*/g;
        }
        @parameters = grep { /$pattern/o }
            $db->config_names({ all => $opts{all} });
        $opts{valueonly} = 0;
    }
    foreach my $p (sort @parameters) {
        my ($v, $status, $default) = $db->get_config_x($p);
        next if $opts{modified} && $status < 2; 
        $v = $default if $opts{defaults};
        print "$p = " unless $opts{valueonly};
        if ($v =~ /^\s+/ || $v =~ /\s+$/) {
            $v =~ s/\"/\\\"/g;
            $v = qq|"$v"|;
        }
        print $v, "\n";
    }
} elsif ($opts{delete}) {
    pod2usage("$0: no parameters given\n") if @ARGV == 0;
    $db->delete_configs(@ARGV);
} elsif ($opts{set}) {
    pod2usage("$0: no configs given\n") if @ARGV == 0;
    $db->set_configs(@ARGV);
} elsif ($opts{alias}) {
    if (@ARGV == 0) {
        # Output aliases for current list
        my $d = IO::Dir->new(File::Spec->join($ENV{HOME}, ".pl"));
        if (defined $d) {
            while (defined ($_ = $d->read)) {
                next if $_ eq ".default-list";
                my $dir = File::Spec->join($ENV{HOME}, ".pl", $_);
                if (-l $dir) {
                    my $lk = readlink $dir;
                    print "$_\n" if basename($lk) eq $listaddr
                        || basename($lk).'@'.basename(dirname($lk)) eq $listaddr;
                };
            }
        }
    } elsif (@ARGV == 1) {
        # Set $ARGV[0] up as an alias for the current list
        my $alias = $ARGV[0];
        pod2usage("$0: alias name may only contain letters, digits, and \".-_\"\n")
            if $alias !~ /^[-.\w]+$/;
        my $lk = File::Spec->join($ENV{HOME}, ".pl", $alias);
        log "debug", "lk=$lk";
        pod2usage("$0: alias $alias is otherwise used") if -e $lk && !-l $lk;
        unlink $lk if -l $lk;
        symlink $db->get_listdir(), $lk or log "err", "alias: $!";
    } else {
        pod2usage("$0: too many arguments\n");
    }
} elsif ($opts{import}) {
    my @lines;
    my %exist = map { $_ => 1 } $db->config_names;
    foreach my $line (grep { !/^$/ && !/^\#/ } <>) {
        my ($name) = $line =~ /^\s*([\.\w]+)/;
        push @lines, $line unless $opts{onlynew} && $exist{$name};
    }
    $db->set_configs(@lines);
} elsif ($opts{edit}) {
    my $cmd = $ENV{VISUAL};
    $cmd ||= $ENV{EDITOR};
    $cmd ||= "/usr/bin/sensible-editor" if -x "/usr/bin/sensible-editor";
    $cmd ||= "/usr/bin/vi";

    my $file = File::Spec->join($db->get_listdir, "pl-conf.$$");
    # Hole Konfiguration nach $file

    if (!system "$cmd $file") {
        # Zurückschreiben in die Datenbank
    } else {
        # Temporäre Datei löschen
    }
} elsif ($opts{merge}) {
    log "debug", "merge $listaddr into $opts{into}";
    $db->merge_into($opts{into}) or die "$0: error on merge\n";
} elsif ($opts{unmerge}) {
    die "$0: unmerge: not implemented yet\n";
}