USAGE.md
author Mahlon E. Smith <mahlon@martini.nu>
Thu, 03 Oct 2019 11:44:44 -0700
changeset 28 99fdbf4a5f37
parent 20 9d59d30685cb
permissions -rw-r--r--
Be explicit with sticky removal, so two simultaneous processes don't create a race where sticky is left enabled.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
17
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
     1
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
     2
Usage
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
     3
=======
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
     4
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
     5
Here's a quick rundown of how to use this library.  For specifics, see
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
     6
the generated RDoc.
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
     7
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
     8
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
     9
Examples
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    10
--------
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    11
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    12
20
9d59d30685cb Fixes for documentation and test directories that didn't make it into the repo.
Mahlon E. Smith <mahlon@laika.com>
parents: 17
diff changeset
    13
### Print the list address for all lists in a directory:
17
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    14
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    15
	Ezmlm.each_list( '/lists' ) do |list|
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    16
		puts list.address
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    17
	end
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    18
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    19
20
9d59d30685cb Fixes for documentation and test directories that didn't make it into the repo.
Mahlon E. Smith <mahlon@laika.com>
parents: 17
diff changeset
    20
### Check if I'm subscribed to a list, and if so, unsubscribe:
17
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    21
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    22
(You don't really have to check first, subscribe and unsubscribe are
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    23
idempotent.)
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    24
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    25
	list = Ezmlm::List.new( '/lists/waffle-lovers' )
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    26
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    27
	if list.include?( 'mahlon@martini.nu' )
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    28
		list.unsubscribe( 'mahlon@martini.nu' )
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    29
	end
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    30
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    31
	puts "The list now has %d subscribers!" % [ list.subscribers.size ]
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    32
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    33
20
9d59d30685cb Fixes for documentation and test directories that didn't make it into the repo.
Mahlon E. Smith <mahlon@laika.com>
parents: 17
diff changeset
    34
### Iterate over the subscriber list:
17
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    35
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    36
	list.subscribers.each do |subscriber|
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    37
		# ...
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    38
	end
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    39
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    40
20
9d59d30685cb Fixes for documentation and test directories that didn't make it into the repo.
Mahlon E. Smith <mahlon@laika.com>
parents: 17
diff changeset
    41
### Make the list moderated, and add a moderator:
17
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    42
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    43
	list.moderated = true
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    44
	list.add_moderator( 'mahlon@martini.nu' )
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    45
	list.moderated? #=> true
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    46
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    47
All other list behavior tunables operate in a similar fashion, see RDoc
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    48
for details.
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    49
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    50
20
9d59d30685cb Fixes for documentation and test directories that didn't make it into the repo.
Mahlon E. Smith <mahlon@laika.com>
parents: 17
diff changeset
    51
### Archiving!
17
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    52
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    53
All of the archival pieces take advantage of Ezmlm-IDX extensions.
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    54
If you want to use these features, you'll want to enable archiving
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    55
and indexing for your lists, using the -a and -i flags to ezmlm-make.
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    56
(Enabling archiving with this library also enables indexing and thread
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    57
indexes, I assume that since you're using ezmlm-idx, you want these
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    58
enhancements!)
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    59
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    60
	list.archived? #=> false
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    61
	list.archived = true
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    62
	list.archived? #=> true
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    63
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    64
If your list(s) already had archiving enabled (the default to
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    65
ezmlm-make) but not indexing, you can manually run ezmlm-archive to
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    66
rebuild the necessary files - afterwards, they are kept up to date
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    67
automatically.
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    68
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    69
20
9d59d30685cb Fixes for documentation and test directories that didn't make it into the repo.
Mahlon E. Smith <mahlon@laika.com>
parents: 17
diff changeset
    70
### How many messages are in the archive?:
17
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    71
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    72
	list.message_count #=> 123
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    73
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    74
20
9d59d30685cb Fixes for documentation and test directories that didn't make it into the repo.
Mahlon E. Smith <mahlon@laika.com>
parents: 17
diff changeset
    75
### Fetch message number 100 from the archive:
17
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    76
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    77
	message = list.message( 100 ) or abort "No such message."
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    78
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    79
	puts message.subject
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    80
	puts message.body.to_s # Print just the body of the message.
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    81
	puts message.to_s      # Print the entire, unparsed message.
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    82
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    83
	thread = message.thread # Returns an Ezmlm::List::Thread object
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    84
	author = message.author # Returns an Ezmlm::List::Author object
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    85
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    86
As a general rule, methods called on the Ezmlm::List object return nil
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    87
if they are unable to perform the requested task.  Instantiating the
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    88
underlying objects directly raise with a specific error.  The following
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    89
are equivalent, but behave differently:
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    90
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    91
	message = list.message( 10000 ) # nonexistent message, returns nil
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    92
	message = Ezmlm::List::Message.new( list, 10000 ) # Raises a RuntimeError 
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    93
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    94
Message objects act as "Mail" objects from the excellent library from
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    95
Mikel Lindsaar (https://github.com/mikel/mail).  See its documentation
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    96
for specifics.
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    97
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
    98
20
9d59d30685cb Fixes for documentation and test directories that didn't make it into the repo.
Mahlon E. Smith <mahlon@laika.com>
parents: 17
diff changeset
    99
### Iterate over messages in a specific thread:
17
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   100
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   101
Messages know what thread they belong to.  Once you have a thread object
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   102
from a message, it is an enumerable.  Iterate or sort on it using
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   103
standard Ruby methods.
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   104
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   105
	thread.each do |message|
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   106
		# ...
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   107
	end
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   108
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   109
Threads are also aware of who participated in the conversation, via the
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   110
'authors' and 'each_author' methods.
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   111
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   112
20
9d59d30685cb Fixes for documentation and test directories that didn't make it into the repo.
Mahlon E. Smith <mahlon@laika.com>
parents: 17
diff changeset
   113
### Iterate over messages from a specific author:
17
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   114
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   115
Messages know who authored them.  Once you have an author object from a
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   116
message, it is an enumerable.  Iterate or sort on it using standard Ruby
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   117
methods.
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   118
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   119
	author.each do |message|
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   120
		# ...
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   121
	end
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   122
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   123
An Author object is also aware of all threads the author participated
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   124
in, via the 'threads' and 'each_thread' methods.
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   125
23c7f5c8ee39 Multiple changes.
Mahlon E. Smith <mahlon@laika.com>
parents:
diff changeset
   126