README.md
author Mahlon E. Smith <mahlon@laika.com>
Tue, 16 May 2017 13:58:34 -0700
changeset 17 23c7f5c8ee39
parent 16 e135ccae6783
child 27 a629597fd647
permissions -rw-r--r--
Multiple changes. - Remove the runtime dependency on rake-compiler. - Use #rb_str_new instead of #rb_str_new2, the hash character array isn't null terminated. - Add various safeguards for object instantiations. - Remove the 'threaded' options for messages, folding them into 'archived'. If archiving is enabled, so is threading. - Return nil for lookups from the list object instead of raising exceptions. - Open subject indexes with the proper encodings (thanks Michael Granger!) - Allow touching and unlinking files to operate on multiple paths at once, within a single safety() wrap.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
     1
# Ruby-Ezmlm
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
     2
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
     3
code
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
     4
: https://bitbucket.org/mahlon/Ruby-Ezmlm
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
     5
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
     6
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
     7
## Authors
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
     8
14
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
     9
* Mahlon E. Smith <mahlon@martini.nu>
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    10
* Michael Granger <ged@faeriemud.org>
15
a38e6916504c Everything is workin!
Mahlon E. Smith <mahlon@laika.com>
parents: 14
diff changeset
    11
* Jeremiah Jordan <jeremiah.m.jordan@gmail.com>
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    12
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    13
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    14
## Description
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    15
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    16
This is a ruby interface for interacting with ezmlm-idx, an email list
14
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    17
manager for use with the Qmail MTA, and the messages contained therein.
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    18
(The -idx provides an extended feature set over the original ezmlm
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    19
environment.)
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    20
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    21
http://untroubled.org/ezmlm/
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    22
14
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    23
This was tested against ezmlm-idx 7.2.2.
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    24
15
a38e6916504c Everything is workin!
Mahlon E. Smith <mahlon@laika.com>
parents: 14
diff changeset
    25
*Strong recommendation*: Create your lists with archiving (-a) and
a38e6916504c Everything is workin!
Mahlon E. Smith <mahlon@laika.com>
parents: 14
diff changeset
    26
indexing (-i)!   This library is suitable for modifying behavior of
a38e6916504c Everything is workin!
Mahlon E. Smith <mahlon@laika.com>
parents: 14
diff changeset
    27
existing lists as a default, but with these flags enabled, can also
16
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    28
be a generic interface for parsing and browsing list content.
15
a38e6916504c Everything is workin!
Mahlon E. Smith <mahlon@laika.com>
parents: 14
diff changeset
    29
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    30
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    31
## Prerequisites
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    32
14
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    33
* Ruby 2.1 or better
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    34
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    35
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    36
## Installation
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    37
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    38
    $ gem install ezmlm
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    39
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    40
14
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    41
## TODO
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    42
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    43
  - Text file editing (trailers, etc.)
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    44
  - Header / mime list accessors
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    45
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    46
13
a03c08c289e9 Multiple changes.
Mahlon E. Smith <mahlon@martini.nu>
parents: 12
diff changeset
    47
## Limitations
a03c08c289e9 Multiple changes.
Mahlon E. Smith <mahlon@martini.nu>
parents: 12
diff changeset
    48
14
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    49
This library doesn't create new lists from scratch.  Use ezmlm-make.
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    50
13
a03c08c289e9 Multiple changes.
Mahlon E. Smith <mahlon@martini.nu>
parents: 12
diff changeset
    51
This library is designed to only work with lists stored on disk (the
a03c08c289e9 Multiple changes.
Mahlon E. Smith <mahlon@martini.nu>
parents: 12
diff changeset
    52
default), not the SQL backends.
a03c08c289e9 Multiple changes.
Mahlon E. Smith <mahlon@martini.nu>
parents: 12
diff changeset
    53
a03c08c289e9 Multiple changes.
Mahlon E. Smith <mahlon@martini.nu>
parents: 12
diff changeset
    54
Address space (32 bit vs 64 bit) matters when ezmlm calculates hashes.
a03c08c289e9 Multiple changes.
Mahlon E. Smith <mahlon@martini.nu>
parents: 12
diff changeset
    55
If things aren't adding up, make sure this library is running on a
a03c08c289e9 Multiple changes.
Mahlon E. Smith <mahlon@martini.nu>
parents: 12
diff changeset
    56
machine with a matching address space as the list itself.  (Running this
a03c08c289e9 Multiple changes.
Mahlon E. Smith <mahlon@martini.nu>
parents: 12
diff changeset
    57
on a 64bit machine to talk to 32bit listserv isn't going to play well.)
a03c08c289e9 Multiple changes.
Mahlon E. Smith <mahlon@martini.nu>
parents: 12
diff changeset
    58
14
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    59
A lot of the fine tuning niceties of ezmlm come as flag options to
15
a38e6916504c Everything is workin!
Mahlon E. Smith <mahlon@laika.com>
parents: 14
diff changeset
    60
the various ezmlm binaries.  This library largely just deals with
14
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    61
ezmlm-make flags for global list behaviors.  (For example, see the man
cba9fb39bcdb Checkpoint commit.
Mahlon E. Smith <mahlon@laika.com>
parents: 13
diff changeset
    62
page for ezmlm-reject.)  Patches are welcome if you'd like these sorts
15
a38e6916504c Everything is workin!
Mahlon E. Smith <mahlon@laika.com>
parents: 14
diff changeset
    63
of miscellaneous things included.
13
a03c08c289e9 Multiple changes.
Mahlon E. Smith <mahlon@martini.nu>
parents: 12
diff changeset
    64
a03c08c289e9 Multiple changes.
Mahlon E. Smith <mahlon@martini.nu>
parents: 12
diff changeset
    65
16
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    66
## Acknowledgments
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    67
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    68
Portions of this library are copied from ezmlm-idx source, authored by
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    69
the following:
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    70
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    71
 * D. J. Bernstein <djb@cr.yp.to>
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    72
 * Bruce Guenter <bruce@untroubled.org>
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    73
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    74
Many thanks for Dan and Bruce for their commitment for fine software, and
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    75
contributions to the internet communities over the years.
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    76
e135ccae6783 Migrate hashing functions to C.
Mahlon E. Smith <mahlon@laika.com>
parents: 15
diff changeset
    77
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    78
## License
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    79
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    80
Copyright (c) 2017, Mahlon E. Smith <mahlon@martini.nu>
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    81
All rights reserved.
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    82
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    83
Redistribution and use in source and binary forms, with or without
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    84
modification, are permitted provided that the following conditions are met:
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    85
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    86
  * Redistributions of source code must retain the above copyright notice,
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    87
    this list of conditions and the following disclaimer.
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    88
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    89
  * Redistributions in binary form must reproduce the above copyright notice,
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    90
    this list of conditions and the following disclaimer in the documentation
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    91
    and/or other materials provided with the distribution.
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    92
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    93
  * Neither the name of the author/s, nor the names of the project's
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    94
    contributors may be used to endorse or promote products derived from this
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    95
    software without specific prior written permission.
1
1d3cfd4837a8 Filled out the project, added Ezmlm module + spec.
Michael Granger <mgranger@laika.com>
parents:
diff changeset
    96
12
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    97
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    98
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
    99
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
   100
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
   101
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
   102
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
   103
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
   104
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
   105
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
3cc813140c80 First round of modernizing after a long absence.
Mahlon E. Smith <mahlon@martini.nu>
parents: 1
diff changeset
   106
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.