#!/usr/bin/ruby

# vim: set nosta noet ts=4 sw=4:

#

# A Ruby interface to a single Ezmlm-idx mailing list directory.

#

# == Version

#

#  $Id$

#

#---

require 'pathname'

require 'etc'

### A Ruby interface to an ezmlm-idx mailing list directory

###

class Ezmlm::List

	# Quick address space detection, to (hopefully)

	# match the overflow size on this machine.

	# Valid subdirectories/sections for subscriptions.

	SUBSCRIPTION_DIRS = %w[ deny mod digest allow ]

	### Create a new Ezmlm::List object for the specified +listdir+, which should be

	### an ezmlm-idx mailing list directory.

	###

	def initialize( listdir )

		listdir = Pathname.new( listdir ) unless listdir.is_a?( Pathname )

		@listdir = listdir

	end

	# The Pathname object for the list directory

	attr_reader :listdir

	### Return the configured name of the list (without the host)

	###

	def name

		@name = self.read( 'outlocal' ) unless @name

		return @name

	end

	### Return the configured host of the list

	###

	def host

		@host = self.read( 'outhost' ) unless @host

		return @host

	end

	### Return the configured address of the list (in list@host form)

	###

	def address

		return "%s@%s" % [ self.name, self.host ]

	end

	alias_method :fullname, :address

	### Return the email address of the list's owner.

	###

	def owner

		owner = self.read( 'owner' )

		return owner =~ /@/ ? owner : nil

	end

	### Returns +true+ if +address+ is a subscriber to this list.

	###

	def include?( addr, section: nil )

		addr.downcase!

		file = self.subscription_dir( section ) + self.hashchar( addr )

		return false unless file.exist?

		return file.read.scan( /T([^\0]+)\0/ ).flatten.include?( addr )

	end

	alias_method :is_subscriber?, :include?

	### Fetch a sorted Array of the email addresses for all of the list's

	### subscribers.

	###

	def subscribers

		return self.read_subscriber_dir

	end

	### Subscribe +addr+ to the list within +section+.

	###

	def subscribe( *addr, section: nil )

		addr.each do |address|

			next unless address.index( '@' )

			address.downcase!

			file = self.subscription_dir( section ) + self.hashchar( address )

			self.with_safety do

				if file.exist?

					addresses = file.read.scan( /T([^\0]+)\0/ ).flatten

					addresses << address

					file.open( 'w' ) do |f|

						f.print addresses.uniq.sort.map{|a| "T#{a}\0" }.join

					end

				else

					file.open( 'w' ) do |f|

						f.print "T%s\0" % [ address ]

					end

				end

			end

		end

	end

	alias_method :add_subscriber, :subscribe

	### Unsubscribe +addr+ from the list within +section+.

	###

	def unsubscribe( *addr, section: nil )

		addr.each do |address|

			address.downcase!

			file = self.subscription_dir( section ) + self.hashchar( address )

			self.with_safety do

				next unless file.exist?

				addresses = file.read.scan( /T([^\0]+)\0/ ).flatten

				addresses = addresses - [ address ]

				if addresses.empty?

					file.unlink

				else

					file.open( 'w' ) do |f|

						f.print addresses.uniq.sort.map{|a| "T#{a}\0" }.join

					end

				end

			end

		end

	end

	alias_method :remove_subscriber, :unsubscribe

	### Returns an Array of email addresses of people responsible for

	### moderating subscription of a closed list.

	###

	def moderators

		return self.read_subscriber_dir( 'mod' )

	end

	### Returns +true+ if +address+ is a moderator.

	###

	def is_moderator?( addr )

		return self.include?( addr, section: 'mod' )

	end

	### Subscribe +addr+ to the list as a Moderator.

	###

	def add_moderator( *addr )

		return self.subscribe( *addr, section: 'mod' )

	end

	### Remove +addr+ from the list as a Moderator.

	###

	def remove_moderator( *addr )

		return self.unsubscribe( *addr, section: 'mod' )

	end

	### Returns an Array of email addresses denied access

	### to the list.

	###

	def blacklisted

		return self.read_subscriber_dir( 'deny' )

	end

	### Returns +true+ if +address+ is disallowed from participating.

	###

	def is_blacklisted?( addr )

		return self.include?( addr, section: 'deny' )

	end

	### Blacklist +addr+ from the list.

	###

	def add_blacklisted( *addr )

		return self.subscribe( *addr, section: 'deny' )

	end

	### Remove +addr+ from the blacklist.

	###

	def remove_blacklisted( *addr )

		return self.unsubscribe( *addr, section: 'deny' )

	end

	### Returns an Array of email addresses that act like

	### regular subscribers for user-post only lists.

	###

	def allowed

		return self.read_subscriber_dir( 'allow' )

	end

	### Returns +true+ if +address+ is given the same benefits as a

	### regular subscriber for user-post only lists.

	###

	def is_allowed?( addr )

		return self.include?( addr, section: 'allow' )

	end

	### Add +addr+ to allow posting to user-post only lists,

	### when +addr+ isn't a subscriber.

	###

	def add_allowed( *addr )

		return self.subscribe( *addr, section: 'allow' )

	end

	### Remove +addr+ from the allowed list.

	###

	def remove_allowed( *addr )

		return self.unsubscribe( *addr, section: 'allow' )

	end

	### Returns +true+ if message threading is enabled.

	###

	def threaded?

		return ( self.listdir + 'threaded' ).exist?

	end

	### Disable or enable message threading.

	###

	### This automatically builds message indexes and thread

	### information on an incoming message.

	###

	def threaded=( enable=true )

		if enable

			self.touch( 'threaded' )

		else

			self.unlink( 'threaded' )

		end

	end

	### Returns +true+ if the list is configured to respond

	###

	def public?

		return ( self.listdir + 'public' ).exist?

	end

	### Disable or enable remote management requests.

	###

	def public=( enable=true )

		if enable

			self.touch( 'public' )

		else

			self.unlink( 'public' )

		end

	end

	### Returns +true+ if the list is not configured to respond

	###

	def private?

		return ! self.public?

	end

	### Disable or enable remote management requests.

	###

	def private=( enable=false )

		self.public = ! enable

	end

	### Returns +true+ if the list supports remote administration

	### subscribe/unsubscribe requests from moderators.

	###

	def remote_subscriptions?

		return ( self.listdir + 'remote' ).exist?

	end

	### Disable or enable remote subscription requests.

	###

	def remote_subscriptions=( enable=false )

		if enable

			self.touch( 'remote' )

		else

			self.unlink( 'remote' )

		end

	end

	### Returns +true+ if list subscription requests require moderator

	### approval.

	###

	def moderated_subscriptions?

		return ( self.listdir + 'modsub' ).exist?

	end

	### Disable or enable subscription moderation.

	###

	def moderated_subscriptions=( enable=false )

		if enable

			self.touch( 'modsub' )

		else

			self.unlink( 'modsub' )

		end

	end

	### Returns +true+ if message moderation is enabled.

	###

	def moderated?

		return ( self.listdir + 'modpost' ).exist?

	end

	### Disable or enable message moderation.

	###

	### Lists act as unmoderated for subscribers, and posts from unknown

	### addresses go to moderation.

	###

	def moderated=( enable=false )

		if enable

			self.touch( 'modpost' )

			self.touch( 'noreturnposts' ) if self.user_posts_only?

		else

			self.unlink( 'modpost' )

			self.unlink( 'noreturnposts' ) if self.user_posts_only?

		end

	end

	### Returns +true+ if posting is only allowed by moderators.

	###

	def moderator_posts_only?

		return ( self.listdir + 'modpostonly' ).exist?

	end

	### Disable or enable moderation only posts.

	###

	def moderator_posts_only=( enable=false )

		if enable

			self.touch( 'modpostonly' )

		else

			self.unlink( 'modpostonly' )

		end

	end

	### Returns +true+ if posting is only allowed by subscribers.

	###

	def user_posts_only?

		return ( self.listdir + 'subpostonly' ).exist?

	end

	### Disable or enable user only posts.

	### This is easily defeated, moderated lists are preferred.

	###

	### This has special meaning for moderated lists.  Lists act as

	### unmoderated for subscribers, and posts from unknown addresses

	### go to moderation.

	###

	def user_posts_only=( enable=false )

		if enable

			self.touch( 'subpostonly' )

			self.touch( 'noreturnposts' )if self.moderated?

		else

			self.unlink( 'subpostonly' )

			self.unlink( 'noreturnposts' ) if self.moderated?

		end

	end

	### Returns +true+ if message archival is enabled.

	###

	def archived?

		return ( self.listdir + 'archived' ).exist? || ( self.listdir + 'indexed' ).exist?

	end

	### Disable or enable message archiving (and indexing.)

	###

	def archive=( enable=true )

		if enable

			self.touch( 'archived' )

			self.touch( 'indexed' )

		else

			self.unlink( 'archived' )

			self.unlink( 'indexed' )

		end

	end

	### Returns +true+ if the message archive is accessible only to

	### moderators.

	###

	def private_archive?

		return ( self.listdir + 'modgetonly' ).exist?

	end

	### Disable or enable private access to the archive.

	###

	def private_archive=( enable=true )

		if enable

			self.touch( 'modgetonly' )

		else

			self.unlink( 'modgetonly' )

		end

	end

	### Returns +true+ if the message archive is accessible to anyone.

	###

	def public_archive?

		return ! self.private_archive?

	end

	### Returns +true+ if the message archive is accessible only to

	### list subscribers.

	###

	def guarded_archive?

		return ( self.listdir + 'subgetonly' ).exist?

	end

	### Disable or enable loimited access to the archive.

	###

	def guarded_archive=( enable=true )

		if enable

			self.touch( 'subgetonly' )

		else

			self.unlink( 'subgetonly' )

		end

	end

	### Returns +true+ if message digests are enabled.

	###

	def digested?

		return ( self.listdir + 'digested' ).exist?

	end

	### Disable or enable message digesting.

	###

	def digest=( enable=true )

		if enable

			self.touch( 'digested' )

		else

			self.unlink( 'digested' )

		end

	end

	### If the list is digestable, trigger the digest after this amount

	### of message body since the latest digest, in kbytes.

	###

	### See: ezmlm-tstdig(1)

	###

	def digest_kbytesize

		size = self.read( 'digsize' ).to_i

		return size.zero? ? 64 : size

	end

	### If the list is digestable, trigger the digest after this amount

	### of message body since the latest digest, in kbytes.

	###

	### See: ezmlm-tstdig(1)

	###

	def digest_kbytesize=( size=64 )

		self.write( 'digsize' ) {|f| f.puts size.to_i }

	end

	### If the list is digestable, trigger the digest after this many

	### messages have accumulated since the latest digest.