1 

     2 Usage

     3 =======

     4 

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

     6 the generated RDoc.

     7 

     8 

     9 Examples

    10 --------

    11 

    12 

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

    14 

    15 	Ezmlm.each_list( '/lists' ) do |list|

    16 		puts list.address

    17 	end

    18 

    19 

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

    21 

    22 (You don't really have to check first, subscribe and unsubscribe are

    23 idempotent.)

    24 

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

    26 

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

    28 		list.unsubscribe( 'mahlon@martini.nu' )

    29 	end

    30 

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

    32 

    33 

    34 *Iterate over the subscriber list*:

    35 

    36 	list.subscribers.each do |subscriber|

    37 		# ...

    38 	end

    39 

    40 

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

    42 

    43 	list.moderated = true

    44 	list.add_moderator( 'mahlon@martini.nu' )

    45 	list.moderated? #=> true

    46 

    47 All other list behavior tunables operate in a similar fashion, see RDoc

    48 for details.

    49 

    50 

    51 *Archiving!*

    52 

    53 All of the archival pieces take advantage of Ezmlm-IDX extensions.

    54 If you want to use these features, you'll want to enable archiving

    55 and indexing for your lists, using the -a and -i flags to ezmlm-make.

    56 (Enabling archiving with this library also enables indexing and thread

    57 indexes, I assume that since you're using ezmlm-idx, you want these

    58 enhancements!)

    59 

    60 	list.archived? #=> false

    61 	list.archived = true

    62 	list.archived? #=> true

    63 

    64 If your list(s) already had archiving enabled (the default to

    65 ezmlm-make) but not indexing, you can manually run ezmlm-archive to

    66 rebuild the necessary files - afterwards, they are kept up to date

    67 automatically.

    68 

    69 

    70 *How many messages are in the archive?*:

    71 

    72 	list.message_count #=> 123

    73 

    74 

    75 *Fetch message number 100 from the archive*:

    76 

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

    78 

    79 	puts message.subject

    80 	puts message.body.to_s # Print just the body of the message.

    81 	puts message.to_s      # Print the entire, unparsed message.

    82 

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

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

    85 

    86 As a general rule, methods called on the Ezmlm::List object return nil

    87 if they are unable to perform the requested task.  Instantiating the

    88 underlying objects directly raise with a specific error.  The following

    89 are equivalent, but behave differently:

    90 

    91 	message = list.message( 10000 ) # nonexistent message, returns nil

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

    93 

    94 Message objects act as "Mail" objects from the excellent library from

    95 Mikel Lindsaar (https://github.com/mikel/mail).  See its documentation

    96 for specifics.

    97 

    98 

    99 *Iterate over messages in a specific thread*:

   100 

   101 Messages know what thread they belong to.  Once you have a thread object

   102 from a message, it is an enumerable.  Iterate or sort on it using

   103 standard Ruby methods.

   104 

   105 	thread.each do |message|

   106 		# ...

   107 	end

   108 

   109 Threads are also aware of who participated in the conversation, via the

   110 'authors' and 'each_author' methods.

   111 

   112 

   113 *Iterate over messages from a specific author:*

   114 

   115 Messages know who authored them.  Once you have an author object from a

   116 message, it is an enumerable.  Iterate or sort on it using standard Ruby

   117 methods.

   118 

   119 	author.each do |message|

   120 		# ...

   121 	end

   122 

   123 An Author object is also aware of all threads the author participated

   124 in, via the 'threads' and 'each_thread' methods.

   125 

   126