Improve help and add pod2usage()
authorHeiko Schlittermann <hs@schlittermann.de>
Wed, 01 Jun 2016 01:09:04 +0200
changeset 64 4a17eef44b7c
parent 63 8525154c1389
child 65 a118304a1f79
Improve help and add pod2usage()
README
bin/exigrey
exim.conf.ex
--- a/README	Wed Jun 01 00:54:05 2016 +0200
+++ b/README	Wed Jun 01 01:09:04 2016 +0200
@@ -1,2 +1,19 @@
 The documenation is currently only available from
 http://www.schlittermann.de/doc/grey
+
+
+Example configuration snippet
+-----------------------------
+
+perl_startup = use Exim::Grey qw(unseen);
+GREYLISTED = ${perl{unseen}{<$sender_address>:<$local_part@$domain>/$sender_host_address}{60}}
+
+acl_check_rcpt:
+
+  ...
+
+  defer  
+	 condition      = GREYLISTED
+         condition      = ${if <{$message_size}{1M}}
+	 log_message    = grey listed exigrey
+
--- a/bin/exigrey	Wed Jun 01 00:54:05 2016 +0200
+++ b/bin/exigrey	Wed Jun 01 01:09:04 2016 +0200
@@ -2,24 +2,6 @@
 # © 2006,2007,2016 Heiko Schlittermann <hs@schlittermann.de>
 # Quick and dirty. Absolutly no warranty. Not even for spelling ;-)
 
-use constant USAGE => <<'#';
-
-Usage: !ME! --insert item [delay [db]]	# insert an item
-       !ME! --remove item               # remove an item
-       !ME! --list [db]			# list all items
-       !ME! --stat [db* ...]		# print short statistic
-       !ME! --clean [days [db* ...]]	# remove items not used since <days> days
-       !ME! --purge [days [db* ...]]	# remove items older than <days> days
-       !ME! --dbs [db* ...]		# list data base(s)
-
-       db  -- single name of database
-       db* -- glob pattern of database
-
-       If the data base name doesn't doesn't start with "./" or "/"
-       it is considered to be realtiv to exim_spool_dir/grey/.
-
-#
-
 use strict;
 use warnings;
 use Getopt::Long;
@@ -29,6 +11,7 @@
 use FindBin qw/$Bin/;
 use POSIX qw/strftime mktime/;
 use if $ENV{DEBUG} => 'Smart::Comments';
+use Pod::Usage;
 
 use Exim::Grey qw(:all);
 
@@ -49,21 +32,17 @@
 MAIN: {
 
     GetOptions(
-        "list!"   => \$opt_list,
-        "insert!" => \$opt_insert,
-        "remove!" => \$opt_remove,
-        "stats!"  => \$opt_stats,
-        "clean!"  => \$opt_clean,
-        "purge!"  => \$opt_purge,
-        "dbs!"    => \$opt_dbs,
-        "help!"   => \$opt_help,
-    ) or die ME . ": Bad usage, try " . ME . " --help.\n";
-
-    if ($opt_help) {
-        ($_ = USAGE) =~ s/!(.*?)!/eval $1/eg;
-        print;
-        exit 0;
-    }
+        'list!'   => \$opt_list,
+        'insert!' => \$opt_insert,
+        'remove!' => \$opt_remove,
+        'stats!'  => \$opt_stats,
+        'clean!'  => \$opt_clean,
+        'purge!'  => \$opt_purge,
+        'dbs!'    => \$opt_dbs,
+        'help!'   => sub { pod2usage(-verbose => 1, -exit => 0) },
+	'man!'    => sub { pod2usage(-verbose => 2, -exit => 0,
+	    noperldoc => system('perldoc -V 2>/dev/null >/dev/null')) },
+    ) or pod2usage;
 
     if ($opt_list) {
         foreach (@ARGV = getDBs(@ARGV)) {
@@ -210,4 +189,66 @@
     }
 }
 
+__END__
+
+=head1 NAME
+
+ exigrey - command line interface to exim greylist database
+
+=head1 SYNOPSIS
+
+ exigrey --insert item [delay [db]]
+ exigrey --remove item
+ exigrey --list [db]
+ exigrey --stat [db-glob ...]
+ exigrey {--clean|--purge} [days [db-glob ...]]
+ exigrey {--man|--help}
+
+=head1 DESCRIPTION
+
+B<exigrey> is the command line interface to the greylist implementation
+for Exim. It may be used to examine, cleanup and manipulate the
+greylist database.
+
+=head1 OPTIONS
+
+=over
+
+=item B<--insert> I<item> [I<delay> [I<db>]]
+
+Insert a new item into the database.
+
+=item B<--remove> I<item> [I<db>]
+
+Remove the Item I<item> from the database I<db>.
+
+=item B<--list> [I<db>]
+
+List the complete content of the database I<db>. This
+may take a while.
+
+=item B<--stat> [I<db-glob>]
+
+Print the statistics about the databases matching the I<db-glob>
+pattern.
+
+=item B<--clean>|B<--purge> [I<days> [I<db-glob>]...]
+
+Clean (unused) items or purge items unconditionally.
+
+=item B<--dbs> [I<db-glob>]
+
+List the matching database names.
+
+=back
+
+If a database name starts with F<./> or F</>, it's considered
+a file name, otherwise it's looked for in F<spool_directory/grey/>.
+
+=head1 AUTHOR
+
+Heiko Schlittermann L<<hs@schlittermann.de>>
+
+=cut
+
 # vim:ft=perl aw sts=4 sw=4:
--- a/exim.conf.ex	Wed Jun 01 00:54:05 2016 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,17 +0,0 @@
-######################################################################
-#                    MAIN CONFIGURATION SETTINGS                     #
-######################################################################
-...
-
-perl_startup = use Exim::Grey qw(unseen);
-GREYLISTED = ${perl{unseen}{<$sender_address>:<$local_part@$domain>/$sender_host_address}{60}}
-
-acl_check_rcpt:
-
-  ...
-
-  defer  
-	 condition      = GREYLISTED
-         condition      = ${if <{$message_size}{1M}}
-	 log_message    = grey listed exigrey
-