Debian Codegraph @

README

raw
1 grepmail - search mailboxes for a particular email
2
3 Grepmail searches a mailbox for a given regular expression, and returns those
4 emails that match it. Piped input is allowed, and date and size restrictions
5 are supported, as are searches using logical operators. Grepmail also supports
6 a variety of compression formats: gzip, bzip2, lzip, and xz.
7
8 SOME NOTES
9
10 perl version:
11
12 If you plan to use advanced pattern features such as "(?>...)", you will need
13 to make sure that your version of perl supports them.
14
15 Complex queries:
16
17 The -E flag allows you to perform complex searches involving logical
18 operators. For example,
19
20 $email_header =~ /^From: .*\@coppit.org/ && $email =~ /grepmail/i
21
22 will find all emails which originate from coppit.org (you must escape the "@"
23 sign with a backslash), and which contain the keyword "grepmail" anywhere in
24 the message, in any capitalization.
25
26 NOTE: -E support is experimental right now. I'm looking for feedback on the
27 following:
28
29 - Do you like the feature?
30 - Do you like the Perl-based syntax? Is there an alternative which is easier?
31 - How should date and size constraints be integrated? Should they be
32 "variables", a la: "$email =~ /grepmail/ && $date <= 'sep 20 1998' || $size
33 > 50000"?
34 - Should -i, -h, and -b be supported in conjunction with -E? (Where "-h
35 pattern" would mean augmenting the -E pattern with "$email_header =~
36 /pattern/ && ")
37 - -S ignores signatures. If/when this feature is implemented for -E, should it
38 be "global" for all $email_body matches, or should it be possible to specify
39 this for each $email_body match? For example, one can append an "i" modifier
40 to an individual pattern match to make it case-insensitive. Should there be
41 a standard way of dealing with such "global" pattern matching options on an
42 individual pattern match basis?
43
44 Message IDs:
45
46 NOTE: For emails without message ids, grepmail will use Digest::MD5 to
47 compute a hash based on the email header. If you don't have
48 Digest::MD5, grepmail will just use the header itself as the messsage
49 id. The Digest::MD5 checksum takes a little while to compute, but
50 saves a lot of space. Currently there is no easy way to choose space
51 over time. Let me know if this is a problem.
52
53
54 MODULE DEPENDENCIES
55
56 To use this program, you will need to install:
57
58 - Mail::Mbox::MessageParser: required
59 - Date::Parse: required
60 - Date::Manip: required if you want to search using complex date
61 specifications (-d)
62 - Digest::MD5: not required, but can help grepmail use less memory if
63 you are checking for unique emails (-u) and your emails don't have a
64 Message-Id header
65
66 To test this module, you will need to install:
67
68 - Test::More
69
70
71 INSTALLATION
72
73 => On Non-Windows (Unix/Cygwin/etc.) systems:
74
75 To install this package, change to the directory where you unarchived this
76 distribution and type the following:
77
78 perl Makefile.PL
79 make
80 make test
81 make install
82
83 You can install this package into a non-default location by appending one of
84 the following to the "perl Makefile.PL" command:
85
86 - "PREFIX=/installation/path" (for installation into a custom location),
87 - "INSTALLDIRS=site" (for installation into site-specific Perl directories)
88 - "INSTALLDIRS=perl" (for installation into standard Perl directories).
89
90 If make test fails, please see the INSTALLATION PROBLEMS section below.
91
92 => On Windows systems:
93
94 - Just copy "grepmail" to a place in your path. You may want to rename it
95 "grepmail.pl" if you've associated .pl files with perl.exe.
96
97
98 CONFIGURATION
99
100 You may want to set your MAIL environment variable so that grepmail will know
101 the default location to search for mailboxes.
102
103 If you are terribly concerned about performance, you may want to modify the
104 value of the variable READ_CHUNK_SIZE located in the code. This variable
105 controls how much text is read from the mailbox at a time. If the value is set
106 to 0, the entire file is read into memory. (There is no user-visible option
107 for setting this value.) You may also want to hack the code to not use
108 Digest::MD5, thereby trading space for time.
109
110 If you frequently use the same set of flags, you may wish to alias "grepmail"
111 to "grepmail -flags" within your command interpreter (shell). See the
112 documentation for your shell for details on how to do this.
113
114
115 INSTALLATION PROBLEMS
116
117 If "make test" fails, run
118
119 make test TEST_VERBOSE=1
120
121 and see which test(s) are failing. Please email, to the address below, the
122 output files for the test. Also email the output of running the particular
123 subtest with the -D flag. e.g.:
124
125 ./blib/script/grepmail -D --help > test_name.debug
126
127 If the first date_manip test case fails, you are in a timezone that
128 Date::Manip does not yet support. You will need to contact the author of
129 Date::Manip.
130
131 For other bugs, see the section REPORTING BUGS below.
132
133
134 DOCUMENTATION
135
136 Just "perldoc grepmail". After installation on Unix systems, you can also do
137 "man grepmail".
138
139
140 RESOURCES
141
142 The CPAN Page:
143 http://search.cpan.org/dist/grepmail/
144
145 The GitHub page:
146 https://github.com/coppit/grepmail/
147
148 Bug and feature tracking:
149 http://rt.cpan.org/Public/Dist/Display.html?Name=grepmail
150
151 When reporting a bug, please attach the output of running grepmail with the -D
152 switch. If the bug is related to processing of a particular mailbox, try to
153 trim the mailbox to the smallest set of emails that still exhibit the problem.
154 Then use the "anonymize_mailbox" program that comes with grepmail to remove
155 any sensitive information, and attach the mailbox to the bug report.
156
157
158 COPYRIGHT
159
160 Copyright (c) 1998-Sep 1 2000 Broc Seib. Copyright (c) Sep 1 2000-2015 David
161 Coppit. All rights reserved, save those granted by the license. See the file
162 LICENSE for licensing terms.
163
164
165 AUTHOR
166
167 David Coppit <[email protected]>