rhizmail 0.1.0

data/lib/rhizmail.rb

@@ -0,0 +1,290 @@
+# RhizMail is a test-friendly library for sending out customized emails. This
+# is the library we use day-to-day at http://rhizome.org, where we send out
+# more than 100 customized emails a day.
+#
+# You can view the Rubyforge project page at
+# http://rubyforge.org/projects/rhizmail.
+#
+# To use RhizMail, create an email and deliver it.
+#
+#   def send_site_message( to_address, to_name, body )
+#     msg = RhizMail::Message.new(
+#       'New features at website.com', to_address, 'webmaster@mysite.com',
+#       body
+#     )
+#     msg.to_name = to_name
+#     msg.deliver
+#   end
+#
+# If you want to test this message, you can set the MockMailer to take place
+# of the default Mailer:
+#
+#   def test_send_site_message
+#     mock_mailer = RhizMail::MockMailer.new
+#     RhizMail::set_mailer mock_mailer
+#     send_site_message( 'bill@yahoo.com', 'Bill Smith', 'Hi, Bill!' )
+#     assert_equal( 1, mock_mailer.messages_sent )
+#     assert_equal( 'Bill Smith', mock_mailer.messages_sent.first.to_name )
+#   end
+#
+# RhizMail comes with a SimpleTemplateMessage class, suited for times when you 
+# want email templating that is simpler than Amrita or ERB.
+#
+# == Dependencies
+#
+# RhizMail depends on two external libraries:
+#
+# * Lafcadio: http://lafcadio.rubyforge.org
+# * MockFS: http://mockfs.rubyforge.org
+
+require 'lafcadio'
+require 'mockfs'
+require 'net/smtp'
+
+module RhizMail
+	Version = '0.1.0'
+
+	# Returns a boolean value describing whether <tt>address</tt> is a plausible 
+	# email address format.
+	def self.valid_address(address); (address =~ /\w@\w*\./) != nil; end
+
+	# InvalidStateError is raised by SimpleTemplateMessage if you try to send it
+	# out without doing all the necessary template substitutions.
+	class InvalidStateError < RuntimeError
+	end
+
+	# The Mailer is the class used to handle mail delivery. However, you usually 
+	# don't need to manipulate it directly; it's usually sufficient to call 
+	# Message#deliver.
+	class Mailer < Lafcadio::ContextualService
+		@@smtpServer = 'localhost'
+		@@smtpClass = Net::SMTP
+		@@messagesSent = []
+	
+		# Resets record of messages sent.
+		def self.reset; @@messagesSent = []; end
+	
+		def self.smtp_class=(smtpClass) # :nodoc:
+			@@smtpClass = smtpClass; 
+		end
+	
+		# Sends an email message. Will call +email+ needs to respond to
+		# +verify_sendable+; Mailer##send_email will call +verify_sendable+ before 
+		# sending the email.
+		def send_email(email)
+			email.verify_sendable
+			msg = []
+			email.headers.each { |header| msg << "#{header}\n" }
+			msg << "\n"
+			msg << email.body
+			begin
+				@@smtpClass.start( @@smtpServer ) { |smtp|
+					smtp.sendmail(msg, email.from_address, [ email.to_address ])
+				}
+				@@messagesSent << email
+			rescue Net::ProtoFatalError, TimeoutError, Errno::ECONNREFUSED,
+					Errno::ECONNRESET
+				# whatever
+			end
+		end
+	
+		# Returns an array of what messages have been sent.
+		def messages_sent; @@messagesSent; end
+	end
+
+	class Message
+		HTML_CONTENT_TYPE 			= 0
+		MULTIPART_CONTENT_TYPE 	= 1
+	
+		attr_accessor :body, :char_set, :content_type, :from_address, :from_name,
+		              :subject, :to_address, :to_name
+	
+		# Unless they are explicitly set using accessors, the following defaults 
+		# apply:
+		# [to_name] nil
+		# [from_name] nil
+		# [content_type] nil
+		# [char_set] 'iso-8859-1'
+		def initialize( subject, to_address, from_address, body = nil )
+			@subject = subject
+			@to_address = to_address
+			@from_address = from_address
+			@char_set = 'iso-8859-1'
+			@body = body
+		end
+	
+		# Sends the email.
+		def deliver; Mailer.get_mailer.send_email( self ); end
+		
+		# Returns an array of strings describing the headers for this email
+		# message.
+		def headers
+			headers = []
+			headers << "Subject: #{@subject}"
+			toHeader = "To: "
+			if @to_name
+				toHeader += " #{@to_name} <#{@to_address}>"
+			else
+				toHeader += " #{@to_address}"
+			end
+			headers << toHeader
+			fromHeader = "From: "
+			if @from_name
+				fromHeader += "#{@from_name} <#{@from_address}>"
+			else
+				fromHeader += "#{@from_address}"
+			end
+			headers << fromHeader
+			if content_type == HTML_CONTENT_TYPE
+				headers << "Content-Type: text/html; charset=\"#{@char_set}\""
+				headers << "MIME-Version: 1.0"
+			elsif content_type == MULTIPART_CONTENT_TYPE
+				headers << "Content-Type: Multipart/Alternative; charset=\"#{@char_set}\""
+				headers << "MIME-Version: 1.0"
+			end
+			headers
+		end
+	
+		# Mailer calls this before sending a message; subclasses can override this
+		# if they want to ensure that certain parts of the message are valid before 
+		# sending.
+		def verify_sendable
+			[ :subject, :from_address, :to_address, :body ].each { |field|
+				if self.send( field ).nil?
+					raise( InvalidStateError,
+								 "Can't send email with blank #{ field.id2name }" )
+				end
+			}
+		end
+	end
+
+	# The MockMailer can be swapped out for the Mailer in test code, and then
+	# queried to make sure that the right emails were sent out. To set this, call
+	#
+	#   mock_mailer = RhizMail::MockMailer.new
+	#   RhizMail::set_mailer mock_mailer
+	#
+	# Afterwards, every time you call Message#deliver it will be delivered by the 
+	# MockMailer.
+	class MockMailer
+		attr_reader :messages_sent
+	
+		def initialize; flush; end
+		
+		# Clear out the history of messages sent.
+		def flush; @messages_sent = []; end
+		
+		# Pretends to send an email, recording it in +messages_sent+ to allow
+		# inspection later.
+		def send_email(email)
+			email.verify_sendable
+			@messages_sent << email
+		end
+	end
+	
+	# The SimpleTemplateMessage is designed to let a programmer define a simple
+	# set of tags for a certain sort of message and then substitute them in-code. 
+	# It's intended to be simple enough that non-programmers can edit it without
+	# too much confusion.
+	#
+	# As an example, let's say you've got an email to send out whenever somebody
+	# signs up to your website. The template could look like this:
+	#
+	#   $ cat /Users/francis/Desktop/template.txt 
+	#   Subject: Thanks for joining Website.com!
+	#   
+	#   Hi! Thanks for joining Website.com. For your reference, here's your signup
+	#   information:
+	#
+	#   Email: <% email %>
+	#   Password: <% password %>
+	#
+	#   Thanks!
+	#
+	# Note that the first line needs to be in the format "Subject: [ SUBJECT ]", 
+	# and should be followed by a blank line.
+	#
+	# Then you create an instance of SimpleTemplateMessage and use 
+	# SimpleTemplateMessage#substitute to change the contents:
+	#
+	#   irb> msg = RhizMail::SimpleTemplateMessage.new(
+	#     'john.doe@email.com', 'webmaster@website.com',
+	#     '/Users/francis/Desktop/template.txt'
+	#   )
+	#   irb> msg.substitute( 'email', 'john.doe@email.com' )
+	#   irb> msg.substitute( 'password', 'p4ssw0rd' )
+	#   irb> puts msg.body
+	#   Hi! Thanks for joining Website.com. For your reference, here's your signup
+	#   information:
+	#
+	#   Email: john.doe@email.com
+	#   Password: p4ssw0rd
+	#
+	#   Thanks!
+	#   irb> msg.deliver
+	#
+	# If you call SimpleTemplateMessage#deliver without doing all the
+	# substitutions required by the template, it will raise an InvalidStateError. 
+	# (Getting an exception is probably better than sending a customer an email
+	# with funny symbols in it.)
+	class SimpleTemplateMessage < Message
+		def initialize( to_address, from_address, template_file )
+			template = ''
+			MockFS.file.open( template_file ) { |file| template = file.gets nil }
+			template =~ /Subject: (.*)/
+			subject = $1
+			super( subject, to_address, from_address )
+			@body = generate_body template
+		end
+	
+		def body_template( template ) # :nodoc:
+			body = ''
+			blank_line_found = false
+			template.each { |line|
+				if blank_line_found
+					body += line
+				else
+					blank_line_found = true if line =~ /^\n/
+				end
+			}
+			body
+		end
+		
+		def generate_body( template ) # :nodoc:
+			body = body_template( template )
+			tokens = body.scan(/<%\s*(\S*)\s*%>/).collect { |matchArray|
+				matchArray[0]
+			}
+			tokens.each { |token|
+				if ( proc = substitutions[token] ); substitute( token, proc ); end
+			}
+			body
+		end
+	
+		def substitute(token, value_or_proc )
+			regexp = Regexp.new( "<%\s*#{ token }\s*%>", true )
+			@body.gsub!( regexp ){ |match|
+				value_or_proc.class <= Proc ? value_or_proc.call : value_or_proc
+			}
+		end
+	
+		# If you want to define a subclass of SimpleTemplateMessage, you can 
+		# override +substitutions+ to automatically define a set of substitutions
+		# to make when you create a new instance. +substitutions+ should always 
+		# return a hash of tokens to either values or Procs.
+		def substitutions; {}; end
+		
+		def verify_sendable
+			super
+			if @body =~ /<%/ || @body =~ /%>/
+				raise InvalidStateError, "substitution failed: #{ @body }", caller
+			elsif @subject =~/<%/ || @subject =~ /%>/
+				raise( InvalidStateError,
+							 "substitution failed with subject: #{ @subject }",
+							 caller )
+			elsif @body == ''
+				raise( InvalidStateError, "can't send email with blank body", caller )
+			end
+		end
+	end
+end

data/lib/rhizmail.rb~

@@ -0,0 +1,260 @@
+# RhizMail is a test-friendly library for sending out customized emails. This
+# is the library we use day-to-day at Rhizome.org, where we send out more than
+# 100 customized emails a day.
+#
+# You can view the Rubyforge project page at
+# http://rubyforge.org/projects/rhizmail.
+#
+# To use RhizMail, create an email and deliver it.
+#
+#   def send_site_message( to_address, to_name, body )
+#     msg = RhizMail::Message.new(
+#       'New features at website.com', to_address, 'webmaster@mysite.com',
+#       body
+#     )
+#     msg.to_name = to_name
+#     msg.deliver
+#   end
+#
+# If you want to test this message, you can set the MockMailer to take place
+# of the default Mailer:
+#
+#   def test_send_site_message
+#     mock_mailer = RhizMail::MockMailer.new
+#     RhizMail::set_mailer mock_mailer
+#     send_site_message( 'bill@yahoo.com', 'Bill Smith', 'Hi, Bill1' )
+#     assert_equal( 1, mock_mailer.messages_sent )
+#     assert_equal( 'Bill Smith', mock_mailer.messages_sent.first.to_name )
+#   end
+
+require 'lafcadio'
+require 'mockfs'
+require 'net/smtp'
+
+module RhizMail
+	Version = '0.1.0'
+
+	# Returns a boolean value describing whether <tt>address</tt> is a plausible 
+	# email address format.
+	def self.valid_address(address); (address =~ /\w@\w*\./) != nil; end
+
+	# InvalidStateError is raised by SimpleTemplateMessage if you try to send it
+	# out without doing all the necessary template substitutions.
+	class InvalidStateError < RuntimeError
+	end
+
+	# The Mailer is the class used to handle mail delivery. However, you usually 
+	# don't need to manipulate it directly; it's usually sufficient to call 
+	# Message#deliver.
+	class Mailer < Lafcadio::ContextualService
+		@@smtpServer = 'localhost'
+		@@smtpClass = Net::SMTP
+		@@messagesSent = []
+	
+		# Resets record of messages sent.
+		def self.reset; @@messagesSent = []; end
+	
+		def self.set_smtp_class(smtpClass) # :nodoc:
+			@@smtpClass = smtpClass; 
+		end
+	
+		# Sends an email message.
+		def send_email(email)
+			email.verify_sendable
+			msg = []
+			email.headers.each { |header| msg << "#{header}\n" }
+			msg << "\n"
+			msg << email.body
+			begin
+				@@smtpClass.start( @@smtpServer ) { |smtp|
+					smtp.sendmail(msg, email.from_address, [ email.to_address ])
+				}
+				@@messagesSent << email
+			rescue Net::ProtoFatalError, TimeoutError, Errno::ECONNREFUSED,
+					Errno::ECONNRESET
+				# whatever
+			end
+		end
+	
+		# Returns an array of what messages have been sent.
+		def messages_sent; @@messagesSent; end
+	end
+
+	class Message
+		HTML_CONTENT_TYPE 			= 0
+		MULTIPART_CONTENT_TYPE 	= 1
+	
+		attr_accessor :body, :char_set, :content_type, :from_address, :from_name,
+		              :subject, :to_address, :to_name
+	
+		# Unless they are explicitly set using accessors, the following defaults 
+		# apply:
+		# [to_name] nil
+		# [from_name] nil
+		# [content_type] nil
+		# [char_set] 'iso-8859-1'
+		def initialize( subject, to_address, from_address, body = nil )
+			@subject = subject
+			@to_address = to_address
+			@from_address = from_address
+			@char_set = 'iso-8859-1'
+			@body = body
+		end
+	
+		# Sends the email.
+		def deliver; Mailer.get_mailer.send_email( self ); end
+		
+		# Returns an array of strings describing the headers for this email
+		# message.
+		def headers
+			headers = []
+			headers << "Subject: #{@subject}"
+			toHeader = "To: "
+			if @to_name
+				toHeader += " #{@to_name} <#{@to_address}>"
+			else
+				toHeader += " #{@to_address}"
+			end
+			headers << toHeader
+			fromHeader = "From: "
+			if @from_name
+				fromHeader += "#{@from_name} <#{@from_address}>"
+			else
+				fromHeader += "#{@from_address}"
+			end
+			headers << fromHeader
+			if content_type == HTML_CONTENT_TYPE
+				headers << "Content-Type: text/html; charset=\"#{@char_set}\""
+				headers << "MIME-Version: 1.0"
+			elsif content_type == MULTIPART_CONTENT_TYPE
+				headers << "Content-Type: Multipart/Alternative; charset=\"#{@char_set}\""
+				headers << "MIME-Version: 1.0"
+			end
+			headers
+		end
+	
+		# Emailer calls this before sending a message; subclasses can override this
+		# if they want to ensure that certain parts of the message are valid before 
+		# sending.
+		def verify_sendable
+			[ :subject, :from_address, :to_address, :body ].each { |field|
+				if self.send( field ).nil?
+					raise( InvalidStateError,
+								 "Can't send email with blank #{ field.id2name }" )
+				end
+			}
+		end
+	end
+
+	# The MockMailer can be swapped out for the Mailer in test code, and then
+	# queried to make sure that the right emails were sent out. To set this, call
+	#
+	#   mock_mailer = RhizMail::MockMailer.new
+	#   RhizMail::set_mailer mock_mailer
+	#
+	# Afterwards, every time you call Message#deliver it will be delivered by the 
+	# MockMailer.
+	class MockMailer
+		attr_reader :messages_sent
+	
+		def initialize; flush; end
+		
+		# Clear out the history of messages sent.
+		def flush; @messages_sent = []; end
+		
+		# Pretends to send an email.
+		def send_email(email)
+			email.verify_sendable
+			@messages_sent << email
+		end
+	end
+	
+	# The SimpleTemplateMessage is designed to let a programmer define a simple
+	# set of tags for a certain sort of message and then substitute them in-code. 
+	# It's intended to be simple enough that non-programmers can edit it without
+	# too much confusion.
+	#
+	# As an example, let's say you've got an email to send out whenever somebody
+	# signs up to your website. The template could look like this:
+	#
+	#   $ cat ~/Desktop/template.txt 
+	#   Subject: Thanks for joining Website.com!
+	#   
+	#   Hi! Thanks for joining Website.com. For your reference, here's your signup
+	#   information:
+	#
+	#   Email: <% email %>
+	#   Password: <% password %>
+	#
+	#   Thanks!
+	#
+	# Note that the first line needs to be in the format "Subject: [ SUBJECT ]", 
+	# and should be followed by a blank line.
+	#
+	# Then you create an instance of SimpleTemplateMessage and use 
+	# SimpleTemplateMessage#substitute to change the :
+	#
+	#   
+	
+	pointing to that file
+	class SimpleTemplateMessage < Message
+		def initialize( to_address, from_address, template_file )
+			template = ''
+			MockFS.get_file.open( template_file ) { |file|
+				template = file.gets nil
+			}
+			template =~ /Subject: (.*)/
+			subject = $1
+			super( subject, to_address, from_address )
+			set_body( template )
+		end
+	
+		def get_body( template )
+			body = ''
+			blank_line_found = false
+			template.each { |line|
+				if blank_line_found
+					body += line
+				else
+					blank_line_found = true if line =~ /^\n/
+				end
+			}
+			body
+		end
+		
+		def get_regexp( token ); Regexp.new(  "<%\s*#{ token }\s*%>", true ); end
+	
+		def get_substitions; {}; end
+		
+		def set_body( template )
+			@body = get_body( template )
+			tokens = @body.scan(/<%\s*(\S*)\s*%>/).collect { |matchArray|
+				matchArray[0]
+			}
+			substitutions = get_substitions
+			tokens.each { |token|
+				if ( proc = substitutions[token] ); substitute( token, proc ); end
+			}
+		end
+	
+		def substitute(token, value_or_proc )
+			regexp = get_regexp( token )
+			@body.gsub!( regexp ){ |match|
+				value_or_proc.class <= Proc ? value_or_proc.call : value_or_proc
+			}
+		end
+	
+		def verify_sendable
+			super
+			if @body =~ /<%/ || @body =~ /%>/
+				raise InvalidStateError, "substitution failed: #{ @body }", caller
+			elsif @subject =~/<%/ || @subject =~ /%>/
+				raise( InvalidStateError,
+							 "substitution failed with subject: #{ @subject }",
+							 caller )
+			elsif @body == ''
+				raise( InvalidStateError, "can't send email with blank body", caller )
+			end
+		end
+	end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.6
+specification_version: 1
+name: rhizmail
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2005-03-19
+summary: RhizMail is a test-friendly library for sending out customized emails.
+require_paths: 
+  - lib
+email: sera@fhwang.net
+homepage: http://rhizmail.rubyforge.org/
+rubyforge_project: 
+description: "RhizMail is a test-friendly library for sending out customized emails. This is
+  the library we use day-to-day at http://rhizome.org, where we send out more than
+  100 customized emails a day"
+autorequire: rhizmail
+default_executable: 
+bindir: bin
+has_rdoc: false
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+authors: 
+  - Francis Hwang
+files: 
+  - lib/rhizmail.rb
+  - lib/rhizmail.rb~
+test_files: []
+rdoc_options: []
+extra_rdoc_files: []
+executables: []
+extensions: []
+requirements: []
+dependencies: 
+  - !ruby/object:Gem::Dependency 
+    name: lafcadio
+    version_requirement: 
+    version_requirements: !ruby/object:Gem::Version::Requirement 
+      requirements: 
+        - 
+          - ">"
+          - !ruby/object:Gem::Version 
+            version: 0.0.0
+      version: 
+  - !ruby/object:Gem::Dependency 
+    name: mockfs
+    version_requirement: 
+    version_requirements: !ruby/object:Gem::Version::Requirement 
+      requirements: 
+        - 
+          - ">"
+          - !ruby/object:Gem::Version 
+            version: 0.0.0
+      version: