ruby-ezmlm/USAGE.md

Usage
=======

Here's a quick rundown of how to use this library.  For specifics, see
the generated RDoc.


Examples
--------


*Print the list address for all lists in a directory*:

	Ezmlm.each_list( '/lists' ) do |list|
		puts list.address
	end


*Check if I'm subscribed to a list, and if so, unsubscribe*:

(You don't really have to check first, subscribe and unsubscribe are
idempotent.)

	list = Ezmlm::List.new( '/lists/waffle-lovers' )

	if list.include?( 'mahlon@martini.nu' )
		list.unsubscribe( 'mahlon@martini.nu' )
	end

	puts "The list now has %d subscribers!" % [ list.subscribers.size ]


*Iterate over the subscriber list*:

	list.subscribers.each do |subscriber|
		# ...
	end


*Make the list moderated, and add a moderator*:

	list.moderated = true
	list.add_moderator( 'mahlon@martini.nu' )
	list.moderated? #=> true

All other list behavior tunables operate in a similar fashion, see RDoc
for details.


*Archiving!*

All of the archival pieces take advantage of Ezmlm-IDX extensions.
If you want to use these features, you'll want to enable archiving
and indexing for your lists, using the -a and -i flags to ezmlm-make.
(Enabling archiving with this library also enables indexing and thread
indexes, I assume that since you're using ezmlm-idx, you want these
enhancements!)

	list.archived? #=> false
	list.archived = true
	list.archived? #=> true

If your list(s) already had archiving enabled (the default to
ezmlm-make) but not indexing, you can manually run ezmlm-archive to
rebuild the necessary files - afterwards, they are kept up to date
automatically.


*How many messages are in the archive?*:

	list.message_count #=> 123


*Fetch message number 100 from the archive*:

	message = list.message( 100 ) or abort "No such message."

	puts message.subject
	puts message.body.to_s # Print just the body of the message.
	puts message.to_s      # Print the entire, unparsed message.

	thread = message.thread # Returns an Ezmlm::List::Thread object
	author = message.author # Returns an Ezmlm::List::Author object

As a general rule, methods called on the Ezmlm::List object return nil
if they are unable to perform the requested task.  Instantiating the
underlying objects directly raise with a specific error.  The following
are equivalent, but behave differently:

	message = list.message( 10000 ) # nonexistent message, returns nil
	message = Ezmlm::List::Message.new( list, 10000 ) # Raises a RuntimeError 

Message objects act as "Mail" objects from the excellent library from
Mikel Lindsaar (https://github.com/mikel/mail).  See its documentation
for specifics.


*Iterate over messages in a specific thread*:

Messages know what thread they belong to.  Once you have a thread object
from a message, it is an enumerable.  Iterate or sort on it using
standard Ruby methods.

	thread.each do |message|
		# ...
	end

Threads are also aware of who participated in the conversation, via the
'authors' and 'each_author' methods.


*Iterate over messages from a specific author:*

Messages know who authored them.  Once you have an author object from a
message, it is an enumerable.  Iterate or sort on it using standard Ruby
methods.

	author.each do |message|
		# ...
	end

An Author object is also aware of all threads the author participated
in, via the 'threads' and 'each_thread' methods.